status-im
/
specs
mirror of https://github.com/status-im/specs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
specs/status-secure-transport-spe...

26 KiB
Raw Blame History

Status Secure Transport Specification

Version: 0.1 (Draft)

Author: Andrea Piana andreap@status.im, Pedro Pombeiro pedro@status.im, Corey Petty corey@status.im, Oskar Thorén oskar@status.im, Dean Eigenmann <dean@status.im

Abstract

This document describes how we provide 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.

Table of Contents

Introduction

In this document we describe how a secure channel is established, and how various conversational security properties are achieved.

Definitions

  • Perfect Forward Secrecy is a feature of specific key-agreement protocols which provide assurances that your 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.

Conventions

Types used in this specification are defined using Protobuf.

Transport Layer

Whisper serves as the transport layer 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 topic) fails to decrypt, a message is replied with the current bundle, so that the other end is notified 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 message payload is subsequently encrypted by the transport protocol - Whisper (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

    • AES-256-GCM
    • 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

    Key derivation is done 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 Account specification.

A contact-code is a protobuf Bundle message, encoded in JSON and converted to their base64 string representation.

Prekey bundles are can be extracted from any user's messages, or found via searching for their specific contact code 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, a shared server is typically used 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

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 Status Account Specification

Initial key exchange flow (X3DH)

The initial key exchange flow is described in section 3 of the X3DH protocol, 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;
  • Bundles are not sent to a centralized server, but instead served in a decentralized way as described in bundle retrieval.

Bob's prekey bundle is retrieved by Alice, 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;
}
  • identity: Identity key IK_B
  • signed_pre_keys: Signed prekey SPK_B for each device, indexed by installation-id
  • signature: Prekey signature Sig(IK_B, Encode(SPK_B))
  • timestamp: When the bundle was created locally

(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, we can use it 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 {

  Bundle bundle = 1;

  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;

}
  • bundle: optional bundle is exchanged with each message, deprecated;
  • 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)

    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);

  • DR_header: Double ratchet header (protobuf). Used when Bob's public bundle is available:

    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);
    • 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)

    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.