nish/net/tls/codec

The TLS 1.3 handshake messages a server and a client read and write (RFC 8446 §4), as bytes.

import {
  TLS_ALERT_BAD_CERTIFICATE,
  TLS_ALERT_DECODE_ERROR,
  TLS_ALERT_DECRYPT_ERROR,
  TLS_ALERT_HANDSHAKE_FAILURE,
  TLS_ALERT_ILLEGAL_PARAMETER,
  TLS_ALERT_INTERNAL_ERROR,
  TLS_ALERT_MISSING_EXTENSION,
  TLS_ALERT_NO_APPLICATION_PROTOCOL,
  TLS_ALERT_PROTOCOL_VERSION,
  TLS_ALERT_UNEXPECTED_MESSAGE,
  TLS_ALERT_UNSUPPORTED_EXTENSION,
  TLS_EXT_ALPN,
  TLS_EXT_COOKIE,
  TLS_EXT_EARLY_DATA,
  TLS_EXT_KEY_SHARE,
  TLS_EXT_PRE_SHARED_KEY,
  TLS_EXT_PSK_KEY_EXCHANGE_MODES,
  TLS_EXT_QUIC_TRANSPORT_PARAMETERS,
  TLS_EXT_RECORD_SIZE_LIMIT,
  TLS_EXT_SERVER_NAME,
  TLS_EXT_SIGNATURE_ALGORITHMS,
  TLS_EXT_SUPPORTED_GROUPS,
  TLS_EXT_SUPPORTED_VERSIONS,
  TLS_GROUP_SECP256R1,
  TLS_GROUP_X25519,
  TLS_HANDSHAKE_CERTIFICATE,
  TLS_HANDSHAKE_CERTIFICATE_VERIFY,
  TLS_HANDSHAKE_CLIENT_HELLO,
  TLS_HANDSHAKE_ENCRYPTED_EXTENSIONS,
  TLS_HANDSHAKE_FINISHED,
  TLS_HANDSHAKE_MESSAGE_HASH,
  TLS_HANDSHAKE_NEW_SESSION_TICKET,
  TLS_HANDSHAKE_SERVER_HELLO,
  TLS_LEGACY_VERSION,
  TLS_P256_SHARE_SIZE,
  TLS_PSK_DHE_KE,
  TLS_PSK_KE,
  TLS_RANDOM_SIZE,
  TLS_RECORD_SIZE_LIMIT_MAX,
  TLS_RECORD_SIZE_LIMIT_MIN,
  TLS_SIGNATURE_ECDSA_SECP256R1_SHA256,
  TLS_SIGNATURE_ECDSA_SECP384R1_SHA384,
  TLS_SIGNATURE_RSA_PSS_RSAE_SHA256,
  TLS_SIGNATURE_RSA_PSS_RSAE_SHA384,
  TLS_SIGNATURE_RSA_PSS_RSAE_SHA512,
  TLS_VERSION_13,
  TLS_X25519_SHARE_SIZE,
  TlsClientHello,
  TlsClientHelloView,
  TlsServerFlightView,
  tlsCertificateVerifyContent,
  tlsClientOffersScheme,
  tlsCopyCertificates,
  tlsCopyWindow,
  tlsEncodeCertificate,
  tlsEncodeCertificateVerify,
  tlsEncodeClientHello,
  tlsEncodeEncryptedExtensions,
  tlsEncodeFinished,
  tlsEncodeHelloRetryRequest,
  tlsEncodeNewSessionTicket,
  tlsEncodeServerHello,
  tlsEncodeServerHelloPsk,
  tlsHexInto,
  tlsListHas,
  tlsParseClientHello,
  tlsReadCertificate,
  tlsReadCertificateVerify,
  tlsReadClientHello,
  tlsReadEncryptedExtensions,
  tlsReadNewSessionTicket,
  tlsReadServerHello,
  tlsSelectPskIdentity,
  tlsServerHelloDowngrade,
  tlsWindowHasU16,
  tlsWindowString,
  tlsWriteCertificate,
  tlsWriteCertificateVerify,
  tlsWriteCertificateVerifyContent,
  tlsWriteClientHello,
  tlsWriteEncryptedExtensions,
  tlsWriteFinished,
  tlsWriteHelloRetryRequest,
  tlsWriteNewSessionTicket,
  tlsWriteServerHello,
  tlsWriteServerHelloPsk,
} from "nish/net/tls/codec";
import {
  TLS_VERSION_13, TlsClientHelloView, tlsCopyWindow, tlsEncodeServerHello,
  tlsReadClientHello, tlsWindowHasU16
} from "nish/net/tls/codec";

// `body` is a ClientHello without its four-byte handshake header;
// `random`, `suite` and `serverShare` are the server's own.
const hello = new TlsClientHelloView()
tlsReadClientHello(hello, body, 0, toI32(body.length))
if (hello.alert !== 0) {
  // send hello.alert, such as TLS_ALERT_DECODE_ERROR (50), and close
} else if (tlsWindowHasU16(hello.data, hello.versionsAt, hello.versionsLength, TLS_VERSION_13)) {
  const sessionId: u8[] = tlsCopyWindow(hello.data, hello.sessionIdAt, hello.sessionIdLength)
  const reply: u8[] = tlsEncodeServerHello(random, sessionId, suite, serverShare)
}
One reader and eight writers

tlsParseClientHello reads a ClientHello body into a TlsClientHello, checking its structure: every length against the bytes it claims, every vector against its RFC 8446 bounds, and no extension twice (§4.2). A message that breaks one answers the alert a server sends for it in the hello's alert field (decode_error for a malformed or truncated one, illegal_parameter for a duplicate), never a panic, since every byte of it is the peer's. What the fields mean — which version, which suite, whether a share is missing — is the server's to decide, in nish/net/tls.

Reading without copying

tlsReadClientHello is the same reader for a server that keeps its state in a slot: it reads into a TlsClientHelloView made once, whose fields are windows into the message rather than copies of it, so a ClientHello read allocates nothing, and tlsParseClientHello copies a view's windows out.

The writers trust their inputs

Each answers one whole handshake message, header included: ServerHello, a resumed ServerHello that names the PSK it accepts, HelloRetryRequest, EncryptedExtensions, Certificate, CertificateVerify, Finished and NewSessionTicket. Their inputs come from the server and the caller's configuration rather than from the peer, so they check nothing. Each is a tlsWrite* function that writes into the caller's array at an offset — run over an empty array, it measures — and a tlsEncode* one that answers the message in a fresh array.

The client's side is the mirror

tlsWriteClientHello and tlsEncodeClientHello write the hello nish/net/tls/client sends, and five readers — tlsReadServerHello (a HelloRetryRequest too), tlsReadEncryptedExtensions, tlsReadCertificate, tlsReadCertificateVerify and tlsReadNewSessionTicket — read the server's flight into a TlsServerFlightView made once, as windows, with the same checks and the same alerts in its alert field. A server's bytes are the peer's just as a client's are, so these readers never panic either (the tls-server-flight fuzz target).

