huddle_core/crypto/
passphrase.rs

1//! Passphrase-derived key wrapping for Megolm session keys.
2//!
3//! Argon2id derives a 32-byte key from a user passphrase + per-room salt.
4//! ChaCha20-Poly1305 then wraps the Megolm session key for transmission.
5//! Anyone in possession of the passphrase + salt can unwrap and join the room.
6//!
7//! huddle 0.7.11: derived keys are returned in a `Zeroizing<[u8;32]>`
8//! wrapper that overwrites the byte slice when the value is dropped.
9//! That doesn't fix every secret-in-memory exposure (the bytes can
10//! still be copied), but it prevents the local owner from leaking
11//! into swap or a stale heap page after the key is no longer in use.
12
13use argon2::{Algorithm, Argon2, Params, Version};
14use base64::Engine;
15use chacha20poly1305::aead::{Aead, AeadCore, KeyInit, OsRng};
16use chacha20poly1305::{ChaCha20Poly1305, Key, Nonce};
17use rand::RngCore;
18use zeroize::Zeroizing;
19
20use crate::error::{HuddleError, Result};
21
22pub const SALT_LEN: usize = 16;
23pub const KEY_LEN: usize = 32;
24pub const NONCE_LEN: usize = 12;
25
26/// Generate a random salt for a new encrypted room.
27pub fn random_salt() -> [u8; SALT_LEN] {
28    let mut salt = [0u8; SALT_LEN];
29    OsRng.fill_bytes(&mut salt);
30    salt
31}
32
33/// Derive a 32-byte symmetric key from a passphrase and salt using
34/// Argon2id. Parameters follow the strong RFC 9106 / OWASP profile
35/// (64 MiB memory, 3 iterations, 4 lanes) and must stay in sync with the
36/// master-key KDF in `storage::keychain::derive_master_key`.
37pub fn derive_key(passphrase: &str, salt: &[u8]) -> Result<[u8; KEY_LEN]> {
38    let zeroizing = derive_key_zeroizing(passphrase, salt)?;
39    // Copy out into a plain array for back-compat with all the call
40    // sites that already accept `&[u8; KEY_LEN]`. The local `zeroizing`
41    // is wiped when it goes out of scope at the end of this function.
42    Ok(*zeroizing)
43}
44
45/// huddle 0.7.11: same as `derive_key` but returns the key in a
46/// zeroize-on-drop wrapper. Callers that want defense-in-depth against
47/// heap-residency leaks should prefer this over `derive_key`.
48pub fn derive_key_zeroizing(
49    passphrase: &str,
50    salt: &[u8],
51) -> Result<Zeroizing<[u8; KEY_LEN]>> {
52    let params = Params::new(65_536, 3, 4, Some(KEY_LEN))
53        .map_err(|e| HuddleError::Session(format!("argon2 params: {e}")))?;
54    let argon = Argon2::new(Algorithm::Argon2id, Version::V0x13, params);
55    let mut out = Zeroizing::new([0u8; KEY_LEN]);
56    argon
57        .hash_password_into(passphrase.as_bytes(), salt, out.as_mut_slice())
58        .map_err(|e| HuddleError::Session(format!("argon2 derive: {e}")))?;
59    Ok(out)
60}
61
62/// Wrap arbitrary plaintext (typically a Megolm SessionKey) under the passphrase key.
63/// Returns nonce || ciphertext, base64-encoded for transmission.
64pub fn wrap(plaintext: &[u8], passphrase_key: &[u8; KEY_LEN]) -> Result<String> {
65    let cipher = ChaCha20Poly1305::new(Key::from_slice(passphrase_key));
66    let nonce = ChaCha20Poly1305::generate_nonce(&mut OsRng);
67    let ciphertext = cipher
68        .encrypt(&nonce, plaintext)
69        .map_err(|e| HuddleError::Session(format!("wrap failed: {e}")))?;
70    let mut combined = Vec::with_capacity(NONCE_LEN + ciphertext.len());
71    combined.extend_from_slice(&nonce);
72    combined.extend_from_slice(&ciphertext);
73    Ok(base64::engine::general_purpose::STANDARD.encode(&combined))
74}
75
76/// Unwrap base64-encoded (nonce || ciphertext) under the passphrase key.
77pub fn unwrap(encoded: &str, passphrase_key: &[u8; KEY_LEN]) -> Result<Vec<u8>> {
78    let bytes = base64::engine::general_purpose::STANDARD
79        .decode(encoded)
80        .map_err(|e| HuddleError::Session(format!("bad base64: {e}")))?;
81    if bytes.len() < NONCE_LEN + 16 {
82        return Err(HuddleError::Session("wrapped key too short".into()));
83    }
84    let (nonce_bytes, ciphertext) = bytes.split_at(NONCE_LEN);
85    let cipher = ChaCha20Poly1305::new(Key::from_slice(passphrase_key));
86    let nonce = Nonce::from_slice(nonce_bytes);
87    cipher
88        .decrypt(nonce, ciphertext)
89        .map_err(|e| HuddleError::Session(format!("unwrap failed (wrong passphrase?): {e}")))
90}
91
92#[cfg(test)]
93mod tests {
94    use super::*;
95
96    #[test]
97    fn derive_is_deterministic() {
98        let salt = [42u8; SALT_LEN];
99        let k1 = derive_key("hunter2", &salt).unwrap();
100        let k2 = derive_key("hunter2", &salt).unwrap();
101        assert_eq!(k1, k2);
102    }
103
104    #[test]
105    fn different_passphrases_different_keys() {
106        let salt = [42u8; SALT_LEN];
107        let k1 = derive_key("hunter2", &salt).unwrap();
108        let k2 = derive_key("hunter3", &salt).unwrap();
109        assert_ne!(k1, k2);
110    }
111
112    #[test]
113    fn different_salts_different_keys() {
114        let k1 = derive_key("same", &[1u8; SALT_LEN]).unwrap();
115        let k2 = derive_key("same", &[2u8; SALT_LEN]).unwrap();
116        assert_ne!(k1, k2);
117    }
118
119    #[test]
120    fn wrap_unwrap_round_trip() {
121        let salt = random_salt();
122        let key = derive_key("hunter2", &salt).unwrap();
123        let secret = b"this is a megolm session key";
124        let wrapped = wrap(secret, &key).unwrap();
125        let recovered = unwrap(&wrapped, &key).unwrap();
126        assert_eq!(recovered, secret);
127    }
128
129    #[test]
130    fn wrong_passphrase_fails_unwrap() {
131        let salt = random_salt();
132        let right_key = derive_key("hunter2", &salt).unwrap();
133        let wrong_key = derive_key("hunter3", &salt).unwrap();
134        let wrapped = wrap(b"secret", &right_key).unwrap();
135        assert!(unwrap(&wrapped, &wrong_key).is_err());
136    }
137
138    #[test]
139    fn wrapped_output_is_nondeterministic() {
140        let salt = random_salt();
141        let key = derive_key("hunter2", &salt).unwrap();
142        let w1 = wrap(b"hello", &key).unwrap();
143        let w2 = wrap(b"hello", &key).unwrap();
144        assert_ne!(w1, w2, "nonce should differ each time");
145    }
146}
huddle_core/crypto/passphrase.rs

huddle_core/crypto/
passphrase.rs
