Double Ratchet Algorithm

The cryptographic engine behind every Encra message. Every time Alice sends Bob a message, three keys advance — and anything the attacker captured before that moment becomes permanently unreadable.

History & origin

The Double Ratchet Algorithm was designed by Trevor Perrin and Moxie Marlinspike at Open Whisper Systems (now Signal Foundation) in 2013, initially shipped in the TextSecure app.1 It evolved from Stuart Anderson's Off-the-Record (OTR) messaging protocol2 by replacing OTR's three-message handshake with an always-on ratchet, eliminating the need to re-negotiate keys mid-conversation.

The formal specification was published in November 20161 and independently analysed by Cohn-Gordon et al. in 20163 and by Alwen, Coretti & Dodis in 2019 (the “ACD” paper)4 which proved the protocol's security under the standard model. Today the same algorithm runs inside Signal, WhatsApp (1 billion+ users), Facebook Messenger (secret conversations), Skype (private conversations), and Google Messages (RCS E2E).

Three keys, three jobs

Every session maintains exactly three long-lived state values:

The KDF chain (symmetric ratchet)

For every message sent, the chain key advances once through a keyed hash function (KDF). Two outputs are produced from a single call:

• KDF(CK, 0x02) → next chain key (replaces the current one)
• KDF(CK, 0x01) → message key (used once to encrypt, then deleted)

Because the KDF is a one-way function, the chain can only move forward. An attacker who steals CK_n can derive MK_n, MK_{n+1}, … but cannot reverse-derive CK_{n-1} or any previous message keys — those are already gone.

The DH ratchet (asymmetric ratchet)

The KDF chain alone provides forward secrecy, but not break-in recovery — if an attacker steals the current chain key, all future messages are compromised until the conversation ends. The Diffie-Hellman ratchet fixes this.

Every message header carries the sender's current ephemeral ratchet public key. When the receiver sees a new public key, they:

1. Perform DH(their_priv, new_pub) → feed the output into the root KDF → derive a new receiving chain key.
2. Generate a fresh ephemeral key pair of their own.
3. Perform DH(new_priv, new_pub) → feed into root KDF → derive a new sending chain key.

Because fresh DH key material is mixed into the root key, any chain-key compromise is healed after the next DH step. An attacker would need to also compromise the new ephemeral private key — which was just generated and never transmitted.

Combined conversation flow

In practice, both ratchets run together: the KDF chain advances on every message; the DH ratchet advances whenever the receiver sees a new ratchet public key in the message header.

Encra implementation

The full implementation lives in packages/core/src/crypto/ratchet.ts. The public API is a single class:

export class DoubleRatchet {
  /** Start a session as the sender (Alice) after X3DH handshake */
  static initSender(
    sharedSecret: Uint8Array,        // 32-byte secret from X25519
    recipientPublicKey: Uint8Array,  // Bob's long-term or signed pre-key
  ): DoubleRatchet

  /** Start a session as the receiver (Bob) after X3DH handshake */
  static initReceiver(
    sharedSecret: Uint8Array,
    localKeyPair: KeyPair,           // Bob's ratchet key pair
  ): DoubleRatchet

  /** Encrypt a plaintext string. Returns header + ciphertext + nonce. */
  encrypt(plaintext: string): EncryptedMessage

  /** Decrypt an EncryptedMessage. Throws DecryptionFailedError on any failure. */
  decrypt(msg: EncryptedMessage): string
}

interface EncryptedMessage {
  header: {
    publicKey: Uint8Array   // sender's current ratchet public key
    n: number               // message number within the sending chain
    pn: number              // message number of last msg in previous sending chain
  }
  ciphertext: Uint8Array    // XSalsa20-Poly1305 ciphertext
  nonce: Uint8Array         // 24-byte random nonce
}

Session initialization

Sessions are bootstrapped with the shared secret from X25519 key exchange. Alice feeds it into the root KDF along with a fresh ephemeral key pair; Bob starts with just the shared secret and his ratchet key pair.

import { generateKeyPair, deriveSharedSecret } from '@encra/core'
import { DoubleRatchet } from '@encra/core'

// --- Alice's device ---
const aliceKeys = await generateKeyPair()
const sharedSecret = await deriveSharedSecret(aliceKeys.privateKey, bobPublicKey)

const aliceRatchet = DoubleRatchet.initSender(sharedSecret, bobPublicKey)
const encrypted = aliceRatchet.encrypt('Hello Bob!')
// → { header, ciphertext, nonce }

// --- Bob's device ---
const bobRatchet = DoubleRatchet.initReceiver(sharedSecret, bobKeyPair)
const plaintext = bobRatchet.decrypt(encrypted)
// → 'Hello Bob!'

Out-of-order message handling

Network reordering is common in mobile environments. When Alice sends messages 1–5 but Bob receives them in order 1, 3, 2, 5, 4 — the ratchet must still decrypt all of them correctly.

The pn (previous-chain-N) field in the header tells the receiver how many messages were sent in the previous sending chain. When a DH ratchet step is detected, Bob computes and stores all skipped message keys from the previous chain before advancing. Skipped keys for the current chain are stored as they are encountered. Both pools are bounded by MAX_SKIP_KEYS = 1000 to prevent memory exhaustion attacks.

Security properties

Signal spec vs Encra implementation

References

1. Perrin, T. & Marlinspike, M. — The Double Ratchet Algorithm (Signal Foundation, 2016)
2. Borisov, N., Goldberg, I. & Brewer, E. — Off-the-Record Communication (ACM WPES 2004)
3. Cohn-Gordon, K. et al. — On the Formal Security of Signal (IEEE EuroS&P 2017, ePrint 2016/221)
4. Alwen, J., Coretti, S. & Dodis, Y. — The Double Ratchet: Security Notions, Proofs, and Modularization (EUROCRYPT 2019, ePrint 2019/800)
5. libsodium — Generic hashing (crypto_generichash / BLAKE2b)
6. Perrin, T. & Marlinspike, M. — The X3DH Key Agreement Protocol (Signal Foundation, 2016)
7. Marlinspike, M. — Advanced cryptographic ratcheting (Signal blog, 2013)

See also