* This example shows how to: *
- * 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/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 5f011b32d..34b85f921 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;
@@ -161,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, options.receiveTransform);
- this.manual = new ManualNegotiation(this, options, chain, steps, tracks, new CodecPreferences(this));
+ this.tracks = new RemoteTracks(this, receiveTransforms(options));
+ this.manual = new ManualNegotiation(this, options, chain, steps, tracks, codecs);
this.signaling = new SignalingLink(this, options.signaling);
rtc.track(connected, events);
@@ -317,7 +320,7 @@ private SenderImpl addSender(LocalTrackImpl local, List ids, List {
- try {
- transform.transform(frame);
- }
- catch (Throwable e) {
- frame.drop();
+ return new RTCEncodedFrameTransformer() {
- if (reported.compareAndSet(false, true)) {
- deliverError(new WebRtcException("The transform of " + owner
- + " failed, and drops each frame it fails on", e));
+ @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));
+ }
}
}
+
+ @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..e0891e469 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,37 @@ 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}.
+ *
+ * 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
+ * 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 +430,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..358ad386b
--- /dev/null
+++ b/webrtc/src/main/java/dev/onvoid/webrtc/e2ee/KeyProvider.java
@@ -0,0 +1,698 @@
+/*
+ * 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));
+ }
+
+ /**
+ * 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
+ * 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