Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@ The library provides a comprehensive set of Java classes that map to the WebRTC

- **[Hardware codecs](https://jrtc.dev/guide/advanced/video-codecs#hardware-encoding)** - H.264, H.265, VP9 and AV1 on the GPU with NVENC/NVDEC, Media Foundation, VA-API and VideoToolbox, falling back to software
- **[Custom codecs](https://jrtc.dev/guide/advanced/video-codecs#adding-a-codec)** - Plug in video encoders and decoders written in Java, or limit the codecs a factory offers
- **[End-to-end encryption](https://jrtc.dev/guide/advanced/encoded-transforms)** - Read, change or drop encoded audio and video frames, like insertable streams in the browser
- **[End-to-end encryption](https://jrtc.dev/guide/advanced/end-to-end-encryption)** - SFrame (RFC 9605) with key management, key rotation and replay protection, interoperable with browsers
- **[Encoded transforms](https://jrtc.dev/guide/advanced/encoded-transforms)** - Read, change or drop encoded audio and video frames, like insertable streams in the browser
- **[Pre-encoded media](https://jrtc.dev/guide/advanced/encoded-transforms#injecting-encoded-frames)** - Send a camera's H.264 stream or a recording without re-encoding it

**Optional modules**
Expand Down
1 change: 1 addition & 0 deletions docs/.vitepress/sidebar.ts
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
items: [
{ text: 'Field Trials', link: '/advanced/field-trials' },
{ text: 'Encoded Transforms', link: '/advanced/encoded-transforms' },
{ text: 'End-to-End Encryption', link: '/advanced/end-to-end-encryption' },
{ text: 'Video Codecs', link: '/advanced/video-codecs' },
{ text: 'Audio Codecs', link: '/advanced/audio-codecs' },
],
Expand Down
10 changes: 6 additions & 4 deletions docs/guide/advanced/encoded-transforms.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ This guide explains how to read and change the encoded frames of a call as they
- Dropping frames
- What each frame tells about itself
- Asking for key frames
- End-to-end encryption as a worked example
- What end-to-end encryption needs of a transform
- Threading and performance
- Sending frames that are already encoded through an injector

Expand Down Expand Up @@ -105,10 +105,12 @@ Both do nothing for audio, and `generateKeyFrame()` nothing before the connectio

## End-to-End Encryption

A complete example with AES-GCM, on the transforms of the client API's peer options, is in [`EncryptedRecordingExample`](https://github.com/devopvoid/webrtc-java/blob/master/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/EncryptedRecordingExample.java). Two points matter for any encrypting transform:
[End-to-End Encryption](/guide/advanced/end-to-end-encryption) builds on these transforms: a `KeyProvider` makes the encryptors and decryptors, in the SFrame format of RFC 9605, and takes care of the keys of every participant, key rotation, replay protection and frames that fail. Use it rather than a transform of your own, which would have to settle all of that, and a frame format browsers can implement too. Two points matter for any encrypting transform that is written anyway:

- **Keep the codec header in the clear.** The packetizer and depacketizer read the start of each frame: a VP8 receiver finds key frames and the frame size in the first bytes. Browsers leave 10 bytes of a VP8 key frame, 3 of a VP8 delta frame and 1 of an Opus frame unencrypted, and authenticate them as associated data instead. H.264 is split at its NAL unit start codes before it is sent, so encrypting it whole breaks the packetizer; prefer VP8, VP9 or AV1 for encrypted calls, or leave the NAL unit headers in the clear.
- **Make each frame self-contained.** Frames are lost, so each needs what it takes to be decrypted, such as its IV, and a receiver must drop a frame that fails to authenticate rather than pass it on.
- **Keep the codec header in the clear.** The packetizer and depacketizer read the start of some frames: a VP8 receiver finds key frames and the frame size in the first bytes, and the AV1 packetizer splits frames into their OBUs. Browsers leave 10 bytes of a VP8 key frame, 3 of a VP8 delta frame and 1 of an Opus frame unencrypted, and authenticate them as associated data instead. H.264 is split at its NAL unit start codes before it is sent, so encrypting it whole breaks the packetizer.
- **Make each frame self-contained.** Frames are lost, so each needs what it takes to be decrypted, such as its nonce, and a receiver must drop a frame that fails to authenticate rather than pass it on.

A transform that protects what passes through it can keep observers of the encoded frames, such as a [`MediaRecorder`](/guide/media/media-recording), from seeing it in the clear by returning false from `allowsPlaintextObservers()`.

## Threading and Performance

Expand Down
Loading
Loading