Signal Protocol Implementation

​

Overview

​

Architecture

• wacore/libsignal/ - Platform-agnostic Signal Protocol core (Rust port of libsignal)
• src/store/signal*.rs - WhatsApp-specific storage integration with Diesel/SQLite

​

Key Components

wacore/libsignal/src/
├── protocol/
│   ├── session_cipher.rs      # Encryption/decryption for 1:1 messages
│   ├── group_cipher.rs        # Encryption/decryption for group messages
│   ├── ratchet.rs            # Double Ratchet implementation
│   ├── sender_keys.rs        # Sender Key protocol for groups
│   └── state/                # Session state management
└── crypto/
    ├── aes_cbc.rs            # AES-256-CBC for message content
    ├── aes_gcm.rs            # AES-GCM for media encryption
    └── hash.rs               # HKDF and HMAC primitives

​

Double ratchet protocol

​

Session Initialization

// Alice initiates the session (sender)
pub fn initialize_alice_session<R: Rng + CryptoRng>(
    parameters: &AliceSignalProtocolParameters,
    csprng: &mut R,
) -> Result<SessionState>

// Bob receives the session (recipient)
pub fn initialize_bob_session(
    parameters: &BobSignalProtocolParameters
) -> Result<SessionState>

1. Compute shared secrets from ephemeral key exchanges
2. Derive root key and chain key using HKDF-SHA256:
   HKDF(discontinuity_bytes || DH1 || DH2 || DH3 [|| DH4])
   → (RootKey[32], ChainKey[32], PQRKey[32])
   
3. Initialize sender and receiver chains

​

Message Encryption

// From wacore/libsignal/src/protocol/session_cipher.rs:65-183
pub async fn message_encrypt(
    ptext: &[u8],
    remote_address: &ProtocolAddress,
    session_store: &mut dyn SessionStore,
    identity_store: &mut dyn IdentityKeyStore,
) -> Result<CiphertextMessage>

1. Load current session state
2. Get sender chain key and derive message keys:
   let (message_keys_gen, next_chain_key) = chain_key.step_with_message_keys();
   let message_keys = message_keys_gen.generate_keys();
   // message_keys contains: cipher_key, mac_key, iv
   
3. Encrypt plaintext with AES-256-CBC:
   aes_256_cbc_encrypt_into(ptext, message_keys.cipher_key(), 
                            message_keys.iv(), &mut buf)
   
4. Create SignalMessage with MAC for authentication
5. Advance chain key and save session state

• SignalMessage: Standard encrypted message
• PreKeySignalMessage: Includes prekey bundle for session establishment

​

Message Decryption

// From wacore/libsignal/src/protocol/session_cipher.rs:292-363
pub async fn message_decrypt_signal<R: Rng + CryptoRng>(
    ciphertext: &SignalMessage,
    remote_address: &ProtocolAddress,
    session_store: &mut dyn SessionStore,
    identity_store: &mut dyn IdentityKeyStore,
    csprng: &mut R,
) -> Result<Vec<u8>>

1. Try current session state first
2. If MAC verification fails, try previous (archived) sessions
3. Derive/retrieve message keys for the counter
4. Verify MAC:
   ciphertext.verify_mac(&their_identity_key, &local_identity_key, 
                         message_keys.mac_key())
   
5. Decrypt with AES-256-CBC
6. Promote successful session to current if needed

​

Chain key ratcheting

pub struct ChainKey {
    key: [u8; 32],
    index: u32,
}

impl ChainKey {
    pub fn step_with_message_keys(self) -> Result<(MessageKeyGenerator, ChainKey)> {
        let message_key_gen = MessageKeyGenerator::new(self.key, self.index);
        let next_chain_key = self.next_chain_key()?;
        Ok((message_key_gen, next_chain_key))
    }
}

​

Chain key overflow protection

// 1:1 chain keys (ratchet/keys.rs)
pub fn next_chain_key(&self) -> crate::protocol::Result<Self> {
    Ok(Self {
        key: self.calculate_base_material(Self::CHAIN_KEY_SEED),
        index: self.index.checked_add(1).ok_or_else(|| {
            SignalProtocolError::InvalidState(
                "next_chain_key",
                "chain key index overflow (u32::MAX)".to_string(),
            )
        })?,
    })
}

// Group sender chain keys (sender_keys.rs)
let new_iteration = self.iteration.checked_add(1).ok_or_else(|| {
    SignalProtocolError::InvalidState(
        "sender_chain_key_next",
        "Sender chain is too long".into(),
    )
})?;

​

Forward Jumps

// wacore/libsignal/src/protocol/consts.rs
pub const MAX_FORWARD_JUMPS: usize = 2_000;       // peer sessions + group sender keys
pub const MAX_FORWARD_JUMPS_SELF: usize = 25_000; // sessions with your own other devices

// wacore/libsignal/src/protocol/session_cipher.rs
const fn forward_jump_limit(is_self: bool) -> usize {
    if is_self { MAX_FORWARD_JUMPS_SELF } else { MAX_FORWARD_JUMPS }
}

if jump > forward_jump_limit(state.session_with_self()?) {
    return Err(SignalProtocolError::InvalidMessage(
        original_message_type,
        "message from too far into the future",
    ));
}

​

DM device fanout

• Recipient devices receive the actual message content
• Own other devices (your other linked devices) receive a DeviceSentMessage wrapper containing the message plus the destination JID, so your other devices can display the sent message in the correct chat

​

Device resolution

1. Local registry first — the client checks the local device registry via get_devices_from_registry() for both the recipient and own account. A network fetch (get_user_devices) is only triggered on a cache miss, avoiding unnecessary LID-migration side effects.
2. Hosted device filtering — devices flagged as hosted (via is_hosted()) are filtered out, matching WA Web’s DBDeviceListFanout exclusion.
3. Sender device exclusion — the exact sender device is removed from the list so ensure_e2e_sessions never creates a self-session. This matches WA Web’s isMeDevice check in getFanOutList.
4. Self-DM deduplication — when sending to your own account, the recipient and own device lists overlap. A HashSet-based dedup pass (matching WA Web’s Map keyed by toString) removes duplicates.

