gbp_sframe/
kdf.rs

1use gbp_mls::MlsContext;
2use hkdf::Hkdf;
3use sha2::Sha256;
4
5use crate::error::SFrameError;
6
7/// SFrame ciphersuite selection.
8///
9/// `Aes128Gcm` is the standard choice; `Aes256Gcm` is available for
10/// high-assurance deployments.
11#[derive(Clone, Copy, Debug, PartialEq, Eq)]
12pub enum CipherSuite {
13    /// AES-128-GCM: 16-byte key, 12-byte nonce.
14    Aes128Gcm,
15    /// AES-256-GCM: 32-byte key, 12-byte nonce.
16    Aes256Gcm,
17}
18
19impl CipherSuite {
20    /// Key length in bytes.
21    pub(crate) fn key_len(self) -> usize {
22        match self {
23            Self::Aes128Gcm => 16,
24            Self::Aes256Gcm => 32,
25        }
26    }
27
28    /// Numeric discriminant used in the FFI (`0` = AES-128, `1` = AES-256).
29    pub fn from_u8(v: u8) -> Option<Self> {
30        match v {
31            0 => Some(Self::Aes128Gcm),
32            1 => Some(Self::Aes256Gcm),
33            _ => None,
34        }
35    }
36
37    /// Numeric discriminant.
38    pub fn as_u8(self) -> u8 {
39        match self {
40            Self::Aes128Gcm => 0,
41            Self::Aes256Gcm => 1,
42        }
43    }
44}
45
46/// Derived key material for one participant in one epoch.
47pub(crate) struct ParticipantKeys {
48    /// AES key: 16 bytes for AES-128-GCM, 32 bytes for AES-256-GCM.
49    pub key: Vec<u8>,
50    /// 12-byte base nonce (XOR'd with the counter to produce each frame nonce).
51    pub salt: [u8; 12],
52}
53
54/// Derives the 32-byte SFrame base key from the MLS `ExportSecret`.
55///
56/// `label` is the application-defined export label
57/// (e.g. `"gbp/sframe v1"`).
58/// `epoch` is passed as an 8-byte big-endian context to bind the key to the
59/// current MLS epoch.
60pub fn derive_base_key(mls: &MlsContext, label: &str, epoch: u64) -> Result<[u8; 32], SFrameError> {
61    let context = epoch.to_be_bytes();
62    let raw = mls
63        .export_raw(label, &context, 32)
64        .map_err(|e| SFrameError::MlsExport(e.to_string()))?;
65    let mut out = [0u8; 32];
66    out.copy_from_slice(&raw);
67    Ok(out)
68}
69
70/// Derives the encryption key and base salt for participant `leaf_index`.
71///
72/// Uses HKDF-Expand (SHA-256) over the epoch's `base_key` with
73/// deterministic info strings so every member can reproduce any sender's
74/// key material.
75pub(crate) fn derive_participant(
76    base_key: &[u8; 32],
77    leaf_index: u32,
78    suite: CipherSuite,
79) -> ParticipantKeys {
80    // SAFETY: base_key is 32 bytes = SHA-256 HashLen, so from_prk never panics.
81    let hk =
82        Hkdf::<Sha256>::from_prk(base_key).expect("base_key is exactly SHA-256 HashLen (32 bytes)");
83
84    let leaf_be = leaf_index.to_be_bytes();
85
86    let mut key_info = b"gbp sframe key ".to_vec();
87    key_info.extend_from_slice(&leaf_be);
88    let mut key = vec![0u8; suite.key_len()];
89    hk.expand(&key_info, &mut key)
90        .expect("key length is well within 255 * HashLen");
91
92    let mut salt_info = b"gbp sframe salt ".to_vec();
93    salt_info.extend_from_slice(&leaf_be);
94    let mut salt = [0u8; 12];
95    hk.expand(&salt_info, &mut salt)
96        .expect("salt length (12) is well within 255 * HashLen");
97
98    ParticipantKeys { key, salt }
99}
100
101/// Constructs the 12-byte per-frame nonce:
102/// `participant_salt XOR (CTR_LE64 || 0x00_00_00_00)`.
103pub(crate) fn make_nonce(salt: &[u8; 12], ctr: u64) -> [u8; 12] {
104    let mut nonce = *salt;
105    let ctr_le = ctr.to_le_bytes(); // 8 bytes little-endian
106    for i in 0..8 {
107        nonce[i] ^= ctr_le[i];
108    }
109    nonce
110}
gbp_sframe/kdf.rs

gbp_sframe/
kdf.rs
