webrtc_dtls (webrtc v0.1.0)
View SourceDTLS endpoint for WebRTC (RFC 9147 DTLS 1.3 and RFC 6347 DTLS 1.2, RFC 5764, RFC 8842), as a sans-IO engine (see docs/ARCHITECTURE.md). Both versions are offered by default; the server picks DTLS 1.3 when the client offers it.
Cert = webrtc_dtls_cert:generate(),
D0 = webrtc_dtls:new(#{role => client, cert => Cert,
remote_fingerprints => [FP]}),
{D1, Actions} = webrtc_dtls:start(Now, D0),
%% execute Actions; feed datagrams with handle_packet/3 and timers
%% with handle_timeout/2 at next_timeout/1.Actions: {send, Datagram} and {event, Event} where Event is {connected, Info}, {data, Bin}, {closed, Reason} or {failed, Reason}.
connected is only reported once the handshake finished AND the peer certificate matched one of the remote fingerprints. When the remote fingerprints are not known yet (the answer has not arrived), the handshake completes and the endpoint waits for set_remote_fingerprints/2; application data received meanwhile is held, not delivered.
This module owns the API; webrtc_dtls12 the DTLS 1.2 record layer, flights and timers; webrtc_dtls_hs the DTLS 1.2 handshake messages and the hello exchange. DTLS 1.3 is in webrtc_dtls13 (records, ACKs, KeyUpdate), webrtc_dtls13_hs and webrtc_dtls13_server.
Summary
Functions
Send close_notify and close (RFC 5246 §7.2.1).
Keying material exporter: RFC 5705 for DTLS 1.2, RFC 8446 §7.5 for DTLS 1.3. DTLS-SRTP uses <<"EXTRACTOR-dtls_srtp">> with no_context (RFC 5764 §4.2).
Connection parameters. extended_master_secret is always true for DTLS 1.3, whose key schedule binds every secret to the handshake transcript, the property RFC 7627 adds to DTLS 1.2.
Update our sending keys and ask the peer to update its own (DTLS 1.3 KeyUpdate, RFC 9147 §8). The new keys are used once the peer acknowledged the KeyUpdate.
Create an endpoint. Options
Bytes a protected application data record adds to its content, for the negotiated version, suite and the peer's connection ID.
DTLS 1.3 server: ask the client for its certificate again (RFC 8446 §4.6.2), when its ClientHello offered post-handshake authentication. {peer_authenticated, Der} follows once its answer verifies; a certificate that does not match the remote fingerprints fails the association.
DTLS 1.3 with connection IDs: send our next records with a fresh CID of the peer, so a new path cannot be linked to the old one by the CID (RFC 9146 §8, RFC 9147 §9). Without a spare CID one is requested and used once it arrives.
Send application data (one record). Only valid once connected.
Provide the remote fingerprints once the remote description is known. Verifies a certificate that was already received.
Start the handshake. The client sends its ClientHello; the server waits for one.
Types
-type flight_item() :: {handshake, Epoch :: non_neg_integer(), webrtc_dtls_msg:msg_type(), Seq :: non_neg_integer(), Body :: binary()} | {change_cipher_spec, Epoch :: non_neg_integer()}.
-type state() :: #dtls{role :: client | server, state :: atom(), version :: undefined | dtls12 | dtls13, versions :: [dtls12 | dtls13], cert_der :: binary(), key :: public_key:private_key(), remote_fps :: undefined | [webrtc_dtls_cert:fingerprint()], peer_cert :: undefined | binary(), peer_key :: undefined | {ecdsa | rsa | eddsa, term()}, verified :: boolean(), handshake_done :: boolean(), srtp_profiles :: [0..65535], srtp_profile :: undefined | 0..65535, suites :: [0..65535], suites13 :: [0..65535], groups :: [webrtc_dtls_crypto:group()], require_ems :: boolean(), use_cookie :: boolean(), cookie_secret :: binary(), mtu :: pos_integer(), client_random :: undefined | binary(), server_random :: undefined | binary(), cookie :: binary(), suite :: undefined | webrtc_dtls_crypto:suite(), group :: undefined | webrtc_dtls_crypto:group(), ecdh_priv :: undefined | binary(), peer_ecdh :: undefined | binary(), peer_schemes :: [0..65535], cert_requested :: boolean(), cv_ok :: boolean(), announced :: boolean(), hvr_count :: non_neg_integer(), ems :: boolean(), master :: undefined | binary(), keys :: undefined | {binary(), binary(), binary(), binary()}, transcript :: [binary()], send_msg_seq :: non_neg_integer(), recv_msg_seq :: non_neg_integer(), reasm :: map(), write_epoch :: non_neg_integer(), write_seq :: #{non_neg_integer() => non_neg_integer()}, write_ciphers :: #{non_neg_integer() => webrtc_dtls_record:cipher() | webrtc_dtls13_keys:keys()}, read_epoch :: non_neg_integer(), read_cipher :: undefined | webrtc_dtls_record:cipher(), pending_read :: undefined | webrtc_dtls_record:cipher(), replay :: #{non_neg_integer() => webrtc_dtls_record:replay()}, early :: [webrtc_dtls_record:dtls_record()], ccs_held :: boolean(), building :: [flight_item()], last_flight :: [flight_item()], rtx_at :: integer() | infinity, rtx_interval :: pos_integer(), rtx_initial :: pos_integer(), rtx_max_interval :: pos_integer(), rtx_count :: non_neg_integer(), rtx_limit :: non_neg_integer(), last_peer_rtx :: undefined | integer(), sent_at :: undefined | integer(), rtx_base :: undefined | pos_integer(), flight_at :: undefined | integer(), addr_valid :: boolean(), pha :: boolean(), pha_state :: undefined | {wait_cert | wait_cv | wait_finished, binary(), [binary()]}, amp_in :: non_neg_integer(), amp_out :: non_neg_integer(), amp_held :: [binary()], held :: [binary()], kx :: undefined | {webrtc_dtls_crypto:group(), binary(), binary()}, hrr :: boolean(), cookie13 :: undefined | binary(), suite13 :: undefined | webrtc_dtls13_keys:suite(), cr_context :: undefined | binary(), secrets :: #{atom() => binary()}, exporter :: undefined | binary(), peer_finished :: boolean(), read_keys :: #{non_neg_integer() => map()}, sent_recs :: #{{non_neg_integer(), non_neg_integer()} => [{non_neg_integer(), non_neg_integer(), non_neg_integer()}]}, acked :: #{non_neg_integer() => [{non_neg_integer(), non_neg_integer()}]}, rcv_recs :: [{non_neg_integer(), non_neg_integer()}], ack_at :: integer() | infinity, ack_now :: boolean(), rcv_new :: boolean(), prev_epoch_until :: undefined | integer(), ku_pending :: boolean(), rekey_records :: pos_integer(), cookie_lifetime :: pos_integer(), cid :: undefined | binary(), peer_cid :: undefined | binary(), cids :: [binary()], cid_in_use :: undefined | binary(), cid_retired :: [binary()], peer_spares :: [binary()], rotate :: boolean(), cid_queue :: [{request, pos_integer()} | {spares, pos_integer()}], resumption :: boolean(), early_data :: boolean(), ticket_lifetime :: pos_integer(), ticket_nonce :: non_neg_integer(), psk :: undefined | map(), resumed :: boolean(), zero_rtt :: undefined | offered | accepted | rejected, early_sent :: non_neg_integer(), out :: [term()]}.
Functions
Send close_notify and close (RFC 5246 §7.2.1).
-spec export_keying_material(binary(), binary() | no_context, non_neg_integer(), state()) -> {ok, binary()} | {error, not_connected}.
Keying material exporter: RFC 5705 for DTLS 1.2, RFC 8446 §7.5 for DTLS 1.3. DTLS-SRTP uses <<"EXTRACTOR-dtls_srtp">> with no_context (RFC 5764 §4.2).
Connection parameters. extended_master_secret is always true for DTLS 1.3, whose key schedule binds every secret to the handshake transcript, the property RFC 7627 adds to DTLS 1.2.
-spec key_update(integer(), state()) -> {ok, state(), [action()]} | {error, not_connected | not_supported | pending}.
Update our sending keys and ask the peer to update its own (DTLS 1.3 KeyUpdate, RFC 9147 §8). The new keys are used once the peer acknowledged the KeyUpdate.
Create an endpoint. Options:
role(required):clientorserver, from the SDP setup attribute (RFC 8842 §5: active is client, passive is server).cert(required): awebrtc_dtls_cert:cert().remote_fingerprints: list ofwebrtc_dtls_cert:fingerprint().srtp_profiles: DTLS-SRTP profile ids in preference order;[]disables use_srtp.versions:[dtlsv1.3', 'dtlsv1.2']' (default) or a subset; the client offers them, the server picks the highest version the client offers.suites: DTLS 1.3 and DTLS 1.2 cipher suite ids in preference order (default: all supported). DTLS 1.3 is only offered when the list has a DTLS 1.3 suite.post_handshake_auth(DTLS 1.3 client, default false): offer post-handshake authentication, so the server may ask for our certificate again (request_client_auth/2).mtu(default 1200),use_cookie(server, default true; a HelloVerifyRequest in DTLS 1.2, a HelloRetryRequest with a stateless cookie in DTLS 1.3),address_validated(server, default false: without a cookie it sends at most three times what it received until the handshake ends, RFC 9147 §5.1; true when the owner validated the address, ICE for instance),require_ems(DTLS 1.2, default true),rtx_initial(ms, default 400),rtx_max(ms, default 60000),rtx_limit(default 7),rekey_records(DTLS 1.3: records sent before a KeyUpdate, default 2^23),cookie_lifetime(ms, default 60000),resumption(DTLS 1.3: issue tickets and resume with them, default false),early_data(0-RTT with resumption, default false),ticket_lifetime(s, default 7200).
-spec record_overhead(state()) -> pos_integer().
Bytes a protected application data record adds to its content, for the negotiated version, suite and the peer's connection ID.
-spec request_client_auth(integer(), state()) -> {ok, state(), [action()]} | {error, not_offered | pending | not_connected | not_supported}.
DTLS 1.3 server: ask the client for its certificate again (RFC 8446 §4.6.2), when its ClientHello offered post-handshake authentication. {peer_authenticated, Der} follows once its answer verifies; a certificate that does not match the remote fingerprints fails the association.
-spec role(state()) -> client | server.
-spec rotate_connection_id(integer(), state()) -> {ok, state(), [action()]} | {error, not_negotiated | not_connected}.
DTLS 1.3 with connection IDs: send our next records with a fresh CID of the peer, so a new path cannot be linked to the old one by the CID (RFC 9146 §8, RFC 9147 §9). Without a spare CID one is requested and used once it arrives.
Send application data (one record). Only valid once connected.
-spec set_remote_fingerprints([webrtc_dtls_cert:fingerprint()], state()) -> {state(), [action()]}.
Provide the remote fingerprints once the remote description is known. Verifies a certificate that was already received.
-spec srtp_profile(state()) -> undefined | 0..65535.
Start the handshake. The client sends its ClientHello; the server waits for one.