Crate auths_pairing_protocol

Expand description

Transport-agnostic pairing protocol for the auths identity system.

This crate implements the cryptographic pairing protocol that allows cross-device identity linking. It is intentionally free of transport dependencies (no axum, tower-http, mdns-sd, reqwest) so that mobile apps can use it with their own transport layer.

§Curve choice

The device’s long-term signing curve (Ed25519 or P-256, carried via the curve wire field on PairingResponse) is independent of the ephemeral ECDH curve used for key agreement.

We use P-256 ECDH unconditionally, regardless of signing curve. Ephemeral keys are generated fresh per session (p256::ecdh::EphemeralSecret::random), never reused, and have zero cryptographic relationship to the device’s long-term signing seed. There is no “signing-curve-to-ECDH-curve mapper” and no need for one.

Why P-256 for ECDH:

P-256 is the workspace default curve, already a dependency for signing.
iOS Secure Enclave is P-256 exclusively; Android StrongBox supports P-256 only for EC.
Removes the X25519 dependency and the 32-byte pubkey ambiguity (X25519 and Ed25519 both produce 32-byte keys).
Constant-time P-256 ECDH via the p256 crate (RustCrypto, audited).

See docs/architecture/cryptography.md → Wire-format Curve Tagging for the workspace-wide curve-agnosticism rule.

Re-exports§

pub use envelope::Envelope;
pub use envelope::EnvelopeError;
pub use envelope::EnvelopeSession;
pub use envelope::MAX_MESSAGES_PER_SESSION;
pub use envelope::Open;
pub use envelope::Sealed;
pub use sas::TransportKey;
pub use sas::decrypt_from_transport;
pub use sas::derive_sas;
pub use sas::derive_transport_key;
pub use sas::format_sas_emoji;
pub use sas::format_sas_numeric;
pub use subkey_chain::SubkeyChain;
pub use subkey_chain::SUBKEY_CHAIN_V1_DOMAIN;
pub use subkey_chain::SubkeyChainError;
pub use subkey_chain::build_binding_message_v1;
pub use subkey_chain::verify_subkey_chain;
pub use types::*;

Modules§

domain_separation: HKDF info registry for the pairing protocol (fn-129.T3).
envelope: SecureEnvelope — AEAD-wrapped session payloads (fn-129.T7).
sas: SAS (Short Authentication String) derivation and transport encryption.
subkey_chain: Per-pairing subkey chains (auths-device-subkey-v1).
types

Structs§

CompletedPairing: Result of a successfully completed pairing exchange (initiator side).
Confirmed: User has confirmed the SAS matches on both devices. Ready to finalize.
Init: Initial state: pairing token generated, no response received yet.
Paired: Pairing complete. The CompletedPairing extractor returns the cryptographic material.
PairingFlow: Typed pairing flow. The type parameter tracks which state the flow is in; methods are available only in the appropriate state.
PairingProtocol: Transport-agnostic pairing protocol state machine.
PairingResponse: A response to a pairing request from the responding device.
PairingSession: Ephemeral keypair for a pairing session.
PairingToken: A pairing token for initiating cross-device identity linking.
Responded: Response received and cryptographically verified; SAS + transport key derived. Awaiting user’s visual SAS confirmation.
ResponderResult: Result of a successful pairing response (responder side).
SasMatch: Zero-sized proof that the user visually compared both SAS outputs and confirmed they match. The only constructor is SasMatch::user_confirmed_visual_match; callers cannot forge one without having seen both SAS arrays.

Enums§

CurveTag: Wire-format curve tag for the pairing response.
KemSlot: fn-129.T10: post-quantum KEM slot advertised by the initiator.
ProtocolError: Protocol-level errors for the pairing exchange.

Functions§

normalize_short_code: Normalize a short code: uppercase, strip spaces/dashes.
respond_to_pairing: Responder-side helper: create a response from a received token.