Extensions

The ones read are server_name (RFC 6066 §3), supported_groups, signature_algorithms, supported_versions and key_share (RFC 8446 §4.2), application_layer_protocol_negotiation (RFC 7301 §3.1), quic_transport_parameters (RFC 9001 §8.2) and record_size_limit (RFC 8449 §4), and pre_shared_key and psk_key_exchange_modes (RFC 8446 §4.2.11, §4.2.9), whose identities and binders the reader checks against their syntax but does not open: a ticket and its binder are the server's to judge. Every other extension is skipped, which is what RFC 8446 §4.2 asks of a server that does not know it.

Written from the RFCs, not ported from another implementation. Private names carry the tls prefix because a std/ module's private functions share the importing program's flat symbol namespace (docs/wp26-stdlib.md §3e).

Functions

tlsCertificateVerifyContent

What a server's CertificateVerify signs (§4.4.3), in a fresh array (tlsWriteCertificateVerifyContent).

const tlsCertificateVerifyContent: (
  transcriptHash: u8[],
) => u8[]
transcriptHashu8[]required

The whole transcript hash through the server's Certificate.

returnsu8[]

The content to sign: 98 bytes of prefix, then the hash. It has no handshake header.

tlsClientOffersScheme

Whether scheme is one the client's signature_algorithms offers, the only ones a server's CertificateVerify may use (§4.4.3).

const tlsClientOffersScheme: (scheme: i32) => boolean
schemei32required

The scheme a server's CertificateVerify names.

returnsboolean

true for ECDSA P-256 or P-384, or RSA-PSS (rsae) with SHA-256, SHA-384 or SHA-512.

tlsCopyCertificates

The DER certificates of the Certificate tlsReadCertificate last read into view, leaf first, each a fresh array.

const tlsCopyCertificates: (
  view: TlsServerFlightView,
) => u8[][]
viewTlsServerFlightViewrequired

A view tlsReadCertificate has just read into.

returnsu8[][]

The chain, copied out of view.data; empty if the read failed or another message was read since.

tlsCopyWindow

A copy of data[at .. at + length), which is how a window of a view becomes an array of its own that outlives the buffer it was read from.

const tlsCopyWindow: (
  data: u8[],
  at: i32,
  length: i32,
) => u8[]
datau8[]required

The buffer the window points into.

ati32required

Where the window starts in data, in bytes.

lengthi32required

How many bytes to copy; a negative one copies none.

returnsu8[]

A fresh array of length bytes; nothing from outside data is copied into it.

tlsEncodeCertificate

A server's Certificate (§4.4.2) in a fresh array (tlsWriteCertificate).

const tlsEncodeCertificate: (chain: u8[][]) => u8[]
chainu8[][]required

The DER certificates, leaf first, each written as it is.

returnsu8[]

The whole message, handshake header included.

tlsEncodeCertificateVerify

A CertificateVerify (§4.4.3) in a fresh array (tlsWriteCertificateVerify).

const tlsEncodeCertificateVerify: (
  scheme: i32,
  signature: u8[],
) => u8[]
schemei32required

The signature scheme, such as TLS_SIGNATURE_ECDSA_SECP256R1_SHA256.

signatureu8[]required

The signature over tlsCertificateVerifyContent, in the scheme's wire encoding.

returnsu8[]

The whole message, handshake header included.

tlsEncodeClientHello

A ClientHello (§4.1.2) in a fresh array (tlsWriteClientHello).

const tlsEncodeClientHello: (
  random: u8[],
  sessionId: u8[],
  suites: i32[],
  groups: i32[],
  shareGroup: i32,
  sharePublic: u8[],
  serverName: string,
  alpn: string[],
  cookie: u8[],
) => u8[]
randomu8[]required

The client's 32-byte random (§4.1.2), written as it is.

sessionIdu8[]required

The legacy_session_id, 0 to 32 bytes; the client sends 32 for middlebox compatibility.

suitesi32[]required

The cipher suites offered, in order of preference.

groupsi32[]required

The groups supported_groups offers, in order of preference.

shareGroupi32required

The group of the one key share sent, such as TLS_GROUP_X25519.

sharePublicu8[]required

That share's public key, its key_exchange.

serverNamestringrequired

The host name for server_name, ASCII; empty to leave the extension out.

alpnstring[]required

The ALPN protocols offered, one character a byte, in order; empty to leave ALPN out.

cookieu8[]required

A HelloRetryRequest's cookie to echo; empty to send none.

returnsu8[]

The whole message, handshake header included.

tlsEncodeEncryptedExtensions

EncryptedExtensions (§4.3.1) in a fresh array (tlsWriteEncryptedExtensions), the ALPN protocol given as its bytes.

const tlsEncodeEncryptedExtensions: (
  extra: u8[],
  alpn: u8[],
  acknowledgeServerName: boolean,
  quicTransportParameters: u8[] | null,
  recordSizeLimit: i32,
) => u8[]
extrau8[]required

Whole extensions, type and length included, written first and unchecked; empty for none.

alpnu8[]required

The protocol the server chose, as its bytes, at most 255; empty to send no ALPN.

acknowledgeServerNamebooleanrequired

Whether to send the empty server_name that says the server used the name.

quicTransportParametersu8[] | nullrequired

The server's QUIC transport parameters, opaque; null to send none.

recordSizeLimiti32required

The server's own record_size_limit (RFC 8449 §4); 0 to send none.

returnsu8[]

The whole message, handshake header included.

tlsEncodeFinished

A Finished (§4.4.4) carrying verifyData, in a fresh array (tlsWriteFinished).

const tlsEncodeFinished: (verifyData: u8[]) => u8[]
verifyDatau8[]required

The whole verify_data, the HMAC the key schedule computed: 32 or 48 bytes.

returnsu8[]

The whole message, handshake header included.

tlsEncodeHelloRetryRequest

A HelloRetryRequest (§4.1.4) choosing suite, echoing sessionId and asking for group, in a fresh array (tlsWriteHelloRetryRequest).

const tlsEncodeHelloRetryRequest: (
  sessionId: u8[],
  suite: i32,
  group: i32,
) => u8[]
sessionIdu8[]required

The client's whole legacy_session_id, 0 to 32 bytes, echoed.

suitei32required

The cipher suite the server chose, which the second ServerHello must choose again.

groupi32required

The group the client is asked to send a share for, such as TLS_GROUP_X25519.

returnsu8[]

The whole message, handshake header included.

tlsEncodeNewSessionTicket

A NewSessionTicket (§4.6.1) in a fresh array (tlsWriteNewSessionTicket).

const tlsEncodeNewSessionTicket: (
  lifetime: u32,
  ageAdd: u32,
  nonce: u8[],
  ticket: u8[],
  extra: u8[],
) => u8[]
lifetimeu32required

How long the ticket may be used, in seconds; RFC 8446 §4.6.1 caps it at seven days.

ageAddu32required

The ticket_age_add that obfuscates the ticket age, which §4.6.1 wants fresh and random.

nonceu8[]required

