webrtc_srtp_cipher (webrtc v0.1.0)

View Source

SRTP and SRTCP packet transforms: AES-CM with HMAC-SHA1 (RFC 3711 §4.1.1, §4.2.1) and AES-GCM (RFC 7714 §8, §9).

This module holds no per-stream state. The caller (webrtc_srtp) parses the packet, determines the index, runs the replay check and passes everything here. Unprotect functions verify the authentication tag before any decryption and compare tags in constant time.

Packet layouts produced and consumed:

  SRTP  AES-CM:  header | E(payload)             | tag (10 or 4)
  SRTP  GCM:     header | E(payload) | GCM tag (16)
  SRTCP AES-CM:  8 octets | E(rest) | E-flag,index | tag (10)
  SRTCP GCM E=1: 8 octets | E(rest) | GCM tag | E-flag,index
  SRTCP GCM E=0: whole packet | GCM tag | E-flag,index
  

Summary

Functions

Len octets of the header extension keystream of a packet: the AES-CM transform and IV of the payload (RFC 3711 §4.1.1) with the header key and salt in place of the session key and salt. AES-CM is also the transform for the AES-GCM profiles (RFC 7714 §8.3).

Build the transform state for one of SRTP or SRTCP from session keys. Salt is the session salt (14 octets for AES-CM, 12 for GCM).

Protect an RTCP compound packet with the 31-bit SRTCP Index. Encrypt sets the E flag. The packet must be at least 8 octets.

Verify and, when the E flag is set, decrypt an SRTCP packet. Returns the RTCP compound packet and the SRTCP index. The caller has read Index and E from the packet to run the replay check and guarantees the minimum length (8 + 4 + tag).

Protect an RTP packet split as Header and Payload with the 48-bit packet index Index.

Protect an RTP packet with its CSRC list and header extension encrypted (RFC 9335 §5.1). Parts is the fixed header (X set), the CSRC list, the extension header (0xC0DE or 0xC2DE), the extension data and the payload. The encrypted portion is CSRCs, extension data and payload as one keystream; for GCM the fixed header and extension header are the associated data (§5.2).

Verify and decrypt an SRTP packet whose RTP header is HdrLen octets long. The caller guarantees the packet holds at least the header and the tag.

Verify and decrypt a cryptex packet with CC CSRCs. The extension header comes back with its usual profile value.

Functions

header_keystream(Key, _, SSRC, Index, Len)

-spec header_keystream(binary(), <<_:112>>, 0..4294967295, non_neg_integer(), non_neg_integer()) ->
                          binary().

Len octets of the header extension keystream of a packet: the AES-CM transform and IV of the payload (RFC 3711 §4.1.1) with the header key and salt in place of the session key and salt. AES-CM is also the transform for the AES-GCM profiles (RFC 7714 §8.3).

keys(Transform, EncKey, Salt, AuthKey, TagLen)

-spec keys(cm | gcm, binary(), binary(), binary(), pos_integer()) ->
              #srtp_keys{transform :: cm | gcm,
                         cipher :: aes_128_ctr | aes_128_gcm | aes_256_gcm,
                         enc_key :: binary(),
                         salt :: non_neg_integer(),
                         auth_key :: binary() | undefined,
                         tag_len :: pos_integer(),
                         enc_state :: term(),
                         dec_state :: term()}.

Build the transform state for one of SRTP or SRTCP from session keys. Salt is the session salt (14 octets for AES-CM, 12 for GCM).

rtcp_protect(Srtp_keys, SSRC, Index, Encrypt, Bin)

-spec rtcp_protect(#srtp_keys{transform :: cm | gcm,
                              cipher :: aes_128_ctr | aes_128_gcm | aes_256_gcm,
                              enc_key :: binary(),
                              salt :: non_neg_integer(),
                              auth_key :: binary() | undefined,
                              tag_len :: pos_integer(),
                              enc_state :: term(),
                              dec_state :: term()},
                   0..4294967295,
                   0..2147483647,
                   boolean(),
                   binary()) ->
                      {ok, binary()} | {error, malformed}.

Protect an RTCP compound packet with the 31-bit SRTCP Index. Encrypt sets the E flag. The packet must be at least 8 octets.

