Implementing Forward Secrecy in Rust: A Double Ratchet and Three Storage Formats

Post 4 of 6 on Anyhide. This post is about forward secrecy: the property that even if your private key is later compromised, past messages stay unreadable.

Forward secrecy is one of those properties that sounds like it should be easy and absolutely is not.

The goal is simple: if Alice sends Bob ten messages and then Bob's laptop gets seized and his long-term private key is extracted, the attacker should not be able to decrypt any of the ten past messages. Not one.

The way you achieve this is by never using the long-term key to encrypt message content directly. Instead, both sides derive per-message keys from a chain, and they delete each key after it's used. Extracting the long-term key later gives you nothing, because the keys that actually encrypted the messages are gone.

Signal pioneered the standard design — the Double Ratchet — in 2014. Anyhide uses a variant of it. This post walks through what I built and why.

The cryptographic primitives

Anyhide's chat uses three primitives, all of which are in standard Rust crates:

• X25519 (x25519-dalek) for Diffie-Hellman key exchange.
• ChaCha20-Poly1305 (chacha20poly1305) for authenticated symmetric encryption.
• HKDF-SHA256 (hkdf + sha2) for key derivation.

None of these are exotic. The interesting part is how they're composed.

The SessionKeys struct

After the handshake (more on that in Post 5), both parties derive a bundle of session keys from the initial DH shared secret. Here's the struct:

// src/chat/protocol/ratchet.rs

use zeroize::{Zeroize, ZeroizeOnDrop};

/// Session keys derived from the initial DH exchange.
#[derive(Zeroize, ZeroizeOnDrop)]
pub struct SessionKeys {
    /// Key for encrypting/decrypting message headers.
    pub header_key: [u8; 32],
    /// Initial sending chain key.
    pub send_chain: [u8; 32],
    /// Initial receiving chain key.
    pub recv_chain: [u8; 32],
    /// Chain for deterministic carrier selection.
    pub carrier_chain: [u8; 32],
    /// Derived passphrase for anyhide encoding (not user-provided).
    pub passphrase: [u8; 32],
}

A few things worth noting:

#[derive(Zeroize, ZeroizeOnDrop)] — when this struct drops, all five [u8; 32] arrays are overwritten with zeros before the memory is released. This isn't a perfect defense (memory can be paged to disk, copied by the compiler, etc.) but it closes the obvious hole. Every key-bearing struct in Anyhide has this.

Separate send and receive chains — Alice's "send" chain is Bob's "receive" chain, and vice versa. Both sides advance their own chain independently as they send and receive messages. Each message gets its own key from the current chain position.

A passphrase field — this is the part that's specific to Anyhide. Remember, chat messages still get encoded as positions in a carrier file. The encoder needs a passphrase. We don't want to reuse the user's chat passphrase (which might be short), so we derive a 32-byte secret from the DH exchange and use that as the passphrase. The user never sees it; it's just a high-entropy key.

The symmetric ratchet

The core "advance one step" operation is this function:

/// Advance a KDF chain and derive a message key.
///
/// This is the symmetric ratchet step. The chain key is updated and a message
/// key is derived for encrypting/decrypting a single message.
pub fn kdf_chain(chain_key: &[u8; 32]) -> ([u8; 32], [u8; 32]) {
    let hk = Hkdf::<Sha256>::new(None, chain_key);

    let mut new_chain = [0u8; 32];
    let mut message_key = [0u8; 32];

    hk.expand(LABEL_CHAIN_ADVANCE, &mut new_chain)
        .expect("32 bytes is valid output length");
    hk.expand(LABEL_MESSAGE_KEY, &mut message_key)
        .expect("32 bytes is valid output length");

    (new_chain, message_key)
}

Input: the current chain key. Output: a new chain key and a message key. The message key encrypts exactly one message and is then discarded. The new chain key replaces the old one.

The security property: given only new_chain, you cannot recover chain_key (HKDF is one-way). Given only message_key, you cannot recover chain_key either. And since the old chain key was overwritten by the new one, a later attacker who extracts memory sees only the current chain — not any of the past ones. Past message keys are unrecoverable.

Domain separation

Notice those LABEL_* constants. HKDF uses them as "info" parameters to distinguish different derivations from the same input. Anyhide has seven labels:

const LABEL_HEADER_KEY: &[u8]    = b"ANYHIDE-CHAT-HEADER";
const LABEL_SEND_CHAIN: &[u8]    = b"ANYHIDE-CHAT-SEND";
const LABEL_RECV_CHAIN: &[u8]    = b"ANYHIDE-CHAT-RECV";
const LABEL_CARRIER_CHAIN: &[u8] = b"ANYHIDE-CHAT-CARRIER";
const LABEL_PASSPHRASE: &[u8]    = b"ANYHIDE-CHAT-PASS";
const LABEL_CHAIN_ADVANCE: &[u8] = b"ANYHIDE-CHAT-CHAIN";
const LABEL_MESSAGE_KEY: &[u8]   = b"ANYHIDE-CHAT-MESSAGE";

Why so many? Because HKDF with the same input but different labels produces uncorrelated outputs. Using distinct labels for distinct purposes means that leaking, say, a carrier chain key doesn't help an attacker derive header keys, and vice versa.

