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 #120

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

14/WAKU2-MESSAGE: Move to Stable #120

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8693a31
Update message.md
jimstir Dec 26, 2024
167ef50
Update message.md
jimstir Jan 2, 2025
15773b9
Update message.md
jimstir Jan 2, 2025
96eba2b
Update waku/standards/core/14/message.md
jimstir Jan 30, 2025
f39d5d6
Update message.md
jimstir Jan 30, 2025
010d422
Update message.md
jimstir Feb 27, 2025
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
99 changes: 57 additions & 42 deletions waku/standards/core/14/message.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
slug: 14
title: 14/WAKU2-MESSAGE
name: Waku v2 Message
status: draft
status: stable
category: Standards Track
tags: waku/core-protocol
editor: Hanno Cornelius <[email protected]>
Expand All @@ -16,54 +16,60 @@ contributors:

## Abstract

Waku v2 is a family of modular peer-to-peer protocols for secure communication.
[10/WAKU2](/waku/standards/core/10/waku2.md) 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
At a high level,
[10/WAKU2](/waku/standards/core/10/waku2.md) implements a publish/subscribe messaging pattern over libp2p and
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not entirely sure, but should other RFCs referenced in a stable RFC also be stable?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not a rule define in 1/COSS. Currently, once an RFC becomes stable only the links can be updated afterwards. So if an RFC, referenced in a stable RFC, becomes deprecated it can not be removed.

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.
The present document specifies the [10/WAKU2](/waku/standards/core/10/waku2.md) message format.
A way to encapsulate the messages sent with specific information security goals,
and Whisper/[6/WAKU1](/waku/standards/legacy/6/waku1.md) backward compatibility.

## Motivation

When sending messages over Waku, 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](../../legacy/6/waku1.md).
- One may want to provide compatibility with [6/WAKU1](/waku/standards/legacy/6/waku1.md) envelopes.
- 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 [2119](https://www.ietf.org/rfc/rfc2119.txt).

### Waku Message

A Waku message is constituted by the combination of data payload and
A `WakuMessage` 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*.

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
The `WakuMessage` attributes are key-value pairs of metadata associated with a message.
The message data payload is the part of the transmitted `WakuMessage`
that is the actual message information.
The data payload is also treated as a Waku message attribute for convenience.
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).
as described in [23/WAKU2-TOPICS](/waku/informational/23/topics.md).

- 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,
to various [10/WAKU2](/waku/standards/core/10/waku2.md) protocols,
thereby enabling customized processing based on its contents.

- The `version` attribute, if present,
Expand All @@ -75,15 +81,18 @@ signifies 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 `rate_limit_proof` attribute, if present,
contains a rate limit proof encoded as per [17/WAKU2-RLN-RELAY](/waku/standards/core/17/rln-relay.md).

- 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.
For example, an ephemeral message SHOULD not be persisted by other nodes on the same 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.

## 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";
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I somehow can't add a suggestion directly in the wire protocol below. In order to be accurate, we should one more field between meta and ephemeral:

optional bytes rate_limit_proof = 21;

and a description under "Message Attributes":

  • The rate_limit_proof attribute, if present, contains a rate limit proof encoded as per 17/WAKU2-RLN-RELAY

Expand All @@ -94,6 +103,7 @@ message WakuMessage {
optional uint32 version = 3;
optional sint64 timestamp = 10;
optional bytes meta = 11;
optional bytes rate_limit_proof = 21;
optional bool ephemeral = 31;
}
```
Expand All @@ -102,7 +112,7 @@ An example proto file following this specification can be found [here (vacp2p/wa

## 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.

Expand All @@ -112,28 +122,28 @@ the schema used to encrypt the payload data.
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](/waku/standards/legacy/6/waku1.md) payload encryption specified in [26/WAKU-PAYLOAD](/waku/standards/application/26/payload.md).
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 [WAKU2-NOISE](https://github.com/waku-org/specs/blob/master/standards/application/noise.md).
Waku Noise protocol provides symmetric encryption and asymmetric key exchange.
The 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.

## Whisper/Waku v1 envelope compatibility
## Whisper/[6/WAKU1](/waku/standards/legacy/6/waku1.md) envelope compatibility

Whisper/Waku v1 envelopes are compatible with Waku v2 messages format.
Whisper/[6/WAKU1](/waku/standards/legacy/6/waku1.md) envelopes are compatible with Waku 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](/waku/standards/legacy/6/waku1.md) `topic` field
SHOULD be mapped to Waku message's `content_topic` attribute.
- Whisper/[6/WAKU1](/waku/standards/legacy/6/waku1.md) `data` field SHOULD be mapped to Waku message's `payload` attribute.

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

## Deterministic message hashing
Expand All @@ -144,7 +154,7 @@ 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:
a [10/WAKU2](/waku/standards/core/10/waku2.md) message's hash MUST be computed following this schema:

```js
message_hash = sha256(concat(pubsub_topic, message.payload, message.content_topic, message.meta, message.timestamp))
Expand All @@ -164,7 +174,7 @@ coupled with using a SHA-2 (256-bit) hashing algorithm.

