mirror of https://github.com/vacp2p/rfc.git
121 lines
5.1 KiB
Markdown
121 lines
5.1 KiB
Markdown
---
|
|
slug: 14
|
|
title: 14/WAKU2-MESSAGE
|
|
name: Waku v2 Message
|
|
status: draft
|
|
editor: Oskar Thorén <oskar@status.im>
|
|
contributors:
|
|
- Sanaz Taheri <sanaz@status.im>
|
|
- Aaryamann Challani <aaryamann@status.im>
|
|
---
|
|
|
|
This specification provides a way to encapsulate messages sent over Waku with specific information security goals.
|
|
|
|
# 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
|
|
|
|
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.
|
|
|
|
The `payload` field SHOULD contain whatever payload is being sent. See section below on payload encryption.
|
|
|
|
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.
|
|
|
|
The `version` field MAY be filled out to allow for various types of payload encryption.
|
|
Omitting it means the version is 0.
|
|
|
|
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.
|
|
|
|
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`.
|
|
|
|
See [13/WAKU2-STORE](/spec/13) for more details.
|
|
|
|
## Payloads
|
|
|
|
Payloads are implemented 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;
|
|
}
|
|
```
|
|
|
|
## Payload encryption
|
|
|
|
Payload encryption depends on the `version` field.
|
|
|
|
### Version 0
|
|
|
|
This indicates that the payload SHOULD be either unencrypted or that encryption is done at a separate layer outside of Waku.
|
|
|
|
### Version 1
|
|
|
|
This indicates that payloads MUST be encrypted using [WAKU2-PAYLOAD](/spec/26).
|
|
|
|
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.
|
|
|
|
### Version 2
|
|
|
|
This indicates that payloads MUST be encoded using [35/WAKU-NOISE](/spec/35).
|
|
|
|
This provides for symmetric encryption and
|
|
asymmetric key-exchange protocols.
|
|
|
|
# Differences from Whisper / Waku v1 envelopes
|
|
|
|
In Whisper and Waku v1, an envelope contains the following fields: `expiry, ttl, topic, data, nonce`.
|
|
|
|
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
|
|
|
|
## 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).
|
|
|
|
## Reliability of the WakuMessage timestamp
|
|
|
|
The `timestamp` field in `WakuMessage` is set by the sender.
|
|
Because `timestamp` isn't independently verified, this field is prone to exploit 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.
|
|
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
|
|
|
|
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.
|
|
|
|
# Copyright
|
|
|
|
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
|