nish/net/tls/schedule
The TLS 1.3 key schedule and transcript hash (RFC 8446 §4.4.1, §7.1, §7.3) for the three cipher suites nish/net/tls negotiates.
import {
TLS_AES_128_GCM_SHA256,
TLS_AES_256_GCM_SHA384,
TLS_CHACHA20_POLY1305_SHA256,
TLS_IV_SIZE,
TlsTranscript,
tlsBinderKey,
tlsBinderKeyInto,
tlsBinderVerify,
tlsDeriveSecret,
tlsDeriveSecretHeld,
tlsDeriveSecretInto,
tlsEarlySecret,
tlsEmptyHash,
tlsExpandLabel,
tlsExtract,
tlsFinishedVerifyData,
tlsFinishedVerifyDataHeld,
tlsFinishedVerifyDataInto,
tlsHandshakeSalt,
tlsHandshakeSaltInto,
tlsHandshakeSecret,
tlsHandshakeSecretHeld,
tlsMasterSecret,
tlsMasterSecretHeld,
tlsMasterSecretInto,
tlsPskEarlySecret,
tlsPskEarlySecretInto,
tlsResumptionPsk,
tlsResumptionPskInto,
tlsSuiteHashLength,
tlsSuiteKeyLength,
tlsTrafficIv,
tlsTrafficKey,
tlsTrafficKeysFromHeld,
tlsTrafficKeysInto,
} from "nish/net/tls/schedule";
tlsBinderKey
The binder key of a resumption PSK: Derive-Secret(early, "res binder", "") (RFC 8446 §7.1).
tlsBinderKeyInto
tlsBinderKey in place: Derive-Secret(early, "res binder", ""), written at out[0].
tlsBinderVerify
Whether binder[binderOff .. binderOff + binderLength) is the PSK binder RFC 8446 §4.2.11.2 asks for: the HMAC, under finished_key = Expand-Label(binderKey, "finished", "", HashLen), of truncatedHash[hashOff .. hashOff + hashLength), the transcript hash of the ClientHello up to its binders list.
tlsDeriveSecret
Derive-Secret (RFC 8446 §7.1): Expand-Label of prk with label and a transcript hash, HashLen bytes held as a Secret.
tlsDeriveSecretHeld
tlsDeriveSecret into a held Secret: Derive-Secret (RFC 8446 §7.1) of prk with label and the transcript hash transcriptHash[hashOff .. hashOff + hashLength), written over the HashLen bytes dst holds.
tlsDeriveSecretInto
tlsDeriveSecret in place: Derive-Secret (RFC 8446 §7.1) of prk with label and the transcript hash transcriptHash[hashOff .. hashOff + hashLength), its HashLen bytes written at out[0].
tlsEarlySecret
The early secret with no PSK: HKDF-Extract of HashLen zeros under a zero salt (RFC 8446 §7.1).
tlsEmptyHash
The hash of the empty string, the transcript Derive-Secret(., "derived", "") hashes.
tlsExpandLabel
HKDF-Expand-Label (RFC 8446 §7.1) over the hash hashLength names: length bytes from prk (RFC 8446's Secret), the label (without its "tls13 " prefix, which is added) and context, held as a Secret.
tlsExtract
HKDF-Extract (RFC 5869 §2.2) over the hash hashLength names, held as a Secret.
tlsFinishedVerifyData
A Finished message's verify_data (RFC 8446 §4.4.4): the HMAC of the transcript hash under finished_key = Expand-Label(baseKey, "finished", "", HashLen), where baseKey is the sender's handshake traffic secret.
tlsFinishedVerifyDataHeld
tlsFinishedVerifyData from a held base key and a window of a transcript: the HMAC of transcriptHash[hashOff .. hashOff + hashLength) under finished_key = Expand-Label(baseKey, "finished", "", HashLen) (RFC 8446 §4.4.4).
tlsFinishedVerifyDataInto
tlsFinishedVerifyData in place: the HMAC of transcriptHash[hashOff .. hashOff + hashLength) under finished_key = Expand-Label(baseKey, "finished", "", HashLen) (RFC 8446 §4.4.4), written at out[at].
tlsHandshakeSalt
The salt the handshake secret is extracted under, Derive-Secret(early, "derived", "") (RFC 8446 §7.1): what tlsHandshakeSecret derives and wipes itself, answered for a caller that extracts in place.
tlsHandshakeSaltInto
tlsHandshakeSalt in place: Derive-Secret(early, "derived", ""), the salt a resumed handshake extracts its handshake secret under, written at out[0].
tlsHandshakeSecret
The handshake secret: HKDF-Extract of the ECDHE secret under Derive-Secret(early, "derived", ""), which is wiped before it returns.
tlsHandshakeSecretHeld
tlsHandshakeSecret into a held Secret: HKDF-Extract of ecdhe under Derive-Secret(early, "derived", ""), written over dst's HashLen bytes.
tlsMasterSecret
The master secret: HKDF-Extract of HashLen zeros under Derive-Secret(handshake, "derived", ""), which is wiped before it returns, as the zeros are.
tlsMasterSecretHeld
tlsMasterSecret into a held Secret: HKDF-Extract of HashLen zeros under Derive-Secret(handshake, "derived", ""), written over dst's HashLen bytes.
tlsMasterSecretInto
tlsMasterSecret in place: HKDF-Extract of HashLen zeros under Derive-Secret(handshake, "derived", ""), written at out[0].
tlsPskEarlySecret
The early secret of a resumed handshake: HKDF-Extract of the PSK under a zero salt (RFC 8446 §7.1).
tlsPskEarlySecretInto
tlsPskEarlySecret in place: HKDF-Extract of psk under a zero salt (RFC 8446 §7.1), written at out[0].
tlsResumptionPsk
The PSK a ticket stands for: HKDF-Expand-Label(resumption_master_secret, "resumption", ticket_nonce, HashLen) (RFC 8446 §4.6.1).
tlsResumptionPskInto
tlsResumptionPsk in place: HKDF-Expand-Label(resumption_master_secret, "resumption", ticketNonce[nonceOff .. nonceOff + nonceLength), HashLen) (RFC 8446 §4.6.1), written at out[0].
tlsSuiteHashLength
The hash length of suite: 32 for the two SHA-256 suites, 48 for TLS_AES_256_GCM_SHA384, and 0 for any suite this module does not negotiate, which is how a caller tells the two apart.
tlsSuiteKeyLength
The AEAD key length of suite: 16 for AES-128-GCM, 32 for the other two, 0 for an unknown suite.
tlsTrafficIv
The 12-byte IV a traffic secret gives suite's record protection (RFC 8446 §7.3), held as a Secret; empty for a suite this module does not negotiate.
tlsTrafficKey
The AEAD key a traffic secret gives suite's record protection (RFC 8446 §7.3), held as a Secret; empty for a suite this module does not negotiate.
tlsTrafficKeysFromHeld
tlsTrafficKeysInto from a held traffic secret: the AEAD key it gives suite (RFC 8446 §7.3) written into key, which must be the suite's key length, and its 12-byte IV into iv.
tlsTrafficKeysInto
tlsTrafficKey and tlsTrafficIv in place: the AEAD key a traffic secret gives suite (RFC 8446 §7.3) written into key, which must be the suite's key length, and its 12-byte IV into iv.
TlsTranscript
The running transcript hash of RFC 8446 §4.4.1: every handshake message, header included, in the order sent, over the negotiated suite's hash.
The schedule is a chain of HKDF steps over the suite's hash, SHA-256 for
TLS_AES_128_GCM_SHA256 and TLS_CHACHA20_POLY1305_SHA256 and SHA-384 for
TLS_AES_256_GCM_SHA384. Without a PSK it runs:
early = HKDF-Extract(0, 0)
handshake = HKDF-Extract(Derive-Secret(early, "derived", ""), ECDHE)
c/s hs traffic = Derive-Secret(handshake, "c hs traffic" / "s hs traffic", CH..SH)
master = HKDF-Extract(Derive-Secret(handshake, "derived", ""), 0)
c/s ap traffic, exporter = Derive-Secret(master, "c ap traffic" / "s ap traffic" / "exp master", CH..server Finished)
A resumed handshake (RFC 8446 §2.2) starts from the ticket's PSK instead, and binds the ClientHello to it before anything else is derived:
PSK = HKDF-Expand-Label(resumption master, "resumption", ticket_nonce, HashLen)
early = HKDF-Extract(0, PSK)
binder key = Derive-Secret(early, "res binder", "")
binder = HMAC(Expand-Label(binder key, "finished", "", HashLen), Hash(truncated ClientHello))
handshake = HKDF-Extract(Derive-Secret(early, "derived", ""), ECDHE)
and goes on from the handshake secret as the full handshake does.
Every function takes the hash length (32 or 48) rather than a suite, because
that is all that changes between them; tlsSuiteHashLength turns a suite
into one. The traffic key and IV are here too, because T2's record layer
needs them and RFC 8448 prints them beside the secrets.
In place
Each step also has an *Into form that computes in an
HkdfScratch the caller owns and writes into the caller's array, and
TlsTranscript resets and reads its hash in hashers it allocated once, so
a handshake that keeps its state in a connection slot can run the whole
schedule inside using a = arena() blocks and leave the arena where it was
(TLS-3 in docs/security/tls.md). The scratch is wiped by every step.
Held
Each step also has a *Held form that reads its secrets from
Secrets the caller holds and writes the secret it derives over the bytes
of one, in place, so a connection keeps each stage of the schedule in one
Secret for its life and ratchets it: tlsDeriveSecretHeld,
tlsHandshakeSecretHeld, tlsMasterSecretHeld, and the two that answer
plain bytes, tlsFinishedVerifyDataHeld (verify_data goes on the wire)
and tlsTrafficKeysFromHeld (the cipher reads the key and IV). Every
plain intermediate is wiped before it returns.
Secrets are `Secret`s
The one-shot functions take every secret they
read (a traffic secret, the ECDHE secret, a stage of the schedule) as a
Secret<u8[]> (nish:secret) and answer every secret they derive as one;
each reads its key only inside exposeWith and wipes the intermediates it
made (the "derived" salts, the finished_key, the zero inputs) before it
returns, and HMAC wipes its key blocks. The caller owns what it is handed
and wipes it. What a Secret cannot reach is TLS-1 in
docs/security/tls.md. The transcript hashes, the labels and a Finished
message's verify_data are public and stay plain.
Written from RFC 8446, not ported from another implementation.
Functions
tlsBinderKey
The binder key of a resumption PSK: Derive-Secret(early, "res binder", "") (RFC 8446 §7.1).
const tlsBinderKey: (
hashLength: i32,
earlySecret: Secret<u8[]>,
) => Secret<u8[]>
hashLengthi32requiredThe hash length, 32 or 48.
earlySecretSecret<u8[]>requiredThe early secret from tlsPskEarlySecret. It stays the caller's: this does not wipe it.
returnsSecret<u8[]>A fresh Secret holding the binder key, which the caller owns and wipes.
tlsBinderKeyInto
tlsBinderKey in place: Derive-Secret(early, "res binder", ""), written at out[0]. The scratch is
wiped before it returns.
const tlsBinderKeyInto: (
kdf: HkdfScratch,
hashLength: i32,
earlySecret: u8[],
out: u8[],
) => void
kdfHkdfScratchrequiredThe caller's HKDF scratch, which this computes in and wipes.
hashLengthi32requiredThe hash length, 32 or 48, which is also how many bytes are written.
earlySecretu8[]requiredThe early secret, plain. It stays the caller's to wipe.
outu8[]requiredWhere the binder key is written, from index 0; the caller owns and wipes it.
tlsBinderVerify
Whether binder[binderOff .. binderOff + binderLength) is the PSK binder
RFC 8446 §4.2.11.2 asks for: the HMAC, under finished_key = Expand-Label(binderKey, "finished", "", HashLen), of
truncatedHash[hashOff .. hashOff + hashLength), the transcript hash of
the ClientHello up to its binders list. A binder that is not HashLen bytes
long, or whose window is not inside binder, is false (row 9 of
"Resumption" in docs/security/tls.md). The comparison reads every byte
whatever it finds; the binder the server computed is wiped before it
returns, as tlsFinishedVerifyDataInto wipes the finished key and the
scratch.
const tlsBinderVerify: (
kdf: HkdfScratch,
hashLength: i32,
binderKey: u8[],
truncatedHash: u8[],
hashOff: i32,
binder: u8[],
binderOff: i32,
binderLength: i32,
) => boolean
kdfHkdfScratchrequiredThe caller's HKDF scratch, which this computes in and wipes.
hashLengthi32requiredThe hash length, 32 or 48.
binderKeyu8[]requiredThe binder key from tlsBinderKeyInto, plain. It stays the caller's to wipe.
truncatedHashu8[]requiredThe array that holds the hash of the ClientHello up to its binders list.
hashOffi32requiredWhere in truncatedHash the hashLength bytes of that hash start.
binderu8[]requiredThe array that holds the binder the client sent, usually the received ClientHello.
binderOffi32requiredWhere in binder the client's binder starts.
binderLengthi32requiredHow many bytes the client's binder is.
returnsbooleantrue when the client's binder matches the one the server computed, so the client holds the PSK.
tlsDeriveSecret
Derive-Secret (RFC 8446 §7.1): Expand-Label of prk with label and a transcript hash, HashLen bytes
held as a Secret.
const tlsDeriveSecret: (
hashLength: i32,
prk: Secret<u8[]>,
label: string,
transcriptHash: u8[],
) => Secret<u8[]>
hashLengthi32requiredThe hash length, 32 or 48, which is also how many bytes are derived.
prkSecret<u8[]>requiredThe stage of the schedule to derive from. It stays the caller's: this function does not wipe it.
labelstringrequiredThe label without its "tls13 " prefix, such as "s hs traffic".
transcriptHashu8[]requiredThe transcript hash the secret is bound to, all of it used as the context.
returnsSecret<u8[]>A fresh Secret holding the HashLen derived bytes, which the caller owns and wipes.
tlsDeriveSecretHeld
tlsDeriveSecret into a held Secret: Derive-Secret (RFC 8446 §7.1) of
prk with label and the transcript hash transcriptHash[hashOff .. hashOff + hashLength), written over the HashLen bytes dst holds. dst
may be prk. Panics unless hashLength is 32 or 48 and both hold
HashLen bytes.
const tlsDeriveSecretHeld: (
hashLength: i32,
prk: Secret<u8[]>,
label: string,
transcriptHash: u8[],
hashOff: i32,
dst: Secret<u8[]>,
) => void
hashLengthi32requiredThe hash length, 32 or 48.
prkSecret<u8[]>requiredThe held stage of the schedule to derive from. It is only overwritten when it is also dst.
labelstringrequiredThe label without its "tls13 " prefix, such as "c ap traffic".
transcriptHashu8[]requiredThe array that holds the transcript hash, which is public.
hashOffi32requiredWhere in transcriptHash the hashLength bytes of the hash start.
dstSecret<u8[]>requiredThe held secret whose bytes the result overwrites. The caller still owns and wipes it.
tlsDeriveSecretInto
tlsDeriveSecret in place: Derive-Secret (RFC 8446 §7.1) of prk with
label and the transcript hash transcriptHash[hashOff .. hashOff + hashLength), its HashLen bytes written at out[0]. The scratch is wiped
before it returns. It panics as hkdfExpandLabelInto does, a window outside
its array included.
const tlsDeriveSecretInto: (
kdf: HkdfScratch,
hashLength: i32,
prk: u8[],
label: string,
transcriptHash: u8[],
hashOff: i32,
out: u8[],
) => void
kdfHkdfScratchrequiredThe caller's HKDF scratch, which this computes in and wipes.
hashLengthi32requiredThe hash length, 32 or 48, which is also how many bytes are written.
prku8[]requiredThe stage of the schedule to derive from, plain. It stays the caller's to wipe.
labelstringrequiredThe label without its "tls13 " prefix, such as "s hs traffic".
transcriptHashu8[]requiredThe array that holds the transcript hash.
hashOffi32requiredWhere in transcriptHash the hashLength bytes of the hash start.
outu8[]requiredWhere the derived secret is written, from index 0; the caller owns and wipes it.
tlsEarlySecret
The early secret with no PSK: HKDF-Extract of HashLen zeros under a zero salt (RFC 8446 §7.1). The zero salt and the zero input are wiped before it returns.
const tlsEarlySecret: (hashLength: i32) => Secret<u8[]>
hashLengthi32requiredThe hash length, 32 or 48.
returnsSecret<u8[]>A fresh Secret holding the early secret, which the caller owns and wipes.
tlsEmptyHash
The hash of the empty string, the transcript Derive-Secret(., "derived", "") hashes.
const tlsEmptyHash: (hashLength: i32) => u8[]
hashLengthi32required48 for SHA-384; any other value runs SHA-256.
returnsu8[]The digest of no bytes, in a fresh array. It is public, so it is plain.
tlsExpandLabel
HKDF-Expand-Label (RFC 8446 §7.1) over the hash hashLength names: length
bytes from prk (RFC 8446's Secret), the label (without its "tls13 "
prefix, which is added) and context, held as a Secret. It panics as
hkdfExpandLabelSha256Secret (or its SHA-384 twin) does.
const tlsExpandLabel: (
hashLength: i32,
prk: Secret<u8[]>,
label: string,
context: u8[],
length: i32,
) => Secret<u8[]>
hashLengthi32required48 for SHA-384; any other value runs SHA-256.
prkSecret<u8[]>requiredThe secret to expand. It stays the caller's: this function does not wipe it.
labelstringrequiredThe label without its "tls13 " prefix, such as "key" or "c hs traffic".
contextu8[]requiredThe public context bytes, usually a transcript hash; empty for none.
lengthi32requiredHow many bytes to derive.
returnsSecret<u8[]>A fresh Secret holding the length derived bytes, which the caller owns and wipes.
tlsExtract
HKDF-Extract (RFC 5869 §2.2) over the hash hashLength names, held as a
Secret. Both inputs are Secrets, since the schedule salts every extract
after the first with a derived secret; an empty salt keys HMAC as HashLen
zeros do.
const tlsExtract: (
hashLength: i32,
salt: Secret<u8[]>,
ikm: Secret<u8[]>,
) => Secret<u8[]>
hashLengthi32required48 for SHA-384; any other value runs SHA-256.
saltSecret<u8[]>requiredThe HMAC key. It stays the caller's: this function does not wipe it.
ikmSecret<u8[]>requiredThe input keying material. It stays the caller's as well.
returnsSecret<u8[]>A fresh Secret holding the HashLen-byte PRK, which the caller owns and wipes.
tlsFinishedVerifyData
A Finished message's verify_data (RFC 8446 §4.4.4): the HMAC of the
transcript hash under finished_key = Expand-Label(baseKey, "finished", "", HashLen), where baseKey is the sender's handshake traffic secret. The
finished_key is wiped before it returns; verify_data goes on the wire,
so it is plain.
const tlsFinishedVerifyData: (
hashLength: i32,
baseKey: Secret<u8[]>,
transcriptHash: u8[],
) => u8[]
hashLengthi32requiredThe hash length, 32 or 48.
baseKeySecret<u8[]>requiredThe sender's handshake traffic secret. It stays the caller's: this does not wipe it.
transcriptHashu8[]requiredThe transcript hash up to, and not including, the Finished message.
returnsu8[]The HashLen bytes of verify_data, plain, in a fresh array.
tlsFinishedVerifyDataHeld
tlsFinishedVerifyData from a held base key and a window of a transcript:
the HMAC of transcriptHash[hashOff .. hashOff + hashLength) under
finished_key = Expand-Label(baseKey, "finished", "", HashLen) (RFC 8446
§4.4.4). The finished key is held and wiped before it returns;
verify_data goes on the wire, so it is plain. Panics unless hashLength
is 32 or 48 and baseKey holds HashLen bytes.
const tlsFinishedVerifyDataHeld: (
hashLength: i32,
baseKey: Secret<u8[]>,
transcriptHash: u8[],
hashOff: i32,
) => u8[]
hashLengthi32requiredThe hash length, 32 or 48.
baseKeySecret<u8[]>requiredThe sender's held handshake traffic secret. It stays the caller's: this does not wipe it.
transcriptHashu8[]requiredThe array that holds the transcript hash up to the Finished message.
hashOffi32requiredWhere in transcriptHash the hashLength bytes of the hash start.
returnsu8[]The HashLen bytes of verify_data, plain, in a fresh array.
tlsFinishedVerifyDataInto
tlsFinishedVerifyData in place: the HMAC of transcriptHash[hashOff .. hashOff + hashLength) under finished_key = Expand-Label(baseKey, "finished", "", HashLen) (RFC 8446 §4.4.4), written at out[at]. The
finished key is wiped before it returns, and so is the scratch.
const tlsFinishedVerifyDataInto: (
kdf: HkdfScratch,
hashLength: i32,
baseKey: u8[],
transcriptHash: u8[],
hashOff: i32,
out: u8[],
at: i32,
) => void
kdfHkdfScratchrequiredThe caller's HKDF scratch, which this computes in and wipes.
hashLengthi32requiredThe hash length, 32 or 48, which is also how many bytes are written.
baseKeyu8[]requiredThe sender's handshake traffic secret, plain. It stays the caller's to wipe.
transcriptHashu8[]requiredThe array that holds the transcript hash up to the Finished message.
hashOffi32requiredWhere in transcriptHash the hashLength bytes of the hash start.
outu8[]requiredWhere verify_data is written. It goes on the wire, so it is plain.
ati32requiredWhere in out the HashLen bytes of verify_data start.
tlsHandshakeSalt
The salt the handshake secret is extracted under, Derive-Secret(early, "derived", "") (RFC 8446 §7.1): what tlsHandshakeSecret derives and
wipes itself, answered for a caller that extracts in place.
const tlsHandshakeSalt: (
hashLength: i32,
earlySecret: Secret<u8[]>,
) => Secret<u8[]>
hashLengthi32requiredThe hash length, 32 or 48.
earlySecretSecret<u8[]>requiredThe early secret. It stays the caller's: this function does not wipe it.
returnsSecret<u8[]>A fresh Secret holding the salt, which the caller owns and wipes once the extract is done.
tlsHandshakeSaltInto
tlsHandshakeSalt in place: Derive-Secret(early, "derived", ""), the
salt a resumed handshake extracts its handshake secret under, written at
out[0]. The caller wipes it once the extract is done. The scratch is wiped
before it returns.
const tlsHandshakeSaltInto: (
kdf: HkdfScratch,
hashLength: i32,
earlySecret: u8[],
out: u8[],
) => void
kdfHkdfScratchrequiredThe caller's HKDF scratch, which this computes in and wipes.
hashLengthi32requiredThe hash length, 32 or 48, which is also how many bytes are written.
earlySecretu8[]requiredThe early secret, plain. It stays the caller's to wipe.
outu8[]requiredWhere the salt is written, from index 0.
tlsHandshakeSecret
The handshake secret: HKDF-Extract of the ECDHE secret under
Derive-Secret(early, "derived", ""), which is wiped before it returns.
const tlsHandshakeSecret: (
hashLength: i32,
earlySecret: Secret<u8[]>,
ecdhe: Secret<u8[]>,
) => Secret<u8[]>
hashLengthi32requiredThe hash length, 32 or 48.
earlySecretSecret<u8[]>requiredThe early secret. It stays the caller's: this function does not wipe it.
ecdheSecret<u8[]>requiredThe shared secret of the key exchange. It stays the caller's to wipe as well.
returnsSecret<u8[]>A fresh Secret holding the handshake secret, which the caller owns and wipes.
tlsHandshakeSecretHeld
tlsHandshakeSecret into a held Secret: HKDF-Extract of ecdhe under
Derive-Secret(early, "derived", ""), written over dst's HashLen bytes.
The salt is wiped before it returns; dst may be earlySecret. Panics
unless hashLength is 32 or 48 and earlySecret and dst hold HashLen
bytes.
const tlsHandshakeSecretHeld: (
hashLength: i32,
earlySecret: Secret<u8[]>,
ecdhe: Secret<u8[]>,
dst: Secret<u8[]>,
) => void
hashLengthi32requiredThe hash length, 32 or 48.
earlySecretSecret<u8[]>requiredThe held early secret. It is only overwritten when it is also dst.
ecdheSecret<u8[]>requiredThe held shared secret of the key exchange. It stays the caller's to wipe.
dstSecret<u8[]>requiredThe held secret whose bytes the handshake secret overwrites. The caller still owns and wipes it.
tlsMasterSecret
The master secret: HKDF-Extract of HashLen zeros under
Derive-Secret(handshake, "derived", ""), which is wiped before it returns,
as the zeros are.
const tlsMasterSecret: (
hashLength: i32,
handshakeSecret: Secret<u8[]>,
) => Secret<u8[]>
hashLengthi32requiredThe hash length, 32 or 48.
handshakeSecretSecret<u8[]>requiredThe handshake secret. It stays the caller's: this function does not wipe it.
returnsSecret<u8[]>A fresh Secret holding the master secret, which the caller owns and wipes.
tlsMasterSecretHeld
tlsMasterSecret into a held Secret: HKDF-Extract of HashLen zeros under
Derive-Secret(handshake, "derived", ""), written over dst's HashLen
bytes. The salt and the zeros are wiped before it returns; dst may be
handshakeSecret. Panics unless hashLength is 32 or 48 and both hold
HashLen bytes.
const tlsMasterSecretHeld: (
hashLength: i32,
handshakeSecret: Secret<u8[]>,
dst: Secret<u8[]>,
) => void
hashLengthi32requiredThe hash length, 32 or 48.
handshakeSecretSecret<u8[]>requiredThe held handshake secret. It is only overwritten when it is also dst.
dstSecret<u8[]>requiredThe held secret whose bytes the master secret overwrites. The caller still owns and wipes it.
tlsMasterSecretInto
tlsMasterSecret in place: HKDF-Extract of HashLen zeros under
Derive-Secret(handshake, "derived", ""), written at out[0]. The salt is
wiped before it returns, and so is the scratch.
const tlsMasterSecretInto: (
kdf: HkdfScratch,
hashLength: i32,
handshakeSecret: u8[],
out: u8[],
) => void
kdfHkdfScratchrequiredThe caller's HKDF scratch, which this computes in and wipes.
hashLengthi32requiredThe hash length, 32 or 48, which is also how many bytes are written.
handshakeSecretu8[]requiredThe handshake secret, plain. It stays the caller's to wipe.
outu8[]requiredWhere the master secret is written, from index 0; the caller owns and wipes it.
tlsPskEarlySecret
The early secret of a resumed handshake: HKDF-Extract of the PSK under a zero salt (RFC 8446 §7.1). The zero salt is wiped before it returns; the PSK is the caller's.
const tlsPskEarlySecret: (
hashLength: i32,
psk: Secret<u8[]>,
) => Secret<u8[]>
hashLengthi32requiredThe hash length, 32 or 48.
pskSecret<u8[]>requiredThe pre-shared key the ticket stands for. It stays the caller's to wipe.
returnsSecret<u8[]>A fresh Secret holding the early secret, which the caller owns and wipes.
tlsPskEarlySecretInto
tlsPskEarlySecret in place: HKDF-Extract of psk under a zero salt
(RFC 8446 §7.1), written at out[0]. The scratch is wiped; the zero salt
holds nothing to wipe.
const tlsPskEarlySecretInto: (
kdf: HkdfScratch,
hashLength: i32,
psk: u8[],
out: u8[],
) => void
kdfHkdfScratchrequiredThe caller's HKDF scratch, which this computes in and wipes.
hashLengthi32requiredThe hash length, 32 or 48, which is also how many bytes are written.
psku8[]requiredThe pre-shared key, plain. It stays the caller's to wipe.
outu8[]requiredWhere the early secret is written, from index 0; the caller owns and wipes it.
tlsResumptionPsk
The PSK a ticket stands for: HKDF-Expand-Label(resumption_master_secret, "resumption", ticket_nonce, HashLen) (RFC 8446 §4.6.1).
const tlsResumptionPsk: (
hashLength: i32,
resumptionMasterSecret: Secret<u8[]>,
ticketNonce: u8[],
) => Secret<u8[]>
hashLengthi32requiredThe hash length, 32 or 48, which is also how many bytes are derived.
resumptionMasterSecretSecret<u8[]>requiredThe connection's resumption master secret. It stays the caller's to wipe.
ticketNonceu8[]requiredThe ticket_nonce of the NewSessionTicket, all of it used as the context. It is public.
returnsSecret<u8[]>A fresh Secret holding the PSK, which the caller owns and wipes.
tlsResumptionPskInto
tlsResumptionPsk in place: HKDF-Expand-Label(resumption_master_secret, "resumption", ticketNonce[nonceOff .. nonceOff + nonceLength), HashLen)
(RFC 8446 §4.6.1), written at out[0]. The scratch is wiped before it
returns. A nonce window outside ticketNonce, or longer than 255 bytes,
panics, as hkdfExpandLabelInto does.
const tlsResumptionPskInto: (
kdf: HkdfScratch,
hashLength: i32,
resumptionMasterSecret: u8[],
ticketNonce: u8[],
nonceOff: i32,
nonceLength: i32,
out: u8[],
) => void
kdfHkdfScratchrequiredThe caller's HKDF scratch, which this computes in and wipes.
hashLengthi32requiredThe hash length, 32 or 48, which is also how many bytes are written.
resumptionMasterSecretu8[]requiredThe connection's resumption master secret, plain. It stays the caller's.
ticketNonceu8[]requiredThe array that holds the ticket's ticket_nonce, which is public.
nonceOffi32requiredWhere in ticketNonce the nonce starts.
nonceLengthi32requiredHow many bytes the nonce is.
outu8[]requiredWhere the PSK is written, from index 0; the caller owns and wipes it.
tlsSuiteHashLength
The hash length of suite: 32 for the two SHA-256 suites, 48 for
TLS_AES_256_GCM_SHA384, and 0 for any suite this module does not
negotiate, which is how a caller tells the two apart.
const tlsSuiteHashLength: (suite: i32) => i32
suitei32requiredA cipher suite code point, such as TLS_AES_128_GCM_SHA256.
returnsi32The suite's hash length in bytes (32 or 48), or 0 for a suite this module does not negotiate.
tlsSuiteKeyLength
The AEAD key length of suite: 16 for AES-128-GCM, 32 for the other two, 0 for an unknown suite.
const tlsSuiteKeyLength: (suite: i32) => i32
suitei32requiredA cipher suite code point, such as TLS_AES_128_GCM_SHA256.
returnsi32The suite's AEAD key length in bytes (16 or 32), or 0 for a suite this module does not negotiate.
tlsTrafficIv
The 12-byte IV a traffic secret gives suite's record protection (RFC 8446
§7.3), held as a Secret; empty for a suite this module does not negotiate.
const tlsTrafficIv: (
suite: i32,
trafficSecret: Secret<u8[]>,
) => Secret<u8[]>
suitei32requiredThe negotiated cipher suite, such as TLS_AES_128_GCM_SHA256.
trafficSecretSecret<u8[]>requiredThe traffic secret the IV comes from. It stays the caller's to wipe.
returnsSecret<u8[]>
A fresh Secret holding the 12-byte IV, or an empty one for an unknown suite. The caller owns
and wipes it.
tlsTrafficKey
The AEAD key a traffic secret gives suite's record protection (RFC 8446
§7.3), held as a Secret; empty for a suite this module does not negotiate.
const tlsTrafficKey: (
suite: i32,
trafficSecret: Secret<u8[]>,
) => Secret<u8[]>
suitei32requiredThe negotiated cipher suite, such as TLS_AES_128_GCM_SHA256.
trafficSecretSecret<u8[]>requiredThe traffic secret the key comes from. It stays the caller's to wipe.
returnsSecret<u8[]>
A fresh Secret holding the suite's key (16 or 32 bytes), or an empty one for an unknown suite.
The caller owns and wipes it.
tlsTrafficKeysFromHeld
tlsTrafficKeysInto from a held traffic secret: the AEAD key it gives
suite (RFC 8446 §7.3) written into key, which must be the suite's key
length, and its 12-byte IV into iv. Both stay plain, since the cipher
reads them. false, writing nothing, for a suite this module does not
negotiate, a secret that is not its hash's length, or a key or IV array of
the wrong length.
const tlsTrafficKeysFromHeld: (
suite: i32,
trafficSecret: Secret<u8[]>,
key: u8[],
iv: u8[],
) => boolean
suitei32requiredThe negotiated cipher suite, such as TLS_AES_128_GCM_SHA256.
trafficSecretSecret<u8[]>requiredThe held traffic secret, of the suite's hash length. It stays the caller's to wipe.
keyu8[]requiredWhere the AEAD key is written: an array of exactly the suite's key length (16 or 32 bytes).
ivu8[]requiredWhere the IV is written: an array of exactly 12 bytes.
returnsbooleantrue when the key and IV were written; false, with nothing written, for a bad suite or length.
tlsTrafficKeysInto
tlsTrafficKey and tlsTrafficIv in place: the AEAD key a traffic secret
gives suite (RFC 8446 §7.3) written into key, which must be the suite's
key length, and its 12-byte IV into iv. false, writing nothing, for a
suite this module does not negotiate, a secret that is not its hash's
length, or a key or IV array of the wrong length. When it derives, the
scratch is wiped before it returns.
const tlsTrafficKeysInto: (
kdf: HkdfScratch,
suite: i32,
trafficSecret: u8[],
key: u8[],
iv: u8[],
) => boolean
kdfHkdfScratchrequiredThe caller's HKDF scratch, which this computes in and wipes.
suitei32requiredThe negotiated cipher suite, such as TLS_AES_128_GCM_SHA256.
trafficSecretu8[]requiredThe traffic secret, plain, of the suite's hash length. It stays the caller's to wipe.
keyu8[]requiredWhere the AEAD key is written: an array of exactly the suite's key length (16 or 32 bytes).
ivu8[]requiredWhere the IV is written: an array of exactly 12 bytes.
returnsbooleantrue when the key and IV were written; false, with nothing written, for a bad suite or length.
Classes
TlsTranscript
The running transcript hash of RFC 8446 §4.4.1: every handshake message, header included, in the order sent, over the negotiated suite's hash.
hash reads the hash so far from a copy, so the transcript keeps going: the
schedule takes it after ServerHello, after Certificate, after
CertificateVerify and after the server's Finished. restartWithMessageHash
is the HelloRetryRequest rule: the first ClientHello is replaced by the
synthetic message_hash message holding its hash.
Both hashers are kept so that the field types do not depend on the suite;
only the one hashLength names is fed. So are a fresh pair, which reset
starts the transcript again from, and a twin pair hashInto reads the hash
through: all six are made once, so a transcript reused for the next
connection with reset allocates nothing that outlives a call.
class TlsTranscript
| Member | |
|---|---|
new TlsTranscript(hashLength: i32) |
Makes an empty transcript and all six of its hashers, once, so that reset can reuse them. |
hash(): u8[] |
The transcript hash of everything absorbed so far, in a fresh array; the transcript goes on. |
restartWithMessageHash(): void |
Replaces the transcript so far, which must be exactly the first ClientHello, by message_hash (type 254, a 24-bit length of HashLen, then Hash(ClientHello1)), as RFC 8446 §4.4.1 has a server do before it absorbs its HelloRetryRequest. |
update(data: u8[], off: i32, len: i32): void |
Absorbs data[off .. off + len), a whole handshake message or part of one. |
Constants
0x1301
TLS_AES_128_GCM_SHA256: i32
TLS_AES_128_GCM_SHA256 (RFC 8446 §B.4).
0x1302
TLS_AES_256_GCM_SHA384: i32
TLS_AES_256_GCM_SHA384 (RFC 8446 §B.4).
0x1303
TLS_CHACHA20_POLY1305_SHA256: i32
TLS_CHACHA20_POLY1305_SHA256 (RFC 8446 §B.4).
12
TLS_IV_SIZE: i32
The length of every TLS 1.3 AEAD nonce, and so of every traffic IV (RFC 8446 §5.3).

