diff --git a/standards/application/wakuchat.md b/standards/application/wakuchat.md new file mode 100644 index 0000000..c2c0f31 --- /dev/null +++ b/standards/application/wakuchat.md @@ -0,0 +1,171 @@ +--- +title: WakuChat +name: A private decentralized messaging protocol over Waku. +category: Standards Track +status: raw +tags: chat +editor: Jazz Alyxzander +contributors: +--- +# Abstract + + +# Background / Rationale / Motivation + +Waku is a decentralized P2P protocol, which _______. + + +## Definitions + +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 + + +# Theory / Semantics + +This specification defines an implementation based on the Chat Protocol framework outlined [here](https://github.com/waku-org/specs/blob/jazzz/chat_framework/standards/application/chat-framework.md) + +- **Discovery Protocol:** OOB Invite Links [TODO: Link to spec]() +- **Initialization Protocol:** [InboxV1](https://github.com/waku-org/specs/blob/jazzz/inbox_xk0/standards/application/inbox.md) +- **Conversation Protocols:** [PrivateV1](TODO) +- **Delivery Service:** Waku +- **Framing Strategy:** WapEnvelopes with protocol tagging + + +# Registration + +A client is considered registered when it generates the required values: +- A static curve25519 keypair referred to as its `InstallationKey` or `IK` +- + +# Protocol Definitions + +## Discovery Protocol +Clients are expected to find one another over existing established channels. + +Data Exchange is specified by using [Invite links](TODO). + +Senders require the following data in order to proceed with initialization: +- Recipient IK +- Recipient EK +- delivery_address + +Where EK is the ephemeral keys used in the initialization protocol. + +## Initialization Protocol +This protocol uses `InboxV1` for handling of initial messages. + + +### Delivery Address +A clients inbox uses a static `delivery_address` so that Senders and Recipients can always derive it the same. + +TODO: define delivery_address + +### Conversation_id +A clients inbox uses a static `conversation_id` so that Senders and Recipients can always derive it the same. + +It's defined as: `rhex(blake2b("inboxV1" || IK.public))` + +TODO: define key format + +## Conversation Protocols + + +# Transport Definitions + +## Delivery Service + +Waku is used as the Delivery service for all in band payloads. + +Clients MUST connect with with following parameters: +- ClusterId: 19 +- ShardId: 0 + +Waku encryption is not used. Instead protocols rely on the application level encryption for confidentiality. + +### ContentTopics + +The content topic of a payload is defined using [23/WAKU2-TOPICS](https://rfc.vac.dev/waku/informational/23/topics#content-topics) where: + +- **application-name:** `wapchat` +- **version-of-the-application:** `0` +- **content-topic-name:** `chat-{rhex(blake2b(delivery_address, 8))}` #TODO: Decide on client load factor, and where to define prefix +- **encoding:** `proto` + +This `content-topic-name` scheme is possible because all protocols used rely on inbox-based-addressing. + +## Framing Strategy + +All payloads are wrapped in a common envelope type and an encryption wrapper. This provides consistent parsing for clients across all protocols. + + +### Envelopes + +Envelopes attach a reference to the state machine required to process the containing payload. + +To process a payload, a client must know how a payload was encoded/encrypted and what encryption state to use to decrypt it. +As clients can support multiple sub-protocols simultaneously, its not always determinable how a message needs to be decrypted/handled. To resolve this a conversation_hint is included with every payload. + +### Conversation Hinting + +Conversation_ids are sufficient to allow clients to determine how to decrypt a payload. However this would leak Conversation metadata, as observers could determine which payloads belonged together into a group. Instead a hint is used which allows clients to check if this payload is of interest without exposing the identifier. + +ConversationHints are computed by using a salted hash of the `conversationId`. specifically defined as `rhex(blake2s(salt || conversation_id))`. + +Clients can check if a conversation_hint is of interest to them, then retrieve the associated encryption state. Payloads with an unknown hint can be safely disregarded. + +TODO: Can this be removed with ratcheting identifiers? Salting requires clients to check every conversation id. + + +## Wire Format Specification / Syntax + +The wire format is specified using protocol buffers v3. + +### Envelope +``` +message WapEnvelopeV1 { + + // Indicates which conversation this message belongs to without revealing metadata + string conversation_hint = 1; + // Used to compute the conversation_hint + uint32 salt = 2; + // Data encoded according to the corresponding ConversationType + bytes payload = 3; +} +``` +This message is the root message of all payloads in the protocol. + +- **conversation_hint:** This field contains a utf8 string representing the `conversation_hint`. +- **salt:** This field contains a 4byte salt used to compute the `conversation_hint`. +- **payload:** This field contains a protobuf encoded payload. + + +## Implementation Suggestions (optional) + +### User level Conversations + +Application developers should maintain standalone identifiers for user-level conversations that are separate from the protocol-level conversation_id. A single logical conversation from the user's perspective may utilize multiple ConversationTypes over time. As versions are considered different types, the underlying relationship is many to one. By maintaining application-level conversation identifiers, developers can provide users with consistent conversation continuity while the underlying protocol mechanisms handle version transitions and security upgrades transparently. + + +## Security/Privacy Considerations + +Payloads inherit the privacy and security properties of the ConversationType used to send them. Please refer to the corresponding specifications when analyzing properties. + +### Inbox Privacy + +Initial messages sent using this protocol do not benefit from recipient privacy. If an attacker learns of a clients inbox conversation_id, they can guess and check all messages for a matching conversation_hint. While not trivial, it must be assumed that attackers can determine if a client has receive a message. + +In this case the Envelopes contain no sender information, so this does not leak social graph information. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +## References + +A list of references.