webrtc_dtls_record (webrtc v0.1.0)

View Source

DTLS 1.2 record layer (RFC 6347 §4.1): record framing, AEAD protection and the anti-replay window (§4.1.2.6).

With a connection ID (RFC 9146) protected records have content type tls12_cid (25) and the CID after the sequence number; the real content type is the last non-zero byte of the decrypted inner plaintext, and the additional data is that of RFC 9146 §5.

Summary

Functions

Split a datagram into records. A datagram may carry several records (§4.1.1). Parsing stops at the first malformed record; the records before it are returned, as invalid records are discarded (§4.1.2.7) without affecting valid ones.

The same when we receive on a connection ID of CidLen bytes: tls12_cid records carry it (RFC 9146 §4). Without one such records cannot be parsed and end the datagram.

Decrypt a protected record, either format: {ok, Type, Content}.

Bytes a protected record adds to its content, with the peer's connection ID: header, explicit nonce, tag, CID and inner type.

Encrypt and frame one record (RFC 5246 §6.2.3.3, RFC 5288 §3, RFC 7905 §2). The 64-bit DTLS sequence (epoch || seq) is the explicit nonce for GCM and is XORed into the IV for ChaCha20-Poly1305.

The same with the peer's connection ID (RFC 9146 §5): a non-empty one makes a tls12_cid record; undefined or an empty one the plain format.

Mark Seq as received. Only call after the record authenticated.

Decrypt a protected record.

Types

cipher/0

-type cipher() ::
          #{cipher := aes_128_gcm | aes_256_gcm | chacha20_poly1305,
            key := binary(),
            iv := binary(),
            explicit_nonce := 0 | 8}.

content_type/0

-type content_type() ::
          change_cipher_spec | alert | handshake | application_data | heartbeat | tls12_cid | ack |
          0..255.

dtls_record/0

-type dtls_record() ::
          #{type := content_type(),
            version := 0..65535,
            epoch := 0..65535,
            seq := 0..281474976710655,
            cid => binary(),
            fragment := binary()}.

replay/0

-type replay() :: {Max :: integer(), Bitmap :: non_neg_integer()}.

Functions

decode(Bin)

-spec decode(binary()) -> [dtls_record()].

Split a datagram into records. A datagram may carry several records (§4.1.1). Parsing stops at the first malformed record; the records before it are returned, as invalid records are discarded (§4.1.2.7) without affecting valid ones.

decode(Bin, CidLen)

-spec decode(binary(), undefined | pos_integer()) -> [dtls_record()].

The same when we receive on a connection ID of CidLen bytes: tls12_cid records carry it (RFC 9146 §4). Without one such records cannot be parsed and end the datagram.

encode(Type, Version, Epoch, Seq, Fragment)

-spec encode(content_type(), 0..65535, 0..65535, 0..281474976710655, iodata()) -> binary().

new_cipher(_, Key, IV)

-spec new_cipher(webrtc_dtls_crypto:suite(), binary(), binary()) -> cipher().

open(R, Cipher)

-spec open(dtls_record(), cipher()) ->
              {ok, content_type(), binary()} | {error, bad_record_mac | record_overflow}.

Decrypt a protected record, either format: {ok, Type, Content}.

overhead(_, Cid)

-spec overhead(cipher(), undefined | binary()) -> pos_integer().

Bytes a protected record adds to its content, with the peer's connection ID: header, explicit nonce, tag, CID and inner type.

protect(Type, Version, Epoch, Seq, Plain0, _)

-spec protect(content_type(), 0..65535, 0..65535, 0..281474976710655, iodata(), cipher()) -> binary().

Encrypt and frame one record (RFC 5246 §6.2.3.3, RFC 5288 §3, RFC 7905 §2). The 64-bit DTLS sequence (epoch || seq) is the explicit nonce for GCM and is XORed into the IV for ChaCha20-Poly1305.

protect(Type, Version, Epoch, Seq, Plain, Cipher, Cid)

-spec protect(content_type(),
              0..65535,
              0..65535,
              0..281474976710655,
              iodata(),
              cipher(),
              undefined | binary()) ->
                 binary().

The same with the peer's connection ID (RFC 9146 §5): a non-empty one makes a tls12_cid record; undefined or an empty one the plain format.

replay_check(Seq, _)

-spec replay_check(non_neg_integer(), replay()) -> ok | replay.

replay_new()

-spec replay_new() -> replay().

replay_update(Seq, _)

-spec replay_update(non_neg_integer(), replay()) -> replay().

Mark Seq as received. Only call after the record authenticated.

type_code(N)

-spec type_code(content_type()) -> 0..255.

type_name(N)

-spec type_name(0..255) -> content_type().

unprotect(_, _)

-spec unprotect(dtls_record(), cipher()) -> {ok, binary()} | {error, bad_record_mac | record_overflow}.

Decrypt a protected record.