vacp2p/rfc
1
0
Fork 0
mirror of https://github.com/vacp2p/rfc.git synced 2025-01-11 15:24:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

promote 14/WAKU2-MESSAGE RFC to stable state (#553)

Browse Source
This commit is contained in:
Lorenzo Delgado 2022-11-15 03:12:48 +01:00 committed by GitHub
parent 50de9e7435
commit 5b798cce3c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 90 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
content/docs/rfcs/14/README.md
View File

@ -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)