# SECURE-TRANSPORT | Vac Research
This document describes how Status provides a secure channel between two peers, providing confidentiality, integrity, authenticity, and forward secrecy.

Skip to main content

# SECURE-TRANSPORT

- Status: deprecated
- Editor: Filip Dimitrijevic <filip@status.im>
- Contributors:
  - Andrea Maria Piana <andreap@status.im>
  - Corey Petty <corey@status.im>
  - Dean Eigenmann <dean@status.im>
  - Oskar Thorén <oskar@status.im>
  - Pedro Pombeiro <pedro@status.im>

## Abstract​

This document describes how Status provides a secure channel between two peers, and thus provide confidentiality, integrity, authenticity and forward secrecy. It is transport-agnostic and works over asynchronous networks.

It builds on the X3DH and Double Ratchet specifications, with some adaptations to operate in a decentralized environment.

## Introduction​

This document describes how nodes establish a secure channel, and how various conversational security properties are achieved.

### Definitions​

- Perfect Forward Secrecy is a feature of specific key-agreement protocols which provide assurances that session keys will not be compromised even if the private keys of the participants are compromised. Specifically, past messages cannot be decrypted by a third-party who manages to get a hold of a private key.

- Secret channel describes a communication channel where Double Ratchet algorithm is in use.

### Design Requirements​

- Confidentiality: The adversary should not be able to learn what data is being exchanged between two Status clients.
- Authenticity: The adversary should not be able to cause either endpoint of a Status 1:1 chat to accept data from any third party as though it came from the other endpoint.
- Forward Secrecy: The adversary should not be able to learn what data was exchanged between two Status clients if, at some later time, the adversary compromises one or both of the endpoint devices.
- Integrity: The adversary should not be able to cause either endpoint of a Status 1:1 chat to accept data that has been tampered with.

All of these properties are ensured by the use of Signal's Double Ratchet

### Conventions​

Types used in this specification are defined using Protobuf.

### Transport Layer​

Whisper and Waku serves as the transport layers for the Status chat protocol.

### User flow for 1-to-1 communications​

#### Account generation​

See Account specification

#### Account recovery​

If Alice later recovers her account, the Double Ratchet state information will not be available, so she is no longer able to decrypt any messages received from existing contacts.

If an incoming message (on the same Whisper/Waku topic) fails to decrypt, the node replies a message with the current bundle, so that the node notifies the other end of the new device. Subsequent communications will use this new bundle.

## Messaging​

All 1:1 and group chat messaging in Status is subject to end-to-end encryption to provide users with a strong degree of privacy and security. Public chat messages are publicly readable by anyone since there's no permission model for who is participating in a public chat.

The rest of this document is purely about 1:1 and private group chat. Private group chat largely reduces to 1:1 chat, since there's a secure channel between each pair-wise participant.

### End-to-end encryption​

End-to-end encryption (E2EE) takes place between two clients. The main cryptographic protocol is a Status implementation of the Double Ratchet protocol, which is in turn derived from the Off-the-Record protocol, using a different ratchet. The transport protocol subsequently encrypt the message payload - Whisper/Waku (see section Transport Layer) -, using symmetric key encryption. Furthermore, Status uses the concept of prekeys (through the use of X3DH) to allow the protocol to operate in an asynchronous environment. It is not necessary for two parties to be online at the same time to initiate an encrypted conversation.

Status uses the following cryptographic primitives:

- Whisper/Waku

  - AES-256-GCM
  - ECIES
  - ECDSA
  - KECCAK-256

- X3DH

  - Elliptic curve Diffie-Hellman key exchange (secp256k1)
  - KECCAK-256
  - ECDSA
  - ECIES

- Double Ratchet

  - HMAC-SHA-256 as MAC

  - Elliptic curve Diffie-Hellman key exchange (Curve25519)

  - AES-256-CTR with HMAC-SHA-256 and IV derived alongside an encryption key

    The node achieves key derivation using HKDF.

### Prekeys​

Every client initially generates some key material which is stored locally:

- Identity keypair based on secp256k1 - `IK`
- A signed prekey based on secp256k1 - `SPK`
- A prekey signature - `Sig(IK, Encode(SPK))`

More details can be found in the `X3DH Prekey bundle creation` section of 2/ACCOUNT.

Prekey bundles can be extracted from any user's messages, or found via searching for their specific topic, `{IK}-contact-code`.

TODO: See below on bundle retrieval, this seems like enhancement and parameter for recommendation

### Bundle retrieval​

