1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
//! Hardware-only AES-256-GCM and key/nonce generation.
//!
//! Every AES round and every GF(2^128) multiply executes as a CPU instruction
//! (`AES-NI`/`PCLMULQDQ` on `x86_64`, `ARMv8` AES/`PMULL` on `aarch64`); no
//! software cipher is compiled in. If the required hardware is absent,
//! construction fails with a typed error rather than degrading to table-based
//! AES.
//!
//! The crate exposes two modules:
//!
//! - [`aes_gcm`]: AES-256-GCM. [`aes_gcm::HardwareAes256Gcm`] owns boxed key
//! state; [`aes_gcm::HardwareAes256GcmKeyState`] owns allocation-free inline
//! key state; [`aes_gcm::HardwareAes256GcmIn`] places the key state in
//! caller-provided memory so the caller controls where keys and key-equivalent
//! state live (use [`aes_gcm::HardwareAes256Gcm::key_state_layout`] to size
//! and align the storage, [`aes_gcm::UninitKeyStateSlot`] to hand it over).
//! Default encryption generates a nonce and returns `ciphertext || tag ||
//! nonce`; default decryption parses the nonce from that envelope. All
//! handles zeroize key state on drop. The same module also provides
//! nonce-misuse-resistant AES-256-GCM-SIV (RFC 8452) through the parallel
//! [`aes_gcm::HardwareAes256GcmSiv`],
//! [`aes_gcm::HardwareAes256GcmSivKeyState`], and
//! [`aes_gcm::HardwareAes256GcmSivIn`] types (placed via
//! [`aes_gcm::SivUninitKeyStateSlot`]), built on the same hardware AES and
//! carryless-multiply backends with POLYVAL authentication and the same
//! default envelope API.
//! - [`random`]: a hardware AES-256-CTR key and nonce generator
//! ([`random::AesCtrKeyGenerator`]) with fork detection and CPU hardware-RNG
//! (`RDSEED`/`RNDRRS`) reseeding.
//!
//! Implementation details (the AES, GHASH, CTR, and fork-detection internals)
//! are private; only the high-level types above are part of the public API.
// The `hax` cfg excludes the RNG module from hax/F* extraction: its `RDSEED`/
// `RNDRRS` inline asm and `pthread_atfork` fn pointer are outside hax's
// importable subset, and it is independent of the AEAD composition being
// extracted. Normal builds and all other tooling compile it as usual.