# `XMediaLib.Srtp`
[🔗](https://github.com/Lazarus404/xmedialib/blob/main/lib/srtp.ex#L31)

Secure RTP (SRTP) and Secure RTCP (SRTCP) encryption and authentication.

## What problem this solves

WebRTC and many VoIP systems encrypt RTP payloads with SRTP after DTLS or ZRTP
key agreement. Senders must AES-CM encrypt and HMAC-authenticate each packet;
receivers must verify tags and maintain rollover counters per SSRC. This module
wraps those protect/unprotect steps and SRTCP index handling for media nodes
built on XMediaLib.

RTP alone does not encrypt media. SRTP adds confidentiality and integrity on
top of RTP using session keys derived from a shared master key and salt (often
exchanged via DTLS-SRTP in WebRTC). Only the RTP payload is encrypted; the
fixed header, CSRC list, and header extension remain readable so receivers can
route and decrypt packets. SRTCP protects control traffic with separate keys
and an explicit SRTCP index in each compound packet trailer.

Typical usage:

1. Build `%Srtp.Srtp_Crypto_Ctx{}` with `new_ctx/6` for each SSRC.
2. Call `encrypt/2` before sending and `decrypt/2` after receiving.
3. Thread the updated context returned from each call (ROC and RTCP index
   advance with traffic).

Pass `:passthru` as the context to skip crypto (plaintext debugging).

Algorithms: encryption `:aes_cm` (AES counter mode, RFC 3711) or `:null`;
authentication `:hmac_sha1`, `:skein_hmac`, or `:null`. WebRTC defaults to
AES-CM + HMAC-SHA1 with a 10-byte tag (`HMAC_SHA1_80`). Authentication
failure returns `{:error, :auth}`.

## RFCs

* [RFC 3711](https://www.rfc-editor.org/rfc/rfc3711) - SRTP and SRTCP
* [RFC 3550](https://www.rfc-editor.org/rfc/rfc3550) - RTP (cleartext header)
* [RFC 5761](https://www.rfc-editor.org/rfc/rfc5761) - RTP/RTCP multiplexing
* [RFC 7983](https://www.rfc-editor.org/rfc/rfc7983) - demux before decrypt

# `append_auth`

Appends an SRTP authentication tag to `data` using `aalg` and session key.

# `check_auth`

Verifies the authentication tag on an SRTP packet (RFC 3711).

`roc` is appended to the authenticated portion for RTP. Returns
`{:ok, data_without_tag}` or `{:error, :auth}`.

# `computeIV`

RFC 3711 AES-CM IV for key derivation or packet encryption.

# `decrypt`

Decrypts an SRTP/SRTCP binary or struct, or passes through with `:passthru`.

Returns `{:ok, rtp_or_rtcp, updated_ctx}` or `{:error, :auth}`.

# `decrypt_payload`

Decrypts a payload encrypted by `encrypt_payload/8`.

# `decrypt_payload`

# `derive_key`

Derives a session key from the master key and salt (RFC 3711 section 4.3.1).

`label` is one of the `srtp_label_*` constants. Default `length` is 16 octets.

# `encrypt`

Encrypts `%Rtp{}` or `%Rtcp{}` with `ctx`, or passes through when `ctx` is `:passthru`.

Returns `{:ok, binary, updated_ctx}` on success.

# `encrypt_payload`

Encrypts an RTP or SRTCP payload with the session encryption algorithm.

For AES-CM, `index` is the packet index (RTP) or SRTCP index. Unsupported
algorithms raise via `throw/1`.

# `encrypt_payload`

# `get_ctr_cipher_stream`

Returns one AES-CTR keystream block for debugging or custom crypto paths.

# `guess_index`

Estimates the 48-bit SRTP packet index from sequence number and ROC (RFC 3711).

Used when decrypting packets that did not carry the full index on the wire.

# `new_ctx`

```elixir
@spec new_ctx(
  non_neg_integer(),
  atom(),
  atom(),
  binary(),
  binary(),
  non_neg_integer()
) ::
  XMediaLib.Srtp.Srtp_Crypto_Ctx.t()
```

Builds an SRTP crypto context for one SSRC.

`ealg` is `:aes_cm` or `:null`. `aalg` is `:hmac_sha1`, `:skein_hmac`, or `:null`.
`tag_length` is 10 for `HMAC_SHA1_80` (WebRTC default). The 6-argument form sets
`key_derivation_rate` to 0; pass a seventh argument to override.

# `new_ctx`

```elixir
@spec new_ctx(
  non_neg_integer(),
  atom(),
  atom(),
  binary(),
  binary(),
  non_neg_integer(),
  non_neg_integer()
) :: XMediaLib.Srtp.Srtp_Crypto_Ctx.t()
```

Same as `new_ctx/6` with explicit `key_derivation_rate` (RFC 3711 master key update).

# `srtp_label_rtcp_auth`

RFC 3711 SRTCP authentication KDF label (0x04).

## Examples

    iex> XMediaLib.Srtp.srtp_label_rtcp_auth()
    4

# `srtp_label_rtcp_encr`

RFC 3711 key derivation label for SRTCP encryption (0x03).

# `srtp_label_rtcp_salt`

RFC 3711 SRTCP salt KDF label (0x05).

## Examples

    iex> XMediaLib.Srtp.srtp_label_rtcp_salt()
    5

# `srtp_label_rtp_auth`

RFC 3711 key derivation label for RTP authentication (0x01).

# `srtp_label_rtp_encr`

RFC 3711 key derivation label for RTP encryption (0x00).

## Examples

    iex> XMediaLib.Srtp.srtp_label_rtp_encr()
    0

# `srtp_label_rtp_salt`

RFC 3711 key derivation label for RTP salt (0x02).

# `update_ctx`

Updates ROC and highest sequence number in `ctx` after a successful RTP op.

---

*Consult [api-reference.md](api-reference.md) for complete listing*