webrtc_srtp (webrtc v0.1.0)

View Source

SRTP and SRTCP crypto contexts (RFC 3711, RFC 7714), keyed from DTLS-SRTP (RFC 5764).

API

A context protects or unprotects one direction of traffic: create one for what you send and one for what you receive. Contexts are plain values; every call returns the updated context, which you keep for the next packet.

  %% After the DTLS handshake, with the negotiated profile:
  Len = webrtc_srtp:key_material_length(Profile),
  %% export Len octets with label webrtc_srtp:exporter_label(), no context
  {Tx, Rx} = webrtc_srtp:dtls_contexts(Profile, Material, client, #{}),
 
  {ok, Srtp, Tx1} = webrtc_srtp:protect_rtp(RtpPacket, Tx),
  {ok, Rtp, Rx1} = webrtc_srtp:unprotect_rtp(SrtpPacket, Rx),
  {ok, Srtcp, Tx2} = webrtc_srtp:protect_rtcp(RtcpCompound, Tx1),
  {ok, Rtcp, Rx2} = webrtc_srtp:unprotect_rtcp(SrtcpPacket, Rx1).

Each function returns {error, Reason} and leaves the context unchanged when the packet is refused:

  • malformed: not an RTP/RTCP packet, or too short for the header and tag.
  • auth_failed: wrong tag (tampered packet or wrong key).
  • replay: index already accepted (receive) or already used (send, which would reuse an IV).
  • too_old: index behind the replay window.
  • key_exhausted: 2^48 SRTP or 2^31 SRTCP indices used; the session must be rekeyed (RFC 3711 §9.2).
  • too_many_streams: a packet of a new SSRC while ?MAX_RX_STREAMS SSRCs already have receive state (see forget/2).

Per-SSRC state (rollover counter, highest sequence number, replay windows, SRTCP index) is created on the first packet of an SSRC that passes authentication. Without cryptex only the payload is encrypted: the RTP header, CSRC list and header extension are authenticated in the clear (and are the AEAD associated data for GCM). MKI is not supported, as RFC 8827 §6.5 forbids it in WebRTC.

Options (new/4, from_session_keys/3, dtls_contexts/4):

  • replay_window (default 1024): SRTP replay window size, at least 64.
  • rtcp_replay_window (default 128): SRTCP replay window size, at least 64.
  • encrypt_rtcp (default true): set the SRTCP E flag and encrypt outgoing RTCP. Incoming RTCP is accepted with either flag.
  • cryptex (default false): encrypt the CSRC list and header extension of outgoing RTP too (RFC 9335; see set_cryptex/2). Incoming cryptex packets are always accepted.
  • encrypted_extensions (default []): ids of the header extension elements encrypted in this direction (RFC 6904; see set_encrypted_extensions/2). A packet sent with cryptex is not masked as well; a received cryptex packet is not unmasked.

forget/2 drops the receive state of an SSRC (a stream that ended). Its highest indices are kept, for the last ?MAX_RETIRED SSRCs forgotten, so that packets sent before cannot be replayed; a stream that comes back continues from them.

Stream state helpers: roc/3 reads the rollover counter of an SSRC, set_roc/4 sets it (a receiver joining a running stream, or keeping the ROC across a rekey) and set_rtcp_index/3 sets the next SRTCP index to send. estimate_index/3 is the RFC 3711 Appendix A index estimate used for every packet.

A context holds precomputed crypto states for the AEAD profiles: use it from one process at a time.

Summary

Functions

Build the outbound and inbound contexts from DTLS-SRTP keying material (RFC 5764 §4.2). Role is the local DTLS role: a client sends with the client write key and receives with the server one.

Estimate the packet index from SEQ, the rollover counter and the highest sequence number seen, s_l (RFC 3711 §3.3.1, Appendix A). Returns the chosen ROC value v (ROC - 1, ROC or ROC + 1) and i = 2^16 * v + SEQ. v is not reduced modulo 2^32: a negative index lies before the start of the stream and an index of 2^48 or more means the key is exhausted.

Drop the receive state (RTP and RTCP) of an SSRC. Packets of that SSRC are accepted again only with higher indices than seen.

Create a context from already derived session keys, as returned by webrtc_srtp_kdf:session_keys/3. Used for test vectors that are given as session keys (RFC 7714 §16, §17).

Create a context from a master key and salt (RFC 3711 §4.3, kdr = 0). Raises badarg on wrong key or salt length.

Rollover counter of an SSRC in the send (tx) or receive (rx) direction.

Cryptex (RFC 9335), once both sides announced it: an outbound context sends the next packets in that form, an inbound one refuses packets with header extensions or CSRCs in any other form (§6.3).

The header extension elements (by id) encrypted in this direction (RFC 6904), as negotiated with urn:ietf:params:rtp-hdrext:encrypt.

Set the rollover counter of an SSRC and reset its sequence and replay state; s_l is taken from the next packet. Use it to join a session whose ROC is signaled out of band, or to keep the ROC across a rekey (RFC 3711 §3.3.1).

Set the next SRTCP index sent for an SSRC. The index must keep increasing across a rekey (RFC 3711 §3.4); 2^31 means exhausted.

Types

ctx/0

-opaque ctx()

error_reason/0

-type error_reason() :: malformed | auth_failed | replay | too_old | key_exhausted | too_many_streams.

opts/0

-type opts() ::
          #{replay_window => pos_integer(),
            rtcp_replay_window => pos_integer(),
            encrypt_rtcp => boolean(),
            cryptex => boolean(),
            encrypted_extensions => [1..255]}.

