Skip to content

Follow key provider key index on media frame cryptors - #1042

Open
tangowhisky-dev wants to merge 6 commits into
livekit:mainfrom
tangowhisky-dev:e2ee-sender-key-index-observer
Open

tangowhisky-dev wants to merge 6 commits into
livekit:mainfrom
tangowhisky-dev:e2ee-sender-key-index-observer

Conversation

@tangowhisky-dev

@tangowhisky-dev tangowhisky-dev commented Oct 22, 2026 •

Copy link
Copy Markdown

Supersedes #1039 — ports the approach merged in client-sdk-swift#1157 to Android.

Problem

addRtpSender stamps a sender's FrameCryptor.keyIndex once at creation and never updates it. Apps that rotate keys into different key-ring slots (e.g. per-epoch MLS key rings in E2EE deployments) can update live data packets via setSharedKey(key, index), but media senders keep stamping the old index — receivers hit MISSING_KEY and drop frames. There is no public API to re-point live senders.

Approach

Mirrors the Swift design rather than adding a setKeyIndex(participant) API (whose identity parameter let a remote identity redirect local encryption — the review concern on the earlier Swift PR #1156).

KeyIndexObservable — new opt-in contract for KeyProviders that track the local encryption index:

interface KeyIndexObservable {
    val currentKeyIndex: Int
    fun addKeyIndexObserver(owner: Any, observer: (keyIndex: Int) -> Unit)
    fun removeKeyIndexObserver(owner: Any)
}

BaseKeyProvider implements it — currentKeyIndex is the single source of truth:

  • setSharedKey(key, index) moves it (parity with JS SDK setSharedKey behavior merged in client-sdk-js#1830/#1831)
  • New setCurrentKeyIndex(index) exposes it directly (ring-size modulo)
  • getLatestKeyIndex() returns it — senders stamp at creation, data packets pick it up per-send
  • Observer dispatch is serialized and re-reads the latest index, so overlapping rotations can't leave senders stale

E2EEManager subscribes internally and re-stamps the frame cryptors of already-published local tracks on the RTC thread (via executeOnRTCThread, honoring the SDK's threading rule). Receivers are untouched — they read the index from each frame's trailer.

Behavior change

In non-shared key mode, setKey() no longer moves the sender index — the key may belong to a remote participant, so it must not redirect local encryption. Apps switching the local index should call setCurrentKeyIndex(). This matches the Swift change.

Custom KeyProvider implementations (e.g. ones that bypass BaseKeyProvider to hand raw key bytes to the RTC provider) opt into live re-pointing by implementing KeyIndexObservable.

Test plan

  • FrameCryptorKeyIndexTest (new, 7 tests): shared-key install moves index, setCurrentKeyIndex modulo wrap, non-shared setKey does not move index, observer add/remove, new senders stamp current index, existing senders follow changes, receivers not re-stamped
  • Existing e2ee tests pass (DataPacketCryptorMockE2ETest, DataTrackCryptorTest)
  • :livekit-android-sdk:detektRelease, spotlessCheck clean

Ports the semantics merged in livekit/client-sdk-swift#1157 to Android,
superseding the approach in livekit#1039.

BaseKeyProvider now implements the new KeyIndexObservable contract:
the current key index is the single source of truth for what the local
participant encrypts with. Installing a shared key moves the index and
setCurrentKeyIndex() exposes it directly; getLatestKeyIndex() returns
it for both media senders and data packets.

E2EEManager subscribes to the provider and re-stamps the frame cryptors
of already-published local tracks on the RTC thread whenever the index
changes, and stamps new senders at creation. Receivers are unaffected:
they read the index from each incoming frame. Cryptor map iteration is
synchronized, and a serialized dispatch that re-reads the latest index
prevents overlapping rotations from leaving senders stale.

Behavior change: in non-shared key mode setKey() no longer moves the
sender index, since the key may belong to a remote participant. Use
setCurrentKeyIndex() to switch the local one.

Custom KeyProvider implementations opt into live re-pointing by
implementing KeyIndexObservable.
@changeset-bot

changeset-bot Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 0fdcffa

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
client-sdk-android Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

devin-ai-integration[bot]

This comment was marked as resolved.

- setCurrentKeyIndex: Math.floorMod -> Int.mod (kotlin stdlib) —
  floorMod is API 24+ and would NoSuchMethodError on API 21-23
  devices during E2EEOptions(sharedKey) setup
- Room.e2eeOptions KDoc: short shared-key rotation example covering
  setCurrentKeyIndex and the KeyIndexObservable opt-in for custom
  providers
@tangowhisky-dev

Copy link
Copy Markdown
Author

@davidliu can you please look into this. Merging it would remove issues associated with E2EE key rotations.
Thanks

@xianshijing-lk

Copy link
Copy Markdown
Contributor

@changt , could you please help review this PR ?

addRtpSender/addRtpReceiver: hold synchronized(frameCryptors) across the
insert + initial keyIndex stamp so a concurrent rotation can't be
overwritten by a stale index read.

removePublishedTrack/removeSubscribedTrack: remove the map entry before
disposing so map iterations (re-stamp, enabled toggle, cleanup) can never
reach a disposed FrameCryptor, which throws IllegalStateException. Only
the caller that removed the entry disposes it.

setSenderKeyIndex: read room.localParticipant.identity on the RTC thread.

Adds three FrameCryptorKeyIndexTest cases covering the stamp race and
use-after-dispose on sender and receiver paths; all three fail against
the unfixed E2EEManager.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@tangowhisky-dev

Copy link
Copy Markdown
Author

Thanks, good catch. The initial stamp in addRtpSender was put → read latest index → set as separate steps, so a rotation landing between the read and the set could overwrite the re-stamped index with a stale one. Fixed in the latest commit:

  • addRtpSender / addRtpReceiver: insert, isEnabled and keyIndex now run inside synchronized(frameCryptors), the monitor the re-stamp loop holds, so either ordering ends on the latest index. Receivers read the index from the frame trailer, so the receiver change is for consistency only.
  • While there, I fixed a related window in removePublishedTrack / removeSubscribedTrack: they disposed a cryptor before removing it from the map, so a concurrent loop (the new re-stamp, the enabled toggle, or cleanup()) could call into a disposed FrameCryptor, which throws IllegalStateException. They now remove first and dispose only what they removed. That window predates this PR, but the new re-stamp loop makes it easier to hit.
  • The room read in setSenderKeyIndex now happens on the RTC thread.

I added three tests to FrameCryptorKeyIndexTest, covering the stamp race and use-after-dispose on both the sender and receiver paths — verified by mutation: all three fail against the unfixed E2EEManager.

Could a maintainer also approve the CI workflows for this fork PR? No checks have run on it yet.

@devin-ai-integration devin-ai-integration Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

Newer findings are available below. Devin Review posted a newer report on this PR, in addition to the findings presented here.

Devin Review found 4 new potential issues.

3 flags not posted on this PR by your GitHub settings — view them in Devin Review. (Configure)

Devin Review

synchronized(frameCryptors) {
for ((key, frameCryptor) in frameCryptors) {
if (key.second == localIdentity) {
frameCryptor.keyIndex = keyIndex

@devin-ai-integration devin-ai-integration Bot Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Key rotation can stall strict receivers

During a live rotation, native encryptFrame can select the old key but label the frame with the new index. A receiver with failureTolerance = 0 stops decrypting subsequent frames if ratcheting cannot recover that frame.

Learn more

The SDK pins WebRTC milestone 150 in the dependency catalog. In the corresponding native encryptFrame implementation, frame encryption runs on a worker separate from the SDK's RTC executor. The worker reads the mutable key index separately for the key lookup and the frame trailer. The Kotlin monitor does not cover that worker. On the receiving side, decryptFrame skips subsequent frames after the failure threshold marks the key handler invalid and the decryption attempt fails.

Example: A sender selects the key in slot 0 for one frame, then rotates to an unrelated key in slot 1 before the worker writes the trailer. A receiver with both keys tries slot 1 against a frame encrypted using slot 0. If that receiver has a zero failure tolerance and ratcheting fails, correctly encrypted slot-1 frames also stop decrypting until the key handler is reset.

Recommended fix: Fix or upgrade the WebRTC dependency so each outgoing frame takes one synchronized snapshot of the index and uses it for the lookup and trailer. Exercise a live rotation with both slots provisioned in a native integration test.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. This one is in native code: encryptFrame reads key_index_ three times without mutex_, so a concurrent SetKeyIndex can split the slot lookup from the trailer byte. The race predates this PR, but it only becomes reachable now that a sender's index can move mid-call.

I don't think it should block this PR. Both slots already hold valid keys when the index moves, because setSharedKey installs the key before the index changes. So the worst case is one frame the receiver can't decrypt per rotation. With the default failureTolerance = -1, that never marks the key invalid, and the next frame decrypts normally.

The fix is to snapshot the index under the lock once at the top of encryptFrame. I'll send that to livekit/libwebrtc as a separate change rather than work around it from Kotlin.

BaseKeyProvider.setSharedKey: a negative index now installs into the
native provider's current slot without moving currentKeyIndex, matching
SetKeyFromMaterial's key_index >= 0 behavior; no observer dispatch, so
senders are not re-stamped for an index that did not move.

BaseKeyProvider.setCurrentKeyIndex: wrap by the effective ring size
(<= 0 -> default 16, > 256 -> MAX_KEYRING_SIZE) so the Kotlin index
agrees with the clamped native ring. The raw size still reaches native,
which applies the same clamp itself.

E2EEManager: new senders and data packets stamp with
KeyIndexObservable.currentKeyIndex when the provider opts in, falling
back to getLatestKeyIndex, so they can't disagree with observer-driven
re-stamps. Receivers keep the per-participant lookup.

Adds four FrameCryptorKeyIndexTest cases (negative index, zero and
oversized ring sizes, divergent observable provider); each fails against
the unfixed code.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
devin-ai-integration[bot]

This comment was marked as resolved.

The native key handler's current pointer only moves on key installs
with a non-negative index, so after setCurrentKeyIndex it can diverge
from this provider's index. A negative setSharedKey index then installed
the replacement into a slot senders were not using.

Resolve negative indexes against currentKeyIndex before the native
call; the resolved value is non-negative, so the install also moves the
native pointer back in sync. The sender index stays unchanged and no
re-stamp is dispatched.

Adds negativeSharedKeyIndexInstallsAtKotlinCurrentSlotAfterSwitch,
which installs two slots, switches back to the first, and verifies the
replacement write targets that slot.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@tangowhisky-dev

Copy link
Copy Markdown
Author

@changt can you please relook into proposed changes. This one is becoming a blocker for my app as it adversly affects the UX.
Thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants