The Signal Protocol

Signal Android implements the Signal Protocol through a combination of the libsignal-android library and Android-specific storage and session management code. This page explains the cryptographic building blocks, where they live in the codebase, and how they interact.

X3DH: session establishment

Before two users can exchange encrypted messages for the first time, they must establish a shared secret without ever communicating directly. Signal uses the Extended Triple Diffie-Hellman (X3DH) key agreement protocol.

Key bundles

Each account publishes a prekey bundle to the Signal server containing:

Key	Type	Description
Identity key	EC long-term	Stable identity, used across all sessions
Signed prekey	EC medium-term	Rotated periodically, signed by identity key
One-time prekey	EC single-use	Consumed on first message; prevents replay
Last-resort Kyber prekey	KEM	Post-quantum, used when one-time prekeys run out
One-time Kyber prekey	KEM	Post-quantum single-use prekey

The X3DH handshake

When Alice sends the first message to Bob, she:

Fetches Bob’s prekey bundle from the server.
Computes four Diffie-Hellman operations using her ephemeral key pair, Bob’s identity key, Bob’s signed prekey, and Bob’s one-time prekey.
Derives a shared master secret by feeding the concatenated DH outputs through HKDF.
Discards her ephemeral private key.

Bob can reconstruct the same master secret when he receives Alice’s initial message, which carries her identity key and ephemeral public key. After this point both parties initialize a Double Ratchet session using the derived secret. The Android implementation delegates all X3DH math to libsignal. The storage layer is in crypto/storage/:

SignalBaseIdentityKeyStore.java   // identity key storage and trust decisions
TextSecurePreKeyStore.java        // EC one-time and signed prekey persistence
SignalKyberPreKeyStore.kt         // Kyber prekey persistence
TextSecureSessionStore.java       // session record read/write

Double Ratchet Algorithm

Once a session is established via X3DH, all subsequent messages are protected by the Double Ratchet Algorithm. The ratchet provides both forward secrecy (compromising today’s key does not reveal past messages) and break-in recovery (future messages recover their secrecy after a compromise).

The two ratchets

Symmetric-key ratchet

A KDF chain that advances with every message. Each step produces a new message key and deletes the previous one. An attacker who obtains one message key cannot derive prior keys.

Diffie-Hellman ratchet

Each reply includes a new DH ratchet public key. Both parties advance the DH ratchet on receiving a new key, deriving a fresh chain key that reseeds the symmetric ratchet.

Message key derivation

Root key  ──DH ratchet──▶  new root key
                       └──▶  chain key  ──KDF──▶  message key (encrypts payload)
                                         └──▶  next chain key

Skipped message keys are stored temporarily so out-of-order messages can still be decrypted. After a configurable threshold they are discarded. All ratchet state is serialized into a SessionRecord protobuf and stored in the sessions table (see Database).

Pre-keys

Pre-keys allow asynchronous session establishment: Bob does not need to be online for Alice to send him a first message.

One-time EC prekeys

Generated in batches of 100 by PreKeyUtil.generateAndStoreOneTimeEcPreKeys():

// crypto/PreKeyUtil.java
private static final int BATCH_SIZE = 100;

public synchronized static List<PreKeyRecord> generateAndStoreOneTimeEcPreKeys(
    SignalServiceAccountDataStore protocolStore,
    PreKeyMetadataStore metadataStore) {
  int startingId = metadataStore.getNextEcOneTimePreKeyId();
  List<PreKeyRecord> records = generateOneTimeEcPreKeys(startingId);
  protocolStore.markAllOneTimeEcPreKeysStaleIfNecessary(System.currentTimeMillis());
  storeOneTimeEcPreKeys(protocolStore, metadataStore, records);
  return records;
}

Once a one-time prekey is consumed by an incoming session it is deleted from OneTimePreKeyTable. PreKeysSyncJob periodically replenishes the server’s supply.

Signed prekeys

A signed prekey is a medium-term EC key pair signed by the account’s identity key. It is rotated approximately every 48 hours via PreKeysSyncJob. The previous signed prekey is retained for a 30-day archive window (ARCHIVE_AGE) so that in-flight messages encrypted to the old key can still be decrypted.

Kyber (post-quantum) prekeys

Signal added post-quantum resistance with CRYSTALS-Kyber KEM prekeys, stored in KyberPreKeyTable:

// database/KyberPreKeyTable.kt
const val CREATE_TABLE = """
  CREATE TABLE $TABLE_NAME (
    $ID          INTEGER PRIMARY KEY,
    $ACCOUNT_ID  TEXT NOT NULL,
    $KEY_ID      INTEGER NOT NULL,
    $TIMESTAMP   INTEGER NOT NULL,
    $LAST_RESORT INTEGER NOT NULL,
    $SERIALIZED  BLOB NOT NULL,
    $STALE_TIMESTAMP INTEGER NOT NULL DEFAULT 0,
    UNIQUE($ACCOUNT_ID, $KEY_ID)
  )
"""

The LAST_RESORT flag distinguishes one-time Kyber prekeys (consumed on use) from the last-resort key (retained as fallback when one-time keys run out). SignalKyberPreKeyStore handles all read/write operations through this table.

Sender keys for group messaging

Encrypting a message separately for every group member would be expensive for large groups. Signal solves this with sender keys. When a device first sends to a group, it generates a sender key — a symmetric ratchet state associated with a DistributionId. The sender key is distributed to each group member encrypted under their individual Signal Protocol session. Subsequent messages to that group are encrypted once using the sender key ratchet and broadcast to all members. Key rotation is explicit. SenderKeyUtil.rotateOurKey() clears the stored sender key state, forcing re-distribution to all members on the next send:

// crypto/SenderKeyUtil.java
public static void rotateOurKey(@NonNull DistributionId distributionId) {
  try (SignalSessionLock.Lock unused = ReentrantSessionLock.INSTANCE.acquire()) {
    AppDependencies.getProtocolStore().aci()
        .senderKeys()
        .deleteAllFor(SignalStore.account().requireAci().toString(), distributionId);
    SignalDatabase.senderKeyShared().deleteAllFor(distributionId);
  }
}

Two tables back sender keys: SenderKeyTable stores your own sender key state; SenderKeySharedTable tracks which recipients have already received your sender key for a given distribution.

Sealed sender

Sealed sender hides the sender’s identity from the Signal server. Normally, even with end-to-end encryption the server sees who is sending to whom. Sealed sender wraps the ciphertext in an additional encryption layer so the server only learns the recipient, not the sender.

How it works

The sender obtains a sender certificate from the Signal server. The certificate binds the sender’s ACI (account identifier) to their identity key and is signed by Signal’s server key. The certificate may optionally omit the sender’s phone number depending on their phone number privacy settings.
The sender certificate and the sealed message ciphertext are bundled together and encrypted to the recipient’s profile key-derived unidentified access key.
The server forwards the sealed message to the recipient without being able to read the sender certificate.
The recipient decrypts using their unidentified access key, then validates the sender certificate to learn who sent the message.

// crypto/SealedSenderAccessUtil.java
private static @Nullable UnidentifiedAccess getTargetUnidentifiedAccess(
    @NonNull Recipient recipient,
    @NonNull byte[] certificate,
    boolean isForStory) throws InvalidCertificateException {

  ProfileKey theirProfileKey = ProfileKeyUtil.profileKeyOrNull(
      recipient.resolve().getProfileKey());

  byte[] accessKey;
  switch (recipient.resolve().getSealedSenderAccessMode()) {
    case ENABLED:
      accessKey = (theirProfileKey != null) ? theirProfileKey.deriveAccessKey() : null;
      break;
    case UNRESTRICTED:
      accessKey = UNRESTRICTED_KEY;
      break;
    // ...
  }
  // ...
}

CertificateType controls whether the certificate includes the sender’s phone number (ACI_AND_E164) or only the ACI (ACI_ONLY), determined by the sender’s phone number privacy setting.

Session management in Android

All Signal Protocol session state is persisted in the sessions table via SessionTable:

// database/SessionTable.kt
const val CREATE_TABLE = """
  CREATE TABLE $TABLE_NAME (
    $ID         INTEGER PRIMARY KEY AUTOINCREMENT,
    $ACCOUNT_ID TEXT NOT NULL,
    $ADDRESS    TEXT NOT NULL,
    $DEVICE     INTEGER NOT NULL,
    $RECORD     BLOB NOT NULL,
    UNIQUE($ACCOUNT_ID, $ADDRESS, $DEVICE)
  )
"""

Each row holds a serialized SessionRecord protobuf keyed by (account_id, address, device_id). This supports multi-device: one account can have sessions with each of a recipient’s linked devices simultaneously. TextSecureSessionStore wraps SessionTable and is accessed through SignalServiceDataStoreImpl, which provides the full SignalProtocolStore interface expected by libsignal.

Session access is guarded by ReentrantSessionLock — a JVM-level reentrant lock — to serialize concurrent session operations across threads. Always acquire this lock when reading or modifying session state outside of libsignal’s normal message processing path.

Safety numbers and fingerprint verification

Safety numbers let users verify they share the same cryptographic keys out-of-band, protecting against a compromised server performing a man-in-the-middle attack. Signal computes safety numbers by combining both parties’ identity keys and phone numbers (or ACIs) through a series of SHA-512 iterations and encoding the result as a 60-digit decimal string, displayed in five-digit groups. Users compare this string by reading it aloud or scanning each other’s QR codes. Identity trust decisions live in SignalBaseIdentityKeyStore and IdentityTable. When an identity key changes (e.g., the remote party reinstalled Signal), the app marks the session as needing verification and surfaces a “safety number changed” notification.

Development

Internals

X3DH: session establishment

Key bundles

The X3DH handshake

Double Ratchet Algorithm

The two ratchets

Symmetric-key ratchet

Diffie-Hellman ratchet

Message key derivation

Pre-keys

One-time EC prekeys

Signed prekeys

Kyber (post-quantum) prekeys

Sender keys for group messaging

Sealed sender

How it works

Session management in Android

Safety numbers and fingerprint verification

​X3DH: session establishment

​Key bundles

​The X3DH handshake

​Double Ratchet Algorithm

​The two ratchets

Symmetric-key ratchet

Diffie-Hellman ratchet

​Message key derivation

​Pre-keys

​One-time EC prekeys

​Signed prekeys

​Kyber (post-quantum) prekeys

​Sender keys for group messaging

​Sealed sender

​How it works

​Session management in Android

​Safety numbers and fingerprint verification

X3DH: session establishment

Key bundles

The X3DH handshake

Double Ratchet Algorithm

The two ratchets

Message key derivation

Pre-keys

One-time EC prekeys

Signed prekeys

Kyber (post-quantum) prekeys

Sender keys for group messaging

Sealed sender

How it works

Session management in Android

Safety numbers and fingerprint verification