profile/0

-type profile() :: webrtc_srtp_profile:profile().

ssrc/0

-type ssrc() :: 0..4294967295.

Functions

dtls_contexts(Profile, Material, Role, Opts)

-spec dtls_contexts(profile(), binary(), client | server, opts()) ->
                       {Outbound :: ctx(), Inbound :: ctx()}.

Build the outbound and inbound contexts from DTLS-SRTP keying material (RFC 5764 §4.2). Role is the local DTLS role: a client sends with the client write key and receives with the server one.

estimate_index(Seq, ROC, SL)

-spec estimate_index(0..65535, non_neg_integer(), 0..65535) -> {integer(), integer()}.

Estimate the packet index from SEQ, the rollover counter and the highest sequence number seen, s_l (RFC 3711 §3.3.1, Appendix A). Returns the chosen ROC value v (ROC - 1, ROC or ROC + 1) and i = 2^16 * v + SEQ. v is not reduced modulo 2^32: a negative index lies before the start of the stream and an index of 2^48 or more means the key is exhausted.

exporter_label()

-spec exporter_label() -> binary().

forget(SSRC, Srtp)

-spec forget(ssrc(), ctx()) -> ctx().

Drop the receive state (RTP and RTCP) of an SSRC. Packets of that SSRC are accepted again only with higher indices than seen.

from_session_keys(Profile, Keys, Opts)

-spec from_session_keys(profile(), webrtc_srtp_kdf:session_keys(), opts()) -> ctx().

Create a context from already derived session keys, as returned by webrtc_srtp_kdf:session_keys/3. Used for test vectors that are given as session keys (RFC 7714 §16, §17).

key_material_length(Profile)

-spec key_material_length(profile()) -> pos_integer().

new(Profile, MasterKey, MasterSalt, Opts)

-spec new(profile(), binary(), binary(), opts()) -> ctx().

Create a context from a master key and salt (RFC 3711 §4.3, kdr = 0). Raises badarg on wrong key or salt length.

profile(Srtp)

-spec profile(ctx()) -> profile().

profile_from_id(Id)

-spec profile_from_id(0..65535 | <<_:16>>) -> {ok, profile()} | {error, unsupported_profile}.

profile_id(Profile)

-spec profile_id(profile()) -> 0..65535.

protect_rtcp(Packet, Srtp)

-spec protect_rtcp(binary(), ctx()) -> {ok, binary(), ctx()} | {error, error_reason()}.

protect_rtp(Packet, Srtp)

-spec protect_rtp(binary(), ctx()) -> {ok, binary(), ctx()} | {error, error_reason()}.

roc(Dir, SSRC, Srtp)

-spec roc(tx | rx, ssrc(), ctx()) -> {ok, non_neg_integer()} | error.

Rollover counter of an SSRC in the send (tx) or receive (rx) direction.

set_cryptex(On, Srtp)

-spec set_cryptex(boolean(), ctx()) -> ctx().

Cryptex (RFC 9335), once both sides announced it: an outbound context sends the next packets in that form, an inbound one refuses packets with header extensions or CSRCs in any other form (§6.3).

set_encrypted_extensions(Ids, Srtp)

-spec set_encrypted_extensions([1..255], ctx()) -> ctx().

The header extension elements (by id) encrypted in this direction (RFC 6904), as negotiated with urn:ietf:params:rtp-hdrext:encrypt.

set_roc(Dir, SSRC, ROC, Srtp)

-spec set_roc(tx | rx, ssrc(), 0..4294967295, ctx()) -> ctx().

Set the rollover counter of an SSRC and reset its sequence and replay state; s_l is taken from the next packet. Use it to join a session whose ROC is signaled out of band, or to keep the ROC across a rekey (RFC 3711 §3.3.1).

set_rtcp_index(SSRC, Index, Srtp)

-spec set_rtcp_index(ssrc(), 0..2147483648, ctx()) -> ctx().

Set the next SRTCP index sent for an SSRC. The index must keep increasing across a rekey (RFC 3711 §3.4); 2^31 means exhausted.

split_dtls_keying_material(Profile, Bin)

-spec split_dtls_keying_material(profile(), binary()) ->
                                    {ClientKey :: binary(),
                                     ClientSalt :: binary(),
                                     ServerKey :: binary(),
                                     ServerSalt :: binary()}.

supported_profiles()

-spec supported_profiles() -> [profile()].

unprotect_rtcp(Packet, Srtp)

-spec unprotect_rtcp(binary(), ctx()) -> {ok, binary(), ctx()} | {error, error_reason()}.

unprotect_rtp(Packet, Srtp)

-spec unprotect_rtp(binary(), ctx()) -> {ok, binary(), ctx()} | {error, error_reason()}.