The whole ticket_nonce, 0 to 255 bytes.

ticketu8[]required

The whole ticket the client will send back: §4.6.1 allows 1 to 65535 bytes, not checked here.

extrau8[]required

Whole extensions, type and length included, written unchecked; empty for none.

returnsu8[]

The whole message, handshake header included.

tlsEncodeServerHello

A ServerHello (§4.1.3) choosing suite and TLS 1.3, echoing the client's sessionId, and carrying the server's x25519 share, in a fresh array (tlsWriteServerHello).

const tlsEncodeServerHello: (
  random: u8[],
  sessionId: u8[],
  suite: i32,
  serverShare: u8[],
) => u8[]
randomu8[]required

The server's 32-byte random (§4.1.3), written as it is.

sessionIdu8[]required

The client's whole legacy_session_id, 0 to 32 bytes, echoed.

suitei32required

The cipher suite the server chose.

serverShareu8[]required

The server's key share, its key_exchange: 32 bytes of x25519, or a 65-byte uncompressed secp256r1 point.

returnsu8[]

The whole message, handshake header included.

tlsEncodeServerHelloPsk

A resumed handshake's ServerHello naming selectedIdentity, in a fresh array (tlsWriteServerHelloPsk).

const tlsEncodeServerHelloPsk: (
  random: u8[],
  sessionId: u8[],
  suite: i32,
  serverShare: u8[],
  selectedIdentity: i32,
) => u8[]
randomu8[]required

The server's 32-byte random (§4.1.3), written as it is.

sessionIdu8[]required

The client's whole legacy_session_id, 0 to 32 bytes, echoed.

suitei32required

The cipher suite the server chose.

serverShareu8[]required

The server's key share, its key_exchange: 32 bytes of x25519, or a 65-byte uncompressed secp256r1 point.

selectedIdentityi32required

The index, from 0, of the client's PSK identity the server accepts; only its low 16 bits are written.

returnsu8[]

The whole message, handshake header included.

tlsHexInto

Writes the bytes the lowercase hex constant text spells at out[at] and answers where they end: how this stack's fixed values, written out where they are defined, become bytes without an array of their own.

const tlsHexInto: (text: string, out: u8[], at: i32) => i32
textstringrequired

Lowercase hex digits, two a byte; a last odd digit is ignored, and nothing else is checked.

outu8[]required

The array to write into; a byte that would land outside it is dropped.

ati32required

Where the first byte goes in out.

returnsi32

at plus the number of bytes text spells, written or not.

tlsListHas

Whether list holds value.

const tlsListHas: (list: i32[], value: i32) => boolean
listi32[]required

The values to look in, such as a TlsClientHello's cipherSuites or groups.

valuei32required

The code point to look for, such as a suite or a group.

returnsboolean

true when value is somewhere in list.

tlsParseClientHello

Reads the ClientHello body data[off .. off + len) — the message without its four-byte handshake header — into a fresh TlsClientHello, with tlsReadClientHello's checks and its alert, every field copied out.

const tlsParseClientHello: (
  data: u8[],
  off: i32,
  len: i32,
) => TlsClientHello
datau8[]required

The buffer that holds the message; nothing in the answer points into it.

offi32required

Where the body starts in data, in bytes, just past the handshake header.

leni32required

How many bytes the body is, from off.

returnsTlsClientHello

A fresh hello whose alert is 0 when the body parsed, or the alert it earns.

tlsReadCertificate

Reads a server's Certificate body (§4.4.2) into view: the request context's length, which the client requires to be 0, and the list of entries. An empty list is decode_error, as §4.4.2.4 has a client answer it; an entry with extensions is unsupported_extension, because the client offers none that a CertificateEntry may carry.

const tlsReadCertificate: (
  view: TlsServerFlightView,
  data: u8[],
  off: i32,
  len: i32,
) => void
viewTlsServerFlightViewrequired

The view to read into, cleared first; its alert and extensionAlert are the verdicts.

datau8[]required

The buffer that holds the message, which the view's windows then point into.

offi32required

Where the Certificate body starts in data, in bytes, just past the handshake header.

leni32required

How many bytes the body is, from off.

tlsReadCertificateVerify

Reads a CertificateVerify body (§4.4.3) into view: the scheme and the signature, neither of them checked here.

const tlsReadCertificateVerify: (
  view: TlsServerFlightView,
  data: u8[],
  off: i32,
  len: i32,
) => void
viewTlsServerFlightViewrequired

The view to read into, cleared first; its alert and extensionAlert are the verdicts.

datau8[]required

The buffer that holds the message, which the view's windows then point into.

offi32required

Where the CertificateVerify body starts in data, in bytes, just past the handshake header.

leni32required

How many bytes the body is, from off.

tlsReadClientHello

Reads the ClientHello body data[off .. off + len) — the message without its four-byte handshake header — into hello, which forgets the last one first. Its alert is 0 when the body parsed; otherwise the first fault decides it: decode_error for a length past its bytes, a vector out of its bounds or bytes left over, and illegal_parameter for an extension sent twice (§4.2), a pre_shared_key that is not the last extension (§4.2.11), two shares for one group, or a bad server_name. A window outside data is decode_error too, rather than a panic.

A hello that parses but offers pre_shared_key with a different number of identities and binders is illegal_parameter, and one that offers it without psk_key_exchange_modes is missing_extension (§4.2.9): rows 10 to 13 of the fallback table in docs/security/tls.md, "Resumption". Nothing is copied: the windows point into data, which must outlive the use made of them.

const tlsReadClientHello: (
  hello: TlsClientHelloView,
  data: u8[],
  off: i32,
  len: i32,
) => void
helloTlsClientHelloViewrequired

The view to read into, cleared first; its alert is the verdict.

datau8[]required

The buffer that holds the message, which the view's windows then point into.

offi32required

Where the body starts in data, in bytes, just past the handshake header.

leni32required

How many bytes the body is, from off.

tlsReadEncryptedExtensions

Reads an EncryptedExtensions body (§4.3.1) into view: ALPN, an empty server_name and supported_groups may be there, and any other extension sets extensionAlert.

const tlsReadEncryptedExtensions: (
  view: TlsServerFlightView,
  data: u8[],
  off: i32,
  len: i32,
) => void
viewTlsServerFlightViewrequired

The view to read into, cleared first; its alert and extensionAlert are the verdicts.

datau8[]required

The buffer that holds the message, which the view's windows then point into.

offi32required

Where the EncryptedExtensions body starts in data, in bytes, just past the handshake header.

leni32required

How many bytes the body is, from off.

tlsReadNewSessionTicket

Checks a NewSessionTicket body's structure (§4.6.1) into view's alert: the client keeps no tickets, so it reads one only to discard it, but a malformed one is still decode_error.

const tlsReadNewSessionTicket: (
  view: TlsServerFlightView,
  data: u8[],
  off: i32,
  len: i32,
) => void
viewTlsServerFlightViewrequired

The view to read into, cleared first; its alert and extensionAlert are the verdicts.

datau8[]required

The buffer that holds the message, which the view's windows then point into.

