uselesskey_hmac/lib.rs
1#![forbid(unsafe_code)]
2
3//! HMAC secret fixtures built on `uselesskey-core`.
4//!
5//! Generates HMAC-SHA256, HMAC-SHA384, and HMAC-SHA512 symmetric secrets
6//! for testing. Supports deterministic and random modes.
7//!
8//! # Usage
9//!
10//! The main entry point is the [`HmacFactoryExt`] trait, which adds the `.hmac()` method
11//! to [`Factory`](uselesskey_core::Factory).
12//!
13//! # Examples
14//!
15//! ```
16//! use uselesskey_core::Factory;
17//! use uselesskey_hmac::{HmacFactoryExt, HmacSpec};
18//!
19//! let fx = Factory::random();
20//! let kp = fx.hmac("my-service", HmacSpec::hs256());
21//! let secret = kp.secret_bytes();
22//! assert_eq!(secret.len(), 32);
23//! ```
24//!
25//! # Deterministic Mode
26//!
27//! Use deterministic mode for reproducible test fixtures:
28//!
29//! ```
30//! use uselesskey_core::{Factory, Seed};
31//! use uselesskey_hmac::{HmacFactoryExt, HmacSpec};
32//!
33//! let seed = Seed::from_env_value("test-seed").unwrap();
34//! let fx = Factory::deterministic(seed);
35//!
36//! // Same seed + label + spec = same secret
37//! let s1 = fx.hmac("issuer", HmacSpec::hs384());
38//! let s2 = fx.hmac("issuer", HmacSpec::hs384());
39//! assert_eq!(s1.secret_bytes(), s2.secret_bytes());
40//!
41//! // Different labels produce different secrets
42//! let s3 = fx.hmac("other", HmacSpec::hs384());
43//! assert_ne!(s1.secret_bytes(), s3.secret_bytes());
44//! ```
45//!
46//! # Available Specs
47//!
48//! | Spec | Algorithm | Secret Length |
49//! |------|-----------|--------------|
50//! | [`HmacSpec::hs256()`] | HMAC-SHA256 | 32 bytes |
51//! | [`HmacSpec::hs384()`] | HMAC-SHA384 | 48 bytes |
52//! | [`HmacSpec::hs512()`] | HMAC-SHA512 | 64 bytes |
53
54mod secret;
55mod spec;
56
57pub use secret::{DOMAIN_HMAC_SECRET, HmacFactoryExt, HmacSecret};
58pub use spec::HmacSpec;