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