webrtc_dtls_record (webrtc v0.1.0)
View SourceDTLS 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
-type content_type() ::
change_cipher_spec | alert | handshake | application_data | heartbeat | tls12_cid | ack |
0..255.
-type dtls_record() :: #{type := content_type(), version := 0..65535, epoch := 0..65535, seq := 0..281474976710655, cid => binary(), fragment := binary()}.
-type replay() :: {Max :: integer(), Bitmap :: non_neg_integer()}.
Functions
-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.
-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.
-spec encode(content_type(), 0..65535, 0..65535, 0..281474976710655, iodata()) -> binary().
-spec new_cipher(webrtc_dtls_crypto:suite(), binary(), binary()) -> 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}.
-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.
-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.
-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.
-spec replay_check(non_neg_integer(), replay()) -> ok | replay.
-spec replay_new() -> replay().
-spec replay_update(non_neg_integer(), replay()) -> replay().
Mark Seq as received. Only call after the record authenticated.
-spec type_code(content_type()) -> 0..255.
-spec type_name(0..255) -> content_type().
-spec unprotect(dtls_record(), cipher()) -> {ok, binary()} | {error, bad_record_mac | record_overflow}.
Decrypt a protected record.