webrtc_dtls13_keys (webrtc v0.1.0)

View Source

DTLS 1.3 key schedule (RFC 8446 §7, RFC 9147 §5.9): HKDF (RFC 5869), HKDF-Expand-Label with the "dtls13" label prefix, handshake and application traffic secrets, traffic keys including the record number encryption key (RFC 9147 §4.2.3), Finished, KeyUpdate and the exporter (RFC 8446 §7.5), and the TLS 1.3 cipher suite table.

Every function that expands a label takes the label prefix so the same code can be checked against the TLS 1.3 traces of RFC 8448, which use "tls13 ". The HKDF and HKDF-Expand-Label code follows quic_hkdf from erlang_quic (Copyright (c) 2024-2026 Benoit Chesneau, Apache License 2.0), adapted to a variable label prefix.

Summary

Functions

The PSK binder (RFC 8446 §4.2.11.2): Finished computed with the binder key over the hash of the truncated ClientHello.

binder_key for a resumption PSK (RFC 8446 §7.1, "res binder").

client_early_traffic_secret (0-RTT), from the ClientHello hash.

Content covered by CertificateVerify (RFC 8446 §4.4.3).

Derive-Secret(Secret, Label, Messages), given the transcript hash of Messages.

Downgrade sentinels (RFC 8446 §4.1.3, RFC 9147 §5.3): last 8 bytes of ServerHello.random when a 1.3 server negotiates DTLS 1.2 or DTLS 1.0.

The early secret without a PSK.

The early secret from a resumption PSK.

HKDF-Expand-Label(Secret, Label, Context, Length) with the given label prefix.

TLS-Exporter (RFC 8446 §7.5). In TLS 1.3 an absent context and an empty context give the same output.

Finished verify_data (RFC 8446 §4.4.4).

The handshake secret from (EC)DHE on top of an early secret (a PSK one when resuming with psk_dhe_ke).

ServerHello.random of a HelloRetryRequest (RFC 8446 §4.1.3).

application_traffic_secret_N+1 (RFC 8446 §7.2).

RFC 9147 §5.9: DTLS 1.3 uses "dtls13" (no trailing space).

resumption_master_secret, from the hash up to the client Finished.

The PSK of a ticket (RFC 8446 §4.6.1).

TLS 1.3 suites in preference order. RFC 8446 §9.1 requires TLS_AES_128_GCM_SHA256.

Traffic keys of RFC 8446 §7.3 plus the record number key of RFC 9147 §4.2.3.

Types

hash/0

-type hash() :: sha256 | sha384.

keys/0

-type keys() ::
          #{cipher := aes_128_gcm | aes_256_gcm | chacha20_poly1305,
            key := binary(),
            iv := binary(),
            sn_key := binary(),
            secret := binary(),
            hash := hash()}.

suite/0

-type suite() ::
          #{id := 0..65535,
            name := atom(),
            cipher := aes_128_gcm | aes_256_gcm | chacha20_poly1305,
            hash := hash(),
            key_len := pos_integer()}.

Functions

binder(Prefix, Hash, BinderKey, TruncatedHash)

-spec binder(binary(), hash(), binary(), binary()) -> binary().

The PSK binder (RFC 8446 §4.2.11.2): Finished computed with the binder key over the hash of the truncated ClientHello.

binder_key(Prefix, Hash, Early)

-spec binder_key(binary(), hash(), binary()) -> binary().

binder_key for a resumption PSK (RFC 8446 §7.1, "res binder").

client_early_secret(Prefix, Hash, Early, ClientHelloHash)

-spec client_early_secret(binary(), hash(), binary(), binary()) -> binary().

client_early_traffic_secret (0-RTT), from the ClientHello hash.

cv_content(Role, TranscriptHash)

-spec cv_content(client | server, binary()) -> binary().

Content covered by CertificateVerify (RFC 8446 §4.4.3).

derive_secret(Prefix, Hash, Secret, Label, TranscriptHash)

-spec derive_secret(binary(), hash(), binary(), binary(), binary()) -> binary().

Derive-Secret(Secret, Label, Messages), given the transcript hash of Messages.

downgrade10()

-spec downgrade10() -> binary().

downgrade12()

-spec downgrade12() -> binary().

Downgrade sentinels (RFC 8446 §4.1.3, RFC 9147 §5.3): last 8 bytes of ServerHello.random when a 1.3 server negotiates DTLS 1.2 or DTLS 1.0.

early_secret(Prefix, Hash)

-spec early_secret(binary(), hash()) -> binary().

The early secret without a PSK.

early_secret(Prefix, Hash, Psk)

-spec early_secret(binary(), hash(), binary()) -> binary().

The early secret from a resumption PSK.

empty_hash(Hash)

-spec empty_hash(hash()) -> binary().

expand(Hash, PRK, Info, Len)

-spec expand(hash(), binary(), binary(), non_neg_integer()) -> binary().

expand_label(Prefix, Hash, Secret, Label, Context, Len)

-spec expand_label(binary(), hash(), binary(), binary(), binary(), non_neg_integer()) -> binary().

HKDF-Expand-Label(Secret, Label, Context, Length) with the given label prefix.

exporter(Prefix, Hash, ExporterSecret, Label, Context, Len)

-spec exporter(binary(), hash(), binary(), binary(), binary() | no_context, non_neg_integer()) ->
                  binary().

TLS-Exporter (RFC 8446 §7.5). In TLS 1.3 an absent context and an empty context give the same output.

extract(Hash, Salt, IKM)

-spec extract(hash(), binary(), binary()) -> binary().

finished(Prefix, Hash, BaseKey, TranscriptHash)

-spec finished(binary(), hash(), binary(), binary()) -> binary().

Finished verify_data (RFC 8446 §4.4.4).

handshake_secret(Prefix, Hash, Shared)

-spec handshake_secret(binary(), hash(), binary()) -> binary().

handshake_secret(Prefix, Hash, Shared, Early)

-spec handshake_secret(binary(), hash(), binary(), binary()) -> binary().

The handshake secret from (EC)DHE on top of an early secret (a PSK one when resuming with psk_dhe_ke).

hash_len(_)

-spec hash_len(hash()) -> pos_integer().

hrr_random()

-spec hrr_random() -> binary().

ServerHello.random of a HelloRetryRequest (RFC 8446 §4.1.3).

master_secret(Prefix, Hash, HandshakeSecret)

-spec master_secret(binary(), hash(), binary()) -> binary().

next_secret(Prefix, Hash, Secret)

-spec next_secret(binary(), hash(), binary()) -> binary().

application_traffic_secret_N+1 (RFC 8446 §7.2).

prefix()

-spec prefix() -> binary().

RFC 9147 §5.9: DTLS 1.3 uses "dtls13" (no trailing space).

resumption_master_secret(Prefix, Hash, Master, TranscriptHash)

-spec resumption_master_secret(binary(), hash(), binary(), binary()) -> binary().

resumption_master_secret, from the hash up to the client Finished.

resumption_psk(Prefix, Hash, ResumptionMaster, Nonce)

-spec resumption_psk(binary(), hash(), binary(), binary()) -> binary().

The PSK of a ticket (RFC 8446 §4.6.1).

suite(_)

-spec suite(0..65535) -> {ok, suite()} | error.

supported_suites()

-spec supported_suites() -> [0..65535].

TLS 1.3 suites in preference order. RFC 8446 §9.1 requires TLS_AES_128_GCM_SHA256.

traffic_keys(Prefix, _, Secret)

-spec traffic_keys(binary(), suite(), binary()) -> keys().

Traffic keys of RFC 8446 §7.3 plus the record number key of RFC 9147 §4.2.3.