From 1a8ccba33f5368ce280eac605008331f6c4ca57b Mon Sep 17 00:00:00 2001 From: Alex Andres Date: Sun, 8 Nov 2026 23:48:06 +0100 Subject: [PATCH] feat: reserve ratchet steps in SFrame key IDs Key IDs are now context (16 bits), participant (32), generation (8) and ratchet step (8), so that the ratchet of RFC 9605, Section 5.1 can be added without changing the format again. Senders send step 0, and receivers take any other step for an unknown key. The format is named webrtc-java-sframe/1 (KeyProvider.FORMAT and FORMAT in the browser module), for applications to agree on by signaling. --- docs/guide/advanced/end-to-end-encryption.md | 17 +++--- docs/public/e2ee/webrtc-java-sframe.js | 25 ++++++--- .../dev/onvoid/webrtc/e2ee/CryptoFailure.java | 2 +- .../onvoid/webrtc/e2ee/FrameDecryptor.java | 5 +- .../dev/onvoid/webrtc/e2ee/FrameFormat.java | 28 ++++++---- .../dev/onvoid/webrtc/e2ee/KeyProvider.java | 9 +++- .../webrtc/e2ee/BrowserInteropTests.java | 2 + .../onvoid/webrtc/e2ee/FrameCryptorTests.java | 53 ++++++++++++++++++- .../dev/onvoid/webrtc/e2ee/sframe-interop.mjs | 4 +- 9 files changed, 116 insertions(+), 29 deletions(-) diff --git a/docs/guide/advanced/end-to-end-encryption.md b/docs/guide/advanced/end-to-end-encryption.md index 528e59f03..616f45099 100644 --- a/docs/guide/advanced/end-to-end-encryption.md +++ b/docs/guide/advanced/end-to-end-encryption.md @@ -189,24 +189,29 @@ receiver.transform = new RTCRtpScriptTransform(worker, { side: 'receive' }); This section specifies the format, so that it can be implemented elsewhere. It is RFC 9605 applied per frame, with the key IDs and the codec layouts below. +### Version + +This is version 1, named `webrtc-java-sframe/1`: `KeyProvider.FORMAT` in Java, `FORMAT` in the browser module. Nothing in a frame says which format it is in, so the participants of a call agree on it, as on the cipher suite and the keys: by the application's signaling, as part of what it sends with the keys. A later version, such as SFrame with the RTP payload format WebRTC is working on, which needs no codec layouts, has a name of its own and is agreed the same way, never told apart by trying. + ### Cipher Suites and Keys Every participant of a call uses the same cipher suite of RFC 9605, Section 4.5, by default `AES_128_GCM_SHA256_128` (0x0004). The key and salt of each key ID are derived from the participant's key with `derive_key_salt` (RFC 9605, Section 4.4.2), and frames are encrypted and decrypted with `encrypt` and `decrypt` (Sections 4.4.3 and 4.4.4). ### Key IDs -A key ID (KID) is made up of three fields, from the most significant bit down, after the MLS scheme of RFC 9605, Section 5.2: +A key ID (KID) is made up of four fields, from the most significant bit down. The lowest 16 bits are the "key generation | ratchet step" of the sender keys scheme of RFC 9605, Section 5.1, and the fields above them follow the MLS scheme of Section 5.2: ``` - 63 40 39 8 7 0 -+----------------+-----------------------------+------------+ -| context (24) | participant (32) | generation | -+----------------+-----------------------------+------------+ + 63 48 47 16 15 8 7 0 ++--------------+-----------------------------+-------------+--------------+ +| context (16) | participant (32) | generation | ratchet step | ++--------------+-----------------------------+-------------+--------------+ ``` - **participant**: the ID of the participant who encrypted the frame. A receiver finds the key by it and by the generation. - **generation**: the generation of that participant's key, 0 to 255. -- **context**: one per RTP stream the participant sends, given out from 0 upwards and never reused for the participant's key provider. Since the KID goes into the key derivation, every stream encrypts with a key and salt of its own. +- **ratchet step**: how many times the generation's key was moved forward with the ratchet of RFC 9605, Section 5.1, `base_key[i+1] = HKDF-Expand(HKDF-Extract("", base_key[i]), "SFrame 1.0 Ratchet", Nh)`. This version of the format always sends 0, and a receiver drops a frame with any other step as one whose key it does not have. +- **context**: one per RTP stream the participant sends, given out from 0 upwards and never reused for the participant's key provider, which therefore serves up to 65,536 streams. Since the KID goes into the key derivation, every stream encrypts with a key and salt of its own. ### Counters diff --git a/docs/public/e2ee/webrtc-java-sframe.js b/docs/public/e2ee/webrtc-java-sframe.js index 418c75731..e1fd0d621 100644 --- a/docs/public/e2ee/webrtc-java-sframe.js +++ b/docs/public/e2ee/webrtc-java-sframe.js @@ -36,6 +36,9 @@ const subtle = globalThis.crypto.subtle; +/** The name of the frame format, as the Java KeyProvider.FORMAT has it. */ +export const FORMAT = 'webrtc-java-sframe/1'; + /** The cipher suites of RFC 9605, Section 4.5, by their registry value. */ export const CipherSuite = Object.freeze({ AES_128_CTR_HMAC_SHA256_80: 1, @@ -66,7 +69,7 @@ export const Failure = Object.freeze({ const NONCE_LENGTH = 12; const MAX_PARTICIPANT = 0xffffffff; -const MAX_CONTEXT = 0xffffff; +const MAX_CONTEXT = 0xffff; /** OBU_FRAME and OBU_SEQUENCE_HEADER, no extension, no size field. */ const AV1_WRAPPER = 6 << 3; @@ -299,9 +302,13 @@ export class SFrameKey { // ---------------------------------------------------------- Frame format -/** KID = context (24 bits) | participant (32 bits) | generation (8 bits). */ -export function keyId(context, participant, generation) { - return BigInt(context) << 40n | BigInt(participant) << 8n | BigInt(generation); +/** + * KID = context (16 bits) | participant (32 bits) | generation (8 bits) | + * ratchet step (8 bits). This version always sends a ratchet step of 0, and + * takes any other step for a key it does not have. + */ +export function keyId(context, participant, generation, ratchetStep = 0) { + return BigInt(context) << 48n | BigInt(participant) << 16n | BigInt(generation) << 8n | BigInt(ratchetStep); } function codecOf(mimeType) { @@ -776,12 +783,14 @@ class FrameDecryptor extends FrameCryptor { return this.fail(stream, Failure.MALFORMED, -1, -1, info); } - const participant = Number(header.kid >> 8n & 0xffffffffn); - const generation = Number(header.kid & 0xffn); - const context = Number(header.kid >> 40n); + const participant = Number(header.kid >> 16n & 0xffffffffn); + const generation = Number(header.kid >> 8n & 0xffn); + const ratchetStep = Number(header.kid & 0xffn); + const context = Number(header.kid >> 48n); const now = Date.now(); - const key = keys.decryptionKey(participant, generation, now); + // A key moved forward by the ratchet is one this version never has. + const key = ratchetStep === 0 ? keys.decryptionKey(participant, generation, now) : null; if (!key) { return this.fail(stream, Failure.UNKNOWN_KEY, participant, generation, info); diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoFailure.java b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoFailure.java index f776b5f2d..eb42641ab 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoFailure.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoFailure.java @@ -66,7 +66,7 @@ public enum CryptoFailure { UNSUPPORTED_CODEC, /** - * The {@link KeyProvider} gave out every one of its 224 + * The {@link KeyProvider} gave out every one of its 216 * sender contexts, and has to be replaced. */ CONTEXTS_EXHAUSTED diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameDecryptor.java b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameDecryptor.java index a732171b8..9decf400b 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameDecryptor.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameDecryptor.java @@ -78,7 +78,10 @@ int process(long ssrc, String mimeType, boolean video, boolean keyFrame, byte[] int generation = FrameFormat.generation(kid); long now = System.nanoTime(); - KeyProvider.RemoteKey key = keys.decryptionKey(participant, generation, now); + // A key moved forward by the ratchet is one this version never has. + KeyProvider.RemoteKey key = FrameFormat.ratchetStep(kid) == 0 + ? keys.decryptionKey(participant, generation, now) + : null; if (key == null) { return fail(stream, CryptoFailure.UNKNOWN_KEY, participant, generation, mimeType); diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameFormat.java b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameFormat.java index f899739ee..dbd0c64ec 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameFormat.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameFormat.java @@ -33,8 +33,8 @@ final class FrameFormat { /** The largest key generation, 8 bits. */ static final int MAX_GENERATION = 0xFF; - /** The largest context, 24 bits. */ - static final int MAX_CONTEXT = 0xFF_FFFF; + /** The largest context, 16 bits. */ + static final int MAX_CONTEXT = 0xFFFF; /** * The OBU header an AV1 delta frame is wrapped in: OBU_FRAME (type 6), no @@ -59,23 +59,33 @@ private FrameFormat() { } /** - * KID = context (24 bits) | participant (32 bits) | generation (8 bits), - * from the most significant bits down, after RFC 9605, Section 5.2. + * KID = context (16 bits) | participant (32 bits) | generation (8 bits) | + * ratchet step (8 bits), from the most significant bits down. The lowest + * 16 bits are the "key generation | ratchet step" of RFC 9605, Section + * 5.1, the participant and context above them follow Section 5.2. + *

