wpa_next/lib.rs
1//! # wpa-next
2//!
3//! A hybrid post-quantum resistant Wi-Fi security protocol prototype.
4//!
5//! `wpa-next` implements a two-stage handshake that combines **X25519 ECDH**
6//! (classical) with **ML-KEM-768** (FIPS 203, post-quantum) and merges both
7//! shared secrets through **HKDF-SHA-384**. It also solves the practical
8//! problem of transmitting large post-quantum keys over 802.11 management
9//! frames via a custom **Layer 2 fragmentation** protocol with a
10//! **HMAC-based DoS-mitigation cookie**.
11//!
12//! ## Security model
13//!
14//! The hybrid design means an adversary must break **both** primitives to
15//! recover the session key:
16//!
17//! - X25519 provides ~128-bit classical security (hard today)
18//! - ML-KEM-768 provides ~180-bit post-quantum security (hard for quantum computers)
19//!
20//! ## Quick start
21//!
22//! ```rust,no_run
23//! use wpa_next::network::{AccessPoint, Station};
24//!
25//! // Create AP and Station with their MAC addresses
26//! let mut ap = AccessPoint::new([0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF]).unwrap();
27//! let station = Station::new([0x11, 0x22, 0x33, 0x44, 0x55, 0x66]).unwrap();
28//!
29//! // Stage 1 — Station sends its X25519 public key
30//! let fast_link = station.build_fast_link_frame().unwrap();
31//! let cookie = ap.process_fast_link_frame(&fast_link, 0xDEADBEEF).unwrap();
32//!
33//! // Stage 2 — Station encapsulates against AP's ML-KEM key and fragments
34//! let ap_mlkem_pk = ap.mlkem_public_key_bytes();
35//! let ap_x25519_pk = ap.x25519_public_key_bytes().unwrap();
36//! let station_x25519_pk = station.x25519_public_key_bytes().unwrap();
37//!
38//! let (pq_frames, station_pq_ss) = station
39//! .build_pq_fragments(&ap_mlkem_pk, 0xDEADBEEF, &cookie)
40//! .unwrap();
41//!
42//! // AP processes fragments one at a time
43//! let mut ap_session_key = None;
44//! for frame in &pq_frames {
45//! ap_session_key = ap
46//! .process_fragment(frame, &[0x11, 0x22, 0x33, 0x44, 0x55, 0x66], &station_x25519_pk)
47//! .unwrap();
48//! }
49//!
50//! // Station completes with X25519 ECDH
51//! let station_key = station.complete_handshake(&ap_x25519_pk, station_pq_ss).unwrap();
52//! let ap_key = ap_session_key.unwrap();
53//!
54//! // Both sides now hold the same 256-bit session key
55//! assert!(ap_key.ct_eq(&station_key));
56//! ```
57//!
58//! ## Modules
59//!
60//! - [`crypto`] — cryptographic primitives: X25519, ML-KEM-768, HKDF combiner, cookie
61//! - [`network`] — frame structures, Layer 2 fragmentation, AP and Station state machines
62//!
63//! ## Feature flags
64//!
65//! This crate has no optional features. All functionality is always available.
66//!
67//! ## ⚠ Research prototype
68//!
69//! This crate is a **research prototype** — it has not been independently
70//! audited for production use in actual wireless deployments.
71
72#![forbid(unsafe_code)]
73#![warn(missing_docs)]
74#![warn(clippy::all)]
75
76/// Cryptographic primitives: X25519 ECDH, ML-KEM-768 (FIPS 203), HKDF-SHA384 hybrid combiner, and HMAC cookie.
77pub mod crypto;
78/// Frame structures, Layer 2 fragmentation, and the AP / Station protocol state machines.
79pub mod network;
80
81// Re-export the most commonly used types at the crate root for convenience.
82pub use crypto::{
83 CryptoError, MlKemKeyPair, SecretBytes, SessionKey, X25519KeyPair,
84 HMAC_LEN, MLKEM_CT_LEN, MLKEM_PK_LEN, SESSION_KEY_LEN, X25519_PK_LEN,
85};
86pub use network::{
87 AccessPoint, FastLinkFrame, FragmentHeader, FragmentedPQFrame, NetworkError, Station,
88 FRAG_PAYLOAD_MAX, MLKEM_PK_FRAG_COUNT,
89};
90
91#[cfg(test)]
92mod tests;