pakery_spake2plus/
transcript.rs

1//! Key schedule and output per RFC 9383 section 3.4.
2
3use alloc::vec::Vec;
4use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};
5
6use pakery_core::crypto::{Hash, Kdf, Mac};
7use pakery_core::SharedSecret;
8
9use crate::ciphersuite::Spake2PlusCiphersuite;
10use crate::error::Spake2PlusError;
11
12/// Output of a completed SPAKE2+ protocol run.
13#[derive(Zeroize, ZeroizeOnDrop)]
14pub struct Spake2PlusOutput {
15    /// The shared session key (K_shared).
16    #[zeroize(skip)]
17    pub session_key: SharedSecret,
18}
19
20impl Spake2PlusOutput {
21    /// Consume the output and yield the session key.
22    ///
23    /// Because [`Spake2PlusOutput`] derives `ZeroizeOnDrop`, it cannot be
24    /// pattern-destructured by the caller. This consumer extracts the
25    /// session key cleanly without the boilerplate `mem::replace` shim.
26    #[must_use]
27    pub fn into_session_key(mut self) -> SharedSecret {
28        core::mem::replace(&mut self.session_key, SharedSecret::new(Vec::new()))
29    }
30}
31
32/// Key schedule derived from the SPAKE2+ transcript.
33///
34/// Contains confirmation keys, MACs, and the shared session key.
35pub(crate) struct KeySchedule {
36    pub confirm_p: Vec<u8>,
37    pub confirm_v: Vec<u8>,
38    pub session_key: SharedSecret,
39}
40
41impl Drop for KeySchedule {
42    fn drop(&mut self) {
43        self.confirm_p.zeroize();
44        self.confirm_v.zeroize();
45        // session_key has its own ZeroizeOnDrop via SharedSecret
46    }
47}
48
49/// Derive the key schedule from transcript TT.
50///
51/// Per RFC 9383 section 3.4:
52/// 1. `K_main = Hash(TT)` (full NH-byte hash output)
53/// 2. `PRK = KDF.extract(salt=[], ikm=K_main)`
54/// 3. `K_confirmP || K_confirmV = KDF.expand(PRK, "ConfirmationKeys", 2*NH)`
55/// 4. `K_shared = KDF.expand(PRK, "SharedKey", NH)`
56/// 5. `confirmV = MAC(K_confirmV, shareP)`, `confirmP = MAC(K_confirmP, shareV)`
57pub(crate) fn derive_key_schedule<C: Spake2PlusCiphersuite>(
58    tt: &[u8],
59    share_p: &[u8],
60    share_v: &[u8],
61) -> Result<KeySchedule, Spake2PlusError> {
62    // Step 1: K_main = Hash(TT)
63    const { assert!(<C::Hash as pakery_core::crypto::Hash>::OUTPUT_SIZE >= C::NH) };
64    let k_main = Zeroizing::new(C::Hash::digest(tt));
65
66    // Step 2: PRK = KDF.extract(salt=[], ikm=K_main)
67    let prk = C::Kdf::extract(&[], &k_main[..C::NH]);
68
69    // Step 3: K_confirmP || K_confirmV = KDF.expand(PRK, "ConfirmationKeys", 2*NH)
70    let kc = C::Kdf::expand(&prk, b"ConfirmationKeys", 2 * C::NH)
71        .map_err(|_| Spake2PlusError::InternalError("KDF expand failed for ConfirmationKeys"))?;
72    let k_confirm_p = &kc[..C::NH];
73    let k_confirm_v = &kc[C::NH..2 * C::NH];
74
75    // Step 4: K_shared = KDF.expand(PRK, "SharedKey", NH)
76    let mut k_shared = C::Kdf::expand(&prk, b"SharedKey", C::NH)
77        .map_err(|_| Spake2PlusError::InternalError("KDF expand failed for SharedKey"))?;
78
79    // Step 5: confirmV = MAC(K_confirmV, shareP), confirmP = MAC(K_confirmP, shareV)
80    // Note: MACs are over the *peer's* share
81    let confirm_v = C::Mac::mac(k_confirm_v, share_p)
82        .map_err(|_| Spake2PlusError::InternalError("MAC computation failed"))?;
83    let confirm_p = C::Mac::mac(k_confirm_p, share_v)
84        .map_err(|_| Spake2PlusError::InternalError("MAC computation failed"))?;
85
86    Ok(KeySchedule {
87        confirm_p,
88        confirm_v,
89        session_key: SharedSecret::new(core::mem::take(&mut *k_shared)),
90    })
91}
pakery_spake2plus/transcript.rs

pakery_spake2plus/
transcript.rs
