mirror of
https://github.com/vacp2p/rfc.git
synced 2025-01-27 07:05:57 +00:00
Waku message spec (#199)
* Pull out WakuMessage into separate spec * Update Waku Message spec * Fmt * Add to README * Update * Spellcheck * Update specs/waku/v2/waku-message.md Co-authored-by: Dean Eigenmann <7621705+decanus@users.noreply.github.com> * Update specs/waku/v2/waku-message.md Co-authored-by: Dean Eigenmann <7621705+decanus@users.noreply.github.com>
This commit is contained in:
Oskar Thorén
GitHub
parent
1ba2b9eed6
commit
61824575fc
@ -12,3 +12,4 @@
|
||||
- [waku/2 filter](./v2/waku-filter.md) spec for WakuFilter, alpha
|
||||
- [waku/2 store](./v2/waku-store.md) spec for WakuStore, alpha
|
||||
- [waku/2 bridge](./v2/waku-bridge.md) spec for Waku bridge with v1, alpha
|
||||
- [waku/2 message](./v2/waku-message.md) spec for Waku Message, alpha
|
||||
|
||||
86
specs/waku/v2/waku-message.md
Normal file
86
specs/waku/v2/waku-message.md
Normal file
@ -0,0 +1,86 @@
|
||||
---
|
||||
title: Waku Message
|
||||
version: 2.0.0-alpha1
|
||||
status: Raw
|
||||
authors: Oskar Thorén <oskar@status.im>
|
||||
---
|
||||
|
||||
# Table of Contents
|
||||
|
||||
- [Abstract](#abstract)
|
||||
- [Motivation](#motivation)
|
||||
- [WakuMessage](#wakumessage)
|
||||
- [Protobuf](#protobuf)
|
||||
- [Payload encryption](#payload-encryption)
|
||||
- [Version 0](#version-0)
|
||||
- [Version 1](#version-1)
|
||||
- [Differences from Whisper / Waku v1 envelopes](#differences-from-whisper--waku-v1-envelopes)
|
||||
- [Changelog](#changelog)
|
||||
- [Copyright](#copyright)
|
||||
|
||||
# Abstract
|
||||
|
||||
This specification provides a way to encapsulate messages sent over Waku with specific information security goals.
|
||||
|
||||
# Motivation
|
||||
|
||||
When using Waku to send 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 [Waku Filter spec](waku-filter.md) for details.
|
||||
|
||||
The `version` field MAY be filled out to allow for various types of payload encryption. Omitting it means the version is 0.
|
||||
|
||||
## Protobuf
|
||||
|
||||
```protobuf
|
||||
message WakuMessage {
|
||||
optional bytes payload = 1;
|
||||
optional string contentTopic = 2;
|
||||
optional string version = 3;
|
||||
}
|
||||
```
|
||||
|
||||
## 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 [Waku v1 envelope data
|
||||
format spec](../v1/envelope-data-format.md).
|
||||
|
||||
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.
|
||||
|
||||
# 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.
|
||||
|
||||
# Changelog
|
||||
|
||||
Initial release on [](TODO).
|
||||
|
||||
# Copyright
|
||||
|
||||
Copyright and related rights waived via
|
||||
[CC0](https://creativecommons.org/publicdomain/zero/1.0/).
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Waku
|
||||
version: 2.0.0-beta1
|
||||
title: Waku Relay
|
||||
version: 2.0.0-beta2
|
||||
status: Draft
|
||||
authors: Oskar Thorén <oskar@status.im>
|
||||
---
|
||||
@ -20,7 +20,7 @@ authors: Oskar Thorén <oskar@status.im>
|
||||
|
||||
`WakuRelay` is part of the gossip domain for Waku. It is a thin layer on top of GossipSub.
|
||||
|
||||
**Protocol identifier***: `/vac/waku/relay/2.0.0-beta1`
|
||||
**Protocol identifier***: `/vac/waku/relay/2.0.0-beta2`
|
||||
|
||||
## Wire Specification
|
||||
|
||||
@ -48,11 +48,6 @@ message Message {
|
||||
optional bytes signature = 5;
|
||||
optional bytes key = 6;
|
||||
}
|
||||
|
||||
message WakuMessage {
|
||||
optional bytes payload = 1;
|
||||
optional string contentTopic = 2;
|
||||
}
|
||||
```
|
||||
|
||||
WakuSub does not currently use the `ControlMessage` defined in GossipSub.
|
||||
@ -69,7 +64,7 @@ gossiped. See section below on how the fields work.
|
||||
|
||||
The `from` field MAY indicate which peer is publishing the message.
|
||||
|
||||
The `data` field SHOULD be filled out with a `WakuMessage`.
|
||||
The `data` field MUST be filled out with a `WakuMessage`. See the [Waku Message](waku-message.md) spec for more details.
|
||||
|
||||
The `seqno` field MAY be used to provide a linearly increasing number. See PubSub spec for more details.
|
||||
|
||||
@ -88,16 +83,15 @@ The `subscribe` field MUST contain a boolean, where 1 means subscribe and 0 mean
|
||||
|
||||
The `topicid` field MUST contain the topic.
|
||||
|
||||
## WakuMessage
|
||||
|
||||
A `WakuMessage` SHOULD be in the `data` field of `Message`.
|
||||
|
||||
The `payload` field SHOULD contain whatever payload is being sent. Encryption of this field is done at a separate layer.
|
||||
|
||||
The `contentTopic` field SHOULD be filled out to allow for content-based filtering (see section below).
|
||||
|
||||
## Changelog
|
||||
|
||||
### 2.0.0-beta2
|
||||
|
||||
Next version. Changes:
|
||||
|
||||
- Moved WakuMessage to separate spec and made it mandatory
|
||||
|
||||
|
||||
### 2.0.0-beta1
|
||||
|
||||
Initial draft version. Released [2020-09-17](https://github.com/vacp2p/specs/commit/a57dad2cc3d62f9128e21f68719704a0b358768b)
|
||||
@ -129,6 +123,4 @@ TODO: Don't quite understand this scenario [key field], to clarify. Wouldn't it
|
||||
|
||||
Re topicid:
|
||||
NOTE: This doesn't appear to be documented in PubSub spec, upstream?
|
||||
|
||||
TODO: Find place for WakuMessage
|
||||
-->
|
||||
|
||||
@ -74,6 +74,9 @@ The current [protocol identifiers](https://docs.libp2p.io/concepts/protocols/) a
|
||||
|
||||
These protocols and their semantics are elaborated on in their own specs.
|
||||
|
||||
For the actual content being passed around, see the [Waku
|
||||
Message](waku-message.md) spec.
|
||||
|
||||
## Gossip domain
|
||||
|
||||
**Protocol identifier***: `/vac/waku/relay/2.0.0-beta1`
|
||||
|
||||
@ -159,6 +159,7 @@ trilemma
|
||||
ttl
|
||||
uint
|
||||
underspecified
|
||||
unlinkability
|
||||
unencrypted
|
||||
unsynchronized
|
||||
upgradability
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user