This is cheap to get right and expensive to get wrong. If you reuse the same label for two different purposes, you can end up in the situation where two independent parts of your protocol derive the same key — and now the two parts can impersonate each other's outputs.

The rule I follow: every hkdf.expand() call gets a unique label that names its purpose. No exceptions.

The DH ratchet

The symmetric ratchet is half the story. It protects message keys within a single direction of the conversation. The other half is the DH ratchet: every time the conversation direction changes (Alice sends, then Bob replies), a new ephemeral keypair is generated and the chain keys are refreshed from a fresh DH output.

This is what gives you the "double" in Double Ratchet: symmetric KDF advances within a run of same-direction messages, DH refreshes when direction changes.

The practical effect: even if an attacker compromises the full session state at some point in the conversation, they lose access to future messages as soon as the next DH ratchet step happens. Because the new ephemeral secret is generated locally and immediately mixed into the chains, the attacker can't derive the post-ratchet keys without DH-negotiating with one of the parties.

Three storage formats (and why)

Here's the part I didn't see coming when I started building this. Once you have ephemeral keys, you have to store them somewhere. And "somewhere" turns out to depend a lot on the use case.

Anyhide supports three formats:

Format 1: Individual PEM files

alice.pub      -----BEGIN ANYHIDE EPHEMERAL PUBLIC KEY-----
alice.key      -----BEGIN ANYHIDE EPHEMERAL SECRET KEY-----

The header explicitly distinguishes ephemeral keys from long-term keys. If you accidentally try to use an ephemeral key as a long-term identity, the parser yells at you. This format is good for one-off file transfers where you hand-manage keys.

Format 2: Separate consolidated JSON

// mykeys.eph.key
{
  "version": 1,
  "contacts": {
    "bob":   { "key": "base64..." },
    "carol": { "key": "base64..." }
  }
}

// contacts.eph.pub
{
  "version": 1,
  "contacts": {
    "bob":   { "key": "base64..." },
    "carol": { "key": "base64..." }
  }
}

One file for your private ephemeral keys, another for the public keys you hold for each contact. This is good when you want to keep private key material in a separate, more-protected file.

Format 3: Unified JSON

// contacts.eph
{
  "version": 1,
  "contacts": {
    "bob": {
      "my_private":   "base64...",
      "their_public": "base64..."
    }
  }
}

One file per contact, containing both sides of the key pair. This is what the chat client uses, because during a live chat the two things you need — your private key for this contact and their public key — are always used together. Splitting them into separate files would just be pain.

Why three?

I tried to collapse these down. I couldn't. Each use case has a different access pattern:

• Format 1 (individual PEM) is good for batch operations where you're moving keys between machines. PEM files are human-inspectable, work with standard tools, and can be attached to emails or printed to paper.
• Format 2 (separate consolidated) is good for archival — you want many contacts in one file, but with clear separation between private and public material. The file you back up is different from the file you share.
• Format 3 (unified per-contact) is good for runtime — the chat client needs fast access to the current key pair for one contact at a time. Having both halves co-located eliminates a class of bugs where a reply uses a mismatched pair.

Rather than force users into one pattern, I let each use case pick. The cost is some serde code and documentation. The benefit is that the tool never makes the user fight the storage model.

If I were writing this today, I'd probably unify them behind a KeyStore trait and let the caller pick a backend. Right now they're three different code paths with similar logic. Not the worst tech debt but it bothers me.

The ratchet in action

From the library API, using the ratchet looks like this:

use anyhide::{encode_with_config, EncoderConfig};

let config = EncoderConfig {
    ratchet: true,
    ..Default::default()
};

let result = encode_with_config(
    &carrier,
    "hello!",
    "pass",
    &bobs_current_public_key,
    &config,
)?;

// result.code is what you send on the wire.
// result.next_keypair is your new ephemeral keypair for the next round.
// Save it. When Bob replies, use next_keypair.secret to decrypt.

And when Bob decodes:

let decoded = decode_with_config(&code, &carrier, "pass",
                                  &my_secret_key, &DecoderConfig::default());

if let Some(next_public) = decoded.next_public_key {
    // Alice included her new public key for next round.
    // Store it and use it for your reply.
    update_contacts_file("bob", &next_public)?;
}

The ratchet metadata rides inside the encrypted payload, not alongside it. An attacker on the wire can't see that key rotation is happening, can't see the ephemeral public keys, can't distinguish a ratcheting session from a non-ratcheting one.

What's coming

Post 5 is about how two parties find each other in the first place and set up the initial session. That's the handshake, and it runs over Tor hidden services using the arti-client crate. I haven't seen a lot of content on building on top of arti, so I'll spend some time on the rough edges and on what Tor gives you (and what it doesn't).

Post 6 closes out the series with the terminal UI: ratatui, multi-contact tabs, a command console overlay modeled on Doom's, and the UX work to make cryptography not feel hostile to use.

Both dropping every two weeks.

Repo: github.com/matutetandil/anyhide. If you're building with the Double Ratchet or similar constructions in Rust, I'd love to compare notes.