Protocols

The figure below shows the structure of Cweb protocols, from the low level crypto, file, and object store access, to higher level protocols.

Crypto and serialization

Two sets of utilities are used across the stack:

• Crypto - a cryptography library that wraps standard primitives Curve25519, AES, and implements AEAD, EC-AEAD, X3DH, Double Ratchet.

• Serialization - Cweb uses Apache Thrift for all data in the object store and for persisting local state on the client.

The Access layer

The Access layer wraps two storage APIs

• storage.remote - A REST client for remote S3-compatible object storage. In the future may contain clients for other storage types.
• storage.local - Wrappers for the local files system. Local files are used for storing encryption keys, local metadata, and caching remote files. Local storage is assumed to be secure and data is not encrypted.

The Discovery layer

The Discovery layer contains primitives for publishing and fetching Identity Descriptors (see Identity and Storage). To communicate with A, one has to know both the Cweb Id of A and the public storage profile of A. At the moment Cweb does not include discovery service, thus Cweb Ids and storage profiles are exchanged via external channels. It is up to the the user to ensure authenticity of the storage profile. In the future, one can imagine a discovery service being part of this layer.

The 1-to-1 layer

The 1-to-1 layer contains protocols for direct communication between two peers.

The Private Broadcast is a bootstrap protocol that serves two main purposes:

• Establishing a Communication Session (see below).
• One-off messaging between peers that are not interested in maintaining a session.

It requires communicating peers to know each other Cweb Ids and storage profiles. For peer A to send a private broadcast message to B, A encrypts its message with B’s public key, and publishes the encrypted file in its cloud storage. The filename is derived from B’s id using a public hash function f. To read the message, B hashes its own id into a filename using f, and attempts to read and decrypt the file with that name from A’s storage. Since f is lossy, the file could have been addressed to a different peer in which case the decryption will fail. Varying hash length of f allows trading-off efficiency (collision probability) and deniability of communicating with B.

The Communication Session is a more efficient protocol for 1-to-1 communication. The protocol is a combination of X3DH key agreement for session initiation, and Double Ratchet for message exchange. The protocol relies on peers broadcasting their X3DH prekeys as part of identity descriptors. A session is initiated by one of the parties (A) sending a session initiation messages to the other party (B) via private broadcast. Once B receives the initial message, a Double Ratchet session is established. The protocol polls messages thereafter. To poll for a message, B constructs the expected message id of the next message from A and attempts to read the corresponding file from A’s storage. When read and decryption succeed, the message is delivered. Message id derivation is an extension of the Double Ratchet protocol and is modeled after the derivation of header keys.

The 1-to-many layer

The 1-to-many layer contains protocols for privately sharing data from one to multiple peers.

Shared Object is a protocol for sharing a mutable data object with a set of peers - the subscribers. Object content is symmetrically encrypted. The owner manages the list of the subscribers, and shares decryption key with subscribers via direct communication sessions (required to be established beforehand). The owner rotates encryption key periodically, and on every change to the subscriber list. The actual object updates are being polled periodically by subscribers via file names derived from the current key.

File Sharing allows uploading and sharing files with selected peers. The protocol chunks file data and supports interrupting and resuming upload/download to allow working with large files over slow and unreliable connections. Every chunk is encrypted with its own key, as is the File Content Descriptor - the file metadata and the list of chunks and their keys. Once uploaded, the file can be shared with peers by sending a File Reference - a small data structure that contains the file metadata, a pointer to its content descriptor, and the decryption key.

Identity Profile complements the property list in the public Identity Descriptor by implementing a private list of properties that are shared with selected peers only. Identity profile protocol is a thin wrapper around the shared object protocol. In StoneAge messenger identity profile is used for sharing profile picture only with peers the user is communicating with, and to avoid having the picture being available publicly as part of the identity descriptor.

The Many-to-many layer

Shared Session implements a shared channel among multiple peers. Closest analogy is a private multi-user chatroom with a single admin. A peer creates a shared session and becomes its admin. The admin maintains session descriptor that contains session metadata, the list of participants and the content encryption key that encrypts all messages in the session. The admin shares session descriptor with participants via the shared object protocol. Participants publish messages, encrypted with the content encryption key, in their storage, and exchange message ids via a gossip protocol over the communication sessions between them. The admin rotates content encryption key periodically, and on every change to the participant list.