X3DH works by having client apps create and make available a bundle of prekeys (the X3DH bundle) that can later be requested by other interlocutors when they wish to start a conversation with a given user.

In the X3DH specification, nodes typically use a shared server to store bundles and allow other users to download them upon request. Given Status' goal of decentralization, Status chat clients cannot rely on the same type of infrastructure and must achieve the same result using other means. By growing order of convenience and security, the considered approaches are:

- contact codes;
- public and one-to-one chats;
- QR codes;
- ENS record;
- Decentralized permanent storage (e.g. Swarm, IPFS).
- Whisper/Waku

Currently, only public and one-to-one message exchanges and Whisper/Waku is used to exchange bundles.

Since bundles stored in QR codes or ENS records cannot be updated to delete already used keys, the approach taken is to rotate more frequently the bundle (once every 24 hours), which will be propagated by the app through the channel available.

### 1:1 chat contact request​

There are two phases in the initial negotiation of a 1:1 chat:

1. Identity verification (e.g., face-to-face contact exchange through QR code, Identicon matching). A QR code serves two purposes simultaneously - identity verification and initial bundle retrieval;
2. Asynchronous initial key exchange, using X3DH.

For more information on account generation and trust establishment, see 2/ACCOUNT

#### Initial key exchange flow (X3DH)​

Section 3 of the X3DH protocol describes the initial key exchange flow, with some additional context:

- The users' identity keys `IK_A` and `IK_B` correspond to their respective Status chat public keys;
- Since it is not possible to guarantee that a prekey will be used only once in a decentralized world, the one-time prekey `OPK_B` is not used in this scenario;
- Nodes do not send Bundles to a centralized server, but instead served in a decentralized way as described in bundle retrieval.

Alice retrieves Bob's prekey bundle, however it is not specific to Alice. It contains:

(protobuf)

    // X3DH prekey bundle
    message Bundle {

      bytes identity = 1;

      map<string,SignedPreKey> signed_pre_keys = 2;

      bytes signature = 4;

      int64 timestamp = 5;
    }

    ```golang
    - `identity`: Identity key `IK_B`
    - `signed_pre_keys`: Signed prekey `SPK_B` for each device, indexed by `installation-id`
    - `signature`: Prekey signature &lt;i&gt;Sig(`IK_B`, Encode(`SPK_B`))&lt;/i&gt;
    - `timestamp`: When the bundle was created locally

    ([protobuf](https://github.com/status-im/status-go/blob/a904d9325e76f18f54d59efc099b63293d3dcad3/services/shhext/chat/encryption.proto#L5))

    ``` protobuf
    message SignedPreKey {
      bytes signed_pre_key = 1;
      uint32 version = 2;
    }

The `signature` is generated by sorting `installation-id` in lexicographical order, and concatenating the `signed-pre-key` and `version`:

`installation-id-1signed-pre-key1version1installation-id2signed-pre-key2-version-2`

#### Double Ratchet​

Having established the initial shared secret `SK` through X3DH, it can be used to seed a Double Ratchet exchange between Alice and Bob.

Please refer to the Double Ratchet spec for more details.

The initial message sent by Alice to Bob is sent as a top-level `ProtocolMessage` (protobuf) containing a map of `DirectMessageProtocol` indexed by `installation-id` (protobuf):

    message ProtocolMessage {

      string installation_id = 2;

      repeated Bundle bundles = 3;

      // One to one message, encrypted, indexed by installation_id
      map<string,DirectMessageProtocol> direct_message = 101;

      // Public chats, not encrypted
      bytes public_message = 102;

    }