offi32required

Where the NewSessionTicket body starts in data, in bytes, just past the handshake header.

leni32required

How many bytes the body is, from off.

tlsReadServerHello

Reads the ServerHello body data[off .. off + len) — without its handshake header — into view, which tells a HelloRetryRequest from it by its random (§4.1.3). An absent extensions block parses: it is how a TLS 1.2 or older server answers, which the client refuses for its version.

const tlsReadServerHello: (
  view: TlsServerFlightView,
  data: u8[],
  off: i32,
  len: i32,
) => void
viewTlsServerFlightViewrequired

The view to read into, cleared first; its alert and extensionAlert are the verdicts.

datau8[]required

The buffer that holds the message, which the view's windows then point into.

offi32required

Where the ServerHello body starts in data, in bytes, just past the handshake header.

leni32required

How many bytes the body is, from off.

tlsSelectPskIdentity

Points hello's pskIdentity*, pskTicketAge and pskBinder* at the offer's identity number index and the binder of the same number, and answers whether there is one: false for an index out of range, or a hello that offered no pre_shared_key or did not parse. It walks the lists tlsReadClientHello checked, and allocates nothing.

const tlsSelectPskIdentity: (
  hello: TlsClientHelloView,
  index: i32,
) => boolean
helloTlsClientHelloViewrequired

A view tlsReadClientHello has read into; its PSK windows are cleared first either way.

indexi32required

Which identity to choose, from 0, in the client's order.

returnsboolean

true when the identity and its binder were found and the windows point at them.

tlsServerHelloDowngrade

Whether the ServerHello in view carries a downgrade sentinel in the last 8 bytes of its random (§4.1.3), which a TLS 1.3 client must refuse with illegal_parameter.

const tlsServerHelloDowngrade: (
  view: TlsServerFlightView,
) => boolean
viewTlsServerFlightViewrequired

A view tlsReadServerHello has just read into.

returnsboolean

true when the random ends in the TLS 1.2 or the TLS 1.1 sentinel.

tlsWindowHasU16

Whether the 16-bit values data[at .. at + length) hold value: how a server asks a TlsClientHelloView's windows what it offers without copying them. The values are big-endian pairs; a last odd byte, and any part of the window outside data, is not read.

const tlsWindowHasU16: (
  data: u8[],
  at: i32,
  length: i32,
  value: i32,
) => boolean
datau8[]required

The buffer the window points into, such as a view's data.

ati32required

Where the window starts in data, in bytes.

lengthi32required

How many bytes the window holds, two a value.

valuei32required

The 16-bit code point to look for, such as TLS_VERSION_13.

returnsboolean

true when one of the window's values is value.

tlsWindowString

The bytes of data[at .. at + length) as a string of one character a byte: ASCII here, a host name.

const tlsWindowString: (
  data: u8[],
  at: i32,
  length: i32,
) => string
datau8[]required

The buffer the window points into.

ati32required

Where the window starts in data, in bytes.

lengthi32required

How many bytes the window holds; any part outside data is left out.

returnsstring

A fresh string, one character for each byte read.

tlsWriteCertificate

Writes a server's Certificate (§4.4.2) at out[at] and answers where it ends: an empty request context, then each DER certificate of chain, leaf first, with no extensions of its own.

const tlsWriteCertificate: (
  out: u8[],
  at: i32,
  chain: u8[][],
) => i32
outu8[]required

The array to write into; a byte that would land outside it is dropped, so an empty one measures.

ati32required

Where the message, handshake header first, starts in out.

chainu8[][]required

The DER certificates, leaf first, each written as it is.

returnsi32

Where the message ends in out: at plus its length, written or not.

tlsWriteCertificateVerify

Writes a CertificateVerify (§4.4.3) at out[at]: the signature scheme and the signature as it goes on the wire.

const tlsWriteCertificateVerify: (
  out: u8[],
  at: i32,
  scheme: i32,
  signature: u8[],
) => i32
outu8[]required

The array to write into; a byte that would land outside it is dropped, so an empty one measures.

ati32required

Where the message, handshake header first, starts in out.

schemei32required

The signature scheme, such as TLS_SIGNATURE_ECDSA_SECP256R1_SHA256.

signatureu8[]required

The signature over tlsCertificateVerifyContent, in the scheme's wire encoding.

returnsi32

Where the message ends in out: at plus its length, written or not.

tlsWriteCertificateVerifyContent

Writes what a server's CertificateVerify signs (§4.4.3) at out[at]: 64 spaces, the context string "TLS 1.3, server CertificateVerify", a zero byte, and the transcript hash transcriptHash[off .. off + len) through Certificate.

const tlsWriteCertificateVerifyContent: (
  out: u8[],
  at: i32,
  transcriptHash: u8[],
  off: i32,
  len: i32,
) => i32
outu8[]required

The array to write into; a byte that would land outside it is dropped, so an empty one measures.

ati32required

Where the content starts in out. It has no handshake header: it is signed, not sent.

transcriptHashu8[]required

The buffer that holds the transcript hash through the server's Certificate.

offi32required

Where the hash starts in transcriptHash.

leni32required

How many bytes the hash is: the suite's hash length.

returnsi32

Where the content ends in out: at plus 98 plus len, written or not.

tlsWriteClientHello