+ * The ratchet step is the number of times the generation's key was moved + * forward with the ratchet of RFC 9605, Section 5.1. This version always + * sends 0, and takes any other step for a key it does not have. */ - static long kid(int context, long participant, int generation) { - return (long) context << 40 | participant << 8 | generation; + static long kid(int context, long participant, int generation, int ratchetStep) { + return (long) context << 48 | participant << 16 | (long) generation << 8 | ratchetStep; } static int context(long kid) { - return (int) (kid >>> 40); + return (int) (kid >>> 48); } static long participant(long kid) { - return kid >>> 8 & MAX_PARTICIPANT; + return kid >>> 16 & MAX_PARTICIPANT; } static int generation(long kid) { - return (int) (kid & MAX_GENERATION); + return (int) (kid >>> 8 & MAX_GENERATION); + } + + static int ratchetStep(long kid) { + return (int) (kid & 0xFF); } /** diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/KeyProvider.java b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/KeyProvider.java index 358ad386b..ab9e07261 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/KeyProvider.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/KeyProvider.java @@ -83,6 +83,13 @@ */ public final class KeyProvider { + /** + * The name of the frame format the transforms write and read. Nothing in + * a frame says which format it is in, so the participants of a call agree + * on it by their signaling, along with the cipher suite and the keys. + */ + public static final String FORMAT = "webrtc-java-sframe/1"; + /** The smallest base key accepted, in bytes. */ static final int MIN_KEY_LENGTH = 16; @@ -636,7 +643,7 @@ static final class LocalKey { SFrame sframe(CipherSuite suite, int context, long participant) { return derived.computeIfAbsent(context, c -> - SFrame.derive(suite, FrameFormat.kid(c, participant, generation), baseKey)); + SFrame.derive(suite, FrameFormat.kid(c, participant, generation, 0), baseKey)); } } diff --git a/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/BrowserInteropTests.java b/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/BrowserInteropTests.java index 1459bdb6f..101e8cbf3 100644 --- a/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/BrowserInteropTests.java +++ b/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/BrowserInteropTests.java @@ -100,6 +100,8 @@ void browserModuleMatchesJava() throws Exception { List output = runNode(input.toString()); + assertTrue(output.contains("format " + KeyProvider.FORMAT), () -> "The formats differ: " + output); + assertEquals(CipherSuite.values().length, output.stream().filter(l -> l.startsWith("vector")).count()); output.stream().filter(l -> l.startsWith("vector")) .forEach(l -> assertTrue(l.endsWith(" ok"), "RFC 9605 vector in JavaScript: " + l)); diff --git a/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/FrameCryptorTests.java b/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/FrameCryptorTests.java index d1f1fc9af..2f1244e78 100644 --- a/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/FrameCryptorTests.java +++ b/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/FrameCryptorTests.java @@ -162,8 +162,8 @@ void everySuiteRoundTrips() { byte[] frame = frame(1000); byte[] sealed = process(encryptor(sender), SSRC, "video/VP8", true, true, frame); - // The tag, and a header of a two-byte KID and a counter of zero. - assertEquals(frame.length + 3 + suite.getTagLength(), sealed.length, suite.name()); + // The tag, and a header of a three-byte KID and a counter of zero. + assertEquals(frame.length + 4 + suite.getTagLength(), sealed.length, suite.name()); assertArrayEquals(frame, process(decryptor(receiver), SSRC, "video/VP8", true, true, sealed), suite.name()); } @@ -408,6 +408,55 @@ void oldGenerationsRetire() throws InterruptedException { assertEquals(0, last(bobEvents).getGeneration()); } + @Test + void keyIdHasFourFields() { + long kid = FrameFormat.kid(0xABCD, 0xFEDC_BA98L, 0x76, 0x54); + + assertEquals(0xABCD_FEDC_BA98_7654L, kid); + assertEquals(0xABCD, FrameFormat.context(kid)); + assertEquals(0xFEDC_BA98L, FrameFormat.participant(kid)); + assertEquals(0x76, FrameFormat.generation(kid)); + assertEquals(0x54, FrameFormat.ratchetStep(kid)); + + // What goes out: the ratchet step is always 0 in this version. + byte[] sealed = process(encryptor(alice), SSRC, "video/VP9", true, true, frame(50)); + long[] header = header(sealed, 0); + + assertEquals(FrameFormat.kid(0, ALICE, 0, 0), header[0]); + } + + @Test + void ratchetedKeysAreUnknown() { + // A frame under a key moved forward once, as a later version may + // send: its key is not there, however well it would authenticate. + long kid = FrameFormat.kid(0, ALICE, 0, 1); + SFrame sframe = SFrame.derive(alice.getCipherSuite(), kid, aliceKey); + + byte[] plaintext = frame(100); + byte[] sealed = new byte[SFrame.MAX_HEADER_LENGTH + plaintext.length + 16]; + int length = sframe.encrypt(0, new byte[0], 0, 0, plaintext, 0, plaintext.length, sealed, 0); + + assertNull(process(decryptor(bob), SSRC, "video/VP9", true, true, Arrays.copyOf(sealed, length))); + + CryptoEvent event = last(bobEvents); + assertEquals(CryptoFailure.UNKNOWN_KEY, event.getFailure()); + assertEquals(ALICE, event.getParticipant()); + assertEquals(0, event.getGeneration()); + } + + @Test + void contextsRunOut() { + KeyProvider keys = KeyProvider.builder(ALICE).build(); + + for (int i = 0; i <= FrameFormat.MAX_CONTEXT; i++) { + assertEquals(i, keys.allocateContext()); + } + + // 65,536 streams in all, and then none. + assertEquals(-1, keys.allocateContext()); + assertEquals(-1, keys.allocateContext()); + } + @Test void generationsWrapAround() { assertTrue(KeyProvider.isNewer(1, 0)); diff --git a/webrtc/src/test/resources/dev/onvoid/webrtc/e2ee/sframe-interop.mjs b/webrtc/src/test/resources/dev/onvoid/webrtc/e2ee/sframe-interop.mjs index 97bad4b3d..f7bcd072a 100644 --- a/webrtc/src/test/resources/dev/onvoid/webrtc/e2ee/sframe-interop.mjs +++ b/webrtc/src/test/resources/dev/onvoid/webrtc/e2ee/sframe-interop.mjs @@ -11,7 +11,7 @@ // jsKey the key this side encrypts with // frame // -// Prints "vector ok|fail", "decrypt ok|fail " and +// Prints "format ", "vector ok|fail", "decrypt ok|fail " and // "sealed ", then "done". import { readFileSync } from 'node:fs'; @@ -23,6 +23,8 @@ const sframe = await import(pathToFileURL(moduleFile).href); const hex = (s) => Uint8Array.from(s.match(/../g) || [], (b) => parseInt(b, 16)); const toHex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join(''); +console.log(`format ${sframe.FORMAT}`); + // The SFrame vectors of RFC 9605, Appendix C.3. let index = 0;