// Build device list — local registry first, network on miss
let mut recipient_cached = self.get_devices_from_registry(&recipient_bare).await;
if recipient_cached.is_none() {
    let _ = self.get_user_devices(std::slice::from_ref(&to)).await;
    recipient_cached = self.get_devices_from_registry(&recipient_bare).await;
}

// Filter hosted devices, exclude sender, dedup for self-DMs
all_dm_jids.retain(|j| !j.is_hosted());
all_dm_jids.retain(|j| !is_sender);
// HashSet dedup for self-DM overlap

​

Device partitioning

pub(crate) fn partition_dm_devices(
    all_devices: Vec<Jid>,
    own_jid: &Jid,
    own_lid: Option<&Jid>,
) -> PartitionedDmDevices

pub(crate) struct PartitionedDmDevices {
    devices: Vec<Jid>,
    recipient_count: usize,
}

impl PartitionedDmDevices {
    // recipient + own, sender excluded
    pub(crate) fn valid_devices(&self) -> &[Jid] {
        &self.devices
    }

    // recipient devices only
    pub(crate) fn recipient_devices(&self) -> &[Jid] {
        &self.devices[..self.recipient_count]
    }

    // own non-sender devices only
    pub(crate) fn own_other_devices(&self) -> &[Jid] {
        &self.devices[self.recipient_count..]
    }
}

​

Sender device exclusion

fn is_exact_dm_sender_device(device_jid: &Jid, own_jid: &Jid, own_lid: Option<&Jid>) -> bool {
    (device_jid.is_same_user_as(own_jid) && device_jid.device == own_jid.device)
        || own_lid.is_some_and(|lid|
            device_jid.is_same_user_as(lid) && device_jid.device == lid.device
        )
}

​

Own device recognition

pub fn matches_user_or_lid(&self, user: &Jid, lid: Option<&Jid>) -> bool {
    self.is_same_user_as(user) || lid.is_some_and(|l| self.is_same_user_as(l))
}

​

DmStanzaRequest and ResolvedDmDevices

pub struct DmStanzaRequest<'a> {
    pub own_jid: &'a Jid,
    pub account: Option<&'a wa::ADVSignedDeviceIdentity>,
    pub to: &'a Jid,
    pub message: &'a wa::Message,
    pub message_id: &'a str,
    pub edit: Option<&'a crate::types::message::EditAttribute>,
    pub extra_nodes: &'a [Node],
    /// The already-partitioned fan-out. Borrowed, not owned: the caller's
    /// per-recipient memo hands out the same `Arc` on every repeat send, so
    /// neither the device list nor its phash is rebuilt here.
    pub devices: &'a ResolvedDmDevices,
    pub pre_encoded: Option<&'a [u8]>,
}

pub struct ResolvedDmDevices { /* partitioned devices + OnceLock<CompactString> phash + OnceLock<DmSignalAddressing> */ }

impl ResolvedDmDevices {
    /// Partitions `all_devices` into recipient devices and own companions,
    /// dropping the sending device itself.
    pub fn new(all_devices: Vec<Jid>, own_jid: &Jid, own_lid: Option<&Jid>) -> Self;

    /// Every device the stanza encrypts for, in partition order.
    pub fn devices(&self) -> &[Jid];

    /// The DM phash over the sent device set: a memo hit is an inline copy.
    pub fn phash(&self) -> Option<CompactString>;

    /// The memoized Signal addressing, if a send has resolved it yet.
    pub fn signal_addressing(&self) -> Option<&DmSignalAddressing>;

    /// Memoizes `addressing`, or hands back what an earlier send already
    /// memoized. Refused (and handed back to the caller) when `addressing`
    /// doesn't carry exactly one address per `devices()` entry.
    pub fn signal_addressing_or_init(
        &self,
        addressing: DmSignalAddressing,
    ) -> Result<&DmSignalAddressing, DmSignalAddressing>;
}

​

Session preflight and the 406 case

​

PreparedDmStanza

pub struct PreparedDmStanza {
    pub node: Node,
    /// Locally computed phash from the sent device set. Not sent on the
    /// wire (WA Web only sends phash for groups). Used by the caller to
    /// compare against the server's ACK phash for device-list drift detection.
    pub phash: Option<CompactString>,
}

​

PN→LID session migration

​

Signal address resolution

​

DM wire namespace vs. Signal session addressing

pub(crate) async fn resolve_dm_wire_jid(&self, to: &Jid) -> Jid {
    if self.is_lid_migrated().await {
        return self.resolve_encryption_jid(to).await.into_non_ad();
    }
    let bare = to.to_non_ad();
    if bare.is_lid() {
        self.swap_pn_lid_namespace(&bare).await.unwrap_or(bare)
    } else {
        bare
    }
}

• Migrated account (Client::is_lid_migrated() is true): behaves exactly like before — the wire namespace upgrades PN → LID whenever a mapping is known.
• Unmigrated account: DMs stay on PN even with a cached LID mapping. A caller-supplied LID with a known PN mapping is mapped back to the PN chat; a LID with no cached mapping is sent as-is (there is no reverse LID→PN network resolution, matching WA Web).

1. The persisted Device.lid_migrated flag (see Storage — DeviceStore), set once from the primary’s pair-success <client-props> (isChatDbLidMigrated) or from a lid_migration_mapping_sync_message protocol message pushed to the primary’s own companions (self-only — see Authentication — one-to-one LID migration state).
2. The lid_one_on_one_migration_enabled ab prop, as a fallback for sessions paired before the flag existed. The first observation of this prop being on also latches the persisted flag, so the account doesn’t flap back to PN addressing before the next props fetch.

​

Why migration is needed

​

Proactive migration at LID discovery

// src/client/lid_pn.rs
pub(crate) async fn migrate_signal_sessions_on_lid_discovery(&self, pn: &str, lid: &str) {
    for device_id in 0..=99u16 {
        // Read from signal_cache (authoritative over backend)
        // If PN session exists and no LID session → move session to LID via cache
        // If both exist → delete the stale PN session from cache
        // Identity keys are migrated independently of sessions
    }
    // Flush migrated state to backend so it survives restarts
    self.signal_cache.flush(backend.as_ref()).await;
}

​

On-the-fly migration during decryption

