gbp_sframe/lib.rs
1//! **GBP-SFrame** — SFrame ([draft-ietf-sframe-enc]) E2EE for GAP audio
2//! streams in the Group Protocol Stack.
3//!
4//! # Overview
5//!
6//! SFrame sits *inside* SRTP (or any transport-level encryption) and provides
7//! **end-to-end** confidentiality for media payloads: the SFU can forward
8//! packets based on RTP headers without seeing the Opus frame content.
9//!
10//! ```text
11//! ┌──────────────────────────────────────────────────┐
12//! │ Transport encryption │ ← client ↔ SFU
13//! │ ┌────────────────────────────────────────────┐ │
14//! │ │ SFrame │ │ ← E2E client ↔ client
15//! │ │ ┌──────────────────────────────────────┐ │ │
16//! │ │ │ Encoded media (Opus / VP8 / VP9) │ │ │
17//! │ │ └──────────────────────────────────────┘ │ │
18//! │ └────────────────────────────────────────────┘ │
19//! └──────────────────────────────────────────────────┘
20//! ```
21//!
22//! # Key derivation
23//!
24//! After each MLS epoch change:
25//!
26//! 1. **Base key** — `MLS.ExportSecret(label, context=epoch_be8, length=32)`.
27//! 2. **Per-sender key** — `HKDF-Expand(base_key, "gbp sframe key " ‖ leaf_be4, L)`.
28//! 3. **Per-sender salt** — `HKDF-Expand(base_key, "gbp sframe salt " ‖ leaf_be4, 12)`.
29//! 4. **Frame nonce** — `salt XOR (CTR_LE64 ‖ 0x00_00_00_00)`.
30//!
31//! The `label` passed to [`SFrameSession::from_mls`] is application-defined
32//! (e.g. `"gbp/sframe v1"`); this lets different deployments use distinct
33//! key universes without changing any other parameter.
34//!
35//! # Quick start
36//!
37//! ```
38//! use gbp_sframe::{SFrameSession, CipherSuite};
39//!
40//! // Both sides derive a session from the same base key (in production this
41//! // comes from SFrameSession::from_mls).
42//! let session = SFrameSession::new([0x42u8; 32], 1, CipherSuite::Aes128Gcm);
43//!
44//! let mut enc = session.encryptor(0);
45//! let payload = enc.encrypt(b"hello audio", b"")?;
46//!
47//! let mut dec = session.decryptor();
48//! let (plaintext, sender_leaf) = dec.decrypt(&payload, b"")?;
49//! assert_eq!(plaintext, b"hello audio");
50//! assert_eq!(sender_leaf, 0);
51//! # Ok::<(), gbp_sframe::SFrameError>(())
52//! ```
53//!
54//! [draft-ietf-sframe-enc]: https://datatracker.ietf.org/doc/draft-ietf-sframe-enc/
55
56#![deny(missing_docs)]
57
58/// AEAD encrypt/decrypt and the stateful encryptor/decryptor types.
59pub mod cipher;
60/// Error type for SFrame operations.
61pub mod error;
62/// SFrame header wire format.
63pub mod header;
64/// Key derivation from MLS export secret.
65pub mod kdf;
66/// Sliding-window replay protection.
67pub mod replay;
68
69pub use cipher::{SFrameDecryptor, SFrameEncryptor};
70pub use error::SFrameError;
71pub use header::SFrameHeader;
72pub use kdf::{CipherSuite, derive_base_key};
73
74use gbp_mls::MlsContext;
75use kdf::derive_participant;
76
77/// An SFrame session bound to one MLS epoch.
78///
79/// A new session must be created whenever the MLS group commits (epoch
80/// changes) — the old base key becomes unreachable and all per-sender keys
81/// are rotated automatically.
82pub struct SFrameSession {
83 base_key: [u8; 32],
84 epoch: u64,
85 suite: CipherSuite,
86}
87
88impl SFrameSession {
89 /// Creates a session from a raw 32-byte base key.
90 ///
91 /// Prefer [`from_mls`](Self::from_mls) when an [`MlsContext`] is
92 /// available; this constructor is mainly for testing.
93 pub fn new(base_key: [u8; 32], epoch: u64, suite: CipherSuite) -> Self {
94 Self { base_key, epoch, suite }
95 }
96
97 /// Derives a session from the current MLS group state.
98 ///
99 /// Calls `MLS.ExportSecret(label, context=epoch_be8, length=32)` to
100 /// obtain the base key, then stores it alongside the current epoch and
101 /// ciphersuite.
102 ///
103 /// `label` is application-defined (e.g. `"gbp/sframe v1"`).
104 pub fn from_mls(
105 mls: &MlsContext,
106 label: &str,
107 suite: CipherSuite,
108 ) -> Result<Self, SFrameError> {
109 let epoch = mls.epoch();
110 let base_key = derive_base_key(mls, label, epoch)?;
111 Ok(Self::new(base_key, epoch, suite))
112 }
113
114 /// Returns the MLS epoch this session was created for.
115 pub fn epoch(&self) -> u64 {
116 self.epoch
117 }
118
119 /// Returns the active ciphersuite.
120 pub fn suite(&self) -> CipherSuite {
121 self.suite
122 }
123
124 /// Creates a sender-side encryptor for `leaf_index`.
125 ///
126 /// The returned [`SFrameEncryptor`] owns the derived key+salt for this
127 /// sender and maintains an internal counter. Create one per sender; do
128 /// **not** share an encryptor across multiple goroutines/threads.
129 pub fn encryptor(&self, leaf_index: u32) -> SFrameEncryptor {
130 let kid = SFrameHeader::kid_from(self.epoch, leaf_index);
131 let keys = derive_participant(&self.base_key, leaf_index, self.suite);
132 SFrameEncryptor::new(keys, kid, self.suite)
133 }
134
135 /// Creates a receiver-side decryptor for this epoch.
136 ///
137 /// The [`SFrameDecryptor`] lazily derives per-sender keys as new KIDs
138 /// arrive, and maintains an independent 1024-entry replay window per sender.
139 pub fn decryptor(&self) -> SFrameDecryptor {
140 SFrameDecryptor::new(self.base_key, self.epoch, self.suite)
141 }
142}
143
144#[cfg(test)]
145mod tests {
146 use super::*;
147
148 fn test_session(epoch: u64) -> SFrameSession {
149 SFrameSession::new([0x42u8; 32], epoch, CipherSuite::Aes128Gcm)
150 }
151
152 #[test]
153 fn encrypt_decrypt_roundtrip_128() {
154 let session = test_session(1);
155 let mut enc = session.encryptor(0);
156 let mut dec = session.decryptor();
157
158 let frame = b"hello sframe";
159 let payload = enc.encrypt(frame, b"").unwrap();
160 let (plain, leaf) = dec.decrypt(&payload, b"").unwrap();
161 assert_eq!(plain, frame);
162 assert_eq!(leaf, 0);
163 }
164
165 #[test]
166 fn encrypt_decrypt_roundtrip_256() {
167 let session = SFrameSession::new([0x11u8; 32], 5, CipherSuite::Aes256Gcm);
168 let mut enc = session.encryptor(3);
169 let mut dec = session.decryptor();
170
171 let frame = b"audio payload aes256";
172 let payload = enc.encrypt(frame, b"rtp-header").unwrap();
173 let (plain, leaf) = dec.decrypt(&payload, b"rtp-header").unwrap();
174 assert_eq!(plain, frame);
175 assert_eq!(leaf, 3);
176 }
177
178 #[test]
179 fn wrong_aad_fails_decryption() {
180 let session = test_session(0);
181 let mut enc = session.encryptor(0);
182 let mut dec = session.decryptor();
183
184 let payload = enc.encrypt(b"data", b"correct-aad").unwrap();
185 assert!(dec.decrypt(&payload, b"wrong-aad").is_err());
186 }
187
188 #[test]
189 fn replay_rejected() {
190 let session = test_session(0);
191 let mut enc = session.encryptor(1);
192 let mut dec = session.decryptor();
193
194 let payload = enc.encrypt(b"frame", b"").unwrap();
195 dec.decrypt(&payload, b"").unwrap();
196 assert!(dec.decrypt(&payload, b"").is_err());
197 }
198
199 #[test]
200 fn multi_sender() {
201 let session = test_session(2);
202 let mut enc0 = session.encryptor(0);
203 let mut enc1 = session.encryptor(1);
204 let mut dec = session.decryptor();
205
206 let p0 = enc0.encrypt(b"from-0", b"").unwrap();
207 let p1 = enc1.encrypt(b"from-1", b"").unwrap();
208
209 let (msg0, leaf0) = dec.decrypt(&p0, b"").unwrap();
210 let (msg1, leaf1) = dec.decrypt(&p1, b"").unwrap();
211
212 assert_eq!(msg0, b"from-0");
213 assert_eq!(leaf0, 0);
214 assert_eq!(msg1, b"from-1");
215 assert_eq!(leaf1, 1);
216 }
217
218 #[test]
219 fn epoch_mismatch_rejected() {
220 let session_a = test_session(1);
221 let session_b = test_session(2); // different epoch
222
223 let mut enc = session_a.encryptor(0);
224 let mut dec = session_b.decryptor();
225
226 let payload = enc.encrypt(b"stale", b"").unwrap();
227 assert!(dec.decrypt(&payload, b"").is_err());
228 }
229}