Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

14/WAKU2-MESSAGE: Move to Stable #20

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

14/WAKU2-MESSAGE: Move to Stable #20

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
213 changes: 124 additions & 89 deletions waku/standards/core/14/message.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,73 +5,87 @@ name: Waku v2 Message
status: draft
category: Standards Track
tags: waku/core-protocol
editor: Oskar Thorén <[email protected]>
editor: Hanno Cornelius <[email protected]>
contributors:
- Sanaz Taheri <[email protected]>
- Aaryamann Challani <[email protected]>
- Lorenzo Delgado <[email protected]>
- Abhimanyu Rawat <[email protected]>
- Oskar Thorén <[email protected]>
---

## Abstract

Waku v2 is a family of modular peer-to-peer protocols for secure communication.
These protocols are designed to be secure, privacy-preserving, and censorship-resistant and can run in resource-restricted environments.
At a high level, Waku v2 implements a Pub/Sub messaging pattern over libp2p and adds capabilities.

The present document specifies the Waku v2 message format, a way to encapsulate the messages sent with specific information security goals, and Whisper/Waku v1 backward compatibility.
[10/WAKU2](/spec/10) is a family of modular peer-to-peer protocols for secure communication.
These protocols are designed to be secure, privacy-preserving,
censorship-resistant and run in resource-restricted environments.
At a high level, it implements a publish/subscribe, PubSub,
messaging mechanism over [libp2p](https://github.com/libp2p/specs) and adds capabilities.

This specification describes the [10/WAKU2](/spec/10) messaging format.
A way to encapsulate the messages sent with specific information security goals, and
[6/WAKU1](/spec/6/) backward compatibility.

## Motivation

When sending messages over Waku, there are multiple requirements:
When sending messages over [10/WAKU2](/spec/10), there are multiple requirements:

- One may have a separate encryption layer as part of the application.
- One may want to provide efficient routing for resource-restricted devices.
- One may want to provide compatibility with [Waku v1 envelopes](../6/waku1.md).
- One may want to provide compatibility with [Waku v1 envelopes](/spec/6/).
- One may want encrypted payloads by default.
- One may want to provide unlinkability to get metadata protection.

This specification attempts to provide for these various requirements.


## Semantics
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”,
and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).

### Waku Message

A Waku message is constituted by the combination of data payload and attributes that, for example, a *publisher* sends to a *topic* and is eventually delivered to *subscribers*.
A `WakuMessage` is constituted by the combination of the data payload and attributes that, for example,
a *publisher* sends to a `pubsubTopic` and is eventually delivered to *subscribers*.

Waku message attributes are key-value pairs of metadata associated with a message.
And the message data payload is the part of the transmitted Waku message that is the actual message information.
The data payload is also treated as a Waku message attribute for convenience.
The `WakuMessage` attributes are key-value pairs of metadata associated with a message.
The message data payload is part of the transmitted `WakuMessage` that is the actual message information.
The data payload is also treated as a `WakuMessage` attribute for convenience.

### Message Attributes

* The `payload` attribute MUST contain the message data payload to be sent.

* The `content_topic` attribute MUST specify a string identifier that can be used for content-based filtering,
as described in [23/WAKU2-TOPICS](../../../informational/23/topics.md).
* The `contentTopic` attribute MUST specify a string identifier that can be used for content-based filtering,
as desribed in [23/WAKU2-TOPICS](/spec/23/).

* The `meta` attribute, if present, contains an arbitrary application-specific variable-length byte array with a maximum length limit of 64 bytes.
This attribute can be utilized to convey supplementary details to various Waku protocols, thereby enabling customized processing based on its contents.
* The `meta` attribute, if present,
SHOULD contain an arbitrary application-specific variable-length byte array with a maximum length limit of 64 bytes.
This attribute can be utilized to convey supplementary details to various Waku protocols, thereby
enabling customized processing based on its contents.

* The `version` attribute, if present, contains a version number to discriminate different types of payload encryption.
* The `version` attribute, if present,
SHOULD contain a version number to discriminate different types of `payload` encryption.
If omitted, the value SHOULD be interpreted as version 0.

* The `timestamp` attribute, if present, signifies the time at which the message was generated by its sender.
* The `timestamp` attribute, if present,
SHOULD signify the time at which the message was generated by its sender.
This attribute MAY contain the Unix epoch time in nanoseconds.
If the attribute is omitted, it SHOULD be interpreted as timestamp 0.

