nish/net/quic-packet
QUIC version 1's packets, as RFC 9000 §16-§17 frames them and RFC 9001 §5 protects them: the variable-length integer, the long and short headers, packet-number encoding and recovery, the Initial secrets, AEAD packet protection, header protection and the Retry integrity tag.
import {
QUIC_AEAD_AES_128_GCM,
QUIC_AEAD_AES_256_GCM,
QUIC_AEAD_CHACHA20_POLY1305,
QUIC_AEAD_TAG_SIZE,
QUIC_ERR_CID_LENGTH,
QUIC_ERR_DECRYPT,
QUIC_ERR_FIXED_BIT,
QUIC_ERR_KEYS,
QUIC_ERR_LENGTH,
QUIC_ERR_NOT_PROTECTED,
QUIC_ERR_RESERVED_BITS,
QUIC_ERR_SAMPLE,
QUIC_ERR_TRUNCATED,
QUIC_ERR_VERSION,
QUIC_MAX_CID_LENGTH,
QUIC_MAX_VARINT,
QUIC_PACKET_HANDSHAKE,
QUIC_PACKET_INITIAL,
QUIC_PACKET_OK,
QUIC_PACKET_RETRY,
QUIC_PACKET_SHORT,
QUIC_PACKET_ZERO_RTT,
QUIC_RETRY_TAG_SIZE,
QUIC_SAMPLE_SIZE,
QUIC_VERSION_1,
QuicHeader,
QuicInitialSecrets,
QuicKeys,
QuicKeysSlot,
QuicPacket,
quicDecryptPacket,
quicDecryptPayload,
quicInitialSecrets,
quicInitialSecretsInto,
quicKeyUpdateSecret,
quicKeyUpdateSecretHeldInto,
quicKeyUpdateSecretInto,
quicKeys,
quicKeysHeldInto,
quicKeysInto,
quicKeysUpdate,
quicKeysUpdateInto,
quicKeysWipe,
quicLongHeader,
quicLongHeaderSize,
quicOpenPacket,
quicPacketCopy,
quicPacketGrow,
quicPacketNumberDecode,
quicPacketNumberLength,
quicParseHeader,
quicParseHeaderInto,
quicPutLongHeader,
quicPutShortHeader,
quicRemoveHeaderProtection,
quicRetryIntegrityTag,
quicRetryPacket,
quicRetryVerify,
quicSealInPlace,
quicSealPacket,
quicShortHeader,
quicUnprotectHeader,
quicVarintLength,
quicVarintPush,
quicVarintPushSized,
quicVarintPut,
quicVarintRead,
quicVarintSize,
} from "nish/net/quic-packet";
import { QuicHeader, QuicInitialSecrets, QuicKeys, QuicKeysSlot, QuicPacket, quicInitialSecrets,
quicKeys, quicLongHeader, quicOpenPacket, quicParseHeader, quicSealPacket,
QUIC_AEAD_AES_128_GCM, QUIC_PACKET_INITIAL, QUIC_PACKET_OK } from "nish/net/quic-packet"
import { Secret, secret, wipe } from "nish:secret"
const dcid: u8[] = [0x83, 0x94, 0xc8, 0xf0, 0x3e, 0x51, 0x57, 0x08]
const secrets: QuicInitialSecrets | null = quicInitialSecrets(dcid) // RFC 9001 §5.2
if (secrets !== null) {
const client: u8[] = new Array<u8>(32) // public, so a copy
client.set(secrets.client)
const held: Secret<u8[]> = secret(client)
const slot: QuicKeysSlot = new QuicKeysSlot() // ours, so ours to wipe
const keys: QuicKeys | null = quicKeys(slot, QUIC_AEAD_AES_128_GCM, held)
wipe(held)
const header: u8[] | null = quicLongHeader(QUIC_PACKET_INITIAL, dcid, [], [], 0, 4, 20)
if (keys !== null && header !== null) {
const datagram: u8[] | null = quicSealPacket(keys, header, 0, new Array<u8>(20))
if (datagram !== null) {
const parsed: QuicHeader = quicParseHeader(datagram, 0, 8) // 8: our short DCID length
const packet: QuicPacket = quicOpenPacket(keys, datagram, parsed, -1)
if (packet.error === QUIC_PACKET_OK) {
// packet.payload holds the 20 bytes of frames sealed above
}
}
}
slot.wipe() // once the level is done
}
quicDecryptPacket
Decrypts the payload of a packet whose header protection quicRemoveHeaderProtection took off (RFC 9001 §5.3), filling in packet.payload and setting packet.error: QUIC_ERR_KEYS for keys quicKeys did not make, QUIC_ERR_DECRYPT when it does not authenticate under keys, and QUIC_ERR_RESERVED_BITS when it does but the header's reserved bits are not zero (RFC 9000 §17.2, §17.3.1), which the caller is to close the connection over.
quicDecryptPayload
Decrypts the payload of the packet header describes, whose header in the clear quicUnprotectHeader answered as clear (RFC 9001 §5.3), without changing datagram.
quicInitialSecrets
The secrets of RFC 9001 §5.2 for the client's first Destination Connection ID, dcid: initial_secret is HKDF-Extract under version 1's salt, and the client's and the server's are expanded from it with the labels client in and server in.
quicInitialSecretsInto
quicInitialSecrets of the Destination Connection ID buf[at .. at + length), read in place, into client and server, 32 bytes each.
quicKeyUpdateSecret
The next generation's traffic secret for a key update (RFC 9001 §6.1): HKDF-Expand-Label(trafficSecret, quic ku, "", Hash.length), taken and answered as a Secret the caller wipes.
quicKeyUpdateSecretHeldInto
quicKeyUpdateSecret from one held secret into another (RFC 9001 §6.1): HKDF-Expand-Label(src, quic ku, "", Hash.length) written over dst's bytes in place, under SHA-384 for a 48-byte secret and SHA-256 for a 32-byte one.
quicKeyUpdateSecretInto
quicKeyUpdateSecret into out, which must be exactly the secret's length and not secret itself.
quicKeys
The packet-protection keys of RFC 9001 §5.1 from a traffic secret, held as a Secret the caller still owns and wipes, derived into slot, which the caller owns too: the AEAD key (quic key), the IV (quic iv) and the header-protection key (quic hp), each HKDF-Expand-Label with an empty context under the hash aead pairs with, written into the slot's arrays and the AES schedules expanded there.
quicKeysHeldInto
quicKeysInto from a traffic secret held as a Secret: the packet key, IV and header-protection key derived from it straight into the slot's arrays, the plain output of each derivation wiped, and the AES schedules expanded in place inside an arena block.
quicKeysInto
quicKeys into slot: the packet key, IV and header-protection key of RFC 9001 §5.1 derived from secret straight into the slot's arrays, in kdf, with the AES schedules expanded in place.
quicKeysUpdate
The next generation's keys in a key update (RFC 9001 §6), derived into slot, which the caller owns and which must not be the slot keys live in: the packet key and IV from nextSecret, which quicKeyUpdateSecret made from the current secret and the caller still owns, read through a plain copy inside an arena block that is zeroed, and keys' header-protection key kept, since header protection never changes with the phase.
quicKeysUpdateInto
quicKeysUpdate into slot, which must not be the slot keys live in: the next generation's packet key and IV from nextSecret, and keys' header-protection key shared, as every generation shares it (RFC 9001 §6).
quicKeysWipe
Zeroes every array keys holds: the packet key, the IV and the header-protection key with secureZero, and each AES schedule with aesKeyWipe, whose volatile stores reach the whole of roundKeys (the kernels' powers of H included) and H itself.
quicLongHeader
The unprotected long header of an Initial, 0-RTT or Handshake packet (RFC 9000 §17.2), ending with the packet number in pnLength bytes, for a payload of payloadLength bytes that quicSealPacket will protect.
quicLongHeaderSize
The size of the long header quicPutLongHeader writes for these arguments, or 0 when it would refuse them (see quicLongHeader).
quicOpenPacket
Opens one packet of a datagram (RFC 9001 §5.3, §5.4): header protection off, the packet number recovered against largestPn (or -1), and the payload decrypted.
quicPacketCopy
Writes bytes[from .. from + length) into buf at at, as one slice copy; the caller has checked both windows.
quicPacketGrow
Appends count zero bytes to out, which a writer then fills in place with the put form of what it appends: one encoder serves both.
quicPacketNumberDecode
The full packet number from the pnLength-byte truncatedPn on the wire, given largestPn, the largest packet number this endpoint has processed in that space, or -1 for none (RFC 9000 §17.1, §A.3): the one closest to largestPn + 1 whose low bytes are truncatedPn.
quicPacketNumberLength
How many bytes to send packet number fullPn in (RFC 9000 §17.1, §A.2), when largestAcked is the largest the peer has acknowledged in its space, or -1 if none: enough that twice the unacknowledged range fits, 1 to 4.
quicParseHeader
Parses the header of the packet starting at datagram[at], which is how a datagram of coalesced packets is walked: parse at 0, then at the answer's end, until end is the datagram's length (RFC 9000 §12.2).
quicParseHeaderInto
Parses the header of the packet starting at datagram[at] into header, filling only its numbers and the windows of its connection IDs and token (dcidStart, dcidLength and the rest), so nothing is copied or allocated: the form a connection reads every packet with.
quicPutLongHeader
Writes into buf at at the unprotected long header quicLongHeader answers, with the connection IDs the first dcidLength and scidLength bytes of dcid and scid, and answers the offset past it: where the payload goes.
quicPutShortHeader
Writes into buf at at the unprotected short header quicShortHeader answers, with the Destination Connection ID the first dcidLength bytes of dcid, and answers the offset past it.
quicRemoveHeaderProtection
Removes header protection from the packet header describes (RFC 9001 §5.4.1): the answer's firstByte, pnLength, packetNumber, keyPhase and header are filled in, the packet number recovered against largestPn, the largest this endpoint has processed in the packet's space (or -1).
quicRetryIntegrityTag
The Retry integrity tag of RFC 9001 §5.8: AES-128-GCM under version 1's fixed key and nonce over an empty plaintext, with the Retry pseudo-packet — odcid's length and bytes, then the Retry packet up to its tag — as the associated data.
quicRetryPacket
A whole Retry packet (RFC 9000 §17.2.5, RFC 9001 §5.8): the long header with unused in the first byte's low four bits (the server picks them; mask them with randomness), the client's SCID as dcid, the server's new SCID, the address-validation token, and the integrity tag over odcid, the DCID the client's Initial was sent to.
quicRetryVerify
Whether the Retry header describes carries a valid integrity tag for odcid, the DCID of the Initial this client sent (RFC 9001 §5.8).
quicSealInPlace
Protects one packet in place (RFC 9001 §5.3, §5.4.1).
quicSealPacket
Protects one packet (RFC 9001 §5.3, §5.4.1): header is what quicLongHeader or quicShortHeader built, ending with the packet number, and packetNumber is the full number its last bytes truncate.
quicShortHeader
The unprotected short header of a 1-RTT packet (RFC 9000 §17.3.1): the first byte with the spin and key-phase bits, the Destination Connection ID and the packet number in pnLength bytes.
quicUnprotectHeader
Removes header protection from the packet header describes (RFC 9001 §5.4.1) without changing datagram: packet's error, firstByte, pnLength, packetNumber and keyPhase are set, and the answer is the header in the clear, packet number included, which is the AEAD's associated data: empty when error is not QUIC_PACKET_OK.
quicVarintLength
The length of the variable-length integer whose first byte is at bytes[at], read from its two-bit prefix: 1, 2, 4 or 8.
quicVarintPush
Appends value to out as a variable-length integer in the fewest bytes (RFC 9000 §16).
quicVarintPushSized
Appends value to out as a variable-length integer of exactly size bytes, as quicVarintPut writes it.
quicVarintPut
Writes value into buf[at .. at + size) as a variable-length integer of exactly size bytes, which may be longer than it needs (RFC 9000 §16 allows that, and a Length field written before its packet is complete uses it).
quicVarintRead
The variable-length integer at bytes[at] (RFC 9000 §16, §A.1), read only from bytes[at .. end).
quicVarintSize
The bytes a variable-length integer needs (RFC 9000 §16): 1, 2, 4 or 8, or 0 for a value that has no encoding, below zero or past 2^62 - 1.
QuicHeader
One packet's header as quicParseHeader read it from a datagram.
QuicInitialSecrets
The two Initial secrets RFC 9001 §5.2 derives from the client's first Destination Connection ID.
QuicKeys
One packet's protection keys (RFC 9001 §5.1): the AEAD's key and IV, and the header-protection key, all derived from one traffic secret by quicKeys.
QuicKeysSlot
The storage one direction of one level's packet keys lives in for a connection slot (QUIC-3): a key and a header-protection key of each length, the IV, and an AES key schedule of each size for each, made once, and the QuicKeys that quicKeysInto and quicKeysUpdateInto point at the ones the negotiated AEAD uses.
QuicPacket
One packet with its protection removed by quicOpenPacket, or as far as that got.
Sans-IO
The module takes bytes in and gives bytes out, with no socket and no clock. It
frames and protects packets and stops there, so it knows nothing of frames,
of a connection's state or of which keys a level is on; that is
nish/net/quic (WP34 Q2). Only version 1 (0x00000001) is spoken. A long
header of another version is parsed as far as RFC 8999's invariants go,
which is what a server needs to send Version Negotiation, and reported as
QUIC_ERR_VERSION.
What a parse refuses. Every read is bounds-checked against the datagram, so nothing a peer sends can make this module panic.
A header that runs past the datagram is QUIC_ERR_TRUNCATED; a clear fixed
bit QUIC_ERR_FIXED_BIT; a connection ID over 20 bytes in a version 1 header
QUIC_ERR_CID_LENGTH; a Length field reaching past the datagram
QUIC_ERR_LENGTH; a packet too short to sample for header protection
QUIC_ERR_SAMPLE; a payload that does not authenticate QUIC_ERR_DECRYPT;
and nonzero reserved bits once both protections are off
QUIC_ERR_RESERVED_BITS, which RFC 9000 §17.2 makes a connection error
rather than a drop, so the payload is still handed back with it. The
builders, whose inputs come from this side rather than from a peer, answer
null for an argument out of range.
In place
For a connection that allocates nothing per packet,
quicParseHeaderInto reads a header as windows into the datagram, the
quicPut* builders write a header into a caller's buffer, quicSealInPlace
seals a packet where it lies, and quicUnprotectHeader and
quicDecryptPayload open one storing only numbers into the QuicPacket
they are given. The AEADs allocate; quicSealInPlace releases what they
allocated before it answers, and the opening halves answer arrays the
caller releases, inside its own arena block.
Coalesced packets
Coalesced packets (RFC 9000 §12.2) are split by length: a long header
carries its own Length, and QuicHeader.end is where the next packet in the
datagram starts. A short header has none, so it runs to the datagram's end.
Secrets
QuicKeys holds a packet key, an IV and a header-protection
key, pointing into a QuicKeysSlot's arrays. quicKeys and quicKeysUpdate
take a traffic secret as a Secret from nish:secret and a slot the caller
owns, and derive into the slot; a slot the caller owns is the caller's to
wipe, and QuicKeysSlot.wipe zeroes it with stores no optimiser removes, AES
schedules included (QUIC-1). quicKeyUpdateSecret answers the next secret as
a Secret, and every derivation wipes its HKDF intermediates before it
returns. quicKeysWipe zeroes the arrays one QuicKeys points at.
The Initial keys are not secret, because anyone who reads the client's first
DCID can derive them (RFC 9001 §5.2), so quicInitialSecrets answers plain
arrays, and quicKeysInto, quicKeysUpdateInto, quicKeyUpdateSecretInto
and quicInitialSecretsInto derive from plain secrets over a caller's
HkdfScratch; the Handshake and 1-RTT keys are secret. Each derivation's own
temporaries go with its arena block. A slot whose traffic secret is held as a
Secret may also derive with quicKeysHeldInto, and ratchet the secret in
place with quicKeyUpdateSecretHeldInto. Sealing and opening a packet wipe
the nonce, which gives the IV away, and the header-protection mask once each
is used (QUIC-2).
Constant time
The AEADs and the header-protection masks are
nish/crypto/aes and nish/crypto/chacha20poly1305, with their guarantees.
What this module branches on is public: lengths, the packet type, the
packet number once header protection is off (it is in the clear to anyone
who holds the header-protection key, and RFC 9001 §5.4.1 protects it against
observers, not timing), and whether a payload authenticated.
Provenance
Written from RFC 9000 and RFC 9001, in this module's own structure: nothing here is ported from another implementation. The packet-number decoding follows the arithmetic of RFC 9000 §A.3 and the length choice the rule of §A.2, neither line by line.
Private names
They carry the quicPacket prefix because a std/ module's
private functions share the importing program's flat symbol namespace
(docs/wp26-stdlib.md §3e).
Functions
quicDecryptPacket
Decrypts the payload of a packet whose header protection
quicRemoveHeaderProtection took off (RFC 9001 §5.3), filling in
packet.payload and setting packet.error: QUIC_ERR_KEYS for keys
quicKeys did not make, QUIC_ERR_DECRYPT when it does not authenticate
under keys, and QUIC_ERR_RESERVED_BITS when it
does but the header's reserved bits are not zero (RFC 9000 §17.2, §17.3.1),
which the caller is to close the connection over. Answers whether the
payload authenticated. A packet already in error is left as it is.
const quicDecryptPacket: (
keys: QuicKeys,
datagram: u8[],
header: QuicHeader,
packet: QuicPacket,
) => boolean
keysQuicKeysrequiredThe level's keys, as quicKeys or one of its Into forms made them.
datagramu8[]requiredThe received bytes header was parsed from, only read.
headerQuicHeaderrequiredThe packet's parsed header.
packetQuicPacketrequiredWhat quicRemoveHeaderProtection answered for this packet.
returnsboolean
True when the payload authenticated, QUIC_ERR_RESERVED_BITS included, so read
packet.error too.
quicDecryptPayload
Decrypts the payload of the packet header describes, whose header in the
clear quicUnprotectHeader answered as clear (RFC 9001 §5.3), without
changing datagram. Sets packet.error as quicDecryptPacket does and
answers the plaintext frames, or null when they did not authenticate
(or packet was already in error). Only numbers are stored into packet.
const quicDecryptPayload: (
keys: QuicKeys,
datagram: u8[],
header: QuicHeader,
clear: u8[],
packet: QuicPacket,
) => u8[] | null
keysQuicKeysrequiredThe level's keys, as quicKeys or one of its Into forms made them.
datagramu8[]requiredThe received bytes header was parsed from, only read.
headerQuicHeaderrequiredThe packet's parsed header.
clearu8[]requiredWhat quicUnprotectHeader answered for this packet: the AEAD's associated data.
packetQuicPacketrequiredThe result quicUnprotectHeader filled for this packet; only its error is changed.
returnsu8[] | nullA new array holding the frames, also for QUIC_ERR_RESERVED_BITS, or null.
quicInitialSecrets
The secrets of RFC 9001 §5.2 for the client's first Destination Connection
ID, dcid: initial_secret is HKDF-Extract under version 1's salt, and the
client's and the server's are expanded from it with the labels client in
and server in. Answers null for a dcid over 20 bytes.
const quicInitialSecrets: (
dcid: u8[],
) => QuicInitialSecrets | null
dcidu8[]requiredThe Destination Connection ID of the client's first Initial, 0 to 20 bytes.
returnsQuicInitialSecrets | nullThe two 32-byte secrets as plain arrays, which are not secret, or null.
quicInitialSecretsInto
quicInitialSecrets of the Destination Connection ID buf[at .. at + length), read in place, into client and server, 32 bytes each.
Answers whether it derived: not for an ID over 20 bytes, a window outside
buf, or an output of another length.
const quicInitialSecretsInto: (
kdf: HkdfScratch,
buf: u8[],
at: i32,
length: i32,
client: u8[],
server: u8[],
) => boolean
kdfHkdfScratchrequired
The caller's HKDF scratch, reused across derivations; its secret-bearing fields are wiped
before each returns (its info label is not).
bufu8[]requiredThe bytes holding the client's first Destination Connection ID, such as the datagram.
ati32requiredThe byte offset in buf where the ID starts.
lengthi32requiredThe ID's length in bytes, 0 to 20.
clientu8[]requiredThe 32-byte array client_initial_secret is written over.
serveru8[]requiredThe 32-byte array server_initial_secret is written over.
returnsbooleanTrue when both secrets were written; false, both untouched, otherwise.
quicKeyUpdateSecret
The next generation's traffic secret for a key update (RFC 9001 §6.1):
HKDF-Expand-Label(trafficSecret, quic ku, "", Hash.length), taken and
answered as a Secret the caller wipes. The header-protection key does
not change with it (§6), so the new keys are quicKeysUpdate of the old
keys and this. Answers null where quicKeys would.
const quicKeyUpdateSecret: (
aead: i32,
trafficSecret: Secret<u8[]>,
) => Secret<u8[]> | null
aeadi32requiredThe negotiated suite, one of the QUIC_AEAD_* constants.
trafficSecretSecret<u8[]>requiredThe current generation's traffic secret; borrowed, and left for the caller to wipe.
returnsSecret<u8[]> | nullThe next generation's secret, a new Secret the caller owns and wipes, or null.
quicKeyUpdateSecretHeldInto
quicKeyUpdateSecret from one held secret into another (RFC 9001 §6.1):
HKDF-Expand-Label(src, quic ku, "", Hash.length) written over dst's
bytes in place, under SHA-384 for a 48-byte secret and SHA-256 for a
32-byte one. dst may be src, which ratchets it. Answers whether it
derived: not unless both hold 32 bytes or both 48.
const quicKeyUpdateSecretHeldInto: (
dst: Secret<u8[]>,
src: Secret<u8[]>,
) => boolean
dstSecret<u8[]>requiredThe secret overwritten with the next generation's; the caller's, and the caller wipes it.
srcSecret<u8[]>requiredThe current generation's secret; borrowed, and not wiped here unless it is dst.
returnsbooleanTrue when dst holds the next secret; false, both untouched, for mismatched or wrong lengths.
quicKeyUpdateSecretInto
quicKeyUpdateSecret into out, which must be exactly the secret's
length and not secret itself. Answers whether it derived, which it does
where quicKeyUpdateSecret answers a secret.
const quicKeyUpdateSecretInto: (
kdf: HkdfScratch,
aead: i32,
secret: u8[],
out: u8[],
) => boolean
kdfHkdfScratchrequired
The caller's HKDF scratch, reused across derivations; its secret-bearing fields are wiped
before each returns (its info label is not).
aeadi32requiredThe negotiated suite, one of the QUIC_AEAD_* constants.
secretu8[]requiredThe current traffic secret as a plain array; only read, and not wiped.
outu8[]requiredThe array the next secret is written over, 32 bytes (48 for AES-256-GCM).
returnsbooleanTrue when out holds the next secret; false, out untouched, for a wrong length or aead.
quicKeys
The packet-protection keys of RFC 9001 §5.1 from a traffic secret, held as a
Secret the caller still owns and wipes, derived into slot, which the
caller owns too: the AEAD key (quic key), the IV (quic iv) and the
header-protection key (quic hp), each HKDF-Expand-Label with an empty
context under the hash aead pairs with, written into the slot's arrays and
the AES schedules expanded there.
The secret is read through a plain copy inside an arena block, which is
zeroed, and the derivation's temporaries go with the block, so the call keeps
in the arena only the HkdfScratch it makes for the derivation, which wipes
itself before the derivation returns. Answers the slot's keys, which the next
derivation into it overwrites and QuicKeysSlot.wipe zeroes, or null,
deriving nothing, for an aead this module does not know or a secret that is
not that hash's length. The Initial secrets are public (RFC 9001 §5.2), so a
caller deriving Initial keys wraps a copy of one in secret, or uses
quicKeysInto.
const quicKeys: (
slot: QuicKeysSlot,
aead: i32,
trafficSecret: Secret<u8[]>,
) => QuicKeys | null
slotQuicKeysSlotrequiredThe caller's slot to derive into; its earlier keys are overwritten.
aeadi32requiredThe negotiated suite, one of the QUIC_AEAD_* constants.
trafficSecretSecret<u8[]>requiredThe level's traffic secret, 32 bytes (48 for AES-256-GCM); borrowed: it is not wiped here, and the caller wipes it once no more keys come from it.
returnsQuicKeys | nullslot.keys, valid until the slot is derived into again or wiped, or null.
quicKeysHeldInto
quicKeysInto from a traffic secret held as a Secret: the packet key, IV
and header-protection key derived from it straight into the slot's arrays,
the plain output of each derivation wiped, and the AES schedules expanded
in place inside an arena block. Answers the slot's keys, or null,
deriving nothing, where quicKeys answers null.
const quicKeysHeldInto: (
slot: QuicKeysSlot,
aead: i32,
secret: Secret<u8[]>,
) => QuicKeys | null
slotQuicKeysSlotrequiredThe caller's slot to derive into; its earlier keys are overwritten.
aeadi32requiredThe negotiated suite, one of the QUIC_AEAD_* constants.
secretSecret<u8[]>requiredThe traffic secret, 32 bytes (48 for AES-256-GCM); borrowed, and left for the caller to wipe.
returnsQuicKeys | nullslot.keys, valid until the slot is derived into again or wiped, or null.
quicKeysInto
quicKeys into slot: the packet key, IV and header-protection key of
RFC 9001 §5.1 derived from secret straight into the slot's arrays, in
kdf, with the AES schedules expanded in place. Answers the slot's keys,
or null, deriving nothing, where quicKeys answers null. The keys
are the slot's: the next derivation into it overwrites them.
const quicKeysInto: (
kdf: HkdfScratch,
slot: QuicKeysSlot,
aead: i32,
secret: u8[],
) => QuicKeys | null
kdfHkdfScratchrequired
The caller's HKDF scratch, reused across derivations; its secret-bearing fields are wiped
before each returns (its info label is not).
slotQuicKeysSlotrequiredThe caller's slot to derive into; its earlier keys are overwritten.
aeadi32requiredThe negotiated suite, one of the QUIC_AEAD_* constants.
secretu8[]requiredThe traffic secret as a plain array, 32 bytes (48 for AES-256-GCM); only read, and not wiped, so a caller passing a non-Initial secret wipes it.
returnsQuicKeys | nullslot.keys, valid until the slot is derived into again or wiped, or null.
quicKeysUpdate
The next generation's keys in a key update (RFC 9001 §6), derived into
slot, which the caller owns and which must not be the slot keys live in:
the packet key and IV from nextSecret, which quicKeyUpdateSecret made
from the current secret and the caller still owns, read through a plain copy
inside an arena block that is zeroed, and keys' header-protection key kept,
since header protection never changes with the phase.
The new generation holds its own copy of that key and its own schedule, in
the slot, so wiping one generation leaves the other usable. Answers the
slot's keys, or null, deriving nothing, for keys quicKeys did not make,
keys that live in slot, or a secret of the wrong length.
const quicKeysUpdate: (
slot: QuicKeysSlot,
keys: QuicKeys,
nextSecret: Secret<u8[]>,
) => QuicKeys | null
slotQuicKeysSlotrequiredThe caller's slot for the next generation; a different slot from the one keys live in.
keysQuicKeysrequiredThe current generation's keys, whose header-protection key is copied; left unchanged.
nextSecretSecret<u8[]>requiredThe next generation's traffic secret; borrowed, and left for the caller to wipe.
returnsQuicKeys | nullslot.keys, valid until the slot is derived into again or wiped, or null.
quicKeysUpdateInto
quicKeysUpdate into slot, which must not be the slot keys live in:
the next generation's packet key and IV from nextSecret, and keys'
header-protection key shared, as every generation shares it (RFC 9001
§6). Answers the slot's keys, or null where quicKeysUpdate does.
Unlike quicKeysUpdate the header-protection key and its schedule are the
same arrays as keys', not a copy, so wiping either generation zeroes the
header-protection key both use.
const quicKeysUpdateInto: (
kdf: HkdfScratch,
slot: QuicKeysSlot,
keys: QuicKeys,
nextSecret: u8[],
) => QuicKeys | null
kdfHkdfScratchrequired
The caller's HKDF scratch, reused across derivations; its secret-bearing fields are wiped
before each returns (its info label is not).
slotQuicKeysSlotrequiredThe caller's slot for the next generation; a different slot from the one keys live in.
keysQuicKeysrequiredThe current generation's keys, whose header-protection arrays are shared; left unchanged.
nextSecretu8[]requiredThe next generation's traffic secret as a plain array; only read, and not wiped.
returnsQuicKeys | nullslot.keys, valid until the slot is derived into again or wiped, or null.
quicKeysWipe
Zeroes every array keys holds: the packet key, the IV and the
header-protection key with secureZero, and each AES schedule with
aesKeyWipe, whose volatile stores reach the whole of roundKeys (the
kernels' powers of H included) and H itself. It zeroes the arrays keys
points at now; a slot's arrays of the other lengths are
QuicKeysSlot.wipe's, which zeroes them all.
const quicKeysWipe: (keys: QuicKeys) => void
keysQuicKeysrequiredThe keys to zero. Nothing marks them wiped and nothing refuses them afterwards, so derive into them again before sealing or opening with them.
quicLongHeader
The unprotected long header of an Initial, 0-RTT or Handshake packet
(RFC 9000 §17.2), ending with the packet number in pnLength bytes, for a
payload of payloadLength bytes that quicSealPacket will protect. The
Length field counts the packet number, the payload and the AEAD tag, and is
always written in two bytes (RFC 9000 §16 allows the longer form), so the
header's size does not move with the payload's and a caller padding a
packet to a size knows the header first. token goes in an Initial and
must be empty otherwise.
Answers null for another type, a connection ID over 20 bytes, a token
on a non-Initial packet, a pnLength outside 1 to 4, a packet number that
is not one, a negative payloadLength, or a Length past 16383, the most two
bytes hold and far more than a datagram carries.
const quicLongHeader: (
type: i32,
dcid: u8[],
scid: u8[],
token: u8[],
packetNumber: i64,
pnLength: i32,
payloadLength: i32,
) => u8[] | null
typei32requiredQUIC_PACKET_INITIAL, QUIC_PACKET_ZERO_RTT or QUIC_PACKET_HANDSHAKE.
dcidu8[]requiredThe Destination Connection ID, 0 to 20 bytes.
scidu8[]requiredThe Source Connection ID, 0 to 20 bytes.
tokenu8[]requiredAn Initial's token, or empty.
packetNumberi64requiredThe full packet number, 0 to 2^62 - 1; its low pnLength bytes are written.
pnLengthi32requiredThe packet number's length on the wire, 1 to 4 bytes.
payloadLengthi32requiredThe plaintext payload's length in bytes, without the AEAD tag.
returnsu8[] | nullA new array holding the header, or null for an argument out of range.
quicLongHeaderSize
The size of the long header quicPutLongHeader writes for these
arguments, or 0 when it would refuse them (see quicLongHeader).
const quicLongHeaderSize: (
type: i32,
dcidLength: i32,
scidLength: i32,
tokenLength: i32,
packetNumber: i64,
pnLength: i32,
payloadLength: i32,
) => i32
typei32requiredQUIC_PACKET_INITIAL, QUIC_PACKET_ZERO_RTT or QUIC_PACKET_HANDSHAKE.
dcidLengthi32requiredThe Destination Connection ID's length in bytes, 0 to 20.
scidLengthi32requiredThe Source Connection ID's length in bytes, 0 to 20.
tokenLengthi32requiredThe token's length in bytes; 0 for anything but an Initial.
packetNumberi64requiredThe full packet number, 0 to 2^62 - 1; only range-checked, as the size does not depend on it.
pnLengthi32requiredThe packet number's length on the wire, 1 to 4 bytes.
payloadLengthi32requiredThe plaintext payload's length in bytes, without the AEAD tag.
returnsi32The header's length in bytes, packet number included, or 0 for an argument out of range.
quicOpenPacket
Opens one packet of a datagram (RFC 9001 §5.3, §5.4): header protection
off, the packet number recovered against largestPn (or -1), and the
payload decrypted. The answer's error is QUIC_PACKET_OK with payload
holding the frames, or the QUIC_ERR_* of the step that failed — see
quicRemoveHeaderProtection and quicDecryptPacket.
const quicOpenPacket: (
keys: QuicKeys,
datagram: u8[],
header: QuicHeader,
largestPn: i64,
) => QuicPacket
keysQuicKeysrequiredThe level's keys, as quicKeys or one of its Into forms made them.
datagramu8[]requiredThe received bytes header was parsed from, only read.
headerQuicHeaderrequiredThe packet's parsed header.
largestPni64requiredThe largest packet number processed in the packet's space, or -1 for none.
returnsQuicPacketA new QuicPacket; read its error before any other field.
quicPacketCopy
Writes bytes[from .. from + length) into buf at at, as one slice copy; the caller has checked both windows.
The part of the run outside either window is skipped rather than written, so a wrong window cannot panic.
const quicPacketCopy: (
buf: u8[],
at: i32,
bytes: u8[],
from: i32,
length: i32,
) => void
bufu8[]requiredThe buffer to write into; it is not grown.
ati32requiredThe byte offset in buf of the first byte written.
bytesu8[]requiredThe bytes to copy from.
fromi32requiredThe byte offset in bytes of the first byte copied.
lengthi32requiredHow many bytes to copy.
quicPacketGrow
Appends count zero bytes to out, which a writer then fills in place
with the put form of what it appends: one encoder serves both.
const quicPacketGrow: (out: u8[], count: i32) => void
outu8[]requiredThe array to lengthen.
counti32requiredHow many zero bytes to append; 0 or less appends none.
quicPacketNumberDecode
The full packet number from the pnLength-byte truncatedPn on the wire,
given largestPn, the largest packet number this endpoint has processed in
that space, or -1 for none (RFC 9000 §17.1, §A.3): the one closest to
largestPn + 1 whose low bytes are truncatedPn. Answers -1 when
pnLength is not 1 to 4 or truncatedPn does not fit in it.
const quicPacketNumberDecode: (
largestPn: i64,
truncatedPn: i64,
pnLength: i32,
) => i64
largestPni64requiredThe largest packet number processed in this space, or -1 for none.
truncatedPni64requiredThe packet number's low bytes as the header carried them, below 2^(8 × pnLength).
pnLengthi32requiredThe packet number's length on the wire, 1 to 4 bytes.
returnsi64The full packet number, 0 to 2^62 - 1, or -1 for an argument out of range.
quicPacketNumberLength
How many bytes to send packet number fullPn in (RFC 9000 §17.1, §A.2),
when largestAcked is the largest the peer has acknowledged in its space,
or -1 if none: enough that twice the unacknowledged range fits, 1 to 4.
Answers 0 when no length will do — fullPn not above largestAcked, not a
packet number, or more than 2^31 packets unacknowledged.
const quicPacketNumberLength: (
fullPn: i64,
largestAcked: i64,
) => i32
fullPni64requiredThe packet number about to be sent, 0 to 2^62 - 1.
largestAckedi64requiredThe largest packet number the peer has acknowledged in this space, or -1 for none.
returnsi32The packet-number length in bytes, 1 to 4, or 0 when none will do.
quicParseHeader
Parses the header of the packet starting at datagram[at], which is how a
datagram of coalesced packets is walked: parse at 0, then at the answer's
end, until end is the datagram's length (RFC 9000 §12.2).
shortDcidLength is the length of the connection IDs this endpoint hands
out, which is the only way to know where a short header's DCID ends
(RFC 9000 §17.3.1); one outside 0 to 20 reads as QUIC_ERR_TRUNCATED.
The connection IDs, the token and a Retry's tag are copied out into the
answer's arrays; quicParseHeaderInto reads the same without a copy.
The answer's error says what stopped it; nothing a peer sends panics.
const quicParseHeader: (
datagram: u8[],
at: i32,
shortDcidLength: i32,
) => QuicHeader
datagramu8[]requiredThe received bytes, only read; the datagram runs to the array's end.
ati32requiredThe byte offset where the packet starts.
shortDcidLengthi32requiredThe length in bytes of the connection IDs this endpoint hands out, 0 to 20.
returnsQuicHeaderA new QuicHeader; read its error before any other field.
quicParseHeaderInto
Parses the header of the packet starting at datagram[at] into header,
filling only its numbers and the windows of its connection IDs and token
(dcidStart, dcidLength and the rest), so nothing is copied or
allocated: the form a connection reads every packet with. Answers
header.error. Every field is reset first, so one QuicHeader serves
every packet; its dcid, scid, token and retryTag arrays are left
as they were. The datagram is datagram[at .. limit), so one buffer can
hold several (a GRO receive); a limit past the array reads as its length.
See quicParseHeader for what is read and refused.
const quicParseHeaderInto: (
header: QuicHeader,
datagram: u8[],
at: i32,
limit: i32,
shortDcidLength: i32,
) => i32
headerQuicHeaderrequiredThe header to overwrite; its windows index into datagram.
datagramu8[]requiredThe received bytes, only read.
ati32requiredThe byte offset where the packet starts.
limiti32requiredThe byte offset one past the datagram's end.
shortDcidLengthi32requiredThe length in bytes of the connection IDs this endpoint hands out, 0 to 20.
returnsi32QUIC_PACKET_OK, or the QUIC_ERR_* that stopped the parse.
quicPutLongHeader
Writes into buf at at the unprotected long header quicLongHeader
answers, with the connection IDs the first dcidLength and scidLength
bytes of dcid and scid, and answers the offset past it: where the
payload goes. Answers -1, writing nothing, where quicLongHeader answers
null, and for a header that does not fit in buf from at.
const quicPutLongHeader: (
buf: u8[],
at: i32,
type: i32,
dcid: u8[],
dcidLength: i32,
scid: u8[],
scidLength: i32,
token: u8[],
packetNumber: i64,
pnLength: i32,
payloadLength: i32,
) => i32
bufu8[]requiredThe buffer to write into; it is not grown.
ati32requiredThe byte offset in buf where the packet starts.
typei32requiredQUIC_PACKET_INITIAL, QUIC_PACKET_ZERO_RTT or QUIC_PACKET_HANDSHAKE.
dcidu8[]requiredThe bytes holding the Destination Connection ID at their start.
dcidLengthi32requiredHow many bytes of dcid are the ID, 0 to 20.
scidu8[]requiredThe bytes holding the Source Connection ID at their start.
scidLengthi32requiredHow many bytes of scid are the ID, 0 to 20.
tokenu8[]requiredThe whole of an Initial's token; empty for the other types.
packetNumberi64requiredThe full packet number, 0 to 2^62 - 1; its low pnLength bytes are written.
pnLengthi32requiredThe packet number's length on the wire, 1 to 4 bytes.
payloadLengthi32requiredThe plaintext payload's length in bytes, without the AEAD tag.
returnsi32The byte offset one past the packet number, where the payload goes, or -1 when nothing was written.
quicPutShortHeader
Writes into buf at at the unprotected short header quicShortHeader
answers, with the Destination Connection ID the first dcidLength bytes of
dcid, and answers the offset past it. Answers -1, writing nothing, where
quicShortHeader answers null, and for a header that does not fit.
const quicPutShortHeader: (
buf: u8[],
at: i32,
dcid: u8[],
dcidLength: i32,
spin: boolean,
keyPhase: boolean,
packetNumber: i64,
pnLength: i32,
) => i32
bufu8[]requiredThe buffer to write into; it is not grown.
ati32requiredThe byte offset in buf where the packet starts.
dcidu8[]requiredThe bytes holding the Destination Connection ID at their start.
dcidLengthi32requiredHow many bytes of dcid are the ID, 0 to 20.
spinbooleanrequiredThe latency spin bit (RFC 9000 §17.4).
keyPhasebooleanrequiredThe Key Phase bit, which says which generation of 1-RTT keys protects the packet (RFC 9001 §6).
packetNumberi64requiredThe full packet number, 0 to 2^62 - 1; its low pnLength bytes are written.
pnLengthi32requiredThe packet number's length on the wire, 1 to 4 bytes.
returnsi32The byte offset one past the packet number, where the payload goes, or -1 when nothing was written.
quicRemoveHeaderProtection
Removes header protection from the packet header describes (RFC 9001
§5.4.1): the answer's firstByte, pnLength, packetNumber, keyPhase
and header are filled in, the packet number recovered against
largestPn, the largest this endpoint has processed in the packet's space
(or -1). The header-protection key never changes with a key update, so a
caller holding two generations of keys calls this, reads keyPhase, and
hands the answer to quicDecryptPacket with the generation it names
(RFC 9001 §6.3).
error is the header's own for a header that did not parse,
QUIC_ERR_NOT_PROTECTED for a Retry, QUIC_ERR_KEYS for keys quicKeys
did not make, and QUIC_ERR_SAMPLE for a packet too short to sample.
const quicRemoveHeaderProtection: (
keys: QuicKeys,
datagram: u8[],
header: QuicHeader,
largestPn: i64,
) => QuicPacket
keysQuicKeysrequiredThe level's keys; the whole set must be usable, though only the header-protection key is used.
datagramu8[]requiredThe received bytes header was parsed from, only read.
headerQuicHeaderrequiredThe packet's parsed header.
largestPni64requiredThe largest packet number processed in the packet's space, or -1 for none.
returnsQuicPacketA new QuicPacket with no payload yet; read its error before any other field.
quicRetryIntegrityTag
The Retry integrity tag of RFC 9001 §5.8: AES-128-GCM under version 1's
fixed key and nonce over an empty plaintext, with the Retry pseudo-packet —
odcid's length and bytes, then the Retry packet up to its tag — as the
associated data. odcid is the Destination Connection ID of the client's
Initial the Retry answers. Answers null for an odcid over 20 bytes.
const quicRetryIntegrityTag: (
odcid: u8[],
retryWithoutTag: u8[],
) => u8[] | null
odcidu8[]requiredThe Destination Connection ID of the client's first Initial, 0 to 20 bytes.
retryWithoutTagu8[]requiredThe Retry packet from its first byte to just before the tag, only read.
returnsu8[] | nullThe 16-byte tag as a new array, or null.
quicRetryPacket
A whole Retry packet (RFC 9000 §17.2.5, RFC 9001 §5.8): the long header with
unused in the first byte's low four bits (the server picks them; mask
them with randomness), the client's SCID as dcid, the server's new SCID,
the address-validation token, and the integrity tag over odcid, the
DCID the client's Initial was sent to. Answers null for a connection ID
over 20 bytes, an empty token (a client discards that Retry, §17.2.5.2) or
unused outside 0 to 15.
const quicRetryPacket: (
dcid: u8[],
scid: u8[],
token: u8[],
odcid: u8[],
unused: i32,
) => u8[] | null
dcidu8[]requiredThe client's Source Connection ID, which the Retry is sent to; 0 to 20 bytes.
scidu8[]requiredThe server's new Source Connection ID, 0 to 20 bytes.
tokenu8[]requiredThe address-validation token the client is to echo; at least one byte.
odcidu8[]requiredThe Destination Connection ID of the client's first Initial, 0 to 20 bytes.
unusedi32requiredThe first byte's four low bits, 0 to 15.
returnsu8[] | nullA new array holding the whole Retry, tag included, or null.
quicRetryVerify
Whether the Retry header describes carries a valid integrity tag for
odcid, the DCID of the Initial this client sent (RFC 9001 §5.8). The tag
is recomputed over the datagram's bytes and compared in constant time.
Answers false for a header that is not a Retry that parsed.
const quicRetryVerify: (
odcid: u8[],
datagram: u8[],
header: QuicHeader,
) => boolean
odcidu8[]requiredThe Destination Connection ID of the Initial this client sent.
datagramu8[]requiredThe received bytes header was parsed from, only read.
headerQuicHeaderrequired
The Retry's header from quicParseHeader, which copies out retryTag;
quicParseHeaderInto leaves that array as it was.
returnsboolean
True when the integrity tag is valid for odcid: the packet was not altered and answers the
Initial that carried that DCID. It authenticates nothing more (RFC 9001 §5.8).
quicSealInPlace
Protects one packet in place (RFC 9001 §5.3, §5.4.1). buf[start .. start + headerLength) is a header quicPutLongHeader or
quicPutShortHeader wrote, ending with the packet number, and the
payloadLength bytes after it are the frames; packetNumber is the full
number the header's last bytes truncate. The payload is sealed where it
lies, its tag written after it, and header protection put on: the answer
is the offset past the tag, which is where the packet ends, or -1, with
buf not to be sent, for anything quicSealPacket refuses and for a tag
that does not fit in buf. The AEAD's temporaries are released before it
answers, so sealing allocates nothing that outlives the call.
const quicSealInPlace: (
keys: QuicKeys,
buf: u8[],
start: i32,
headerLength: i32,
payloadLength: i32,
packetNumber: i64,
) => i32
keysQuicKeysrequiredThe level's keys, as quicKeys or one of its Into forms made them.
bufu8[]requiredThe buffer holding the packet; it is not grown, so it needs 16 bytes of room past the payload.
starti32requiredThe byte offset in buf where the packet starts.
headerLengthi32requiredThe header's length in bytes, packet number included.
payloadLengthi32requiredThe plaintext payload's length in bytes; with the packet number, at least 4.
packetNumberi64requiredThe full packet number the header carries, 0 to 2^62 - 1.
returnsi32The byte offset one past the AEAD tag, or -1 when the packet is not to be sent.
quicSealPacket
Protects one packet (RFC 9001 §5.3, §5.4.1): header is what
quicLongHeader or quicShortHeader built, ending with the packet number,
and packetNumber is the full number its last bytes truncate. The answer
is the header under header protection followed by the AEAD-sealed payload
and its tag, ready to send or to coalesce; quicSealInPlace does the same
in a caller's buffer.
The header and the arguments are held to each other, because a packet that
disagrees with its own header is one the peer silently drops: the header's
packet-number bytes must be packetNumber's low bytes, and a long header's
two-byte Length must count this payload. The sample is the 16 bytes from
4 past the packet number's start, so the packet number and payload together
must be at least 4 bytes; a shorter payload has to be padded first (RFC 9001
§5.4.2). Answers null for any of those, for a header too short for its
packet-number length, and for keys quicKeys did not make.
const quicSealPacket: (
keys: QuicKeys,
header: u8[],
packetNumber: i64,
payload: u8[],
) => u8[] | null
keysQuicKeysrequiredThe level's keys, as quicKeys or one of its Into forms made them.
headeru8[]requiredThe unprotected header, only read.
packetNumberi64requiredThe full packet number the header carries, 0 to 2^62 - 1.
payloadu8[]requiredThe plaintext frames, only read.
returnsu8[] | nullA new array holding the protected packet, 16 bytes longer than header and payload, or null.
quicShortHeader
The unprotected short header of a 1-RTT packet (RFC 9000 §17.3.1): the
first byte with the spin and key-phase bits, the Destination Connection ID
and the packet number in pnLength bytes. Answers null for a connection
ID over 20 bytes, a pnLength outside 1 to 4 or a packet number that is
not one.
const quicShortHeader: (
dcid: u8[],
spin: boolean,
keyPhase: boolean,
packetNumber: i64,
pnLength: i32,
) => u8[] | null
dcidu8[]requiredThe Destination Connection ID, 0 to 20 bytes.
spinbooleanrequiredThe latency spin bit (RFC 9000 §17.4).
keyPhasebooleanrequiredThe Key Phase bit, which says which generation of 1-RTT keys protects the packet (RFC 9001 §6).
packetNumberi64requiredThe full packet number, 0 to 2^62 - 1; its low pnLength bytes are written.
pnLengthi32requiredThe packet number's length on the wire, 1 to 4 bytes.
returnsu8[] | nullA new array holding the header, or null for an argument out of range.
quicUnprotectHeader
Removes header protection from the packet header describes (RFC 9001
§5.4.1) without changing datagram: packet's error, firstByte,
pnLength, packetNumber and keyPhase are set, and the answer is the
header in the clear, packet number included, which is the AEAD's
associated data: empty when error is not QUIC_PACKET_OK. Only numbers
are stored into packet, so a connection reuses one for every packet and
the answer is its own to let go. See quicRemoveHeaderProtection.
const quicUnprotectHeader: (
keys: QuicKeys,
datagram: u8[],
header: QuicHeader,
largestPn: i64,
packet: QuicPacket,
) => u8[]
keysQuicKeysrequiredThe level's keys, as quicKeys or one of its Into forms made them.
datagramu8[]requiredThe received bytes header was parsed from, only read.
headerQuicHeaderrequiredThe packet's parsed header.
largestPni64requiredThe largest packet number processed in the packet's space, or -1 for none.
packetQuicPacketrequiredThe result to overwrite; its header and payload arrays are not touched.
returnsu8[]A new array holding the header in the clear, or an empty one when packet.error is set.
quicVarintLength
The length of the variable-length integer whose first byte is at
bytes[at], read from its two-bit prefix: 1, 2, 4 or 8. Answers 0 when
at is outside bytes.
const quicVarintLength: (bytes: u8[], at: i32) => i32
bytesu8[]requiredThe bytes holding the integer.
ati32requiredThe byte offset of the integer's first byte.
returnsi32The integer's length in bytes, which may run past the end of bytes; or 0.
quicVarintPush
Appends value to out as a variable-length integer in the fewest bytes
(RFC 9000 §16). Answers false, appending nothing, for a value below zero
or past 2^62 - 1.
const quicVarintPush: (out: u8[], value: i64) => boolean
outu8[]requiredThe array to append to.
valuei64requiredThe integer, 0 to 2^62 - 1.
returnsbooleanTrue when the integer was appended.
quicVarintPushSized
Appends value to out as a variable-length integer of exactly size
bytes, as quicVarintPut writes it. Answers false, appending nothing,
when size is not 1, 2, 4 or 8 or is too short for value.
const quicVarintPushSized: (
out: u8[],
value: i64,
size: i32,
) => boolean
outu8[]requiredThe array to append to.
valuei64requiredThe integer, 0 to 2^62 - 1.
sizei32requiredThe encoded length in bytes: 1, 2, 4 or 8, at least quicVarintSize(value).
returnsbooleanTrue when the integer was appended.
quicVarintPut
Writes value into buf[at .. at + size) as a variable-length integer of
exactly size bytes, which may be longer than it needs (RFC 9000 §16
allows that, and a Length field written before its packet is complete uses
it). Answers at + size, or -1, writing nothing, when size is not 1, 2,
4 or 8, is too short for value, or does not fit in buf from at.
const quicVarintPut: (
buf: u8[],
at: i32,
value: i64,
size: i32,
) => i32
bufu8[]requiredThe buffer to write into; it is not grown.
ati32requiredThe byte offset of the integer's first byte.
valuei64requiredThe integer, 0 to 2^62 - 1.
sizei32requiredThe encoded length in bytes: 1, 2, 4 or 8, at least quicVarintSize(value).
returnsi32The byte offset one past the integer, or -1 when nothing was written.
quicVarintRead
The variable-length integer at bytes[at] (RFC 9000 §16, §A.1), read only
from bytes[at .. end). Answers -1, which no varint holds, when it does not
fit in that window or the window is not inside bytes. Advance past it by
quicVarintLength(bytes, at).
const quicVarintRead: (
bytes: u8[],
at: i32,
end: i32,
) => i64
bytesu8[]requiredThe bytes holding the integer.
ati32requiredThe byte offset of the integer's first byte.
endi32requiredThe byte offset the integer must end at or before, at most bytes.length.
returnsi64The integer, 0 to 2^62 - 1, or -1 when it cannot be read.
quicVarintSize
The bytes a variable-length integer needs (RFC 9000 §16): 1, 2, 4 or 8, or 0 for a value that has no encoding, below zero or past 2^62 - 1.
const quicVarintSize: (value: i64) => i32
valuei64requiredThe integer to encode.
returnsi32The encoded length in bytes, or 0 when value has no encoding.
Classes
QuicHeader
One packet's header as quicParseHeader read it from a datagram. The
fields after error are meaningful as far as the parse got: all of them
when error is QUIC_PACKET_OK, and version, dcid and scid for
QUIC_ERR_VERSION, which is what Version Negotiation needs.
The packet number and the low bits of the first byte are still under
header protection here, so the header carries where they are rather than
what they hold; quicOpenPacket reads them.
class QuicHeader
| Member | |
|---|---|
new QuicHeader() |
Makes an empty header, every array empty and every window at 0, for quicParseHeader or quicParseHeaderInto to fill. |
dcid: u8[] |
The Destination Connection ID. |
dcidLength: i32 |
The Destination Connection ID's length in bytes, 0 to 20; a short header's is the length the reader passed. |
dcidStart: i32 |
Where dcid, scid and token sit in the datagram, as far as the parse got. quicParseHeaderInto fills these and nothing else, so a connection reads a header with no copy; quicParseHeader copies the windows out into the arrays above. |
end: i32 |
One past the packet's last byte, which is where the next coalesced packet starts. |
error: i32 |
QUIC_PACKET_OK, or the QUIC_ERR_* that stopped the parse. |
pnOffset: i32 |
Where the protected packet number starts: the header-protection sample starts 4 bytes after it. For a Retry, which has none, where its tag starts. |
retryTag: u8[] |
A Retry's integrity tag, the datagram's last 16 bytes; empty for every other type. |
scid: u8[] |
The Source Connection ID; empty for a short header. |
scidLength: i32 |
The Source Connection ID's length in bytes, 0 to 20; 0 for a short header. |
scidStart: i32 |
Where the Source Connection ID starts in the datagram; 0 for a short header. |
start: i32 |
Where in the datagram the packet starts. |
token: u8[] |
An Initial's token, or a Retry's; empty for every other type. |
tokenLength: i32 |
An Initial's or a Retry's token length in bytes; 0 for every other type. |
tokenStart: i32 |
Where an Initial's or a Retry's token starts in the datagram; 0 for every other type. |
type: i32 |
QUIC_PACKET_INITIAL, _ZERO_RTT, _HANDSHAKE, _RETRY or _SHORT. |
version: i64 |
The long header's 32-bit version, held in an i64; 0 for a short header, which has none. |
QuicInitialSecrets
The two Initial secrets RFC 9001 §5.2 derives from the client's first Destination Connection ID.
class QuicInitialSecrets
| Member | |
|---|---|
new QuicInitialSecrets(client: u8[], server: u8[]) |
Pairs two secrets already derived, keeping the arrays rather than copying them. |
client: u8[] |
client_initial_secret: what protects the client's Initial packets. |
server: u8[] |
server_initial_secret: what protects the server's. |
QuicKeys
One packet's protection keys (RFC 9001 §5.1): the AEAD's key and IV, and
the header-protection key, all derived from one traffic secret by
quicKeys. For the AES suites the two keys are also kept expanded, so a
connection expands them once rather than once a packet.
class QuicKeys
| Member | |
|---|---|
new QuicKeys(aead: i32, key: u8[], iv: u8[], hp: u8[]) |
Wraps keys already derived; the arrays are kept, not copied, so they stay the owner's to wipe. packetAes and hpAes start null; the quicKeys* functions fill them for the AES suites. A QuicKeys built by hand for an AES suite stays unusable: opening refuses it with QUIC_ERR_KEYS, and sealing answers null. |
aead: i32 |
QUIC_AEAD_AES_128_GCM, _AES_256_GCM or _CHACHA20_POLY1305. |
hp: u8[] |
The header-protection key, the same length as key. |
hpAes: AesKey | null |
hp expanded, for the AES suites; null for ChaCha20-Poly1305. |
iv: u8[] |
The 12-byte IV the packet number is XORed into. |
key: u8[] |
The packet-protection key: 16 bytes for AES-128-GCM, 32 for the others. |
packetAes: AesKey | null |
key expanded, for the AES suites; null for ChaCha20-Poly1305. |
QuicKeysSlot
The storage one direction of one level's packet keys lives in for a
connection slot (QUIC-3): a key and a header-protection key of each
length, the IV, and an AES key schedule of each size for each, made once,
and the QuicKeys that quicKeysInto and quicKeysUpdateInto point at
the ones the negotiated AEAD uses. So installing a level's keys, or a key
update's, writes into memory the slot already holds and keeps nothing in
the arena. The slot is its owner's to wipe (QUIC-1): wipe zeroes all of
it.
class QuicKeysSlot
| Member | |
|---|---|
new QuicKeysSlot() |
Makes the slot's arrays and key schedules once, with no keys derived yet (keys.aead is 0). |
hp128: AesKey |
The AES-128 key schedule for header protection, expanded from hp16. |
hp16: u8[] |
The 16-byte header-protection key an AES-128-GCM suite uses. |
hp256: AesKey |
The AES-256 key schedule for header protection, expanded from hp32. |
hp32: u8[] |
The 32-byte header-protection key an AES-256-GCM or ChaCha20-Poly1305 suite uses. |
key16: u8[] |
The 16-byte packet key an AES-128-GCM suite uses. |
key32: u8[] |
The 32-byte packet key an AES-256-GCM or ChaCha20-Poly1305 suite uses. |
keys: QuicKeys |
The keys, pointing into the arrays below; aead is 0 until something is derived. |
packet128: AesKey |
The AES-128 key schedule for packet protection, expanded from key16. |
packet256: AesKey |
The AES-256 key schedule for packet protection, expanded from key32. |
wipe(): void |
Zeroes every key the slot holds: the keys and the IV with secureZero, and each AES schedule with aesKeyWipe, whose volatile stores reach the whole of roundKeys (the kernels' powers of H included) and H itself. |
QuicPacket
One packet with its protection removed by quicOpenPacket, or as far as
that got. With error at QUIC_PACKET_OK or QUIC_ERR_RESERVED_BITS
every field is filled in; with QUIC_ERR_DECRYPT all but payload.
class QuicPacket
| Member | |
|---|---|
new QuicPacket() |
Makes an empty packet, its header and payload empty, for quicOpenPacket to fill. |
error: i32 |
QUIC_PACKET_OK, or the QUIC_ERR_* that stopped the open. |
firstByte: i32 |
The first byte with header protection removed. |
header: u8[] |
The header in the clear, packet number included: the AEAD's associated data. |
keyPhase: boolean |
A short header's Key Phase bit (RFC 9001 §6); false for a long header. |
packetNumber: i64 |
The full packet number, recovered from the truncated one (RFC 9000 §17.1). |
payload: u8[] |
The decrypted frames. |
pnLength: i32 |
The packet number's length on the wire, 1 to 4 bytes. |
Limits
20
QUIC_MAX_CID_LENGTH: i32
The longest connection ID version 1 allows (RFC 9000 §17.2).
QUIC_MAX_VARINT
QUIC_MAX_VARINT: i64
The largest value a variable-length integer holds, 2^62 - 1 (RFC 9000 §16),
and so the largest packet number. Spelled as 2^30 × 2^32 - 1 because an
i64 literal past 2^53 is refused (docs/LANGUAGE.md, numeric literals).
Constants
1
QUIC_AEAD_AES_128_GCM: i32
AEAD_AES_128_GCM with SHA-256, the Initial packets' AEAD (TLS_AES_128_GCM_SHA256).
2
QUIC_AEAD_AES_256_GCM: i32
AEAD_AES_256_GCM with SHA-384 (TLS_AES_256_GCM_SHA384).
3
QUIC_AEAD_CHACHA20_POLY1305: i32
AEAD_CHACHA20_POLY1305 with SHA-256 (TLS_CHACHA20_POLY1305_SHA256).
16
QUIC_AEAD_TAG_SIZE: i32
Every version 1 AEAD's tag, and so what each protected payload adds, in bytes (RFC 9001 §5.3).
4
QUIC_ERR_CID_LENGTH: i32
A version 1 connection ID longer than 20 bytes (RFC 9000 §17.2).
7
QUIC_ERR_DECRYPT: i32
The payload does not authenticate under the keys given (RFC 9001 §5.3).
2
QUIC_ERR_FIXED_BIT: i32
The fixed bit, 0x40 of the first byte, is clear (RFC 9000 §17.2, §17.3.1).
10
QUIC_ERR_KEYS: i32
Keys quicKeys or quicKeysUpdate did not make: a caller's own mistake, never a peer's.
5
QUIC_ERR_LENGTH: i32
A long header whose Length field reaches past the end of the datagram (RFC 9000 §17.2).
9
QUIC_ERR_NOT_PROTECTED: i32
The packet carries no protected payload: a Retry (RFC 9000 §17.2.5).
8
QUIC_ERR_RESERVED_BITS: i32
The payload authenticated but a reserved bit is set, a PROTOCOL_VIOLATION (RFC 9000 §17.2, §17.3.1).
6
QUIC_ERR_SAMPLE: i32
Too few bytes after the packet number's offset to take the 16-byte sample (RFC 9001 §5.4.2).
1
QUIC_ERR_TRUNCATED: i32
The header runs past the end of the datagram.
3
QUIC_ERR_VERSION: i32
A long header of a version other than 1; version, dcid and scid are still filled in (RFC 8999 §5.1).
2
QUIC_PACKET_HANDSHAKE: i32
A long-header Handshake packet (RFC 9000 §17.2.4).
0
QUIC_PACKET_INITIAL: i32
A long-header Initial packet (RFC 9000 §17.2.2).
0
QUIC_PACKET_OK: i32
A packet parsed, or opened, with nothing wrong.
3
QUIC_PACKET_RETRY: i32
A long-header Retry packet (RFC 9000 §17.2.5).
4
QUIC_PACKET_SHORT: i32
A short-header, 1-RTT packet (RFC 9000 §17.3.1).
1
QUIC_PACKET_ZERO_RTT: i32
A long-header 0-RTT packet (RFC 9000 §17.2.3): parsed, since a server may be sent one; quicLongHeader builds one for a client.
16
QUIC_RETRY_TAG_SIZE: i32
The Retry integrity tag, in bytes (RFC 9001 §5.8).
16
QUIC_SAMPLE_SIZE: i32
The bytes of ciphertext header protection samples (RFC 9001 §5.4.2).
1
QUIC_VERSION_1: i64
QUIC version 1 (RFC 9000 §15), the only version this module protects.

