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)
}
tlsCertificateVerifyContent
What a server's CertificateVerify signs (§4.4.3), in a fresh array (tlsWriteCertificateVerifyContent).
tlsClientOffersScheme
Whether scheme is one the client's signature_algorithms offers, the only ones a server's CertificateVerify may use (§4.4.3).
tlsCopyCertificates
The DER certificates of the Certificate tlsReadCertificate last read into view, leaf first, each a fresh array.
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.
tlsEncodeCertificate
A server's Certificate (§4.4.2) in a fresh array (tlsWriteCertificate).
tlsEncodeCertificateVerify
A CertificateVerify (§4.4.3) in a fresh array (tlsWriteCertificateVerify).
tlsEncodeClientHello
A ClientHello (§4.1.2) in a fresh array (tlsWriteClientHello).
tlsEncodeEncryptedExtensions
EncryptedExtensions (§4.3.1) in a fresh array (tlsWriteEncryptedExtensions), the ALPN protocol given as its bytes.
tlsEncodeFinished
A Finished (§4.4.4) carrying verifyData, in a fresh array (tlsWriteFinished).
tlsEncodeHelloRetryRequest
A HelloRetryRequest (§4.1.4) choosing suite, echoing sessionId and asking for group, in a fresh array (tlsWriteHelloRetryRequest).
tlsEncodeNewSessionTicket
A NewSessionTicket (§4.6.1) in a fresh array (tlsWriteNewSessionTicket).
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).
tlsEncodeServerHelloPsk
A resumed handshake's ServerHello naming selectedIdentity, in a fresh array (tlsWriteServerHelloPsk).
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.
tlsListHas
Whether list holds value.
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.
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.
tlsReadCertificateVerify
Reads a CertificateVerify body (§4.4.3) into view: the scheme and the signature, neither of them checked here.
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.
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.
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.
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).
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.
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.
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.
tlsWindowString
The bytes of data[at .. at + length) as a string of one character a byte: ASCII here, a host name.
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.
tlsWriteCertificateVerify
Writes a CertificateVerify (§4.4.3) at out[at]: the signature scheme and the signature as it goes on the wire.
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.
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).
tlsWriteEncryptedExtensions
Writes EncryptedExtensions (§4.3.1) at out[at] and answers where it ends.
tlsWriteFinished
Writes a Finished (§4.4.4) at out[at], carrying verifyData[off .. off + len).
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.
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.
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.
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.
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.
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.
TlsServerFlightView
One message of the server's flight as a tlsRead* function below read it: a ServerHello or HelloRetryRequest, EncryptedExtensions, Certificate, CertificateVerify or NewSessionTicket.
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[]requiredThe 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
schemei32requiredThe scheme a server's CertificateVerify names.
returnsbooleantrue 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[][]
viewTlsServerFlightViewrequiredA 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[]requiredThe buffer the window points into.
ati32requiredWhere the window starts in data, in bytes.
lengthi32requiredHow 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[][]requiredThe 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[]
schemei32requiredThe signature scheme, such as TLS_SIGNATURE_ECDSA_SECP256R1_SHA256.
signatureu8[]requiredThe 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[]requiredThe client's 32-byte random (§4.1.2), written as it is.
sessionIdu8[]requiredThe legacy_session_id, 0 to 32 bytes; the client sends 32 for middlebox compatibility.
suitesi32[]requiredThe cipher suites offered, in order of preference.
groupsi32[]requiredThe groups supported_groups offers, in order of preference.
shareGroupi32requiredThe group of the one key share sent, such as TLS_GROUP_X25519.
sharePublicu8[]requiredThat share's public key, its key_exchange.
serverNamestringrequiredThe host name for server_name, ASCII; empty to leave the extension out.
alpnstring[]requiredThe ALPN protocols offered, one character a byte, in order; empty to leave ALPN out.
cookieu8[]requiredA 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[]requiredWhole extensions, type and length included, written first and unchecked; empty for none.
alpnu8[]requiredThe protocol the server chose, as its bytes, at most 255; empty to send no ALPN.
acknowledgeServerNamebooleanrequiredWhether to send the empty server_name that says the server used the name.
quicTransportParametersu8[] | nullrequiredThe server's QUIC transport parameters, opaque; null to send none.
recordSizeLimiti32requiredThe 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[]requiredThe 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[]requiredThe client's whole legacy_session_id, 0 to 32 bytes, echoed.
suitei32requiredThe cipher suite the server chose, which the second ServerHello must choose again.
groupi32requiredThe 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[]
lifetimeu32requiredHow long the ticket may be used, in seconds; RFC 8446 §4.6.1 caps it at seven days.
ageAddu32requiredThe ticket_age_add that obfuscates the ticket age, which §4.6.1 wants fresh and random.
nonceu8[]requiredThe whole ticket_nonce, 0 to 255 bytes.
ticketu8[]requiredThe whole ticket the client will send back: §4.6.1 allows 1 to 65535 bytes, not checked here.
extrau8[]requiredWhole 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[]requiredThe server's 32-byte random (§4.1.3), written as it is.
sessionIdu8[]requiredThe client's whole legacy_session_id, 0 to 32 bytes, echoed.
suitei32requiredThe 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[]requiredThe server's 32-byte random (§4.1.3), written as it is.
sessionIdu8[]requiredThe client's whole legacy_session_id, 0 to 32 bytes, echoed.
suitei32requiredThe 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.
selectedIdentityi32requiredThe 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
textstringrequiredLowercase hex digits, two a byte; a last odd digit is ignored, and nothing else is checked.
outu8[]requiredThe array to write into; a byte that would land outside it is dropped.
ati32requiredWhere the first byte goes in out.
returnsi32at plus the number of bytes text spells, written or not.
tlsListHas
Whether list holds value.
const tlsListHas: (list: i32[], value: i32) => boolean
listi32[]requiredThe values to look in, such as a TlsClientHello's cipherSuites or groups.
valuei32requiredThe code point to look for, such as a suite or a group.
returnsbooleantrue 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[]requiredThe buffer that holds the message; nothing in the answer points into it.
offi32requiredWhere the body starts in data, in bytes, just past the handshake header.
leni32requiredHow many bytes the body is, from off.
returnsTlsClientHelloA 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
viewTlsServerFlightViewrequiredThe view to read into, cleared first; its alert and extensionAlert are the verdicts.
datau8[]requiredThe buffer that holds the message, which the view's windows then point into.
offi32requiredWhere the Certificate body starts in data, in bytes, just past the handshake header.
leni32requiredHow 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
viewTlsServerFlightViewrequiredThe view to read into, cleared first; its alert and extensionAlert are the verdicts.
datau8[]requiredThe buffer that holds the message, which the view's windows then point into.
offi32requiredWhere the CertificateVerify body starts in data, in bytes, just past the handshake header.
leni32requiredHow 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
helloTlsClientHelloViewrequiredThe view to read into, cleared first; its alert is the verdict.
datau8[]requiredThe buffer that holds the message, which the view's windows then point into.
offi32requiredWhere the body starts in data, in bytes, just past the handshake header.
leni32requiredHow 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
viewTlsServerFlightViewrequiredThe view to read into, cleared first; its alert and extensionAlert are the verdicts.
datau8[]requiredThe buffer that holds the message, which the view's windows then point into.
offi32requiredWhere the EncryptedExtensions body starts in data, in bytes, just past the handshake header.
leni32requiredHow 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
viewTlsServerFlightViewrequiredThe view to read into, cleared first; its alert and extensionAlert are the verdicts.
datau8[]requiredThe buffer that holds the message, which the view's windows then point into.
offi32requiredWhere the NewSessionTicket body starts in data, in bytes, just past the handshake header.
leni32requiredHow 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
viewTlsServerFlightViewrequiredThe view to read into, cleared first; its alert and extensionAlert are the verdicts.
datau8[]requiredThe buffer that holds the message, which the view's windows then point into.
offi32requiredWhere the ServerHello body starts in data, in bytes, just past the handshake header.
leni32requiredHow 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
helloTlsClientHelloViewrequiredA view tlsReadClientHello has read into; its PSK windows are cleared first either way.
indexi32requiredWhich identity to choose, from 0, in the client's order.
returnsbooleantrue 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
viewTlsServerFlightViewrequiredA view tlsReadServerHello has just read into.
returnsbooleantrue 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[]requiredThe buffer the window points into, such as a view's data.
ati32requiredWhere the window starts in data, in bytes.
lengthi32requiredHow many bytes the window holds, two a value.
valuei32requiredThe 16-bit code point to look for, such as TLS_VERSION_13.
returnsbooleantrue 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[]requiredThe buffer the window points into.
ati32requiredWhere the window starts in data, in bytes.
lengthi32requiredHow many bytes the window holds; any part outside data is left out.
returnsstringA 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[]requiredThe array to write into; a byte that would land outside it is dropped, so an empty one measures.
ati32requiredWhere the message, handshake header first, starts in out.
chainu8[][]requiredThe DER certificates, leaf first, each written as it is.
returnsi32Where 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[]requiredThe array to write into; a byte that would land outside it is dropped, so an empty one measures.
ati32requiredWhere the message, handshake header first, starts in out.
schemei32requiredThe signature scheme, such as TLS_SIGNATURE_ECDSA_SECP256R1_SHA256.
signatureu8[]requiredThe signature over tlsCertificateVerifyContent, in the scheme's wire encoding.
returnsi32Where 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[]requiredThe array to write into; a byte that would land outside it is dropped, so an empty one measures.
ati32requiredWhere the content starts in out. It has no handshake header: it is signed, not sent.
transcriptHashu8[]requiredThe buffer that holds the transcript hash through the server's Certificate.
offi32requiredWhere the hash starts in transcriptHash.
leni32requiredHow many bytes the hash is: the suite's hash length.
returnsi32Where 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[]requiredThe array to write into; a byte that would land outside it is dropped, so an empty one measures.
ati32requiredWhere the message, handshake header first, starts in out.
randomu8[]requiredThe client's 32-byte random (§4.1.2), written as it is.
sessionIdu8[]requiredThe legacy_session_id, 0 to 32 bytes; the client sends 32 for middlebox compatibility.
suitesi32[]requiredThe cipher suites offered, in order of preference.
groupsi32[]requiredThe groups supported_groups offers, in order of preference.
shareGroupi32requiredThe group of the one key share sent, such as TLS_GROUP_X25519.
sharePublicu8[]requiredThat share's public key, its key_exchange.
serverNamestringrequiredThe host name for server_name, ASCII; empty to leave the extension out.
alpnstring[]requiredThe ALPN protocols offered, one character a byte, in order; empty to leave ALPN out.
cookieu8[]requiredA HelloRetryRequest's cookie to echo; empty to send none.
returnsi32Where 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[]requiredThe array to write into; a byte that would land outside it is dropped, so an empty one measures.
ati32requiredWhere the message, handshake header first, starts in out.
extrau8[]requiredWhole extensions, type and length included, written first and unchecked; empty for none.
alpnstringrequiredThe protocol the server chose, one character a byte, at most 255; empty to send no ALPN.
acknowledgeServerNamebooleanrequiredWhether to send the empty server_name that says the server used the name.
quicTransportParametersu8[] | nullrequiredThe server's QUIC transport parameters, opaque; null to send none.
recordSizeLimiti32requiredThe largest record plaintext the server takes, content type included, written as a uint16; 0 to send none.
returnsi32Where 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[]requiredThe array to write into; a byte that would land outside it is dropped, so an empty one measures.
ati32requiredWhere the message, handshake header first, starts in out.
verifyDatau8[]requiredThe buffer that holds the verify_data, the HMAC the key schedule computed.
offi32requiredWhere the verify_data starts in verifyData.
leni32requiredHow many bytes it is: the suite's hash length, 32 or 48.
returnsi32Where 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[]requiredThe array to write into; a byte that would land outside it is dropped, so an empty one measures.
ati32requiredWhere the message, handshake header first, starts in out.
sessionIdu8[]requiredThe buffer that holds the client's legacy_session_id, such as the hello's data.
sessionIdOffi32requiredWhere the session id starts in sessionId.
sessionIdLengthi32requiredHow many bytes the session id is, 0 to 32.
suitei32requiredThe cipher suite the server chose, which the second ServerHello must choose again.
groupi32requiredThe group the client is asked to send a share for, such as TLS_GROUP_X25519.
returnsi32Where 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[]requiredThe array to write into; a byte that would land outside it is dropped, so an empty one measures.
ati32requiredWhere the message, handshake header first, starts in out.
lifetimeu32requiredHow long the ticket may be used, in seconds; RFC 8446 §4.6.1 caps it at seven days.
ageAddu32requiredThe ticket_age_add that obfuscates the ticket age, which §4.6.1 wants fresh and random.
nonceu8[]requiredThe buffer that holds the ticket_nonce.
nonceOffi32requiredWhere the nonce starts in nonce.
nonceLengthi32requiredHow many bytes the nonce is, 0 to 255.
ticketu8[]requiredThe buffer that holds the ticket the client will send back.
ticketOffi32requiredWhere the ticket starts in ticket.
ticketLengthi32requiredHow many bytes the ticket is: §4.6.1 allows 1 to 65535, not checked here.
extrau8[]requiredWhole extensions, type and length included, written unchecked; empty for none.
returnsi32Where 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[]requiredThe array to write into; a byte that would land outside it is dropped, so an empty one measures.
ati32requiredWhere the message, handshake header first, starts in out.
randomu8[]requiredThe server's 32-byte random (§4.1.3), written as it is.
sessionIdu8[]requiredThe buffer that holds the client's legacy_session_id, such as the hello's data.
sessionIdOffi32requiredWhere the session id starts in sessionId.
sessionIdLengthi32requiredHow many bytes the session id is, 0 to 32.
suitei32requiredThe 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.
returnsi32Where 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[]requiredThe array to write into; a byte that would land outside it is dropped, so an empty one measures.
ati32requiredWhere the message, handshake header first, starts in out.
randomu8[]requiredThe server's 32-byte random (§4.1.3), written as it is.
sessionIdu8[]requiredThe buffer that holds the client's legacy_session_id, such as the hello's data.
sessionIdOffi32requiredWhere the session id starts in sessionId.
sessionIdLengthi32requiredHow many bytes the session id is, 0 to 32.
suitei32requiredThe 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.
selectedIdentityi32requiredThe index, from 0, of the client's PSK identity the server accepts; only its low 16 bits are written.
returnsi32Where 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).

