hap_crypto/lib.rs
1//! HomeKit Accessory Protocol pairing **cryptography**.
2//!
3//! This crate covers Milestones 2 and 3 (M2, M3) of the `hap-rust` roadmap. It
4//! is currently an empty skeleton: the public API lands in the M2/M3
5//! implementation plans.
6//!
7//! # Scope
8//!
9//! - **M2 — Pair Setup (SRP-6a).** The controller proves knowledge of the
10//! accessory's 8-digit setup code without sending it, using SRP-6a (RFC 5054,
11//! 3072-bit group, SHA-512), HKDF-SHA512 key derivation, ChaCha20-Poly1305
12//! for the encrypted sub-TLVs, and an Ed25519 long-term keypair (`LTPK`).
13//! - **M3 — Pair Verify (X25519 + Ed25519).** Establishes a fresh session from
14//! an existing pairing via X25519 ephemeral ECDH and Ed25519 signatures
15//! verified against the stored `LTPK`, deriving the directional session keys
16//! (`Control-Read` / `Control-Write`).
17//!
18//! We never implement cryptographic primitives — AEAD, HKDF, SHA-512, Ed25519,
19//! and X25519 come from vetted crates; SRP big-integer math from a vetted
20//! bigint crate. We implement the *protocols* on top. The primitive provider is
21//! selected in the M2 plan and pinned in `[workspace.dependencies]` then.
22//!
23//! Correctness is established by byte-for-byte cross-verification of every
24//! SRP-6a intermediate value and every pairing message against captured
25//! `aiohomekit` traces and the HAP spec's SRP test vectors, plus interoperable
26//! pairing against real accessories and negative-path tests. See `CLAUDE.md`
27//! ("Crypto verification") for why this project does **not** gate crypto
28//! publishes on external review.
29//!
30//! Depends on [`hap_tlv8`] (pairing messages are TLV8).
31
32#![forbid(unsafe_code)]
33
34pub mod aead;
35mod error;
36mod kdf;
37mod keys;
38mod pair_setup;
39mod pair_verify;
40mod srp;
41mod tlv_types;
42mod x25519;
43
44pub use error::{CryptoError, Result};
45pub use keys::{verify_ed25519, ControllerKeypair};
46pub use pair_setup::{AccessoryPairing, PairSetupClient, PairSetupStep};
47pub use pair_verify::{PairVerifyClient, PairVerifyStep, SessionKeys};
48pub use x25519::{x25519_shared, EphemeralKeypair};