1use 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#[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
44pub 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
76pub 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
105pub 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
123pub 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 #[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}