Repository navigation
Follow key provider key index on media frame cryptors - #1042
tangowhisky-dev wants to merge 6 commits into
Conversation
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 detectedLatest commit: 0fdcffa The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
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 |
- 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
|
@davidliu can you please look into this. Merging it would remove issues associated with E2EE key rotations. |
|
@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>
|
Thanks, good catch. The initial stamp in
I added three tests to Could a maintainer also approve the CI workflows for this fork PR? No checks have run on it yet. |
There was a problem hiding this comment.
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)
| synchronized(frameCryptors) { | ||
| for ((key, frameCryptor) in frameCryptors) { | ||
| if (key.second == localIdentity) { | ||
| frameCryptor.keyIndex = keyIndex |
There was a problem hiding this comment.
🔴 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
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>
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>
|
@changt can you please relook into proposed changes. This one is becoming a blocker for my app as it adversly affects the UX. |
Supersedes #1039 — ports the approach merged in client-sdk-swift#1157 to Android.
Problem
addRtpSenderstamps a sender'sFrameCryptor.keyIndexonce 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 viasetSharedKey(key, index), but media senders keep stamping the old index — receivers hitMISSING_KEYand 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 forKeyProviders that track the local encryption index:BaseKeyProviderimplements it —currentKeyIndexis the single source of truth:setSharedKey(key, index)moves it (parity with JS SDKsetSharedKeybehavior merged in client-sdk-js#1830/#1831)setCurrentKeyIndex(index)exposes it directly (ring-size modulo)getLatestKeyIndex()returns it — senders stamp at creation, data packets pick it up per-sendE2EEManagersubscribes internally and re-stamps the frame cryptors of already-published local tracks on the RTC thread (viaexecuteOnRTCThread, 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 callsetCurrentKeyIndex(). This matches the Swift change.Custom
KeyProviderimplementations (e.g. ones that bypassBaseKeyProviderto hand raw key bytes to the RTC provider) opt into live re-pointing by implementingKeyIndexObservable.Test plan
FrameCryptorKeyIndexTest(new, 7 tests): shared-key install moves index,setCurrentKeyIndexmodulo wrap, non-sharedsetKeydoes not move index, observer add/remove, new senders stamp current index, existing senders follow changes, receivers not re-stampede2eetests pass (DataPacketCryptorMockE2ETest,DataTrackCryptorTest):livekit-android-sdk:detektRelease,spotlessCheckclean