rtcp_unprotect(Srtp_keys, SSRC, Index, Bin)

-spec rtcp_unprotect(#srtp_keys{transform :: cm | gcm,
                                cipher :: aes_128_ctr | aes_128_gcm | aes_256_gcm,
                                enc_key :: binary(),
                                salt :: non_neg_integer(),
                                auth_key :: binary() | undefined,
                                tag_len :: pos_integer(),
                                enc_state :: term(),
                                dec_state :: term()},
                     0..4294967295,
                     0..2147483647,
                     binary()) ->
                        {ok, binary()} | {error, auth_failed | malformed}.

Verify and, when the E flag is set, decrypt an SRTCP packet. Returns the RTCP compound packet and the SRTCP index. The caller has read Index and E from the packet to run the replay check and guarantees the minimum length (8 + 4 + tag).

rtp_protect(Srtp_keys, SSRC, Index, Hdr, Payload)

-spec rtp_protect(#srtp_keys{transform :: cm | gcm,
                             cipher :: aes_128_ctr | aes_128_gcm | aes_256_gcm,
                             enc_key :: binary(),
                             salt :: non_neg_integer(),
                             auth_key :: binary() | undefined,
                             tag_len :: pos_integer(),
                             enc_state :: term(),
                             dec_state :: term()},
                  0..4294967295,
                  non_neg_integer(),
                  binary(),
                  binary()) ->
                     {ok, binary()} | {error, malformed}.

Protect an RTP packet split as Header and Payload with the 48-bit packet index Index.

rtp_protect_cryptex(Srtp_keys, SSRC, Index, _)

-spec rtp_protect_cryptex(#srtp_keys{transform :: cm | gcm,
                                     cipher :: aes_128_ctr | aes_128_gcm | aes_256_gcm,
                                     enc_key :: binary(),
                                     salt :: non_neg_integer(),
                                     auth_key :: binary() | undefined,
                                     tag_len :: pos_integer(),
                                     enc_state :: term(),
                                     dec_state :: term()},
                          0..4294967295,
                          non_neg_integer(),
                          {binary(), binary(), binary(), binary(), binary()}) ->
                             {ok, binary()} | {error, malformed}.

Protect an RTP packet with its CSRC list and header extension encrypted (RFC 9335 §5.1). Parts is the fixed header (X set), the CSRC list, the extension header (0xC0DE or 0xC2DE), the extension data and the payload. The encrypted portion is CSRCs, extension data and payload as one keystream; for GCM the fixed header and extension header are the associated data (§5.2).

rtp_unprotect(Srtp_keys, SSRC, Index, Bin, HdrLen)

-spec rtp_unprotect(#srtp_keys{transform :: cm | gcm,
                               cipher :: aes_128_ctr | aes_128_gcm | aes_256_gcm,
                               enc_key :: binary(),
                               salt :: non_neg_integer(),
                               auth_key :: binary() | undefined,
                               tag_len :: pos_integer(),
                               enc_state :: term(),
                               dec_state :: term()},
                    0..4294967295,
                    non_neg_integer(),
                    binary(),
                    non_neg_integer()) ->
                       {ok, binary()} | {error, auth_failed | malformed}.

Verify and decrypt an SRTP packet whose RTP header is HdrLen octets long. The caller guarantees the packet holds at least the header and the tag.

rtp_unprotect_cryptex(Srtp_keys, SSRC, Index, Bin, CC)

-spec rtp_unprotect_cryptex(#srtp_keys{transform :: cm | gcm,
                                       cipher :: aes_128_ctr | aes_128_gcm | aes_256_gcm,
                                       enc_key :: binary(),
                                       salt :: non_neg_integer(),
                                       auth_key :: binary() | undefined,
                                       tag_len :: pos_integer(),
                                       enc_state :: term(),
                                       dec_state :: term()},
                            0..4294967295,
                            non_neg_integer(),
                            binary(),
                            0..15) ->
                               {ok, binary()} | {error, auth_failed | malformed}.

Verify and decrypt a cryptex packet with CC CSRCs. The extension header comes back with its usual profile value.