1. Look up the PN for the sender’s LID
2. Attempt to migrate PN sessions to LID via the signal cache (same cache-first logic as proactive migration)
3. Retry decryption with the migrated session (already in the cache — no reload needed)
4. If DuplicateMessage occurs during post-migration retry, it is silently ignored
5. Fall back to retry receipt only if migration does not resolve the issue

​

Login-time session check

• LID session exists — no action needed
• PN session only — logged; migration deferred to first message via on-the-fly path
• No session — will be established on first message exchange

// src/client/sessions.rs
pub(crate) async fn establish_primary_phone_session_immediate(&self) -> Result<()> {
    // Checks LID session → logs PN-only state → defers migration to message path
}

​

Sender keys (group encryption)

​

Sender key address normalization

// Decryption path (src/message.rs) — normalize before group_decrypt
let sender_for_sk = info.source.sender.to_non_ad();
let sender_address = sender_for_sk.to_protocol_address();
let sender_key_name = SenderKeyName::from_jid(&info.source.chat, &sender_address);

// SKDM storage path (src/message.rs) — normalize before process_sender_key_distribution_message
let sender_bare = sender_jid.to_non_ad();
let sender_address = sender_bare.to_protocol_address();
let sender_key_name = SenderKeyName::from_jid(&group_jid, &sender_address);

​

Sender key distribution

// From wacore/libsignal/src/protocol/group_cipher.rs:283-336
pub async fn create_sender_key_distribution_message<R: Rng + CryptoRng>(
    sender_key_name: &SenderKeyName,
    sender_key_store: &mut dyn SenderKeyStore,
    csprng: &mut R,
) -> Result<SenderKeyDistributionMessage>

• Chain ID: Random 31-bit identifier for this sender key session
• Iteration: Message counter (starts at 0)
• Chain Key: 32-byte seed for deriving message keys
• Signing Key: Ed25519 public key for message authentication

​

Group Encryption

// From wacore/libsignal/src/protocol/group_cipher.rs:53-116
pub async fn group_encrypt<R: Rng + CryptoRng>(
    sender_key_store: &mut dyn SenderKeyStore,
    sender_key_name: &SenderKeyName,
    plaintext: &[u8],
    csprng: &mut R,
) -> Result<SenderKeyMessage>

1. Load sender key state for the group
2. Derive message keys from current chain key
3. Encrypt with AES-256-CBC
4. Sign message with Ed25519 private key
5. Advance chain key

​

Group Decryption

// From wacore/libsignal/src/protocol/group_cipher.rs:202-212
pub async fn group_decrypt(
    skm_bytes: &[u8],
    sender_key_store: &mut dyn SenderKeyStore,
    sender_key_name: &SenderKeyName,
) -> Result<Vec<u8>>

// From wacore/libsignal/src/protocol/group_cipher.rs:218-223
pub async fn group_decrypt_shared(
    skm_bytes: Bytes,
    sender_key_store: &mut dyn SenderKeyStore,
    sender_key_name: &SenderKeyName,
) -> Result<Vec<u8>>

1. Parse SenderKeyMessage
2. Look up sender key state by chain ID
3. Verify Ed25519 signature
4. Derive message keys for iteration (handling out-of-order)
5. Decrypt with AES-256-CBC into a plaintext buffer sized exactly to the ciphertext length

​

Unknown device detection

1. After successful skmsg decrypt — if the sender device is not in the registry, the decrypted message is still processed and delivered normally. Signal decryption success already proves the sender holds a valid session key, so discarding the message would only add latency via an unnecessary retry round-trip. A background device sync is triggered to update the local device registry.
2. After a NoSenderKeyState error — if the sender device is unknown, the retry reason is upgraded from NoSession to UnknownCompanionNoPrekey

• Online: the client immediately invalidates the cached device registry for the user and fires a background usync request to refresh the device list
• Offline (during offline sync): the unknown device’s user JID is batched into a PendingDeviceSync set, which is flushed after offline sync completes (see Deferred device sync)

// src/message.rs — simplified flow
async fn handle_unknown_device_sync(&self, info: &Arc<MessageInfo>) {
    let user_jid = info.source.sender.to_non_ad();
    if !self.pending_device_sync.add(&user_jid) {
        return; // already queued, dedup
    }
    if info.is_offline {
        return; // batched for deferred flush
    }
    // Online: immediate sync
    self.invalidate_device_cache(&user_jid.user).await;
    self.get_user_devices(&[user_jid]).await.ok();
}

​

Retry receipt from unknown group device

// wacore/src/protocol/retry.rs
pub fn should_drop_unknown_device_retry(keys_present: bool, device_known: bool) -> bool {
    !keys_present && !device_known
}

​

Immutable sender key loading

​

Sender key existence check

​

Per-device sender key tracking

pub struct PreparedGroupStanza {
    pub node: Node,
    /// The devices this send reports as holding the sender key — the
    /// distribution target set, not just the ones SKDM-encryption actually
    /// succeeded for. Empty when no distribution occurred.
    pub skdm_devices: Vec<Jid>,
    /// The phash on the stanza, so the caller can compare it against the
    /// one the server echoes back on the ack.
    pub phash: Option<CompactString>,
}

