mirror of https://github.com/vacp2p/rfc.git
148 lines
6.4 KiB
Markdown
148 lines
6.4 KiB
Markdown
---
|
||
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>
|
||
---
|
||
|
||
# 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 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.
|
||
|
||
|
||
# Semantics
|
||
|
||
## 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*.
|
||
|
||
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.
|
||
|
||
## 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.
|
||
|
||
* 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.
|
||
|
||
* 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 content_topic = 2;
|
||
optional uint32 version = 3;
|
||
optional sint64 timestamp = 10;
|
||
optional bool ephemeral = 31;
|
||
}
|
||
```
|
||
|
||
|
||
# Payload encryption
|
||
|
||
The Waku message 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.
|
||
|
||
- **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.
|
||
|
||
- **Version 2:**
|
||
The payload SHOULD be encoded according to [35/WAKU2-NOISE](/spec/35).
|
||
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/Waku v1 envelopes are compatible with Waku v2 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.
|
||
|
||
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.
|
||
|
||
|
||
# Security Considerations
|
||
|
||
## 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.
|
||
|
||
## 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 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` 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.
|
||
|
||
## 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) |