Skip to main content

yang_base/action/auth/
password.rs

1//! 密码哈希与校验的受控执行边界。
2//!
3//! Argon2 是刻意的内存困难算法,直接运行在异步运行时上会阻塞工作线程;
4//! [`PasswordEngine`] 把所有哈希/校验运算收敛到 `spawn_blocking`,并用信号量限制
5//! 全局并发上限,避免认证洪泛耗尽阻塞线程池。并发上限等参数由构造函数注入,
6//! 不读取任何应用配置。
7
8use argon2::password_hash::{Error as PasswordHashError, PasswordHash, SaltString};
9use argon2::{Argon2, PasswordHasher, PasswordVerifier};
10use rand_core::OsRng;
11use std::sync::Arc;
12use tokio::sync::Semaphore;
13use yang_base::BaseError;
14
15/// 等时校验使用的固定 dummy PHC 哈希。
16///
17/// 算法与参数(argon2id / v=19 / m=19456,t=2,p=1)与 `Argon2::default()` 的产出
18/// 完全一致,保证「账号不存在」与「密码错误」两条路径执行相同成本的 Argon2 运算;
19/// 参数若漂移(例如升级 argon2 默认值),单元测试会拒绝启动并提示重新生成。
20/// 该常量不对应任何真实账号,仅为拉齐认证入口的响应时间分布。
21const DUMMY_PASSWORD_HASH: &str = "$argon2id$v=19$m=19456,t=2,p=1$KeT08Pv9+LVzDxDOmS18Tw$f1ITNKuxgUMXlkesQPqcEpIDZlQZ8FOm1wadvq9lxiU";
22
23/// 密码哈希执行器:Argon2 运算 + 受控并发上限。
24#[derive(Clone)]
25pub struct PasswordEngine {
26    permits: Arc<Semaphore>,
27}
28
29impl PasswordEngine {
30    /// 创建执行器;`max_concurrency` 为同时进行的 Argon2 运算上限,必须大于 0。
31    pub fn new(max_concurrency: usize) -> Result<Self, BaseError> {
32        if max_concurrency == 0 {
33            return Err(BaseError::ConfigError(
34                "argon2_max_concurrency 必须大于 0".to_string(),
35            ));
36        }
37        Ok(Self {
38            permits: Arc::new(Semaphore::new(max_concurrency)),
39        })
40    }
41
42    /// 计算密码的 Argon2 哈希(PHC 字符串格式)。
43    pub async fn hash(&self, password: &str) -> Result<String, BaseError> {
44        let password = password.to_owned();
45        self.run_blocking(move || {
46            let salt = SaltString::generate(&mut OsRng);
47            Argon2::default()
48                .hash_password(password.as_bytes(), &salt)
49                .map(|value| value.to_string())
50                .map_err(|_| BaseError::Unknown("密码哈希失败".to_string()))
51        })
52        .await
53    }
54
55    /// 校验密码明文与已存储的 PHC 哈希是否匹配。
56    pub async fn verify(&self, password: &str, encoded: &str) -> Result<bool, BaseError> {
57        let password = password.to_owned();
58        let encoded = encoded.to_owned();
59        self.run_blocking(move || {
60            let parsed = PasswordHash::new(&encoded)
61                .map_err(|_| BaseError::Unknown("数据库中的密码哈希格式无效".to_string()))?;
62            match Argon2::default().verify_password(password.as_bytes(), &parsed) {
63                Ok(()) => Ok(true),
64                Err(PasswordHashError::Password) => Ok(false),
65                Err(_) => Err(BaseError::Unknown("密码校验失败".to_string())),
66            }
67        })
68        .await
69    }
70
71    /// 等时校验:账号记录缺失时也对内置 dummy 哈希执行一次完整的 Argon2 校验。
72    ///
73    /// 认证入口(如登录)在「用户不存在」与「密码错误」之间必须保持一致的响应时间
74    /// 与响应错误,否则时间差会泄露用户名是否存在(时序枚举旁路)。传入
75    /// `Some(真实哈希)` 时语义与 [`Self::verify`] 完全一致;传入 `None` 时走同一条
76    /// 校验代码路径运算内置 dummy 哈希,并恒返回 `Ok(false)`——dummy 哈希
77    /// 不对应任何真实账号,即使碰巧匹配也不能视为认证通过。
78    pub async fn verify_or_dummy(
79        &self,
80        password: &str,
81        encoded: Option<&str>,
82    ) -> Result<bool, BaseError> {
83        match encoded {
84            Some(encoded) => self.verify(password, encoded).await,
85            // 结果故意丢弃:None 分支只为拉齐耗时,语义上恒为校验失败。
86            None => self
87                .verify(password, DUMMY_PASSWORD_HASH)
88                .await
89                .map(|_| false),
90        }
91    }
92
93    async fn run_blocking<T>(
94        &self,
95        operation: impl FnOnce() -> Result<T, BaseError> + Send + 'static,
96    ) -> Result<T, BaseError>
97    where
98        T: Send + 'static,
99    {
100        let permit = Arc::clone(&self.permits)
101            .acquire_owned()
102            .await
103            .map_err(|_| BaseError::Unknown("密码执行器已关闭".to_string()))?;
104        tokio::task::spawn_blocking(move || {
105            let _permit = permit;
106            operation()
107        })
108        .await
109        .map_err(|error| BaseError::Unknown(format!("密码任务执行失败: {error}")))?
110    }
111}
112
113#[cfg(test)]
114mod tests {
115    use super::*;
116
117    #[tokio::test]
118    async fn password_hash_round_trip() {
119        let engine =
120            PasswordEngine::new(1).unwrap_or_else(|error| panic!("密码执行器应构建成功: {error}"));
121        let encoded = engine
122            .hash("correct-horse-battery-staple")
123            .await
124            .unwrap_or_else(|error| panic!("密码应成功哈希: {error}"));
125
126        assert!(engine
127            .verify("correct-horse-battery-staple", &encoded)
128            .await
129            .unwrap_or_else(|error| panic!("密码应成功校验: {error}")));
130        assert!(!engine
131            .verify("wrong-password", &encoded)
132            .await
133            .unwrap_or_else(|error| panic!("错误密码应得到 false: {error}")));
134        assert!(!encoded.contains("correct-horse-battery-staple"));
135    }
136
137    #[tokio::test]
138    async fn dummy_hash_parameters_match_engine_output() {
139        // 验证需求: 等时校验的前提是 dummy 哈希与真实哈希的 Argon2 参数一致,
140        // 否则两条路径仍有可分辨的耗时差。这里用引擎真实产出做基准逐段比对。
141        let engine =
142            PasswordEngine::new(1).unwrap_or_else(|error| panic!("密码执行器应构建成功: {error}"));
143        let real = engine
144            .hash("parameter-probe")
145            .await
146            .unwrap_or_else(|error| panic!("密码应成功哈希: {error}"));
147        // PHC 格式 $算法$v=版本$m=...,t=...,p=...$盐$哈希,前三段必须逐字相同。
148        let dummy_segments: Vec<&str> = DUMMY_PASSWORD_HASH.split('$').take(4).collect();
149        let real_segments: Vec<&str> = real.split('$').take(4).collect();
150        assert_eq!(
151            dummy_segments, real_segments,
152            "dummy 哈希参数已漂移,请用 PasswordEngine::hash 重新生成 DUMMY_PASSWORD_HASH"
153        );
154    }
155
156    #[tokio::test]
157    async fn verify_or_dummy_runs_full_pipeline_for_none() {
158        let engine =
159            PasswordEngine::new(1).unwrap_or_else(|error| panic!("密码执行器应构建成功: {error}"));
160        // None 分支必须走完整校验管线而非短路:若 dummy 哈希无法解析或未执行
161        // Argon2 运算,这里会报错而不是返回 Ok(false)。
162        assert!(!engine
163            .verify_or_dummy("any-password", None)
164            .await
165            .unwrap_or_else(|error| panic!("None 分支应走完整校验并返回 false: {error}")));
166        // dummy 哈希本身不认证任何密码。
167        assert!(!engine
168            .verify("any-password", DUMMY_PASSWORD_HASH)
169            .await
170            .unwrap_or_else(|error| panic!("dummy 哈希应能正常校验: {error}")));
171    }
172
173    #[tokio::test]
174    async fn verify_or_dummy_matches_verify_for_real_hash() {
175        let engine =
176            PasswordEngine::new(1).unwrap_or_else(|error| panic!("密码执行器应构建成功: {error}"));
177        let encoded = engine
178            .hash("real-password")
179            .await
180            .unwrap_or_else(|error| panic!("密码应成功哈希: {error}"));
181        assert!(engine
182            .verify_or_dummy("real-password", Some(&encoded))
183            .await
184            .unwrap_or_else(|error| panic!("正确密码应通过等时校验: {error}")));
185        assert!(!engine
186            .verify_or_dummy("wrong-password", Some(&encoded))
187            .await
188            .unwrap_or_else(|error| panic!("错误密码应校验失败: {error}")));
189    }
190
191    #[test]
192    fn zero_concurrency_is_rejected() {
193        assert!(matches!(
194            PasswordEngine::new(0),
195            Err(BaseError::ConfigError(message)) if message.contains("argon2_max_concurrency")
196        ));
197    }
198}