- `bundles`: a sequence of bundles
- `installation_id`: the installation id of the sender
- `direct_message` is a map of `DirectMessageProtocol` indexed by `installation-id`
- `public_message`: unencrypted public chat message.

    message DirectMessageProtocol {
      X3DHHeader X3DH_header = 1;
      DRHeader DR_header = 2;
      DHHeader DH_header = 101;
      // Encrypted payload
      bytes payload = 3;
    }

    - `X3DH_header`: the `X3DHHeader` field in `DirectMessageProtocol` contains:

        ([protobuf](https://github.com/status-im/status-go/blob/a904d9325e76f18f54d59efc099b63293d3dcad3/services/shhext/chat/encryption.proto#L47))
        ``` protobuf
        message X3DHHeader {
          bytes key = 1;
          bytes id = 4;
        }
        ```

        - `key`: Alice's ephemeral key `EK_A`;
        - `id`: Identifier stating which of Bob's prekeys Alice used, in this case Bob's bundle signed prekey.

        Alice's identity key `IK_A` is sent at the transport layer level (Whisper/Waku);

    - `DR_header`: Double ratchet header ([protobuf](https://github.com/status-im/status-go/blob/a904d9325e76f18f54d59efc099b63293d3dcad3/services/shhext/chat/encryption.proto#L31)). Used when Bob's public bundle is available:
        ``` protobuf
        message DRHeader {
          bytes key = 1;
          uint32 n = 2;
          uint32 pn = 3;
          bytes id = 4;
        }
        ```
        - `key`: Alice's current ratchet public key (as mentioned in [DR spec section 2.2](https://signal.org/docs/specifications/doubleratchet/#symmetric-key-ratchet));
        - `n`: number of the message in the sending chain;
        - `pn`: length of the previous sending chain;
        - `id`: Bob's bundle ID.

    - `DH_header`: Diffie-Helman header (used when Bob's bundle is not available):
        ([protobuf](https://github.com/status-im/status-go/blob/a904d9325e76f18f54d59efc099b63293d3dcad3/services/shhext/chat/encryption.proto#L42))
        ``` protobuf
        message DHHeader {
          bytes key = 1;
        }
        ```
        - `key`: Alice's compressed ephemeral public key.

    - `payload`:
        - if a bundle is available, contains payload encrypted with the Double Ratchet algorithm;
        - otherwise, payload encrypted with output key of DH exchange (no Perfect Forward Secrecy).

## Security Considerations​

The same considerations apply as in section 4 of the X3DH spec and section 6 of the Double Ratchet spec, with some additions detailed below.

## Session management​

A node identifies a peer by two pieces of data:

1) An `installation-id` which is generated upon creating a new account in the `Status` application 2) Their identity Whisper/Waku key

### Initialization​

A node initializes a new session once a successful X3DH exchange has taken place. Subsequent messages will use the established session until re-keying is necessary.

### Concurrent sessions​

If a node creates two sessions concurrently between two peers, the one with the symmetric key first in byte order SHOULD be used, this marks that the other has expired.

### Re-keying​

On receiving a bundle from a given peer with a higher version, the old bundle SHOULD be marked as expired and a new session SHOULD be established on the next message sent.

### Multi-device support​

Multi-device support is quite challenging as there is not a central place where information on which and how many devices (identified by their respective `installation-id`) belongs to a whisper-identity / waku-identity.

Furthermore, account recovery always needs to be taken into consideration, where a user wipes clean the whole device and the nodes loses all the information about any previous sessions.

Taking these considerations into account, the way the network propagates multi-device information using x3dh bundles, which will contain information about paired devices as well as information about the sending device.

This means that every time a new device is paired, the bundle needs to be updated and propagated with the new information, the user has the responsibility to make sure the pairing is successful.

The method is loosely based on Sesame.

### Pairing​

When a user adds a new account in the `Status` application, a new `installation-id` will be generated. The device should be paired as soon as possible if other devices are present. Once paired the contacts will be notified of the new device and it will be included in further communications.

If a bundle received from the `IK` is different to the `installation-id`, the device will be shown to the user and will have to be manually approved, to a maximum of 3. Once that is done any message sent by one device will also be sent to any other enabled device.

Once a user enables a new device, a new bundle will be generated which will include pairing information.

The bundle will be propagated to contacts through the usual channels.

Removal of paired devices is a manual step that needs to be applied on each device, and consist simply in disabling the device, at which point pairing information will not be propagated anymore.

### Sending messages to a paired group​

When sending a message, the peer will send a message to other `installation-id` that they have seen. The node caps the number of devices to 3, ordered by last activity. The node sends messages using pairwise encryption, including their own devices.

Account recovery

Account recovery is no different from adding a new device, and it is handled in exactly the same way.

### Partitioned devices​

In some cases (i.e. account recovery when no other pairing device is available, device not paired), it is possible that a device will receive a message that is not targeted to its own `installation-id`. In this case an empty message containing bundle information is sent back, which will notify the receiving end of including this device in any further communication.

## Changelog​

### Version 0.3​

Released May 22, 2020

- Added language to include Waku in all relevant places

## Copyright​

Copyright and related rights waived via CC0.

## References​

- X3DH
- Double Ratchet
- Protobuf
- Whisper
- Waku
- Account specification
- Status implementation
- Off-the-Record protocol
- X3DH
- ACCOUNT
- Sesame
- May 22, 2020 commit change