axum_gate/hashing/
mod.rs

1//! Password hashing and verification services.
2//!
3//! This module provides secure password hashing functionality using industry-standard
4//! algorithms. The primary implementation uses Argon2, which is recommended by security
5//! experts for password hashing due to its resistance to both brute-force and side-channel
6//! attacks.
7//!
8//! # Key Components
9//!
10//! - [`HashingService`] - Service for hashing and verifying passwords
11//! - [`HashedValue`] - Represents a hashed password with algorithm metadata
12//! - [`argon2`] - Argon2 algorithm implementation with secure defaults
13//!
14//! # Quick Start
15//!
16//! ```rust
17//! use axum_gate::hashing::{HashingService, argon2::Argon2Hasher};
18//! use axum_gate::verification_result::VerificationResult;
19//!
20//! let hasher = Argon2Hasher::new_recommended().unwrap();
21//!
22//! // Hash a password
23//! let hashed = hasher.hash_value("user_password").unwrap();
24//! println!("Hashed password: {}", hashed);
25//!
26//! // Verify a password
27//! let result = hasher.verify_value("user_password", &hashed).unwrap();
28//! assert_eq!(result, VerificationResult::Ok);
29//! ```
30//!
31//! # Security Features
32//!
33//! - **Argon2id algorithm** - Recommended by password hashing competition
34//! - **Configurable parameters** - Memory cost, time cost, and parallelism
35//! - **Built-in salt generation** - Each password gets a unique random salt
36//! - **Constant-time verification** - Prevents timing attacks
37//! - **Development vs production profiles** - Fast hashing in debug builds, secure in release
38//!
39//! # Performance Considerations
40//!
41//! The hashing service automatically adjusts parameters based on build configuration:
42//! - **Debug builds**: Fast parameters for development efficiency
43//! - **Release builds**: Secure parameters for production security
44//! - **Custom parameters**: Override via `Argon2Hasher::with_params()`
45
46pub mod argon2;
47mod hashing_service;
48
49pub use hashing_service::HashingService;
50
51pub mod errors;
52pub use errors::{HashingError, HashingOperation};
53
54/// A hashed value produced by password hashing algorithms.
55///
56/// This type represents the output of cryptographic password hashing functions,
57/// typically containing the algorithm identifier, parameters, salt, and hash in
58/// a standardized format.
59///
60/// ## Format
61///
62/// For Argon2id hashes, the format follows the PHC (Password Hashing Competition) standard:
63/// ```text
64/// $argon2id$v=19$m=65536,t=3,p=1$<salt>$<hash>
65/// ```
66///
67/// Where:
68/// - `argon2id` - Algorithm identifier
69/// - `v=19` - Algorithm version
70/// - `m=65536,t=3,p=1` - Memory cost, time cost, parallelism parameters
71/// - `<salt>` - Base64-encoded random salt
72/// - `<hash>` - Base64-encoded password hash
73///
74/// ## Security Properties
75///
76/// - **Self-contained**: Includes all information needed for verification
77/// - **Salt included**: Each hash has a unique random salt to prevent rainbow table attacks
78/// - **Parameter embedded**: Hash contains the parameters used, enabling verification
79/// - **Future-proof**: Format supports algorithm upgrades and parameter changes
80///
81/// ## Usage
82///
83/// ```rust
84/// use axum_gate::hashing::{argon2::Argon2Hasher, HashingService, HashedValue};
85///
86/// let hasher = Argon2Hasher::new_recommended().unwrap();
87/// let hashed: HashedValue = hasher.hash_value("my_password").unwrap();
88///
89/// // The hashed value is self-contained and can be stored directly
90/// println!("Hashed password: {}", hashed);
91///
92/// // Later, verify against the stored hash
93/// use axum_gate::verification_result::VerificationResult;
94/// let result = hasher.verify_value("my_password", &hashed).unwrap();
95/// assert_eq!(result, VerificationResult::Ok);
96/// ```
97///
98/// ## Storage Considerations
99///
100/// - **Database storage**: Store as TEXT/VARCHAR with sufficient length (≥100 characters recommended)
101/// - **No additional encoding needed**: The string is already in a safe, printable format
102/// - **Indexing**: Generally should not be indexed as hashes are not used for lookups
103/// - **Migration**: Hash format changes require re-hashing passwords during user login
104pub type HashedValue = String;
axum_gate/hashing/mod.rs

axum_gate/hashing/
mod.rs
