Skip to content

docs(signal-protocol): document the pluggable X25519 key agreement #479

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jlucaso1 merged 2 commits into from
Aug 7, 2026
Merged

docs(signal-protocol): document the pluggable X25519 key agreement #479

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
98a8e2b
docs(signal-protocol): document the pluggable X25519 key agreement
claude Aug 6, 2026
746335d
docs(signal-protocol): fix agreement-per-turn claim, tighten prose
claude Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions advanced/signal-protocol.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -982,6 +982,18 @@ pub fn derive_keys(secret_input: &[u8]) -> (RootKey, ChainKey, InitialPQRKey) {

Location: `wacore/libsignal/src/protocol/ratchet.rs:18-39`

### X25519 Key Agreement
Comment thread
jlucaso1 marked this conversation as resolved.
Outdated

Every DH step in session setup, and every ratchet turn, goes through this — `RootKey::create_chain` calls it once per turn, which in an alternating conversation is per message:
Comment thread
jlucaso1 marked this conversation as resolved.
Outdated
Comment thread
jlucaso1 marked this conversation as resolved.
Outdated

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

Location: `wacore/libsignal/src/core/curve.rs`

As of PR #1218, the agreement routes through the same pluggable crypto-provider trait as the other primitives on this page (`SignalCryptoProvider`, overridden via `set_crypto_provider` in `wacore/libsignal/src/crypto/provider.rs`) instead of calling the X25519 implementation directly. The default is this crate's own implementation and cannot fail. A substituted backend can refuse the operation; that surfaces as `CurveError::AgreementFailed` and, through `SignalProtocolError`, as `KeyAgreementFailed` — a refusal is treated as a local failure and takes priority over the MAC-based decrypt verdicts (`InvalidMessage`, `BadMac`) rather than being reported as message corruption.
Comment thread
jlucaso1 marked this conversation as resolved.
Outdated
Comment thread
jlucaso1 marked this conversation as resolved.
Outdated
Comment thread
jlucaso1 marked this conversation as resolved.
Outdated

## PreKey Management

Pre-keys enable asynchronous session establishment in the Signal Protocol. whatsapp-rust manages pre-key generation and upload to match WhatsApp Web's behavior.
Expand Down