Skip to content

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

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

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

Conversation

@tangowhisky-dev

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: 50d9894

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

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.

1 participant