Class FrameCryptor

LiveKit's end-to-end encryption of media frames, as its clients and Element Call do it: AES-GCM with a key derived by HKDF, the first bytes of each frame in the clear and authenticated, and the IV and the key's index after the frame.

Inheritance

object

FrameCryptor

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Uniform.LiveKit

Assembly: Uniform.LiveKit.dll

Syntax

public sealed class FrameCryptor

Remarks

A frame is header ‖ AES-GCM(ciphertext ‖ tag) ‖ IV(12) ‖ 12 ‖ key index. The header is the frame's first bytes, as FrameKind says, and the additional data of AES-GCM. A raw key, e.g. one a member sent in io.element.call.encryption_keys, becomes an AES-128 key with HKDF-SHA-256, the salt LKFrameEncryptionKey and 128 zero bytes of info.

Fields

IvLength

Length of the IV after each frame.

Declaration

public const int IvLength = 12

Field Value

Type	Description
int

Salt

The salt of the key derivation.

Declaration

public static readonly byte[] Salt

Field Value

Type	Description
byte[]

TagLength

Length of the AES-GCM tag.

Declaration

public const int TagLength = 16

Field Value

Type	Description
int

Properties

CurrentIndex

The index of the key frames are encrypted with, set by SetKey(byte, ReadOnlySpan<byte>, bool).

Declaration

public byte CurrentIndex { get; }

Property Value

Type	Description
byte

Failures

Frames that did not decrypt, e.g. before their key came.

Declaration

public long Failures { get; }

Property Value

Type	Description
long

ServerTrailer

The trailer of frames an SFU injects, e.g. silence while muted, which come unencrypted; empty for none.

Declaration

public byte[] ServerTrailer { get; set; }

Property Value

Type	Description
byte[]

Methods

ClearLength(ReadOnlySpan<byte>, FrameKind)

Return how many first bytes of frame stay in the clear.

Declaration

public static int ClearLength(ReadOnlySpan<byte> frame, FrameKind kind)

Parameters

Type	Name	Description
ReadOnlySpan<byte>	frame
FrameKind	kind

Returns

Type	Description
int

Decrypt(ReadOnlySpan<byte>, FrameKind)

Return frame decrypted with the key its trailer names; null when it does not decrypt, has no such key, or is a frame the SFU injected.

Declaration

public byte[]? Decrypt(ReadOnlySpan<byte> frame, FrameKind kind)

Parameters

Type	Name	Description
ReadOnlySpan<byte>	frame
FrameKind	kind

Returns

Type	Description
byte[]

DeriveKey(ReadOnlySpan<byte>)

Return the AES-128 key of a raw key, as LiveKit derives it.

Declaration

public static byte[] DeriveKey(ReadOnlySpan<byte> rawKey)

Parameters

Type	Name	Description
ReadOnlySpan<byte>	rawKey

Returns

Type	Description
byte[]

Encrypt(ReadOnlySpan<byte>, FrameKind, uint, uint)

Return frame encrypted with the current key; the IV takes the stream's ssrc, the frame's timestamp and a counter, so it never repeats.

Declaration

public byte[] Encrypt(ReadOnlySpan<byte> frame, FrameKind kind, uint ssrc, uint timestamp)

Parameters

Type	Name	Description
ReadOnlySpan<byte>	frame
FrameKind	kind
uint	ssrc
uint	timestamp

Returns

Type	Description
byte[]

Exceptions

Type	Condition
InvalidOperationException	When no key is set.

HasKey(byte)

Return whether a key of index is set.

Declaration

public bool HasKey(byte index)

Parameters

Type	Name	Description
byte	index

Returns

Type	Description
bool

SetKey(byte, ReadOnlySpan<byte>, bool)

Set the raw key of index; with current, frames are encrypted with it from now on.

Declaration

public void SetKey(byte index, ReadOnlySpan<byte> rawKey, bool current = true)

Parameters

Type	Name	Description
byte	index
ReadOnlySpan<byte>	rawKey
bool	current