From 61824575fc3926f03bb597a309e422afbd4bbdc9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oskar=20Thor=C3=A9n?= Date: Wed, 30 Sep 2020 12:14:31 +0800 Subject: [PATCH] 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> --- specs/waku/README.md | 1 + specs/waku/v2/waku-message.md | 86 +++++++++++++++++++++++++++++++++++ specs/waku/v2/waku-relay.md | 30 +++++------- specs/waku/v2/waku-v2.md | 3 ++ wordlist.txt | 1 + 5 files changed, 102 insertions(+), 19 deletions(-) create mode 100644 specs/waku/v2/waku-message.md diff --git a/specs/waku/README.md b/specs/waku/README.md index dc68535e..3b9165dc 100644 --- a/specs/waku/README.md +++ b/specs/waku/README.md @@ -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 diff --git a/specs/waku/v2/waku-message.md b/specs/waku/v2/waku-message.md new file mode 100644 index 00000000..a37014bc --- /dev/null +++ b/specs/waku/v2/waku-message.md @@ -0,0 +1,86 @@ +--- +title: Waku Message +version: 2.0.0-alpha1 +status: Raw +authors: Oskar Thorén +--- + +# 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/). diff --git a/specs/waku/v2/waku-relay.md b/specs/waku/v2/waku-relay.md index 1f4be19d..74c265a9 100644 --- a/specs/waku/v2/waku-relay.md +++ b/specs/waku/v2/waku-relay.md @@ -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 --- @@ -20,7 +20,7 @@ authors: Oskar Thorén `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 --> diff --git a/specs/waku/v2/waku-v2.md b/specs/waku/v2/waku-v2.md index 66ec691e..20e611d1 100644 --- a/specs/waku/v2/waku-v2.md +++ b/specs/waku/v2/waku-v2.md @@ -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` diff --git a/wordlist.txt b/wordlist.txt index e083a0e4..7a55a47d 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -159,6 +159,7 @@ trilemma ttl uint underspecified +unlinkability unencrypted unsynchronized upgradability