mytheclipse_crypto/lib.rs
1//! # mytheclipse-crypto
2//!
3//! Low-level security helpers that are easy to get wrong when hand-rolled:
4//!
5//! - **Argon2id** password hashing & verification (`password` feature), with
6//! RFC 9106-ish parameters.
7//! - **AES-256-GCM** authenticated encryption with a fresh random nonce per
8//! operation (`encryption` feature).
9//! - **JWT** (HS256) / **Paseto** v4 local token generation & validation (`tokens`
10//! feature).
11//! - **Key rotation** via [`KeyRing`]: decryption/verification tries the current
12//! key then a list of previous keys.
13//!
14//! Nothing in the crate owns long-lived key material; keys are passed in as
15//! bytes/keys by the caller and the caller is responsible for storage. Each
16//! primitive is small enough to reason about in one screen.
17//!
18//! ## Example
19//!
20//! ```no_run
21//! use mytheclipse_crypto::{PasswordHasher, Encryptor, TokenSigner};
22//!
23//! // Hash & verify a password.
24//! let hasher = PasswordHasher::new();
25//! let hash = hasher.hash("hunter2").unwrap();
26//! assert!(hasher.verify(&hash, "hunter2"));
27//!
28//! // Encrypt & decrypt a blob.
29//! let key = [0u8; 32];
30//! let enc = Encryptor::new(&key);
31//! let (nonce, ct) = enc.encrypt(b"secret message");
32//! let plain = enc.decrypt(&nonce, &ct).unwrap();
33//! assert_eq!(plain, b"secret message");
34//!
35//! // Sign & verify a JWT.
36//! let signer = TokenSigner::new("super-secret-key");
37//! let token = signer
38//! .sign(&serde_json::json!({ "sub": "u1" }), std::time::Duration::from_secs(3600))
39//! .unwrap();
40//! let claims = signer.verify(&token).unwrap();
41//! assert_eq!(claims["sub"], "u1");
42//! ```
43
44pub mod key_registry;
45pub mod key_ring;
46
47#[cfg(feature = "password")]
48pub mod password;
49
50#[cfg(feature = "encryption")]
51pub mod encryption;
52
53#[cfg(feature = "tokens")]
54pub mod token;
55
56#[cfg(feature = "derivation")]
57pub mod hkdf;
58#[cfg(feature = "paseto")]
59pub mod paseto;
60
61#[cfg(feature = "password")]
62pub use password::PasswordHasher;
63
64#[cfg(feature = "encryption")]
65pub use encryption::{AeadError, Encryptor};
66
67#[cfg(feature = "tokens")]
68pub use token::{Claims, TokenError, TokenSigner};
69
70#[cfg(feature = "paseto")]
71pub use paseto::{PasetoClaims, PasetoSigner};
72
73pub use key_registry::TypedKeyRegistry;
74pub use key_ring::KeyRing;
75
76#[cfg(feature = "derivation")]
77pub use hkdf::HkdfKeyDeriver;
78
79/// Errors returned across mytheclipse-crypto primitives.
80#[non_exhaustive]
81#[derive(Debug)]
82pub enum CryptoError {
83 /// Password hashing or verification failed.
84 Password(String),
85 /// Authenticated encryption / decryption failed.
86 Encryption(String),
87 /// Token generation or validation failed.
88 Token(String),
89 /// Key material is invalid for the requested operation.
90 Key(String),
91}
92
93impl std::fmt::Display for CryptoError {
94 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
95 match self {
96 Self::Password(msg) => write!(f, "password error: {msg}"),
97 Self::Encryption(msg) => write!(f, "encryption error: {msg}"),
98 Self::Token(msg) => write!(f, "token error: {msg}"),
99 Self::Key(msg) => write!(f, "key error: {msg}"),
100 }
101 }
102}
103
104impl std::error::Error for CryptoError {}
105
106/// The fixed AES-256-GCM nonce length (96 bits) in bytes.
107pub const NONCE_LEN: usize = 12;
108/// The fixed AES-256-GCM key length in bytes.
109pub const KEY_LEN: usize = 32;