From 58ca4951e8663eedc45f9f70ee1d2476873e04bb Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Sun, 21 Sep 2025 22:22:44 -0700 Subject: [PATCH 1/5] Rough draft --- standards/application/inbox.md | 212 +++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 standards/application/inbox.md diff --git a/standards/application/inbox.md b/standards/application/inbox.md new file mode 100644 index 0000000..fd8aa49 --- /dev/null +++ b/standards/application/inbox.md @@ -0,0 +1,212 @@ +--- +title: Inbox based messaging +name: +category: Standards Track +status: raw +tags: chat +editor: Jazz Alyxzander +contributors: +--- +# Abstract + + +# Background / Rationale / Motivation + +Communication protocols often face a fundamental bootstrapping problem: how can two parties establish secure, authenticated communication when they lack trusted channels? Traditional centralized approaches rely on servers to deliver invitations using pre-agreed upon encryption mechanisms. + +In a decentralized context, this problem is more pronounced as participants cannot rely on an external service to help navigate version mismatches and client routing. Senders must know where participants are listening for messages and how to encode messages. Clients running older versions of the protocol are not able to interoperate with newer protocol versions which can fragment the network during upgrades. + + + +## Design goals + + +# Theory / Semantics + +## Definitions + +This document makes use of the shared terminology defined in the [CHATDEFS]() protocol. +[Sender, Recipient, invite, OutOfBand] + +## Inbox + +Inboxes are a mechanism for a client to receive messages from others which it does not share a channel with. +They are inbound only method to exchange payloads with a client. Its most direct application is to enable the reception of invites to other communication channels. + +They provide : + - Payload Confidentiality: Only the participants can read the contents of any message sent. + - Content Integrity: Recipients can detect if the contents were modified by a third party. + - Sender Privacy: Only the recipient can determine who the sender was. + - Mutual Authentication: All participants are confident of who the participants are + - Forward Secrecy: A compromise in the future does not allow previous messages to be decrypted by a third party. + +### Message Flow + +- Recipient subscribes to a `delivery_address`. +- Recipient and Sender exchange the required data out of band. +- Sender sends message to the `deliver_address` encrypted for the recipient. + +```mermaid +sequenceDiagram + + actor S as Saro + participant I as
(Raya) + actor R as Raya + + I -->> R: Subscribe + + note over R,S: Send Out-of-Band + R ->> S : PreMessage(IK,EK,) + + note over R,S: Sent In-Band + S ->> I : M1 + I --) R: + +``` + + +### Message Routing + +This protocol assumes that a delivery service is used to transport messages. To facilitate the delivery of messages this protocol introduces the concept of a `delivery address`. The `delivery address` is an abstraction of the identifier used to route messages in the delivery service of choice. Clients subscribe to a delivery address, in order to receive message the set of messages sent to that address. While messages are not + +- Messages sent to a `delivery address` MAY not be delivered to a subscribed client. +- Messages sent to a `delivery address` MAY arrive out of order +- All clients subscribed to the same `delivery address` MUST receive the same set of messages under normal operation. +- Clients subscribed to a `delivery address` MAY receive message +- A subscription to a `delivery address` MAY include messages intended for other subscribers. + +`Senders` must know in advance the `delivery_address` which a client is subscribed to. How this occurs is out-of-scope of this specification. + +# Encryption + +## Preamble + +### Keys +Each participant has two keys: +- **InstallationKey (IK):** Longterm static key which identifies an instance of a client. +- **EphemeralKey (EK):** Single use key for added security. + + +## Pre-messages + +As a prerequiste to establishing a secure channel, the `sender` must know the `recipients` InstallationKey and EphemeralKey + +How these are transfer is out of scope for this protocol. + + +## Key Exchange + +Inbox messages are encrypted using a variant of the KX noise handshake. + +``` +KX: + -> s + ... + -> e + <- e, ee, se, s, es +``` + +To maintain asynchronicity of the key exchange the Noise:initiators ephemeral key is sent as a pre-message along with the initiators long term secret. + + +A equivalent way of writing this using noise handshake notation would be: + +``` +XK0: + <- s + <- e + ... + -> e, ee, es, s, se +``` +In this notation the noise roles have been swapped so that the noise initiator aligns with the protocols definitions of a `Sender`. + + +## Ciphersuite + +The noise handshake is implemented with the following functions: + +DH: X25519 cipher: AEAD_CHACHA20_POLY1305 hash: BLAKE2b + +## Recipient Key Identifer +Recipients need to know which ephemeral public key was used in the senders noise handshake. To communicate this, senders include a short identifier for the key. + +Calculated as: `blake2b('WAP|{K})`[0..4] + +Where +- `K` is the publicKey encoded acccording to [section 5](https://datatracker.ietf.org/doc/html/rfc7748#section-5) of rfc7748 + +[TODO] The key Identifier is sent unencrypted and thus can be used to link sent payloads to an existing set of participants if the channel used to distribute the pre-messages was compromised. At the moment it needs to be transmitted it is possible to compute `es` which would mean the information could be encrypted prior to transport with modification to the handshake. + +## Validation + +- Clients MUST ensure that ephemeral keys are used at most once. +- Once a ephemeral key has been used recipients must discard all future messages attempting to use that key. + +## Wire Format Specification / Syntax + +The wire format is specified using protocol buffers v3. + +### Encryption Wrapper +```protobuf +message NoiseXK0 { + bytes ephemeral = 1; + bytes key_ref = 2; + bytes static = 3; //Encrypted + bytes payload = 4; +} +``` +Message provides the required parameters for a recipient to decrypt a message using the XK0 handshake pattern. + +- **ephemeral:** This field contains the remotes ephemeral public key. +- **key_ref:** This field contains the recipient key identifier used in the handshake. This value is 4 bytes long. +- **static:** this field contains the remotes static public key. This value is encrypted according to the noise protocol to hide the senders identity. +- **payload:** This field contains an encrypted protobuf encoded InboxV1Frame containing the encrypted payload. + + +### Inbox Frame +```protobuf +message InboxV1Frame { + int64 timestamp = 1; + oneof frame_type { + invite.InvitePrivateV1 invite_private_v1 = 10; + } +} +``` +This message + + + + + + +## Implementation Suggestions (optional) + +Recipients ephemeral key is not signed, and is susceptible to tampering by an active attacker during transit out of band. Implementors SHOULD keep the number of valid keys as little as possible. Revoking keys after a defined period of time, and only generating keys when needed minimizes the ability for an attacker to substitute weak keys + +### Delivery Address + +Implementors should be mindful when choosing a scheme for assigning delivery addresses to an inbox as this will have direct impact on client scalability. Clients will receive all messages for a delivery address, which increases the number of messages that clients will have to process. + + +## Security/Privacy Considerations + +Ephemeral key signing + + +- Weak forward secrecy attack - Ephemeral keys can be chosen by a malicious actor +- Privacy Concern - Ephemeral key binding + + +Recipient Ephemeral keys are considered identifying information. Anyone knowing the ephemeral key, will be able to link the pre-message to the first message on the wire. Note: When pre-messages are sent publicly or intercepted by a attacker, the security properties remain intact. + + +## References + +[rfc7748](https://datatracker.ietf.org/doc/html/rfc7748#section-5) + + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + + From c8bb2b3602539a78588a8003f9b040e84c928c82 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Mon, 22 Sep 2025 16:53:43 -0700 Subject: [PATCH 2/5] fix typos --- standards/application/inbox.md | 25 +++++++++---------------- 1 file changed, 9 insertions(+), 16 deletions(-) diff --git a/standards/application/inbox.md b/standards/application/inbox.md index fd8aa49..362aa9b 100644 --- a/standards/application/inbox.md +++ b/standards/application/inbox.md @@ -17,10 +17,6 @@ Communication protocols often face a fundamental bootstrapping problem: how can In a decentralized context, this problem is more pronounced as participants cannot rely on an external service to help navigate version mismatches and client routing. Senders must know where participants are listening for messages and how to encode messages. Clients running older versions of the protocol are not able to interoperate with newer protocol versions which can fragment the network during upgrades. - -## Design goals - - # Theory / Semantics ## Definitions @@ -91,7 +87,7 @@ Each participant has two keys: As a prerequiste to establishing a secure channel, the `sender` must know the `recipients` InstallationKey and EphemeralKey -How these are transfer is out of scope for this protocol. +How these are transfered is out of scope for this protocol. ## Key Exchange @@ -130,14 +126,19 @@ DH: X25519 cipher: AEAD_CHACHA20_POLY1305 hash: BLAKE2b ## Recipient Key Identifer Recipients need to know which ephemeral public key was used in the senders noise handshake. To communicate this, senders include a short identifier for the key. -Calculated as: `blake2b('WAP|{K})`[0..4] +Calculated as: `blake2b(utf8ToBytes('WAP') || K)`[0..4] Where -- `K` is the publicKey encoded acccording to [section 5](https://datatracker.ietf.org/doc/html/rfc7748#section-5) of rfc7748 +- `K` is the publicKey encoded according to [section 5](https://datatracker.ietf.org/doc/html/rfc7748#section-5) of rfc7748. +- `||` is byte concatenation + +Example: + [TODO] [TODO] The key Identifier is sent unencrypted and thus can be used to link sent payloads to an existing set of participants if the channel used to distribute the pre-messages was compromised. At the moment it needs to be transmitted it is possible to compute `es` which would mean the information could be encrypted prior to transport with modification to the handshake. -## Validation +## Key Management + - Clients MUST ensure that ephemeral keys are used at most once. - Once a ephemeral key has been used recipients must discard all future messages attempting to use that key. @@ -172,12 +173,6 @@ message InboxV1Frame { } } ``` -This message - - - - - ## Implementation Suggestions (optional) @@ -191,8 +186,6 @@ Implementors should be mindful when choosing a scheme for assigning delivery add ## Security/Privacy Considerations Ephemeral key signing - - - Weak forward secrecy attack - Ephemeral keys can be chosen by a malicious actor - Privacy Concern - Ephemeral key binding From aac0ef6a87160bbbc92f286f4898bda4f3137346 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Thu, 25 Sep 2025 09:37:10 -0700 Subject: [PATCH 3/5] cross link chat-definitions --- standards/application/inbox.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/standards/application/inbox.md b/standards/application/inbox.md index 362aa9b..e3e3332 100644 --- a/standards/application/inbox.md +++ b/standards/application/inbox.md @@ -21,8 +21,14 @@ In a decentralized context, this problem is more pronounced as participants cann ## Definitions -This document makes use of the shared terminology defined in the [CHATDEFS]() protocol. -[Sender, Recipient, invite, OutOfBand] +This document makes use of the shared terminology defined in the [CHAT-DEFINITIONS](https://github.com/waku-org/specs/blob/jazzz/chatdefs/informational/chatdefs.md) specification. + +The terms include: +- Invite +- OutOfBand +- Recipient +- Sender + ## Inbox From 1a46d4bf8c88dc691aa1a2d665b2b2267ba575d4 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Thu, 25 Sep 2025 13:47:17 -0700 Subject: [PATCH 4/5] update message routing --- standards/application/inbox.md | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/standards/application/inbox.md b/standards/application/inbox.md index e3e3332..ac93838 100644 --- a/standards/application/inbox.md +++ b/standards/application/inbox.md @@ -42,6 +42,14 @@ They provide : - Mutual Authentication: All participants are confident of who the participants are - Forward Secrecy: A compromise in the future does not allow previous messages to be decrypted by a third party. + +### Message Routing + +This protocol assumes that a delivery service is used to transport messages as described by [CHAT-FRAMEWORK](https://github.com/waku-org/specs/blob/jazzz/chat_framework/standards/application/chat-framework.md#delivery-service) + +`Senders` must know in advance the `delivery_address` which a client is subscribed to. How this occurs is out-of-scope of this specification. + + ### Message Flow - Recipient subscribes to a `delivery_address`. @@ -67,18 +75,6 @@ sequenceDiagram ``` -### Message Routing - -This protocol assumes that a delivery service is used to transport messages. To facilitate the delivery of messages this protocol introduces the concept of a `delivery address`. The `delivery address` is an abstraction of the identifier used to route messages in the delivery service of choice. Clients subscribe to a delivery address, in order to receive message the set of messages sent to that address. While messages are not - -- Messages sent to a `delivery address` MAY not be delivered to a subscribed client. -- Messages sent to a `delivery address` MAY arrive out of order -- All clients subscribed to the same `delivery address` MUST receive the same set of messages under normal operation. -- Clients subscribed to a `delivery address` MAY receive message -- A subscription to a `delivery address` MAY include messages intended for other subscribers. - -`Senders` must know in advance the `delivery_address` which a client is subscribed to. How this occurs is out-of-scope of this specification. - # Encryption ## Preamble From 3d4eac0fa4b5a0be23dbb0863153d344b3e73805 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Thu, 25 Sep 2025 13:48:34 -0700 Subject: [PATCH 5/5] expanded rki --- standards/application/inbox.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/standards/application/inbox.md b/standards/application/inbox.md index ac93838..ee9c674 100644 --- a/standards/application/inbox.md +++ b/standards/application/inbox.md @@ -126,7 +126,10 @@ The noise handshake is implemented with the following functions: DH: X25519 cipher: AEAD_CHACHA20_POLY1305 hash: BLAKE2b ## Recipient Key Identifer -Recipients need to know which ephemeral public key was used in the senders noise handshake. To communicate this, senders include a short identifier for the key. +When receiving a payload it is initially unclear which Recipients ephemeral key was used by the sender in the noise handshake. +The Recipient sends their ephemeral key out of band, and there may exist many such keys. The recipient could exhaustively attempt decryption with it's available keys however this is potentially inefficient. Additionally in the case of decryption failure, its ambiguious whether the ephemeral keys was never valid or has expired/consumed. + +To make this efficient, the Sender includes a short identifier for the key. Calculated as: `blake2b(utf8ToBytes('WAP') || K)`[0..4]