mirror of https://github.com/vacp2p/rfc.git
promote 14/WAKU2-MESSAGE RFC to stable state (#553)
This commit is contained in:
parent
50de9e7435
commit
5b798cce3c
|
@ -3,118 +3,146 @@ slug: 14
|
|||
title: 14/WAKU2-MESSAGE
|
||||
name: Waku v2 Message
|
||||
status: draft
|
||||
category: Standards Track
|
||||
tags: waku/core-protocol
|
||||
editor: Oskar Thorén <oskar@status.im>
|
||||
contributors:
|
||||
- Sanaz Taheri <sanaz@status.im>
|
||||
- Aaryamann Challani <aaryamann@status.im>
|
||||
- Lorenzo Delgado <lorenzo@status.im>
|
||||
---
|
||||
|
||||
This specification provides a way to encapsulate messages sent over Waku with specific information security goals.
|
||||
# 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.
|
||||
|
||||
|
||||
# Motivation
|
||||
|
||||
When sending messages over Waku there are multiple concerns:
|
||||
- We may have a separate encryption layer as part of our application
|
||||
- We may want to provide efficient routing for resource restricted devices
|
||||
- We may want to provide compatibility with Waku v1 envelopes
|
||||
- We may want payloads to be encrypted by default
|
||||
- We may want to provide unlinkability for metadata protection
|
||||
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](/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.
|
||||
|
||||
# WakuMessage
|
||||
|
||||
A `WakuMessage` is what is being passed around by the other protocols, such as WakuRelay, WakuStore, and WakuFilter.
|
||||
# Semantics
|
||||
|
||||
The `payload` field SHOULD contain whatever payload is being sent. See section below on payload encryption.
|
||||
## Waku Message
|
||||
|
||||
The `contentTopic` field SHOULD be filled out to allow for content-based filtering.
|
||||
See [12/WAKU2-FILTER](/spec/12) and [13/WAKU2-STORE](/spec/13) for more details.
|
||||
To enable a bidirectional bridge with Waku v1 see [15/WAKU2-BRIDGE](/spec/15) for further requirements on this field.
|
||||
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*.
|
||||
|
||||
The `version` field MAY be filled out to allow for various types of payload encryption.
|
||||
Omitting it means the version is 0.
|
||||
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 `timestamp` field MAY be filled out to signify the time at which the message is generated by its sender.
|
||||
This field holds the Unix epoch time in nanoseconds.
|
||||
Omitting it means the timestamp is unspecified.
|
||||
## Message Attributes
|
||||
|
||||
The `ephemeral` field MAY be set to signify the transient nature of the message.
|
||||
If the message should be stored by the [store protocol](/spec/13), then this field MUST be set to `false`, which is equivalent to omitting the field.
|
||||
If the message should not be stored by the [store protocol](/spec/13), then this field MUST be set to `true`.
|
||||
* The `payload` attribute MUST contain the message data payload to be sent.
|
||||
|
||||
See [13/WAKU2-STORE](/spec/13) for more details.
|
||||
* The `content_topic` attribute MUST specify a string identifier that can be used for content-based filtering.
|
||||
|
||||
## Payloads
|
||||
* The `version` attribute, if present, contains a version number to discriminate different types of payload encryption.
|
||||
If omitted, the value SHOULD be interpreted as version 0.
|
||||
|
||||
Payloads are implemented using [protocol buffers v3](https://developers.google.com/protocol-buffers/).
|
||||
* The `timestamp` attribute, if present, 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 `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.
|
||||
|
||||
# Wire Format
|
||||
|
||||
The Waku message wire format is specified using [protocol buffers v3](https://developers.google.com/protocol-buffers/).
|
||||
|
||||
```protobuf
|
||||
syntax = "proto3";
|
||||
|
||||
message WakuMessage {
|
||||
bytes payload = 1;
|
||||
string contentTopic = 2;
|
||||
uint32 version = 3;
|
||||
sint64 timestamp = 10;
|
||||
bool ephemeral = 31;
|
||||
string content_topic = 2;
|
||||
optional uint32 version = 3;
|
||||
optional sint64 timestamp = 10;
|
||||
optional bool ephemeral = 31;
|
||||
}
|
||||
```
|
||||
|
||||
## Payload encryption
|
||||
|
||||
Payload encryption depends on the `version` field.
|
||||
# Payload encryption
|
||||
|
||||
### Version 0
|
||||
The Waku message payload MAY be encrypted.
|
||||
The message `version` attribute indicates the schema used to encrypt the payload data.
|
||||
|
||||
This indicates that the payload SHOULD be either unencrypted or that encryption is done at a separate layer outside of Waku.
|
||||
- **Version 0:**
|
||||
The payload SHOULD be interpreted as unencrypted; additionally, it CAN indicate that the message payload has been encrypted at the application layer.
|
||||
|
||||
### Version 1
|
||||
- **Version 1:**
|
||||
The payload SHOULD be encrypted using Waku v1 payload encryption 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.
|
||||
|
||||
This indicates that payloads MUST be encrypted using [WAKU2-PAYLOAD](/spec/26).
|
||||
- **Version 2:**
|
||||
The payload SHOULD be encoded according to [35/WAKU2-NOISE](/spec/35).
|
||||
Waku Noise protocol provides symmetric encryption and asymmetric key exchange.
|
||||
|
||||
This provides for asymmetric and symmetric encryption.
|
||||
Key agreement is out of band.
|
||||
It also provides an encrypted signature and padding for some form of unlinkability.
|
||||
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.
|
||||
|
||||
### Version 2
|
||||
|
||||
This indicates that payloads MUST be encoded using [35/WAKU-NOISE](/spec/35).
|
||||
# Whisper/Waku v1 envelope compatibility
|
||||
|
||||
This provides for symmetric encryption and
|
||||
asymmetric key-exchange protocols.
|
||||
Whisper/Waku v1 envelopes are compatible with Waku v2 messages format.
|
||||
|
||||
# Differences from Whisper / Waku v1 envelopes
|
||||
* 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.
|
||||
|
||||
In Whisper and Waku v1, an envelope contains the following fields: `expiry, ttl, topic, data, nonce`.
|
||||
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.
|
||||
|
||||
Since Waku v2 is using libp2p PubSub, some of these fields can be dropped.
|
||||
The previous `topic` field corresponds to `contentTopic`.
|
||||
The previous `data` field corresponds to the `payload` field.
|
||||
|
||||
# Security Consideration
|
||||
# Security Considerations
|
||||
|
||||
## Confidentiality, integrity, and authenticity
|
||||
It is up to the application layer as to what level confidentiality, integrity and authenticity of the `payload` of `WakuMessage` matters.
|
||||
Accordingly, the application layer shall utilize the encryption and signature schemes supported in WAKU2 to meet the application-specific privacy needs.
|
||||
The set of supported schemes in WAKU2 is presented in [WAKU2-PAYLOAD](/spec/26).
|
||||
## Confidentiality, integrity, and authenticity
|
||||
|
||||
## Reliability of the WakuMessage timestamp
|
||||
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 `timestamp` field in `WakuMessage` is set by the sender.
|
||||
Because `timestamp` isn't independently verified, this field is prone to exploit and misuse.
|
||||
## 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.
|
||||
It should not solely be relied upon for operations such as message ordering.
|
||||
|
||||
For example, a malicious node 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 `WakuMessage`'s `timestamp` field are recommended to use additional methods for more robust 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](https://specs.status.im/spec/6#clock-vs-timestamp-and-message-ordering).
|
||||
|
||||
## Reliability of the ephemeral flag
|
||||
## Reliability of the `ephemeral` attribute
|
||||
|
||||
The `ephemeral` field in `WakuMessage` is set by the sender.
|
||||
Since there is currently no incentive mechanism for nodes that implement [13/WAKU2-STORE](/spec/13) and [11/WAKU2-RELAY](/spec/11) to behave correctly, this field is inherently unsecure.
|
||||
Malicious nodes that implement [11/WAKU2-RELAY](/spec/11) can flip the value of the ephemeral flag, and nodes that receive such messages would have no mechanism to verify the integrity of the message.
|
||||
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.
|
||||
|
||||
# Copyright
|
||||
## Copyright
|
||||
|
||||
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
|
||||
|
||||
|
||||
# References
|
||||
|
||||
- [6/WAKU1](/spec/6/)
|
||||
- [Google Protocol buffers v3](https://developers.google.com/protocol-buffers/)
|
||||
- [26/WAKU-PAYLOAD](/spec/26)
|
||||
- [35/WAKU2-NOISE](/spec/35)
|
||||
- [6/PAYLOADS](https://specs.status.im/spec/6#clock-vs-timestamp-and-message-ordering)
|
Loading…
Reference in New Issue