aescrypt_rs/aliases.rs
1//! # Secure-Gate Type Aliases
2//!
3//! This module provides type aliases for secure memory management using [`secure-gate`](https://github.com/Slurp9187/secure-gate).
4//! All types in this module provide automatic zeroization on drop and prevent accidental secret exposure.
5//!
6//! ## Type Categories
7//!
8//! ### HMAC Primitives
9//! - [`HmacSha256`] - HMAC-SHA256 for session block and payload authentication
10//! - [`HmacSha512`] - HMAC-SHA512 for PBKDF2 key derivation
11//!
12//! ### Generic Secure Buffers
13//! - [`SpanBuffer<N>`] - Generic secure stack buffer for any size `N`
14//!
15//! ### Semantic Fixed-Size Types
16//! - [`AckdfHashState32`] - 32-byte ACKDF hash state
17//! - [`Block16`] - 16-byte AES block
18//! - [`Trailer32`] - 32-byte HMAC trailer (v0/v3)
19//!
20//! ### Dynamic Secrets
21//! - [`PasswordString`] - Secure password string wrapper
22//!
23//! ### Fixed-Size Secrets
24//! - [`Aes256Key32`] - 32-byte AES-256 key
25//! - [`EncryptedSessionBlock48`] - 48-byte encrypted session block
26//! - [`Iv16`] - 16-byte initialization vector
27//! - [`RingBuffer64`] - 64-byte ring buffer for streaming decryption
28//! - [`Salt16`] - 16-byte salt for KDF operations
29//! - [`SessionHmacTag32`] - 32-byte session block HMAC tag
30//!
31//! ## Usage
32//!
33//! All secure types require scoped `.with_secret()` or `.with_secret_mut()` to access
34//! the underlying data, ensuring no accidental secret exposure.
35
36use secure_gate::dynamic_alias;
37use secure_gate::fixed_alias;
38
39// ─────────────────────────────────────────────────────────────────────────────
40// HMAC primitives — available via `aliases::*`
41// ─────────────────────────────────────────────────────────────────────────────
42use hmac::Hmac;
43use sha2::{Sha256, Sha512};
44
45pub type HmacSha256 = Hmac<Sha256>;
46pub type HmacSha512 = Hmac<Sha512>;
47
48// ─────────────────────────────────────────────────────────────────────────────
49// SpanBuffer — generic secure stack buffer (direct alias to secure-gate's Fixed)
50// ─────────────────────────────────────────────────────────────────────────────
51pub type SpanBuffer<const N: usize> = secure_gate::Fixed<[u8; N]>;
52
53// Semantic sub-types — compile-time safe
54pub type AckdfHashState32 = SpanBuffer<32>;
55pub type Block16 = SpanBuffer<16>; // one AES block
56pub type Trailer32 = SpanBuffer<32>; // v0/v3 HMAC trailer
57
58// ─────────────────────────────────────────────────────────────────────────────
59// Dynamic secrets
60// ─────────────────────────────────────────────────────────────────────────────
61dynamic_alias!(pub PasswordString, String);
62
63// ─────────────────────────────────────────────────────────────────────────────
64// Fixed-size concrete secrets — alphabetical order
65// ─────────────────────────────────────────────────────────────────────────────
66fixed_alias!(pub Aes256Key32, 32); // session key, HMAC key
67fixed_alias!(pub EncryptedSessionBlock48, 48); // encrypted session IV + key
68fixed_alias!(pub Iv16, 16); // public IV, session IV
69fixed_alias!(pub RingBuffer64, 64); // streaming decryption ring buffer
70fixed_alias!(pub Salt16, 16); // PBKDF2/ACKDF salt
71fixed_alias!(pub SessionHmacTag32, 32); // session block HMAC