Encryptor
Encrypts outgoing media frames using the DAVE protocol.
An Encryptor operates on a single send stream. Once a KeyRatchet is set via
setKeyRatchet, each call to encrypt advances the ratchet and produces an
authenticated ciphertext. Before a ratchet is available (e.g. while the MLS group is
being established), call setPassthroughMode(true) to forward frames unmodified.
local enc = Dave.Encryptor.new()
enc:assignSsrcToCodec(ssrc, Dave.sys.codec.opus)enc:setKeyRatchet(session:getKeyRatchet(selfUserId))
local encrypted = enc:encrypt(Dave.sys.mediaType.audio, ssrc, rawFrame)Summary
Properties
Encryptor.handle :: Sys.EncryptorHandleEncryptor.versionChangedClosure :: FFIPointerEncryptor.versionChangedCallbackRef :: { current: (() -> ())? }Methods
Encryptor:setKeyRatchet(keyRatchet: KeyRatchet.KeyRatchet)Encryptor:setPassthroughMode(enabled: boolean)Encryptor:hasKeyRatchet() → booleanEncryptor:isPassthroughMode() → booleanEncryptor:assignSsrcToCodec(ssrc: number, codec: number)Encryptor:getProtocolVersion() → numberEncryptor:getMaxCiphertextByteSize(mediaType: number, frameSize: number) → numberEncryptor:encrypt(mediaType: number, ssrc: number, frame: buffer) → bufferEncryptor:setProtocolVersionChangedCallback(callback: () -> ())Encryptor:getStats(mediaType: number) → EncryptorStatsEncryptor:destroy()Functions
Encryptor.new() → EncryptorProperties
Section titled “Properties”handle
Section titled “handle”versionChangedClosure
Section titled “versionChangedClosure”versionChangedCallbackRef
Section titled “versionChangedCallbackRef”{ current: (() -> ())? } }
Methods
Section titled “Methods”setKeyRatchet
Section titled “setKeyRatchet”Encryptor : setKeyRatchet ( keyRatchet ) -> ()
Sets the key ratchet used for encryption. Derives fresh keys on each frame from the
given ratchet. Obtain a ratchet from Session:getKeyRatchet(selfUserId) after the
MLS group has been established.
Parameters
| keyRatchet: KeyRatchet |
setPassthroughMode
Section titled “setPassthroughMode”Encryptor : setPassthroughMode ( enabled ) -> ()
Enables or disables passthrough mode. When enabled, frames are forwarded to encrypt
callers unchanged without consuming key material. Use this while the MLS group is not
yet ready.
Parameters
| enabled: boolean |
hasKeyRatchet
Section titled “hasKeyRatchet”Encryptor : hasKeyRatchet ( ) -> boolean
Returns true if a key ratchet has been set on this encryptor.
Returns
| boolean |
isPassthroughMode
Section titled “isPassthroughMode”Encryptor : isPassthroughMode ( ) -> boolean
Returns true if the encryptor is currently in passthrough mode.
Returns
| boolean |
assignSsrcToCodec
Section titled “assignSsrcToCodec”Encryptor : assignSsrcToCodec ( ssrc , codec ) -> ()
Associates ssrc with codec so the encryptor knows how to frame-parse the stream.
Must be called for each SSRC before the first encrypt call for that stream.
codec should be a value from Dave.sys.codec.
getProtocolVersion
Section titled “getProtocolVersion”Encryptor : getProtocolVersion ( ) -> number
Returns the DAVE protocol version this encryptor is currently operating at.
Returns
| number |
getMaxCiphertextByteSize
Section titled “getMaxCiphertextByteSize”Encryptor : getMaxCiphertextByteSize ( mediaType , frameSize ) -> number
Returns the maximum number of bytes that encrypt may write for a plaintext frame of
frameSize bytes on mediaType. Use this to pre-allocate output buffers or to
validate output size expectations.
encrypt
Section titled “encrypt”Encryptor : encrypt ( mediaType , ssrc , frame ) -> buffer
Encrypts frame and returns the ciphertext as a new buffer. The SSRC must have been
registered via assignSsrcToCodec. Logs an error and halts the calling coroutine on
any non-success result code (missing ratchet, too many retries, etc.).
setProtocolVersionChangedCallback
Section titled “setProtocolVersionChangedCallback”Encryptor : setProtocolVersionChangedCallback ( callback ) -> ()
Registers a callback that fires whenever the encryptor’s protocol version changes (e.g. after the voice server negotiates an upgrade). Replaces any previously set callback without re-registering with the library.
Parameters
| callback: () -> () |
getStats
Section titled “getStats”Encryptor : getStats ( mediaType ) -> EncryptorStats
Returns a snapshot of encryption statistics for mediaType. Statistics are cumulative
since the encryptor was created. mediaType should be a value from Dave.sys.mediaType.
Parameters
| mediaType: number |
Returns
| EncryptorStats |
destroy
Section titled “destroy”Encryptor : destroy ( ) -> ()
Destroys the encryptor and frees all associated libdave resources. The encryptor must not be used after this call.
Functions
Section titled “Functions”Encryptor . new ( ) -> Encryptor
Constructs a new Encryptor. Registers a stable forwarder closure for the
protocol-version-changed callback so the Luau handler can be swapped later via
setProtocolVersionChangedCallback.
Returns
| Encryptor |