Skip to main content

hofmann_rfc/
lib.rs

1//! # hofmann-rfc
2//!
3//! Rust implementation of three layered IETF RFCs for password-authenticated
4//! key exchange:
5//!
6//! - **RFC 9380** — Hash-to-Elliptic-Curves (Simplified SWU, `expand_message_xmd`)
7//! - **RFC 9497** — Oblivious Pseudorandom Functions (OPRF), base mode
8//! - **RFC 9807** — OPAQUE asymmetric PAKE protocol
9//!
10//! ## Supported Cipher Suites
11//!
12//! | Suite | Curve | Hash | Element Size | Scalar Size | Hash Output |
13//! |---|---|---|---|---|---|
14//! | P256-SHA256 | NIST P-256 | SHA-256 | 33 bytes | 32 bytes | 32 bytes |
15//! | P384-SHA384 | NIST P-384 | SHA-384 | 49 bytes | 48 bytes | 48 bytes |
16//! | P521-SHA512 | NIST P-521 | SHA-512 | 67 bytes | 66 bytes | 64 bytes |
17//! | ristretto255-SHA512 | ristretto255 | SHA-512 | 32 bytes | 32 bytes | 64 bytes |
18//!
19//! ## Quick Start: OPAQUE Registration + Authentication
20//!
21//! ```rust
22//! use hofmann_rfc::opaque::config::OpaqueConfig;
23//! use hofmann_rfc::opaque::{OpaqueClient, OpaqueServer};
24//!
25//! let config = OpaqueConfig::for_testing();
26//! let mut rng = rand::thread_rng();
27//!
28//! // --- Server setup ---
29//! let server = OpaqueServer::generate(&config, &mut rng);
30//! let client = OpaqueClient::new(&config);
31//!
32//! // --- Registration ---
33//! let reg_state = client.create_registration_request(b"password", &mut rng);
34//! let reg_response = server
35//!     .create_registration_response(&reg_state.request, b"user@example.com")
36//!     .unwrap();
37//! let record = client
38//!     .finalize_registration(&reg_state, &reg_response, None, None, &mut rng)
39//!     .unwrap();
40//!
41//! // --- Authentication ---
42//! let auth_state = client.generate_ke1(b"password", &mut rng);
43//! let ke2_result = server.generate_ke2(
44//!     None, &record, b"user@example.com", &auth_state.ke1, None, &mut rng,
45//! ).unwrap();
46//! let auth_result = client.generate_ke3(&auth_state, None, None, &ke2_result.ke2).unwrap();
47//! let session_key = server.server_finish(&ke2_result.server_auth_state, &auth_result.ke3).unwrap();
48//!
49//! assert_eq!(auth_result.session_key, session_key);
50//! ```
51//!
52//! ## Module Organization
53//!
54//! - [`common`] — Byte-level utilities (I2OSP, concat, XOR, constant-time equality)
55//! - [`elliptic_curve`] — [`GroupSpec`](elliptic_curve::GroupSpec) trait and curve implementations
56//! - [`oprf`] — RFC 9497 OPRF cipher suite ([`OprfCipherSuite`](oprf::OprfCipherSuite))
57//! - [`opaque`] — RFC 9807 OPAQUE protocol ([`OpaqueClient`](opaque::OpaqueClient),
58//!   [`OpaqueServer`](opaque::OpaqueServer))
59//!
60//! ## Security
61//!
62//! This library has **not** been formally audited. Use at your own risk in
63//! production systems. All MAC comparisons use constant-time equality, and
64//! sensitive state (`ClientAuthState`, `ClientRegistrationState`,
65//! `ServerAuthState`, `AuthResult`, `RegistrationRecord`) is zeroized on drop.
66
67pub mod common;
68pub mod elliptic_curve;
69pub mod opaque;
70pub mod oprf;
71pub mod recovery;