Skip to main content

rullst_security/
recovery_codes.rs

1//! Subject-bound single-use recovery-code verifiers for MFA recovery flows.
2
3use hmac::{Hmac, KeyInit, Mac};
4use serde::{Deserialize, Serialize};
5use sha2::Sha256;
6use subtle::ConstantTimeEq;
7use zeroize::Zeroize;
8
9const CODE_ALPHABET: &[u8; 32] = b"ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
10const CODE_CHARACTERS: usize = 16;
11const MIN_PEPPER_BYTES: usize = 32;
12const MAX_CODES: usize = 20;
13const MAX_SUBJECT_BYTES: usize = 256;
14const DOMAIN: &[u8] = b"rullst.recovery-code.v1";
15
16type HmacSha256 = Hmac<Sha256>;
17
18#[derive(Debug, thiserror::Error, Clone, PartialEq, Eq)]
19#[non_exhaustive]
20pub enum RecoveryCodeError {
21    #[error("invalid recovery-code configuration: {0}")]
22    InvalidConfiguration(&'static str),
23    #[error("recovery-code pepper must contain at least 32 strong bytes")]
24    WeakPepper,
25    #[error("recovery-code verifier could not be initialized")]
26    CryptoInitialization,
27}
28
29/// Persist this verifier, never the corresponding plaintext recovery code.
30#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
31#[non_exhaustive]
32pub struct RecoveryCodeVerifier {
33    version: u8,
34    salt: [u8; 16],
35    digest: [u8; 32],
36}
37
38impl RecoveryCodeVerifier {
39    pub fn version(&self) -> u8 {
40        self.version
41    }
42}
43
44/// Plaintext codes and their storage-safe verifiers returned only at enrollment.
45///
46/// The plaintext vector is zeroized when this value is dropped. Render it once,
47/// then persist only the verifier vector.
48pub struct GeneratedRecoveryCodes {
49    plaintext: Vec<String>,
50    verifiers: Vec<RecoveryCodeVerifier>,
51}
52
53impl GeneratedRecoveryCodes {
54    pub fn plaintext(&self) -> &[String] {
55        &self.plaintext
56    }
57
58    pub fn verifiers(&self) -> &[RecoveryCodeVerifier] {
59        &self.verifiers
60    }
61
62    pub fn into_parts(mut self) -> (Vec<String>, Vec<RecoveryCodeVerifier>) {
63        (
64            std::mem::take(&mut self.plaintext),
65            std::mem::take(&mut self.verifiers),
66        )
67    }
68}
69
70impl Drop for GeneratedRecoveryCodes {
71    fn drop(&mut self) {
72        self.plaintext.zeroize();
73    }
74}
75
76/// Generates 80-bit recovery codes bound to one canonical application subject.
77pub fn generate_recovery_codes(
78    subject: impl Into<String>,
79    count: usize,
80    pepper: &[u8],
81) -> Result<GeneratedRecoveryCodes, RecoveryCodeError> {
82    let subject = subject.into();
83    validate_configuration(&subject, count, pepper)?;
84    let mut plaintext = Vec::with_capacity(count);
85    let mut verifiers = Vec::with_capacity(count);
86    for _ in 0..count {
87        let code = generate_code();
88        let normalized_code =
89            normalize_code(&code).ok_or(RecoveryCodeError::CryptoInitialization)?;
90        let salt = rand::random::<[u8; 16]>();
91        let digest = recovery_digest(&subject, &normalized_code, &salt, pepper)?;
92        plaintext.push(code);
93        verifiers.push(RecoveryCodeVerifier {
94            version: 1,
95            salt,
96            digest,
97        });
98    }
99    Ok(GeneratedRecoveryCodes {
100        plaintext,
101        verifiers,
102    })
103}
104
105/// Verifies without consuming. Prefer [`consume_recovery_code`] in login flows.
106pub fn verify_recovery_code(
107    subject: &str,
108    code: &str,
109    verifier: &RecoveryCodeVerifier,
110    pepper: &[u8],
111) -> Result<bool, RecoveryCodeError> {
112    validate_subject_and_pepper(subject, pepper)?;
113    if verifier.version != 1 {
114        return Ok(false);
115    }
116    let Some(code) = normalize_code(code) else {
117        return Ok(false);
118    };
119    let candidate = recovery_digest(subject, &code, &verifier.salt, pepper)?;
120    Ok(bool::from(candidate.ct_eq(&verifier.digest)))
121}
122
123/// Removes one matching verifier after scanning every candidate.
124///
125/// Callers backed by a database must perform the read, match and delete in one
126/// transaction or equivalent compare-and-delete operation to retain single-use
127/// semantics across processes.
128pub fn consume_recovery_code(
129    subject: &str,
130    code: &str,
131    verifiers: &mut Vec<RecoveryCodeVerifier>,
132    pepper: &[u8],
133) -> Result<bool, RecoveryCodeError> {
134    validate_subject_and_pepper(subject, pepper)?;
135    let Some(code) = normalize_code(code) else {
136        return Ok(false);
137    };
138    let mut matched = None;
139    for (index, verifier) in verifiers.iter().enumerate() {
140        let valid_version = u8::from(verifier.version == 1);
141        let candidate = recovery_digest(subject, &code, &verifier.salt, pepper)?;
142        let digest_matches = candidate.ct_eq(&verifier.digest).unwrap_u8();
143        if (valid_version & digest_matches) == 1 && matched.is_none() {
144            matched = Some(index);
145        }
146    }
147    if let Some(index) = matched {
148        verifiers.remove(index);
149        Ok(true)
150    } else {
151        Ok(false)
152    }
153}
154
155fn validate_configuration(
156    subject: &str,
157    count: usize,
158    pepper: &[u8],
159) -> Result<(), RecoveryCodeError> {
160    if count == 0 || count > MAX_CODES {
161        return Err(RecoveryCodeError::InvalidConfiguration("count"));
162    }
163    validate_subject_and_pepper(subject, pepper)
164}
165
166fn validate_subject_and_pepper(subject: &str, pepper: &[u8]) -> Result<(), RecoveryCodeError> {
167    if subject.is_empty()
168        || subject.trim() != subject
169        || subject.len() > MAX_SUBJECT_BYTES
170        || subject.chars().any(char::is_control)
171    {
172        return Err(RecoveryCodeError::InvalidConfiguration("subject"));
173    }
174    let mut distinct = [false; 256];
175    for byte in pepper {
176        distinct[usize::from(*byte)] = true;
177    }
178    if pepper.len() < MIN_PEPPER_BYTES || distinct.iter().filter(|present| **present).count() < 12 {
179        return Err(RecoveryCodeError::WeakPepper);
180    }
181    Ok(())
182}
183
184fn generate_code() -> String {
185    let mut compact = [0_u8; CODE_CHARACTERS];
186    for character in &mut compact {
187        *character = CODE_ALPHABET[usize::from(rand::random::<u8>()) % CODE_ALPHABET.len()];
188    }
189    let mut formatted = String::with_capacity(CODE_CHARACTERS + 3);
190    for (index, byte) in compact.into_iter().enumerate() {
191        if index > 0 && index % 4 == 0 {
192            formatted.push('-');
193        }
194        formatted.push(char::from(byte));
195    }
196    formatted
197}
198
199fn normalize_code(code: &str) -> Option<String> {
200    let compact = code
201        .bytes()
202        .filter(|byte| *byte != b'-')
203        .map(|byte| byte.to_ascii_uppercase())
204        .collect::<Vec<_>>();
205    if compact.len() != CODE_CHARACTERS || compact.iter().any(|byte| !CODE_ALPHABET.contains(byte))
206    {
207        return None;
208    }
209    String::from_utf8(compact).ok()
210}
211
212fn recovery_digest(
213    subject: &str,
214    normalized_code: &str,
215    salt: &[u8; 16],
216    pepper: &[u8],
217) -> Result<[u8; 32], RecoveryCodeError> {
218    let mut mac = <HmacSha256 as KeyInit>::new_from_slice(pepper)
219        .map_err(|_| RecoveryCodeError::CryptoInitialization)?;
220    mac.update(DOMAIN);
221    mac.update(&(subject.len() as u64).to_be_bytes());
222    mac.update(subject.as_bytes());
223    mac.update(salt);
224    mac.update(normalized_code.as_bytes());
225    Ok(mac.finalize().into_bytes().into())
226}
227
228#[cfg(test)]
229mod tests {
230    use super::*;
231
232    const PEPPER: &[u8] = b"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
233
234    // TM-AUTH-07: recovery codes are subject-bound, stored as verifiers and
235    // removed on the first successful use.
236    #[test]
237    fn codes_are_subject_bound_single_use_and_do_not_store_plaintext() {
238        let batch = generate_recovery_codes("learner-7", 8, PEPPER).expect("recovery batch");
239        assert_eq!(batch.plaintext().len(), 8);
240        assert_eq!(batch.verifiers().len(), 8);
241        let code = batch.plaintext()[0].clone();
242        let serialized = serde_json::to_string(batch.verifiers()).expect("serialized verifiers");
243        assert!(!serialized.contains(&code));
244        assert!(
245            verify_recovery_code("learner-7", &code, &batch.verifiers()[0], PEPPER)
246                .expect("correct subject")
247        );
248        assert!(
249            !verify_recovery_code("learner-8", &code, &batch.verifiers()[0], PEPPER)
250                .expect("wrong subject")
251        );
252
253        let (_, mut verifiers) = batch.into_parts();
254        assert!(
255            consume_recovery_code("learner-7", &code, &mut verifiers, PEPPER)
256                .expect("first consume")
257        );
258        assert!(
259            !consume_recovery_code("learner-7", &code, &mut verifiers, PEPPER)
260                .expect("replay consume")
261        );
262        assert_eq!(verifiers.len(), 7);
263    }
264
265    #[test]
266    fn configuration_format_pepper_and_tampering_fail_closed() {
267        assert!(generate_recovery_codes("learner", 0, PEPPER).is_err());
268        assert!(generate_recovery_codes("learner", 21, PEPPER).is_err());
269        assert!(generate_recovery_codes(" learner", 8, PEPPER).is_err());
270        assert!(generate_recovery_codes("learner", 8, b"weak").is_err());
271
272        let batch = generate_recovery_codes("learner", 1, PEPPER).expect("recovery batch");
273        let lowercase = batch.plaintext()[0].to_ascii_lowercase();
274        assert!(
275            verify_recovery_code("learner", &lowercase, &batch.verifiers()[0], PEPPER)
276                .expect("normalized code")
277        );
278        assert!(
279            !verify_recovery_code(
280                "learner",
281                "AAAA-AAAA-AAAA-AAAA",
282                &batch.verifiers()[0],
283                PEPPER,
284            )
285            .expect("wrong code")
286        );
287        assert!(
288            !verify_recovery_code("learner", "not a code", &batch.verifiers()[0], PEPPER)
289                .expect("invalid format")
290        );
291    }
292}