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";

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[]>
hashLengthi32required

The hash length, 32 or 48.

earlySecretSecret<u8[]>required

The 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
kdfHkdfScratchrequired

The caller's HKDF scratch, which this computes in and wipes.

hashLengthi32required

The hash length, 32 or 48, which is also how many bytes are written.

earlySecretu8[]required

The early secret, plain. It stays the caller's to wipe.

outu8[]required

Where 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
kdfHkdfScratchrequired

The caller's HKDF scratch, which this computes in and wipes.

hashLengthi32required

The hash length, 32 or 48.

binderKeyu8[]required

The binder key from tlsBinderKeyInto, plain. It stays the caller's to wipe.

truncatedHashu8[]required

The array that holds the hash of the ClientHello up to its binders list.

hashOffi32required

Where in truncatedHash the hashLength bytes of that hash start.

binderu8[]required

The array that holds the binder the client sent, usually the received ClientHello.

binderOffi32required

Where in binder the client's binder starts.

binderLengthi32required

How many bytes the client's binder is.

returnsboolean

true 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[]>
hashLengthi32required

The hash length, 32 or 48, which is also how many bytes are derived.

prkSecret<u8[]>required

The stage of the schedule to derive from. It stays the caller's: this function does not wipe it.

labelstringrequired

The label without its "tls13 " prefix, such as "s hs traffic".

transcriptHashu8[]required

The 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
hashLengthi32required

The hash length, 32 or 48.

prkSecret<u8[]>required

The held stage of the schedule to derive from. It is only overwritten when it is also dst.

labelstringrequired

The label without its "tls13 " prefix, such as "c ap traffic".

transcriptHashu8[]required

The array that holds the transcript hash, which is public.

hashOffi32required

Where in transcriptHash the hashLength bytes of the hash start.

dstSecret<u8[]>required

The 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
kdfHkdfScratchrequired

The caller's HKDF scratch, which this computes in and wipes.

hashLengthi32required

The hash length, 32 or 48, which is also how many bytes are written.

prku8[]required

The stage of the schedule to derive from, plain. It stays the caller's to wipe.

labelstringrequired

The label without its "tls13 " prefix, such as "s hs traffic".

transcriptHashu8[]required

The array that holds the transcript hash.

hashOffi32required

Where in transcriptHash the hashLength bytes of the hash start.

outu8[]required

Where 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[]>
hashLengthi32required

The 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[]
hashLengthi32required

48 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[]>
hashLengthi32required

48 for SHA-384; any other value runs SHA-256.

prkSecret<u8[]>required

The secret to expand. It stays the caller's: this function does not wipe it.

labelstringrequired

The label without its "tls13 " prefix, such as "key" or "c hs traffic".

contextu8[]required

The public context bytes, usually a transcript hash; empty for none.

lengthi32required

How 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[]>
hashLengthi32required

48 for SHA-384; any other value runs SHA-256.

saltSecret<u8[]>required

The HMAC key. It stays the caller's: this function does not wipe it.

ikmSecret<u8[]>required

The 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[]
hashLengthi32required

The hash length, 32 or 48.

baseKeySecret<u8[]>required

The sender's handshake traffic secret. It stays the caller's: this does not wipe it.

transcriptHashu8[]required

The 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[]
hashLengthi32required

The hash length, 32 or 48.

baseKeySecret<u8[]>required

The sender's held handshake traffic secret. It stays the caller's: this does not wipe it.

transcriptHashu8[]required

The array that holds the transcript hash up to the Finished message.

hashOffi32required

Where 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
kdfHkdfScratchrequired

The caller's HKDF scratch, which this computes in and wipes.

hashLengthi32required

The hash length, 32 or 48, which is also how many bytes are written.

baseKeyu8[]required

The sender's handshake traffic secret, plain. It stays the caller's to wipe.

transcriptHashu8[]required

The array that holds the transcript hash up to the Finished message.

hashOffi32required

Where in transcriptHash the hashLength bytes of the hash start.

outu8[]required

Where verify_data is written. It goes on the wire, so it is plain.

ati32required

Where 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[]>
hashLengthi32required