Writes a ClientHello (§4.1.2) at out[at] and answers where it ends: random, the legacy_session_id sessionId, the cipher suites suites, null compression, then the extensions server_name (a host_name, left out when serverName is empty), supported_groups (groups), signature_algorithms, ALPN (left out when alpn is empty), supported_versions (TLS 1.3 alone), a key_share with the one entry shareGroup/sharePublic, and cookie when cookie is not empty (the echo of a HelloRetryRequest's, §4.2.2).

const tlsWriteClientHello: (
  out: u8[],
  at: i32,
  random: u8[],
  sessionId: u8[],
  suites: i32[],
  groups: i32[],
  shareGroup: i32,
  sharePublic: u8[],
  serverName: string,
  alpn: string[],
  cookie: u8[],
) => i32
outu8[]required

The array to write into; a byte that would land outside it is dropped, so an empty one measures.

ati32required

Where the message, handshake header first, starts in out.

randomu8[]required

The client's 32-byte random (§4.1.2), written as it is.

sessionIdu8[]required

The legacy_session_id, 0 to 32 bytes; the client sends 32 for middlebox compatibility.

suitesi32[]required

The cipher suites offered, in order of preference.

groupsi32[]required

The groups supported_groups offers, in order of preference.

shareGroupi32required

The group of the one key share sent, such as TLS_GROUP_X25519.

sharePublicu8[]required

That share's public key, its key_exchange.

serverNamestringrequired

The host name for server_name, ASCII; empty to leave the extension out.

alpnstring[]required

The ALPN protocols offered, one character a byte, in order; empty to leave ALPN out.

cookieu8[]required

A HelloRetryRequest's cookie to echo; empty to send none.

returnsi32

Where the message ends in out: at plus its length, written or not.

tlsWriteEncryptedExtensions

Writes EncryptedExtensions (§4.3.1) at out[at] and answers where it ends. extra is extensions the caller encodes itself, written first and as they are; then the chosen ALPN protocol when alpn is not empty (RFC 7301 §3.1, a list of exactly one), an empty server_name when acknowledgeServerName (RFC 6066 §3's acknowledgement), the server's quic_transport_parameters when quicTransportParameters is not null, and the server's own record_size_limit (RFC 8449 §4) when recordSizeLimit is not 0.

const tlsWriteEncryptedExtensions: (
  out: u8[],
  at: i32,
  extra: u8[],
  alpn: string,
  acknowledgeServerName: boolean,
  quicTransportParameters: u8[] | null,
  recordSizeLimit: i32,
) => i32
outu8[]required

The array to write into; a byte that would land outside it is dropped, so an empty one measures.

ati32required

Where the message, handshake header first, starts in out.

extrau8[]required

Whole extensions, type and length included, written first and unchecked; empty for none.

alpnstringrequired

The protocol the server chose, one character a byte, at most 255; empty to send no ALPN.

acknowledgeServerNamebooleanrequired

Whether to send the empty server_name that says the server used the name.

quicTransportParametersu8[] | nullrequired

The server's QUIC transport parameters, opaque; null to send none.

recordSizeLimiti32required

The largest record plaintext the server takes, content type included, written as a uint16; 0 to send none.

returnsi32

Where the message ends in out: at plus its length, written or not.

tlsWriteFinished

Writes a Finished (§4.4.4) at out[at], carrying verifyData[off .. off + len).

const tlsWriteFinished: (
  out: u8[],
  at: i32,
  verifyData: u8[],
  off: i32,
  len: i32,
) => i32
outu8[]required

The array to write into; a byte that would land outside it is dropped, so an empty one measures.

ati32required

Where the message, handshake header first, starts in out.

verifyDatau8[]required

The buffer that holds the verify_data, the HMAC the key schedule computed.

offi32required

Where the verify_data starts in verifyData.

leni32required

How many bytes it is: the suite's hash length, 32 or 48.

returnsi32

Where the message ends in out: at plus its length, written or not.

tlsWriteHelloRetryRequest

Writes a HelloRetryRequest (§4.1.4) at out[at] and answers where it ends: a ServerHello whose random is the fixed HelloRetryRequest value, choosing suite, echoing the session id, and asking for a share of group in key_share. No cookie is sent.

const tlsWriteHelloRetryRequest: (
  out: u8[],
  at: i32,
  sessionId: u8[],
  sessionIdOff: i32,
  sessionIdLength: i32,
  suite: i32,
  group: i32,
) => i32
outu8[]required

The array to write into; a byte that would land outside it is dropped, so an empty one measures.

ati32required

Where the message, handshake header first, starts in out.

sessionIdu8[]required

The buffer that holds the client's legacy_session_id, such as the hello's data.

sessionIdOffi32required

Where the session id starts in sessionId.

sessionIdLengthi32required

How many bytes the session id is, 0 to 32.

suitei32required

The cipher suite the server chose, which the second ServerHello must choose again.

groupi32required

The group the client is asked to send a share for, such as TLS_GROUP_X25519.

returnsi32

Where the message ends in out: at plus its length, written or not.

tlsWriteNewSessionTicket

Writes a NewSessionTicket (§4.6.1) at out[at] and answers where it ends: lifetime in seconds, ageAdd, the nonce nonce[nonceOff .. nonceOff + nonceLength), the ticket ticket[ticketOff .. ticketOff + ticketLength), and extra as the extensions, encoded by the caller and written as they are. The server sends none; RFC 8448 §3's ticket carries early_data.

const tlsWriteNewSessionTicket: (
  out: u8[],
  at: i32,
  lifetime: u32,
  ageAdd: u32,
  nonce: u8[],
  nonceOff: i32,
  nonceLength: i32,
  ticket: u8[],
  ticketOff: i32,
  ticketLength: i32,
  extra: u8[],
) => i32
outu8[]required

The array to write into; a byte that would land outside it is dropped, so an empty one measures.

ati32required

Where the message, handshake header first, starts in out.

lifetimeu32required

How long the ticket may be used, in seconds; RFC 8446 §4.6.1 caps it at seven days.

ageAddu32required

The ticket_age_add that obfuscates the ticket age, which §4.6.1 wants fresh and random.

nonceu8[]required

The buffer that holds the ticket_nonce.

nonceOffi32required

Where the nonce starts in nonce.

nonceLengthi32required

How many bytes the nonce is, 0 to 255.

ticketu8[]required

The buffer that holds the ticket the client will send back.

ticketOffi32required

Where the ticket starts in ticket.

ticketLengthi32required

How many bytes the ticket is: §4.6.1 allows 1 to 65535, not checked here.

extrau8[]required

Whole extensions, type and length included, written unchecked; empty for none.

returnsi32

Where the message ends in out: at plus its length, written or not.

tlsWriteServerHello

Writes a ServerHello (§4.1.3) at out[at] and answers where it ends: choosing suite and TLS 1.3, echoing the session id sessionId[sessionIdOff .. sessionIdOff + sessionIdLength), and carrying the server's key share, secp256r1 when serverShare is a 65-byte point and x25519 otherwise. The extensions are key_share then supported_versions, the order RFC 8448 §3 shows.

const tlsWriteServerHello: (
  out: u8[],
  at: i32,
  random: u8[],
  sessionId: u8[],
  sessionIdOff: i32,
  sessionIdLength: i32,
  suite: i32,
  serverShare: u8[],
) => i32
outu8[]required

The array to write into; a byte that would land outside it is dropped, so an empty one measures.

ati32required

Where the message, handshake header first, starts in out.

randomu8[]required

The server's 32-byte random (§4.1.3), written as it is.

sessionIdu8[]required

The buffer that holds the client's legacy_session_id, such as the hello's data.

sessionIdOffi32required

Where the session id starts in sessionId.

sessionIdLengthi32required

How many bytes the session id is, 0 to 32.

suitei32required

The cipher suite the server chose, such as nish/net/tls/schedule's TLS_AES_128_GCM_SHA256.

serverShareu8[]required

The server's key share, its key_exchange: 32 bytes of x25519, or a 65-byte uncompressed secp256r1 point.

returnsi32

Where the message ends in out: at plus its length, written or not.

tlsWriteServerHelloPsk

Writes the ServerHello of a resumed handshake (§4.1.3, §4.2.11) at out[at] and answers where it ends: tlsWriteServerHello's, with a pre_shared_key that names the client's identity number selectedIdentity (a uint16) ahead of key_share, since the server resumes only in psk_dhe_ke and so always sends its share.

const tlsWriteServerHelloPsk: (
  out: u8[],
  at: i32,
  random: u8[],
  sessionId: u8[],
  sessionIdOff: i32,
  sessionIdLength: i32,
  suite: i32,
  serverShare: u8[],
  selectedIdentity: i32,
) => i32
outu8[]required

The array to write into; a byte that would land outside it is dropped, so an empty one measures.

ati32required

Where the message, handshake header first, starts in out.

randomu8[]required

The server's 32-byte random (§4.1.3), written as it is.

sessionIdu8[]required

The buffer that holds the client's legacy_session_id, such as the hello's data.

sessionIdOffi32required

Where the session id starts in sessionId.

sessionIdLengthi32required

How many bytes the session id is, 0 to 32.

suitei32required

The cipher suite the server chose.

serverShareu8[]required

The server's key share, its key_exchange: 32 bytes of x25519, or a 65-byte uncompressed secp256r1 point.

selectedIdentityi32required

The index, from 0, of the client's PSK identity the server accepts; only its low 16 bits are written.

returnsi32

Where the message ends in out: at plus its length, written or not.

Classes

TlsClientHello

A ClientHello as tlsParseClientHello read it (RFC 8446 §4.1.2), each field copied out of the message into an array of its own: the same hello as a TlsClientHelloView, for a caller that wants values rather than windows. A field whose extension was absent keeps its empty value, and its has* flag says so.

class TlsClientHello
Member
new TlsClientHello() Makes an empty hello, every field empty and every flag false, for tlsParseClientHello to fill.
alert: i32 0 when the message parsed, or the alert it earns: decode_error or illegal_parameter.
alpn: u8[][] The ALPN protocol names offered, each as its bytes (RFC 7301 §3.1).
cipherSuites: i32[] cipher_suites, 16-bit values in the client's order.
extensionTypes: i32[] Every extension type read, in order.
groups: i32[] supported_groups, in the client's order.
hasAlpn: boolean Whether the hello carried ALPN.
hasKeyShare: boolean Whether the hello carried key_share, even an empty one.
hasPreSharedKey: boolean Whether the hello carried pre_shared_key, which must be its last extension (§4.2.11).
hasPskModes: boolean Whether the hello carried psk_key_exchange_modes, without which a server must not resume (§4.2.9).
hasQuicTransportParameters: boolean Whether the hello carried quic_transport_parameters, which a QUIC handshake requires (RFC 9001 §8.2).
hasServerName: boolean Whether the hello carried server_name with a host_name in it.
hasSignatureAlgorithms: boolean Whether the hello carried signature_algorithms.
hasSupportedGroups: boolean Whether the hello carried supported_groups.
hasSupportedVersions: boolean Whether the hello carried supported_versions: without it the client does not offer TLS 1.3 (§4.2.1).
hasX25519Share: boolean Whether key_share offered an x25519 share, so x25519Share holds one.
legacyVersion: i32 legacy_version as sent; TLS 1.3 fixes it at 0x0303 and negotiates the real version in supported_versions (§4.1.2).
nullCompressionOnly: boolean Whether legacy_compression_methods is the single null method TLS 1.3 requires (§4.1.2).
pskBinders: u8[][] pre_shared_key's binders, one an identity.
pskBindersPrefix: i32 How many bytes of the body come before binders: the body truncated there, after its handshake header, is what each binder covers (§4.2.11.2).
pskDheKe: boolean Whether psk_key_exchange_modes lists psk_dhe_ke.
pskIdentities: u8[][] pre_shared_key's identities, in the client's order, and each one's obfuscated ticket age (§4.2.11).
pskModes: u8[] psk_key_exchange_modes, one byte a mode.
pskTicketAges: u32[] Each identity's obfuscated_ticket_age, as sent: entry i belongs to pskIdentities[i].
quicTransportParameters: u8[] The client's quic_transport_parameters, opaque (RFC 9001 §8.2).
random: u8[] The client's 32-byte random.
recordSizeLimit: i32 The client's record_size_limit (RFC 8449), lowered to the TLS 1.3 maximum, or 0 when it sent none.
serverName: string The host_name of server_name, or empty.
sessionId: u8[] legacy_session_id, which a server echoes (§4.1.3).
shareGroups: i32[] Every group a key share was offered for, in order.
signatureSchemes: i32[] signature_algorithms, in the client's order.
versions: i32[] supported_versions, in the client's order.
x25519Share: u8[] The x25519 share's key_exchange, as sent; its length is the server's to check.

TlsClientHelloView

A ClientHello as tlsReadClientHello read it, without a byte copied: every field the server needs is a window (…At, …Length) into data, the buffer the hello was read from, and the rest are numbers and flags. A field whose extension was absent keeps an empty window, and its has* flag says so, since an empty list and a missing extension mean different things to the server (§9.2). Make one per connection and read every hello into it: it allocates nothing after its constructor, so a handshake that keeps its state in a slot reads its ClientHellos without moving the arena.

class TlsClientHelloView
Member
new TlsClientHelloView() Makes an empty view, every window empty and every flag false, for tlsReadClientHello to fill.
alert: i32 0 when the message parsed, or the alert it earns: decode_error or illegal_parameter.
alpnAt: i32 ALPN's protocol_name_list, each name a length byte and its bytes (RFC 7301 §3.1).
alpnLength: i32 The ALPN list's length in bytes, its length bytes included; 0 when ALPN was absent.
extensionsAt: i32 The extensions block, every extension in it.
extensionsLength: i32 The extensions block's length in bytes, 0 for a hello with none.
groupsAt: i32 supported_groups, 16-bit values.
groupsLength: i32 The supported_groups window's length in bytes, two a group; 0 when the extension was absent.
hasAlpn: boolean Whether the hello carried ALPN.
hasKeyShare: boolean Whether the hello carried key_share, even an empty one.
hasP256Share: boolean Whether key_share offered a secp256r1 share, so p256ShareAt names one.
hasPreSharedKey: boolean Whether the hello carried pre_shared_key, which must be its last extension (§4.2.11).
hasPskModes: boolean Whether the hello carried psk_key_exchange_modes, without which a server must not resume (§4.2.9).
hasQuicTransportParameters: boolean Whether the hello carried quic_transport_parameters, which a QUIC handshake requires (RFC 9001 §8.2).
hasRecordSizeLimit: boolean Whether the hello carried record_size_limit (RFC 8449).
hasServerName: boolean Whether the hello carried server_name with a host_name in it.
hasSignatureAlgorithms: boolean Whether the hello carried signature_algorithms.
hasSupportedGroups: boolean Whether the hello carried supported_groups.
hasSupportedVersions: boolean Whether the hello carried supported_versions: without it the client does not offer TLS 1.3 (§4.2.1).
hasX25519Share: boolean Whether key_share offered an x25519 share, so x25519ShareAt names one.
legacyVersion: i32 legacy_version as sent; TLS 1.3 fixes it at 0x0303 and negotiates the real version in supported_versions (§4.1.2).
nullCompressionOnly: boolean Whether legacy_compression_methods is the single null method TLS 1.3 requires (§4.1.2).
p256ShareAt: i32 The secp256r1 share's key_exchange, as sent; its length is the server's to check.
p256ShareLength: i32 The secp256r1 share's length in bytes as sent, 0 when none was offered; a usable share is 65.
pskBinderAt: i32 That identity's binder, the entry of the same index in binders.
pskBinderCount: i32 How many binders binders holds, one an identity.
pskBinderLength: i32 The chosen binder's length in bytes, 32 to 255: tlsReadPreSharedKey refuses a shorter one when it parses the extension. It must equal the suite's hash length.
pskBindersAt: i32 pre_shared_key's binders list: each a PskBinderEntry<32..255>.
pskBindersLength: i32 The binders window's length in bytes, 0 when pre_shared_key was absent.
pskBindersPrefixAt: i32 Where binders' two-byte length starts: the ClientHello up to here, its handshake header included, is what each binder is computed over (§4.2.11.2).
pskDheKe: boolean Whether ke_modes lists psk_dhe_ke, the one mode the server resumes in.
pskIdentitiesAt: i32 pre_shared_key's identities list (§4.2.11): each an identity<1..2^16-1> and a 32-bit obfuscated age.
pskIdentitiesLength: i32 The identities window's length in bytes, 0 when pre_shared_key was absent.
pskIdentityAt: i32 The identity tlsSelectPskIdentity last chose: its bytes and its obfuscated ticket age.
pskIdentityCount: i32 How many identities identities holds; the binder count must match it (§4.2.11).
pskIdentityLength: i32 The chosen identity's length in bytes, 0 until tlsSelectPskIdentity chooses one.
pskModesAt: i32 psk_key_exchange_modes' ke_modes, one byte a mode (§4.2.9).
pskModesLength: i32 The ke_modes window's length in bytes, one a mode; 0 when the extension was absent.
pskTicketAge: u32 The chosen identity's obfuscated_ticket_age, as sent: the ticket's age in milliseconds plus its ticket_age_add, modulo 2^32 (§4.2.11.1).
quicAt: i32 The client's quic_transport_parameters, opaque (RFC 9001 §8.2).
quicLength: i32 The QUIC transport parameters' length in bytes, 0 when the extension was absent.
randomAt: i32 Where the client's 32-byte random starts in data; its length is always 32.
recordSizeLimit: i32 The client's record_size_limit, at least TLS_RECORD_SIZE_LIMIT_MIN and at most TLS_RECORD_SIZE_LIMIT_MAX, a larger value lowered to it; 0 when the hello carried none.
schemesAt: i32 signature_algorithms, 16-bit values.
schemesLength: i32 The signature_algorithms window's length in bytes, two a scheme; 0 when the extension was absent.
serverNameAt: i32 The host_name of server_name, or empty.
serverNameLength: i32 The host_name's length in bytes, 0 when server_name was absent.
sessionIdAt: i32 legacy_session_id, which a server echoes (§4.1.3).
sessionIdLength: i32 The legacy_session_id's length in bytes, 0 to 32.
sharesAt: i32 The client_shares list of key_share, every entry in it.
sharesLength: i32 The client_shares window's length in bytes; 0 when key_share was absent.
suitesAt: i32 cipher_suites, 16-bit values in the client's order.
suitesLength: i32 The cipher_suites window's length in bytes, two a suite.
versionsAt: i32 supported_versions, 16-bit values.
versionsLength: i32 The supported_versions window's length in bytes, two a version; 0 when the extension was absent.
x25519ShareAt: i32 The x25519 share's key_exchange, as sent; its length is the server's to check.
x25519ShareLength: i32 The x25519 share's length in bytes as sent, 0 when none was offered; a usable share is 32.

TlsServerFlightView

One message of the server's flight as a tlsRead* function below read it: a ServerHello or HelloRetryRequest, EncryptedExtensions, Certificate, CertificateVerify or NewSessionTicket. Like TlsClientHelloView its fields are windows into data and numbers, so a read allocates nothing; each read forgets the last message first.

Two verdicts, kept apart so the client can rank them. alert is the structure's: decode_error for a length past its bytes, a vector out of its bounds or bytes left over. extensionAlert is the extensions': an extension sent twice, or one the client offered but this message may not carry, is illegal_parameter; one the client never offers is unsupported_extension (§4.2). The client reads the structure first, then the version and the downgrade sentinel, then the extensions, so that a TLS 1.2 ServerHello is refused for its version, not for the extensions a TLS 1.2 server sends.

class TlsServerFlightView
Member
new TlsServerFlightView() Makes an empty view, every window empty and every flag false, for the tlsRead* functions to fill.
alert: i32 0 when the message parsed, else decode_error.
alpnAt: i32 EncryptedExtensions' ALPN: the one protocol the server chose (RFC 7301 §3.1).
alpnLength: i32 The chosen protocol name's length in bytes, 0 when ALPN was absent.
certificateCount: i32 How many entries certificate_list holds; the first is the server's own certificate.
certificatesAt: i32 Certificate's certificate_list, every entry in it, and how many there are.
certificatesLength: i32 The certificate_list window's length in bytes.
compression: i32 legacy_compression_method, which must be 0 (§4.1.3).
contextLength: i32 Certificate's certificate_request_context, which must be empty for a server's (§4.4.2).
cookieAt: i32 A HelloRetryRequest's cookie, which the second ClientHello echoes (§4.2.2).
cookieLength: i32 The cookie's length in bytes, 0 when none was sent.
extensionAlert: i32 0 when the extensions are ones this message may carry, else illegal_parameter or unsupported_extension.
hasAlpn: boolean Whether EncryptedExtensions carried ALPN.
hasCookie: boolean Whether a HelloRetryRequest carried cookie.
hasKeyShare: boolean Whether the message carried key_share.
hasSupportedVersions: boolean Whether the message carried supported_versions: a TLS 1.3 ServerHello must (§4.2.1).
isRetry: boolean A ServerHello whose random is the HelloRetryRequest value (§4.1.3).
legacyVersion: i32 ServerHello's legacy_version as sent; a TLS 1.3 server sends 0x0303 and names 1.3 in supported_versions (§4.1.3).
randomAt: i32 Where the server's 32-byte random starts in data; the client checks it for the downgrade sentinel (§4.1.3).
scheme: i32 CertificateVerify's scheme and signature (§4.4.3).
selectedVersion: i32 supported_versions' selected_version, 0 when the extension was absent; 0x0304 for TLS 1.3.
serverNameAcknowledged: boolean EncryptedExtensions' empty server_name, the acknowledgement of RFC 6066 §3.
sessionIdAt: i32 legacy_session_id_echo, which must equal the session id the client sent (§4.1.3).
sessionIdLength: i32 The echoed session id's length in bytes, 0 to 32.
shareAt: i32 Where the ServerHello's key_exchange starts in data.
shareGroup: i32 key_share: a ServerHello's entry, or a HelloRetryRequest's selected_group with an empty share.
shareLength: i32 The key_exchange's length in bytes as sent, 0 for a HelloRetryRequest; an x25519 share is 32.
signatureAt: i32 Where CertificateVerify's signature starts in data.
signatureLength: i32 The signature's length in bytes.
suite: i32 The cipher suite the server chose, a 16-bit value.

Limits

16,385

TLS_RECORD_SIZE_LIMIT_MAX: i32

The largest record_size_limit TLS 1.3 can use (RFC 8449 §4): 2^14 bytes of content and the content-type byte. A larger value means this.

64

TLS_RECORD_SIZE_LIMIT_MIN: i32

The smallest record_size_limit a peer may send (RFC 8449 §4); below it is illegal_parameter.

Constants

42

TLS_ALERT_BAD_CERTIFICATE: i32

The client's verdict on a server certificate it does not accept, which TlsClient.authenticate(false) sends by default.

50

TLS_ALERT_DECODE_ERROR: i32

A message that does not parse: a length past its bytes, a vector out of its bounds, trailing bytes.

51

TLS_ALERT_DECRYPT_ERROR: i32

A Finished that does not verify.

40

TLS_ALERT_HANDSHAKE_FAILURE: i32

No acceptable set of parameters: no common suite, group or signature scheme.

47

TLS_ALERT_ILLEGAL_PARAMETER: i32

A field well formed but wrong: a duplicate, a bad share, a second retry without the share.

80

TLS_ALERT_INTERNAL_ERROR: i32

A failure of this side's own: a bad configuration, randomness or signature, or a call out of order.

109

TLS_ALERT_MISSING_EXTENSION: i32

An extension the handshake needs is absent (§9.2, RFC 9001 §8.2).

120

TLS_ALERT_NO_APPLICATION_PROTOCOL: i32

ALPN offered no protocol the server accepts (RFC 7301 §3.2, RFC 9001 §8.1).

70

TLS_ALERT_PROTOCOL_VERSION: i32

A peer that does not offer TLS 1.3.

10

TLS_ALERT_UNEXPECTED_MESSAGE: i32

A message arrived that the handshake's state does not allow.

110

TLS_ALERT_UNSUPPORTED_EXTENSION: i32

An extension in a server message that the client never offered (§4.2).

16

TLS_EXT_ALPN: i32

application_layer_protocol_negotiation (RFC 7301 §3.1): the protocols offered, or the one chosen.

44

TLS_EXT_COOKIE: i32

cookie (§4.2.2): what a HelloRetryRequest may carry and the client's second ClientHello echoes.

42

TLS_EXT_EARLY_DATA: i32

early_data (§4.2.10): read past here, since the server takes no 0-RTT data.

51

TLS_EXT_KEY_SHARE: i32

key_share (§4.2.8): the (EC)DHE shares, or a HelloRetryRequest's selected_group.

41

TLS_EXT_PRE_SHARED_KEY: i32

pre_shared_key (§4.2.11): the client's identities and binders, which must be the last extension.

45

TLS_EXT_PSK_KEY_EXCHANGE_MODES: i32

psk_key_exchange_modes (§4.2.9): which modes the client will resume in.

57

TLS_EXT_QUIC_TRANSPORT_PARAMETERS: i32

quic_transport_parameters (RFC 9001 §8.2): QUIC's own parameters, opaque to TLS.

28

TLS_EXT_RECORD_SIZE_LIMIT: i32

record_size_limit (RFC 8449 §4): the largest protected record plaintext the sender will take, content type included.

0

TLS_EXT_SERVER_NAME: i32

server_name (RFC 6066 §3): the host name the client asks for, or the server's empty acknowledgement.

13

TLS_EXT_SIGNATURE_ALGORITHMS: i32

signature_algorithms (§4.2.3): the schemes a CertificateVerify may be signed with.

10

TLS_EXT_SUPPORTED_GROUPS: i32

supported_groups (§4.2.7): the key-exchange groups the client offers.

43

TLS_EXT_SUPPORTED_VERSIONS: i32

supported_versions (§4.2.1): where TLS 1.3 is offered and chosen, since legacy_version stays 1.2.

0x0017

TLS_GROUP_SECP256R1: i32

secp256r1 (§4.2.7), the second group the client offers and the server agrees to.

0x001d

TLS_GROUP_X25519: i32

x25519 (§4.2.7), the group nish/net/tls prefers.

11

TLS_HANDSHAKE_CERTIFICATE: i32

certificate (§4.4.2): the server's chain, leaf first.

15

TLS_HANDSHAKE_CERTIFICATE_VERIFY: i32

certificate_verify (§4.4.3): a signature over the transcript under the leaf's key.

1

TLS_HANDSHAKE_CLIENT_HELLO: i32

client_hello (§4.1.2): the first message of a handshake, and the client's second after a HelloRetryRequest.

8

TLS_HANDSHAKE_ENCRYPTED_EXTENSIONS: i32

encrypted_extensions (§4.3.1): the server's extensions that do not belong in its ServerHello.

20

TLS_HANDSHAKE_FINISHED: i32

finished (§4.4.4): the MAC over the transcript that closes a side's flight.

254

TLS_HANDSHAKE_MESSAGE_HASH: i32

The synthetic message a HelloRetryRequest puts in the transcript in place of the first ClientHello (§4.4.1).

4

TLS_HANDSHAKE_NEW_SESSION_TICKET: i32

new_session_ticket (§4.6.1): a ticket the server sends after the handshake, for resumption.

2

TLS_HANDSHAKE_SERVER_HELLO: i32

server_hello (§4.1.3), which a HelloRetryRequest shares, told apart by its random.

0x0303

TLS_LEGACY_VERSION: i32

legacy_version in every TLS 1.3 hello (§4.1.2).

65

TLS_P256_SHARE_SIZE: i32

The length of a secp256r1 key share: an uncompressed point, 0x04 then X and Y (§4.2.8.2).

1

TLS_PSK_DHE_KE: i32

psk_dhe_ke (§4.2.9): resumption with an (EC)DHE exchange, the one mode the server resumes in.

0

TLS_PSK_KE: i32

psk_ke (§4.2.9): resumption from the PSK alone, without forward secrecy, which the server never selects.

32

TLS_RANDOM_SIZE: i32

The size of a hello's random (§4.1.2).

0x0403

TLS_SIGNATURE_ECDSA_SECP256R1_SHA256: i32

ecdsa_secp256r1_sha256 (§4.2.3), what a production server signs with.

0x0503

TLS_SIGNATURE_ECDSA_SECP384R1_SHA384: i32

ecdsa_secp384r1_sha384 (§4.2.3), offered by the client.

0x0804

TLS_SIGNATURE_RSA_PSS_RSAE_SHA256: i32

rsa_pss_rsae_sha256 (§4.2.3), what RFC 8448's server signs with.

0x0805

TLS_SIGNATURE_RSA_PSS_RSAE_SHA384: i32

rsa_pss_rsae_sha384 (§4.2.3), offered by the client.

0x0806

TLS_SIGNATURE_RSA_PSS_RSAE_SHA512: i32

rsa_pss_rsae_sha512 (§4.2.3), offered by the client.

0x0304

TLS_VERSION_13: i32

TLS 1.3 in supported_versions (§4.2.1).

32

TLS_X25519_SHARE_SIZE: i32

The length of an x25519 key share (RFC 8446 §4.2.8.2).