Docs · How-to
Prove who you're talking to.
Two devices, six groups of four characters. If they match, the keys on both ends are the same keys — no relay rewrote them.
Know the number
Once QERYX arrives, both devices will derive the safety number for every session, in three forms: six groups of four, a longer eight-group form, and an emoji fingerprint if you prefer to compare pictures.
A1B2-C3D4-E5F6-0718-293A-4B5C
FORMAT SPECIMEN — YOUR NUMBER IS DERIVED PER SESSION
Compare it out loud
The comparison runs in person, or over a channel you already trust: both devices must derive the same digits. The app compares in constant time; so should you — check every group, not just the first.
One number on two screens.
Your device and your peer’s each derive it from the session. If they match, your keys agree end to end — an interceptor cannot show you the same number.
Your safety number: BF4B-945F-A4B5-7A1E-D4D9-7C20
In the app: Q-Ratchet root key + both peers’ ML-DSA-87 public keys → HKDF-SHA512 → 16 bytes; the short form renders 12 of them as six groups of four hex characters.KTS-QUORUM SPEC
Know what a match proves
The number is derived with HKDF-SHA512 over the session root key and both peers' ML-DSA-87 identity public keys, sorted so both devices compute the same bytes. The short form renders 12 of those bytes as six groups of four hex characters; the full form renders 16 bytes as eight groups.
A match means both devices hold the same session root and the same identity keys — the handshake you ran is the handshake your peer ran. A mismatch means the two devices were handed different identity keys. Stop, delete the session, and re-entangle in person.
Behind the number: the key log
Identity keys are also appended to KTS, an append-only key transparency log: a 2-of-3 multi-witness quorum that starts dormant — all three ML-DSA-87 slots and all three external Ed25519 auditor slots hold placeholder keys, so no cosignature is carried and no witness check runs yet. Every root, until the witnesses enroll, is signed by one operator ML-DSA-87 key, which your device verifies against a SHA-384 anchor compiled into the app and cross-checks peer-to-peer through gossiped log roots. Enrolling a witness takes a new app release, by design. Identity signatures are ML-DSA-87 (FIPS 204).
Verifying at first contact, before a session exists
During the in-person connect ceremony the witness is computed over the two ML-DSA-87 identity public keys alone — the session root is deliberately excluded, because each side has just bootstrapped its own handshake. Disagreement there means the relay handed the two devices different identity keys, not a session-state artifact.
04The number changed — what to do next
Act when the number changes.
My peer's number changed — is that an attack?
Not necessarily. The number changes when identity keys rotate — a reinstall or a new device does that legitimately. Treat it as unverified again: ask your peer what happened, then re-verify. If nothing changed on their side, stop and re-entangle in person.
Do I have to verify every conversation?
Every session is X25519 + ML-KEM-1024 hybrid-encrypted whether you verify or not. Verification removes the last assumption — that the key bundle the relay served you belongs to your peer. For anything sensitive, verify.
Why hex groups instead of words?
Four-character hex groups survive being read across languages and noisy channels, and they map one-to-one onto the derived bytes — what you read aloud is the cryptographic value itself, not an encoding of an encoding.