The hash length, 32 or 48.

earlySecretSecret<u8[]>required

The 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
kdfHkdfScratchrequired

The caller's HKDF scratch, which this computes in and wipes.

hashLengthi32required

The hash length, 32 or 48, which is also how many bytes are written.

earlySecretu8[]required

The early secret, plain. It stays the caller's to wipe.

outu8[]required

Where 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[]>
hashLengthi32required

The hash length, 32 or 48.

earlySecretSecret<u8[]>required

The early secret. It stays the caller's: this function does not wipe it.

ecdheSecret<u8[]>required

The 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
hashLengthi32required

The hash length, 32 or 48.

earlySecretSecret<u8[]>required

The held early secret. It is only overwritten when it is also dst.

ecdheSecret<u8[]>required

The held shared secret of the key exchange. It stays the caller's to wipe.

dstSecret<u8[]>required

The 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[]>
hashLengthi32required

The hash length, 32 or 48.

handshakeSecretSecret<u8[]>required

The 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
hashLengthi32required

The hash length, 32 or 48.

handshakeSecretSecret<u8[]>required

The held handshake secret. It is only overwritten when it is also dst.

dstSecret<u8[]>required

The 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
kdfHkdfScratchrequired

The caller's HKDF scratch, which this computes in and wipes.

hashLengthi32required

The hash length, 32 or 48, which is also how many bytes are written.

handshakeSecretu8[]required

The handshake secret, plain. It stays the caller's to wipe.

outu8[]required

Where 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[]>
hashLengthi32required

The hash length, 32 or 48.

pskSecret<u8[]>required

The 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
kdfHkdfScratchrequired

The caller's HKDF scratch, which this computes in and wipes.

hashLengthi32required

The hash length, 32 or 48, which is also how many bytes are written.

psku8[]required

The pre-shared key, plain. It stays the caller's to wipe.

outu8[]required

Where 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[]>
hashLengthi32required

The hash length, 32 or 48, which is also how many bytes are derived.

resumptionMasterSecretSecret<u8[]>required

The connection's resumption master secret. It stays the caller's to wipe.

ticketNonceu8[]required

The 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
kdfHkdfScratchrequired

The caller's HKDF scratch, which this computes in and wipes.

hashLengthi32required

The hash length, 32 or 48, which is also how many bytes are written.

resumptionMasterSecretu8[]required

The connection's resumption master secret, plain. It stays the caller's.

ticketNonceu8[]required

The array that holds the ticket's ticket_nonce, which is public.

nonceOffi32required

Where in ticketNonce the nonce starts.

nonceLengthi32required

How many bytes the nonce is.

outu8[]required

Where 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
suitei32required

A cipher suite code point, such as TLS_AES_128_GCM_SHA256.

returnsi32

The 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
suitei32required

A cipher suite code point, such as TLS_AES_128_GCM_SHA256.

returnsi32

The 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[]>
suitei32required

The negotiated cipher suite, such as TLS_AES_128_GCM_SHA256.

trafficSecretSecret<u8[]>required

The 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[]>
suitei32required

The negotiated cipher suite, such as TLS_AES_128_GCM_SHA256.

trafficSecretSecret<u8[]>required

The 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
suitei32required

The negotiated cipher suite, such as TLS_AES_128_GCM_SHA256.

trafficSecretSecret<u8[]>required

The held traffic secret, of the suite's hash length. It stays the caller's to wipe.

keyu8[]required

Where the AEAD key is written: an array of exactly the suite's key length (16 or 32 bytes).

ivu8[]required

Where the IV is written: an array of exactly 12 bytes.

returnsboolean

true 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
kdfHkdfScratchrequired

The caller's HKDF scratch, which this computes in and wipes.

suitei32required

The negotiated cipher suite, such as TLS_AES_128_GCM_SHA256.

trafficSecretu8[]required

The traffic secret, plain, of the suite's hash length. It stays the caller's to wipe.

keyu8[]required

Where the AEAD key is written: an array of exactly the suite's key length (16 or 32 bytes).

ivu8[]required

Where the IV is written: an array of exactly 12 bytes.

returnsboolean

true 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).