### Test vectors

Waku message hash computation (`meta` size of 12 bytes):
The `WakuMessage` hash computation (`meta` size of 12 bytes):

```js
pubsub_topic = "/waku/2/default-waku/proto" (0x2f77616b752f322f64656661756c742d77616b752f70726f746f)
Expand All @@ -176,7 +186,7 @@ message.timestamp = 0x175789bfa23f8400
message_hash = 0x64cce733fed134e83da02b02c6f689814872b1a0ac97ea56b76095c3c72bfe05
```

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

```js
pubsub_topic = "/waku/2/default-waku/proto" (0x2f77616b752f322f64656661756c742d77616b752f70726f746f)
Expand All @@ -188,7 +198,7 @@ message.timestamp = 0x175789bfa23f8400
message_hash = 0x7158b6498753313368b9af8f6e0a0a05104f68f972981da42a43bc53fb0c1b27
```

Waku message hash computation (`meta` attribute not present):
The `WakuMessage` hash computation (`meta` attribute not present):

```js
pubsub_topic = "/waku/2/default-waku/proto" (0x2f77616b752f322f64656661756c742d77616b752f70726f746f)
Expand All @@ -200,7 +210,7 @@ message.timestamp = 0x175789bfa23f8400
message_hash = 0xa2554498b31f5bcdfcbf7fa58ad1c2d45f0254f3f8110a85588ec3cf10720fd8
```

Waku message hash computation (`payload` length 0):
The `WakuMessage` hash computation (`payload` length 0):

```js
pubsub_topic = "/waku/2/default-waku/proto" (0x2f77616b752f322f64656661756c742d77616b752f70726f746f)
Expand All @@ -217,28 +227,29 @@ message_hash = 0x483ea950cb63f9b9d6926b262bb36194d3f40a0463ce8446228350bd44e96de
### Confidentiality, integrity, and authenticity

The level of confidentiality, integrity, and
authenticity of the Waku message payload is discretionary.
authenticity of the `WakuMessage` 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.
signature schemes supported by [10/WAKU2](/waku/standards/core/10/waku2.md),
to meet the application-specific privacy needs.

### Reliability of the `timestamp` attribute

The Waku message `timestamp` attribute is set by the sender.
The message `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
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 Waku messages’ `timestamp` attribute
are recommended to use additional methods for more robust message ordering.
Applications using [10/WAKU2](/waku/standards/core/10/waku2.md) 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 [62/STATUS-PAYLOADS](../../../../status/62/payloads.md/#clock-vs-timestamp-and-message-ordering).
see [62/STATUS-PAYLOADS](/status/62/payloads.md/#clock-vs-timestamp-and-message-ordering).
Comment on lines 235 to +248
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not true anymore, as the timestamp are checked together with the RLN proof. Perhaps we just remove this entire section?

Copy link
Collaborator Author

@jimstir jimstir Jan 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure if this should be removed. I believe this security consideration is still relevant if an implementation does not include RLN. But if the RLN proof timestamp attribute is a solution to deter malicious actors, should this be described in this section?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Afaik the timestamp validation is still WIP and not specified properly (so we can't reference it). I wouldn't suddenly introduce RLN concepts here. Perhaps it's enough to simply state the problem as is done in this section.


### Reliability of the `ephemeral` attribute

The Waku message `ephemeral` attribute is set by the sender.
The 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.
Expand All @@ -251,8 +262,12 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public

## References

- [6/WAKU1](../../legacy/6/waku1.md)
- [Google Protocol buffers v3](https://developers.google.com/protocol-buffers/)
- [26/WAKU-PAYLOAD](../../application/26/payload.md)
- [10/WAKU2](/waku/standards/core/10/waku2.md)
- [6/WAKU1](/waku/standards/legacy/6/waku1.md)
- [23/WAKU2-TOPICS](/waku/informational/23/topics.md)
- [17/WAKU2-RLN-RELAY](/waku/standards/core/17/rln-relay.md)
- [64/WAKU2-NETWORK](/waku/standards/core/64/network.md)
- [protocol buffers v3](https://developers.google.com/protocol-buffers/)
- [26/WAKU-PAYLOAD](/waku/standards/application/26/payload.md)
- [WAKU2-NOISE](https://github.com/waku-org/specs/blob/master/standards/application/noise.md)
- [62/STATUS-PAYLOADS](../../../../status/62/payloads.md/#clock-vs-timestamp-and-message-ordering)
- [62/STATUS-PAYLOADS](/status/62/payloads.md/#clock-vs-timestamp-and-message-ordering)
Loading