• Group path: After send_node() succeeds, the caller uses the skdm_devices list from PreparedGroupStanza to call set_sender_key_status(group, devices, true). No re-resolution needed.
• Status path: A late-init boolean tracks whether full distribution occurred. The sender key tracking is only updated after the status stanza is successfully sent.
• Error recovery: If prepare_group_stanza fails with NoSenderKeyState, all sender key device tracking for that group is cleared and the send is retried with full distribution.
• Sender key rotation: On rotateKey, the Signal sender key is also deleted for forward secrecy (matching WhatsApp Web’s deleteGroupSenderKeyInfo), and all device tracking is cleared via reset_sender_key_device_tracking — a DB-first clear with a cold-mark fallback (see below).
• Group <modify> notification (number/LID migration): A w:gp2 <modify> notification (a participant’s number or LID changed) unconditionally force-rotates the own group sender key and invalidates both the persisted and in-memory group metadata cache, matching WhatsApp Web’s modifyParticipantInfo (rotateKey: true). The next send regenerates and redistributes a fresh sender key against the current participant list instead of risking a stale entry for the migrated device. See Client::force_rotate_own_sender_key, src/handlers/notification/groups.rs.
• Admin revoke: When you send an admin revoke (RevokeType::Admin), the client treats it as an ordinary group message for distribution purposes. It uses the same incremental-targeting diff described above, own-device exception included, instead of a message-type-specific override (#1278). Earlier versions forced full redistribution on every admin revoke, on the mistaken assumption that the server required it. On a warm group, this could turn a small revoke payload into one <enc> node per device. A cold group (no cached key, or mid-rotation) still distributes to every device, same as a cold ordinary send.

1. Loads the per-device sender key map — first checking the in-memory cache, falling back to the database via get_sender_key_devices
2. Resolves all current group participant devices
3. Computes the diff — only devices with has_key=false or not yet tracked receive the SKDM
4. Passes the targeted device list to prepare_group_stanza via the skdm_target_devices parameter

​

Parallelized group encrypt fan-out

​

In-memory sender key device cache

pub(crate) struct SenderKeyDeviceCache {
    inner: Cache<String, Arc<SenderKeyDeviceMap>>,
}

• Time-to-idle eviction: The cache uses TTI semantics (default: 1 hour, 500 entries), so entries for inactive groups are automatically evicted while frequently-used groups stay cached
• Pre-parsed, pre-indexed maps: Database rows are parsed into a SenderKeyDeviceMap struct that provides O(1) lookups by user and device ID, avoiding per-query string parsing
• Single-flight initialization: The get_or_init method uses PortableCache’s single-flight get_with — if multiple concurrent group sends for the same group trigger a cache miss simultaneously, only one database read executes and all callers share the result
• Explicit invalidation: The cache is invalidated when sender key state changes (rotation, error recovery, retry failures) so stale data is never served

// Atomic get-or-init: concurrent callers for the same group
// share the single database read result
let cached_map = self
    .sender_key_device_cache
    .get_or_init(group_jid, async {
        let db_rows = pm.get_sender_key_devices(group_jid).await.unwrap_or_default();
        Arc::new(SenderKeyDeviceMap::from_db_rows(&db_rows))
    })
    .await;

pub(crate) struct SenderKeyDeviceMap {
    /// user → (device_id → has_key)
    devices: HashMap<Arc<str>, HashMap<u16, bool>>,
    /// Users with at least one has_key=false device
    forgotten_users: HashSet<Arc<str>>,
}

​

Phash validation for stale device list detection

1. Before sending, the client obtains the locally computed phash — from the stanza phash attribute for group/status messages, or from PreparedDmStanza.phash for DMs
2. A PhashWaiter (expected hash, target JID, whether to also invalidate the group cache) is registered for the message ID via register_phash_waiter — a map entry, not a channel or a task
3. The message stanza is sent to the server
4. When the server’s ack for that message ID arrives, the read loop compares its phash attribute against the expected value inline, with no task involved
5. On a match the entry is just dropped; on a mismatch the client spawns a task to invalidate caches — so a send only pays for a task in the uncommon case, not on every send (#1116)

// src/send.rs — simplified phash validation flow

// Each branch populates SendBranchOutput::ack_phash from its own prepared
// stanza — group and DM both read it off `prepared.phash` (the group phash
// is also on the wire; the DM phash is computed locally only). This is what
// the ack is later compared against.
let branch_output = SendBranchOutput {
    ack_phash: prepared.phash,
    // ...other fields
};

// On DM phash mismatch:
if !jid.is_group() && !jid.is_status_broadcast() {
    client.invalidate_device_cache(&jid.user).await;
    if let Some(own_pn) = &client.persistence_manager.get_device_snapshot().pn {
        client.invalidate_device_cache(&own_pn.user).await;
    }
}

​

WA Web phash parity (v0.6)

• Full device set, every send. The group phash is now computed over the complete resolved participant device set plus the sending device on every send — not just the devices that received an SKDM in that stanza. Warm sends (which distribute no new SKDM) now pass the full resolved set via the all_devices_for_phash parameter to prepare_group_stanza, so the phash matches the server’s view even when the SKDM target set is empty. Status broadcasts keep their prior phash behavior.
• Standard base64 alphabet. The phash now encodes with the standard base64 alphabet (+ / /) instead of URL-safe (- / _), matching WA Web and whatsmeow.

​

Cryptographic Primitives

​

AES-256-CBC (message content)

pub fn aes_256_cbc_encrypt_into(
    plaintext: &[u8],
    key: &[u8],      // 32 bytes
    iv: &[u8],       // 16 bytes
    output: &mut Vec<u8>,
) -> Result<()>

​

Thread-Local Buffers

thread_local! {
    static ENCRYPTION_BUFFER: RefCell<EncryptionBuffer> = ...;
    static DECRYPTION_BUFFER: RefCell<EncryptionBuffer> = ...;
}

// Usage in session_cipher.rs:99-111
let ctext = ENCRYPTION_BUFFER.with(|buffer| {
    let mut buf_wrapper = buffer.borrow_mut();
    let buf = buf_wrapper.get_buffer();
    aes_256_cbc_encrypt_into(ptext, message_keys.cipher_key(), 
                            message_keys.iv(), buf)?;
    let result = std::mem::take(buf);
    buf.reserve(EncryptionBuffer::INITIAL_CAPACITY);
    Ok::<Vec<u8>, SignalProtocolError>(result)
})?;

​

HKDF-SHA256

pub fn derive_keys(secret_input: &[u8]) -> (RootKey, ChainKey, InitialPQRKey) {
    let mut secrets = [0; 96];
    hkdf::Hkdf::<sha2::Sha256>::new(None, secret_input)
        .expand(b"WhisperText", &mut secrets)
        .expect("valid length");
    // Split into RootKey[32], ChainKey[32], PQRKey[32]
}

​

X25519 key agreement

pub fn calculate_agreement(&self, their_key: &PublicKey) -> Result<[u8; 32], CurveError>

​

PreKey Management

​

Configuration

// Via the Bot builder
Bot::builder()
    .with_wanted_pre_key_count(256) // smaller batches for embedded consumers
    // ...

// Or directly on a Client constructed by hand (before connect)
client.set_wanted_pre_key_count(256);

​

Pre-key ID counter and wrap-around

// Determine starting ID using both the persistent counter AND the store max
let max_id = backend.get_max_prekey_id().await?;
let start_id = if device_snapshot.next_pre_key_id > 0 {
    std::cmp::max(device_snapshot.next_pre_key_id, max_id + 1)
} else {
    // Migration: start from MAX(key_id) + 1
    max_id + 1
};

const MAX_PREKEY_ID: u32 = 16777215; // 2^24 - 1

// Wrap start ID into valid [1, MAX_PREKEY_ID] range
let start_id = ((raw_start as u64 - 1) % MAX_PREKEY_ID as u64) as u32 + 1;

// Each key ID in the batch is also wrapped
let pre_key_id = (((start_id as u64 - 1) + i as u64) % (MAX_PREKEY_ID as u64)) as u32 + 1;

// After upload, the persisted next_pre_key_id wraps too
let next_id = (((start_id as u64 - 1) + key_pairs_to_upload.len() as u64)
    % (MAX_PREKEY_ID as u64)) as u32 + 1;

​

Retry-receipt prekey marking

​

Force-refreshing pre-keys for device migration

// After restoring a session from another library
client.refresh_pre_keys().await?;

• Client::refresh_pre_keys_with_count(count) — same force-upload as refresh_pre_keys(), but with a caller-chosen batch size instead of the configured wanted_pre_key_count.
• Client::ensure_pre_keys() — a non-forced check-and-top-up: uploads only if the server-side pool is below the low-water mark, rather than unconditionally replacing it.

​

Digest key validation

<!-- Request -->
<iq xmlns="encrypt" type="get" to="s.whatsapp.net" id="...">
  <digest/>
</iq>

<!-- Response -->
<iq from="s.whatsapp.net" id="..." type="result">
  <digest>
    <registration>[4-byte BE registration ID]</registration>
    <type>[1-byte: 5]</type>
    <identity>[32-byte identity public key]</identity>
    <skey>
      <id>[3-byte BE signed pre-key ID]</id>
      <value>[32-byte signed pre-key public]</value>
      <signature>[64-byte signature]</signature>
    </skey>
    <list>
      <id>[3-byte BE prekey ID]</id>
      ...
    </list>
    <hash>[20-byte SHA-1 hash]</hash>
  </digest>
</iq>

1. Query the server for the key bundle digest via DigestKeyBundleSpec
2. If the server returns 404 (no record), trigger a full pre-key re-upload
3. If the server returns 406/503 or other errors, log and skip
4. On success, compare registration IDs
5. Load each pre-key referenced by the server and extract its public key
6. Compute a local SHA-1 digest over: identity public key + signed pre-key public + signed pre-key signature + all pre-key public keys
7. Compare the local hash against the server-provided hash

​

Signed pre-key rotation (RotateKeyJob)

• Checked once per connection. Spawned right after the startup pre-key upload during post-login init, so a slow or failing rotation IQ never delays the rest of login.
• Checked again on a ~6-hour keepalive maintenance tick for as long as the connection stays up (whatsapp-rust#1411). Before this, the connect-time check was the rotation’s only caller, so a process that paired once and never reconnected could hold a connection open past the 27-day cadence and never rotate at all. The keepalive pass re-checks connection_generation before rotating — a pass still queued against a connection that has since been retired (a reconnect landed first) no-ops instead of uploading against stale session state.
• Rotates once now - last_signed_pre_key_rotation_ms >= SIGNED_PRE_KEY_ROTATION_INTERVAL_MS (27 days). This matches the interval WA Web’s ROTATE_KEY task returns to its scheduler (WAWebTasksDefinitions, confirmed against a fresh captured WA Web bundle) and is not configurable — there is no A/B property behind the value, so a per-client override would only widen the public API for a number the official client hardcodes identically. rotate_signed_pre_key() remains the escape hatch for forcing a rotation out of band.
• A device upgraded in with the field at 0 gets a one-time baseline stamp (DeviceCommand::SetSignedPreKeyRotationBaseline) instead of rotating immediately, so its first rotation lands a full interval out.
• Single-flighted via Client::signed_pre_key_rotation_lock so overlapping post-login tasks (from reconnect churn) can’t run the rotate/upload/prune sequence concurrently; a losing task just no-ops for that check.

<iq xmlns="encrypt" type="set" to="s.whatsapp.net" id="...">
  <rotate>
    <skey>
      <id>[3-byte BE signed pre-key ID]</id>
      <value>[32-byte signed pre-key public]</value>
      <signature>[64-byte signature]</signature>
    </skey>
  </rotate>
</iq>

1. Compute new_id = current_id + 1, wrapping to 1 at the 24-bit border (same scheme as one-time pre-key IDs).
2. Stage the new key pair in the signed_prekeys backend table before upload — an already-staged candidate for that id is reused verbatim, so a retry after an ambiguous failure re-uploads the exact key the server may have already accepted instead of minting a different one under the same id.
3. Retain the outgoing (current) key in the backend table before upload, so once the server accepts the new key the old id’s decrypt window is already durable — no post-acceptance write can strand it.
4. Upload via the <rotate> IQ above.
5. On success, DeviceCommand::SetSignedPreKey atomically installs the new key pair, id, signature, and rotation timestamp. The now-redundant staged copy is dropped, and retained signed pre-keys are pruned (newest-id-first) to SIGNED_PRE_KEY_RETENTION (3 total: the current key + the 2 most recent rotated-out keys).

​

Re-pair pre-key healing (v0.6)

​

ADV companion identity validation

1. In-blob key: If ADVSignedDeviceIdentity.account_signature_key is present and non-empty, it is used directly.
2. Stored identity fallback: The server legitimately omits this field for a contact’s companion because the client already holds the contact’s primary (device 0) identity in the Signal identity store. When the field is absent, Client::load_account_identity loads it — reading through the SignalStoreCache so any unflushed mutations from the current session are visible. PreKeyFetchSpec::with_account_identities threads the pre-loaded map into wacore’s stateless prekey parser, keeping store access in the whatsapp-rust crate.

​

Storage Integration

src/store/
├── signal.rs               # SignalStore trait impl for Device (identity, session, prekey, sender key)
├── signal_adapter.rs       # SignalProtocolStoreAdapter — cache-backed adapter bridging wacore traits to libsignal traits
└── signal_cache.rs         # Re-export of wacore::store::signal_cache::SignalStoreCache

// SignalProtocolStoreAdapter reads/writes through the cache
#[async_trait]
impl SessionStore for SessionAdapter {
    async fn load_session(
        &self,
        address: &ProtocolAddress,
    ) -> Result<Option<SessionRecord>, SignalProtocolError> {
        // Returns cached SessionRecord object directly (no deserialization)
        // Cold load deserializes from backend bytes once and caches the object
        self.cache.get_session(&addr_str, &*device.backend).await
    }

    async fn store_session(
        &mut self,
        address: &ProtocolAddress,
        record: SessionRecord,  // Takes ownership — zero-cost move
    ) -> Result<(), SignalProtocolError> {
        // Stores the SessionRecord object in cache, marks dirty
        // Serialization happens only during flush()
        self.cache.put_session(&addr_str, record).await;
        Ok(())
    }
}

​

Flush scheduling: send vs. receive

• Send (DM/1:1 sessions) persists through a batched counter lease. SessionRecord reserves its outbound sender-chain counter SENDER_CHAIN_RESERVATION_BATCH (64) values at a time, via SessionRecord::reserve_sender_chain_counters. A send covered by an unexhausted lease is already durable — it only schedules the same coalesced write-behind as the receive path below. The send that exhausts the lease, roughly 1 in 64, raises the ceiling and flushes synchronously, before the stanza reaches the wire. If that flush fails, the send aborts instead of transmitting an advance it couldn’t save. Reusing an outbound counter reuses its message key and IV, so no counter can ever be used before its lease is durable. The lease field is local-only: it’s field 100 in the encoded SessionRecord, outside the vendored whatsapp.proto. By default (SessionRecord::deserialize), every load fast-forwards the sender chain to the lease ceiling, so a crash mid-lease can never re-derive a possibly-spent counter — the store-backed load path relaxes this only for a trusted reload, via the incarnation marker described below.
• Send (group and status sends) follows the same lease pattern as DMs. SenderKeyRecord reserves its outbound chain iteration SENDER_CHAIN_RESERVATION_BATCH (64) at a time via SenderKeyRecord::reserve_iterations, using the same field-100 local-only encoding and the same fast-forward-on-load recovery as SessionRecord. A send within an unexhausted lease rides the coalesced write-behind; only the send that raises the ceiling, roughly 1 in 64, flushes synchronously before the stanza reaches the wire. Status posts go through the same group-encrypt path and inherit this behavior; status reactions are a DM-branch send and always followed the DM lease instead. Production encryption (wacore::send::encrypt_group_message) delegates to the same group_encrypt primitive these guarantees live in, so there is exactly one sender-key encrypt/advance/store implementation — earlier, a second unguarded copy on the production path meant most warm group sends skipped the pre-wire flush entirely.
• Receive (live traffic, outside the offline-drain batcher) routes through a single-flight coalescing scheduler (src/signal_flush.rs) instead of flushing per stanza: a burst of receives folds into one flush per ~25ms window, retried with exponential backoff (up to a 5s cap) on backend failure. This is safe because a lost receive-side advance simply re-derives forward on the next message (the receiving chain derives CK_n → CK_n+1), and a consumed one-time prekey stays buffered until its session is durable — a crash inside the window is recoverable.

​

Clean reload vs. crash recovery

• A live SignalStoreCache generates one incarnation marker when it’s constructed. A reload that observes a matching marker proves the record came from this same live cache and was never lost to a crash, so it’s exact: the chain resumes at the next iteration instead of fast-forwarding.
• A reload with no marker, a different marker, or a malformed/duplicated marker is untrusted and keeps the conservative fast-forward — this covers process restarts, a freshly constructed cache, and any genuinely lossy discard.
• SignalStoreCache::clear_after_flush(), used by connection teardown, only evicts a store once it’s fully settled — no dirty, deleted, checked-out, or pending-wire-gate entries. Anything a concurrent write installs after the flush stays resident (and the incarnation stays put) until a later flush settles it; only an actual lossy discard rotates the marker.
• Direct Device stores hold one process-level incarnation in an OnceLock instead of a per-cache one. Since these stores synchronously await the backend write before returning ciphertext, a new Device wrapping the same backend in the same process is a clean, trusted reload; a process restart gets a fresh marker and stays conservative.

​

DH ratchet resets rebase the lease

​

Waiving the counter lease

let mut record = SessionRecord::from_components(components)?;
record.waive_counter_lease();

let mut record = SenderKeyRecord::from_components(components)?;
record.waive_counter_lease()?;

• The policy is the consumer’s, never inferred. Nothing about a record’s stored representation says whether a lease is in force — the same components can come from a consumer that wants the lease and one that does not — so this call has to happen on every load that should waive it, not just once. There is no build feature or store-shape heuristic that does it implicitly.
• This gives up a real guarantee. Message keys and IVs derive deterministically from the counter, so without the lease a crash between the encrypt and the write can reissue a counter and, with it, its (key, IV) pair. Only make this trade if persistence is synchronous and durable before the wire — the same property a direct Device store already has for itself, since it awaits the backend write before returning ciphertext (see store incarnation). SignalStoreCache’s trusted reload relies on a different, weaker guarantee — a matching live-cache incarnation, not synchronous durability, since its warm sends ride the coalesced write-behind — so don’t read the two as the same requirement.
• A reservation the record already carries still burns once. A record loaded from a snapshot written while the lease was in force may already have published counters below its ceiling; waiving doesn’t make that untrue. The call materializes that ceiling into the chain — archived states included, the same way into_components() already would — and then the lease is gone, so it only pays that cost once instead of on every subsequent export.
• An unadvanceable ceiling is handled differently per record, matching how their exports already differ: SessionRecord::waive_counter_lease() has no failure path — a chain too stale to fast-forward is dropped fail-closed, per session, without discarding the rest of the record. SenderKeyRecord has one shared chain rather than per-peer sessions, so dropping it isn’t a safe partial failure; waive_counter_lease() returns Err instead and leaves the record on its lease rather than dropping the ceiling and risking reissue.
• The default is unchanged. A record that never calls this keeps the lease, the wire gate, and the fast-forward-on-load exactly as documented above.

​

Record components

// wacore/libsignal/src/protocol/record_components.rs, re-exported from
// wacore/libsignal/src/protocol/mod.rs
pub use record_components::{
    PendingKeyExchangeComponents, PendingPreKeyComponents, SenderChainKeyComponents,
    SenderKeyRecordComponents, SenderKeyStateComponents, SenderMessageKeyComponents,
    SenderSigningKeyComponents, SessionChainComponents, SessionChainKeyComponents,
    SessionComponents, SessionMessageKeyComponents, SessionMessageKeyMaterial,
    SessionRecordComponents,
};

​

Session and sender-key shapes

pub struct SessionRecordComponents {
    pub current_session: Option<SessionComponents>,
    pub previous_sessions: Vec<SessionComponents>,
}

pub struct SessionComponents {
    pub session_version: Option<u32>,
    pub local_identity_public: Option<Vec<u8>>,
    pub remote_identity_public: Option<Vec<u8>>,
    pub root_key: Option<Vec<u8>>,
    pub previous_counter: Option<u32>,
    pub sender_chain: Option<SessionChainComponents>,
    pub receiver_chains: Vec<SessionChainComponents>,
    pub pending_key_exchange: Option<PendingKeyExchangeComponents>,
    pub pending_pre_key: Option<PendingPreKeyComponents>,
    pub remote_registration_id: Option<u32>,
    pub local_registration_id: Option<u32>,
    pub needs_refresh: Option<bool>,
    pub alice_base_key: Option<Vec<u8>>,
}

pub struct SessionChainComponents {
    pub sender_ratchet_key: Option<Vec<u8>>,
    pub sender_ratchet_key_private: Option<Vec<u8>>,
    pub chain_key: Option<SessionChainKeyComponents>,
    pub message_keys: Vec<SessionMessageKeyComponents>,
}

pub struct SenderKeyRecordComponents {
    pub states: Vec<SenderKeyStateComponents>,
}

pub struct SenderKeyStateComponents {
    pub key_id: u32,
    pub chain_key: SenderChainKeyComponents,           // { iteration: u32, seed: Vec<u8> }
    pub signing_key: SenderSigningKeyComponents,        // { public: Vec<u8>, private: Option<Vec<u8>> }
    pub message_keys: Vec<SenderMessageKeyComponents>,  // { iteration: u32, seed: Vec<u8> }
}

#[derive(Clone, Copy, PartialEq, Eq)]
pub enum SessionMessageKeyMaterial {
    Seed([u8; 32]),
    Derived {
        cipher_key: [u8; 32],
        mac_key: [u8; 32],
        iv: [u8; 16],
    },
}

impl SessionRecord {
    pub fn from_components(value: SessionRecordComponents) -> Result<Self, SignalProtocolError>;
    pub fn into_components(mut self) -> Result<SessionRecordComponents, SignalProtocolError>;
}
impl SenderKeyRecord {
    pub fn from_components(value: SenderKeyRecordComponents) -> Result<Self, SignalProtocolError>;
    pub fn into_components(mut self) -> Result<SenderKeyRecordComponents, SignalProtocolError>;
}

​

Import validation

• A sender chain (the local sending ratchet chain within a pairwise session — not to be confused with a group sender-key chain) must be structurally complete: ratchet public key present, a 32-byte ratchet private key, and a chain key with both its index and 32-byte secret set. An incomplete sender chain fails with SignalProtocolError::InvalidArgument; a session with no sender chain at all (e.g. one just received and not yet replied to) is fine and imports as sender_chain: None.
• A receiver chain must never carry sender_ratchet_key_private — receiver chains never own the remote party’s private key, so import fails if one is set. Symmetrically, projecting a persisted record into components always reports a receiver chain’s sender_ratchet_key_private as None, silently dropping any non-canonical private material a legacy record might contain, matching how the canonical reader already treats that field.
• Raw 32-byte public keys and canonically-serialized public keys (type byte + 32 bytes) are both accepted on import; whichever form was imported, into_components() always exports canonical serialization.

​

Export normalization

• Any durably reserved sender-chain counter range — see the counter-lease mechanics in Flush scheduling: send vs. receive — is advanced to its exclusive ceiling before export. Re-importing the exported components can’t reuse a counter value that was only reserved, not yet actually sent.
• A sender chain too stale to fast-forward past its reservation is dropped from the exported chain rather than aborting the whole export — the rest of the record (receiver chains, other archived sessions) still exports normally.
• SessionRecordComponents.previous_sessions is truncated to ARCHIVED_STATES_MAX_LENGTH (40) and SenderKeyRecordComponents.states is truncated to MAX_SENDER_KEY_STATES (5) — the same bounds the records themselves already enforce. See Protocol safety limits.

​

has_usable_sender_chain

impl SessionState {
    pub fn has_usable_sender_chain(&self) -> Result<bool, InvalidSessionError>;
}
impl SessionRecord {
    pub fn has_usable_sender_chain(&self) -> Result<bool, SignalProtocolError>;
}

​

Debug output redacts secrets

println!("{chain:?}");
// SessionChainKeyComponents { index: Some(7), key: <redacted> }

// `record: SessionRecord` loaded from your store
if record.has_usable_sender_chain()? {
    let components = record.into_components()?;
    println!("{:?}", components.current_session); // secrets redacted
}

​

Legacy session v1 interop

// wacore/libsignal/src/protocol/legacy_session.rs, re-exported from
// wacore/libsignal/src/protocol/mod.rs behind `legacy-session-interop`
pub use legacy_session::{
    LegacyIndexedSessionV1, LegacySessionBaseKeyRoleV1, LegacySessionChainCounterV1,
    LegacySessionChainKeyV1, LegacySessionChainRoleV1, LegacySessionChainV1,
    LegacySessionDispositionV1, LegacySessionFieldV1, LegacySessionIndexV1,
    LegacySessionInteropError, LegacySessionKeyPairV1, LegacySessionLocalContext,
    LegacySessionMessageKeyV1, LegacySessionPendingPreKeyV1, LegacySessionRatchetV1,
    LegacySessionRecordV1, LegacySessionUnrepresentableFieldV1, LegacySessionV1,
};

impl LegacySessionRecordV1 {
    pub fn from_indexed_sessions(
        sessions: Vec<LegacyIndexedSessionV1>,
    ) -> Result<Self, LegacySessionInteropError>;

    pub fn into_session_record(
        self,
        context: LegacySessionLocalContext,
    ) -> Result<SessionRecord, LegacySessionInteropError>;
}

impl SessionRecord {
    pub fn into_legacy_session_v1_operational(
        self,
    ) -> Result<LegacySessionRecordV1, LegacySessionInteropError>;
}

​

Security Considerations

​

Identity key trust

if !crate::protocol::storage::is_trusted_identity(
    identity_store,
    remote_address,
    &their_identity_key,
    Direction::Sending,
)
.await?
{
    return Err(SignalProtocolError::UntrustedIdentity(
        remote_address.clone(),
    ));
}

​

Self-only protocol message gating

• A spoofed app_state_sync_key_share from a peer would let an attacker inject an app-state encryption key, leading to attacker-controlled mutations of your contacts, blocklist, archive state, etc.
• A spoofed app_state_sync_key_request from a peer would make the client share its app-state encryption keys with an attacker instead of only with the account’s own companion devices.
• A spoofed history_sync_notification would point the client at attacker-supplied media for ingestion as your own history.

​

Duplicate message detection

if chain_index > counter {
    return match state.get_message_keys(their_ephemeral, counter)? {
        Some(keys) => Ok(keys),
        None => Err(SignalProtocolError::DuplicateMessage(chain_index, counter)),
    };
}

​

Log level discipline

• No private keys or secrets are ever logged — ChainKey, MessageKeys, and RootKey types do not expose their key bytes through logging
• Public keys appear only at warn/error levels — and only when something has gone wrong (untrusted identity, MAC failure)
• MAC key fingerprints are truncated — only the first 4 bytes (8 hex chars) are logged during MAC verification failures, not the full key:
  let mac_key_fingerprint: String = hex::encode(mac_key_bytes).chars().take(8).collect();
  
• Ratchet keys in debug logs — successful decryptions log the sender ratchet public key (never private) at debug level for diagnostics
• Pre-key operations use debug for routine operations and warn/info for exceptional conditions

​

Session state corruption

fn create_decryption_failure_log(
    remote_address: &ProtocolAddress,
    errs: &[SignalProtocolError],
    record: &SessionRecord,
    ciphertext: &SignalMessage,
) -> Result<String>

• All attempted session states
• Receiver chain information
• Message metadata (sender ratchet key, counter)

​

Protocol safety limits

​

Self-DM / sibling decryption recovery

​

Performance optimizations

​

Session object cache

// wacore/src/store/signal_cache.rs
enum SessionEntry {
    /// Arc so peek_session (retry / LID-migration checks) bumps a refcount
    /// instead of deep-cloning the record (KBs with archived states).
    Present(Arc<SessionRecord>),
    Absent,
    /// Taken by a destructive-update load; has_session treats as present.
    /// Carries enough identity to reject a stale owner — see
    /// "Cancellation-safe session checkouts" below.
    CheckedOut {
        had_session: bool,
        token: NonZeroU64,
    },
}

struct SessionStoreState {
    cache: HashMap<Arc<str>, SessionEntry>,  // Objects, not bytes
    dirty: HashSet<Arc<str>>,
    deleted: HashSet<Arc<str>>,
    incarnation: StoreIncarnation,
    checkout_generation: u64,
    next_checkout_token: u64,
}

// Sender keys use the same object-caching pattern
struct SenderKeyStoreState {
    cache: HashMap<Arc<str>, Option<SenderKeyRecord>>,  // Objects, not bytes
    dirty: HashSet<Arc<str>>,
}

// wacore/libsignal/src/protocol/storage/traits.rs
pub trait SessionStore {
    async fn store_session(
        &mut self,
        address: &ProtocolAddress,
        record: SessionRecord,  // Owned — zero-cost move, no clone
    ) -> Result<()>;
}

​

Cancellation-safe session checkouts

• commit(self) — stores the mutated record back through try_store_session_from_checkout, or
• discard(self) — releases a deliberately-rejected fresh (never-had-a-session) checkout without storing.

​

Unboxed identity and session hooks

• try_save_identity declines when nothing is cached for the address, so the caller reads the backend. Answering from an empty cache would report every identity as new.
• try_has_session declines when the cache cannot answer, rather than reporting “no session” and forcing a needless session rebuild.
• try_is_trusted_identity can always answer for the bundled adapter specifically, because its async is_trusted_identity is already the unconditional Ok(true) above. This is not a general license to short-circuit trust checks: a custom IdentityKeyStore whose async is_trusted_identity enforces a real policy must not copy this hook verbatim — returning Some(Ok(true)) unconditionally would let it bypass that policy. Such a store should return None unless it can decide synchronously without skipping any of its own trust logic.

// wacore/libsignal/src/protocol/storage/traits.rs
pub async fn is_trusted_identity<S: IdentityKeyStore + ?Sized>(
    store: &S,
    address: &ProtocolAddress,
    identity: &IdentityKey,
    direction: Direction,
) -> Result<bool> {
    match store.try_is_trusted_identity(address, identity, direction) {
        Some(answer) => answer,
        None => store.is_trusted_identity(address, identity, direction).await,
    }
}

​

Arc previous sessions

// wacore/libsignal/src/protocol/state/session.rs
pub struct SessionRecord {
    current_session: Option<SessionState>,
    /// Wrapped in Arc so cloning is O(1). Only mutated on rare paths via Arc::make_mut.
    previous_sessions: Arc<Vec<SessionStructure>>,
}

​

Chain key buffer reuse

fn write_chain_key(field: &mut Option<bytes::Bytes>, key: &[u8]) {
    if let Some(existing) = field.take()
        && existing.len() == key.len()
        && let Ok(mut owned) = existing.try_into_mut()
    {
        owned.copy_from_slice(key);
        *field = Some(owned.freeze());
        return;
    }
    *field = Some(bytes::Bytes::copy_from_slice(key));
}