* The `ephemeral` attribute, if present, signifies the transient nature of the message.
For example, an ephemeral message SHOULD not be persisted by the Waku network.
If this attribute is set to `true`, the message SHOULD be interpreted as ephemeral.
If, instead, the attribute is omitted or set to `false`, the message SHOULD be interpreted as non-ephemeral.
* The `ephemeral` attribute, if present,
signifies the transient nature of the message.
For example, an ephemeral message SHOULD not be persisted by any [10/WAKU2](/spec/10) nodes.
If this attribute is set to `true`,
the message SHOULD be interpreted as ephemeral.
If the attribute is omitted or set to `false`,
the message SHOULD be interpreted as non-ephemeral.

## Wire Format
### Wire Format

The Waku message wire format is specified using [protocol buffers v3](https://developers.google.com/protocol-buffers/).
The `WakuMessage` wire format is specified using [protocol buffers v3](https://developers.google.com/protocol-buffers/).

```protobuf

syntax = "proto3";

message WakuMessage {
Expand All @@ -82,126 +96,143 @@ message WakuMessage {
optional bytes meta = 11;
optional bool ephemeral = 31;
}
```

An example proto file following this specification can be found [here (vacp2p/waku)](https://github.com/vacp2p/waku/blob/main/waku/message/v1/message.proto).

```

## Payload encryption
### Payload Encryption

The Waku message payload MAY be encrypted.
The `WakuMessage` payload MAY be encrypted.
The message `version` attribute indicates the schema used to encrypt the payload data.

- **Version 0:**
The payload SHOULD be interpreted as unencrypted; additionally, it CAN indicate that the message payload has been encrypted at the application layer.
The `payload` SHOULD be interpreted as unencrypted; additionally,
it MAY indicate that the message payload has been encrypted at the application layer.

- **Version 1:**
The payload SHOULD be encrypted using Waku v1 payload encryption specified in [26/WAKU-PAYLOAD](../../application/26/payload.md).
The `payload` SHOULD be encrypted using [6/WAKU1](/spec/6/) payload encryption,
as specified in [26/WAKU-PAYLOAD](/spec/26).
This provides asymmetric and symmetric encryption.
The key agreement is performed out of band.
And provides an encrypted signature and padding for some form of unlinkability.

- **Version 2:**
The payload SHOULD be encoded according to [35/WAKU2-NOISE]([/spec/35](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/noise.md)).
Waku Noise protocol provides symmetric encryption and asymmetric key exchange.

Any `version` value not included in this list is reserved for future specification.
And, in this case, the payload SHOULD be interpreted as unencrypted by the Waku layer.
The `payload` SHOULD be encoded according to the [35/WAKU2-NOISE](/spec/35) protocol,
which provides symmetric encryption and asymmetric key exchange.

Any `version` value not included in this list is reserved for a future specification.
And, in this case, the `payload` SHOULD be interpreted as unencrypted by the Waku layer.

## Whisper/Waku v1 envelope compatibility
### Whisper/Waku v1 Envelope Compatibility

Whisper/Waku v1 envelopes are compatible with Waku v2 messages format.
Whisper/[6/WAKU1](/spec/6/) envelopes are compatible with [10/WAKU2](/spec/10) messages format.

* Whisper/Waku v1 `topic` field SHOULD be mapped to Waku v2 message's `content_topic` attribute.
* Whisper/Waku v1 `data` field SHOULD be mapped to Waku v2 message's `payload` attribute.
* Whisper/[6/WAKU1](/spec/6/) `topic` field SHOULD be mapped to [10/WAKU2](/spec/10) message's `content_topic` attribute.
* Whisper/[6/WAKU1](/spec/6/) `data` field SHOULD be mapped to [10/WAKU2](/spec/10) message's `payload` attribute.

Waku v2 implements a pub/sub messaging pattern over libp2p.
This makes redundant some Whisper/Waku v1 envelope fields (e.g., `expiry`, `ttl`, `topic`, etc.), so they can be ignored.
[10/WAKU2](/spec/10) implements a pub/sub messaging pattern over libp2p.
This makes redundant some Whisper/[6/WAKU1](/spec/6/) envelope fields (e.g., `expiry`, `ttl`, `topic`, etc.), so
they can be ignored.

## Deterministic message hashing
### Deterministic Message Hashing

In Protocol Buffers v3, the deterministic serialization is not canonical across the different implementations and languages.
In Protocol Buffers v3,
the deterministic serialization is not canonical across the different implementations and languages.
It is also unstable across different builds with schema changes due to unknown fields.

To overcome this interoperability limitation, a Waku v2 message's hash MUST be computed following this schema:
To overcome this interoperability limitation,
a `WakuMessage` hash MUST be computed following this schema:

```
message_hash = sha256(concat(pubsub_topic, message.payload, message.content_topic, message.meta, message.timestamp))
messageHash = sha256(concat(pubsub_topic, WakuMessage.payload, WakuMessage.content_topic, WakuMessage.meta, WakuMessage.timestamp));

```

If an optional attribute, such as `meta`, is absent, the concatenation of attributes SHOULD exclude it. This recommendation is made to ensure that the concatenation process proceeds smoothly when certain attributes are missing and to maintain backward compatibility.
If an optional attribute, such as `meta`, is absent,
the concatenation of attributes SHOULD exclude it.
This is RECOMMENDED to ensure that the concatenation process proceeds smoothly when certain attributes are missing and
to maintain backward compatibility.

This hashing schema is deemed appropriate for use cases where a cross-implementation deterministic hash is needed, such as message deduplication and integrity validation. The collision probability offered by this hashing schema can be considered negligible. This is due to the deterministic concatenation order of the message attributes, coupled with using a SHA-2 (256-bit) hashing algorithm.
This hashing schema is deemed appropriate for use cases where a cross-implementation deterministic hash is needed,
such as message deduplication and integrity validation.
The collision probability offered by this hashing schema can be considered negligible.
This is due to the deterministic concatenation order of the message attributes,
coupled with using a SHA-2 (256-bit) hashing algorithm.

### Test vectors
### Test Vectors

Waku message hash computation (`meta` size of 12 bytes):
`WakuMessage` hash computation (`meta` size of 12 bytes):
```
pubsub_topic = "/waku/2/default-waku/proto" (0x2f77616b752f322f64656661756c742d77616b752f70726f746f)
message.payload = 0x010203045445535405060708
message.content_topic = "/waku/2/default-content/proto" (0x2f77616b752f322f64656661756c742d636f6e74656e742f70726f746f)
message.meta = 0x73757065722d736563726574
message.timestamp = 0x175789bfa23f8400
WakuMessage.payload = 0x010203045445535405060708
WakuMessage.content_topic = "/waku/2/default-content/proto" (0x2f77616b752f322f64656661756c742d636f6e74656e742f70726f746f)
WakuMessage.meta = 0x73757065722d736563726574
WakuMessage.timestamp = 0x175789bfa23f8400

message_hash = 0x64cce733fed134e83da02b02c6f689814872b1a0ac97ea56b76095c3c72bfe05
messageHash = 0x64cce733fed134e83da02b02c6f689814872b1a0ac97ea56b76095c3c72bfe05
```

Waku message hash computation (`meta` size of 64 bytes):

`WakuMessage` hash computation (`meta` size of 64 bytes):
```
pubsub_topic = "/waku/2/default-waku/proto" (0x2f77616b752f322f64656661756c742d77616b752f70726f746f)
message.payload = 0x010203045445535405060708
message.content_topic = "/waku/2/default-content/proto" (0x2f77616b752f322f64656661756c742d636f6e74656e742f70726f746f)
message.meta = 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f
message.timestamp = 0x175789bfa23f8400
WakuMessage.payload = 0x010203045445535405060708
WakuMessage.content_topic = "/waku/2/default-content/proto" (0x2f77616b752f322f64656661756c742d636f6e74656e742f70726f746f)
WakuMessage.meta = 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f
WakuMessage.timestamp = 0x175789bfa23f8400

message_hash = 0x7158b6498753313368b9af8f6e0a0a05104f68f972981da42a43bc53fb0c1b27
messageHash = 0x7158b6498753313368b9af8f6e0a0a05104f68f972981da42a43bc53fb0c1b27
```

Waku message hash computation (`meta` attribute not present):
`WakuMessage` hash computation (`meta` attribute not present):
```
pubsub_topic = "/waku/2/default-waku/proto" (0x2f77616b752f322f64656661756c742d77616b752f70726f746f)
message.payload = 0x010203045445535405060708
message.content_topic = "/waku/2/default-content/proto" (0x2f77616b752f322f64656661756c742d636f6e74656e742f70726f746f)
message.meta = <not-present>
message.timestamp = 0x175789bfa23f8400
WakuMessage.payload = 0x010203045445535405060708
WakuMessage.content_topic = "/waku/2/default-content/proto" (0x2f77616b752f322f64656661756c742d636f6e74656e742f70726f746f)
WakuMessage.meta = <not-present>
WakuMessage.timestamp = 0x175789bfa23f8400

message_hash = 0xa2554498b31f5bcdfcbf7fa58ad1c2d45f0254f3f8110a85588ec3cf10720fd8
messageHash = 0xa2554498b31f5bcdfcbf7fa58ad1c2d45f0254f3f8110a85588ec3cf10720fd8
```

Waku message hash computation (`payload` length 0):
`WakuMessage` hash computation (`payload` length 0):
```
pubsub_topic = "/waku/2/default-waku/proto" (0x2f77616b752f322f64656661756c742d77616b752f70726f746f)
message.payload = []
message.content_topic = "/waku/2/default-content/proto" (0x2f77616b752f322f64656661756c742d636f6e74656e742f70726f746f)
message.meta = 0x73757065722d736563726574
message.timestamp = 0x175789bfa23f8400
WakuMessage.payload = []
WakuMessage.content_topic = "/waku/2/default-content/proto" (0x2f77616b752f322f64656661756c742d636f6e74656e742f70726f746f)
WakuMessage.meta = 0x73757065722d736563726574
WakuMessage.timestamp = 0x175789bfa23f8400

message_hash = 0x483ea950cb63f9b9d6926b262bb36194d3f40a0463ce8446228350bd44e96de4
messageHash = 0x483ea950cb63f9b9d6926b262bb36194d3f40a0463ce8446228350bd44e96de4
```

## Security Considerations

### Confidentiality, integrity, and authenticity
### Confidentiality, Integrity, and Authenticity

The level of confidentiality, integrity, and authenticity of the Waku message payload is discretionary.
Accordingly, the application layer shall utilize the encryption and signature schemes supported by Waku v2 to meet the application-specific privacy needs.
The level of confidentiality, integrity, and
authenticity of the `WakuMessage` data payload is discretionary.
Accordingly, the application layer shall utilize the encryption and
signature schemes supported by [10/WAKU2](/spec/10) to meet the application-specific privacy needs.

### Reliability of the `timestamp` attribute

The Waku message `timestamp` attribute is set by the sender.
Therefore, because message timestamps aren’t independently verified, this attribute is prone to exploitation and misuse.
The `timestamp` attribute is set by the sender.
Therefore, because message timestamps aren’t independently verified,
this attribute is prone to exploitation and misuse.
It should not solely be relied upon for operations such as message ordering.
For example, a malicious actor can arbitrarily set the `timestamp` of a Waku message to a high value so that it always shows up as the most recent message in a chat application.
Applications using Waku messages’ `timestamp` attribute are recommended to use additional methods for more robust message ordering.
An example of how to deal with message ordering against adversarial message timestamps can be found in the Status protocol, see [6/PAYLOADS](../6/waku1.md/#clock-vs-timestamp-and-message-ordering).
For example, a malicious actor can arbitrarily set the `timestamp` of a `WakuMessage` to a high value, so
that it always shows up as the most recent message in a chat application.
Applications using the `timestamp` attribute are RECOMMENDED
to use additional methods for more robust message ordering.
An example of how to deal with message ordering against adversarial message timestamps can be found in the Status protocol,
see [62/STATUS-PAYLOADS](/spec/62).

### Reliability of the `ephemeral` attribute

The Waku message `ephemeral` attribute is set by the sender.
Since there is currently no incentive mechanism for network participants to behave correctly, this attribute is inherently insecure.
A malicious actor can tamper with the value of a Waku message’s `ephemeral` attribute, and the receiver would not be able to verify the integrity of the message.
The `ephemeral` attribute is set by the sender.
Since there is currently no incentive mechanism for network participants to behave correctly,
this attribute is inherently insecure.
A malicious actor can tamper with the value of the `ephemeral` attribute, and
the receiver would not be able to verify the integrity of the message.

## Copyright

Expand All @@ -210,8 +241,12 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public

## References

- [10/WAKU2](/spec/10)
- [6/WAKU1](/spec/6/)
- [23/WAKU2-TOPICS](/spec/23/)
- [64/WAKU2-NETWORK](/spec/64)
- [Google Protocol buffers v3](https://developers.google.com/protocol-buffers/)
- [26/WAKU-PAYLOAD](../../application/26/payload.md)
- [35/WAKU2-NOISE]([/spec/35](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/noise.md))
- [6/PAYLOADS](https://specs.status.im/spec/6#clock-vs-timestamp-and-message-ordering)
- [11/WAKU2-RELAY](/spec/11/)
- [26/WAKU-PAYLOAD](/spec/26)
- [35/WAKU2-NOISE](/spec/35)
- [62/STATUS-PAYLOADS](/spec/62)