From 86642eadb655ef6ba466559ace6486562f44835c Mon Sep 17 00:00:00 2001 From: Alex Andres Date: Sun, 8 Nov 2026 19:59:52 +0100 Subject: [PATCH 1/2] feat: add end-to-end encryption in the SFrame format A KeyProvider in dev.onvoid.webrtc.e2ee encrypts and decrypts encoded frames as RFC 9605 SFrame: participant keys with generations and rotation, a key ID per sent stream, replay protection, defined handling of unknown keys and failed frames, and codec layouts for VP8, VP9, AV1 and audio. PeerOptions, Whip and Whep take it as e2ee(keys). Transforms can keep their frames from encoded-frame observers; the native router enforces it, and MediaRecorder refuses such tracks unless the key provider allows plaintext recording. The guide specifies the frame format, and a WebCrypto implementation for browsers is published with the docs and tested against Java. --- README.md | 3 +- docs/.vitepress/sidebar.ts | 1 + docs/guide/advanced/encoded-transforms.md | 10 +- docs/guide/advanced/end-to-end-encryption.md | 251 ++++++ docs/guide/client-api-design.md | 1 + docs/guide/client-api.md | 12 +- docs/guide/examples.md | 4 +- docs/guide/media/media-recording.md | 15 +- docs/public/e2ee/webrtc-java-sframe.js | 837 ++++++++++++++++++ .../examples/EncryptedRecordingExample.java | 188 +--- .../main/cpp/include/JNI_AllocationFault.h | 24 + .../src/main/cpp/include/JNI_NativeApi.h | 8 + .../src/main/cpp/include/JNI_RTCRtpReceiver.h | 8 +- .../src/main/cpp/include/JNI_RTCRtpSender.h | 8 +- .../main/cpp/include/api/EncodedFrameRouter.h | 10 +- .../cpp/include/api/EncodedFrameTransformer.h | 8 +- .../src/main/cpp/src/JNI_AllocationFault.cpp | 52 ++ webrtc-jni/src/main/cpp/src/JNI_NativeApi.cpp | 10 + .../src/main/cpp/src/JNI_RTCRtpReceiver.cpp | 6 +- .../src/main/cpp/src/JNI_RTCRtpSender.cpp | 6 +- .../main/cpp/src/api/EncodedFrameRouter.cpp | 15 +- .../cpp/src/api/EncodedFrameTransformer.cpp | 9 +- .../webrtc/media/recorder/MediaRecorder.java | 31 +- .../media/recorder/MediaRecorderTest.java | 81 ++ .../webrtc/RTCEncodedFrameTransformer.java | 19 + .../dev/onvoid/webrtc/RTCRtpReceiver.java | 12 +- .../java/dev/onvoid/webrtc/RTCRtpSender.java | 12 +- .../dev/onvoid/webrtc/client/PeerImpl.java | 60 +- .../dev/onvoid/webrtc/client/PeerOptions.java | 46 +- .../onvoid/webrtc/client/RemoteTracks.java | 35 +- .../java/dev/onvoid/webrtc/client/Whep.java | 15 + .../java/dev/onvoid/webrtc/client/Whip.java | 15 + .../dev/onvoid/webrtc/e2ee/CipherSuite.java | 139 +++ .../dev/onvoid/webrtc/e2ee/CryptoEvent.java | 103 +++ .../dev/onvoid/webrtc/e2ee/CryptoFailure.java | 74 ++ .../onvoid/webrtc/e2ee/CryptoListener.java | 43 + .../dev/onvoid/webrtc/e2ee/CryptoStats.java | 79 ++ .../dev/onvoid/webrtc/e2ee/FrameCryptor.java | 224 +++++ .../onvoid/webrtc/e2ee/FrameDecryptor.java | 118 +++ .../onvoid/webrtc/e2ee/FrameEncryptor.java | 101 +++ .../dev/onvoid/webrtc/e2ee/FrameFormat.java | 195 ++++ .../dev/onvoid/webrtc/e2ee/KeyProvider.java | 683 ++++++++++++++ .../dev/onvoid/webrtc/e2ee/ReplayWindow.java | 123 +++ .../java/dev/onvoid/webrtc/e2ee/SFrame.java | 436 +++++++++ .../dev/onvoid/webrtc/internal/NativeApi.java | 18 + webrtc/src/main/java/module-info.java | 1 + .../java/dev/onvoid/webrtc/E2eeCallTests.java | 356 ++++++++ .../dev/onvoid/webrtc/client/E2eeTests.java | 215 +++++ .../webrtc/e2ee/BrowserInteropTests.java | 198 +++++ .../onvoid/webrtc/e2ee/FrameCryptorTests.java | 540 +++++++++++ .../dev/onvoid/webrtc/e2ee/SFrameTests.java | 221 +++++ .../webrtc/internal/AllocationFault.java | 23 + .../webrtc/e2ee/rfc9605-test-vectors.txt | 299 +++++++ .../dev/onvoid/webrtc/e2ee/sframe-interop.mjs | 93 ++ 54 files changed, 5882 insertions(+), 212 deletions(-) create mode 100644 docs/guide/advanced/end-to-end-encryption.md create mode 100644 docs/public/e2ee/webrtc-java-sframe.js create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CipherSuite.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoEvent.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoFailure.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoListener.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoStats.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameCryptor.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameDecryptor.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameEncryptor.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameFormat.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/e2ee/KeyProvider.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/e2ee/ReplayWindow.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/e2ee/SFrame.java create mode 100644 webrtc/src/test/java/dev/onvoid/webrtc/E2eeCallTests.java create mode 100644 webrtc/src/test/java/dev/onvoid/webrtc/client/E2eeTests.java create mode 100644 webrtc/src/test/java/dev/onvoid/webrtc/e2ee/BrowserInteropTests.java create mode 100644 webrtc/src/test/java/dev/onvoid/webrtc/e2ee/FrameCryptorTests.java create mode 100644 webrtc/src/test/java/dev/onvoid/webrtc/e2ee/SFrameTests.java create mode 100644 webrtc/src/test/resources/dev/onvoid/webrtc/e2ee/rfc9605-test-vectors.txt create mode 100644 webrtc/src/test/resources/dev/onvoid/webrtc/e2ee/sframe-interop.mjs diff --git a/README.md b/README.md index aafde85c9..927b23255 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,8 @@ The library provides a comprehensive set of Java classes that map to the WebRTC - **[Hardware codecs](https://jrtc.dev/guide/advanced/video-codecs#hardware-encoding)** - H.264, H.265, VP9 and AV1 on the GPU with NVENC/NVDEC, Media Foundation, VA-API and VideoToolbox, falling back to software - **[Custom codecs](https://jrtc.dev/guide/advanced/video-codecs#adding-a-codec)** - Plug in video encoders and decoders written in Java, or limit the codecs a factory offers -- **[End-to-end encryption](https://jrtc.dev/guide/advanced/encoded-transforms)** - Read, change or drop encoded audio and video frames, like insertable streams in the browser +- **[End-to-end encryption](https://jrtc.dev/guide/advanced/end-to-end-encryption)** - SFrame (RFC 9605) with key management, key rotation and replay protection, interoperable with browsers +- **[Encoded transforms](https://jrtc.dev/guide/advanced/encoded-transforms)** - Read, change or drop encoded audio and video frames, like insertable streams in the browser - **[Pre-encoded media](https://jrtc.dev/guide/advanced/encoded-transforms#injecting-encoded-frames)** - Send a camera's H.264 stream or a recording without re-encoding it **Optional modules** diff --git a/docs/.vitepress/sidebar.ts b/docs/.vitepress/sidebar.ts index 6613c3863..6b7da27dd 100644 --- a/docs/.vitepress/sidebar.ts +++ b/docs/.vitepress/sidebar.ts @@ -78,6 +78,7 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { items: [ { text: 'Field Trials', link: '/advanced/field-trials' }, { text: 'Encoded Transforms', link: '/advanced/encoded-transforms' }, + { text: 'End-to-End Encryption', link: '/advanced/end-to-end-encryption' }, { text: 'Video Codecs', link: '/advanced/video-codecs' }, { text: 'Audio Codecs', link: '/advanced/audio-codecs' }, ], diff --git a/docs/guide/advanced/encoded-transforms.md b/docs/guide/advanced/encoded-transforms.md index fbcf48eaa..5323e23f9 100644 --- a/docs/guide/advanced/encoded-transforms.md +++ b/docs/guide/advanced/encoded-transforms.md @@ -7,7 +7,7 @@ This guide explains how to read and change the encoded frames of a call as they - Dropping frames - What each frame tells about itself - Asking for key frames -- End-to-end encryption as a worked example +- What end-to-end encryption needs of a transform - Threading and performance - Sending frames that are already encoded through an injector @@ -105,10 +105,12 @@ Both do nothing for audio, and `generateKeyFrame()` nothing before the connectio ## End-to-End Encryption -A complete example with AES-GCM, on the transforms of the client API's peer options, is in [`EncryptedRecordingExample`](https://github.com/devopvoid/webrtc-java/blob/master/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/EncryptedRecordingExample.java). Two points matter for any encrypting transform: +[End-to-End Encryption](/guide/advanced/end-to-end-encryption) builds on these transforms: a `KeyProvider` makes the encryptors and decryptors, in the SFrame format of RFC 9605, and takes care of the keys of every participant, key rotation, replay protection and frames that fail. Use it rather than a transform of your own, which would have to settle all of that, and a frame format browsers can implement too. Two points matter for any encrypting transform that is written anyway: -- **Keep the codec header in the clear.** The packetizer and depacketizer read the start of each frame: a VP8 receiver finds key frames and the frame size in the first bytes. Browsers leave 10 bytes of a VP8 key frame, 3 of a VP8 delta frame and 1 of an Opus frame unencrypted, and authenticate them as associated data instead. H.264 is split at its NAL unit start codes before it is sent, so encrypting it whole breaks the packetizer; prefer VP8, VP9 or AV1 for encrypted calls, or leave the NAL unit headers in the clear. -- **Make each frame self-contained.** Frames are lost, so each needs what it takes to be decrypted, such as its IV, and a receiver must drop a frame that fails to authenticate rather than pass it on. +- **Keep the codec header in the clear.** The packetizer and depacketizer read the start of some frames: a VP8 receiver finds key frames and the frame size in the first bytes, and the AV1 packetizer splits frames into their OBUs. Browsers leave 10 bytes of a VP8 key frame, 3 of a VP8 delta frame and 1 of an Opus frame unencrypted, and authenticate them as associated data instead. H.264 is split at its NAL unit start codes before it is sent, so encrypting it whole breaks the packetizer. +- **Make each frame self-contained.** Frames are lost, so each needs what it takes to be decrypted, such as its nonce, and a receiver must drop a frame that fails to authenticate rather than pass it on. + +A transform that protects what passes through it can keep observers of the encoded frames, such as a [`MediaRecorder`](/guide/media/media-recording), from seeing it in the clear by returning false from `allowsPlaintextObservers()`. ## Threading and Performance diff --git a/docs/guide/advanced/end-to-end-encryption.md b/docs/guide/advanced/end-to-end-encryption.md new file mode 100644 index 000000000..5e51dd3e5 --- /dev/null +++ b/docs/guide/advanced/end-to-end-encryption.md @@ -0,0 +1,251 @@ +# End-to-End Encryption + +This guide explains how to encrypt a call end to end, so that the media servers, TURN servers and SFUs between the participants forward media they cannot read. It covers: + +- Encrypting a call with the client API, or with senders and receivers directly +- Participants, keys and key generations +- Rotating keys +- What happens to frames that cannot be encrypted or decrypted +- Replay protection +- The codecs that can be encrypted +- Recording an encrypted call +- Encrypting a call with a browser +- The frame format, as a specification for other implementations + +The [encoded transforms](/guide/advanced/encoded-transforms) are where the encryption happens. `dev.onvoid.webrtc.e2ee` adds what an encryption algorithm alone does not settle: the [SFrame](https://www.rfc-editor.org/rfc/rfc9605) format of RFC 9605, a key provider that holds the keys of every participant with their key IDs and generations, separate keys for every stream a participant sends, protection against replayed frames, a defined behavior for every frame that fails, and a recording policy. + +## Encrypting a Call + +Every participant of a call has an ID, unique within the call, and a `KeyProvider` that holds its own key and the keys of the others. Getting the keys to the others is up to the application (see [Distributing Keys](#distributing-keys)). + +```java +KeyProvider keys = KeyProvider.builder(myId) + .listener(event -> log.warning("Frames dropped: " + event)) + .build(); + +byte[] myKey = keys.generateKey(); +keys.setEncryptionKey(0, myKey); +// Send (myId, 0, myKey) to the others, over a channel the servers cannot read. + +// For every key another participant sends: +keys.setDecryptionKey(theirId, theirGeneration, theirKey); +``` + +With the [client API](/guide/client-api), the key provider goes into the peer options. The peer then encrypts every frame it sends and decrypts every frame it receives, from the first one: + +```java +Peer peer = rtc.createPeer(PeerOptions.builder() + .signaling(signaling) + .e2ee(keys) + .build()); +``` + +`Whip.Builder` and `Whep.Builder` take `e2ee(keys)` as well. End-to-end encryption brings its own transforms, so the options take no `sendTransform` or `receiveTransform` besides. + +Without the client API, every sender and receiver takes a transform of the key provider. Set them before negotiating, so that no frame leaves unencrypted and the encoder needs no restart: + +```java +RTCRtpSender sender = peerConnection.addTrack(videoTrack, List.of("stream")); +sender.setTransform(keys.createEncryptor(sender::generateKeyFrame)); + +// Once the remote description is set: +for (RTCRtpReceiver receiver : peerConnection.getReceivers()) { + receiver.setTransform(keys.createDecryptor(receiver::requestKeyFrame)); +} +``` + +The argument of `createEncryptor` and `createDecryptor` asks for a key frame when one helps (see [Key Frames](#key-frames)). Both work without one too. + +## Participants and Keys + +A participant ID is a number from 0 to 232-1, which every participant of the call knows the others by, such as the index of a member in an [MLS](https://www.rfc-editor.org/rfc/rfc9420) group or a number the application's server hands out. Each participant encrypts with a key of its own, which the others decrypt with. This is the "sender keys" scheme of RFC 9605, Section 5.1, and it follows the rule of the RFC that a key is only ever used for encryption by one participant: `setDecryptionKey` refuses the local participant's ID. + +Every key belongs to a generation, 0 to 255, which goes up with each new key of a participant and wraps around after 255. A receiver keeps a participant's generations side by side, so a new key can be handed out before it is used. `generateKey()` makes a random key as long as the cipher suite's hash output; any key of at least 16 bytes works. + +::: warning +Use a key for one call only, and never give it to a second `KeyProvider`. A key provider counts the frames it encrypts under each key, and a new one starts over, which would encrypt two frames under the same key and nonce. +::: + +### Distributing Keys + +The keys have to reach the other participants over a channel that the servers forwarding the media cannot read. That channel, and how participants authenticate each other on it, decides how secure the call is. Common choices are an MLS group, whose exporter gives a key per epoch (`MLS-Exporter("SFrame 1.0 Base Key", "", 16)`, RFC 9605, Section 5.2), or a messaging channel that is itself end-to-end encrypted. The signaling channel of the call is only good enough if the signaling server is trusted not to read it. + +### Rotating Keys + +A participant changes its key when someone joins or leaves the call, so that the newcomer cannot decrypt what was sent before, and the one who left cannot decrypt what is sent after. To rotate: + +1. Make a new key with the next generation, and send it to the others, who `setDecryptionKey` it next to the old one. +2. Once they have it, acknowledged or after a timeout, `setEncryptionKey` it. Frames go out with the new key from the next one on. +3. Nothing more is needed on the receiving side. A receiver retires a participant's older generations 5 seconds after the first frame of a newer one decrypted (`Builder.keyRetention`), which covers the frames that were on their way during the switch. `removeDecryptionKey` and `removeParticipant` remove keys right away. + +A video sender asks its encoder for a key frame with the first frame under a new key, so that a participant who has just joined, and has no key for the frames before, does not have to wait for the next one. + +### Streams + +Every RTP stream a participant sends, its audio, its video and every simulcast layer, gets a context of its own, and with it a key ID and a derived key of its own. Streams count their frames independently and never share a key and nonce, without the application having to give them different keys. One encryptor may serve several senders, as the client API's peer options do, since it tells the streams apart by their SSRC. + +## Failed Frames + +A frame that cannot be encrypted is dropped, never sent in the clear. A received frame that does not decrypt is dropped, never passed to the decoder. Each has a reason, a `CryptoFailure`: + +| Failure | Sending or receiving | Means | +| --- | --- | --- | +| `MISSING_KEY` | sending | The key provider has no encryption key, or no longer. | +| `UNKNOWN_KEY` | receiving | The key the frame was encrypted with is not there: not arrived yet, removed, or retired. | +| `AUTHENTICATION` | receiving | The frame was changed on the way, or encrypted with another key of the same key ID. | +| `REPLAY` | receiving | A frame with the same counter was decrypted before, or the frame is older than the replay window. | +| `MALFORMED` | both | A received frame is no SFrame ciphertext, as when the other side does not encrypt, or a frame to send is too short for its codec's header. | +| `UNSUPPORTED_CODEC` | both | H.264 or H.265, which the frame format does not cover (see [Codecs](#codecs)). | + +A stream whose key has not arrived yet drops its frames until it has, and then decrypts again from the first frame whose key is there. Frames are not held back to wait for a key, since a frame is only valid while its transform runs. + +The listener of the key provider hears of a stream when it begins to fail, and again only when it fails for another reason or after frames went through in between, so a stream without its key does not report each of its frames. The event says which participant and key generation the frames need, which is what a request for a missing key takes: + +```java +KeyProvider keys = KeyProvider.builder(myId) + .listener(event -> { + if (event.getFailure() == CryptoFailure.UNKNOWN_KEY) { + keyChannel.requestKey(event.getParticipant(), event.getGeneration()); + } + }) + .build(); +``` + +The listener runs on the transform thread of the sender or receiver, so it should hand anything slow to another thread. `getStats()` counts every frame encrypted, decrypted and dropped, by reason. With the client API, failed frames go to the listener only, not to the peer's `onError` handlers. + +### Key Frames + +A decoder cannot decode the video frames that follow one it never got, so a video receiver that dropped frames asks the remote sender for a key frame as soon as frames decrypt again, at most twice a second. A video sender asks its own encoder for one when it starts to use a new key, and when it sends again after dropping frames for want of a key. + +## Replay Protection + +A receiver accepts each counter of a stream once: a frame that repeats the counter of one already decrypted, as a server that records and resends frames would produce, is dropped, and so is a frame older than the replay window. The window reaches 128 frames back by default, several seconds of any stream and far more than any reordering. `Builder.replayWindow(frames)` changes it, and 0 turns the protection off. A counter only counts as seen once its frame authenticated, so forged frames cannot move the window. + +## Codecs + +The frame format covers VP8, VP9, AV1 and every audio codec. WebRTC's packetizers and depacketizers read parts of some frames, so the format keeps those parts readable and authenticates them instead: + +- **VP8** keeps its payload header in the clear: 10 bytes of a key frame, 3 of a delta frame. The receiver finds key frames and the frame size there. +- **Opus** keeps its first byte, the TOC byte, in the clear, as browsers do. +- **AV1** is split into OBUs by its packetizer, so the encrypted frame travels as a single OBU: a sequence header for a key frame, which is how the receiver recognizes one, and a frame OBU otherwise. +- **VP9** and other audio codecs are encrypted whole. + +H.264 and H.265 frames are split at their start codes before they are sent, which a ciphertext would contain anywhere, so they are dropped with `UNSUPPORTED_CODEC`. Prefer VP8, VP9 or AV1 for encrypted calls with `setCodecPreferences` on the transceivers, or with `videoCodecs("VP8", "VP9", "AV1")` of the [WHIP and WHEP](/guide/client-api#whip-and-whep) builders. This matters on macOS in particular, where WebRTC prefers H.264 through VideoToolbox. + +## Recording + +A [`MediaRecorder`](/guide/media/media-recording) records a sender's frames before its transform and a receiver's frames after it, so it would store an encrypted call in the clear. Whether that may happen is decided where the encryption is set up: the transforms of a key provider keep their frames from every observer of encoded frames, the recorder included, and `MediaRecorder.addTrack` refuses their senders, receivers and tracks with an `IllegalStateException`. A transform set on a track that is already being recorded keeps the recorder from any further frame of it. + +An application that records its calls on purpose says so: + +```java +KeyProvider keys = KeyProvider.builder(myId) + .allowPlaintextRecording(true) + .build(); +``` + +A recording made this way is decrypted media on the disk of one participant, outside the protection of the call. Other transforms decide for themselves through `RTCEncodedFrameTransformer.allowsPlaintextObservers()`, which is true unless they say otherwise. + +## Browsers + +Browsers have no built-in SFrame support yet, but they run the same format with [`RTCRtpScriptTransform`](https://www.w3.org/TR/webrtc-encoded-transform/) and WebCrypto. [`webrtc-java-sframe.js`](/e2ee/webrtc-java-sframe.js) implements it, with a `KeyProvider` that works like the Java one. webrtc-java's tests run it in Node.js against the RFC's test vectors, and check that frames of every codec layout and cipher suite encrypted on either side decrypt on the other. + +The transforms run in a worker: + +```js +// worker.js +import { KeyProvider, attach } from './webrtc-java-sframe.js'; + +const keys = new KeyProvider({ participant: 2 }); + +onmessage = ({ data }) => { + if (data.encryptionKey) { + keys.setEncryptionKey(data.generation, data.encryptionKey); + } + else { + keys.setDecryptionKey(data.participant, data.generation, data.decryptionKey); + } +}; + +onrtctransform = ({ transformer }) => attach(keys, transformer); +``` + +and the page sets them on its senders and receivers, with `side` telling which is which: + +```js +const worker = new Worker('worker.js', { type: 'module' }); + +worker.postMessage({ generation: 0, encryptionKey: myKey }); +sender.transform = new RTCRtpScriptTransform(worker, { side: 'send' }); +receiver.transform = new RTCRtpScriptTransform(worker, { side: 'receive' }); +``` + +`attach` asks for key frames through the transformer as the Java side does. Browsers that predate `RTCRtpScriptTransform` need the older `createEncodedStreams()` instead, whose frames the encryptor's and decryptor's `transformFrame(frame, controller)` take just the same. + +## Frame Format + +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. + +### 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: + +``` + 63 40 39 8 7 0 ++----------------+-----------------------------+------------+ +| context (24) | participant (32) | generation | ++----------------+-----------------------------+------------+ +``` + +- **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. + +### Counters + +Each stream counts its frames from 0, one counter value (CTR) per frame, and never resets the counter, not even when the key changes. A receiver accepts a counter at most once per KID, and only if it is at most the replay window below the highest counter it accepted. It marks a counter as seen only after the frame authenticated. + +### Frame Layout + +A protected frame is the codec's clear prefix followed by an SFrame ciphertext, the header, the ciphertext and the tag: + +``` ++--------------+---------------+------------------------+-----+ +| clear prefix | SFrame header | encrypted frame data | tag | ++--------------+---------------+------------------------+-----+ +``` + +The clear prefix is also the `metadata` that SFrame authenticates along with its header, and the plaintext is the rest of the frame: + +| Codec (MIME type) | Clear prefix | +| --- | --- | +| `video/VP8` | the first 10 bytes of a key frame, the first 3 of a delta frame | +| `video/VP9` | none | +| `video/AV1` | one OBU header: `0x08` (OBU_SEQUENCE_HEADER) for a key frame, `0x30` (OBU_FRAME) otherwise; the plaintext is the whole frame | +| `audio/opus` | the first byte | +| any other `audio/*` | none | +| anything else | not covered: the frame is dropped | + +An AV1 frame arrives with its OBU header changed by the depacketizer, which sets the size bit (`0x02`) and inserts the OBU's size as a LEB128 value. A receiver accepts the OBU header with or without the size bit, skips the size, and authenticates the header without the size bit: `0x08` or `0x30`. It takes a VP8 frame for a key frame if its first byte has the lowest bit clear, as the depacketizer does. + +### Receiving + +A receiver drops a frame, rather than passing it to the decoder, when its codec is not covered, it is shorter than its clear prefix, its header is not in the minimal encoding of RFC 9605, Section 4.3, it has no key for the KID's participant and generation, its counter fails the replay check, or it does not authenticate. + +## Security Considerations + +- SFrame protects the media, not its metadata. The servers still see who sends, at what rate and with which key IDs, which tell the participant IDs and key generations, and they see the clear prefixes: whether a VP8 frame is a key frame and its size, and the Opus TOC byte. +- Every participant who has a key can encrypt frames that pass for that key's participant, since SFrame keys are symmetric (RFC 9605, Section 7.2). Telling participants apart is up to the key distribution. +- Short tags (the `AES_128_CTR_HMAC_SHA256_*` suites) make forgeries more likely; keep the replay window on with them. +- The keys are held in Java memory for as long as the key provider has them. + +## Related + +- [Encoded Transforms](/guide/advanced/encoded-transforms) +- [Media Recording](/guide/media/media-recording) +- [Client API](/guide/client-api) +- [RFC 9605: Secure Frame (SFrame)](https://www.rfc-editor.org/rfc/rfc9605) diff --git a/docs/guide/client-api-design.md b/docs/guide/client-api-design.md index e435c281a..9f05ed240 100644 --- a/docs/guide/client-api-design.md +++ b/docs/guide/client-api-design.md @@ -301,6 +301,7 @@ public final class PeerOptions { public Builder channelReceiveLimit(long bytes); // unhandled messages of a data channel, default 16 MiB public Builder sendTransform(RTCEncodedFrameTransformer transform); // every sender, from its first frame public Builder receiveTransform(RTCEncodedFrameTransformer transform); // every receiver, from its first frame + public Builder e2ee(KeyProvider keys); // SFrame encryption of both, instead of the transforms public Builder configure(Consumer customizer); // anything else RTCConfiguration has public PeerOptions build(); } diff --git a/docs/guide/client-api.md b/docs/guide/client-api.md index 2eef44fdd..42426ef8c 100644 --- a/docs/guide/client-api.md +++ b/docs/guide/client-api.md @@ -687,6 +687,15 @@ Peer peer = rtc.createPeer(PeerOptions.builder() The peer sets the send transform on each sender as its track is added, before negotiation, so no frame leaves without it and the encoder needs no restart. It sets the receive transform on each receiver before `onTrack` hands out the track, so the transform is in place before the first frame arrives. If installing the receive transform fails, the peer stops that track's transceiver and reports the failure through `onError`; the track is neither listed in `remoteTracks()` nor delivered through `onTrack`. If the receive path cannot be stopped, the peer closes. The builders of [WHIP and WHEP](#whip-and-whep) take them too, `Whip`'s as `sendTransform(...)`, `Whep`'s as `receiveTransform(...)`. +For end-to-end encryption, `e2ee(keys)` takes the place of both transforms: every sender gets an encryptor and every remote track a decryptor of the [key provider](/guide/advanced/end-to-end-encryption), which also takes care of key rotation, replay protection, frames that fail and key frame requests: + +```java +PeerOptions.builder() + .signaling(signaling) + .e2ee(keys) + .build(); +``` + A single sender or remote track takes a transform of its own, in place of the peer's, and `null` removes it: ```java @@ -705,7 +714,7 @@ remoteTrack.asVideo().requestKeyFrame(); // asks the remote sender for one `generateKeyFrame()` does nothing for an audio sender, and nothing before the peer is negotiated, as the stream starts with a key frame anyway. `requestKeyFrame()` fails once the track ended. -Transforms run on a thread of each sender and receiver, not on the peer's event thread. A frame a transform throws on is dropped rather than passed on, so a failed encryption never sends a frame in the clear. The first such failure of each sender or receiver goes to the peer's `onError` handlers. The [`EncryptedRecordingExample`](https://github.com/devopvoid/webrtc-java/blob/master/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/EncryptedRecordingExample.java) encrypts a call with AES-GCM this way. +Transforms run on a thread of each sender and receiver, not on the peer's event thread. A frame a transform throws on is dropped rather than passed on, so a failed encryption never sends a frame in the clear. The first such failure of each sender or receiver goes to the peer's `onError` handlers. The [`EncryptedRecordingExample`](https://github.com/devopvoid/webrtc-java/blob/master/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/EncryptedRecordingExample.java) encrypts a call with `e2ee(keys)` and records it. ## Data Channels @@ -876,6 +885,7 @@ Requests go through Java's `HttpClient`, with the default `SSLContext` and the H | `alwaysOfferVideo()` | Video in the offer even without a video track, WHIP only, for endpoints that refuse an offer without video. | | `simulcast()`, `simulcast(Encoding...)` | The video track in layers, as simulcast, WHIP only: three by default (`f`, `h`, `q`), or two or three given, the largest first. | | `sendTransform(RTCEncodedFrameTransformer)` | The [encoded transform](#encoded-transforms) of every frame sent, WHIP only, in place before the offer goes out. | +| `e2ee(KeyProvider)` | [End-to-end encryption](/guide/advanced/end-to-end-encryption) of every frame sent (WHIP) or received (WHEP), in place of the transforms. | | `receiveTransform(RTCEncodedFrameTransformer)` | The [encoded transform](#encoded-transforms) of every frame received, WHEP only, in place before the first frame, also for a counter-offer. | | `timeout(Duration)` | How long the session may take to be connected, and its deletion to be answered. | diff --git a/docs/guide/examples.md b/docs/guide/examples.md index 2a236fbf2..13b8489aa 100644 --- a/docs/guide/examples.md +++ b/docs/guide/examples.md @@ -180,10 +180,10 @@ mvn exec:java -D"exec.mainClass=dev.onvoid.webrtc.examples.JavaFxCameraExample" ## Encrypted Recording -The [`EncryptedRecordingExample`](https://github.com/devopvoid/webrtc-java/blob/master/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/EncryptedRecordingExample.java) encrypts a call end to end with encoded frame transforms, with the [Client API](/guide/client-api#encoded-transforms), and records what the receiving side decrypted into a media file. See the [Encoded Transforms](/guide/advanced/encoded-transforms) and [Media Recording](/guide/media/media-recording) guides for the APIs it uses. +The [`EncryptedRecordingExample`](https://github.com/devopvoid/webrtc-java/blob/master/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/EncryptedRecordingExample.java) encrypts a call end to end with a key provider of [End-to-End Encryption](/guide/advanced/end-to-end-encryption), with the [Client API](/guide/client-api#encoded-transforms), and records what the receiving side decrypted into a media file. See the [Encoded Transforms](/guide/advanced/encoded-transforms) and [Media Recording](/guide/media/media-recording) guides for the APIs it uses. **Key features demonstrated:** -- Encrypting every encoded audio and video frame with AES-GCM in the send transform of the peer options, and decrypting it in the receive transform, from the first frame on +- Encrypting every encoded audio and video frame in the SFrame format with `e2ee(keys)` of the peer options, and decrypting it, from the first frame on - Keeping the codec header of each frame in the clear for the packetizer, and authenticating it instead - Dropping frames that fail to encrypt or to authenticate, rather than passing them on - Recording the remote tracks with a `MediaRecorder`, without decoding or re-encoding diff --git a/docs/guide/media/media-recording.md b/docs/guide/media/media-recording.md index 6ce173d9e..1cd90e9f3 100644 --- a/docs/guide/media/media-recording.md +++ b/docs/guide/media/media-recording.md @@ -157,4 +157,17 @@ System.out.println("Queue peak: " + stats.getMaxQueuedBytes() + " bytes"); ## Recording an Encrypted Call -A sender's frames are recorded before an [encoded transform](/guide/advanced/encoded-transforms) runs on them, and a receiver's after it. An end-to-end encrypted call is therefore recorded in the clear, on either side. [`EncryptedRecordingExample`](https://github.com/devopvoid/webrtc-java/blob/master/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/EncryptedRecordingExample.java) shows both together. +A sender's frames are recorded before an [encoded transform](/guide/advanced/encoded-transforms) runs on them, and a receiver's after it. An end-to-end encrypted call would therefore be recorded in the clear, on either side, so whether it may be is up to the encryption: + +- The transforms of a `KeyProvider` of [End-to-End Encryption](/guide/advanced/end-to-end-encryption) do not allow it by default. `addTrack` refuses their senders, receivers and tracks with an `IllegalStateException`, and a recording that is running gets no further frame of a track once such a transform is set on it. +- A key provider built with `allowPlaintextRecording(true)` allows it, for an application that records its calls on purpose: + +```java +KeyProvider keys = KeyProvider.builder(myId) + .allowPlaintextRecording(true) + .build(); +``` + +- A transform of your own allows it unless its `allowsPlaintextObservers()` returns false. + +A recording of an encrypted call holds the decrypted media, outside the protection of the call. [`EncryptedRecordingExample`](https://github.com/devopvoid/webrtc-java/blob/master/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/EncryptedRecordingExample.java) shows both together. diff --git a/docs/public/e2ee/webrtc-java-sframe.js b/docs/public/e2ee/webrtc-java-sframe.js new file mode 100644 index 000000000..418c75731 --- /dev/null +++ b/docs/public/e2ee/webrtc-java-sframe.js @@ -0,0 +1,837 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * The end-to-end encryption of webrtc-java for browsers: the SFrame frame + * format (RFC 9605) as the guide "End-to-End Encryption" specifies it, on + * WebCrypto alone. It runs in a worker with RTCRtpScriptTransform, and in + * Node.js, where webrtc-java's tests check it against the Java side. + * + * In a worker: + * + * import { KeyProvider, attach } from './webrtc-java-sframe.js'; + * + * const keys = new KeyProvider({ participant: 2 }); + * onmessage = async ({ data }) => { ...setEncryptionKey / setDecryptionKey... }; + * onrtctransform = ({ transformer }) => attach(keys, transformer); + * + * and on the page: + * + * sender.transform = new RTCRtpScriptTransform(worker, { side: 'send' }); + * receiver.transform = new RTCRtpScriptTransform(worker, { side: 'receive' }); + */ + +const subtle = globalThis.crypto.subtle; + +/** 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, + AES_128_CTR_HMAC_SHA256_64: 2, + AES_128_CTR_HMAC_SHA256_32: 3, + AES_128_GCM_SHA256_128: 4, + AES_256_GCM_SHA512_128: 5, +}); + +const SUITES = { + 1: { id: 1, gcm: false, hash: 'SHA-256', nh: 32, nka: 16, nk: 48, nt: 10 }, + 2: { id: 2, gcm: false, hash: 'SHA-256', nh: 32, nka: 16, nk: 48, nt: 8 }, + 3: { id: 3, gcm: false, hash: 'SHA-256', nh: 32, nka: 16, nk: 48, nt: 4 }, + 4: { id: 4, gcm: true, hash: 'SHA-256', nh: 32, nk: 16, nt: 16 }, + 5: { id: 5, gcm: true, hash: 'SHA-512', nh: 64, nk: 32, nt: 16 }, +}; + +/** Why a frame was dropped, as in the Java CryptoFailure. */ +export const Failure = Object.freeze({ + MISSING_KEY: 'MISSING_KEY', + UNKNOWN_KEY: 'UNKNOWN_KEY', + AUTHENTICATION: 'AUTHENTICATION', + REPLAY: 'REPLAY', + MALFORMED: 'MALFORMED', + UNSUPPORTED_CODEC: 'UNSUPPORTED_CODEC', + CONTEXTS_EXHAUSTED: 'CONTEXTS_EXHAUSTED', +}); + +const NONCE_LENGTH = 12; +const MAX_PARTICIPANT = 0xffffffff; +const MAX_CONTEXT = 0xffffff; + +/** OBU_FRAME and OBU_SEQUENCE_HEADER, no extension, no size field. */ +const AV1_WRAPPER = 6 << 3; +const AV1_KEY_WRAPPER = 1 << 3; + +const encoder = new TextEncoder(); +const KEY_LABEL = encoder.encode('SFrame 1.0 Secret key '); +const SALT_LABEL = encoder.encode('SFrame 1.0 Secret salt '); + +// ---------------------------------------------------------------- SFrame + +function concat(...parts) { + const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0)); + let offset = 0; + + for (const part of parts) { + out.set(part, offset); + offset += part.length; + } + + return out; +} + +function bigEndian(value, length) { + const out = new Uint8Array(length); + let v = BigInt(value); + + for (let i = length - 1; i >= 0; i--) { + out[i] = Number(v & 0xffn); + v >>= 8n; + } + + return out; +} + +function extendedLength(value) { + if (value < 8n) { + return 0; + } + + let length = 0; + + for (let v = value; v > 0n; v >>= 8n) { + length++; + } + + return length; +} + +/** Encodes an SFrame header (RFC 9605, Section 4.3); KID and CTR are BigInts. */ +export function encodeHeader(kid, ctr) { + const kidLength = extendedLength(kid); + const ctrLength = extendedLength(ctr); + + let config = kidLength === 0 ? Number(kid) << 4 : 0x80 | (kidLength - 1) << 4; + config |= ctrLength === 0 ? Number(ctr) : 0x08 | (ctrLength - 1); + + return concat(Uint8Array.of(config), bigEndian(kid, kidLength), bigEndian(ctr, ctrLength)); +} + +/** + * Parses an SFrame header in its minimal encoding. + * + * @returns {{kid: bigint, ctr: bigint, length: number} | null} + */ +export function parseHeader(bytes, offset = 0) { + if (bytes.length - offset < 1) { + return null; + } + + const config = bytes[offset]; + const values = []; + let position = offset + 1; + + for (const bits of [config >> 4, config & 0x0f]) { + if ((bits & 0x08) === 0) { + values.push(BigInt(bits & 0x07)); + continue; + } + + const size = (bits & 0x07) + 1; + + if (bytes.length - position < size || bytes[position] === 0) { + return null; + } + + let value = 0n; + + for (let i = 0; i < size; i++) { + value = value << 8n | BigInt(bytes[position + i]); + } + + if (value < 8n) { + return null; + } + + values.push(value); + position += size; + } + + return { kid: values[0], ctr: values[1], length: position - offset }; +} + +function label(prefix, kid, suite) { + return concat(prefix, bigEndian(kid, 8), bigEndian(suite.id, 2)); +} + +/** derive_key_salt of RFC 9605, Section 4.4.2. */ +export async function deriveKeySalt(suiteId, kid, baseKey) { + const suite = SUITES[suiteId]; + const ikm = await subtle.importKey('raw', baseKey, 'HKDF', false, ['deriveBits']); + const hkdf = (info) => ({ name: 'HKDF', hash: suite.hash, salt: new Uint8Array(0), info }); + + const key = new Uint8Array(await subtle.deriveBits(hkdf(label(KEY_LABEL, kid, suite)), ikm, suite.nk * 8)); + const salt = new Uint8Array(await subtle.deriveBits(hkdf(label(SALT_LABEL, kid, suite)), ikm, NONCE_LENGTH * 8)); + + return { key, salt }; +} + +/** The derived key of one KID: encrypt and decrypt of RFC 9605, Section 4.4. */ +export class SFrameKey { + + static async derive(suiteId, kid, baseKey) { + const { key, salt } = await deriveKeySalt(suiteId, kid, baseKey); + + return SFrameKey.of(suiteId, kid, key, salt); + } + + static async of(suiteId, kid, sframeKey, salt) { + const suite = SUITES[suiteId]; + const sframe = new SFrameKey(); + + sframe.suite = suite; + sframe.kid = kid; + sframe.salt = salt; + + if (suite.gcm) { + sframe.aesKey = await subtle.importKey('raw', sframeKey, 'AES-GCM', false, ['encrypt', 'decrypt']); + } + else { + sframe.aesKey = await subtle.importKey('raw', sframeKey.slice(0, suite.nka), 'AES-CTR', false, + ['encrypt', 'decrypt']); + sframe.authKey = await subtle.importKey('raw', sframeKey.slice(suite.nka), + { name: 'HMAC', hash: suite.hash }, false, ['sign']); + } + + return sframe; + } + + nonce(ctr) { + const nonce = this.salt.slice(); + const counter = bigEndian(ctr, 8); + + for (let i = 0; i < 8; i++) { + nonce[NONCE_LENGTH - 8 + i] ^= counter[i]; + } + + return nonce; + } + + /** Returns the header followed by the ciphertext and the tag. */ + async encrypt(ctr, metadata, plaintext) { + const header = encodeHeader(this.kid, ctr); + const body = await this.seal(this.nonce(ctr), concat(header, metadata), plaintext); + + return concat(header, body); + } + + /** Returns the plaintext, or null if the ciphertext did not authenticate. */ + async decrypt(ctr, header, metadata, ciphertext) { + return this.open(this.nonce(ctr), concat(header, metadata), ciphertext); + } + + async seal(nonce, aad, plaintext) { + const suite = this.suite; + + if (suite.gcm) { + return new Uint8Array(await subtle.encrypt( + { name: 'AES-GCM', iv: nonce, additionalData: aad, tagLength: 128 }, this.aesKey, plaintext)); + } + + const ct = new Uint8Array(await subtle.encrypt( + { name: 'AES-CTR', counter: concat(nonce, new Uint8Array(4)), length: 32 }, this.aesKey, plaintext)); + + return concat(ct, await this.tag(nonce, aad, ct)); + } + + async open(nonce, aad, ciphertext) { + const suite = this.suite; + + if (ciphertext.length < suite.nt) { + return null; + } + + if (suite.gcm) { + try { + return new Uint8Array(await subtle.decrypt( + { name: 'AES-GCM', iv: nonce, additionalData: aad, tagLength: 128 }, this.aesKey, ciphertext)); + } + catch (e) { + return null; + } + } + + const ct = ciphertext.subarray(0, ciphertext.length - suite.nt); + const expected = await this.tag(nonce, aad, ct); + const actual = ciphertext.subarray(ciphertext.length - suite.nt); + + let difference = 0; + + for (let i = 0; i < suite.nt; i++) { + difference |= expected[i] ^ actual[i]; + } + + if (difference !== 0) { + return null; + } + + return new Uint8Array(await subtle.decrypt( + { name: 'AES-CTR', counter: concat(nonce, new Uint8Array(4)), length: 32 }, this.aesKey, ct)); + } + + async tag(nonce, aad, ct) { + const authData = concat(bigEndian(aad.length, 8), bigEndian(ct.length, 8), bigEndian(this.suite.nt, 8), + nonce, aad, ct); + + return new Uint8Array(await subtle.sign('HMAC', this.authKey, authData)).slice(0, this.suite.nt); + } +} + +// ---------------------------------------------------------- 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); +} + +function codecOf(mimeType) { + const type = (mimeType || '').toLowerCase(); + + switch (type) { + case 'video/vp8': return 'vp8'; + case 'video/vp9': return 'vp9'; + case 'video/av1': return 'av1'; + case 'audio/opus': return 'opus'; + default: return type.startsWith('audio/') ? 'audio' : null; + } +} + +function clearBytes(codec, keyFrame) { + switch (codec) { + case 'vp8': return keyFrame ? 10 : 3; + case 'opus': return 1; + default: return 0; + } +} + +/** Where the SFrame ciphertext of an AV1 frame starts, or -1. */ +function av1PayloadOffset(frame) { + if (frame.length < 1) { + return -1; + } + + const header = frame[0] & ~0x02; + + if (header !== AV1_WRAPPER && header !== AV1_KEY_WRAPPER) { + return -1; + } + if ((frame[0] & 0x02) === 0) { + return 1; + } + + let size = 0; + let position = 1; + + for (let i = 0; i < 8; i++, position++) { + if (position >= frame.length) { + return -1; + } + + const b = frame[position]; + size += (b & 0x7f) * 2 ** (7 * i); + + if ((b & 0x80) === 0) { + position++; + + return size === frame.length - position ? position : -1; + } + } + + return -1; +} + +function isNewer(a, b) { + const distance = (a - b) & 0xff; + + return distance > 0 && distance < 128; +} + +class ReplayWindow { + + constructor(size) { + this.size = BigInt(size); + this.seen = new Uint32Array(size / 32); + this.highest = -1n; + } + + isFresh(ctr) { + if (ctr > this.highest) { + return true; + } + + return this.highest - ctr < this.size && !this.test(ctr); + } + + accept(ctr) { + if (ctr > this.highest) { + if (this.highest < 0n || ctr - this.highest >= this.size) { + this.seen.fill(0); + } + else { + for (let c = this.highest + 1n; c < ctr; c++) { + this.set(c, false); + } + } + + this.highest = ctr; + this.set(ctr, true); + return true; + } + if (this.highest - ctr >= this.size || this.test(ctr)) { + return false; + } + + this.set(ctr, true); + return true; + } + + test(ctr) { + const bit = Number(ctr % this.size); + + return (this.seen[bit >>> 5] & (1 << (bit & 31))) !== 0; + } + + set(ctr, value) { + const bit = Number(ctr % this.size); + + if (value) { + this.seen[bit >>> 5] |= 1 << (bit & 31); + } + else { + this.seen[bit >>> 5] &= ~(1 << (bit & 31)); + } + } +} + +function equalBytes(a, b) { + return a.length === b.length && a.every((v, i) => v === b[i]); +} + +/** + * The keys of a call, as the Java KeyProvider holds them: the local + * participant's encryption key and the others' decryption keys, each of a + * generation from 0 to 255. + */ +export class KeyProvider { + + /** + * @param {object} options + * @param {number} options.participant The local participant's ID, 0 to 2^32-1. + * @param {number} [options.cipherSuite] A CipherSuite value, AES-128-GCM by default. + * @param {number} [options.replayWindow] Frames, a multiple of 32; 0 turns it off. + * @param {number} [options.keyRetentionMs] How long older generations decrypt after a newer one did. + * @param {function} [options.onFailure] Hears of streams that begin to drop frames. + */ + constructor({ participant, cipherSuite = CipherSuite.AES_128_GCM_SHA256_128, replayWindow = 128, + keyRetentionMs = 5000, onFailure } = {}) { + if (!Number.isInteger(participant) || participant < 0 || participant > MAX_PARTICIPANT) { + throw new RangeError('A participant ID is from 0 to 2^32-1'); + } + if (!SUITES[cipherSuite]) { + throw new RangeError('Unknown cipher suite ' + cipherSuite); + } + + this.participant = participant; + this.suite = cipherSuite; + this.replayWindow = Math.ceil(replayWindow / 32) * 32; + this.keyRetentionMs = keyRetentionMs; + this.onFailure = onFailure; + this.encryptionKey = null; + this.participants = new Map(); + this.nextContext = 0; + this.stats = { encrypted: 0, decrypted: 0, dropped: {} }; + } + + /** A new random key, as long as the suite's hash output. */ + generateKey() { + return globalThis.crypto.getRandomValues(new Uint8Array(SUITES[this.suite].nh)); + } + + setEncryptionKey(generation, key) { + checkGeneration(generation); + this.encryptionKey = { generation, baseKey: copyKey(key), derived: new Map() }; + } + + removeEncryptionKey() { + this.encryptionKey = null; + } + + setDecryptionKey(participant, generation, key) { + checkGeneration(generation); + + if (participant === this.participant) { + throw new RangeError('A key of the local participant is only for encryption'); + } + + const baseKey = copyKey(key); + let remote = this.participants.get(participant); + + if (!remote) { + remote = { keys: new Array(256).fill(null), newest: -1 }; + this.participants.set(participant, remote); + } + + const current = remote.keys[generation]; + + if (current && equalBytes(current.baseKey, baseKey)) { + current.retireAt = 0; + return; + } + + remote.keys[generation] = { generation, baseKey, openers: new Map(), retireAt: 0 }; + } + + removeDecryptionKey(participant, generation) { + const remote = this.participants.get(participant); + + if (!remote || !remote.keys[generation]) { + return false; + } + + remote.keys[generation] = null; + return true; + } + + removeParticipant(participant) { + return this.participants.delete(participant); + } + + /** @param {function} [keyFrameRequest] Asks the sender for a key frame. */ + createEncryptor(keyFrameRequest) { + return new FrameEncryptor(this, keyFrameRequest); + } + + /** @param {function} [keyFrameRequest] Asks the remote side for a key frame. */ + createDecryptor(keyFrameRequest) { + return new FrameDecryptor(this, keyFrameRequest); + } + + allocateContext() { + return this.nextContext > MAX_CONTEXT ? -1 : this.nextContext++; + } + + decryptionKey(participant, generation, now) { + const remote = this.participants.get(participant); + const key = remote ? remote.keys[generation] : null; + + if (key && key.retireAt !== 0 && now > key.retireAt) { + remote.keys[generation] = null; + return null; + } + + return key; + } + + decryptedWith(participant, key, now) { + this.stats.decrypted++; + + const remote = this.participants.get(participant); + + if (!remote || remote.newest === key.generation) { + return; + } + if (remote.newest !== -1 && !isNewer(key.generation, remote.newest)) { + return; + } + + remote.newest = key.generation; + + for (const other of remote.keys) { + if (other && other !== key && other.retireAt === 0 && isNewer(key.generation, other.generation)) { + other.retireAt = now + this.keyRetentionMs; + } + } + } +} + +function checkGeneration(generation) { + if (!Number.isInteger(generation) || generation < 0 || generation > 255) { + throw new RangeError('A key generation is from 0 to 255'); + } +} + +function copyKey(key) { + const copy = new Uint8Array(key); + + if (copy.length < 16) { + throw new RangeError('A key has at least 16 bytes'); + } + + return copy; +} + +class FrameCryptor { + + constructor(keys, keyFrameRequest) { + this.keys = keys; + this.keyFrameRequest = keyFrameRequest; + this.streams = new Map(); + } + + stream(ssrc) { + let stream = this.streams.get(ssrc); + + if (!stream) { + stream = { ssrc, context: -1, counter: 0n, generation: -1, failure: null, interrupted: false, + keyFramePending: false, lastKeyFrameRequest: 0 }; + this.streams.set(ssrc, stream); + } + + return stream; + } + + fail(stream, failure, participant, generation, info) { + const dropped = this.keys.stats.dropped; + dropped[failure] = (dropped[failure] || 0) + 1; + + if (failure !== Failure.REPLAY) { + stream.interrupted = true; + } + if (stream.failure !== failure) { + stream.failure = failure; + + if (this.keys.onFailure) { + this.keys.onFailure({ failure, outgoing: this.outgoing, participant, generation, + ssrc: stream.ssrc, mimeType: info.mimeType }); + } + } + + return null; + } + + succeed(stream, info, needsKeyFrame) { + const wanted = needsKeyFrame || stream.interrupted; + + stream.failure = null; + stream.interrupted = false; + + if (!info.video || info.keyFrame) { + stream.keyFramePending = false; + return; + } + if (wanted) { + stream.keyFramePending = true; + } + + const now = Date.now(); + + if (stream.keyFramePending && this.keyFrameRequest && now - stream.lastKeyFrameRequest >= 500) { + stream.lastKeyFrameRequest = now; + + Promise.resolve().then(this.keyFrameRequest).catch(() => { }); + } + } + + /** + * Transforms one RTCEncodedVideoFrame or RTCEncodedAudioFrame in a + * TransformStream: enqueues it changed, or drops it. + */ + async transformFrame(frame, controller) { + const metadata = frame.getMetadata(); + const info = { + ssrc: metadata.synchronizationSource, + mimeType: metadata.mimeType, + video: frame.type !== undefined, + keyFrame: frame.type === 'key', + }; + + const out = await this.process(info, new Uint8Array(frame.data)); + + if (out) { + frame.data = out.buffer.slice(out.byteOffset, out.byteOffset + out.byteLength); + controller.enqueue(frame); + } + } +} + +class FrameEncryptor extends FrameCryptor { + + get outgoing() { + return true; + } + + /** + * @param {{ssrc: number, mimeType: string, video: boolean, keyFrame: boolean}} info + * @param {Uint8Array} frame + * @returns {Promise} The encrypted frame, or null to drop it. + */ + async process(info, frame) { + const keys = this.keys; + const stream = this.stream(info.ssrc); + + if (stream.context < 0) { + stream.context = keys.allocateContext(); + + if (stream.context < 0) { + return this.fail(stream, Failure.CONTEXTS_EXHAUSTED, keys.participant, -1, info); + } + } + + const key = keys.encryptionKey; + + if (!key) { + return this.fail(stream, Failure.MISSING_KEY, keys.participant, -1, info); + } + + const codec = codecOf(info.mimeType); + + if (!codec) { + return this.fail(stream, Failure.UNSUPPORTED_CODEC, keys.participant, key.generation, info); + } + + const clear = clearBytes(codec, info.keyFrame); + + if (frame.length < clear) { + return this.fail(stream, Failure.MALFORMED, keys.participant, key.generation, info); + } + + const prefix = codec === 'av1' + ? Uint8Array.of(info.keyFrame ? AV1_KEY_WRAPPER : AV1_WRAPPER) + : frame.slice(0, clear); + + let sframe = key.derived.get(stream.context); + + if (!sframe) { + sframe = SFrameKey.derive(keys.suite, keyId(stream.context, keys.participant, key.generation), + key.baseKey); + key.derived.set(stream.context, sframe); + } + + // Never reset, not even by a new key. + const ctr = stream.counter++; + const sealed = await (await sframe).encrypt(ctr, prefix, frame.subarray(clear)); + + const newKey = stream.generation !== -1 && stream.generation !== key.generation; + stream.generation = key.generation; + + keys.stats.encrypted++; + this.succeed(stream, info, newKey); + + return concat(prefix, sealed); + } +} + +class FrameDecryptor extends FrameCryptor { + + get outgoing() { + return false; + } + + /** + * @param {{ssrc: number, mimeType: string, video: boolean, keyFrame: boolean}} info + * @param {Uint8Array} frame + * @returns {Promise} The decrypted frame, or null to drop it. + */ + async process(info, frame) { + const keys = this.keys; + const stream = this.stream(info.ssrc); + const codec = codecOf(info.mimeType); + + if (!codec) { + return this.fail(stream, Failure.UNSUPPORTED_CODEC, -1, -1, info); + } + + let clear = 0; + let headerOffset; + let metadata; + + if (codec === 'av1') { + headerOffset = av1PayloadOffset(frame); + + if (headerOffset < 0) { + return this.fail(stream, Failure.MALFORMED, -1, -1, info); + } + + metadata = Uint8Array.of(frame[0] & ~0x02); + } + else { + clear = clearBytes(codec, info.keyFrame); + headerOffset = clear; + metadata = frame.subarray(0, clear); + } + + const header = headerOffset <= frame.length ? parseHeader(frame, headerOffset) : null; + + if (!header) { + 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 now = Date.now(); + + const key = keys.decryptionKey(participant, generation, now); + + if (!key) { + return this.fail(stream, Failure.UNKNOWN_KEY, participant, generation, info); + } + + let opener = key.openers.get(context); + + if (!opener) { + opener = SFrameKey.derive(keys.suite, header.kid, key.baseKey).then((sframe) => ({ + sframe, window: keys.replayWindow > 0 ? new ReplayWindow(keys.replayWindow) : null, + })); + key.openers.set(context, opener); + } + + const { sframe, window } = await opener; + + if (window && !window.isFresh(header.ctr)) { + return this.fail(stream, Failure.REPLAY, participant, generation, info); + } + + const headerBytes = frame.subarray(headerOffset, headerOffset + header.length); + const plaintext = await sframe.decrypt(header.ctr, headerBytes, metadata, + frame.subarray(headerOffset + header.length)); + + if (!plaintext) { + return this.fail(stream, Failure.AUTHENTICATION, participant, generation, info); + } + if (window && !window.accept(header.ctr)) { + return this.fail(stream, Failure.REPLAY, participant, generation, info); + } + + keys.decryptedWith(participant, key, now); + this.succeed(stream, info, false); + + return concat(frame.subarray(0, clear), plaintext); + } +} + +/** + * Pipes the frames of an RTCRtpScriptTransformer through an encryptor or + * decryptor of the key provider, by the transformer's options.side ('send' + * or 'receive'), with key frame requests going to the transformer. + */ +export function attach(keys, transformer) { + const send = transformer.options && transformer.options.side === 'send'; + const cryptor = send + ? keys.createEncryptor(() => transformer.generateKeyFrame()) + : keys.createDecryptor(() => transformer.sendKeyFrameRequest()); + + return transformer.readable + .pipeThrough(new TransformStream({ transform: (frame, controller) => cryptor.transformFrame(frame, controller) })) + .pipeTo(transformer.writable); +} diff --git a/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/EncryptedRecordingExample.java b/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/EncryptedRecordingExample.java index 1c08cfc43..82b89e079 100644 --- a/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/EncryptedRecordingExample.java +++ b/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/EncryptedRecordingExample.java @@ -19,24 +19,14 @@ import java.nio.ByteBuffer; import java.nio.file.Path; import java.nio.file.Paths; -import java.security.GeneralSecurityException; -import java.security.SecureRandom; import java.util.concurrent.CompletableFuture; import java.util.concurrent.Executors; import java.util.concurrent.ScheduledExecutorService; import java.util.concurrent.TimeUnit; import java.util.concurrent.atomic.AtomicInteger; -import java.util.concurrent.atomic.AtomicLong; -import java.util.logging.Level; import java.util.logging.Logger; -import javax.crypto.Cipher; -import javax.crypto.SecretKey; -import javax.crypto.spec.GCMParameterSpec; -import javax.crypto.spec.SecretKeySpec; -import dev.onvoid.webrtc.RTCEncodedFrame; -import dev.onvoid.webrtc.RTCEncodedVideoFrame; import dev.onvoid.webrtc.client.AudioMode; import dev.onvoid.webrtc.client.CustomAudio; import dev.onvoid.webrtc.client.CustomVideo; @@ -47,6 +37,7 @@ import dev.onvoid.webrtc.client.Signaling; import dev.onvoid.webrtc.client.SignalingPair; import dev.onvoid.webrtc.client.WebRtc; +import dev.onvoid.webrtc.e2ee.KeyProvider; import dev.onvoid.webrtc.media.recorder.MediaRecorder; import dev.onvoid.webrtc.media.recorder.MediaRecorderListener; import dev.onvoid.webrtc.media.recorder.MediaRecorderResult; @@ -59,13 +50,12 @@ *

* This example shows how to: *

    - *
  • Encrypt every encoded audio and video frame with AES-GCM in the send - * transform of the peer options, and decrypt it in the receive - * transform, so that whatever relays the media (an SFU, a TURN server) - * never sees it in the clear
  • - *
  • Keep the first bytes of each frame in the clear, where the RTP - * packetizer and depacketizer read the codec header, and authenticate - * them instead
  • + *
  • Encrypt every encoded audio and video frame end to end in the SFrame + * format, with a {@link KeyProvider} in the peer options, so that + * whatever relays the media (an SFU, a TURN server) never sees it in + * the clear
  • + *
  • Allow the receiving side to record what it decrypted, which a key + * provider refuses by default
  • *
  • Record the decrypted media of the remote tracks with a * {@link MediaRecorder}, without decoding or re-encoding it
  • *
@@ -74,9 +64,9 @@ * on each receiver before its track is handed out, so no frame leaves * unencrypted and none reaches the decoder still encrypted. *

- * Both peers live in this application and the key is simply shared between - * them; a real application exchanges it over its signaling channel, or better - * derives it with a key agreement such as MLS. + * Both peers live in this application and hand each other their keys + * directly; a real application exchanges them over a channel the media + * servers cannot read, or derives them with a key agreement such as MLS. *

* Run it with an optional output file, whose extension picks the container: *

@@ -100,7 +90,11 @@ public class EncryptedRecordingExample {
     public static void main(String[] args) throws Exception {
         Path file = Paths.get(args.length > 0 ? args[0] : "encrypted-call.mkv");
 
-        FrameCipher cipher = new FrameCipher(newKey());
+        // Each participant encrypts with a key of its own. The callee records
+        // what it decrypts, which its key provider has to allow.
+        KeyProvider callerKeys = KeyProvider.builder(1).build();
+        KeyProvider calleeKeys = KeyProvider.builder(2).allowPlaintextRecording(true).build();
+        exchangeKeys(callerKeys, calleeKeys);
 
         // A headless runtime sends pushed audio and needs no microphone or speakers.
         try (WebRtc rtc = WebRtc.builder().audio(AudioMode.HEADLESS).build()) {
@@ -110,15 +104,13 @@ public static void main(String[] args) throws Exception {
             Peer caller = rtc.createPeer(PeerOptions.builder()
                     .name("caller")
                     .signaling(link.first())
-                    .sendTransform(cipher::encrypt)
-                    .receiveTransform(cipher::decrypt)
+                    .e2ee(callerKeys)
                     .build());
             Peer callee = rtc.createPeer(PeerOptions.builder()
                     .name("callee")
                     .polite(true)
                     .signaling(link.second())
-                    .sendTransform(cipher::encrypt)
-                    .receiveTransform(cipher::decrypt)
+                    .e2ee(calleeKeys)
                     .build());
 
             CompletableFuture remoteVideo = new CompletableFuture<>();
@@ -143,8 +135,7 @@ public static void main(String[] args) throws Exception {
             finally {
                 feeder.shutdownNow();
 
-                LOG.info(String.format("Encrypted %d frames, decrypted %d, rejected %d",
-                        cipher.encrypted.get(), cipher.decrypted.get(), cipher.rejected.get()));
+                LOG.info("Caller: " + callerKeys.getStats() + ", callee: " + calleeKeys.getStats());
             }
         }
         // The runtime closed the peers, the tracks and the factory.
@@ -188,11 +179,19 @@ public void onError(String message) {
         }
     }
 
-    private static SecretKey newKey() {
-        byte[] key = new byte[16];
-        new SecureRandom().nextBytes(key);
-
-        return new SecretKeySpec(key, "AES");
+    /**
+     * Hands each participant's key to the other. Both live in this
+     * application; a real one sends them over a channel the media servers
+     * cannot read, such as an MLS group.
+     */
+    private static void exchangeKeys(KeyProvider caller, KeyProvider callee) {
+        byte[] callerKey = caller.generateKey();
+        byte[] calleeKey = callee.generateKey();
+
+        caller.setEncryptionKey(0, callerKey);
+        callee.setEncryptionKey(0, calleeKey);
+        caller.setDecryptionKey(callee.getParticipant(), 0, calleeKey);
+        callee.setDecryptionKey(caller.getParticipant(), 0, callerKey);
     }
 
     /**
@@ -238,129 +237,4 @@ private static byte[] tone(int sampleRate) {
 
         return pcm;
     }
-
-
-
-    /**
-     * AES-GCM over the payload of each frame. An encrypted frame is laid out
-     * as the clear header, the ciphertext with its tag, then the 12-byte IV.
-     * One instance serves every sender and receiver, each of which runs its
-     * transform on a thread of its own, so each call makes its own Cipher
-     * rather than share one.
-     */
-    private static class FrameCipher {
-
-        private static final int IV_SIZE = 12;
-        private static final int TAG_BITS = 128;
-
-        private final SecretKey key;
-        private final SecureRandom random = new SecureRandom();
-
-        // Counted from the threads of every sender and receiver.
-        final AtomicLong encrypted = new AtomicLong();
-        final AtomicLong decrypted = new AtomicLong();
-        final AtomicLong rejected = new AtomicLong();
-
-
-        FrameCipher(SecretKey key) {
-            this.key = key;
-        }
-
-        void encrypt(RTCEncodedFrame frame) {
-            ByteBuffer data = frame.getData();
-            int clear = clearBytes(frame, data.remaining());
-
-            byte[] iv = new byte[IV_SIZE];
-            random.nextBytes(iv);
-
-            try {
-                Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
-                cipher.init(Cipher.ENCRYPT_MODE, key, new GCMParameterSpec(TAG_BITS, iv));
-
-                ByteBuffer header = data.duplicate();
-                header.limit(clear);
-                cipher.updateAAD(header);
-
-                ByteBuffer out = ByteBuffer.allocate(clear + cipher.getOutputSize(data.remaining() - clear) + IV_SIZE);
-                ByteBuffer headerCopy = data.duplicate();
-                headerCopy.limit(clear);
-                out.put(headerCopy);
-
-                data.position(clear);
-                cipher.doFinal(data, out);
-                out.put(iv);
-                out.flip();
-
-                frame.setData(out);
-                encrypted.incrementAndGet();
-            }
-            catch (GeneralSecurityException e) {
-                // Never send a frame that failed to encrypt.
-                frame.drop();
-                LOG.log(Level.WARNING, "Encrypting a frame failed", e);
-            }
-        }
-
-        void decrypt(RTCEncodedFrame frame) {
-            ByteBuffer data = frame.getData();
-            int size = data.remaining();
-            int clear = clearBytes(frame, size);
-
-            if (size < clear + TAG_BITS / 8 + IV_SIZE) {
-                frame.drop();
-                rejected.incrementAndGet();
-                return;
-            }
-
-            byte[] iv = new byte[IV_SIZE];
-            data.position(size - IV_SIZE);
-            data.get(iv);
-
-            try {
-                Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
-                cipher.init(Cipher.DECRYPT_MODE, key, new GCMParameterSpec(TAG_BITS, iv));
-
-                ByteBuffer header = data.duplicate();
-                header.position(0);
-                header.limit(clear);
-                cipher.updateAAD(header);
-
-                ByteBuffer out = ByteBuffer.allocate(size);
-                ByteBuffer headerCopy = data.duplicate();
-                headerCopy.position(0);
-                headerCopy.limit(clear);
-                out.put(headerCopy);
-
-                ByteBuffer body = data.duplicate();
-                body.position(clear);
-                body.limit(size - IV_SIZE);
-                cipher.doFinal(body, out);
-                out.flip();
-
-                frame.setData(out);
-                decrypted.incrementAndGet();
-            }
-            catch (GeneralSecurityException e) {
-                // A frame that does not authenticate was tampered with, or
-                // encrypted with another key: it must not reach the decoder.
-                frame.drop();
-                rejected.incrementAndGet();
-            }
-        }
-
-        /**
-         * The bytes left in the clear: the VP8 payload header, which the
-         * receiver's depacketizer reads to find key frames and the frame
-         * size (10 bytes on a key frame, 3 otherwise), and the Opus TOC byte.
-         */
-        private static int clearBytes(RTCEncodedFrame frame, int size) {
-            int clear = 1;
-
-            if (frame instanceof RTCEncodedVideoFrame video) {
-                clear = video.isKeyFrame() ? 10 : 3;
-            }
-
-            return Math.min(clear, size);
-        }
-    }
 }
diff --git a/webrtc-jni/src/main/cpp/include/JNI_AllocationFault.h b/webrtc-jni/src/main/cpp/include/JNI_AllocationFault.h
index c1b1b9cc4..d76e5de83 100644
--- a/webrtc-jni/src/main/cpp/include/JNI_AllocationFault.h
+++ b/webrtc-jni/src/main/cpp/include/JNI_AllocationFault.h
@@ -65,6 +65,30 @@ extern "C" {
 	JNIEXPORT jint JNICALL Java_dev_onvoid_webrtc_internal_AllocationFault_encodedObservers
 	(JNIEnv *, jclass, jlong);
 
+	/*
+	 * Class:     dev_onvoid_webrtc_internal_AllocationFault
+	 * Method:    addCountingObserver
+	 * Signature: (J)J
+	 */
+	JNIEXPORT jlong JNICALL Java_dev_onvoid_webrtc_internal_AllocationFault_addCountingObserver
+	(JNIEnv *, jclass, jlong);
+
+	/*
+	 * Class:     dev_onvoid_webrtc_internal_AllocationFault
+	 * Method:    countedFrames
+	 * Signature: (J)J
+	 */
+	JNIEXPORT jlong JNICALL Java_dev_onvoid_webrtc_internal_AllocationFault_countedFrames
+	(JNIEnv *, jclass, jlong);
+
+	/*
+	 * Class:     dev_onvoid_webrtc_internal_AllocationFault
+	 * Method:    removeCountingObserver
+	 * Signature: (J)V
+	 */
+	JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_internal_AllocationFault_removeCountingObserver
+	(JNIEnv *, jclass, jlong);
+
 	/*
 	 * Class:     dev_onvoid_webrtc_internal_AllocationFault
 	 * Method:    disarm
diff --git a/webrtc-jni/src/main/cpp/include/JNI_NativeApi.h b/webrtc-jni/src/main/cpp/include/JNI_NativeApi.h
index 4721642f9..dd35ff87b 100644
--- a/webrtc-jni/src/main/cpp/include/JNI_NativeApi.h
+++ b/webrtc-jni/src/main/cpp/include/JNI_NativeApi.h
@@ -54,6 +54,14 @@ extern "C" {
 	JNIEXPORT jlong JNICALL Java_dev_onvoid_webrtc_internal_NativeApi_receiverFrames
 	(JNIEnv *, jclass, jlong);
 
+	/*
+	 * Class:     dev_onvoid_webrtc_internal_NativeApi
+	 * Method:    framesSealed
+	 * Signature: (J)Z
+	 */
+	JNIEXPORT jboolean JNICALL Java_dev_onvoid_webrtc_internal_NativeApi_framesSealed
+	(JNIEnv *, jclass, jlong);
+
 	/*
 	 * Class:     dev_onvoid_webrtc_internal_NativeApi
 	 * Method:    releaseFrames
diff --git a/webrtc-jni/src/main/cpp/include/JNI_RTCRtpReceiver.h b/webrtc-jni/src/main/cpp/include/JNI_RTCRtpReceiver.h
index 633d9954a..822eab589 100644
--- a/webrtc-jni/src/main/cpp/include/JNI_RTCRtpReceiver.h
+++ b/webrtc-jni/src/main/cpp/include/JNI_RTCRtpReceiver.h
@@ -49,11 +49,11 @@ extern "C" {
 
 	/*
 	 * Class:     dev_onvoid_webrtc_RTCRtpReceiver
-	 * Method:    setTransform
-	 * Signature: (Ldev/onvoid/webrtc/RTCEncodedFrameTransformer;)V
+	 * Method:    applyTransform
+	 * Signature: (Ldev/onvoid/webrtc/RTCEncodedFrameTransformer;Z)V
 	 */
-	JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCRtpReceiver_setTransform
-	(JNIEnv *, jobject, jobject);
+	JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCRtpReceiver_applyTransform
+	(JNIEnv *, jobject, jobject, jboolean);
 
 	/*
 	 * Class:     dev_onvoid_webrtc_RTCRtpReceiver
diff --git a/webrtc-jni/src/main/cpp/include/JNI_RTCRtpSender.h b/webrtc-jni/src/main/cpp/include/JNI_RTCRtpSender.h
index 1c23215c9..d10f81a34 100644
--- a/webrtc-jni/src/main/cpp/include/JNI_RTCRtpSender.h
+++ b/webrtc-jni/src/main/cpp/include/JNI_RTCRtpSender.h
@@ -65,11 +65,11 @@ extern "C" {
 
 	/*
 	 * Class:     dev_onvoid_webrtc_RTCRtpSender
-	 * Method:    setTransform
-	 * Signature: (Ldev/onvoid/webrtc/RTCEncodedFrameTransformer;)V
+	 * Method:    applyTransform
+	 * Signature: (Ldev/onvoid/webrtc/RTCEncodedFrameTransformer;Z)V
 	 */
-	JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCRtpSender_setTransform
-	(JNIEnv *, jobject, jobject);
+	JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCRtpSender_applyTransform
+	(JNIEnv *, jobject, jobject, jboolean);
 
 	/*
 	 * Class:     dev_onvoid_webrtc_RTCRtpSender
diff --git a/webrtc-jni/src/main/cpp/include/api/EncodedFrameRouter.h b/webrtc-jni/src/main/cpp/include/api/EncodedFrameRouter.h
index 09b7a60a2..41e39ded6 100644
--- a/webrtc-jni/src/main/cpp/include/api/EncodedFrameRouter.h
+++ b/webrtc-jni/src/main/cpp/include/api/EncodedFrameRouter.h
@@ -74,8 +74,11 @@ namespace jni
 			void RemoveCallback();
 			void RemoveSinkCallback(uint32_t ssrc);
 
-			void SetTransformer(std::shared_ptr transformer);
+			// A sealed transform keeps every frame from the observers until
+			// another transform, or none, takes its place.
+			void SetTransformer(std::shared_ptr transformer, bool sealed);
 			std::shared_ptr GetTransformer() const;
+			bool IsSealed() const;
 
 			Observer * AddObserver(wj_encoded_frame_fn fn, void * opaque);
 			// When this returns, the observer is not running and never runs
@@ -83,7 +86,8 @@ namespace jni
 			void RemoveObserver(Observer * observer);
 			size_t GetObserverCount() const;
 
-			// Shows the frame to every observer.
+			// Shows the frame to every observer, unless the transform is
+			// sealed.
 			void Observe(const webrtc::TransformableFrameInterface & frame);
 
 			// Hands the frame back to WebRTC, to the callback that registered
@@ -100,6 +104,8 @@ namespace jni
 
 			mutable std::mutex transformerMutex;
 			std::shared_ptr transformer;
+			// Read without the lock, on the thread of every frame.
+			std::atomic sealed;
 
 			// Held while observers run, which is what lets RemoveObserver()
 			// promise that its observer is done.
diff --git a/webrtc-jni/src/main/cpp/include/api/EncodedFrameTransformer.h b/webrtc-jni/src/main/cpp/include/api/EncodedFrameTransformer.h
index e8f77836d..f7fe5b6fa 100644
--- a/webrtc-jni/src/main/cpp/include/api/EncodedFrameTransformer.h
+++ b/webrtc-jni/src/main/cpp/include/api/EncodedFrameTransformer.h
@@ -69,7 +69,13 @@ namespace jni
 			// transform starts the worker it runs on, and from then on every
 			// frame passes through that worker, transform or not, so that
 			// frames never overtake each other when the transform changes.
-			void SetTransformer(JNIEnv * env, jobject transformer);
+			//
+			// A sealed transform keeps the frames from every observer for as
+			// long as it is set, since they would see what it protects.
+			void SetTransformer(JNIEnv * env, jobject transformer, bool sealed);
+
+			// Whether the transform that is set keeps frames from observers.
+			bool IsSealed() const;
 
 			EncodedFrameRouter::Observer * AddObserver(wj_encoded_frame_fn fn, void * opaque);
 			void RemoveObserver(EncodedFrameRouter::Observer * observer);
diff --git a/webrtc-jni/src/main/cpp/src/JNI_AllocationFault.cpp b/webrtc-jni/src/main/cpp/src/JNI_AllocationFault.cpp
index fdfa5076f..8975c476e 100644
--- a/webrtc-jni/src/main/cpp/src/JNI_AllocationFault.cpp
+++ b/webrtc-jni/src/main/cpp/src/JNI_AllocationFault.cpp
@@ -21,11 +21,27 @@
 #include "api/EncodedFrameTransformer.h"
 #include "api/ExtensionApi.h"
 
+#include 
+#include 
+
 namespace
 {
 	void IgnoreFrame(void * opaque, const wj_encoded_frame * frame)
 	{
 	}
+
+	// An observer that counts the frames it sees, for the tests of what
+	// observers get to see.
+	struct CountingObserver
+	{
+		std::atomic frames { 0 };
+		void * observer = nullptr;
+	};
+
+	void CountFrame(void * opaque, const wj_encoded_frame * frame)
+	{
+		static_cast(opaque)->frames.fetch_add(1, std::memory_order_relaxed);
+	}
 }
 
 // The Java class this belongs to exists in the tests only, so that nothing but
@@ -79,6 +95,42 @@ JNIEXPORT jint JNICALL Java_dev_onvoid_webrtc_internal_AllocationFault_encodedOb
 	});
 }
 
+JNIEXPORT jlong JNICALL Java_dev_onvoid_webrtc_internal_AllocationFault_addCountingObserver
+(JNIEnv * env, jclass caller, jlong frames)
+{
+	return jni::CallFromJava(env, [&]() -> jlong {
+		auto counter = new CountingObserver();
+		counter->observer = jni::GetExtensionApi()->encoded_observer_add(reinterpret_cast(frames), &CountFrame, counter);
+
+		if (counter->observer == nullptr) {
+			delete counter;
+			return 0;
+		}
+
+		return reinterpret_cast(counter);
+	});
+}
+
+JNIEXPORT jlong JNICALL Java_dev_onvoid_webrtc_internal_AllocationFault_countedFrames
+(JNIEnv * env, jclass caller, jlong counter)
+{
+	return jni::CallFromJava(env, [&]() -> jlong {
+		return static_cast(reinterpret_cast(counter)->frames.load(std::memory_order_relaxed));
+	});
+}
+
+JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_internal_AllocationFault_removeCountingObserver
+(JNIEnv * env, jclass caller, jlong counter)
+{
+	jni::CallFromJava(env, [&]() {
+		auto observer = reinterpret_cast(counter);
+
+		// Once removed, the observer never runs again, and the counter may go.
+		jni::GetExtensionApi()->encoded_observer_remove(observer->observer);
+		delete observer;
+	});
+}
+
 JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_internal_AllocationFault_disarm
 (JNIEnv * env, jclass caller)
 {
diff --git a/webrtc-jni/src/main/cpp/src/JNI_NativeApi.cpp b/webrtc-jni/src/main/cpp/src/JNI_NativeApi.cpp
index 2fe373615..bd80a7c2f 100644
--- a/webrtc-jni/src/main/cpp/src/JNI_NativeApi.cpp
+++ b/webrtc-jni/src/main/cpp/src/JNI_NativeApi.cpp
@@ -120,6 +120,16 @@ JNIEXPORT jlong JNICALL Java_dev_onvoid_webrtc_internal_NativeApi_receiverFrames
 	});
 }
 
+JNIEXPORT jboolean JNICALL Java_dev_onvoid_webrtc_internal_NativeApi_framesSealed
+(JNIEnv * env, jclass caller, jlong frames)
+{
+	return jni::CallFromJava(env, [&]() -> jboolean {
+		auto transformer = reinterpret_cast(frames);
+
+		return transformer != nullptr && transformer->IsSealed() ? JNI_TRUE : JNI_FALSE;
+	});
+}
+
 JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_internal_NativeApi_releaseFrames
 (JNIEnv * env, jclass caller, jlong frames)
 {
diff --git a/webrtc-jni/src/main/cpp/src/JNI_RTCRtpReceiver.cpp b/webrtc-jni/src/main/cpp/src/JNI_RTCRtpReceiver.cpp
index 9b18e541b..5390e91c9 100644
--- a/webrtc-jni/src/main/cpp/src/JNI_RTCRtpReceiver.cpp
+++ b/webrtc-jni/src/main/cpp/src/JNI_RTCRtpReceiver.cpp
@@ -134,8 +134,8 @@ JNIEXPORT jobject JNICALL Java_dev_onvoid_webrtc_RTCRtpReceiver_getSynchronizati
 	}
 }
 
-JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCRtpReceiver_setTransform
-(JNIEnv * env, jobject caller, jobject jTransformer)
+JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCRtpReceiver_applyTransform
+(JNIEnv * env, jobject caller, jobject jTransformer, jboolean sealed)
 {
 	jni::CallFromJava(env, [&]() {
 		jni::NativeLease receiver(env, caller);
@@ -148,7 +148,7 @@ JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCRtpReceiver_setTransform
 				: jni::EncodedFrameTransformer::Find(receiver);
 
 			if (transformer) {
-				transformer->SetTransformer(env, jTransformer);
+				transformer->SetTransformer(env, jTransformer, sealed == JNI_TRUE);
 			}
 		}
 		catch (...) {
diff --git a/webrtc-jni/src/main/cpp/src/JNI_RTCRtpSender.cpp b/webrtc-jni/src/main/cpp/src/JNI_RTCRtpSender.cpp
index 24616c479..7565e2cdc 100644
--- a/webrtc-jni/src/main/cpp/src/JNI_RTCRtpSender.cpp
+++ b/webrtc-jni/src/main/cpp/src/JNI_RTCRtpSender.cpp
@@ -170,8 +170,8 @@ JNIEXPORT jobject JNICALL Java_dev_onvoid_webrtc_RTCRtpSender_getDtmfSender
 	}
 }
 
-JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCRtpSender_setTransform
-(JNIEnv * env, jobject caller, jobject jTransformer)
+JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCRtpSender_applyTransform
+(JNIEnv * env, jobject caller, jobject jTransformer, jboolean sealed)
 {
 	jni::CallFromJava(env, [&]() {
 		jni::NativeLease sender(env, caller);
@@ -184,7 +184,7 @@ JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCRtpSender_setTransform
 				: jni::EncodedFrameTransformer::Find(sender);
 
 			if (transformer) {
-				transformer->SetTransformer(env, jTransformer);
+				transformer->SetTransformer(env, jTransformer, sealed == JNI_TRUE);
 			}
 		}
 		catch (...) {
diff --git a/webrtc-jni/src/main/cpp/src/api/EncodedFrameRouter.cpp b/webrtc-jni/src/main/cpp/src/api/EncodedFrameRouter.cpp
index a5c08adcb..416b3bb7f 100644
--- a/webrtc-jni/src/main/cpp/src/api/EncodedFrameRouter.cpp
+++ b/webrtc-jni/src/main/cpp/src/api/EncodedFrameRouter.cpp
@@ -28,6 +28,7 @@ namespace jni
 	EncodedFrameRouter::EncodedFrameRouter(webrtc::MediaType mediaType, bool sender) :
 		mediaType(mediaType),
 		sender(sender),
+		sealed(false),
 		observerCount(0)
 	{
 	}
@@ -86,7 +87,7 @@ namespace jni
 		}
 	}
 
-	void EncodedFrameRouter::SetTransformer(std::shared_ptr transformer)
+	void EncodedFrameRouter::SetTransformer(std::shared_ptr transformer, bool sealed)
 	{
 		std::shared_ptr previous;
 
@@ -95,6 +96,7 @@ namespace jni
 
 			previous = std::move(this->transformer);
 			this->transformer = std::move(transformer);
+			this->sealed.store(sealed, std::memory_order_release);
 		}
 
 		// The previous transform holds a global reference, which is deleted
@@ -109,6 +111,11 @@ namespace jni
 		return transformer;
 	}
 
+	bool EncodedFrameRouter::IsSealed() const
+	{
+		return sealed.load(std::memory_order_acquire);
+	}
+
 	EncodedFrameRouter::Observer * EncodedFrameRouter::AddObserver(wj_encoded_frame_fn fn, void * opaque)
 	{
 		auto observer = std::make_unique(Observer{ fn, opaque });
@@ -147,6 +154,12 @@ namespace jni
 			return;
 		}
 
+		// What a sealed transform protects: a sender's frames before it
+		// encrypts them, a receiver's after it decrypted them.
+		if (sealed.load(std::memory_order_acquire)) {
+			return;
+		}
+
 		std::lock_guard lock(observerMutex);
 
 		if (observers.empty()) {
diff --git a/webrtc-jni/src/main/cpp/src/api/EncodedFrameTransformer.cpp b/webrtc-jni/src/main/cpp/src/api/EncodedFrameTransformer.cpp
index d71543690..47a757567 100644
--- a/webrtc-jni/src/main/cpp/src/api/EncodedFrameTransformer.cpp
+++ b/webrtc-jni/src/main/cpp/src/api/EncodedFrameTransformer.cpp
@@ -145,7 +145,7 @@ namespace jni
 		delete worker.load(std::memory_order_acquire);
 	}
 
-	void EncodedFrameTransformer::SetTransformer(JNIEnv * env, jobject transformer)
+	void EncodedFrameTransformer::SetTransformer(JNIEnv * env, jobject transformer, bool sealed)
 	{
 		std::shared_ptr javaTransformer;
 
@@ -163,7 +163,12 @@ namespace jni
 			}
 		}
 
-		router->SetTransformer(std::move(javaTransformer));
+		router->SetTransformer(std::move(javaTransformer), sealed && transformer != nullptr);
+	}
+
+	bool EncodedFrameTransformer::IsSealed() const
+	{
+		return router->IsSealed();
 	}
 
 	EncodedFrameRouter::Observer * EncodedFrameTransformer::AddObserver(wj_encoded_frame_fn fn, void * opaque)
diff --git a/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorder.java b/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorder.java
index 3bad3b122..2ca9b7e50 100644
--- a/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorder.java
+++ b/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorder.java
@@ -84,7 +84,14 @@
  * 
  • A sender with simulcast is recorded at one of its layers.
  • *
  • A sender's frames are recorded before an {@link * dev.onvoid.webrtc.RTCEncodedFrameTransformer} runs on them, a receiver's - * after, so an end-to-end encrypted call is recorded in the clear.
  • + * after, so an end-to-end encrypted call is recorded in the clear. Whether + * that may happen is the transform's decision: one whose {@link + * dev.onvoid.webrtc.RTCEncodedFrameTransformer#allowsPlaintextObservers()} + * says no, as the transforms of a {@link dev.onvoid.webrtc.e2ee.KeyProvider} + * do unless it {@link + * dev.onvoid.webrtc.e2ee.KeyProvider.Builder#allowPlaintextRecording(boolean) + * allows recording}, is refused by {@code addTrack}. Set on a track that is + * being recorded, it keeps the recorder from any further frame of it. * * * @author Alex Andres @@ -204,7 +211,9 @@ public void setListener(MediaRecorderListener listener) { * * @param sender The sender to record. * - * @throws IllegalStateException If the recorder was started or closed. + * @throws IllegalStateException If the recorder was started or closed, + * or the sender's transform does not + * allow recording. * @throws IllegalArgumentException If the sender was disposed. */ public void addTrack(RTCRtpSender sender) { @@ -222,7 +231,9 @@ public void addTrack(RTCRtpSender sender) { * * @param receiver The receiver to record. * - * @throws IllegalStateException If the recorder was started or closed. + * @throws IllegalStateException If the recorder was started or closed, + * or the receiver's transform does not + * allow recording. * @throws IllegalArgumentException If the receiver was disposed. */ public void addTrack(RTCRtpReceiver receiver) { @@ -243,7 +254,9 @@ public void addTrack(RTCRtpReceiver receiver) { * * @param sender The sender to record. * - * @throws IllegalStateException If the recorder was started or closed. + * @throws IllegalStateException If the recorder was started or closed, + * or the sender's transform does not + * allow recording. * @throws IllegalArgumentException If the sender was removed, or its peer * closed. */ @@ -263,7 +276,9 @@ public void addTrack(Sender sender) { * * @param track The remote track to record. * - * @throws IllegalStateException If the recorder was started or closed. + * @throws IllegalStateException If the recorder was started or closed, + * or the track's transform does not + * allow recording. * @throws IllegalArgumentException If the track ended. */ public void addTrack(RemoteTrack track) { @@ -527,6 +542,12 @@ private void addTrack(long frames, Runnable keyFrameRequest) { if (frames == 0) { throw new IllegalArgumentException("The sender or receiver was disposed"); } + if (NativeApi.isSealed(frames)) { + NativeApi.releaseEncodedFrames(frames); + + throw new IllegalStateException("The track is end-to-end encrypted, and its transform " + + "does not allow recording the decrypted media"); + } // The native recorder takes over the reference the handle carries. addTrack(handle, frames); diff --git a/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/MediaRecorderTest.java b/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/MediaRecorderTest.java index 51e898241..6500550b0 100644 --- a/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/MediaRecorderTest.java +++ b/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/MediaRecorderTest.java @@ -41,6 +41,8 @@ import dev.onvoid.webrtc.PeerConnectionFactory; import dev.onvoid.webrtc.RTCRtpReceiver; +import dev.onvoid.webrtc.RTCRtpSender; +import dev.onvoid.webrtc.e2ee.KeyProvider; import dev.onvoid.webrtc.media.audio.AudioDeviceModule; import dev.onvoid.webrtc.media.audio.AudioLayer; import dev.onvoid.webrtc.media.player.AllocationFault; @@ -140,6 +142,85 @@ void recordsReceivedCallIntoMatroska() throws Exception { assertDuration(info); } + @Test + void refusesEncryptedTracks() throws Exception { + KeyProvider callerKeys = KeyProvider.builder(1).build(); + KeyProvider calleeKeys = KeyProvider.builder(2).build(); + byte[] key = callerKeys.generateKey(); + callerKeys.setEncryptionKey(0, key); + calleeKeys.setDecryptionKey(1, 0, key); + + try (TestCall call = new TestCall(factory); + MediaRecorder recorder = new MediaRecorder(tempDir.resolve("refused.mkv"))) { + RTCRtpSender sender = call.getVideoSender(); + RTCRtpReceiver receiver = call.getReceiver(0); + + sender.setTransform(callerKeys.createEncryptor()); + receiver.setTransform(calleeKeys.createDecryptor()); + + // The decrypted media is not to be stored, unless the keys say so. + assertThrows(IllegalStateException.class, () -> recorder.addTrack(sender)); + assertThrows(IllegalStateException.class, () -> recorder.addTrack(receiver)); + + // A refused track leaves the recorder as it was. + recorder.addTrack(call.getAudioSender()); + assertEquals(MediaRecorderState.IDLE, recorder.getState()); + + receiver.dispose(); + } + } + + @Test + void recordsAllowedEncryptedCall() throws Exception { + Path file = tempDir.resolve("encrypted.mkv"); + Listener listener = new Listener(); + + KeyProvider callerKeys = KeyProvider.builder(1).build(); + KeyProvider calleeKeys = KeyProvider.builder(2).allowPlaintextRecording(true).build(); + byte[] key = callerKeys.generateKey(); + callerKeys.setEncryptionKey(0, key); + calleeKeys.setDecryptionKey(1, 0, key); + + try (TestCall call = new TestCall(factory)) { + RTCRtpReceiver video = call.getReceiver(0); + RTCRtpReceiver audio = call.getReceiver(1); + + // The receivers decrypt before the senders encrypt, so that no + // frame reaches them in the clear. + video.setTransform(calleeKeys.createDecryptor(video::requestKeyFrame)); + audio.setTransform(calleeKeys.createDecryptor()); + call.getVideoSender().setTransform(callerKeys.createEncryptor()); + call.getAudioSender().setTransform(callerKeys.createEncryptor()); + + try (MediaRecorder recorder = new MediaRecorder(file)) { + recorder.setListener(listener); + recorder.addTrack(video); + recorder.addTrack(audio); + recorder.start(); + + assertTrue(listener.started.await(10, TimeUnit.SECONDS), "not started"); + + Thread.sleep(RECORD_MS); + + assertTrue(recorder.stop()); + } + finally { + video.dispose(); + audio.dispose(); + } + } + + assertNull(listener.error.get()); + assertTrue(calleeKeys.getStats().getDecryptedFrames() > 0); + + // What was recorded is the decrypted media, which reads as such. + MediaInfo info = readInfo(file); + + assertEquals("vp8", info.getVideoCodec()); + assertEquals("opus", info.getAudioCodec()); + assertDuration(info); + } + @Test void recordsSentCallIntoWebm() throws Exception { Path file = tempDir.resolve("sent.webm"); diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/RTCEncodedFrameTransformer.java b/webrtc/src/main/java/dev/onvoid/webrtc/RTCEncodedFrameTransformer.java index ab0b56231..00cd4b66d 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/RTCEncodedFrameTransformer.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/RTCEncodedFrameTransformer.java @@ -66,4 +66,23 @@ public interface RTCEncodedFrameTransformer { */ void transform(RTCEncodedFrame frame); + /** + * Says whether observers of the encoded frames, such as a {@code + * MediaRecorder}, may see the frames this transform protects. They watch + * a sender's frames before the transform and a receiver's after it, so + * with an encryption transform they see the media in the clear. + *

    + * A transform that returns false keeps every observer of its sender or + * receiver from seeing any frame, for as long as it is set, and a + * recorder refuses to record them. The method is asked once, when the + * transform is set. + * + * @return True by default; false to keep the plaintext from observers. + * + * @see dev.onvoid.webrtc.e2ee.KeyProvider.Builder#allowPlaintextRecording(boolean) + */ + default boolean allowsPlaintextObservers() { + return true; + } + } diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/RTCRtpReceiver.java b/webrtc/src/main/java/dev/onvoid/webrtc/RTCRtpReceiver.java index 2b2702dd8..dc720a8ec 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/RTCRtpReceiver.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/RTCRtpReceiver.java @@ -136,12 +136,20 @@ private RTCRtpReceiver() { * The transform belongs to the native receiver, so it is shared by every * RTCRtpReceiver instance standing for it, and it stays in place when * this instance is disposed. + *

    + * A transform whose {@link + * RTCEncodedFrameTransformer#allowsPlaintextObservers()} is false keeps + * every observer of the encoded frames, such as a recorder, from seeing + * any frame for as long as it is set. * * @param transformer The transform, or {@code null} to remove it. * * @see RTCEncodedFrameTransformer */ - public native void setTransform(RTCEncodedFrameTransformer transformer); + public void setTransform(RTCEncodedFrameTransformer transformer) { + // Asked once, so that the native side need not call into Java. + applyTransform(transformer, transformer != null && !transformer.allowsPlaintextObservers()); + } /** * Asks the remote sender for a video key frame, e.g. so that a recording @@ -190,4 +198,6 @@ public int hashCode() { return nativeHashCode(); } + private native void applyTransform(RTCEncodedFrameTransformer transformer, boolean sealed); + } diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/RTCRtpSender.java b/webrtc/src/main/java/dev/onvoid/webrtc/RTCRtpSender.java index 1662c9116..4e8aa89f0 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/RTCRtpSender.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/RTCRtpSender.java @@ -180,12 +180,20 @@ private RTCRtpSender() { * instance is disposed. Setting it before the connection is negotiated * avoids the key frame the encoder otherwise sends when the first * transform is set on a running video sender. + *

    + * A transform whose {@link + * RTCEncodedFrameTransformer#allowsPlaintextObservers()} is false keeps + * every observer of the encoded frames, such as a recorder, from seeing + * any frame for as long as it is set. * * @param transformer The transform, or {@code null} to remove it. * * @see RTCEncodedFrameTransformer */ - public native void setTransform(RTCEncodedFrameTransformer transformer); + public void setTransform(RTCEncodedFrameTransformer transformer) { + // Asked once, so that the native side need not call into Java. + applyTransform(transformer, transformer != null && !transformer.allowsPlaintextObservers()); + } /** * Asks the encoder to make the next video frame a key frame, e.g. so that @@ -294,4 +302,6 @@ public int hashCode() { return nativeHashCode(); } + private native void applyTransform(RTCEncodedFrameTransformer transformer, boolean sealed); + } diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerImpl.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerImpl.java index 5f011b32d..e56dc64e0 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerImpl.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerImpl.java @@ -37,6 +37,7 @@ import dev.onvoid.webrtc.RTCDataChannel; import dev.onvoid.webrtc.RTCConfiguration; import dev.onvoid.webrtc.RTCIceServer; +import dev.onvoid.webrtc.RTCEncodedFrame; import dev.onvoid.webrtc.RTCEncodedFrameTransformer; import dev.onvoid.webrtc.RTCIceCandidate; import dev.onvoid.webrtc.RTCIceGatheringState; @@ -170,7 +171,7 @@ final class PeerImpl implements Peer { this.automatic = new PerfectNegotiation(this, options, chain, steps); this.statistics = new StatsSampler(this); this.channels = new DataChannels(this); - this.tracks = new RemoteTracks(this, options.receiveTransform); + this.tracks = new RemoteTracks(this, receiveTransforms(options)); this.manual = new ManualNegotiation(this, options, chain, steps, tracks, new CodecPreferences(this)); this.signaling = new SignalingLink(this, options.signaling); @@ -317,7 +318,7 @@ private SenderImpl addSender(LocalTrackImpl local, List ids, List { - try { - transform.transform(frame); - } - catch (Throwable e) { - frame.drop(); + return new RTCEncodedFrameTransformer() { + + @Override + public void transform(RTCEncodedFrame frame) { + try { + transform.transform(frame); + } + catch (Throwable e) { + frame.drop(); - if (reported.compareAndSet(false, true)) { - deliverError(new WebRtcException("The transform of " + owner - + " failed, and drops each frame it fails on", e)); + if (reported.compareAndSet(false, true)) { + deliverError(new WebRtcException("The transform of " + owner + + " failed, and drops each frame it fails on", e)); + } } } + + @Override + public boolean allowsPlaintextObservers() { + // Wrapping must not open up what the transform protects. + return transform.allowsPlaintextObservers(); + } }; } + /** + * The transform of a sender: an encryptor of its own with end-to-end + * encryption, which asks the sender for a key frame when the key changes, + * or the send transform of the options. + */ + private RTCEncodedFrameTransformer sendTransform(SenderImpl sender) { + if (options.e2ee != null) { + return options.e2ee.createEncryptor(sender::generateKeyFrame); + } + + return options.sendTransform; + } + + /** Makes the transform of each remote track, or null for none. */ + private static Function receiveTransforms(PeerOptions options) { + if (options.e2ee != null) { + return options.e2ee::createDecryptor; + } + if (options.receiveTransform != null) { + RTCEncodedFrameTransformer transform = options.receiveTransform; + + return keyFrameRequest -> transform; + } + + return null; + } + void deliverError(WebRtcException error) { events.execute(() -> { if (errorHandlers.isEmpty()) { diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerOptions.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerOptions.java index 949fbb0b9..62a49f883 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerOptions.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerOptions.java @@ -31,6 +31,7 @@ import dev.onvoid.webrtc.RTCEncodedFrameTransformer; import dev.onvoid.webrtc.RTCIceServer; import dev.onvoid.webrtc.RTCIceTransportPolicy; +import dev.onvoid.webrtc.e2ee.KeyProvider; import dev.onvoid.webrtc.internal.Timeouts; /** @@ -73,6 +74,8 @@ public final class PeerOptions { final RTCEncodedFrameTransformer receiveTransform; + final KeyProvider e2ee; + private PeerOptions(Builder builder) { this.name = builder.name; @@ -90,6 +93,7 @@ private PeerOptions(Builder builder) { this.channelReceiveLimit = builder.channelReceiveLimit; this.sendTransform = builder.sendTransform; this.receiveTransform = builder.receiveTransform; + this.e2ee = builder.e2ee; } /** @@ -159,6 +163,8 @@ public static final class Builder { private RTCEncodedFrameTransformer receiveTransform; + private KeyProvider e2ee; + private Builder() { } @@ -376,6 +382,36 @@ public Builder receiveTransform(RTCEncodedFrameTransformer transform) { return this; } + /** + * Encrypts every frame the peer sends, and decrypts every frame it + * receives, end to end with the keys of the given provider, in the + * SFrame format that the guide specifies for browsers to implement + * too. + *

    + * Each sender gets an encryptor of its own, set before negotiation, + * which asks it for a key frame when the encryption key changes; each + * remote track a decryptor, set before {@link Peer#onTrack} hands it + * out, which asks the remote side for a key frame once video decrypts + * again after frames were dropped. Frames that fail are dropped and + * reported to the provider's {@link + * dev.onvoid.webrtc.e2ee.CryptoListener}, not to {@code onError}. + *

    + * Video has to be sent in VP8, VP9 or AV1: H.264 and H.265 frames are + * dropped, see {@link dev.onvoid.webrtc.e2ee.CryptoFailure#UNSUPPORTED_CODEC}. + * {@link Sender#transform} and {@link RemoteTrack#transform} still + * replace the transform of one sender or track. A {@code MediaRecorder} + * refuses the senders and tracks unless the provider {@link + * KeyProvider.Builder#allowPlaintextRecording allows recording}. + * + * @param keys the keys of the call. + * + * @return this builder. + */ + public Builder e2ee(KeyProvider keys) { + this.e2ee = requireNonNull(keys, "keys"); + return this; + } + /** * Changes anything else of the {@link RTCConfiguration} the peer is * created with, after this builder applied its own values. @@ -393,10 +429,16 @@ public Builder configure(Consumer customizer) { * @return the options. * * @throws IllegalStateException if the peer negotiates automatically - * and has no signaling, or recovery is - * configured for manual negotiation. + * and has no signaling, recovery is + * configured for manual negotiation, or + * end-to-end encryption is set together + * with a send or receive transform. */ public PeerOptions build() { + if (e2ee != null && (sendTransform != null || receiveTransform != null)) { + throw new IllegalStateException("End-to-end encryption brings its own transforms, " + + "and takes no send or receive transform besides"); + } if (recovery != null && negotiation != Negotiation.AUTOMATIC) { throw new IllegalStateException("Peer recovery requires automatic negotiation"); } diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/RemoteTracks.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/RemoteTracks.java index c67922387..bba9ad7f1 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/client/RemoteTracks.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/RemoteTracks.java @@ -26,7 +26,9 @@ import java.util.Map; import java.util.Set; import java.util.concurrent.CopyOnWriteArrayList; +import java.util.concurrent.atomic.AtomicReference; import java.util.function.BiConsumer; +import java.util.function.Function; import java.util.function.Consumer; import dev.onvoid.webrtc.RTCEncodedFrameTransformer; @@ -49,8 +51,11 @@ final class RemoteTracks { private final PeerImpl peer; - /** Set on each track before the application hears of it, or null. */ - private final RTCEncodedFrameTransformer transform; + /** + * Makes the transform of each track, set before the application hears of + * it, from what asks the track's sender for a key frame; or null. + */ + private final Function transforms; private final BiConsumer installTransform; @@ -73,16 +78,21 @@ final class RemoteTracks { private final Handlers handlers; - RemoteTracks(PeerImpl peer, RTCEncodedFrameTransformer transform) { - this(peer, transform, RTCRtpReceiver::setTransform); + RemoteTracks(PeerImpl peer, Function transforms) { + this(peer, transforms, RTCRtpReceiver::setTransform); } /** Allows a test to fail installation before the native receiver takes the transform. */ RemoteTracks(PeerImpl peer, RTCEncodedFrameTransformer transform, BiConsumer installTransform) { + this(peer, transform == null ? null : keyFrameRequest -> transform, installTransform); + } + + private RemoteTracks(PeerImpl peer, Function transforms, + BiConsumer installTransform) { this.peer = peer; this.installTransform = installTransform; - this.transform = transform; + this.transforms = transforms; this.handlers = new Handlers<>(peer.rtc::reportError); } @@ -158,10 +168,22 @@ void added(RTCRtpReceiver receiver, MediaStream[] streams) { return; } - if (transform != null) { + // The track a key frame request of the transform goes to, once there + // is one: frames may arrive before it is published. + AtomicReference published = new AtomicReference<>(); + + if (transforms != null) { String owner = "the track " + id + " of " + peer.name; try { + RTCEncodedFrameTransformer transform = transforms.apply(() -> { + RemoteTrackImpl remote = published.get(); + + if (remote instanceof RemoteVideoImpl) { + ((RemoteVideoImpl) remote).requestKeyFrame(); + } + }); + // Before the application hears of the track, and so before // its first frame arrives. installTransform.accept(receiver, peer.guard(transform, owner)); @@ -196,6 +218,7 @@ void added(RTCRtpReceiver receiver, MediaStream[] streams) { byId.put(id, remote); tracks.add(remote); + published.set(remote); peer.events.execute(() -> { delivered.add(remote); diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/Whep.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/Whep.java index 2a23b9c08..1fb2388b1 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/client/Whep.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/Whep.java @@ -28,6 +28,7 @@ import java.util.concurrent.CompletableFuture; import dev.onvoid.webrtc.RTCEncodedFrameTransformer; +import dev.onvoid.webrtc.e2ee.KeyProvider; import dev.onvoid.webrtc.internal.Timeouts; /** @@ -305,6 +306,20 @@ public Builder receiveTransform(RTCEncodedFrameTransformer transform) { return this; } + /** + * Decrypts every frame received end to end with the keys of the given + * provider, which the media server forwards without being able to read. + * See {@link PeerOptions.Builder#e2ee}. + * + * @param keys the keys of the call. + * + * @return this builder. + */ + public Builder e2ee(KeyProvider keys) { + options.e2ee(keys); + return this; + } + /** * Asks the endpoint with HEAD whether it serves WHEP, as a player may * before it plays a URL it was given (draft-ietf-wish-whep-05, 4.2): a diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/Whip.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/Whip.java index 55233c635..4f19e0069 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/client/Whip.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/Whip.java @@ -30,6 +30,7 @@ import java.util.concurrent.CompletableFuture; import dev.onvoid.webrtc.RTCEncodedFrameTransformer; +import dev.onvoid.webrtc.e2ee.KeyProvider; import dev.onvoid.webrtc.RTCRtpEncodingParameters; import dev.onvoid.webrtc.internal.Timeouts; @@ -359,6 +360,20 @@ public Builder sendTransform(RTCEncodedFrameTransformer transform) { return this; } + /** + * Encrypts every frame sent end to end with the keys of the given + * provider, which the media server forwards without being able to read. + * See {@link PeerOptions.Builder#e2ee}. + * + * @param keys the keys of the call. + * + * @return this builder. + */ + public Builder e2ee(KeyProvider keys) { + options.e2ee(keys); + return this; + } + /** * Creates a peer of the runtime that sends the tracks and negotiates it * with the endpoint. diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CipherSuite.java b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CipherSuite.java new file mode 100644 index 000000000..64142810b --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CipherSuite.java @@ -0,0 +1,139 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.e2ee; + +/** + * The SFrame cipher suites of RFC 9605, Section 4.5. Every participant of a + * call has to use the same one, since nothing in a frame says which it is. + *

    + * The GCM suites have full 16-byte tags and are what browsers implement + * fastest with WebCrypto. The CTR suites trade a shorter tag, down to 4 + * bytes, for a higher risk of forgeries (RFC 9605, Section 7.5); the replay + * window of the {@link KeyProvider} is one of the mitigations the RFC names. + * + * @author Alex Andres + */ +public enum CipherSuite { + + /** AES-128 in counter mode with an 80-bit HMAC-SHA256 tag. */ + AES_128_CTR_HMAC_SHA256_80(0x0001, 16, 48, 10, false, "HmacSHA256", 32), + + /** AES-128 in counter mode with a 64-bit HMAC-SHA256 tag. */ + AES_128_CTR_HMAC_SHA256_64(0x0002, 16, 48, 8, false, "HmacSHA256", 32), + + /** AES-128 in counter mode with a 32-bit HMAC-SHA256 tag. */ + AES_128_CTR_HMAC_SHA256_32(0x0003, 16, 48, 4, false, "HmacSHA256", 32), + + /** AES-128-GCM with a 128-bit tag and HKDF-SHA256, the default. */ + AES_128_GCM_SHA256_128(0x0004, 16, 16, 16, true, "HmacSHA256", 32), + + /** AES-256-GCM with a 128-bit tag and HKDF-SHA512. */ + AES_256_GCM_SHA512_128(0x0005, 32, 32, 16, true, "HmacSHA512", 64); + + /** The size of every nonce, Nn. */ + static final int NONCE_LENGTH = 12; + + private final int id; + + /** The AES key size, Nka for the CTR suites. */ + private final int aesKeyLength; + + /** The size of the AEAD key, Nk. */ + private final int keyLength; + + /** The size of the tag, Nt. */ + private final int tagLength; + + private final boolean gcm; + + private final String hmac; + + /** The size of the hash output, Nh. */ + private final int hashLength; + + + CipherSuite(int id, int aesKeyLength, int keyLength, int tagLength, boolean gcm, String hmac, + int hashLength) { + this.id = id; + this.aesKeyLength = aesKeyLength; + this.keyLength = keyLength; + this.tagLength = tagLength; + this.gcm = gcm; + this.hmac = hmac; + this.hashLength = hashLength; + } + + /** + * @return The identifier of the suite in the IANA "SFrame Cipher Suites" + * registry, e.g. {@code 0x0004}. + */ + public int getId() { + return id; + } + + /** + * @return The size of the authentication tag each frame carries, in + * bytes. + */ + public int getTagLength() { + return tagLength; + } + + /** + * @return The size of the keys {@link KeyProvider#generateKey()} makes, + * the output size of the suite's hash, in bytes. + */ + public int getHashLength() { + return hashLength; + } + + /** + * Returns the suite with the given registry identifier. + * + * @param id The identifier, e.g. {@code 0x0004}. + * + * @return The suite. + * + * @throws IllegalArgumentException If no suite has this identifier. + */ + public static CipherSuite of(int id) { + for (CipherSuite suite : values()) { + if (suite.id == id) { + return suite; + } + } + + throw new IllegalArgumentException(String.format("Unknown cipher suite 0x%04x", id)); + } + + int aesKeyLength() { + return aesKeyLength; + } + + int keyLength() { + return keyLength; + } + + boolean isGcm() { + return gcm; + } + + String hmac() { + return hmac; + } + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoEvent.java b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoEvent.java new file mode 100644 index 000000000..4bb49d55c --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoEvent.java @@ -0,0 +1,103 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.e2ee; + +/** + * A stream of frames that began to fail, as a {@link CryptoListener} hears + * of it. + * + * @author Alex Andres + */ +public final class CryptoEvent { + + private final CryptoFailure failure; + + private final boolean outgoing; + + private final long participant; + + private final int generation; + + private final long ssrc; + + private final String mimeType; + + + CryptoEvent(CryptoFailure failure, boolean outgoing, long participant, int generation, long ssrc, + String mimeType) { + this.failure = failure; + this.outgoing = outgoing; + this.participant = participant; + this.generation = generation; + this.ssrc = ssrc; + this.mimeType = mimeType; + } + + /** + * @return Why the frames are dropped. + */ + public CryptoFailure getFailure() { + return failure; + } + + /** + * @return True for frames to be sent, false for received ones. + */ + public boolean isOutgoing() { + return outgoing; + } + + /** + * Returns the participant the frames belong to: the local one for + * outgoing frames, the one the key ID of a received frame names, or -1 if + * a received frame has no readable key ID. + * + * @return The participant ID, or -1. + */ + public long getParticipant() { + return participant; + } + + /** + * @return The key generation the frames are encrypted with or were to be + * decrypted with, or -1 if there is none. + */ + public int getGeneration() { + return generation; + } + + /** + * @return The SSRC of the RTP stream, an unsigned 32-bit value. + */ + public long getSsrc() { + return ssrc; + } + + /** + * @return The codec of the frames, e.g. {@code video/VP8}. + */ + public String getMimeType() { + return mimeType; + } + + @Override + public String toString() { + return String.format("%s [%s, participant=%d, generation=%d, ssrc=%d, mimeType=%s]", + failure, outgoing ? "outgoing" : "incoming", participant, generation, ssrc, mimeType); + } + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoFailure.java b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoFailure.java new file mode 100644 index 000000000..f776b5f2d --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoFailure.java @@ -0,0 +1,74 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.e2ee; + +/** + * Why a frame was dropped. Every failure drops the frame: nothing is sent in + * the clear, and nothing that did not authenticate reaches a decoder. + * + * @author Alex Andres + * + * @see CryptoListener + */ +public enum CryptoFailure { + + /** + * A frame was to be sent, but the {@link KeyProvider} has no encryption + * key yet, or no longer. + */ + MISSING_KEY, + + /** + * A received frame names a participant or key generation the {@link + * KeyProvider} has no decryption key for: the key has not arrived yet, + * was removed, or was retired after its successor took over. Decryption + * resumes with the first frame whose key is there. + */ + UNKNOWN_KEY, + + /** + * A received frame did not authenticate: it was changed on the way, or + * encrypted with another key under the same key ID. + */ + AUTHENTICATION, + + /** + * A received frame repeats the counter of one already decrypted, or is + * older than the replay window reaches back. + */ + REPLAY, + + /** + * A received frame is no SFrame ciphertext, e.g. because the remote side + * sends without encryption, or a frame to be sent is too short for its + * codec's header. + */ + MALFORMED, + + /** + * The frame's codec is one the frame format does not cover, H.264 or + * H.265; use VP8, VP9, AV1 or any audio codec instead. + */ + UNSUPPORTED_CODEC, + + /** + * The {@link KeyProvider} gave out every one of its 224 + * sender contexts, and has to be replaced. + */ + CONTEXTS_EXHAUSTED + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoListener.java b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoListener.java new file mode 100644 index 000000000..5b9c90f6d --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoListener.java @@ -0,0 +1,43 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.e2ee; + +/** + * Hears of the streams whose frames are dropped, e.g. to ask the signaling + * channel for a key that has not arrived. + *

    + * Each RTP stream is reported when it begins to fail, and again only when it + * fails for another reason, or after frames went through again in between, + * so that a stream without its key does not report each of its frames. The + * {@link CryptoStats statistics} count every frame. + *

    + * The listener runs on the transform thread of the sender or receiver, and + * holds up its frames while it runs: hand anything slow to another thread. + * + * @author Alex Andres + */ +@FunctionalInterface +public interface CryptoListener { + + /** + * Called when a stream begins to drop frames for a reason. + * + * @param event What fails, and why. + */ + void onFailure(CryptoEvent event); + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoStats.java b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoStats.java new file mode 100644 index 000000000..e5038b37d --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/CryptoStats.java @@ -0,0 +1,79 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.e2ee; + +import java.util.EnumMap; +import java.util.Map; + +/** + * The frames the encryptors and decryptors of a {@link KeyProvider} handled + * since it was created, as of the moment it was asked. + * + * @author Alex Andres + */ +public final class CryptoStats { + + private final long encrypted; + + private final long decrypted; + + private final Map dropped; + + + CryptoStats(long encrypted, long decrypted, Map dropped) { + this.encrypted = encrypted; + this.decrypted = decrypted; + this.dropped = new EnumMap<>(dropped); + } + + /** + * @return The frames encrypted and sent on. + */ + public long getEncryptedFrames() { + return encrypted; + } + + /** + * @return The frames decrypted and passed to the decoder. + */ + public long getDecryptedFrames() { + return decrypted; + } + + /** + * @param failure The reason. + * + * @return The frames dropped for the reason. + */ + public long getDroppedFrames(CryptoFailure failure) { + return dropped.getOrDefault(failure, 0L); + } + + /** + * @return The frames dropped for any reason. + */ + public long getDroppedFrames() { + return dropped.values().stream().mapToLong(Long::longValue).sum(); + } + + @Override + public String toString() { + return String.format("CryptoStats [encrypted=%d, decrypted=%d, dropped=%s]", + encrypted, decrypted, dropped); + } + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameCryptor.java b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameCryptor.java new file mode 100644 index 000000000..91ef74257 --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameCryptor.java @@ -0,0 +1,224 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.e2ee; + +import java.nio.ByteBuffer; +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.TimeUnit; + +import dev.onvoid.webrtc.RTCEncodedFrame; +import dev.onvoid.webrtc.RTCEncodedFrameTransformer; +import dev.onvoid.webrtc.RTCEncodedVideoFrame; + +/** + * What the encryptor and the decryptor share: the state of each RTP stream, + * the reports of failing streams, the key frame requests, and the buffers. + *

    + * The actual work is done on byte arrays by {@link #process}, so that it can + * be tested without a call. + */ +abstract class FrameCryptor implements RTCEncodedFrameTransformer { + + /** The least time between two key frame requests of a stream. */ + private static final long KEY_FRAME_INTERVAL_NANOS = TimeUnit.MILLISECONDS.toNanos(500); + + /** The largest buffer a transform thread keeps for the next frame. */ + private static final int MAX_RETAINED_BUFFER = 1024 * 1024; + + private static final ThreadLocal BUFFERS = ThreadLocal.withInitial(() -> new byte[2][]); + + final KeyProvider keys; + + private final Runnable keyFrameRequest; + + private final ConcurrentHashMap streams = new ConcurrentHashMap<>(); + + + FrameCryptor(KeyProvider keys, Runnable keyFrameRequest) { + this.keys = keys; + this.keyFrameRequest = keyFrameRequest; + } + + @Override + public void transform(RTCEncodedFrame frame) { + boolean video = frame instanceof RTCEncodedVideoFrame; + boolean keyFrame = video && ((RTCEncodedVideoFrame) frame).isKeyFrame(); + + ByteBuffer data = frame.getData(); + int size = data.remaining(); + + byte[][] buffers = BUFFERS.get(); + byte[] in = buffer(buffers, 0, size); + byte[] out = buffer(buffers, 1, size + FrameFormat.MAX_OVERHEAD); + + data.get(in, 0, size); + + try { + int length = process(frame.getSsrc(), frame.getMimeType(), video, keyFrame, in, size, out); + + if (length < 0) { + frame.drop(); + } + else { + frame.setData(out, 0, length); + } + } + finally { + release(buffers, 0, in); + release(buffers, 1, out); + } + } + + @Override + public boolean allowsPlaintextObservers() { + return keys.allowsPlaintextRecording(); + } + + /** + * Encrypts or decrypts one frame. + * + * @param in The frame, {@code size} bytes. + * @param out Room for the result, {@link FrameFormat#MAX_OVERHEAD} bytes + * more than the frame. + * + * @return The size of the result, or -1 if the frame is to be dropped. + */ + abstract int process(long ssrc, String mimeType, boolean video, boolean keyFrame, byte[] in, int size, + byte[] out); + + abstract boolean isOutgoing(); + + Stream stream(long ssrc) { + return streams.computeIfAbsent(ssrc, Stream::new); + } + + /** + * Drops a frame: counts it, and reports the stream if it was not failing + * for this reason already. + * + * @return -1, for the caller to return. + */ + int fail(Stream stream, CryptoFailure failure, long participant, int generation, String mimeType) { + keys.dropped(failure); + + if (failure != CryptoFailure.REPLAY) { + // A replayed frame was a copy; the stream itself lost nothing. + stream.interrupted = true; + } + + if (stream.failure != failure) { + stream.failure = failure; + + keys.report(new CryptoEvent(failure, isOutgoing(), participant, generation, stream.ssrc, mimeType)); + } + + return -1; + } + + /** + * Notes that a frame went through, and asks for a key frame if a video + * stream needs one. + * + * @param needsKeyFrame Whether a key frame would help even if nothing was + * dropped before, as after a key change. + */ + void succeed(Stream stream, boolean video, boolean keyFrame, boolean needsKeyFrame) { + boolean wanted = needsKeyFrame || stream.interrupted; + + stream.failure = null; + stream.interrupted = false; + + if (!video || keyFrame) { + stream.keyFramePending = false; + return; + } + + if (wanted) { + stream.keyFramePending = true; + } + + if (stream.keyFramePending && keyFrameRequest != null) { + long now = System.nanoTime(); + + if (stream.lastKeyFrameRequest == 0 || now - stream.lastKeyFrameRequest >= KEY_FRAME_INTERVAL_NANOS) { + stream.lastKeyFrameRequest = now; + + try { + keyFrameRequest.run(); + } + catch (RuntimeException e) { + // Not negotiated yet, or gone; the next frame asks again. + } + } + } + } + + private static byte[] buffer(byte[][] buffers, int index, int size) { + byte[] buffer = buffers[index]; + + if (buffer == null || buffer.length < size) { + buffer = new byte[Math.max(size, 4096)]; + } + + buffers[index] = null; + + return buffer; + } + + private static void release(byte[][] buffers, int index, byte[] buffer) { + if (buffer.length <= MAX_RETAINED_BUFFER) { + buffers[index] = buffer; + } + } + + + + /** + * One RTP stream through the transform. Its frames come one at a time, + * from the transform thread of its sender or receiver. + */ + static final class Stream { + + final long ssrc; + + /** The context of an outgoing stream, or -1 until it has one. */ + int context = -1; + + /** The next counter of an outgoing stream; never reset. */ + long counter; + + /** The generation the last outgoing frame was encrypted with, or -1. */ + int generation = -1; + + /** Why the last frame was dropped, or null if it went through. */ + CryptoFailure failure; + + /** Whether frames were lost since the last one went through. */ + boolean interrupted; + + /** Whether a key frame was asked for and has not come yet. */ + boolean keyFramePending; + + long lastKeyFrameRequest; + + + Stream(long ssrc) { + this.ssrc = ssrc; + } + } + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameDecryptor.java b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameDecryptor.java new file mode 100644 index 000000000..a732171b8 --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameDecryptor.java @@ -0,0 +1,118 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.e2ee; + +import dev.onvoid.webrtc.e2ee.FrameFormat.Codec; + +/** + * Decrypts the frames a receiver receives, and drops every one that does not + * authenticate before it reaches the decoder. + */ +final class FrameDecryptor extends FrameCryptor { + + FrameDecryptor(KeyProvider keys, Runnable keyFrameRequest) { + super(keys, keyFrameRequest); + } + + @Override + int process(long ssrc, String mimeType, boolean video, boolean keyFrame, byte[] in, int size, byte[] out) { + Stream stream = stream(ssrc); + Codec codec = Codec.of(mimeType); + + if (codec == null) { + return fail(stream, CryptoFailure.UNSUPPORTED_CODEC, -1, -1, mimeType); + } + + // The bytes before the SFrame header, the clear ones kept in the + // frame, and the metadata the frame is authenticated with. + int clear; + int headerOffset; + byte[] metadata; + int metadataLength; + + if (codec == Codec.AV1) { + clear = 0; + headerOffset = FrameFormat.av1PayloadOffset(in, size); + + if (headerOffset < 0) { + return fail(stream, CryptoFailure.MALFORMED, -1, -1, mimeType); + } + + metadata = new byte[] { (byte) FrameFormat.av1Wrapper(in[0]) }; + metadataLength = 1; + } + else { + // A VP8 receiver knows a key frame from the clear header itself. + clear = codec.clearBytes(keyFrame); + headerOffset = clear; + metadata = in; + metadataLength = clear; + } + + long[] header = new long[2]; + int headerLength = headerOffset <= size + ? SFrame.parseHeader(in, headerOffset, size - headerOffset, header) + : -1; + + if (headerLength < 0) { + return fail(stream, CryptoFailure.MALFORMED, -1, -1, mimeType); + } + + long kid = header[0]; + long ctr = header[1]; + long participant = FrameFormat.participant(kid); + int generation = FrameFormat.generation(kid); + long now = System.nanoTime(); + + KeyProvider.RemoteKey key = keys.decryptionKey(participant, generation, now); + + if (key == null) { + return fail(stream, CryptoFailure.UNKNOWN_KEY, participant, generation, mimeType); + } + + KeyProvider.Opener opener = key.opener(keys.getCipherSuite(), kid, keys.replayWindow()); + + if (opener.window != null && !opener.window.isFresh(ctr)) { + return fail(stream, CryptoFailure.REPLAY, participant, generation, mimeType); + } + + int ciphertextOffset = headerOffset + headerLength; + + int length = opener.sframe.decrypt(ctr, in, headerOffset, headerLength, metadata, 0, metadataLength, + in, ciphertextOffset, size - ciphertextOffset, out, clear); + + if (length < 0) { + return fail(stream, CryptoFailure.AUTHENTICATION, participant, generation, mimeType); + } + if (opener.window != null && !opener.window.accept(ctr)) { + return fail(stream, CryptoFailure.REPLAY, participant, generation, mimeType); + } + + System.arraycopy(in, 0, out, 0, clear); + + keys.decryptedWith(participant, key, now); + succeed(stream, video, keyFrame, false); + + return clear + length; + } + + @Override + boolean isOutgoing() { + return false; + } + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameEncryptor.java b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameEncryptor.java new file mode 100644 index 000000000..b0442aa28 --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameEncryptor.java @@ -0,0 +1,101 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.e2ee; + +import dev.onvoid.webrtc.e2ee.FrameFormat.Codec; + +/** + * Encrypts the frames a sender sends: the codec's clear bytes, if any, then + * the SFrame header, the ciphertext and the tag. + */ +final class FrameEncryptor extends FrameCryptor { + + FrameEncryptor(KeyProvider keys, Runnable keyFrameRequest) { + super(keys, keyFrameRequest); + } + + @Override + int process(long ssrc, String mimeType, boolean video, boolean keyFrame, byte[] in, int size, byte[] out) { + Stream stream = stream(ssrc); + long participant = keys.getParticipant(); + + if (stream.context < 0) { + stream.context = keys.allocateContext(); + + if (stream.context < 0) { + return fail(stream, CryptoFailure.CONTEXTS_EXHAUSTED, participant, -1, mimeType); + } + } + + KeyProvider.LocalKey key = keys.encryptionKey(); + + if (key == null) { + return fail(stream, CryptoFailure.MISSING_KEY, participant, -1, mimeType); + } + + Codec codec = Codec.of(mimeType); + + if (codec == null) { + return fail(stream, CryptoFailure.UNSUPPORTED_CODEC, participant, key.generation, mimeType); + } + + int clear = codec.clearBytes(keyFrame); + + if (size < clear) { + return fail(stream, CryptoFailure.MALFORMED, participant, key.generation, mimeType); + } + + // The bytes before the SFrame header, which are its metadata too: the + // codec's clear bytes, or the OBU header an AV1 frame is wrapped in. + byte[] metadata; + int metadataLength; + + if (codec == Codec.AV1) { + out[0] = (byte) (keyFrame ? FrameFormat.AV1_KEY_WRAPPER : FrameFormat.AV1_WRAPPER); + metadata = out; + metadataLength = 1; + } + else { + System.arraycopy(in, 0, out, 0, clear); + metadata = in; + metadataLength = clear; + } + + SFrame sframe = key.sframe(keys.getCipherSuite(), stream.context, participant); + + // Never reset, not even by a new key, so that no counter repeats + // under a key ID, whichever key it names. + long ctr = stream.counter++; + + int length = metadataLength + sframe.encrypt(ctr, metadata, 0, metadataLength, + in, clear, size - clear, out, metadataLength); + + boolean newKey = stream.generation != -1 && stream.generation != key.generation; + stream.generation = key.generation; + + keys.encrypted(); + succeed(stream, video, keyFrame, newKey); + + return length; + } + + @Override + boolean isOutgoing() { + return true; + } + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameFormat.java b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameFormat.java new file mode 100644 index 000000000..f899739ee --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/FrameFormat.java @@ -0,0 +1,195 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.e2ee; + +import java.util.Locale; + +/** + * What the frame format adds to RFC 9605: how a KID is made up, and how the + * SFrame ciphertext sits in the frame of each codec so that WebRTC's + * packetizers and depacketizers still find what they read. The guide + * ({@code docs/guide/advanced/end-to-end-encryption.md}) is the + * specification; this class and the browser implementation follow it. + */ +final class FrameFormat { + + /** The largest participant ID, 32 bits. */ + static final long MAX_PARTICIPANT = 0xFFFF_FFFFL; + + /** 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 OBU header an AV1 delta frame is wrapped in: OBU_FRAME (type 6), no + * extension, no size field. The packetizer sends it as one OBU, and the + * depacketizer hands it over with a size field added. + */ + static final int AV1_WRAPPER = 6 << 3; + + /** + * The OBU header an AV1 key frame is wrapped in: OBU_SEQUENCE_HEADER (type + * 1). The packetizer marks a key frame as the start of a new coded video + * sequence, which is how the receiver knows it, only if it begins with a + * sequence header. + */ + static final int AV1_KEY_WRAPPER = 1 << 3; + + /** The most a frame grows by: the AV1 wrapper, a header and a tag. */ + static final int MAX_OVERHEAD = 1 + SFrame.MAX_HEADER_LENGTH + 16; + + + private FrameFormat() { + } + + /** + * KID = context (24 bits) | participant (32 bits) | generation (8 bits), + * from the most significant bits down, after RFC 9605, Section 5.2. + */ + static long kid(int context, long participant, int generation) { + return (long) context << 40 | participant << 8 | generation; + } + + static int context(long kid) { + return (int) (kid >>> 40); + } + + static long participant(long kid) { + return kid >>> 8 & MAX_PARTICIPANT; + } + + static int generation(long kid) { + return (int) (kid & MAX_GENERATION); + } + + /** + * The codecs the format covers, by how their frames are laid out. + */ + enum Codec { + + /** The payload header stays in the clear: 10 bytes on a key frame, 3 otherwise. */ + VP8, + + /** Encrypted whole; its RTP descriptor comes from the encoder, not the bitstream. */ + VP9, + + /** Encrypted whole, inside one OBU the packetizer can carry. */ + AV1, + + /** The TOC byte stays in the clear. */ + OPUS, + + /** Every other audio codec, encrypted whole. */ + AUDIO; + + /** + * @return The codec of a MIME type, or null if the format does not + * cover it, as for H.264 and H.265, whose packetizers split frames at + * start codes that a ciphertext would contain. + */ + static Codec of(String mimeType) { + if (mimeType == null) { + return null; + } + + String type = mimeType.toLowerCase(Locale.ROOT); + + switch (type) { + case "video/vp8": + return VP8; + case "video/vp9": + return VP9; + case "video/av1": + return AV1; + case "audio/opus": + return OPUS; + default: + return type.startsWith("audio/") ? AUDIO : null; + } + } + + /** + * @return The bytes at the start of a frame that stay in the clear, + * and that are the metadata the frame is authenticated with. + */ + int clearBytes(boolean keyFrame) { + switch (this) { + case VP8: + return keyFrame ? 10 : 3; + case OPUS: + return 1; + default: + return 0; + } + } + } + + /** + * The OBU header of an AV1 wrapper as sent, without the size bit the + * depacketizer sets: the metadata an AV1 frame is authenticated with. + */ + static int av1Wrapper(byte header) { + return header & 0xFF & ~0x02; + } + + /** + * Finds the SFrame ciphertext in a received AV1 frame: the payload of the + * one OBU it consists of. + * + * @return The offset of the payload, or -1 if the frame is no wrapped + * ciphertext. + */ + static int av1PayloadOffset(byte[] frame, int size) { + if (size < 1) { + return -1; + } + + int header = av1Wrapper(frame[0]); + + // Type 1 or 6, no extension, the forbidden and reserved bits clear; + // the depacketizer may have set the size bit. + if (header != AV1_WRAPPER && header != AV1_KEY_WRAPPER) { + return -1; + } + if ((frame[0] & 0x02) == 0) { + return 1; + } + + long obuSize = 0; + int position = 1; + + for (int i = 0; i < 8; i++, position++) { + if (position >= size) { + return -1; + } + + int b = frame[position] & 0xFF; + obuSize |= (long) (b & 0x7F) << (7 * i); + + if ((b & 0x80) == 0) { + position++; + + return obuSize == size - position ? position : -1; + } + } + + return -1; + } + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/KeyProvider.java b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/KeyProvider.java new file mode 100644 index 000000000..354b9f97f --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/KeyProvider.java @@ -0,0 +1,683 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.e2ee; + +import static java.util.Objects.requireNonNull; + +import java.security.SecureRandom; +import java.time.Duration; +import java.util.Arrays; +import java.util.EnumMap; +import java.util.Map; +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.concurrent.atomic.AtomicReferenceArray; +import java.util.concurrent.atomic.LongAdder; + +import dev.onvoid.webrtc.RTCEncodedFrameTransformer; + +/** + * The keys of an end-to-end encrypted call, and the transforms that encrypt + * and decrypt its frames with them, in the SFrame format of RFC 9605. + *

    + * Every participant of a call has an ID, unique within the call, and a key of + * its own that it encrypts with and the others decrypt with (the sender keys + * of RFC 9605, Section 5.1). A key belongs to a generation, 0 to + * 255, which goes up with every new key and wraps around. Getting the keys to + * the other participants, over a channel the media servers cannot read, is + * up to the application; this class only holds them: + *

    {@code
    + * KeyProvider keys = KeyProvider.builder(myId).build();
    + *
    + * byte[] myKey = keys.generateKey();
    + * keys.setEncryptionKey(0, myKey);
    + * // send (myId, 0, myKey) to the others; for each key they send:
    + * keys.setDecryptionKey(theirId, theirGeneration, theirKey);
    + *
    + * sender.setTransform(keys.createEncryptor(sender::generateKeyFrame));
    + * receiver.setTransform(keys.createDecryptor(receiver::requestKeyFrame));
    + * }
    + *

    + * How it behaves: + *

      + *
    • Each RTP stream an encryptor sends gets a context of its own, and so a + * key ID and an encryption key of its own derived from the participant's + * key: audio, video and every simulcast layer count their frames + * independently, and no two of them, nor two participants, ever encrypt + * under the same key and nonce.
    • + *
    • To rotate its key, a participant sends the new one to the others + * first, and calls {@link #setEncryptionKey} once they have it: frames go + * out with the new key from then on, and a video stream begins with a key + * frame. A receiver keeps the previous generations of a participant until + * {@link Builder#keyRetention a while} after a frame of a newer one + * decrypted.
    • + *
    • A received frame whose key is not there, that does not authenticate, + * or that repeats a counter is dropped and never reaches the decoder, see + * {@link CryptoFailure}. A video receiver asks for a key frame once frames + * decrypt again.
    • + *
    • A frame that cannot be encrypted is dropped, never sent in the + * clear.
    • + *
    • The transforms do not let {@code MediaRecorder}, or any other observer + * of encoded frames, see the decrypted media unless {@link + * Builder#allowPlaintextRecording} says so.
    • + *
    + *

    + * All methods are thread-safe, and key changes take effect with the next + * frame. + * + * @author Alex Andres + */ +public final class KeyProvider { + + /** The smallest base key accepted, in bytes. */ + static final int MIN_KEY_LENGTH = 16; + + private final CipherSuite suite; + + private final long participant; + + private final int replayWindow; + + private final long keyRetentionNanos; + + private final boolean plaintextRecording; + + private final CryptoListener listener; + + private final SecureRandom random = new SecureRandom(); + + private volatile LocalKey encryptionKey; + + private final ConcurrentHashMap participants = new ConcurrentHashMap<>(); + + /** The next context to give out. Never reused, so neither is a key ID. */ + private final AtomicInteger contexts = new AtomicInteger(); + + private final LongAdder encrypted = new LongAdder(); + + private final LongAdder decrypted = new LongAdder(); + + private final Map dropped = new EnumMap<>(CryptoFailure.class); + + + private KeyProvider(Builder builder) { + this.suite = builder.suite; + this.participant = builder.participant; + this.replayWindow = builder.replayWindow; + this.keyRetentionNanos = builder.keyRetention.toNanos(); + this.plaintextRecording = builder.plaintextRecording; + this.listener = builder.listener; + + for (CryptoFailure failure : CryptoFailure.values()) { + dropped.put(failure, new LongAdder()); + } + } + + /** + * Starts a key provider for the local participant of a call. + * + * @param participant The ID of the local participant, unique within the + * call, from 0 to 232-1. + * + * @return A builder using AES-128-GCM. + * + * @throws IllegalArgumentException If the ID is out of range. + */ + public static Builder builder(long participant) { + return new Builder(checkParticipant(participant)); + } + + /** + * Makes a new random key, as long as the cipher suite's hash output. A + * key is meant for one call: never use it again with another key + * provider, since the counters of a new provider start over. + * + * @return The key. + */ + public byte[] generateKey() { + byte[] key = new byte[suite.getHashLength()]; + random.nextBytes(key); + + return key; + } + + /** + * Sets the key the local participant encrypts with from now on, of the + * given generation. The other participants should have it before, or + * they drop the frames until it arrives. Setting a generation again + * replaces its key. + * + * @param generation The key generation, 0 to 255. + * @param key The key, at least 16 bytes; it is copied. + * + * @throws IllegalArgumentException If the generation is out of range, or + * the key too short. + */ + public void setEncryptionKey(int generation, byte[] key) { + checkGeneration(generation); + + encryptionKey = new LocalKey(generation, copyKey(key)); + } + + /** + * Removes the encryption key, after which every frame to be sent is + * dropped, e.g. while the participant is not allowed to send. + */ + public void removeEncryptionKey() { + encryptionKey = null; + } + + /** + * @return The generation of the encryption key, or -1 if there is none. + */ + public int getEncryptionGeneration() { + LocalKey key = encryptionKey; + + return key == null ? -1 : key.generation; + } + + /** + * Sets a key that frames of another participant are decrypted with. A + * participant's generations are kept side by side, so that a new key can + * be set before the participant starts to use it; setting a generation + * again with another key replaces it. + * + * @param participant The ID of the participant. + * @param generation The key generation, 0 to 255. + * @param key The key, at least 16 bytes; it is copied. + * + * @throws IllegalArgumentException If the participant is the local one, + * whose key is only for encryption, if + * a value is out of range, or the key + * too short. + */ + public void setDecryptionKey(long participant, int generation, byte[] key) { + checkParticipant(participant); + checkGeneration(generation); + + if (participant == this.participant) { + throw new IllegalArgumentException("A key of the local participant is only for encryption"); + } + + byte[] copy = copyKey(key); + RemoteParticipant remote = participants.computeIfAbsent(participant, id -> new RemoteParticipant()); + + synchronized (remote) { + RemoteKey current = remote.keys.get(generation); + + if (current != null && Arrays.equals(current.baseKey, copy)) { + // The same key again, e.g. sent once more by the signaling: + // keeps the frames seen, so that none can be replayed. + current.retireAt = 0; + return; + } + + remote.keys.set(generation, new RemoteKey(generation, copy)); + } + } + + /** + * Removes a decryption key. Frames of that generation are dropped from + * now on. + * + * @param participant The ID of the participant. + * @param generation The key generation. + * + * @return True if there was such a key. + */ + public boolean removeDecryptionKey(long participant, int generation) { + RemoteParticipant remote = participants.get(participant); + + if (remote == null || generation < 0 || generation > FrameFormat.MAX_GENERATION) { + return false; + } + + return remote.keys.getAndSet(generation, null) != null; + } + + /** + * Removes every decryption key of a participant, e.g. one that left. + * + * @param participant The ID of the participant. + * + * @return True if there were keys of the participant. + */ + public boolean removeParticipant(long participant) { + return participants.remove(participant) != null; + } + + /** + * Creates a transform for senders that encrypts their frames. One + * encryptor may serve several senders, but each sender with an encryptor + * of its own can be asked for a key frame when the key changes. + * + * @return The encryptor. + */ + public RTCEncodedFrameTransformer createEncryptor() { + return new FrameEncryptor(this, null); + } + + /** + * Creates a transform for a sender that encrypts its frames, and asks the + * sender's encoder for a key frame when a video stream starts to use a + * new key, or once its frames can be sent again, so that receivers that + * just got the key need not wait for one. + * + * @param keyFrameRequest Asks the sender for a key frame, e.g. {@code + * sender::generateKeyFrame}. It runs on the + * transform's thread. + * + * @return The encryptor. + */ + public RTCEncodedFrameTransformer createEncryptor(Runnable keyFrameRequest) { + return new FrameEncryptor(this, requireNonNull(keyFrameRequest, "keyFrameRequest")); + } + + /** + * Creates a transform for receivers that decrypts their frames. + * + * @return The decryptor. + */ + public RTCEncodedFrameTransformer createDecryptor() { + return new FrameDecryptor(this, null); + } + + /** + * Creates a transform for a receiver that decrypts its frames, and asks + * the remote sender for a key frame once video frames decrypt again after + * some were dropped, since the decoder cannot use the frames that follow + * a missing one. + * + * @param keyFrameRequest Asks for a key frame, e.g. {@code + * receiver::requestKeyFrame}. It runs on the + * transform's thread. + * + * @return The decryptor. + */ + public RTCEncodedFrameTransformer createDecryptor(Runnable keyFrameRequest) { + return new FrameDecryptor(this, requireNonNull(keyFrameRequest, "keyFrameRequest")); + } + + /** + * @return The frames encrypted, decrypted and dropped so far. + */ + public CryptoStats getStats() { + Map counts = new EnumMap<>(CryptoFailure.class); + + dropped.forEach((failure, count) -> counts.put(failure, count.sum())); + + return new CryptoStats(encrypted.sum(), decrypted.sum(), counts); + } + + /** + * @return The ID of the local participant. + */ + public long getParticipant() { + return participant; + } + + /** + * @return The cipher suite of the call. + */ + public CipherSuite getCipherSuite() { + return suite; + } + + /** + * @return Whether observers of encoded frames, such as a recorder, may + * see what the transforms protect. + */ + public boolean allowsPlaintextRecording() { + return plaintextRecording; + } + + LocalKey encryptionKey() { + return encryptionKey; + } + + /** + * Gives out a context for a new stream. + * + * @return The context, or -1 if all were given out. + */ + int allocateContext() { + int context = contexts.getAndUpdate(c -> c > FrameFormat.MAX_CONTEXT ? c : c + 1); + + return context > FrameFormat.MAX_CONTEXT ? -1 : context; + } + + /** + * Looks up the decryption key of a key ID, and retires it if its time is + * up. + */ + RemoteKey decryptionKey(long participant, int generation, long now) { + RemoteParticipant remote = participants.get(participant); + + if (remote == null) { + return null; + } + + RemoteKey key = remote.keys.get(generation); + + if (key != null && key.retireAt != 0 && now - key.retireAt > 0) { + remote.keys.compareAndSet(generation, key, null); + + return null; + } + + return key; + } + + /** + * Notes that a frame decrypted with a key: once a generation newer than + * any before is in use, the older ones retire after the retention time. + */ + void decryptedWith(long participant, RemoteKey key, long now) { + decrypted.increment(); + + RemoteParticipant remote = participants.get(participant); + + if (remote == null || remote.newest == key.generation) { + return; + } + + synchronized (remote) { + if (remote.newest != -1 && !isNewer(key.generation, remote.newest)) { + return; + } + + remote.newest = key.generation; + + long retireAt = now + keyRetentionNanos; + + if (retireAt == 0) { + retireAt = 1; + } + + for (int g = 0; g <= FrameFormat.MAX_GENERATION; g++) { + RemoteKey other = remote.keys.get(g); + + if (other != null && other != key && other.retireAt == 0 && isNewer(key.generation, g)) { + other.retireAt = retireAt; + } + } + } + } + + void encrypted() { + encrypted.increment(); + } + + void dropped(CryptoFailure failure) { + dropped.get(failure).increment(); + } + + int replayWindow() { + return replayWindow; + } + + void report(CryptoEvent event) { + CryptoListener current = listener; + + if (current == null) { + return; + } + + try { + current.onFailure(event); + } + catch (Throwable e) { + Thread thread = Thread.currentThread(); + + try { + thread.getUncaughtExceptionHandler().uncaughtException(thread, e); + } + catch (Throwable ignored) { + // Nothing more can be done about it here. + } + } + } + + /** + * Whether generation a came after b, given that generations wrap around + * at 256 and at most 127 of them are in use at a time. + */ + static boolean isNewer(int a, int b) { + int distance = (a - b) & FrameFormat.MAX_GENERATION; + + return distance > 0 && distance < 128; + } + + private static long checkParticipant(long participant) { + if (participant < 0 || participant > FrameFormat.MAX_PARTICIPANT) { + throw new IllegalArgumentException("A participant ID is from 0 to 2^32-1: " + participant); + } + + return participant; + } + + private static void checkGeneration(int generation) { + if (generation < 0 || generation > FrameFormat.MAX_GENERATION) { + throw new IllegalArgumentException("A key generation is from 0 to 255: " + generation); + } + } + + private static byte[] copyKey(byte[] key) { + requireNonNull(key, "key"); + + if (key.length < MIN_KEY_LENGTH) { + throw new IllegalArgumentException("A key has at least " + MIN_KEY_LENGTH + " bytes"); + } + + return key.clone(); + } + + + + /** + * Configures a {@link KeyProvider}. + */ + public static final class Builder { + + private final long participant; + + private CipherSuite suite = CipherSuite.AES_128_GCM_SHA256_128; + + private int replayWindow = 128; + + private Duration keyRetention = Duration.ofSeconds(5); + + private boolean plaintextRecording; + + private CryptoListener listener; + + + private Builder(long participant) { + this.participant = participant; + } + + /** + * Sets the cipher suite, which every participant has to use alike. + * The default is {@link CipherSuite#AES_128_GCM_SHA256_128}. + * + * @param suite The cipher suite. + * + * @return This builder. + */ + public Builder cipherSuite(CipherSuite suite) { + this.suite = requireNonNull(suite, "suite"); + return this; + } + + /** + * Sets how far back from the newest frame of a stream a frame that + * arrives late is still accepted, in frames; a frame further back, + * or one decrypted before, is dropped as a replay. The default of + * 128 is several seconds of any stream, more than any reordering. + * 0 turns replay protection off. + * + * @param frames The window, rounded up to a multiple of 64, at most + * 65536. + * + * @return This builder. + */ + public Builder replayWindow(int frames) { + if (frames < 0 || frames > 65536) { + throw new IllegalArgumentException("The replay window is from 0 to 65536 frames: " + frames); + } + + this.replayWindow = (frames + 63) / 64 * 64; + return this; + } + + /** + * Sets how long a participant's older key generations still decrypt + * after a frame of a newer generation did, for frames that were on + * their way during the switch. The default is 5 seconds. + * + * @param retention The time, zero or more. + * + * @return This builder. + */ + public Builder keyRetention(Duration retention) { + requireNonNull(retention, "retention"); + + if (retention.isNegative()) { + throw new IllegalArgumentException("The key retention is negative: " + retention); + } + + this.keyRetention = retention; + return this; + } + + /** + * Sets whether observers of encoded frames may see what the + * transforms protect: a sender's frames before they are encrypted, a + * receiver's after they are decrypted. Such an observer is, above + * all, a {@code MediaRecorder}, which stores the media in the clear. + * The default is false: a recorder refuses the senders and receivers + * of the transforms, and frames are kept from any observer. + * + * @param allowed Whether to allow it. + * + * @return This builder. + */ + public Builder allowPlaintextRecording(boolean allowed) { + this.plaintextRecording = allowed; + return this; + } + + /** + * Sets what hears of streams that begin to drop frames. + * + * @param listener The listener. + * + * @return This builder. + */ + public Builder listener(CryptoListener listener) { + this.listener = requireNonNull(listener, "listener"); + return this; + } + + /** + * @return The key provider, without keys yet. + */ + public KeyProvider build() { + return new KeyProvider(this); + } + } + + + + /** The key the local participant encrypts with. */ + static final class LocalKey { + + final int generation; + + private final byte[] baseKey; + + /** The derived key of each context. */ + private final ConcurrentHashMap derived = new ConcurrentHashMap<>(); + + + LocalKey(int generation, byte[] baseKey) { + this.generation = generation; + this.baseKey = baseKey; + } + + SFrame sframe(CipherSuite suite, int context, long participant) { + return derived.computeIfAbsent(context, c -> + SFrame.derive(suite, FrameFormat.kid(c, participant, generation), baseKey)); + } + } + + + + /** A key that frames of another participant are decrypted with. */ + static final class RemoteKey { + + final int generation; + + final byte[] baseKey; + + /** When the key retires, in System.nanoTime(), or 0 while it is in use. */ + volatile long retireAt; + + /** What each context of the participant needs to decrypt. */ + private final ConcurrentHashMap openers = new ConcurrentHashMap<>(); + + + RemoteKey(int generation, byte[] baseKey) { + this.generation = generation; + this.baseKey = baseKey; + } + + Opener opener(CipherSuite suite, long kid, int window) { + return openers.computeIfAbsent(FrameFormat.context(kid), c -> + new Opener(SFrame.derive(suite, kid, baseKey), window > 0 ? new ReplayWindow(window) : null)); + } + } + + + + /** The derived key of one key ID, and the counters it has seen. */ + static final class Opener { + + final SFrame sframe; + + /** Null if replay protection is off. */ + final ReplayWindow window; + + + Opener(SFrame sframe, ReplayWindow window) { + this.sframe = sframe; + this.window = window; + } + } + + + + /** The decryption keys of another participant. */ + private static final class RemoteParticipant { + + final AtomicReferenceArray keys = new AtomicReferenceArray<>(FrameFormat.MAX_GENERATION + 1); + + /** The newest generation that decrypted a frame, or -1. */ + volatile int newest = -1; + } + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/ReplayWindow.java b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/ReplayWindow.java new file mode 100644 index 000000000..c04f73a26 --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/ReplayWindow.java @@ -0,0 +1,123 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.e2ee; + +/** + * The counters seen of one KID, after the anti-replay window of SRTP (RFC + * 3711, Section 3.3.2) that RFC 9605, Section 9.3 suggests: a counter is + * accepted once, and only if it is newer than the highest one seen or at + * most a window's size older. + *

    + * A counter is only marked as seen once its frame authenticated, so that + * forged frames cannot move the window. + */ +final class ReplayWindow { + + private final int size; + + /** One bit per counter of the window, indexed by counter modulo size. */ + private final long[] seen; + + /** The highest counter accepted, unsigned; meaningless while empty. */ + private long highest; + + private boolean empty = true; + + + /** + * @param size The number of counters below the highest one that are + * still accepted, a multiple of 64. + */ + ReplayWindow(int size) { + this.size = size; + this.seen = new long[size / 64]; + } + + /** + * @return Whether a frame with the counter may be decrypted. + */ + synchronized boolean isFresh(long ctr) { + if (empty || Long.compareUnsigned(ctr, highest) > 0) { + return true; + } + + long age = highest - ctr; + + return Long.compareUnsigned(age, size) < 0 && !isSeen(ctr); + } + + /** + * Marks a counter as seen, after its frame authenticated. + * + * @return False if it was seen meanwhile, or fell out of the window. + */ + synchronized boolean accept(long ctr) { + if (empty) { + empty = false; + highest = ctr; + mark(ctr); + return true; + } + + if (Long.compareUnsigned(ctr, highest) > 0) { + long advance = ctr - highest; + + if (Long.compareUnsigned(advance, size) >= 0) { + java.util.Arrays.fill(seen, 0); + } + else { + for (long c = highest + 1; c != ctr; c++) { + clear(c); + } + } + + highest = ctr; + mark(ctr); + return true; + } + + if (Long.compareUnsigned(highest - ctr, size) >= 0 || isSeen(ctr)) { + return false; + } + + mark(ctr); + return true; + } + + private boolean isSeen(long ctr) { + int bit = index(ctr); + + return (seen[bit >>> 6] & 1L << (bit & 63)) != 0; + } + + private void mark(long ctr) { + int bit = index(ctr); + + seen[bit >>> 6] |= 1L << (bit & 63); + } + + private void clear(long ctr) { + int bit = index(ctr); + + seen[bit >>> 6] &= ~(1L << (bit & 63)); + } + + private int index(long ctr) { + return (int) Long.remainderUnsigned(ctr, size); + } + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/SFrame.java b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/SFrame.java new file mode 100644 index 000000000..31958b0c1 --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/SFrame.java @@ -0,0 +1,436 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.e2ee; + +import java.nio.charset.StandardCharsets; +import java.security.GeneralSecurityException; +import java.security.MessageDigest; +import java.util.Arrays; +import java.util.HashMap; +import java.util.Map; + +import javax.crypto.AEADBadTagException; +import javax.crypto.Cipher; +import javax.crypto.Mac; +import javax.crypto.spec.GCMParameterSpec; +import javax.crypto.spec.IvParameterSpec; +import javax.crypto.spec.SecretKeySpec; + +/** + * The SFrame operations of RFC 9605: the header encoding (Section 4.3), the + * key and salt derivation (Section 4.4.2), and the encryption and decryption + * of one SFrame ciphertext (Sections 4.4.3 to 4.5.1). + *

    + * An instance is the derived key of one KID, and may be used from any + * thread: the JCA objects it needs are kept per thread. + */ +final class SFrame { + + private static final byte[] KEY_LABEL = "SFrame 1.0 Secret key ".getBytes(StandardCharsets.US_ASCII); + + private static final byte[] SALT_LABEL = "SFrame 1.0 Secret salt ".getBytes(StandardCharsets.US_ASCII); + + /** The longest header: the config byte, an 8-byte KID and an 8-byte CTR. */ + static final int MAX_HEADER_LENGTH = 17; + + private static final ThreadLocal GCM = ThreadLocal.withInitial(() -> cipher("AES/GCM/NoPadding")); + + private static final ThreadLocal CTR = ThreadLocal.withInitial(() -> cipher("AES/CTR/NoPadding")); + + private static final ThreadLocal> MACS = ThreadLocal.withInitial(HashMap::new); + + private final CipherSuite suite; + + private final long kid; + + /** The AES key: all of sframe_key for GCM, its first Nka bytes for CTR. */ + private final SecretKeySpec aesKey; + + /** The HMAC key of the CTR suites, the rest of sframe_key; null for GCM. */ + private final SecretKeySpec authKey; + + private final byte[] salt; + + + private SFrame(CipherSuite suite, long kid, byte[] sframeKey, byte[] salt) { + this.suite = suite; + this.kid = kid; + this.salt = salt; + + if (suite.isGcm()) { + this.aesKey = new SecretKeySpec(sframeKey, "AES"); + this.authKey = null; + } + else { + int split = suite.aesKeyLength(); + + this.aesKey = new SecretKeySpec(sframeKey, 0, split, "AES"); + this.authKey = new SecretKeySpec(sframeKey, split, sframeKey.length - split, suite.hmac()); + } + } + + /** Wraps an sframe_key and sframe_salt that are already derived. */ + static SFrame of(CipherSuite suite, long kid, byte[] sframeKey, byte[] salt) { + return new SFrame(suite, kid, sframeKey.clone(), salt.clone()); + } + + /** + * Derives the key and salt of a KID from a base key, as + * {@code derive_key_salt} does. + */ + static SFrame derive(CipherSuite suite, long kid, byte[] baseKey) { + byte[] secret = hkdfExtract(suite, baseKey); + + try { + byte[] key = hkdfExpand(suite, secret, label(KEY_LABEL, kid, suite), suite.keyLength()); + byte[] salt = hkdfExpand(suite, secret, label(SALT_LABEL, kid, suite), CipherSuite.NONCE_LENGTH); + + return new SFrame(suite, kid, key, salt); + } + finally { + Arrays.fill(secret, (byte) 0); + } + } + + long kid() { + return kid; + } + + /** + * Encrypts a plaintext with the given counter: writes the SFrame header + * at {@code out[outOffset]} followed by the ciphertext and its tag. The + * metadata is authenticated with the header but not written. + * + * @return The number of bytes written. + */ + int encrypt(long ctr, byte[] metadata, int metadataOffset, int metadataLength, + byte[] plaintext, int plaintextOffset, int plaintextLength, byte[] out, int outOffset) { + int headerLength = writeHeader(kid, ctr, out, outOffset); + + return headerLength + seal(nonce(ctr), out, outOffset, headerLength, metadata, metadataOffset, + metadataLength, plaintext, plaintextOffset, plaintextLength, out, outOffset + headerLength); + } + + /** + * AEAD.Encrypt with the AAD in two parts, the header and the metadata. + * + * @return The size of the ciphertext with its tag. + */ + int seal(byte[] nonce, byte[] header, int headerOffset, int headerLength, + byte[] metadata, int metadataOffset, int metadataLength, + byte[] plaintext, int plaintextOffset, int plaintextLength, byte[] out, int outOffset) { + try { + if (suite.isGcm()) { + Cipher cipher = GCM.get(); + cipher.init(Cipher.ENCRYPT_MODE, aesKey, new GCMParameterSpec(suite.getTagLength() * 8, nonce)); + cipher.updateAAD(header, headerOffset, headerLength); + cipher.updateAAD(metadata, metadataOffset, metadataLength); + + return cipher.doFinal(plaintext, plaintextOffset, plaintextLength, out, outOffset); + } + + Cipher cipher = CTR.get(); + cipher.init(Cipher.ENCRYPT_MODE, aesKey, new IvParameterSpec(counterBlock(nonce))); + int ctLength = cipher.doFinal(plaintext, plaintextOffset, plaintextLength, out, outOffset); + + byte[] tag = tag(nonce, header, headerOffset, headerLength, metadata, metadataOffset, metadataLength, + out, outOffset, ctLength); + System.arraycopy(tag, 0, out, outOffset + ctLength, suite.getTagLength()); + + return ctLength + suite.getTagLength(); + } + catch (GeneralSecurityException e) { + throw new IllegalStateException("Encrypting a frame failed", e); + } + } + + /** + * Decrypts the ciphertext and tag that follow a parsed header, writing + * the plaintext to {@code out[outOffset]}. + * + * @return The size of the plaintext, or -1 if the frame did not + * authenticate. + */ + int decrypt(long ctr, byte[] header, int headerOffset, int headerLength, + byte[] metadata, int metadataOffset, int metadataLength, + byte[] ciphertext, int ciphertextOffset, int ciphertextLength, byte[] out, int outOffset) { + return open(nonce(ctr), header, headerOffset, headerLength, metadata, metadataOffset, metadataLength, + ciphertext, ciphertextOffset, ciphertextLength, out, outOffset); + } + + /** + * AEAD.Decrypt with the AAD in two parts, the header and the metadata. + * + * @return The size of the plaintext, or -1 if it did not authenticate. + */ + int open(byte[] nonce, byte[] header, int headerOffset, int headerLength, + byte[] metadata, int metadataOffset, int metadataLength, + byte[] ciphertext, int ciphertextOffset, int ciphertextLength, byte[] out, int outOffset) { + int tagLength = suite.getTagLength(); + + if (ciphertextLength < tagLength) { + return -1; + } + + try { + if (suite.isGcm()) { + Cipher cipher = GCM.get(); + cipher.init(Cipher.DECRYPT_MODE, aesKey, new GCMParameterSpec(tagLength * 8, nonce)); + cipher.updateAAD(header, headerOffset, headerLength); + cipher.updateAAD(metadata, metadataOffset, metadataLength); + + return cipher.doFinal(ciphertext, ciphertextOffset, ciphertextLength, out, outOffset); + } + + int innerLength = ciphertextLength - tagLength; + byte[] expected = tag(nonce, header, headerOffset, headerLength, metadata, metadataOffset, + metadataLength, ciphertext, ciphertextOffset, innerLength); + + byte[] actual = Arrays.copyOfRange(ciphertext, ciphertextOffset + innerLength, + ciphertextOffset + ciphertextLength); + + if (!MessageDigest.isEqual(actual, Arrays.copyOf(expected, tagLength))) { + return -1; + } + + Cipher cipher = CTR.get(); + cipher.init(Cipher.DECRYPT_MODE, aesKey, new IvParameterSpec(counterBlock(nonce))); + + return cipher.doFinal(ciphertext, ciphertextOffset, innerLength, out, outOffset); + } + catch (AEADBadTagException e) { + return -1; + } + catch (GeneralSecurityException e) { + throw new IllegalStateException("Decrypting a frame failed", e); + } + } + + /** + * The nonce of a counter: the salt XORed with the counter as a big-endian + * integer of the nonce's size. + */ + byte[] nonce(long ctr) { + byte[] nonce = salt.clone(); + + for (int i = 0; i < Long.BYTES; i++) { + nonce[nonce.length - 1 - i] ^= (byte) (ctr >>> (8 * i)); + } + + return nonce; + } + + /** + * Returns the size of the header for a KID and CTR. Both are unsigned + * 64-bit values. + */ + static int headerLength(long kid, long ctr) { + return 1 + extendedLength(kid) + extendedLength(ctr); + } + + /** + * Writes the header for a KID and CTR, as {@code encode_sframe_header} + * does. + * + * @return The number of bytes written. + */ + static int writeHeader(long kid, long ctr, byte[] out, int offset) { + int kidLength = extendedLength(kid); + int ctrLength = extendedLength(ctr); + + int config = 0; + config |= kidLength == 0 ? (int) kid << 4 : 0x80 | (kidLength - 1) << 4; + config |= ctrLength == 0 ? (int) ctr : 0x08 | (ctrLength - 1); + + out[offset] = (byte) config; + + writeBigEndian(kid, kidLength, out, offset + 1); + writeBigEndian(ctr, ctrLength, out, offset + 1 + kidLength); + + return 1 + kidLength + ctrLength; + } + + /** + * Parses a header. Only the minimal encoding RFC 9605 requires is + * accepted. + * + * @param values Receives the KID at index 0 and the CTR at index 1. + * + * @return The size of the header, or -1 if the bytes are no valid header. + */ + static int parseHeader(byte[] in, int offset, int length, long[] values) { + if (length < 1) { + return -1; + } + + int config = in[offset] & 0xFF; + int position = 1; + + for (int field = 0; field < 2; field++) { + int bits = field == 0 ? config >>> 4 : config; + boolean extended = (bits & 0x08) != 0; + int value = bits & 0x07; + + if (!extended) { + values[field] = value; + continue; + } + + int size = value + 1; + + if (length - position < size || in[offset + position] == 0) { + // Too short, or not the shortest encoding. + return -1; + } + + long decoded = 0; + + for (int i = 0; i < size; i++) { + decoded = decoded << 8 | (in[offset + position + i] & 0xFF); + } + + if (Long.compareUnsigned(decoded, 8) < 0) { + return -1; + } + + values[field] = decoded; + position += size; + } + + return position; + } + + private byte[] tag(byte[] nonce, byte[] header, int headerOffset, int headerLength, + byte[] metadata, int metadataOffset, int metadataLength, + byte[] ct, int ctOffset, int ctLength) throws GeneralSecurityException { + Mac mac = mac(suite.hmac()); + mac.init(authKey); + + byte[] lengths = new byte[24]; + writeBigEndian(headerLength + metadataLength, 8, lengths, 0); + writeBigEndian(ctLength, 8, lengths, 8); + writeBigEndian(suite.getTagLength(), 8, lengths, 16); + + mac.update(lengths); + mac.update(nonce); + mac.update(header, headerOffset, headerLength); + mac.update(metadata, metadataOffset, metadataLength); + mac.update(ct, ctOffset, ctLength); + + return mac.doFinal(); + } + + /** The initial counter block of AES-CTR: the nonce and four zero bytes. */ + private static byte[] counterBlock(byte[] nonce) { + return Arrays.copyOf(nonce, 16); + } + + static byte[] hkdfExtract(CipherSuite suite, byte[] ikm) { + try { + Mac mac = mac(suite.hmac()); + // An empty salt is a string of zeros as long as the hash + // (RFC 5869, Section 2.2), which HMAC pads alike. + mac.init(new SecretKeySpec(new byte[suite.getHashLength()], suite.hmac())); + + return mac.doFinal(ikm); + } + catch (GeneralSecurityException e) { + throw new IllegalStateException(e); + } + } + + static byte[] hkdfExpand(CipherSuite suite, byte[] prk, byte[] info, int length) { + try { + Mac mac = mac(suite.hmac()); + mac.init(new SecretKeySpec(prk, suite.hmac())); + + byte[] okm = new byte[length]; + byte[] block = new byte[0]; + int written = 0; + + for (int i = 1; written < length; i++) { + mac.update(block); + mac.update(info); + mac.update((byte) i); + block = mac.doFinal(); + + int n = Math.min(block.length, length - written); + System.arraycopy(block, 0, okm, written, n); + written += n; + } + + return okm; + } + catch (GeneralSecurityException e) { + throw new IllegalStateException(e); + } + } + + /** A label followed by the KID as 8 bytes and the suite as 2 bytes. */ + static byte[] label(byte[] prefix, long kid, CipherSuite suite) { + byte[] label = Arrays.copyOf(prefix, prefix.length + 10); + + writeBigEndian(kid, 8, label, prefix.length); + writeBigEndian(suite.getId(), 2, label, prefix.length + 8); + + return label; + } + + static byte[] keyLabel(long kid, CipherSuite suite) { + return label(KEY_LABEL, kid, suite); + } + + static byte[] saltLabel(long kid, CipherSuite suite) { + return label(SALT_LABEL, kid, suite); + } + + /** The number of bytes after the config byte for a value: 0 if below 8. */ + private static int extendedLength(long value) { + if (Long.compareUnsigned(value, 8) < 0) { + return 0; + } + + return (Long.SIZE - Long.numberOfLeadingZeros(value) + 7) / 8; + } + + private static void writeBigEndian(long value, int length, byte[] out, int offset) { + for (int i = 0; i < length; i++) { + out[offset + i] = (byte) (value >>> (8 * (length - 1 - i))); + } + } + + private static Mac mac(String algorithm) { + return MACS.get().computeIfAbsent(algorithm, name -> { + try { + return Mac.getInstance(name); + } + catch (GeneralSecurityException e) { + throw new IllegalStateException(name + " is not available", e); + } + }); + } + + private static Cipher cipher(String transformation) { + try { + return Cipher.getInstance(transformation); + } + catch (GeneralSecurityException e) { + throw new IllegalStateException(transformation + " is not available", e); + } + } + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/internal/NativeApi.java b/webrtc/src/main/java/dev/onvoid/webrtc/internal/NativeApi.java index f554445d4..b6f9db157 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/internal/NativeApi.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/internal/NativeApi.java @@ -186,6 +186,24 @@ public static void releaseEncodedFrames(long frames) { } } + /** + * Says whether the transform set on the sender or receiver of a handle + * keeps its frames from observers, as an end-to-end encryption transform + * does unless told otherwise: observers attached to the handle see no + * frame for as long as it is set. + * + * @param frames The handle from {@code encodedFramesOf()}, not released. + * + * @return True if the frames are kept from observers. + * + * @see dev.onvoid.webrtc.RTCEncodedFrameTransformer#allowsPlaintextObservers() + */ + public static boolean isSealed(long frames) { + return frames != 0 && framesSealed(frames); + } + + private static native boolean framesSealed(long frames); + private static native long senderFrames(long senderHandle); private static native long receiverFrames(long receiverHandle); diff --git a/webrtc/src/main/java/module-info.java b/webrtc/src/main/java/module-info.java index 8a613027c..0f960353e 100644 --- a/webrtc/src/main/java/module-info.java +++ b/webrtc/src/main/java/module-info.java @@ -7,6 +7,7 @@ exports dev.onvoid.webrtc; exports dev.onvoid.webrtc.client; + exports dev.onvoid.webrtc.e2ee; exports dev.onvoid.webrtc.logging; exports dev.onvoid.webrtc.media; exports dev.onvoid.webrtc.media.audio; diff --git a/webrtc/src/test/java/dev/onvoid/webrtc/E2eeCallTests.java b/webrtc/src/test/java/dev/onvoid/webrtc/E2eeCallTests.java new file mode 100644 index 000000000..ce60ab664 --- /dev/null +++ b/webrtc/src/test/java/dev/onvoid/webrtc/E2eeCallTests.java @@ -0,0 +1,356 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.Assertions.fail; +import static org.junit.jupiter.api.Assumptions.assumeTrue; + +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.function.BooleanSupplier; + +import dev.onvoid.webrtc.e2ee.CryptoFailure; +import dev.onvoid.webrtc.e2ee.KeyProvider; +import dev.onvoid.webrtc.internal.AllocationFault; +import dev.onvoid.webrtc.internal.NativeApi; +import dev.onvoid.webrtc.media.MediaType; +import dev.onvoid.webrtc.media.video.VideoTrack; +import dev.onvoid.webrtc.media.video.VideoTrackSink; + +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.parallel.Execution; +import org.junit.jupiter.api.parallel.ExecutionMode; + +/** + * Tests end-to-end encryption with a {@link KeyProvider} on a call between + * two local peer connections, through WebRTC's real packetizers, depacketizers + * and decoders. + */ +@Execution(ExecutionMode.SAME_THREAD) +class E2eeCallTests extends TestBase { + + private static final long TIMEOUT_SECONDS = 10; + + private static final long CALLER = 1; + private static final long CALLEE = 2; + + private KeyProvider callerKeys; + private KeyProvider calleeKeys; + + private byte[] callerKey; + + + @BeforeEach + void createKeys() { + callerKeys = KeyProvider.builder(CALLER).build(); + calleeKeys = KeyProvider.builder(CALLEE).build(); + + callerKey = callerKeys.generateKey(); + callerKeys.setEncryptionKey(0, callerKey); + calleeKeys.setDecryptionKey(CALLER, 0, callerKey); + } + + @Test + void encryptedVp8Decodes() throws Exception { + assertVideoDecodes("VP8"); + } + + @Test + void encryptedVp9Decodes() throws Exception { + assertVideoDecodes("VP9"); + } + + @Test + void encryptedAv1Decodes() throws Exception { + assertVideoDecodes("AV1"); + } + + private void assertVideoDecodes(String codec) throws Exception { + assumeTrue(canSend(codec), codec + " is not available"); + + AtomicInteger decoded = new AtomicInteger(); + + try (TestMediaCall call = new TestMediaCall(factory, true, false, codec)) { + RTCRtpSender sender = call.getVideoSender(); + sender.setTransform(callerKeys.createEncryptor(sender::generateKeyFrame)); + + call.negotiate(); + + RTCRtpReceiver receiver = call.getReceiver("video"); + receiver.setTransform(calleeKeys.createDecryptor(receiver::requestKeyFrame)); + + VideoTrack track = (VideoTrack) receiver.getTrack(); + VideoTrackSink sink = frame -> { + frame.release(); + decoded.incrementAndGet(); + }; + track.addSink(sink); + + call.awaitConnected(); + call.startMedia(); + + awaitTrue(() -> decoded.get() >= 10, () -> codec + ": too few frames decoded, " + + callerKeys.getStats() + ", " + calleeKeys.getStats()); + + String sent = call.getSentVideoCodec(); + assertTrue(sent == null || sent.equalsIgnoreCase("video/" + codec), sent); + + // Nothing was dropped on the way: every frame authenticated. + assertEquals(0, callerKeys.getStats().getDroppedFrames()); + assertEquals(0, calleeKeys.getStats().getDroppedFrames()); + + track.removeSink(sink); + receiver.dispose(); + } + } + + @Test + void encryptedAudioDecrypts() throws Exception { + try (TestMediaCall call = new TestMediaCall(factory, false, true)) { + call.getAudioSender().setTransform(callerKeys.createEncryptor()); + + call.negotiate(); + + RTCRtpReceiver receiver = call.getReceiver("audio"); + receiver.setTransform(calleeKeys.createDecryptor()); + + call.awaitConnected(); + call.startMedia(); + + awaitTrue(() -> calleeKeys.getStats().getDecryptedFrames() >= 20, + () -> "too few audio frames decrypted: " + calleeKeys.getStats()); + + assertEquals(0, calleeKeys.getStats().getDroppedFrames()); + + receiver.dispose(); + } + } + + @Test + void missingKeyRecovers() throws Exception { + KeyProvider keys = KeyProvider.builder(CALLEE).build(); + AtomicInteger decoded = new AtomicInteger(); + + try (TestMediaCall call = new TestMediaCall(factory, true, false)) { + RTCRtpSender sender = call.getVideoSender(); + sender.setTransform(callerKeys.createEncryptor(sender::generateKeyFrame)); + + call.negotiate(); + + RTCRtpReceiver receiver = call.getReceiver("video"); + receiver.setTransform(keys.createDecryptor(receiver::requestKeyFrame)); + + VideoTrack track = (VideoTrack) receiver.getTrack(); + VideoTrackSink sink = frame -> { + frame.release(); + decoded.incrementAndGet(); + }; + track.addSink(sink); + + call.awaitConnected(); + call.startMedia(); + + // Without the key, every frame is dropped before the decoder. + awaitTrue(() -> keys.getStats().getDroppedFrames(CryptoFailure.UNKNOWN_KEY) >= 30, + () -> "too few frames dropped: " + keys.getStats()); + assertEquals(0, decoded.get()); + assertEquals(0, keys.getStats().getDecryptedFrames()); + + // The key arrives late: the decryptor asks for a key frame, and + // the picture comes back without waiting for the next one. + keys.setDecryptionKey(CALLER, 0, callerKey); + + awaitTrue(() -> decoded.get() >= 5, () -> "no frames decoded after the key arrived: " + + keys.getStats()); + + track.removeSink(sink); + receiver.dispose(); + } + } + + @Test + void rotationKeepsDecoding() throws Exception { + AtomicInteger decoded = new AtomicInteger(); + + try (TestMediaCall call = new TestMediaCall(factory, true, true)) { + RTCRtpSender video = call.getVideoSender(); + video.setTransform(callerKeys.createEncryptor(video::generateKeyFrame)); + call.getAudioSender().setTransform(callerKeys.createEncryptor()); + + call.negotiate(); + + RTCRtpReceiver videoReceiver = call.getReceiver("video"); + RTCRtpReceiver audioReceiver = call.getReceiver("audio"); + videoReceiver.setTransform(calleeKeys.createDecryptor(videoReceiver::requestKeyFrame)); + audioReceiver.setTransform(calleeKeys.createDecryptor()); + + VideoTrack track = (VideoTrack) videoReceiver.getTrack(); + VideoTrackSink sink = frame -> { + frame.release(); + decoded.incrementAndGet(); + }; + track.addSink(sink); + + call.awaitConnected(); + call.startMedia(); + + awaitTrue(() -> decoded.get() >= 10, () -> "too few frames decoded"); + + // The new key reaches the callee first, then the caller uses it. + byte[] next = callerKeys.generateKey(); + calleeKeys.setDecryptionKey(CALLER, 1, next); + callerKeys.setEncryptionKey(1, next); + + int before = decoded.get(); + long decryptedBefore = calleeKeys.getStats().getDecryptedFrames(); + + awaitTrue(() -> decoded.get() >= before + 20 + && calleeKeys.getStats().getDecryptedFrames() >= decryptedBefore + 40, + () -> "decoding stopped after the key changed: " + calleeKeys.getStats()); + + assertEquals(0, calleeKeys.getStats().getDroppedFrames()); + + // The caller removes the old key everywhere: frames keep coming. + assertTrue(calleeKeys.removeDecryptionKey(CALLER, 0)); + int after = decoded.get(); + + awaitTrue(() -> decoded.get() >= after + 10, () -> "decoding stopped without the old key"); + + track.removeSink(sink); + videoReceiver.dispose(); + audioReceiver.dispose(); + } + } + + @Test + void sealedTransformHidesFrames() throws Exception { + try (TestMediaCall call = new TestMediaCall(factory, true, false)) { + RTCRtpSender sender = call.getVideoSender(); + long senderFrames = NativeApi.encodedFramesOf(sender); + long sent = AllocationFault.addCountingObserver(senderFrames); + + call.negotiate(); + + RTCRtpReceiver receiver = call.getReceiver("video"); + long receiverFrames = NativeApi.encodedFramesOf(receiver); + long received = AllocationFault.addCountingObserver(receiverFrames); + + try { + // A transform of its own does not hide anything. + sender.setTransform(frame -> { }); + assertFalse(NativeApi.isSealed(senderFrames)); + + call.awaitConnected(); + call.startMedia(); + + awaitTrue(() -> AllocationFault.countedFrames(sent) >= 10 + && AllocationFault.countedFrames(received) >= 10, () -> "observers saw no frames"); + + // The encryptor and decryptor of the call keep the frames + // from the observers, from the moment they are set. + sender.setTransform(callerKeys.createEncryptor()); + receiver.setTransform(calleeKeys.createDecryptor()); + + assertTrue(NativeApi.isSealed(senderFrames)); + assertTrue(NativeApi.isSealed(receiverFrames)); + + long decryptedBefore = calleeKeys.getStats().getDecryptedFrames(); + awaitTrue(() -> calleeKeys.getStats().getDecryptedFrames() >= decryptedBefore + 2, + () -> "nothing decrypted"); + + long sentSealed = AllocationFault.countedFrames(sent); + long receivedSealed = AllocationFault.countedFrames(received); + + awaitTrue(() -> calleeKeys.getStats().getDecryptedFrames() >= decryptedBefore + 30, + () -> "too few frames decrypted"); + + assertEquals(sentSealed, AllocationFault.countedFrames(sent)); + assertEquals(receivedSealed, AllocationFault.countedFrames(received)); + + // Removing the transform shows the frames again. + sender.setTransform(null); + receiver.setTransform(null); + + assertFalse(NativeApi.isSealed(senderFrames)); + assertFalse(NativeApi.isSealed(receiverFrames)); + + awaitTrue(() -> AllocationFault.countedFrames(sent) > sentSealed + 10 + && AllocationFault.countedFrames(received) > receivedSealed + 10, + () -> "observers saw no frames after the transform was removed"); + } + finally { + AllocationFault.removeCountingObserver(sent); + AllocationFault.removeCountingObserver(received); + NativeApi.releaseEncodedFrames(senderFrames); + NativeApi.releaseEncodedFrames(receiverFrames); + receiver.dispose(); + } + } + } + + @Test + void allowedRecordingShowsFrames() throws Exception { + KeyProvider open = KeyProvider.builder(CALLER).allowPlaintextRecording(true).build(); + open.setEncryptionKey(0, callerKey); + + try (TestMediaCall call = new TestMediaCall(factory, true, false)) { + RTCRtpSender sender = call.getVideoSender(); + sender.setTransform(open.createEncryptor()); + + long frames = NativeApi.encodedFramesOf(sender); + long sent = AllocationFault.addCountingObserver(frames); + + try { + assertFalse(NativeApi.isSealed(frames)); + + call.negotiate(); + call.awaitConnected(); + call.startMedia(); + + awaitTrue(() -> AllocationFault.countedFrames(sent) >= 10, () -> "the observer saw no frames"); + } + finally { + AllocationFault.removeCountingObserver(sent); + NativeApi.releaseEncodedFrames(frames); + } + } + } + + private boolean canSend(String codec) { + RTCRtpCapabilities capabilities = factory.getRtpSenderCapabilities(MediaType.VIDEO); + + return capabilities.getCodecs().stream().anyMatch(c -> codec.equalsIgnoreCase(c.getName())); + } + + private static void awaitTrue(BooleanSupplier condition, java.util.function.Supplier message) + throws InterruptedException { + long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(TIMEOUT_SECONDS); + + while (!condition.getAsBoolean()) { + if (System.nanoTime() > deadline) { + fail(message.get()); + } + + Thread.sleep(20); + } + } + +} diff --git a/webrtc/src/test/java/dev/onvoid/webrtc/client/E2eeTests.java b/webrtc/src/test/java/dev/onvoid/webrtc/client/E2eeTests.java new file mode 100644 index 000000000..7fb7b087c --- /dev/null +++ b/webrtc/src/test/java/dev/onvoid/webrtc/client/E2eeTests.java @@ -0,0 +1,215 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.nio.ByteBuffer; +import java.util.Collections; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.Executors; +import java.util.concurrent.ScheduledExecutorService; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.function.BooleanSupplier; + +import dev.onvoid.webrtc.RTCEncodedFrameTransformer; +import dev.onvoid.webrtc.e2ee.CryptoFailure; +import dev.onvoid.webrtc.e2ee.KeyProvider; +import dev.onvoid.webrtc.media.video.NativeI420Buffer; +import dev.onvoid.webrtc.media.video.VideoFrame; + +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; + +/** + * Tests the end-to-end encryption of the peer options. + */ +class E2eeTests extends ClientTestBase { + + private static final long CALLER = 10; + private static final long CALLEE = 20; + + private ScheduledExecutorService feeder; + + + @BeforeEach + void createFeeder() { + feeder = Executors.newSingleThreadScheduledExecutor(); + } + + @AfterEach + void stopFeeder() throws InterruptedException { + feeder.shutdownNow(); + feeder.awaitTermination(5, TimeUnit.SECONDS); + } + + @Test + void encryptedCallDecodes() throws Exception { + KeyProvider callerKeys = KeyProvider.builder(CALLER).build(); + KeyProvider calleeKeys = KeyProvider.builder(CALLEE).build(); + exchangeKeys(callerKeys, calleeKeys); + + Peer[] peers = videoPair(callerKeys, calleeKeys); + CustomVideo video = rtc.media().customVideo("video"); + AtomicInteger decoded = new AtomicInteger(); + + peers[1].onTrack(track -> track.asVideo().onFrame(frame -> decoded.incrementAndGet())); + peers[0].addTrack(video); + + feedVideo(video); + waitFor(() -> decoded.get() >= 10); + + assertTrue(callerKeys.getStats().getEncryptedFrames() > 0); + assertTrue(calleeKeys.getStats().getDecryptedFrames() >= 10); + assertEquals(0, calleeKeys.getStats().getDroppedFrames()); + } + + @Test + void lateKeyRecovers() throws Exception { + KeyProvider callerKeys = KeyProvider.builder(CALLER).build(); + KeyProvider calleeKeys = KeyProvider.builder(CALLEE).build(); + byte[] key = callerKeys.generateKey(); + callerKeys.setEncryptionKey(3, key); + + Peer[] peers = videoPair(callerKeys, calleeKeys); + CustomVideo video = rtc.media().customVideo("video"); + AtomicInteger decoded = new AtomicInteger(); + + peers[1].onTrack(track -> track.asVideo().onFrame(frame -> decoded.incrementAndGet())); + peers[0].addTrack(video); + + feedVideo(video); + waitFor(() -> calleeKeys.getStats().getDroppedFrames(CryptoFailure.UNKNOWN_KEY) >= 30); + assertEquals(0, decoded.get()); + + // The remote track asks for a key frame through its peer once frames + // decrypt again. + calleeKeys.setDecryptionKey(CALLER, 3, key); + + waitFor(() -> decoded.get() >= 5); + } + + @Test + void e2eeTakesNoOtherTransform() { + KeyProvider keys = KeyProvider.builder(CALLER).build(); + + assertThrows(IllegalStateException.class, () -> PeerOptions.builder() + .negotiation(Negotiation.MANUAL).e2ee(keys).sendTransform(frame -> { }).build()); + assertThrows(IllegalStateException.class, () -> PeerOptions.builder() + .negotiation(Negotiation.MANUAL).e2ee(keys).receiveTransform(frame -> { }).build()); + } + + @Test + void guardKeepsRecordingPolicy() { + PeerImpl peer = (PeerImpl) rtc.createPeer(PeerOptions.builder().negotiation(Negotiation.MANUAL).build()); + KeyProvider sealed = KeyProvider.builder(CALLER).build(); + KeyProvider open = KeyProvider.builder(CALLER).allowPlaintextRecording(true).build(); + + RTCEncodedFrameTransformer plain = frame -> { }; + + assertFalse(peer.guard(sealed.createEncryptor(), "a sender").allowsPlaintextObservers()); + assertFalse(peer.guard(sealed.createDecryptor(), "a track").allowsPlaintextObservers()); + assertTrue(peer.guard(open.createEncryptor(), "a sender").allowsPlaintextObservers()); + assertTrue(peer.guard(plain, "a sender").allowsPlaintextObservers()); + } + + static void exchangeKeys(KeyProvider caller, KeyProvider callee) { + byte[] callerKey = caller.generateKey(); + byte[] calleeKey = callee.generateKey(); + + caller.setEncryptionKey(0, callerKey); + callee.setEncryptionKey(0, calleeKey); + caller.setDecryptionKey(callee.getParticipant(), 0, calleeKey); + callee.setDecryptionKey(caller.getParticipant(), 0, callerKey); + } + + private Peer[] videoPair(KeyProvider callerKeys, KeyProvider calleeKeys) throws Exception { + SignalingPair link = Signaling.loopback(); + + Peer caller = rtc.createPeer(PeerOptions.builder() + .name("caller") + .signaling(link.first()) + .e2ee(callerKeys) + .build()); + Peer callee = rtc.createPeer(PeerOptions.builder() + .name("callee") + .signaling(link.second()) + .polite(true) + .e2ee(calleeKeys) + .build()); + + Peer[] peers = { caller, callee }; + + // A codec the frame format covers on every platform: macOS would + // otherwise prefer H.264, which end-to-end encryption refuses. + for (Peer peer : peers) { + await(((PeerImpl) peer).manual.preferCodecs(Collections.singletonMap( + MediaKind.VIDEO, Collections.singletonList("VP8")))); + } + + return peers; + } + + private void feedVideo(CustomVideo video) { + AtomicInteger shade = new AtomicInteger(); + + feeder.scheduleAtFixedRate(() -> { + NativeI420Buffer buffer = NativeI420Buffer.allocate(160, 120); + ByteBuffer y = buffer.getDataY(); + int offset = shade.addAndGet(3); + + for (int i = 0; i < y.capacity(); i++) { + y.put(i, (byte) (i + offset)); + } + + fill(buffer.getDataU()); + fill(buffer.getDataV()); + + VideoFrame frame = new VideoFrame(buffer, System.nanoTime()); + + try { + video.push(frame); + } + finally { + frame.release(); + } + }, 0, 33, TimeUnit.MILLISECONDS); + } + + private static void fill(ByteBuffer plane) { + while (plane.hasRemaining()) { + plane.put((byte) 128); + } + } + + /** Waits for frames to arrive, which only time brings. */ + private static void waitFor(BooleanSupplier condition) throws InterruptedException { + long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(TIMEOUT_SECONDS); + + while (!condition.getAsBoolean()) { + assertTrue(System.nanoTime() < deadline, "Timed out"); + + Thread.sleep(20); + } + } + +} diff --git a/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/BrowserInteropTests.java b/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/BrowserInteropTests.java new file mode 100644 index 000000000..1459bdb6f --- /dev/null +++ b/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/BrowserInteropTests.java @@ -0,0 +1,198 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.e2ee; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.Assumptions.assumeTrue; + +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; +import java.util.Random; +import java.util.concurrent.TimeUnit; + +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +/** + * Checks the browser implementation of the frame format, the JavaScript + * module the guide publishes ({@code docs/public/e2ee}), against this one: in + * Node.js, which has the same WebCrypto a browser has. Frames encrypted on + * either side must decrypt on the other, in every cipher suite and codec + * layout. Skipped where Node.js is not installed. + */ +class BrowserInteropTests { + + private static final Path MODULE = Paths.get("..", "docs", "public", "e2ee", "webrtc-java-sframe.js"); + + private static final long JAVA = 7; + private static final long JS = 9; + + /** Codec, key frame, of every layout the format defines. */ + private static final String[][] FRAMES = { + { "video/VP8", "1" }, { "video/VP8", "0" }, + { "video/VP9", "1" }, { "video/VP9", "0" }, + { "video/AV1", "1" }, { "video/AV1", "0" }, + { "audio/opus", "0" }, { "audio/PCMU", "0" }, + }; + + @TempDir + Path dir; + + + @Test + void browserModuleMatchesJava() throws Exception { + assumeTrue(Files.isRegularFile(MODULE), "The browser module is not there"); + assumeTrue(nodeAvailable(), "Node.js is not installed"); + + Random random = new Random(7); + + for (CipherSuite suite : CipherSuite.values()) { + KeyProvider keys = KeyProvider.builder(JAVA).cipherSuite(suite).build(); + byte[] javaKey = keys.generateKey(); + byte[] jsKey = keys.generateKey(); + + keys.setEncryptionKey(0, javaKey); + keys.setDecryptionKey(JS, 0, jsKey); + + FrameCryptor encryptor = (FrameCryptor) keys.createEncryptor(); + FrameCryptor decryptor = (FrameCryptor) keys.createDecryptor(); + + List plain = new ArrayList<>(); + StringBuilder input = new StringBuilder(); + input.append("suite ").append(suite.getId()).append('\n'); + input.append("javaKey ").append(JAVA).append(' ').append(hex(javaKey)).append('\n'); + input.append("jsKey ").append(JS).append(' ').append(hex(jsKey)).append('\n'); + + for (int i = 0; i < FRAMES.length; i++) { + byte[] frame = new byte[20 + random.nextInt(2000)]; + random.nextBytes(frame); + plain.add(frame); + + String mimeType = FRAMES[i][0]; + boolean keyFrame = FRAMES[i][1].equals("1"); + byte[] sealed = process(encryptor, 1000 + i, mimeType, keyFrame, frame); + + input.append("frame ").append(mimeType).append(' ').append(FRAMES[i][1]).append(' ') + .append(1000 + i).append(' ').append(hex(frame)).append(' ').append(hex(sealed)).append('\n'); + } + + List output = runNode(input.toString()); + + 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)); + + for (int i = 0; i < FRAMES.length; i++) { + String label = suite + " " + FRAMES[i][0] + " " + FRAMES[i][1]; + + assertTrue(output.contains("decrypt " + i + " ok"), "JavaScript decrypts " + label + ": " + output); + + String sealedLine = find(output, "sealed " + i + " "); + byte[] fromJs = unhex(sealedLine.substring(("sealed " + i + " ").length())); + + // Another stream than Java's own, of the JavaScript participant. + byte[] decrypted = process(decryptor, 2000 + i, FRAMES[i][0], FRAMES[i][1].equals("1"), fromJs); + + assertArrayEquals(plain.get(i), decrypted, "Java decrypts " + label); + } + + assertEquals(0, keys.getStats().getDroppedFrames()); + } + } + + private List runNode(String input) throws Exception { + Path frames = dir.resolve("frames.txt"); + Files.write(frames, input.getBytes(StandardCharsets.US_ASCII)); + + Path script = resource("sframe-interop.mjs"); + Path vectors = resource("rfc9605-test-vectors.txt"); + Path log = dir.resolve("node.log"); + + Process process = new ProcessBuilder("node", script.toString(), MODULE.toAbsolutePath().toString(), + vectors.toString(), frames.toString()) + .redirectErrorStream(true) + .redirectOutput(log.toFile()) + .start(); + + assertTrue(process.waitFor(60, TimeUnit.SECONDS), "Node.js did not finish"); + + List output = Files.readAllLines(log, StandardCharsets.UTF_8); + + assertEquals(0, process.exitValue(), () -> String.join("\n", output)); + assertTrue(output.contains("done"), () -> String.join("\n", output)); + + return output; + } + + private static Path resource(String name) throws Exception { + return Paths.get(BrowserInteropTests.class.getResource(name).toURI()); + } + + private static boolean nodeAvailable() { + try { + Process process = new ProcessBuilder("node", "--version").redirectErrorStream(true).start(); + process.getInputStream().readAllBytes(); + + return process.waitFor(10, TimeUnit.SECONDS) && process.exitValue() == 0; + } + catch (IOException e) { + return false; + } + catch (InterruptedException e) { + Thread.currentThread().interrupt(); + return false; + } + } + + private static String find(List lines, String prefix) { + return lines.stream().filter(l -> l.startsWith(prefix)).findFirst() + .orElseThrow(() -> new AssertionError("No line " + prefix + " in " + lines)); + } + + private static byte[] process(FrameCryptor cryptor, long ssrc, String mimeType, boolean keyFrame, byte[] frame) { + byte[] out = new byte[frame.length + FrameFormat.MAX_OVERHEAD]; + int length = cryptor.process(ssrc, mimeType, mimeType.startsWith("video/"), keyFrame, frame.clone(), + frame.length, out); + + assertTrue(length >= 0, mimeType); + + return Arrays.copyOf(out, length); + } + + private static String hex(byte[] bytes) { + StringBuilder hex = new StringBuilder(bytes.length * 2); + + for (byte b : bytes) { + hex.append(String.format("%02x", b)); + } + + return hex.toString(); + } + + private static byte[] unhex(String hex) { + return SFrameTests.hex(hex); + } + +} diff --git a/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/FrameCryptorTests.java b/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/FrameCryptorTests.java new file mode 100644 index 000000000..d1f1fc9af --- /dev/null +++ b/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/FrameCryptorTests.java @@ -0,0 +1,540 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.e2ee; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.time.Duration; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; +import java.util.Random; +import java.util.concurrent.atomic.AtomicInteger; + +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; + +/** + * Tests the encryptor and decryptor on frames given as bytes, the way a + * sender's and a receiver's transform see them. + */ +class FrameCryptorTests { + + private static final long ALICE = 1; + private static final long BOB = 2; + + private static final long SSRC = 1111; + + private final List aliceEvents = new ArrayList<>(); + private final List bobEvents = new ArrayList<>(); + + private final Random random = new Random(42); + + private KeyProvider alice; + private KeyProvider bob; + + private byte[] aliceKey; + + + @BeforeEach + void createKeys() { + alice = KeyProvider.builder(ALICE).listener(aliceEvents::add).build(); + bob = KeyProvider.builder(BOB).listener(bobEvents::add).build(); + + aliceKey = alice.generateKey(); + alice.setEncryptionKey(0, aliceKey); + bob.setDecryptionKey(ALICE, 0, aliceKey); + } + + @Test + void everyCodecRoundTrips() { + FrameCryptor encryptor = encryptor(alice); + FrameCryptor decryptor = decryptor(bob); + + String[][] codecs = { + { "video/VP8", "key", "10" }, { "video/VP8", "delta", "3" }, + { "video/VP9", "key", "0" }, { "video/VP9", "delta", "0" }, + { "audio/opus", "audio", "1" }, { "audio/PCMU", "audio", "0" }, + { "audio/red", "audio", "0" } + }; + + long ssrc = SSRC; + + for (String[] codec : codecs) { + boolean video = !codec[1].equals("audio"); + boolean key = codec[1].equals("key"); + int clear = Integer.parseInt(codec[2]); + byte[] frame = frame(500); + + byte[] sealed = process(encryptor, ssrc, codec[0], video, key, frame); + + assertNotNull(sealed, codec[0]); + assertArrayEquals(Arrays.copyOf(frame, clear), Arrays.copyOf(sealed, clear), + codec[0] + " must leave its header in the clear"); + assertFalse(Arrays.equals(Arrays.copyOfRange(frame, clear, clear + 16), + Arrays.copyOfRange(sealed, clear, clear + 16)), codec[0]); + + assertArrayEquals(frame, process(decryptor, ssrc, codec[0], video, key, sealed), codec[0]); + + ssrc++; + } + + assertTrue(bobEvents.isEmpty(), bobEvents.toString()); + } + + @Test + void av1TravelsAsOneObu() { + FrameCryptor encryptor = encryptor(alice); + FrameCryptor decryptor = decryptor(bob); + + for (int size : new int[] { 10, 200, 20000 }) { + byte[] frame = frame(size); + byte[] sealed = process(encryptor, SSRC, "video/AV1", true, size == 10, frame); + + // OBU_SEQUENCE_HEADER for a key frame, so that the packetizer + // marks it as one, OBU_FRAME otherwise; without extension and + // size field. + assertEquals(size == 10 ? 0x08 : 0x30, sealed[0] & 0xFF); + + // What the depacketizer hands over: the size bit set and a + // leb128 size inserted. + byte[] payload = Arrays.copyOfRange(sealed, 1, sealed.length); + byte[] received = concat(new byte[] { (byte) (sealed[0] | 0x02) }, leb128(payload.length), payload); + + assertArrayEquals(frame, process(decryptor, SSRC, "video/AV1", true, size == 10, received)); + // And without the size field, as sent. A frame of its own, since + // the first one is a replay now. + byte[] next = frame(size); + assertArrayEquals(next, process(decryptor, SSRC, "video/AV1", true, false, + process(encryptor, SSRC, "video/AV1", true, false, next))); + } + + // A size field that does not match is no frame of the format. + byte[] sealed = process(encryptor, SSRC, "video/AV1", true, false, frame(100)); + byte[] payload = Arrays.copyOfRange(sealed, 1, sealed.length); + byte[] wrong = concat(new byte[] { 0x32 }, leb128(payload.length + 1), payload); + + assertNull(process(decryptor, SSRC + 2, "video/AV1", true, false, wrong)); + assertEquals(CryptoFailure.MALFORMED, last(bobEvents).getFailure()); + + // The wrapper is authenticated: a delta frame cannot pass for a key + // frame. + byte[] delta = process(encryptor, SSRC, "video/AV1", true, false, frame(100)); + delta[0] = 0x08; + + assertNull(process(decryptor, SSRC + 3, "video/AV1", true, true, delta)); + assertEquals(CryptoFailure.AUTHENTICATION, last(bobEvents).getFailure()); + } + + @Test + void everySuiteRoundTrips() { + for (CipherSuite suite : CipherSuite.values()) { + KeyProvider sender = KeyProvider.builder(ALICE).cipherSuite(suite).build(); + KeyProvider receiver = KeyProvider.builder(BOB).cipherSuite(suite).build(); + byte[] key = sender.generateKey(); + + assertEquals(suite.getHashLength(), key.length); + + sender.setEncryptionKey(7, key); + receiver.setDecryptionKey(ALICE, 7, key); + + 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()); + assertArrayEquals(frame, process(decryptor(receiver), SSRC, "video/VP8", true, true, sealed), + suite.name()); + } + } + + @Test + void h264IsRefused() { + FrameCryptor encryptor = encryptor(alice); + + assertNull(process(encryptor, SSRC, "video/H264", true, true, frame(100))); + assertNull(process(encryptor, SSRC, "video/H264", true, false, frame(100))); + assertNull(process(decryptor(bob), SSRC, "video/H265", true, false, frame(100))); + + // Reported once per stream, counted for every frame. + assertEquals(1, aliceEvents.size()); + assertEquals(CryptoFailure.UNSUPPORTED_CODEC, aliceEvents.get(0).getFailure()); + assertTrue(aliceEvents.get(0).isOutgoing()); + assertEquals(2, alice.getStats().getDroppedFrames(CryptoFailure.UNSUPPORTED_CODEC)); + } + + @Test + void missingKeyDropsInsteadOfSending() { + KeyProvider keys = KeyProvider.builder(ALICE).listener(aliceEvents::add).build(); + AtomicInteger keyFrames = new AtomicInteger(); + FrameCryptor encryptor = (FrameCryptor) keys.createEncryptor(keyFrames::incrementAndGet); + + for (int i = 0; i < 5; i++) { + assertNull(process(encryptor, SSRC, "video/VP8", true, i == 0, frame(100))); + } + + assertEquals(1, aliceEvents.size()); + assertEquals(CryptoFailure.MISSING_KEY, aliceEvents.get(0).getFailure()); + assertEquals(-1, aliceEvents.get(0).getGeneration()); + assertEquals(ALICE, aliceEvents.get(0).getParticipant()); + + keys.setEncryptionKey(0, aliceKey); + + // The first frame that goes out again asks for a key frame, since the + // receivers missed the ones before. + assertNotNull(process(encryptor, SSRC, "video/VP8", true, false, frame(100))); + assertEquals(1, keyFrames.get()); + + keys.removeEncryptionKey(); + assertNull(process(encryptor, SSRC, "video/VP8", true, false, frame(100))); + assertEquals(2, aliceEvents.size()); + } + + @Test + void unknownKeyDropsUntilItArrives() { + KeyProvider carol = KeyProvider.builder(3).listener(bobEvents::add).build(); + AtomicInteger keyFrames = new AtomicInteger(); + FrameCryptor encryptor = encryptor(alice); + FrameCryptor decryptor = (FrameCryptor) carol.createDecryptor(keyFrames::incrementAndGet); + + byte[][] frames = new byte[4][]; + + for (int i = 0; i < frames.length; i++) { + frames[i] = process(encryptor, SSRC, "video/VP8", true, i == 0, frame(300)); + } + + assertNull(process(decryptor, SSRC, "video/VP8", true, true, frames[0])); + assertNull(process(decryptor, SSRC, "video/VP8", true, false, frames[1])); + + assertEquals(1, bobEvents.size()); + assertEquals(CryptoFailure.UNKNOWN_KEY, bobEvents.get(0).getFailure()); + assertEquals(ALICE, bobEvents.get(0).getParticipant()); + assertEquals(0, bobEvents.get(0).getGeneration()); + assertFalse(bobEvents.get(0).isOutgoing()); + + carol.setDecryptionKey(ALICE, 0, aliceKey); + + // Decrypts again, and asks for a key frame for what was lost. + assertNotNull(process(decryptor, SSRC, "video/VP8", true, false, frames[2])); + assertEquals(1, keyFrames.get()); + + // Not again right away, however many frames follow. + assertNotNull(process(decryptor, SSRC, "video/VP8", true, false, frames[3])); + assertEquals(1, keyFrames.get()); + + CryptoStats stats = carol.getStats(); + assertEquals(2, stats.getDecryptedFrames()); + assertEquals(2, stats.getDroppedFrames(CryptoFailure.UNKNOWN_KEY)); + } + + @Test + void replaysAreDropped() { + FrameCryptor encryptor = encryptor(alice); + FrameCryptor decryptor = decryptor(bob); + + byte[][] frames = new byte[200][]; + + for (int i = 0; i < frames.length; i++) { + frames[i] = process(encryptor, SSRC, "audio/opus", false, false, frame(80)); + } + + assertNotNull(process(decryptor, SSRC, "audio/opus", false, false, frames[0])); + assertNull(process(decryptor, SSRC, "audio/opus", false, false, frames[0])); + assertEquals(CryptoFailure.REPLAY, last(bobEvents).getFailure()); + + // Late, but within the window, and not seen before. + assertNotNull(process(decryptor, SSRC, "audio/opus", false, false, frames[150])); + assertNotNull(process(decryptor, SSRC, "audio/opus", false, false, frames[100])); + assertNull(process(decryptor, SSRC, "audio/opus", false, false, frames[100])); + + // Further back than the window of 128 frames. + assertNull(process(decryptor, SSRC, "audio/opus", false, false, frames[10])); + + assertEquals(3, bob.getStats().getDroppedFrames(CryptoFailure.REPLAY)); + + // The same key set again keeps what was seen. + bob.setDecryptionKey(ALICE, 0, aliceKey); + assertNull(process(decryptor, SSRC, "audio/opus", false, false, frames[150])); + } + + @Test + void replayWindowCanBeTurnedOff() { + KeyProvider keys = KeyProvider.builder(BOB).replayWindow(0).build(); + keys.setDecryptionKey(ALICE, 0, aliceKey); + + byte[] sealed = process(encryptor(alice), SSRC, "audio/opus", false, false, frame(80)); + FrameCryptor decryptor = decryptor(keys); + + assertNotNull(process(decryptor, SSRC, "audio/opus", false, false, sealed)); + assertNotNull(process(decryptor, SSRC, "audio/opus", false, false, sealed)); + } + + @Test + void tamperedFramesAreDropped() { + FrameCryptor encryptor = encryptor(alice); + FrameCryptor decryptor = decryptor(bob); + + byte[] frame = frame(300); + byte[] sealed = process(encryptor, SSRC, "video/VP8", true, false, frame); + + // The clear header is authenticated too. + for (int i : new int[] { 0, 2, 20, sealed.length - 1 }) { + byte[] tampered = sealed.clone(); + tampered[i] ^= 0x04; + + assertNull(process(decryptor, SSRC, "video/VP8", true, false, tampered), "byte " + i); + } + + // Still decrypts afterwards: forged frames do not move the window. + assertArrayEquals(frame, process(decryptor, SSRC, "video/VP8", true, false, sealed)); + assertTrue(bob.getStats().getDroppedFrames(CryptoFailure.AUTHENTICATION) >= 3); + } + + @Test + void unencryptedFramesAreDropped() { + FrameCryptor decryptor = decryptor(bob); + + // A clear frame reads as a header of some key ID, or as none. + assertNull(process(decryptor, SSRC, "audio/opus", false, false, frame(100))); + assertNull(process(decryptor, SSRC, "video/VP8", true, false, new byte[2])); + assertNull(process(decryptor, SSRC, "video/AV1", true, false, frame(50))); + + assertEquals(3, bob.getStats().getDroppedFrames()); + assertEquals(0, bob.getStats().getDecryptedFrames()); + } + + @Test + void streamsHaveOwnKeyIds() { + FrameCryptor encryptor = encryptor(alice); + FrameCryptor other = encryptor(alice); + + long[] audio = header(process(encryptor, SSRC, "audio/opus", false, false, frame(50)), 1); + long[] video = header(process(encryptor, SSRC + 1, "video/VP9", true, true, frame(50)), 0); + long[] second = header(process(other, SSRC + 2, "video/VP9", true, true, frame(50)), 0); + + // One participant, one generation, three contexts. + for (long[] header : new long[][] { audio, video, second }) { + assertEquals(ALICE, FrameFormat.participant(header[0])); + assertEquals(0, FrameFormat.generation(header[0])); + assertEquals(0, header[1]); + } + + assertNotEquals(audio[0], video[0]); + assertNotEquals(video[0], second[0]); + assertNotEquals(audio[0], second[0]); + + // Each counts its own frames. + assertEquals(1, header(process(encryptor, SSRC, "audio/opus", false, false, frame(50)), 1)[1]); + assertEquals(1, header(process(encryptor, SSRC + 1, "video/VP9", true, false, frame(50)), 0)[1]); + } + + @Test + void rotationSwitchesKeys() { + AtomicInteger keyFrames = new AtomicInteger(); + FrameCryptor encryptor = (FrameCryptor) alice.createEncryptor(keyFrames::incrementAndGet); + FrameCryptor decryptor = decryptor(bob); + + byte[] old = process(encryptor, SSRC, "video/VP8", true, true, frame(100)); + byte[] oldLate = process(encryptor, SSRC, "video/VP8", true, false, frame(100)); + assertEquals(0, keyFrames.get()); + + byte[] newKey = alice.generateKey(); + bob.setDecryptionKey(ALICE, 1, newKey); + alice.setEncryptionKey(1, newKey); + + assertEquals(1, alice.getEncryptionGeneration()); + + byte[] frame = frame(100); + byte[] rotated = process(encryptor, SSRC, "video/VP8", true, false, frame); + + // The first frame with the new key asks the encoder for a key frame. + assertEquals(1, keyFrames.get()); + assertEquals(1, FrameFormat.generation(header(rotated, 3)[0])); + // The counter goes on rather than starting over. + assertEquals(2, header(rotated, 3)[1]); + + assertNotNull(process(decryptor, SSRC, "video/VP8", true, true, old)); + assertArrayEquals(frame, process(decryptor, SSRC, "video/VP8", true, false, rotated)); + + // A frame of the old generation on its way still decrypts. + assertNotNull(process(decryptor, SSRC, "video/VP8", true, false, oldLate)); + } + + @Test + void oldGenerationsRetire() throws InterruptedException { + KeyProvider receiver = KeyProvider.builder(BOB).keyRetention(Duration.ZERO).listener(bobEvents::add).build(); + FrameCryptor encryptor = encryptor(alice); + FrameCryptor decryptor = decryptor(receiver); + + byte[] newKey = alice.generateKey(); + receiver.setDecryptionKey(ALICE, 0, aliceKey); + receiver.setDecryptionKey(ALICE, 1, newKey); + + byte[] old = process(encryptor, SSRC, "audio/opus", false, false, frame(50)); + byte[] oldLate = process(encryptor, SSRC, "audio/opus", false, false, frame(50)); + + assertNotNull(process(decryptor, SSRC, "audio/opus", false, false, old)); + + alice.setEncryptionKey(1, newKey); + assertNotNull(process(decryptor, SSRC, "audio/opus", false, false, + process(encryptor, SSRC, "audio/opus", false, false, frame(50)))); + + Thread.sleep(2); + + // Generation 0 retired once generation 1 decrypted. + assertNull(process(decryptor, SSRC, "audio/opus", false, false, oldLate)); + assertEquals(CryptoFailure.UNKNOWN_KEY, last(bobEvents).getFailure()); + assertEquals(0, last(bobEvents).getGeneration()); + } + + @Test + void generationsWrapAround() { + assertTrue(KeyProvider.isNewer(1, 0)); + assertTrue(KeyProvider.isNewer(0, 255)); + assertTrue(KeyProvider.isNewer(100, 0)); + assertFalse(KeyProvider.isNewer(0, 1)); + assertFalse(KeyProvider.isNewer(5, 5)); + assertFalse(KeyProvider.isNewer(200, 0)); + } + + @Test + void keyRolesAreSeparate() { + assertThrows(IllegalArgumentException.class, () -> alice.setDecryptionKey(ALICE, 0, aliceKey)); + assertThrows(IllegalArgumentException.class, () -> alice.setEncryptionKey(256, aliceKey)); + assertThrows(IllegalArgumentException.class, () -> alice.setEncryptionKey(0, new byte[15])); + assertThrows(IllegalArgumentException.class, () -> KeyProvider.builder(-1)); + assertThrows(IllegalArgumentException.class, () -> KeyProvider.builder(1L << 32)); + + // Neither encrypts with the other's key, nor decrypts its own frames. + byte[] sealed = process(encryptor(alice), SSRC, "audio/opus", false, false, frame(50)); + assertNull(process(decryptor(alice), SSRC, "audio/opus", false, false, sealed)); + + assertTrue(bob.removeParticipant(ALICE)); + assertNull(process(decryptor(bob), SSRC, "audio/opus", false, false, sealed)); + } + + @Test + void recordingPolicyFollowsBuilder() { + assertFalse(alice.createEncryptor().allowsPlaintextObservers()); + assertFalse(alice.createDecryptor().allowsPlaintextObservers()); + + KeyProvider open = KeyProvider.builder(ALICE).allowPlaintextRecording(true).build(); + + assertTrue(open.createEncryptor().allowsPlaintextObservers()); + assertTrue(open.createDecryptor().allowsPlaintextObservers()); + } + + @Test + void listenerFailureDoesNotStopFrames() { + KeyProvider keys = KeyProvider.builder(ALICE).listener(event -> { + throw new IllegalStateException("listener"); + }).build(); + + List uncaught = new ArrayList<>(); + Thread thread = Thread.currentThread(); + Thread.UncaughtExceptionHandler previous = thread.getUncaughtExceptionHandler(); + thread.setUncaughtExceptionHandler((t, e) -> uncaught.add(e)); + + try { + assertNull(process(encryptor(keys), SSRC, "audio/opus", false, false, frame(50))); + } + finally { + thread.setUncaughtExceptionHandler(previous); + } + + assertEquals(1, uncaught.size()); + assertEquals(1, keys.getStats().getDroppedFrames(CryptoFailure.MISSING_KEY)); + } + + private static FrameCryptor encryptor(KeyProvider keys) { + return (FrameCryptor) keys.createEncryptor(); + } + + private static FrameCryptor decryptor(KeyProvider keys) { + return (FrameCryptor) keys.createDecryptor(); + } + + private static byte[] process(FrameCryptor cryptor, long ssrc, String mimeType, boolean video, + boolean keyFrame, byte[] frame) { + byte[] out = new byte[frame.length + FrameFormat.MAX_OVERHEAD]; + int length = cryptor.process(ssrc, mimeType, video, keyFrame, frame.clone(), frame.length, out); + + return length < 0 ? null : Arrays.copyOf(out, length); + } + + /** Parses the SFrame header after the given clear bytes. */ + private static long[] header(byte[] sealed, int clear) { + long[] header = new long[2]; + + assertTrue(SFrame.parseHeader(sealed, clear, sealed.length - clear, header) > 0); + + return header; + } + + private byte[] frame(int size) { + byte[] frame = new byte[size]; + random.nextBytes(frame); + + return frame; + } + + private static CryptoEvent last(List events) { + assertFalse(events.isEmpty()); + + return events.get(events.size() - 1); + } + + private static byte[] leb128(int value) { + byte[] bytes = new byte[5]; + int n = 0; + + do { + int b = value & 0x7F; + value >>>= 7; + bytes[n++] = (byte) (value != 0 ? b | 0x80 : b); + } + while (value != 0); + + return Arrays.copyOf(bytes, n); + } + + private static byte[] concat(byte[]... parts) { + int size = 0; + + for (byte[] part : parts) { + size += part.length; + } + + byte[] all = new byte[size]; + int offset = 0; + + for (byte[] part : parts) { + System.arraycopy(part, 0, all, offset, part.length); + offset += part.length; + } + + return all; + } + +} diff --git a/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/SFrameTests.java b/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/SFrameTests.java new file mode 100644 index 000000000..edb7feb99 --- /dev/null +++ b/webrtc/src/test/java/dev/onvoid/webrtc/e2ee/SFrameTests.java @@ -0,0 +1,221 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.e2ee; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; + +import java.io.BufferedReader; +import java.io.IOException; +import java.io.InputStream; +import java.io.InputStreamReader; +import java.nio.charset.StandardCharsets; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.HashMap; +import java.util.List; +import java.util.Map; + +import org.junit.jupiter.api.Test; + +/** + * Checks the SFrame operations against the test vectors of RFC 9605, + * Appendix C. + */ +class SFrameTests { + + @Test + void headersMatchVectors() throws IOException { + List> vectors = vectors("header"); + + assertEquals(289, vectors.size()); + + for (Map vector : vectors) { + long kid = Long.parseUnsignedLong(vector.get("kid"), 16); + long ctr = Long.parseUnsignedLong(vector.get("ctr"), 16); + byte[] expected = hex(vector.get("header")); + + byte[] header = new byte[SFrame.MAX_HEADER_LENGTH]; + int length = SFrame.writeHeader(kid, ctr, header, 0); + + assertArrayEquals(expected, Arrays.copyOf(header, length), vector.toString()); + assertEquals(length, SFrame.headerLength(kid, ctr)); + + long[] parsed = new long[2]; + assertEquals(expected.length, SFrame.parseHeader(expected, 0, expected.length, parsed)); + assertEquals(kid, parsed[0]); + assertEquals(ctr, parsed[1]); + } + } + + @Test + void nonMinimalHeadersRejected() { + long[] parsed = new long[2]; + + // A KID of 5 in an extended field, and a CTR of 0x0001 in two bytes. + assertEquals(-1, SFrame.parseHeader(new byte[] { (byte) 0x80, 0x05 }, 0, 2, parsed)); + assertEquals(-1, SFrame.parseHeader(new byte[] { 0x09, 0x00, 0x01 }, 0, 3, parsed)); + // Cut short. + assertEquals(-1, SFrame.parseHeader(new byte[] { 0x09, 0x01 }, 0, 2, parsed)); + assertEquals(-1, SFrame.parseHeader(new byte[0], 0, 0, parsed)); + } + + @Test + void aeadMatchesVectors() throws IOException { + List> vectors = vectors("aead"); + + assertEquals(3, vectors.size()); + + for (Map vector : vectors) { + CipherSuite suite = CipherSuite.of(Integer.parseInt(vector.get("cipher_suite"), 16)); + byte[] nonce = hex(vector.get("nonce")); + byte[] aad = hex(vector.get("aad")); + byte[] pt = hex(vector.get("pt")); + byte[] ct = hex(vector.get("ct")); + + SFrame sframe = SFrame.of(suite, 0, hex(vector.get("key")), nonce); + + byte[] sealed = new byte[pt.length + suite.getTagLength()]; + int length = sframe.seal(nonce, aad, 0, aad.length, new byte[0], 0, 0, pt, 0, pt.length, sealed, 0); + + assertEquals(ct.length, length); + assertArrayEquals(ct, sealed, suite.name()); + + byte[] opened = new byte[ct.length]; + length = sframe.open(nonce, aad, 0, aad.length, new byte[0], 0, 0, ct, 0, ct.length, opened, 0); + + assertArrayEquals(pt, Arrays.copyOf(opened, length), suite.name()); + } + } + + @Test + void sframeMatchesVectors() throws IOException { + List> vectors = vectors("sframe"); + + assertEquals(CipherSuite.values().length, vectors.size()); + + for (Map vector : vectors) { + CipherSuite suite = CipherSuite.of(Integer.parseInt(vector.get("cipher_suite"), 16)); + long kid = Long.parseUnsignedLong(vector.get("kid"), 16); + long ctr = Long.parseUnsignedLong(vector.get("ctr"), 16); + byte[] baseKey = hex(vector.get("base_key")); + byte[] metadata = hex(vector.get("metadata")); + byte[] pt = hex(vector.get("pt")); + byte[] ct = hex(vector.get("ct")); + + assertArrayEquals(hex(vector.get("sframe_key_label")), SFrame.keyLabel(kid, suite)); + assertArrayEquals(hex(vector.get("sframe_salt_label")), SFrame.saltLabel(kid, suite)); + assertArrayEquals(hex(vector.get("sframe_secret")), SFrame.hkdfExtract(suite, baseKey)); + + SFrame sframe = SFrame.derive(suite, kid, baseKey); + + assertArrayEquals(hex(vector.get("nonce")), sframe.nonce(ctr), suite.name()); + + byte[] out = new byte[SFrame.MAX_HEADER_LENGTH + pt.length + suite.getTagLength()]; + int length = sframe.encrypt(ctr, metadata, 0, metadata.length, pt, 0, pt.length, out, 0); + + assertArrayEquals(ct, Arrays.copyOf(out, length), suite.name()); + + long[] header = new long[2]; + int headerLength = SFrame.parseHeader(ct, 0, ct.length, header); + + assertEquals(kid, header[0]); + assertEquals(ctr, header[1]); + + byte[] opened = new byte[ct.length]; + length = sframe.decrypt(ctr, ct, 0, headerLength, metadata, 0, metadata.length, + ct, headerLength, ct.length - headerLength, opened, 0); + + assertArrayEquals(pt, Arrays.copyOf(opened, length), suite.name()); + } + } + + @Test + void tamperingFailsAuthentication() throws IOException { + for (Map vector : vectors("sframe")) { + CipherSuite suite = CipherSuite.of(Integer.parseInt(vector.get("cipher_suite"), 16)); + long kid = Long.parseUnsignedLong(vector.get("kid"), 16); + long ctr = Long.parseUnsignedLong(vector.get("ctr"), 16); + byte[] metadata = hex(vector.get("metadata")); + byte[] ct = hex(vector.get("ct")); + + SFrame sframe = SFrame.derive(suite, kid, hex(vector.get("base_key"))); + int headerLength = SFrame.headerLength(kid, ctr); + byte[] out = new byte[ct.length]; + + for (int i = 0; i < ct.length; i++) { + byte[] tampered = ct.clone(); + tampered[i] ^= 0x01; + + int length = sframe.decrypt(ctr, tampered, 0, headerLength, metadata, 0, metadata.length, + tampered, headerLength, tampered.length - headerLength, out, 0); + + assertEquals(-1, length, suite.name() + " accepted a change of byte " + i); + } + + byte[] otherMetadata = metadata.clone(); + otherMetadata[0] ^= 0x01; + + assertEquals(-1, sframe.decrypt(ctr, ct, 0, headerLength, otherMetadata, 0, otherMetadata.length, + ct, headerLength, ct.length - headerLength, out, 0)); + + // A shorter ciphertext than a tag never authenticates. + assertFalse(sframe.decrypt(ctr, ct, 0, headerLength, metadata, 0, metadata.length, + ct, headerLength, suite.getTagLength() - 1, out, 0) >= 0); + } + } + + static List> vectors(String section) throws IOException { + List> vectors = new ArrayList<>(); + + try (InputStream stream = SFrameTests.class.getResourceAsStream("rfc9605-test-vectors.txt"); + BufferedReader reader = new BufferedReader(new InputStreamReader(stream, StandardCharsets.US_ASCII))) { + String line; + + while ((line = reader.readLine()) != null) { + if (line.startsWith("#") || line.isBlank()) { + continue; + } + + Map vector = new HashMap<>(); + + for (String field : line.trim().split(" ")) { + int equals = field.indexOf('='); + vector.put(field.substring(0, equals), field.substring(equals + 1)); + } + + if (section.equals(vector.get("section"))) { + vectors.add(vector); + } + } + } + + return vectors; + } + + static byte[] hex(String hex) { + byte[] bytes = new byte[hex.length() / 2]; + + for (int i = 0; i < bytes.length; i++) { + bytes[i] = (byte) Integer.parseInt(hex.substring(2 * i, 2 * i + 2), 16); + } + + return bytes; + } + +} diff --git a/webrtc/src/test/java/dev/onvoid/webrtc/internal/AllocationFault.java b/webrtc/src/test/java/dev/onvoid/webrtc/internal/AllocationFault.java index 3664f9388..2b78d38ae 100644 --- a/webrtc/src/test/java/dev/onvoid/webrtc/internal/AllocationFault.java +++ b/webrtc/src/test/java/dev/onvoid/webrtc/internal/AllocationFault.java @@ -70,6 +70,29 @@ private AllocationFault() { */ static native int encodedObservers(long frames); + /** + * Attaches an observer that counts the frames it is shown. + * + * @param frames A handle from {@link NativeApi#encodedFramesOf}. + * + * @return The counter, or {@code 0} if it could not be attached. + */ + public static native long addCountingObserver(long frames); + + /** + * @param counter The counter from {@link #addCountingObserver(long)}. + * + * @return The frames the observer was shown so far. + */ + public static native long countedFrames(long counter); + + /** + * Detaches and frees a counter. + * + * @param counter The counter from {@link #addCountingObserver(long)}. + */ + public static native void removeCountingObserver(long counter); + /** * Forgets a fault that has not fired. */ diff --git a/webrtc/src/test/resources/dev/onvoid/webrtc/e2ee/rfc9605-test-vectors.txt b/webrtc/src/test/resources/dev/onvoid/webrtc/e2ee/rfc9605-test-vectors.txt new file mode 100644 index 000000000..7969b560e --- /dev/null +++ b/webrtc/src/test/resources/dev/onvoid/webrtc/e2ee/rfc9605-test-vectors.txt @@ -0,0 +1,299 @@ +# Test vectors of RFC 9605, Appendix C, one per line: C.1 (section=header), +# C.2 (section=aead) and C.3 (section=sframe). Extracted from the RFC text. +section=header kid=0000000000000000 ctr=0000000000000000 header=00 +section=header kid=0000000000000000 ctr=0000000000000001 header=01 +section=header kid=0000000000000000 ctr=00000000000000ff header=08ff +section=header kid=0000000000000000 ctr=0000000000000100 header=090100 +section=header kid=0000000000000000 ctr=000000000000ffff header=09ffff +section=header kid=0000000000000000 ctr=0000000000010000 header=0a010000 +section=header kid=0000000000000000 ctr=0000000000ffffff header=0affffff +section=header kid=0000000000000000 ctr=0000000001000000 header=0b01000000 +section=header kid=0000000000000000 ctr=00000000ffffffff header=0bffffffff +section=header kid=0000000000000000 ctr=0000000100000000 header=0c0100000000 +section=header kid=0000000000000000 ctr=000000ffffffffff header=0cffffffffff +section=header kid=0000000000000000 ctr=0000010000000000 header=0d010000000000 +section=header kid=0000000000000000 ctr=0000ffffffffffff header=0dffffffffffff +section=header kid=0000000000000000 ctr=0001000000000000 header=0e01000000000000 +section=header kid=0000000000000000 ctr=00ffffffffffffff header=0effffffffffffff +section=header kid=0000000000000000 ctr=0100000000000000 header=0f0100000000000000 +section=header kid=0000000000000000 ctr=ffffffffffffffff header=0fffffffffffffffff +section=header kid=0000000000000001 ctr=0000000000000000 header=10 +section=header kid=0000000000000001 ctr=0000000000000001 header=11 +section=header kid=0000000000000001 ctr=00000000000000ff header=18ff +section=header kid=0000000000000001 ctr=0000000000000100 header=190100 +section=header kid=0000000000000001 ctr=000000000000ffff header=19ffff +section=header kid=0000000000000001 ctr=0000000000010000 header=1a010000 +section=header kid=0000000000000001 ctr=0000000000ffffff header=1affffff +section=header kid=0000000000000001 ctr=0000000001000000 header=1b01000000 +section=header kid=0000000000000001 ctr=00000000ffffffff header=1bffffffff +section=header kid=0000000000000001 ctr=0000000100000000 header=1c0100000000 +section=header kid=0000000000000001 ctr=000000ffffffffff header=1cffffffffff +section=header kid=0000000000000001 ctr=0000010000000000 header=1d010000000000 +section=header kid=0000000000000001 ctr=0000ffffffffffff header=1dffffffffffff +section=header kid=0000000000000001 ctr=0001000000000000 header=1e01000000000000 +section=header kid=0000000000000001 ctr=00ffffffffffffff header=1effffffffffffff +section=header kid=0000000000000001 ctr=0100000000000000 header=1f0100000000000000 +section=header kid=0000000000000001 ctr=ffffffffffffffff header=1fffffffffffffffff +section=header kid=00000000000000ff ctr=0000000000000000 header=80ff +section=header kid=00000000000000ff ctr=0000000000000001 header=81ff +section=header kid=00000000000000ff ctr=00000000000000ff header=88ffff +section=header kid=00000000000000ff ctr=0000000000000100 header=89ff0100 +section=header kid=00000000000000ff ctr=000000000000ffff header=89ffffff +section=header kid=00000000000000ff ctr=0000000000010000 header=8aff010000 +section=header kid=00000000000000ff ctr=0000000000ffffff header=8affffffff +section=header kid=00000000000000ff ctr=0000000001000000 header=8bff01000000 +section=header kid=00000000000000ff ctr=00000000ffffffff header=8bffffffffff +section=header kid=00000000000000ff ctr=0000000100000000 header=8cff0100000000 +section=header kid=00000000000000ff ctr=000000ffffffffff header=8cffffffffffff +section=header kid=00000000000000ff ctr=0000010000000000 header=8dff010000000000 +section=header kid=00000000000000ff ctr=0000ffffffffffff header=8dffffffffffffff +section=header kid=00000000000000ff ctr=0001000000000000 header=8eff01000000000000 +section=header kid=00000000000000ff ctr=00ffffffffffffff header=8effffffffffffffff +section=header kid=00000000000000ff ctr=0100000000000000 header=8fff0100000000000000 +section=header kid=00000000000000ff ctr=ffffffffffffffff header=8fffffffffffffffffff +section=header kid=0000000000000100 ctr=0000000000000000 header=900100 +section=header kid=0000000000000100 ctr=0000000000000001 header=910100 +section=header kid=0000000000000100 ctr=00000000000000ff header=980100ff +section=header kid=0000000000000100 ctr=0000000000000100 header=9901000100 +section=header kid=0000000000000100 ctr=000000000000ffff header=990100ffff +section=header kid=0000000000000100 ctr=0000000000010000 header=9a0100010000 +section=header kid=0000000000000100 ctr=0000000000ffffff header=9a0100ffffff +section=header kid=0000000000000100 ctr=0000000001000000 header=9b010001000000 +section=header kid=0000000000000100 ctr=00000000ffffffff header=9b0100ffffffff +section=header kid=0000000000000100 ctr=0000000100000000 header=9c01000100000000 +section=header kid=0000000000000100 ctr=000000ffffffffff header=9c0100ffffffffff +section=header kid=0000000000000100 ctr=0000010000000000 header=9d0100010000000000 +section=header kid=0000000000000100 ctr=0000ffffffffffff header=9d0100ffffffffffff +section=header kid=0000000000000100 ctr=0001000000000000 header=9e010001000000000000 +section=header kid=0000000000000100 ctr=00ffffffffffffff header=9e0100ffffffffffffff +section=header kid=0000000000000100 ctr=0100000000000000 header=9f01000100000000000000 +section=header kid=0000000000000100 ctr=ffffffffffffffff header=9f0100ffffffffffffffff +section=header kid=000000000000ffff ctr=0000000000000000 header=90ffff +section=header kid=000000000000ffff ctr=0000000000000001 header=91ffff +section=header kid=000000000000ffff ctr=00000000000000ff header=98ffffff +section=header kid=000000000000ffff ctr=0000000000000100 header=99ffff0100 +section=header kid=000000000000ffff ctr=000000000000ffff header=99ffffffff +section=header kid=000000000000ffff ctr=0000000000010000 header=9affff010000 +section=header kid=000000000000ffff ctr=0000000000ffffff header=9affffffffff +section=header kid=000000000000ffff ctr=0000000001000000 header=9bffff01000000 +section=header kid=000000000000ffff ctr=00000000ffffffff header=9bffffffffffff +section=header kid=000000000000ffff ctr=0000000100000000 header=9cffff0100000000 +section=header kid=000000000000ffff ctr=000000ffffffffff header=9cffffffffffffff +section=header kid=000000000000ffff ctr=0000010000000000 header=9dffff010000000000 +section=header kid=000000000000ffff ctr=0000ffffffffffff header=9dffffffffffffffff +section=header kid=000000000000ffff ctr=0001000000000000 header=9effff01000000000000 +section=header kid=000000000000ffff ctr=00ffffffffffffff header=9effffffffffffffffff +section=header kid=000000000000ffff ctr=0100000000000000 header=9fffff0100000000000000 +section=header kid=000000000000ffff ctr=ffffffffffffffff header=9fffffffffffffffffffff +section=header kid=0000000000010000 ctr=0000000000000000 header=a0010000 +section=header kid=0000000000010000 ctr=0000000000000001 header=a1010000 +section=header kid=0000000000010000 ctr=00000000000000ff header=a8010000ff +section=header kid=0000000000010000 ctr=0000000000000100 header=a90100000100 +section=header kid=0000000000010000 ctr=000000000000ffff header=a9010000ffff +section=header kid=0000000000010000 ctr=0000000000010000 header=aa010000010000 +section=header kid=0000000000010000 ctr=0000000000ffffff header=aa010000ffffff +section=header kid=0000000000010000 ctr=0000000001000000 header=ab01000001000000 +section=header kid=0000000000010000 ctr=00000000ffffffff header=ab010000ffffffff +section=header kid=0000000000010000 ctr=0000000100000000 header=ac0100000100000000 +section=header kid=0000000000010000 ctr=000000ffffffffff header=ac010000ffffffffff +section=header kid=0000000000010000 ctr=0000010000000000 header=ad010000010000000000 +section=header kid=0000000000010000 ctr=0000ffffffffffff header=ad010000ffffffffffff +section=header kid=0000000000010000 ctr=0001000000000000 header=ae01000001000000000000 +section=header kid=0000000000010000 ctr=00ffffffffffffff header=ae010000ffffffffffffff +section=header kid=0000000000010000 ctr=0100000000000000 header=af0100000100000000000000 +section=header kid=0000000000010000 ctr=ffffffffffffffff header=af010000ffffffffffffffff +section=header kid=0000000000ffffff ctr=0000000000000000 header=a0ffffff +section=header kid=0000000000ffffff ctr=0000000000000001 header=a1ffffff +section=header kid=0000000000ffffff ctr=00000000000000ff header=a8ffffffff +section=header kid=0000000000ffffff ctr=0000000000000100 header=a9ffffff0100 +section=header kid=0000000000ffffff ctr=000000000000ffff header=a9ffffffffff +section=header kid=0000000000ffffff ctr=0000000000010000 header=aaffffff010000 +section=header kid=0000000000ffffff ctr=0000000000ffffff header=aaffffffffffff +section=header kid=0000000000ffffff ctr=0000000001000000 header=abffffff01000000 +section=header kid=0000000000ffffff ctr=00000000ffffffff header=abffffffffffffff +section=header kid=0000000000ffffff ctr=0000000100000000 header=acffffff0100000000 +section=header kid=0000000000ffffff ctr=000000ffffffffff header=acffffffffffffffff +section=header kid=0000000000ffffff ctr=0000010000000000 header=adffffff010000000000 +section=header kid=0000000000ffffff ctr=0000ffffffffffff header=adffffffffffffffffff +section=header kid=0000000000ffffff ctr=0001000000000000 header=aeffffff01000000000000 +section=header kid=0000000000ffffff ctr=00ffffffffffffff header=aeffffffffffffffffffff +section=header kid=0000000000ffffff ctr=0100000000000000 header=afffffff0100000000000000 +section=header kid=0000000000ffffff ctr=ffffffffffffffff header=afffffffffffffffffffffff +section=header kid=0000000001000000 ctr=0000000000000000 header=b001000000 +section=header kid=0000000001000000 ctr=0000000000000001 header=b101000000 +section=header kid=0000000001000000 ctr=00000000000000ff header=b801000000ff +section=header kid=0000000001000000 ctr=0000000000000100 header=b9010000000100 +section=header kid=0000000001000000 ctr=000000000000ffff header=b901000000ffff +section=header kid=0000000001000000 ctr=0000000000010000 header=ba01000000010000 +section=header kid=0000000001000000 ctr=0000000000ffffff header=ba01000000ffffff +section=header kid=0000000001000000 ctr=0000000001000000 header=bb0100000001000000 +section=header kid=0000000001000000 ctr=00000000ffffffff header=bb01000000ffffffff +section=header kid=0000000001000000 ctr=0000000100000000 header=bc010000000100000000 +section=header kid=0000000001000000 ctr=000000ffffffffff header=bc01000000ffffffffff +section=header kid=0000000001000000 ctr=0000010000000000 header=bd01000000010000000000 +section=header kid=0000000001000000 ctr=0000ffffffffffff header=bd01000000ffffffffffff +section=header kid=0000000001000000 ctr=0001000000000000 header=be0100000001000000000000 +section=header kid=0000000001000000 ctr=00ffffffffffffff header=be01000000ffffffffffffff +section=header kid=0000000001000000 ctr=0100000000000000 header=bf010000000100000000000000 +section=header kid=0000000001000000 ctr=ffffffffffffffff header=bf01000000ffffffffffffffff +section=header kid=00000000ffffffff ctr=0000000000000000 header=b0ffffffff +section=header kid=00000000ffffffff ctr=0000000000000001 header=b1ffffffff +section=header kid=00000000ffffffff ctr=00000000000000ff header=b8ffffffffff +section=header kid=00000000ffffffff ctr=0000000000000100 header=b9ffffffff0100 +section=header kid=00000000ffffffff ctr=000000000000ffff header=b9ffffffffffff +section=header kid=00000000ffffffff ctr=0000000000010000 header=baffffffff010000 +section=header kid=00000000ffffffff ctr=0000000000ffffff header=baffffffffffffff +section=header kid=00000000ffffffff ctr=0000000001000000 header=bbffffffff01000000 +section=header kid=00000000ffffffff ctr=00000000ffffffff header=bbffffffffffffffff +section=header kid=00000000ffffffff ctr=0000000100000000 header=bcffffffff0100000000 +section=header kid=00000000ffffffff ctr=000000ffffffffff header=bcffffffffffffffffff +section=header kid=00000000ffffffff ctr=0000010000000000 header=bdffffffff010000000000 +section=header kid=00000000ffffffff ctr=0000ffffffffffff header=bdffffffffffffffffffff +section=header kid=00000000ffffffff ctr=0001000000000000 header=beffffffff01000000000000 +section=header kid=00000000ffffffff ctr=00ffffffffffffff header=beffffffffffffffffffffff +section=header kid=00000000ffffffff ctr=0100000000000000 header=bfffffffff0100000000000000 +section=header kid=00000000ffffffff ctr=ffffffffffffffff header=bfffffffffffffffffffffffff +section=header kid=0000000100000000 ctr=0000000000000000 header=c00100000000 +section=header kid=0000000100000000 ctr=0000000000000001 header=c10100000000 +section=header kid=0000000100000000 ctr=00000000000000ff header=c80100000000ff +section=header kid=0000000100000000 ctr=0000000000000100 header=c901000000000100 +section=header kid=0000000100000000 ctr=000000000000ffff header=c90100000000ffff +section=header kid=0000000100000000 ctr=0000000000010000 header=ca0100000000010000 +section=header kid=0000000100000000 ctr=0000000000ffffff header=ca0100000000ffffff +section=header kid=0000000100000000 ctr=0000000001000000 header=cb010000000001000000 +section=header kid=0000000100000000 ctr=00000000ffffffff header=cb0100000000ffffffff +section=header kid=0000000100000000 ctr=0000000100000000 header=cc01000000000100000000 +section=header kid=0000000100000000 ctr=000000ffffffffff header=cc0100000000ffffffffff +section=header kid=0000000100000000 ctr=0000010000000000 header=cd0100000000010000000000 +section=header kid=0000000100000000 ctr=0000ffffffffffff header=cd0100000000ffffffffffff +section=header kid=0000000100000000 ctr=0001000000000000 header=ce010000000001000000000000 +section=header kid=0000000100000000 ctr=00ffffffffffffff header=ce0100000000ffffffffffffff +section=header kid=0000000100000000 ctr=0100000000000000 header=cf01000000000100000000000000 +section=header kid=0000000100000000 ctr=ffffffffffffffff header=cf0100000000ffffffffffffffff +section=header kid=000000ffffffffff ctr=0000000000000000 header=c0ffffffffff +section=header kid=000000ffffffffff ctr=0000000000000001 header=c1ffffffffff +section=header kid=000000ffffffffff ctr=00000000000000ff header=c8ffffffffffff +section=header kid=000000ffffffffff ctr=0000000000000100 header=c9ffffffffff0100 +section=header kid=000000ffffffffff ctr=000000000000ffff header=c9ffffffffffffff +section=header kid=000000ffffffffff ctr=0000000000010000 header=caffffffffff010000 +section=header kid=000000ffffffffff ctr=0000000000ffffff header=caffffffffffffffff +section=header kid=000000ffffffffff ctr=0000000001000000 header=cbffffffffff01000000 +section=header kid=000000ffffffffff ctr=00000000ffffffff header=cbffffffffffffffffff +section=header kid=000000ffffffffff ctr=0000000100000000 header=ccffffffffff0100000000 +section=header kid=000000ffffffffff ctr=000000ffffffffff header=ccffffffffffffffffffff +section=header kid=000000ffffffffff ctr=0000010000000000 header=cdffffffffff010000000000 +section=header kid=000000ffffffffff ctr=0000ffffffffffff header=cdffffffffffffffffffffff +section=header kid=000000ffffffffff ctr=0001000000000000 header=ceffffffffff01000000000000 +section=header kid=000000ffffffffff ctr=00ffffffffffffff header=ceffffffffffffffffffffffff +section=header kid=000000ffffffffff ctr=0100000000000000 header=cfffffffffff0100000000000000 +section=header kid=000000ffffffffff ctr=ffffffffffffffff header=cfffffffffffffffffffffffffff +section=header kid=0000010000000000 ctr=0000000000000000 header=d0010000000000 +section=header kid=0000010000000000 ctr=0000000000000001 header=d1010000000000 +section=header kid=0000010000000000 ctr=00000000000000ff header=d8010000000000ff +section=header kid=0000010000000000 ctr=0000000000000100 header=d90100000000000100 +section=header kid=0000010000000000 ctr=000000000000ffff header=d9010000000000ffff +section=header kid=0000010000000000 ctr=0000000000010000 header=da010000000000010000 +section=header kid=0000010000000000 ctr=0000000000ffffff header=da010000000000ffffff +section=header kid=0000010000000000 ctr=0000000001000000 header=db01000000000001000000 +section=header kid=0000010000000000 ctr=00000000ffffffff header=db010000000000ffffffff +section=header kid=0000010000000000 ctr=0000000100000000 header=dc0100000000000100000000 +section=header kid=0000010000000000 ctr=000000ffffffffff header=dc010000000000ffffffffff +section=header kid=0000010000000000 ctr=0000010000000000 header=dd010000000000010000000000 +section=header kid=0000010000000000 ctr=0000ffffffffffff header=dd010000000000ffffffffffff +section=header kid=0000010000000000 ctr=0001000000000000 header=de01000000000001000000000000 +section=header kid=0000010000000000 ctr=00ffffffffffffff header=de010000000000ffffffffffffff +section=header kid=0000010000000000 ctr=0100000000000000 header=df0100000000000100000000000000 +section=header kid=0000010000000000 ctr=ffffffffffffffff header=df010000000000ffffffffffffffff +section=header kid=0000ffffffffffff ctr=0000000000000000 header=d0ffffffffffff +section=header kid=0000ffffffffffff ctr=0000000000000001 header=d1ffffffffffff +section=header kid=0000ffffffffffff ctr=00000000000000ff header=d8ffffffffffffff +section=header kid=0000ffffffffffff ctr=0000000000000100 header=d9ffffffffffff0100 +section=header kid=0000ffffffffffff ctr=000000000000ffff header=d9ffffffffffffffff +section=header kid=0000ffffffffffff ctr=0000000000010000 header=daffffffffffff010000 +section=header kid=0000ffffffffffff ctr=0000000000ffffff header=daffffffffffffffffff +section=header kid=0000ffffffffffff ctr=0000000001000000 header=dbffffffffffff01000000 +section=header kid=0000ffffffffffff ctr=00000000ffffffff header=dbffffffffffffffffffff +section=header kid=0000ffffffffffff ctr=0000000100000000 header=dcffffffffffff0100000000 +section=header kid=0000ffffffffffff ctr=000000ffffffffff header=dcffffffffffffffffffffff +section=header kid=0000ffffffffffff ctr=0000010000000000 header=ddffffffffffff010000000000 +section=header kid=0000ffffffffffff ctr=0000ffffffffffff header=ddffffffffffffffffffffffff +section=header kid=0000ffffffffffff ctr=0001000000000000 header=deffffffffffff01000000000000 +section=header kid=0000ffffffffffff ctr=00ffffffffffffff header=deffffffffffffffffffffffffff +section=header kid=0000ffffffffffff ctr=0100000000000000 header=dfffffffffffff0100000000000000 +section=header kid=0000ffffffffffff ctr=ffffffffffffffff header=dfffffffffffffffffffffffffffff +section=header kid=0001000000000000 ctr=0000000000000000 header=e001000000000000 +section=header kid=0001000000000000 ctr=0000000000000001 header=e101000000000000 +section=header kid=0001000000000000 ctr=00000000000000ff header=e801000000000000ff +section=header kid=0001000000000000 ctr=0000000000000100 header=e9010000000000000100 +section=header kid=0001000000000000 ctr=000000000000ffff header=e901000000000000ffff +section=header kid=0001000000000000 ctr=0000000000010000 header=ea01000000000000010000 +section=header kid=0001000000000000 ctr=0000000000ffffff header=ea01000000000000ffffff +section=header kid=0001000000000000 ctr=0000000001000000 header=eb0100000000000001000000 +section=header kid=0001000000000000 ctr=00000000ffffffff header=eb01000000000000ffffffff +section=header kid=0001000000000000 ctr=0000000100000000 header=ec010000000000000100000000 +section=header kid=0001000000000000 ctr=000000ffffffffff header=ec01000000000000ffffffffff +section=header kid=0001000000000000 ctr=0000010000000000 header=ed01000000000000010000000000 +section=header kid=0001000000000000 ctr=0000ffffffffffff header=ed01000000000000ffffffffffff +section=header kid=0001000000000000 ctr=0001000000000000 header=ee0100000000000001000000000000 +section=header kid=0001000000000000 ctr=00ffffffffffffff header=ee01000000000000ffffffffffffff +section=header kid=0001000000000000 ctr=0100000000000000 header=ef010000000000000100000000000000 +section=header kid=0001000000000000 ctr=ffffffffffffffff header=ef01000000000000ffffffffffffffff +section=header kid=00ffffffffffffff ctr=0000000000000000 header=e0ffffffffffffff +section=header kid=00ffffffffffffff ctr=0000000000000001 header=e1ffffffffffffff +section=header kid=00ffffffffffffff ctr=00000000000000ff header=e8ffffffffffffffff +section=header kid=00ffffffffffffff ctr=0000000000000100 header=e9ffffffffffffff0100 +section=header kid=00ffffffffffffff ctr=000000000000ffff header=e9ffffffffffffffffff +section=header kid=00ffffffffffffff ctr=0000000000010000 header=eaffffffffffffff010000 +section=header kid=00ffffffffffffff ctr=0000000000ffffff header=eaffffffffffffffffffff +section=header kid=00ffffffffffffff ctr=0000000001000000 header=ebffffffffffffff01000000 +section=header kid=00ffffffffffffff ctr=00000000ffffffff header=ebffffffffffffffffffffff +section=header kid=00ffffffffffffff ctr=0000000100000000 header=ecffffffffffffff0100000000 +section=header kid=00ffffffffffffff ctr=000000ffffffffff header=ecffffffffffffffffffffffff +section=header kid=00ffffffffffffff ctr=0000010000000000 header=edffffffffffffff010000000000 +section=header kid=00ffffffffffffff ctr=0000ffffffffffff header=edffffffffffffffffffffffffff +section=header kid=00ffffffffffffff ctr=0001000000000000 header=eeffffffffffffff01000000000000 +section=header kid=00ffffffffffffff ctr=00ffffffffffffff header=eeffffffffffffffffffffffffffff +section=header kid=00ffffffffffffff ctr=0100000000000000 header=efffffffffffffff0100000000000000 +section=header kid=00ffffffffffffff ctr=ffffffffffffffff header=efffffffffffffffffffffffffffffff +section=header kid=0100000000000000 ctr=0000000000000000 header=f00100000000000000 +section=header kid=0100000000000000 ctr=0000000000000001 header=f10100000000000000 +section=header kid=0100000000000000 ctr=00000000000000ff header=f80100000000000000ff +section=header kid=0100000000000000 ctr=0000000000000100 header=f901000000000000000100 +section=header kid=0100000000000000 ctr=000000000000ffff header=f90100000000000000ffff +section=header kid=0100000000000000 ctr=0000000000010000 header=fa0100000000000000010000 +section=header kid=0100000000000000 ctr=0000000000ffffff header=fa0100000000000000ffffff +section=header kid=0100000000000000 ctr=0000000001000000 header=fb010000000000000001000000 +section=header kid=0100000000000000 ctr=00000000ffffffff header=fb0100000000000000ffffffff +section=header kid=0100000000000000 ctr=0000000100000000 header=fc01000000000000000100000000 +section=header kid=0100000000000000 ctr=000000ffffffffff header=fc0100000000000000ffffffffff +section=header kid=0100000000000000 ctr=0000010000000000 header=fd0100000000000000010000000000 +section=header kid=0100000000000000 ctr=0000ffffffffffff header=fd0100000000000000ffffffffffff +section=header kid=0100000000000000 ctr=0001000000000000 header=fe010000000000000001000000000000 +section=header kid=0100000000000000 ctr=00ffffffffffffff header=fe0100000000000000ffffffffffffff +section=header kid=0100000000000000 ctr=0100000000000000 header=ff01000000000000000100000000000000 +section=header kid=0100000000000000 ctr=ffffffffffffffff header=ff0100000000000000ffffffffffffffff +section=header kid=ffffffffffffffff ctr=0000000000000000 header=f0ffffffffffffffff +section=header kid=ffffffffffffffff ctr=0000000000000001 header=f1ffffffffffffffff +section=header kid=ffffffffffffffff ctr=00000000000000ff header=f8ffffffffffffffffff +section=header kid=ffffffffffffffff ctr=0000000000000100 header=f9ffffffffffffffff0100 +section=header kid=ffffffffffffffff ctr=000000000000ffff header=f9ffffffffffffffffffff +section=header kid=ffffffffffffffff ctr=0000000000010000 header=faffffffffffffffff010000 +section=header kid=ffffffffffffffff ctr=0000000000ffffff header=faffffffffffffffffffffff +section=header kid=ffffffffffffffff ctr=0000000001000000 header=fbffffffffffffffff01000000 +section=header kid=ffffffffffffffff ctr=00000000ffffffff header=fbffffffffffffffffffffffff +section=header kid=ffffffffffffffff ctr=0000000100000000 header=fcffffffffffffffff0100000000 +section=header kid=ffffffffffffffff ctr=000000ffffffffff header=fcffffffffffffffffffffffffff +section=header kid=ffffffffffffffff ctr=0000010000000000 header=fdffffffffffffffff010000000000 +section=header kid=ffffffffffffffff ctr=0000ffffffffffff header=fdffffffffffffffffffffffffffff +section=header kid=ffffffffffffffff ctr=0001000000000000 header=feffffffffffffffff01000000000000 +section=header kid=ffffffffffffffff ctr=00ffffffffffffff header=feffffffffffffffffffffffffffffff +section=header kid=ffffffffffffffff ctr=0100000000000000 header=ffffffffffffffffff0100000000000000 +section=header kid=ffffffffffffffff ctr=ffffffffffffffff header=ffffffffffffffffffffffffffffffffff +section=aead cipher_suite=0001 key=000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f enc_key=000102030405060708090a0b0c0d0e0f auth_key=101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f nonce=101112131415161718191a1b aad=4945544620534672616d65205747 pt=64726166742d696574662d736672616d652d656e63 ct=6339af04ada1d064688a442b8dc69d5b6bfa40f4bef0583e8081069cc60705 +section=aead cipher_suite=0002 key=000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f enc_key=000102030405060708090a0b0c0d0e0f auth_key=101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f nonce=101112131415161718191a1b aad=4945544620534672616d65205747 pt=64726166742d696574662d736672616d652d656e63 ct=6339af04ada1d064688a442b8dc69d5b6bfa40f4be6e93b7da076927bb +section=aead cipher_suite=0003 key=000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f enc_key=000102030405060708090a0b0c0d0e0f auth_key=101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f nonce=101112131415161718191a1b aad=4945544620534672616d65205747 pt=64726166742d696574662d736672616d652d656e63 ct=6339af04ada1d064688a442b8dc69d5b6bfa40f4be09480509 +section=sframe cipher_suite=0001 kid=0000000000000123 ctr=0000000000004567 base_key=000102030405060708090a0b0c0d0e0f sframe_key_label=534672616d6520312e3020536563726574206b65792000000000000001230001 sframe_salt_label=534672616d6520312e30205365637265742073616c742000000000000001230001 sframe_secret=d926952ca8b7ec4a95941d1ada3a5203ceff8cceee34f574d23909eb314c40c0 sframe_key=3f7d9a7c83ae8e1c8a11ae695ab59314b367e359fadac7b9c46b2bc6f81f46e16b96f0811868d59402b7e870102720b3 sframe_salt=50b29329a04dc0f184ac3168 metadata=4945544620534672616d65205747 nonce=50b29329a04dc0f184ac740f aad=99012345674945544620534672616d65205747 pt=64726166742d696574662d736672616d652d656e63 ct=9901234567449408b6f490086165b9d6f62b24ae1a59a56486b4ae8ed036b88912e24f11 +section=sframe cipher_suite=0002 kid=0000000000000123 ctr=0000000000004567 base_key=000102030405060708090a0b0c0d0e0f sframe_key_label=534672616d6520312e3020536563726574206b65792000000000000001230002 sframe_salt_label=534672616d6520312e30205365637265742073616c742000000000000001230002 sframe_secret=d926952ca8b7ec4a95941d1ada3a5203ceff8cceee34f574d23909eb314c40c0 sframe_key=e2ec5c797540310483b16bf6e7a570d2a27d192fe869c7ccd8584a8d9dab91549fbe553f5113461ec6aa83bf3865553e sframe_salt=e68ac8dd3d02fbcd368c5577 metadata=4945544620534672616d65205747 nonce=e68ac8dd3d02fbcd368c1010 aad=99012345674945544620534672616d65205747 pt=64726166742d696574662d736672616d652d656e63 ct=99012345673f31438db4d09434e43afa0f8a2f00867a2be085046a9f5cb4f101d607 +section=sframe cipher_suite=0003 kid=0000000000000123 ctr=0000000000004567 base_key=000102030405060708090a0b0c0d0e0f sframe_key_label=534672616d6520312e3020536563726574206b65792000000000000001230003 sframe_salt_label=534672616d6520312e30205365637265742073616c742000000000000001230003 sframe_secret=d926952ca8b7ec4a95941d1ada3a5203ceff8cceee34f574d23909eb314c40c0 sframe_key=2c5703089cbb8c583475e4fc461d97d18809df79b6d550f78eb6d50ffa80d89211d57909934f46f5405e38cd583c69fe sframe_salt=38c16e4f5159700c00c7f350 metadata=4945544620534672616d65205747 nonce=38c16e4f5159700c00c7b637 aad=99012345674945544620534672616d65205747 pt=64726166742d696574662d736672616d652d656e63 ct=990123456717fc8af28a5a695afcfc6c8df6358a17e26b2fcb3bae32e443 +section=sframe cipher_suite=0004 kid=0000000000000123 ctr=0000000000004567 base_key=000102030405060708090a0b0c0d0e0f sframe_key_label=534672616d6520312e3020536563726574206b65792000000000000001230004 sframe_salt_label=534672616d6520312e30205365637265742073616c742000000000000001230004 sframe_secret=d926952ca8b7ec4a95941d1ada3a5203ceff8cceee34f574d23909eb314c40c0 sframe_key=d34f547f4ca4f9a7447006fe7fcbf768 sframe_salt=75234edefe07819026751816 metadata=4945544620534672616d65205747 nonce=75234edefe07819026755d71 aad=99012345674945544620534672616d65205747 pt=64726166742d696574662d736672616d652d656e63 ct=9901234567b7412c2513a1b66dbb48841bbaf17f598751176ad847681a69c6d0b091c07018ce4adb34eb +section=sframe cipher_suite=0005 kid=0000000000000123 ctr=0000000000004567 base_key=000102030405060708090a0b0c0d0e0f sframe_key_label=534672616d6520312e3020536563726574206b65792000000000000001230005 sframe_salt_label=534672616d6520312e30205365637265742073616c742000000000000001230005 sframe_secret=0fc3ea6de6aac97a35f194cf9bed94d4b5230f1cb45a785c9fe5dce9c188938ab6ba005bc4c0a19181599e9d1bcf7b74aca48b60bf5e254e546d809313e083a3 sframe_key=d3e27b0d4a5ae9e55df01a70e6d4d28d969b246e2936f4b7a5d9b494da6b9633 sframe_salt=84991c167b8cd23c93708ec7 metadata=4945544620534672616d65205747 nonce=84991c167b8cd23c9370cba0 aad=99012345674945544620534672616d65205747 pt=64726166742d696574662d736672616d652d656e63 ct=990123456794f509d36e9beacb0e261d99c7d1e972f1fed787d4049f17ca21353c1cc24d56ceabced279 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 new file mode 100644 index 000000000..97bad4b3d --- /dev/null +++ b/webrtc/src/test/resources/dev/onvoid/webrtc/e2ee/sframe-interop.mjs @@ -0,0 +1,93 @@ +// Runs the browser implementation of the frame format (docs/public/e2ee) in +// Node.js for BrowserInteropTests: checks it against the RFC 9605 test +// vectors, decrypts the frames the Java side encrypted, and encrypts the +// same frames for the Java side to decrypt. +// +// node sframe-interop.mjs +// +// The frames file has one item per line: +// suite +// javaKey the key the Java side encrypts with +// jsKey the key this side encrypts with +// frame +// +// Prints "vector ok|fail", "decrypt ok|fail " and +// "sealed ", then "done". + +import { readFileSync } from 'node:fs'; +import { pathToFileURL } from 'node:url'; + +const [moduleFile, vectorsFile, framesFile] = process.argv.slice(2); +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(''); + +// The SFrame vectors of RFC 9605, Appendix C.3. +let index = 0; + +for (const line of readFileSync(vectorsFile, 'utf8').split('\n')) { + if (!line.startsWith('section=sframe')) { + continue; + } + + const v = Object.fromEntries(line.trim().split(' ').map((field) => field.split('='))); + const suite = parseInt(v.cipher_suite, 16); + const key = await sframe.SFrameKey.derive(suite, BigInt('0x' + v.kid), hex(v.base_key)); + const ct = await key.encrypt(BigInt('0x' + v.ctr), hex(v.metadata), hex(v.pt)); + + const header = sframe.parseHeader(ct); + const pt = await key.decrypt(header.ctr, ct.subarray(0, header.length), hex(v.metadata), + ct.subarray(header.length)); + + console.log(`vector ${index++} ${toHex(ct) === v.ct && pt && toHex(pt) === v.pt ? 'ok' : 'fail'}`); +} + +// The frames of the Java side. +const failures = []; +let keys; +let frameIndex = 0; +const sealed = []; + +for (const line of readFileSync(framesFile, 'utf8').split('\n')) { + const fields = line.trim().split(' '); + + switch (fields[0]) { + case 'suite': + keys = { suite: parseInt(fields[1], 10) }; + break; + case 'javaKey': + keys.java = { participant: parseInt(fields[1], 10), key: hex(fields[2]) }; + break; + case 'jsKey': { + keys.js = { participant: parseInt(fields[1], 10), key: hex(fields[2]) }; + + keys.provider = new sframe.KeyProvider({ participant: keys.js.participant, cipherSuite: keys.suite, + onFailure: (event) => failures.push(event.failure) }); + keys.provider.setEncryptionKey(0, keys.js.key); + keys.provider.setDecryptionKey(keys.java.participant, 0, keys.java.key); + keys.encryptor = keys.provider.createEncryptor(); + keys.decryptor = keys.provider.createDecryptor(); + break; + } + case 'frame': { + const [, mimeType, key, ssrc, plain, encrypted] = fields; + const info = { mimeType, keyFrame: key === '1', video: mimeType.startsWith('video/'), ssrc: Number(ssrc) }; + + const decrypted = await keys.decryptor.process(info, hex(encrypted)); + const ok = decrypted && toHex(decrypted) === plain; + + console.log(`decrypt ${frameIndex} ${ok ? 'ok' : 'fail ' + (failures.at(-1) || 'mismatch')}`); + + const out = await keys.encryptor.process(info, hex(plain)); + console.log(`sealed ${frameIndex} ${out ? toHex(out) : '-'}`); + + frameIndex++; + break; + } + default: + break; + } +} + +console.log('done'); From 8423c70017b9c9d884fdcf7e52bb0a3075c114a4 Mon Sep 17 00:00:00 2001 From: Alex Andres Date: Sun, 8 Nov 2026 20:38:17 +0100 Subject: [PATCH 2/2] fix: negotiate only encryptable video codecs with e2ee A peer with e2ee(keys) applied no codec preference, so macOS negotiated H.264, whose frames end-to-end encryption drops. Such a peer now offers and answers only VP8, VP9 and AV1 video, and videoCodecs() that names none of them fails. KeyProvider.supportsCodec() tells which codecs can be encrypted. The call tests accept replayed frames, which retransmissions produce on loaded machines, and print the stats when other frames are dropped. --- docs/guide/advanced/end-to-end-encryption.md | 5 +- .../webrtc/client/CodecPreferences.java | 91 +++++++++++++++---- .../webrtc/client/NegotiationSteps.java | 42 ++++++++- .../dev/onvoid/webrtc/client/PeerImpl.java | 6 +- .../dev/onvoid/webrtc/client/PeerOptions.java | 5 +- .../dev/onvoid/webrtc/e2ee/KeyProvider.java | 15 +++ .../java/dev/onvoid/webrtc/E2eeCallTests.java | 23 ++++- .../dev/onvoid/webrtc/client/E2eeTests.java | 69 +++++++++++--- 8 files changed, 214 insertions(+), 42 deletions(-) diff --git a/docs/guide/advanced/end-to-end-encryption.md b/docs/guide/advanced/end-to-end-encryption.md index 5e51dd3e5..528e59f03 100644 --- a/docs/guide/advanced/end-to-end-encryption.md +++ b/docs/guide/advanced/end-to-end-encryption.md @@ -130,7 +130,10 @@ The frame format covers VP8, VP9, AV1 and every audio codec. WebRTC's packetizer - **AV1** is split into OBUs by its packetizer, so the encrypted frame travels as a single OBU: a sequence header for a key frame, which is how the receiver recognizes one, and a frame OBU otherwise. - **VP9** and other audio codecs are encrypted whole. -H.264 and H.265 frames are split at their start codes before they are sent, which a ciphertext would contain anywhere, so they are dropped with `UNSUPPORTED_CODEC`. Prefer VP8, VP9 or AV1 for encrypted calls with `setCodecPreferences` on the transceivers, or with `videoCodecs("VP8", "VP9", "AV1")` of the [WHIP and WHEP](/guide/client-api#whip-and-whep) builders. This matters on macOS in particular, where WebRTC prefers H.264 through VideoToolbox. +H.264 and H.265 frames are split at their start codes before they are sent, which a ciphertext would contain anywhere, so they are dropped with `UNSUPPORTED_CODEC`. A call has to negotiate them away, which matters on macOS in particular, where WebRTC prefers H.264 through VideoToolbox: + +- A peer of the client API with `e2ee(keys)` does so by itself: it offers and answers only VP8, VP9 and AV1 video, in WebRTC's order. `videoCodecs(...)` of the [WHIP and WHEP](/guide/client-api#whip-and-whep) builders still picks among them, and fails the session with a `ConfigurationException` if it names none of them. +- Without the client API, call `setCodecPreferences` on each video transceiver with the codecs for which `KeyProvider.supportsCodec(codec.getMimeType())` is true, keeping `rtx`, `red` and `ulpfec`. ## Recording diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/CodecPreferences.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/CodecPreferences.java index 81b4d8563..df00f594c 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/client/CodecPreferences.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/CodecPreferences.java @@ -30,12 +30,14 @@ import dev.onvoid.webrtc.RTCRtpCodecCapability; import dev.onvoid.webrtc.RTCRtpReceiver; import dev.onvoid.webrtc.RTCRtpTransceiver; +import dev.onvoid.webrtc.e2ee.KeyProvider; import dev.onvoid.webrtc.media.MediaStreamTrack; import dev.onvoid.webrtc.media.MediaType; /** * The codecs a peer negotiates, for the kinds of media a session named codecs - * of. Confined to the control executor. + * of, and for video always if the peer encrypts end to end, which only some + * codecs can be. Confined to the control executor. */ final class CodecPreferences { @@ -48,12 +50,16 @@ final class CodecPreferences { private final PeerImpl peer; + /** Whether the peer encrypts end to end, and so negotiates only video it can encrypt. */ + private final boolean encrypted; + /** The codecs each kind of media is negotiated with, in order. */ private final Map> codecs = new EnumMap<>(MediaKind.class); - CodecPreferences(PeerImpl peer) { + CodecPreferences(PeerImpl peer, boolean encrypted) { this.peer = peer; + this.encrypted = encrypted; } /** @@ -67,21 +73,60 @@ final class CodecPreferences { */ void prefer(Map> names) { for (Map.Entry> entry : names.entrySet()) { - codecs.put(entry.getKey(), named(entry.getKey(), entry.getValue())); + MediaKind kind = entry.getKey(); + List named = named(kind, entry.getValue()); + + if (encrypted && kind == MediaKind.VIDEO) { + named = encryptable(named); + + if (named.stream().allMatch(CodecPreferences::isCompanion)) { + throw new ConfigurationException("End-to-end encryption covers VP8, VP9 and AV1 video, not " + + entry.getValue() + ", for " + peer.name); + } + } + + codecs.put(kind, named); } apply(); } /** - * Sets the preferred codecs on every transceiver that has not stopped. + * Sets the preferred codecs on every transceiver that has not stopped: + * those named, and with end-to-end encryption the video codecs it covers, + * in WebRTC's order, unless video codecs were named. */ void apply() { - if (codecs.isEmpty()) { + Map> preferred = codecs; + + if (encrypted && !codecs.containsKey(MediaKind.VIDEO)) { + preferred = new EnumMap<>(MediaKind.class); + preferred.putAll(codecs); + preferred.put(MediaKind.VIDEO, encryptable(new ArrayList<>(available(MediaKind.VIDEO).values()))); + } + + if (preferred.isEmpty()) { return; } - apply(peer.connection().getTransceivers(), codecs); + apply(peer.connection().getTransceivers(), preferred); + } + + /** The codecs of a list that end-to-end encryption covers, with their companions. */ + private static List encryptable(List codecs) { + List encryptable = new ArrayList<>(); + + for (RTCRtpCodecCapability codec : codecs) { + if (isCompanion(codec) || KeyProvider.supportsCodec(codec.getMimeType())) { + encryptable.add(codec); + } + } + + return encryptable; + } + + private static boolean isCompanion(RTCRtpCodecCapability codec) { + return COMPANION_CODECS.contains(codec.getName().toLowerCase(Locale.ROOT)); } /** Takes ownership of every wrapper, including those not reached on failure. */ @@ -121,19 +166,7 @@ static void apply(RTCRtpTransceiver[] transceivers, Map named(MediaKind kind, List names) { - MediaType type = kind == MediaKind.AUDIO ? MediaType.AUDIO : MediaType.VIDEO; - // Those WebRTC sends and receives, each once. WebRTC tells codecs - // apart as this key does, not by their scalability modes, in which - // the two lists differ; one codec twice would be offered twice. - Map, RTCRtpCodecCapability> available = new LinkedHashMap<>(); - - for (RTCRtpCapabilities capabilities : List.of(peer.rtc.factory.getRtpSenderCapabilities(type), - peer.rtc.factory.getRtpReceiverCapabilities(type))) { - for (RTCRtpCodecCapability codec : capabilities.getCodecs()) { - available.putIfAbsent(Arrays.asList(codec.getMimeType().toLowerCase(Locale.ROOT), - codec.getClockRate(), codec.getSDPFmtp()), codec); - } - } + Map, RTCRtpCodecCapability> available = available(kind); List named = new ArrayList<>(); @@ -165,4 +198,24 @@ private List named(MediaKind kind, List names) { return named; } + + /** + * The codecs of a kind WebRTC sends and receives, each once. WebRTC tells + * codecs apart as the key does, not by their scalability modes, in which + * the two lists differ; one codec twice would be offered twice. + */ + private Map, RTCRtpCodecCapability> available(MediaKind kind) { + MediaType type = kind == MediaKind.AUDIO ? MediaType.AUDIO : MediaType.VIDEO; + Map, RTCRtpCodecCapability> available = new LinkedHashMap<>(); + + for (RTCRtpCapabilities capabilities : List.of(peer.rtc.factory.getRtpSenderCapabilities(type), + peer.rtc.factory.getRtpReceiverCapabilities(type))) { + for (RTCRtpCodecCapability codec : capabilities.getCodecs()) { + available.putIfAbsent(Arrays.asList(codec.getMimeType().toLowerCase(Locale.ROOT), + codec.getClockRate(), codec.getSDPFmtp()), codec); + } + } + + return available; + } } diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/NegotiationSteps.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/NegotiationSteps.java index 229d1d9a7..0e4c3d7c1 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/client/NegotiationSteps.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/NegotiationSteps.java @@ -62,6 +62,9 @@ final class NegotiationSteps { private final Consumer candidateRejected; + /** Readies the transceivers before WebRTC writes an offer or answer. */ + private final Runnable beforeDescription; + /** The remote candidates that came before a remote description. */ private final List heldCandidates = new ArrayList<>(); @@ -78,10 +81,12 @@ final class NegotiationSteps { * candidates then fail to be added, harmlessly. * @param candidateRejected told of a held candidate WebRTC rejected, whose * operation is over by then. + * @param beforeDescription runs before every offer or answer is made, to + * set the codecs of the transceivers there are. */ NegotiationSteps(SerialExecutor control, ScheduledExecutorService timer, OperationChain chain, Supplier connection, Duration gatheringTimeout, BooleanSupplier ignoringOffer, - Consumer candidateRejected) { + Consumer candidateRejected, Runnable beforeDescription) { this.control = control; this.timer = timer; this.chain = chain; @@ -89,6 +94,7 @@ final class NegotiationSteps { this.gatheringTimeout = gatheringTimeout; this.ignoringOffer = ignoringOffer; this.candidateRejected = candidateRejected; + this.beforeDescription = beforeDescription; } /** @@ -96,6 +102,12 @@ final class NegotiationSteps { * or an answer. */ CompletableFuture setLocal() { + CompletableFuture ready = ready(); + + if (ready != null) { + return ready; + } + CompletableFuture future = chain.step(); connection.get().setLocalDescription(descriptionObserver(future, "Applying the local description failed")); return future; @@ -116,17 +128,45 @@ CompletableFuture setRemote(RTCSessionDescription description) { } CompletableFuture createOffer() { + CompletableFuture ready = ready(); + + if (ready != null) { + return ready; + } + CompletableFuture future = chain.step(); connection.get().createOffer(new RTCOfferOptions(), createObserver(future, "Creating the offer failed")); return future; } CompletableFuture createAnswer() { + CompletableFuture ready = ready(); + + if (ready != null) { + return ready; + } + CompletableFuture future = chain.step(); connection.get().createAnswer(new RTCAnswerOptions(), createObserver(future, "Creating the answer failed")); return future; } + /** + * Readies the transceivers for the description WebRTC is about to write. + * + * @return null if that worked, or a failed future to return instead. + */ + private CompletableFuture ready() { + try { + beforeDescription.run(); + + return null; + } + catch (RuntimeException e) { + return CompletableFuture.failedFuture(e); + } + } + /** * Takes back what is pending of an offer/answer exchange, whichever side * made the offer, so that signaling is stable again. diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerImpl.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerImpl.java index e56dc64e0..34b85f921 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerImpl.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerImpl.java @@ -162,17 +162,19 @@ final class PeerImpl implements Peer { this.stateHandlers = new Handlers<>(rtc::reportError); this.errorHandlers = new Handlers<>(rtc::reportError); this.chain = new OperationChain(control, rtc.timer, rtc.operationTimeout, name, new ChainHost()); + CodecPreferences codecs = new CodecPreferences(this, options.e2ee != null); + this.steps = new NegotiationSteps(control, rtc.timer, chain, () -> connection, options.gatheringTimeout, this::ignoresOffer, error -> { if (!closed) { deliverError(error); } - }); + }, codecs::apply); this.automatic = new PerfectNegotiation(this, options, chain, steps); this.statistics = new StatsSampler(this); this.channels = new DataChannels(this); this.tracks = new RemoteTracks(this, receiveTransforms(options)); - this.manual = new ManualNegotiation(this, options, chain, steps, tracks, new CodecPreferences(this)); + this.manual = new ManualNegotiation(this, options, chain, steps, tracks, codecs); this.signaling = new SignalingLink(this, options.signaling); rtc.track(connected, events); diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerOptions.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerOptions.java index 62a49f883..e0891e469 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerOptions.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerOptions.java @@ -396,8 +396,9 @@ public Builder receiveTransform(RTCEncodedFrameTransformer transform) { * reported to the provider's {@link * dev.onvoid.webrtc.e2ee.CryptoListener}, not to {@code onError}. *

    - * Video has to be sent in VP8, VP9 or AV1: H.264 and H.265 frames are - * dropped, see {@link dev.onvoid.webrtc.e2ee.CryptoFailure#UNSUPPORTED_CODEC}. + * The peer negotiates only the video codecs that can be encrypted, VP8, + * VP9 and AV1, since H.264 and H.265 frames would be dropped, see {@link + * dev.onvoid.webrtc.e2ee.CryptoFailure#UNSUPPORTED_CODEC}. * {@link Sender#transform} and {@link RemoteTrack#transform} still * replace the transform of one sender or track. A {@code MediaRecorder} * refuses the senders and tracks unless the provider {@link 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 354b9f97f..358ad386b 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/KeyProvider.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/KeyProvider.java @@ -141,6 +141,21 @@ public static Builder builder(long participant) { return new Builder(checkParticipant(participant)); } + /** + * Says whether frames of a codec can be encrypted: those of VP8, VP9, AV1 + * and every audio codec. H.264 and H.265 cannot, since their packetizers + * split frames at start codes that a ciphertext would contain anywhere, + * so an encrypted call has to negotiate them away, e.g. with {@code + * RTCRtpTransceiver.setCodecPreferences}. + * + * @param mimeType The codec as a MIME type, e.g. {@code video/VP8}. + * + * @return True if its frames can be encrypted. + */ + public static boolean supportsCodec(String mimeType) { + return FrameFormat.Codec.of(mimeType) != null; + } + /** * Makes a new random key, as long as the cipher suite's hash output. A * key is meant for one call: never use it again with another key diff --git a/webrtc/src/test/java/dev/onvoid/webrtc/E2eeCallTests.java b/webrtc/src/test/java/dev/onvoid/webrtc/E2eeCallTests.java index ce60ab664..3606d175e 100644 --- a/webrtc/src/test/java/dev/onvoid/webrtc/E2eeCallTests.java +++ b/webrtc/src/test/java/dev/onvoid/webrtc/E2eeCallTests.java @@ -27,6 +27,7 @@ import java.util.function.BooleanSupplier; import dev.onvoid.webrtc.e2ee.CryptoFailure; +import dev.onvoid.webrtc.e2ee.CryptoStats; import dev.onvoid.webrtc.e2ee.KeyProvider; import dev.onvoid.webrtc.internal.AllocationFault; import dev.onvoid.webrtc.internal.NativeApi; @@ -113,9 +114,9 @@ private void assertVideoDecodes(String codec) throws Exception { String sent = call.getSentVideoCodec(); assertTrue(sent == null || sent.equalsIgnoreCase("video/" + codec), sent); - // Nothing was dropped on the way: every frame authenticated. - assertEquals(0, callerKeys.getStats().getDroppedFrames()); - assertEquals(0, calleeKeys.getStats().getDroppedFrames()); + // Nothing was lost on the way: every frame authenticated. + assertNothingLost(callerKeys); + assertNothingLost(calleeKeys); track.removeSink(sink); receiver.dispose(); @@ -138,7 +139,7 @@ void encryptedAudioDecrypts() throws Exception { awaitTrue(() -> calleeKeys.getStats().getDecryptedFrames() >= 20, () -> "too few audio frames decrypted: " + calleeKeys.getStats()); - assertEquals(0, calleeKeys.getStats().getDroppedFrames()); + assertNothingLost(calleeKeys); receiver.dispose(); } @@ -226,7 +227,7 @@ void rotationKeepsDecoding() throws Exception { && calleeKeys.getStats().getDecryptedFrames() >= decryptedBefore + 40, () -> "decoding stopped after the key changed: " + calleeKeys.getStats()); - assertEquals(0, calleeKeys.getStats().getDroppedFrames()); + assertNothingLost(calleeKeys); // The caller removes the old key everywhere: frames keep coming. assertTrue(calleeKeys.removeDecryptionKey(CALLER, 0)); @@ -334,6 +335,18 @@ void allowedRecordingShowsFrames() throws Exception { } } + /** + * Asserts that no frame was lost: every frame dropped was a replay. A + * frame can arrive twice on a loaded machine, when a retransmission + * completes it again, and the replay protection rightly drops the copy + * of what was already decoded. + */ + static void assertNothingLost(KeyProvider keys) { + CryptoStats stats = keys.getStats(); + + assertEquals(0, stats.getDroppedFrames() - stats.getDroppedFrames(CryptoFailure.REPLAY), stats::toString); + } + private boolean canSend(String codec) { RTCRtpCapabilities capabilities = factory.getRtpSenderCapabilities(MediaType.VIDEO); diff --git a/webrtc/src/test/java/dev/onvoid/webrtc/client/E2eeTests.java b/webrtc/src/test/java/dev/onvoid/webrtc/client/E2eeTests.java index 7fb7b087c..d38cbd363 100644 --- a/webrtc/src/test/java/dev/onvoid/webrtc/client/E2eeTests.java +++ b/webrtc/src/test/java/dev/onvoid/webrtc/client/E2eeTests.java @@ -18,12 +18,14 @@ import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.Assumptions.assumeTrue; import java.nio.ByteBuffer; import java.util.Collections; -import java.util.concurrent.CompletableFuture; +import java.util.concurrent.ExecutionException; import java.util.concurrent.Executors; import java.util.concurrent.ScheduledExecutorService; import java.util.concurrent.TimeUnit; @@ -32,7 +34,9 @@ import dev.onvoid.webrtc.RTCEncodedFrameTransformer; import dev.onvoid.webrtc.e2ee.CryptoFailure; +import dev.onvoid.webrtc.e2ee.CryptoStats; import dev.onvoid.webrtc.e2ee.KeyProvider; +import dev.onvoid.webrtc.media.MediaType; import dev.onvoid.webrtc.media.video.NativeI420Buffer; import dev.onvoid.webrtc.media.video.VideoFrame; @@ -80,7 +84,9 @@ void encryptedCallDecodes() throws Exception { assertTrue(callerKeys.getStats().getEncryptedFrames() > 0); assertTrue(calleeKeys.getStats().getDecryptedFrames() >= 10); - assertEquals(0, calleeKeys.getStats().getDroppedFrames()); + // Every frame dropped was a replay, if any: see E2eeCallTests. + CryptoStats stats = calleeKeys.getStats(); + assertEquals(0, stats.getDroppedFrames() - stats.getDroppedFrames(CryptoFailure.REPLAY), stats::toString); } @Test @@ -108,6 +114,46 @@ void lateKeyRecovers() throws Exception { waitFor(() -> decoded.get() >= 5); } + @Test + void offersOnlyEncryptableVideo() throws Exception { + Peer encrypted = rtc.createPeer(PeerOptions.builder().negotiation(Negotiation.MANUAL) + .e2ee(KeyProvider.builder(CALLER).build()).build()); + Peer plain = rtc.createPeer(PeerOptions.builder().negotiation(Negotiation.MANUAL).build()); + + encrypted.addTrack(rtc.media().customVideo("encrypted")); + encrypted.addTrack(rtc.media().customAudio("encrypted-audio")); + plain.addTrack(rtc.media().customVideo("plain")); + + String encryptedOffer = await(encrypted.negotiator().createOffer()).sdp; + String plainOffer = await(plain.negotiator().createOffer()).sdp; + + assertTrue(encryptedOffer.contains(" VP8/90000"), encryptedOffer); + assertFalse(encryptedOffer.contains(" H264/90000"), encryptedOffer); + assertFalse(encryptedOffer.contains(" H265/90000"), encryptedOffer); + // Audio is left as it is. + assertTrue(encryptedOffer.contains(" opus/48000"), encryptedOffer); + + // The plain peer offers what the encrypted one leaves out. + assertTrue(plainOffer.contains(" VP8/90000"), plainOffer); + + if (hasH264()) { + assertTrue(plainOffer.contains(" H264/90000"), plainOffer); + } + } + + @Test + void unencryptableCodecsAreRefused() { + PeerImpl peer = (PeerImpl) rtc.createPeer(PeerOptions.builder().negotiation(Negotiation.MANUAL) + .e2ee(KeyProvider.builder(CALLER).build()).build()); + + assumeTrue(hasH264(), "WebRTC has no H.264 here"); + + ExecutionException e = assertThrows(ExecutionException.class, () -> await(peer.manual.preferCodecs( + Collections.singletonMap(MediaKind.VIDEO, Collections.singletonList("H264"))))); + + assertInstanceOf(ConfigurationException.class, e.getCause()); + } + @Test void e2eeTakesNoOtherTransform() { KeyProvider keys = KeyProvider.builder(CALLER).build(); @@ -132,6 +178,11 @@ void guardKeepsRecordingPolicy() { assertTrue(peer.guard(plain, "a sender").allowsPlaintextObservers()); } + private boolean hasH264() { + return rtc.factory.getRtpSenderCapabilities(MediaType.VIDEO).getCodecs().stream() + .anyMatch(codec -> "H264".equalsIgnoreCase(codec.getName())); + } + static void exchangeKeys(KeyProvider caller, KeyProvider callee) { byte[] callerKey = caller.generateKey(); byte[] calleeKey = callee.generateKey(); @@ -157,16 +208,10 @@ private Peer[] videoPair(KeyProvider callerKeys, KeyProvider calleeKeys) throws .e2ee(calleeKeys) .build()); - Peer[] peers = { caller, callee }; - - // A codec the frame format covers on every platform: macOS would - // otherwise prefer H.264, which end-to-end encryption refuses. - for (Peer peer : peers) { - await(((PeerImpl) peer).manual.preferCodecs(Collections.singletonMap( - MediaKind.VIDEO, Collections.singletonList("VP8")))); - } - - return peers; + // No codec preferences: the peers negotiate a codec end-to-end + // encryption covers by themselves, also on macOS, which would + // otherwise prefer H.264. + return new Peer[] { caller, callee }; } private void feedVideo(CustomVideo video) {