Skip to content
Open
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
5 changes: 5 additions & 0 deletions .changeset/sender-key-index-observer.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"client-sdk-android": patch
---

Media frame cryptors now follow the key provider's current key index, matching the JavaScript and Swift SDKs. `BaseKeyProvider` implements the new `KeyIndexObservable` contract: installing a shared key moves the current index, `setCurrentKeyIndex` re-points live senders, and `getLatestKeyIndex` returns the current index. Custom `KeyProvider` implementations can opt into live re-pointing by implementing `KeyIndexObservable`. Behavior change: in non-shared key mode `setKey` no longer moves the sender index — the key may belong to a remote participant — use `setCurrentKeyIndex` to switch the local one.
1 change: 1 addition & 0 deletions livekit-android-sdk/detekt-baseline-release.xml
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@
<ID>SwallowedException:TextureViewRenderer.kt$TextureViewRenderer$e: NotFoundException</ID>
<ID>TooManyFunctions:CommunicationWorkaround.kt$CommunicationWorkaroundImpl : CommunicationWorkaround</ID>
<ID>TooManyFunctions:E2EEManager.kt$E2EEManager</ID>
<ID>TooManyFunctions:KeyProvider.kt$BaseKeyProvider : KeyProviderKeyIndexObservable</ID>
<ID>TooManyFunctions:LKLog.kt$LKLog$Companion</ID>
<ID>TooManyFunctions:LocalParticipant.kt$LocalParticipant : ParticipantOutgoingDataStreamManagerRpcManager</ID>
<ID>TooManyFunctions:LocalVideoTrack.kt$LocalVideoTrack : VideoTrack</ID>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,8 @@ import io.livekit.android.room.track.RemoteVideoTrack
import io.livekit.android.room.track.Track
import io.livekit.android.room.track.TrackPublication
import io.livekit.android.util.LKLog
import io.livekit.android.webrtc.peerconnection.RTCThreadToken
import io.livekit.android.webrtc.peerconnection.executeOnRTCThread
import livekit.LivekitModels.Encryption
import livekit.org.webrtc.FrameCryptor
import livekit.org.webrtc.FrameCryptor.FrameCryptionState
Expand All @@ -40,16 +42,18 @@ import livekit.org.webrtc.FrameCryptorFactory
import livekit.org.webrtc.PeerConnectionFactory
import livekit.org.webrtc.RtpReceiver
import livekit.org.webrtc.RtpSender
import java.util.Collections

class E2EEManager
@AssistedInject
constructor(
@Assisted val keyProvider: KeyProvider,
val peerConnectionFactory: PeerConnectionFactory,
dataPacketCryptorManagerFactory: DataPacketCryptorManager.Factory,
private val rtcThreadToken: RTCThreadToken,
) {
private var room: Room? = null
private val frameCryptors = mutableMapOf<Pair<String, Participant.Identity>, FrameCryptor>()
private val frameCryptors = Collections.synchronizedMap(mutableMapOf<Pair<String, Participant.Identity>, FrameCryptor>())
private var algorithm: FrameCryptorAlgorithm = FrameCryptorAlgorithm.AES_GCM
private lateinit var emitEvent: (roomEvent: RoomEvent) -> Unit?

Expand All @@ -58,9 +62,11 @@ constructor(
var enabled: Boolean = false
set(value) {
field = value
for (item in frameCryptors.entries) {
val frameCryptor = item.value
frameCryptor.isEnabled = enabled
synchronized(frameCryptors) {
for (item in frameCryptors.entries) {
val frameCryptor = item.value
frameCryptor.isEnabled = enabled
}
}
}

Expand Down Expand Up @@ -96,6 +102,7 @@ constructor(
this.enabled = true
this.room = room
this.emitEvent = emitEvent
observeKeyIndex()
this.room?.localParticipant?.trackPublications?.forEach { item ->
val participant = this.room!!.localParticipant
val publication = item.value
Expand Down Expand Up @@ -140,12 +147,12 @@ constructor(
fun removeSubscribedTrack(track: Track, publication: TrackPublication, participant: RemoteParticipant, room: Room) {
val trackId = publication.sid
val participantId = participant.identity
val frameCryptor = frameCryptors.get(trackId to participantId)
if (frameCryptor != null) {
frameCryptor.isEnabled = false
frameCryptor.dispose()
frameCryptors.remove(trackId to participantId)
}
// Remove before disposing: a loop over frameCryptors (key-index re-stamp,
// enabled toggle, cleanup) must never see a disposed cryptor, and only the
// caller that removed the entry disposes it.
val frameCryptor = frameCryptors.remove(trackId to participantId) ?: return
frameCryptor.isEnabled = false
frameCryptor.dispose()
}

fun addPublishedTrack(track: Track, publication: TrackPublication, participant: LocalParticipant, room: Room) {
Expand Down Expand Up @@ -175,14 +182,21 @@ constructor(
fun removePublishedTrack(track: Track, publication: TrackPublication, participant: LocalParticipant, room: Room) {
val trackId = publication.sid
val participantId = participant.identity
val frameCryptor = frameCryptors.get(trackId to participantId)
if (frameCryptor != null) {
frameCryptor.isEnabled = false
frameCryptor.dispose()
frameCryptors.remove(trackId to participantId)
}
// Remove before disposing: a loop over frameCryptors (key-index re-stamp,
// enabled toggle, cleanup) must never see a disposed cryptor, and only the
// caller that removed the entry disposes it.
val frameCryptor = frameCryptors.remove(trackId to participantId) ?: return
frameCryptor.isEnabled = false
frameCryptor.dispose()
}

/** The index local senders stamp with: the observable provider's
* [KeyIndexObservable.currentKeyIndex] when it opts in, else the legacy
* latest-index lookup. */
private fun localSenderKeyIndex(participantId: String): Int =
(keyProvider as? KeyIndexObservable)?.currentKeyIndex
?: keyProvider.getLatestKeyIndex(participantId)

private fun e2eeStateFromFrameCryptoState(state: FrameCryptionState?): E2EEState {
return when (state) {
FrameCryptionState.NEW -> E2EEState.NEW
Expand All @@ -205,9 +219,13 @@ constructor(
keyProvider.rtcKeyProvider,
)

frameCryptors[trackId to participantId] = frameCryptor
frameCryptor.isEnabled = enabled
frameCryptor.keyIndex = keyProvider.getLatestKeyIndex(participantId.value)
// Insert and stamp under the same monitor the key-index re-stamp holds, so a
// rotation landing mid-setup can't be overwritten by a stale index read here.
synchronized(frameCryptors) {
frameCryptors[trackId to participantId] = frameCryptor
frameCryptor.isEnabled = enabled
frameCryptor.keyIndex = localSenderKeyIndex(participantId.value)
}
return frameCryptor
}

Expand All @@ -220,9 +238,13 @@ constructor(
keyProvider.rtcKeyProvider,
)

frameCryptors[trackId to participantId] = frameCryptor
frameCryptor.isEnabled = enabled
frameCryptor.keyIndex = keyProvider.getLatestKeyIndex(participantId.value)
// Receivers read the key index from each frame's trailer; locked for
// consistency with addRtpSender (one insert-and-configure step per cryptor).
synchronized(frameCryptors) {
frameCryptors[trackId to participantId] = frameCryptor
frameCryptor.isEnabled = enabled
frameCryptor.keyIndex = keyProvider.getLatestKeyIndex(participantId.value)
}
return frameCryptor
}

Expand All @@ -242,22 +264,50 @@ constructor(
LKLog.d { "ratchetSharedKey: newKey: $newKey" }
}

/**
* Re-stamps the frame cryptors of every track the local participant has
* already published with the provider's latest key index. Runs on the
* RTC thread like all other frame cryptor calls.
*/
internal fun setSenderKeyIndex(keyIndex: Int) {
executeOnRTCThread(rtcThreadToken) {
val localIdentity = room?.localParticipant?.identity ?: return@executeOnRTCThread
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.

}
}
}
}
}

private fun observeKeyIndex() {
(keyProvider as? KeyIndexObservable)?.addKeyIndexObserver(this) { index ->
setSenderKeyIndex(index)
}
}

internal fun cleanup() {
for (frameCryptor in frameCryptors.values) {
frameCryptor.dispose()
(keyProvider as? KeyIndexObservable)?.removeKeyIndexObserver(this)
synchronized(frameCryptors) {
for (frameCryptor in frameCryptors.values) {
frameCryptor.dispose()
}
frameCryptors.clear()
}
frameCryptors.clear()
}

internal fun dispose() {
(keyProvider as? KeyIndexObservable)?.removeKeyIndexObserver(this)
dataPacketCryptorManager.dispose()
}

fun encrypt(byteArray: ByteArray): EncryptedPacket? {
val participantId = room?.localParticipant?.identity ?: Participant.Identity("")
return dataPacketCryptorManager.encrypt(
participantId,
keyIndex = keyProvider.getLatestKeyIndex(participantId.value),
keyIndex = localSenderKeyIndex(participantId.value),
payload = byteArray,
)
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,9 @@ internal const val defaultMagicBytes = "LK-ROCKS"
internal const val defaultRatchetWindowSize = 16
internal const val defaultFailureTolerance = -1
internal const val defaultKeyRingSize = 16

// Matches libwebrtc's MAX_KEYRING_SIZE — the native provider caps the ring here.
internal const val maxKeyRingSize = 256
internal const val defaultDiscardFrameWhenCryptorNotReady = false
internal val defaultKeyDerivationAlgorithm = FrameCryptorKeyDerivationAlgorithm.PBKDF2

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,34 @@ interface KeyProvider {
var enableSharedKey: Boolean
}

/**
* Implemented by [KeyProvider]s that track the key index the local
* participant encrypts with and can push changes to observers.
*
* [E2EEManager] subscribes so the frame cryptors of media tracks that are
* already published get re-stamped whenever the index changes. Receivers
* are unaffected: they read the index from each incoming frame.
*/
interface KeyIndexObservable {

/**
* The key index the local participant encrypts with.
*/
val currentKeyIndex: Int

/**
* Registers [observer] under [owner]; [removeKeyIndexObserver] with the
* same owner detaches it. The observer is invoked with the latest index
* on every change and may be called from any thread.
*/
fun addKeyIndexObserver(owner: Any, observer: (keyIndex: Int) -> Unit)

/**
* Detaches the observer previously registered under [owner].
*/
fun removeKeyIndexObserver(owner: Any)
}

class BaseKeyProvider(
ratchetSalt: String = defaultRatchetSalt,
uncryptedMagicBytes: String = defaultMagicBytes,
Expand All @@ -51,9 +79,23 @@ class BaseKeyProvider(
keyRingSize: Int = defaultKeyRingSize,
discardFrameWhenCryptorNotReady: Boolean = defaultDiscardFrameWhenCryptorNotReady,
keyDerivationAlgorithm: FrameCryptorKeyDerivationAlgorithm = defaultKeyDerivationAlgorithm,
) : KeyProvider {
) : KeyProvider, KeyIndexObservable {

// The native provider clamps the requested ring size the same way
// (<= 0 falls back to the default, > 256 caps at 256); the local index
// must wrap by the effective size, not the requested one.
private val effectiveKeyRingSize: Int =
if (keyRingSize <= 0) defaultKeyRingSize else minOf(keyRingSize, maxKeyRingSize)

private val keyIndexStateLock = Any()
private val keyIndexDispatchLock = Any()
private val keyIndexObservers = mutableMapOf<Any, (Int) -> Unit>()

@Volatile
private var _currentKeyIndex: Int = 0

private val latestSetIndex = mutableMapOf<String, Int>()
override val currentKeyIndex: Int
get() = _currentKeyIndex

override val rtcKeyProvider: FrameCryptorKeyProvider = FrameCryptorFactory.createFrameCryptorKeyProvider(
enableSharedKey,
Expand All @@ -66,8 +108,24 @@ class BaseKeyProvider(
keyDerivationAlgorithm,
)

/**
* Installs the shared key at [keyIndex] and makes it the local encryption
* index. A negative [keyIndex] installs into the current slot without
* moving it.
*/
override fun setSharedKey(key: String, keyIndex: Int?): Boolean {
return rtcKeyProvider.setSharedKey(keyIndex ?: 0, key.toByteArray())
// Resolve a negative index against this provider's current index, not
// the native handler's — the native pointer only moves on key installs
// and can diverge from this one after setCurrentKeyIndex.
val index = keyIndex ?: 0
return rtcKeyProvider.setSharedKey(
if (index >= 0) index else currentKeyIndex,
key.toByteArray(),
).also { succeeded ->
if (succeeded && index >= 0) {
setCurrentKeyIndex(index)
}
}
}

override fun ratchetSharedKey(keyIndex: Int?): ByteArray {
Expand All @@ -94,10 +152,7 @@ class BaseKeyProvider(
return
}

val keyIndex = keyIndex ?: 0
latestSetIndex[participantId] = keyIndex

rtcKeyProvider.setKey(participantId, keyIndex, key.toByteArray())
rtcKeyProvider.setKey(participantId, keyIndex ?: 0, key.toByteArray())
}

override fun ratchetKey(participantId: String, keyIndex: Int?): ByteArray {
Expand All @@ -112,7 +167,43 @@ class BaseKeyProvider(
rtcKeyProvider.setSifTrailer(trailer)
}

/**
* Switches the local participant's encryption to the key at [keyIndex]
* (modulo the effective key ring size: the default for a size <= 0,
* capped at 256, matching the native provider).
*
* Takes effect immediately for the media tracks already published and
* for every data packet sent afterwards. Receivers are unaffected: they
* read the index from each frame.
*/
fun setCurrentKeyIndex(keyIndex: Int) {
Comment thread
devin-ai-integration[bot] marked this conversation as resolved.
Resolved
val observers = synchronized(keyIndexStateLock) {
_currentKeyIndex = keyIndex.mod(effectiveKeyRingSize)
keyIndexObservers.values.toList()
}
// Dispatch is serialized and each pass re-reads the newest index,
// so overlapping rotations can't leave senders on a stale index.
synchronized(keyIndexDispatchLock) {
val latest = _currentKeyIndex
observers.forEach { it(latest) }
}
}

/**
* The key index outgoing media frames and data packets are stamped with.
* In non-shared key mode [setKey] does not move it — the key may belong
* to a remote participant — so switch the local one with
* [setCurrentKeyIndex].
*/
override fun getLatestKeyIndex(participantId: String): Int {
return latestSetIndex[participantId] ?: 0
return currentKeyIndex
}

override fun addKeyIndexObserver(owner: Any, observer: (keyIndex: Int) -> Unit) {
synchronized(keyIndexStateLock) { keyIndexObservers[owner] = observer }
}

override fun removeKeyIndexObserver(owner: Any) {
synchronized(keyIndexStateLock) { keyIndexObservers.remove(owner) }
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -332,6 +332,20 @@ constructor(
* Options for end-to-end encryption. Must be setup prior to [connect].
*
* If null, e2ee will be disabled.
*
* Example — shared-key encryption with key-index rotation:
* ```
* val keyProvider = BaseKeyProvider()
* keyProvider.setSharedKey("my-secret", keyIndex = 0)
* room.e2eeOptions = E2EEOptions(keyProvider = keyProvider)
* room.connect(url, token)
*
* // Later, after distributing the next key out-of-band:
* keyProvider.setSharedKey("next-secret", keyIndex = 1)
* keyProvider.setCurrentKeyIndex(1) // already-published senders follow
* ```
* Custom providers can implement [io.livekit.android.e2ee.KeyIndexObservable]
* to opt into the same live re-stamping.
*/
var e2eeOptions: E2EEOptions? = null

Expand Down
Loading