AtlatestRepositorysigil-quic
sigil-quic / tree / docsimplementation.md
1
# sigil-quic3
Experimental QUIC v1 packet protection and a TLS 1.3 handshake engine in Sigil.4
The experimental endpoint supports private numeric IPv4/IPv6 interface testing.6
`(sigil quic tls)` exports SHA-256 HKDF-Expand-Label, key-schedule7
transitions, traffic updates, Finished MACs and the client/server handshake.8
`(sigil quic packet)`9
derives Initial keys, seals/opens payloads and applies/removes header10
protection with the AES-128 single-block primitive in sigil-crypto.12
The package requires sigil-crypto ^0.18.1, which includes the AES block API.13
Install released dependencies normally, without development redirects.14
Configured UDP endpoints additionally require the shared `(sigil socket)`15
family-aware `udp-socket` and `socket-normalize-address` APIs, introduced by16
Sigil commit `d237e25c6d881300cf37eedbc657b2203badec0f`. That shared runtime17
change has not been released yet: the current published runtime alone cannot18
run the configured endpoint. The focused endpoint gate uses a runtime built19
with that change; upstream availability is required for normal consumption.20
RFC 9001 tests derive real AES masks and check complete client/server Initial21
packets, sample selection, payload authentication and inverse processing.23
Build on a Linux measurement machine:25
```sh26
sigil deps install27
sigil build --config native28
scripts/run-gates.sh build/native/bin/quic-probe29
```31
The gate runs a red invocation first, changing one byte in every expected32
vector and requiring every comparison to fail, then the original vectors.33
It also checks rejection after changing each ciphertext/tag byte and the AAD.34
RFC 8448 section 3 checks chain actual X25519 and transcript hashes through35
the handshake, master, traffic, exporter and resumption secrets.37
TLS wire helpers live in `(sigil quic tls codec)`, `(sigil quic tls messages)`38
and `(sigil quic tls signature)`. They provide bounded handshake framing,39
duplicate-rejecting extensions, Hello codecs and P-256 CertificateVerify40
encoding/signing. Run `sigil test` for41
their truncation, malformed-input and signature-binding checks. The control42
`QUIC_TLS_CODEC_RED=1 sigil test test/test-tls-codec.sgl` must fail exactly43
the four known-byte comparisons before the normal suite passes.45
`(sigil quic tls extensions)` handles ALPN, SNI, negotiation lists, key46
shares, cookies and server extension placement. `(sigil quic wire)` provides47
exact 62-bit varints; `(sigil quic transport parameters)` checks parameter48
bounds, role restrictions and connection ID bindings. Transport parameters49
become authenticated when the handshake verifies Finished.50
`QUIC_TLS_EXT_RED=1 sigil test test/test-tls-extensions.sgl` must fail its51
eleven known-byte comparisons before the normal suite passes.53
`(sigil quic tls authentication)` encodes and bounds authentication-flight54
messages with opaque certificate entries. `(sigil quic tls transcript)`55
tracks SHA-256 transcript hashes and the one-time HelloRetryRequest56
message_hash transformation, with message-count and byte limits.57
`QUIC_TLS_AUTH_RED=1 sigil test test/test-tls-authentication.sgl` must fail58
seven published-byte/hash controls before the normal suite passes.60
The handshake engine supports TLS_AES_128_GCM_SHA256, X25519,61
ecdsa_secp256r1_sha256, ALPN, optional SNI, QUIC transport parameters and one62
HelloRetryRequest. It has no TLS records, sockets, PSK authentication, 0-RTT63
acceptance or client identity. Unknown PSK offers are structurally validated64
and fall back to the full X25519/certificate handshake. Retry allows updated65
ticket ages/binders and removal of identities, while rejecting new or reordered66
identities and a repeated early-data offer. No PSK or early-data selection is sent.67
An optional CertificateRequest is declined with an empty Certificate. Bounded68
NewSessionTicket messages are checked and discarded; TLS KeyUpdate is rejected.70
Extension and client key-share duplicate tracking use fixed 8 KiB bitmaps for71
the complete uint16 identifier space. Marking each ID takes constant time;72
the existing wire-size bounds and duplicate rejection remain in force.73
Incoming SNI values outside the supported DNS syntax are treated as74
unrecognized: the server continues with its configured certificate and omits75
the SNI acknowledgement. Empty host names, duplicate name types and malformed76
vectors still fail. Outgoing client SNI retains strict DNS-name validation;77
the client verifier must authenticate the intended identity or pin.79
`make-tls-client` takes ALPN bytevectors, an explicit identity, local transport80
parameters and a verifier. A DNS-name identity requires a callback that receives81
the DER chain and requested name, validates both the chain and name, and returns82
the authenticated leaf's raw 65-byte P-256 public key or `#f` to reject. There83
is no built-in X.509 trust store. An unnamed `#f` identity is rejected.85
For an independently trusted raw public key, use identity `'pinned-key` and86
`(make-tls-pin-verifier public-key)`. This mode sends no SNI and authenticates87
possession of that key through CertificateVerify and Finished. It requires88
the library-created verifier token; arbitrary callbacks are rejected in pin89
mode. The optional `certificate:` bytevector additionally pins the exact leaf90
DER. The factory copies both inputs and never adopts a key from the peer's91
certificate. Pinning authenticates the configured key; it performs no X.50992
path, expiry or DNS-name validation. `make-quic-client` uses the same contract.93
`make-tls-server` takes ALPN preferences, local parameters, a DER certificate94
chain and a 32-byte P-256 private key. Each engine owns its copied signing key.96
Call `tls-bind-peer!` once with the original destination CID, peer's initial97
source CID and Retry source CID (`#f` without QUIC Retry), taken from packet98
headers. Bind before peer transport parameters arrive. Start clients with99
`tls-start!`; deliver ordered, reassembled CRYPTO bytes through100
`tls-input! engine level bytes`, where level is `initial`, `handshake` or101
`application`. The four-byte header is checked against the current state102
before its body is accepted. Hello, EncryptedExtensions, CertificateRequest103
and discarded tickets are limited to 16 KiB; ECDSA CertificateVerify to 76104
bytes, Finished to exactly 32 bytes, and Certificate to 1 MiB. Input storage105
grows only as bytes arrive, with bounded geometric slack and wiped replaced106
prefixes. Transcript/ticket counts are bounded; completion and failure clear107
and drop the retained transcript. `tls-retained-input-bytes` reports input108
capacity plus retained transcript bytes, excluding secrets and outbound events.110
`tls-take-events!` drains ordered events. A `crypto` event carries its level111
and handshake bytes. A `secrets` event carries its level and a pair of112
read/write traffic secrets; `#f` means that direction is not installed by113
that event. These keys are provisional packet-protection material. Require114
`tls-complete?` before accepting application data; `tls-negotiated-alpn` and115
`tls-peer-parameters` return authenticated copies only after completion.116
Failure permanently closes the engine, clears retained secrets and discards117
queued events. The caller must also discard already installed packet keys.118
The implementation still needs independent security review before public use.120
The key schedule clears its owned derived HKDF salts and Finished HMAC keys121
on return and exception; borrowed inputs and returned results remain owned by122
the caller. Zeroization is best-effort: these writes clear reachable mutable123
buffers, without guaranteeing erasure of compiler, garbage-collector or124
native-library copies. In sigil-crypto 0.18.1, internal HKDF MAC-chain and125
accumulator buffers and native HMAC stack outputs are not exposed to this126
library and cannot be cleared here. Cleanup requires normal return or stack127
unwinding; process termination and failures that prevent unwinding can bypass it.129
The engine clears its private key share after deriving handshake secrets and130
its master secret after deriving application traffic secrets. Completion or131
abort clears copied signing keys and remaining engine-owned traffic secrets.132
The server clears its owned server handshake-traffic secret after emitting133
Finished; queued packet-key event copies remain owned by the caller. Its134
client handshake-traffic secret stays live until the peer Finished verifies,135
and clients retain their server handshake-traffic secret until authentication.136
Handshake derivation also clears its owned shared, early and handshake-secret137
intermediates when a later primitive throws, as well as on normal return.138
Fresh key-share private bytes belong to the engine before public-key generation,139
so an exception from that primitive also reaches the engine's abort cleanup.140
Secret-event copies stay in a cleanup scope until queued; a later copy or141
queue failure clears partial results. Drained event copies belong to the caller142
and remain live until the caller clears them.143
Server construction clears its copied signing key if engine creation fails.144
QUIC construction retains ownership of its fresh TLS engine and any installed145
Initial keys until initialization succeeds, clearing them on an exception.147
`raise-tls-alert`, `tls-alert?`, `tls-alert-code` and `tls-alert-reason`148
preserve TLS alert metadata. Connections map these to QUIC CRYPTO_ERROR149
0x0100 plus the alert: failed/absent ALPN is 0x0178, missing transport150
parameters 0x016d, and TLS KeyUpdate/unexpected handshake types 0x010a.151
QUIC transport errors keep their own codes; unclassified TLS failures retain152
the generic handshake_failure fallback.154
`QUIC_TLS_ENGINE_RED=1 sigil test test/test-tls-handshake.sgl` must fail four155
directional-secret controls before the normal suite passes. Engine tests156
exercise both roles in memory, fragmented/coalesced flights, HRR, explicit157
certificate rejection, signature/MAC corruption, CID bindings and level/order158
failures. These tests do not replace independent QUIC interoperability checks.160
`(sigil quic frame)` provides `decode-frames payload level sender`,161
`encode-frame frame` and `encode-frames frames level sender` for RFC 9000162
types 0x00 through 0x1e. Construct a frame with `make-quic-frame type fields`,163
where fields is an alist; use `quic-frame-type`, `quic-frame-fields` and164
`frame-ref` to inspect it. ACK `ranges` are inclusive `(low . high)` pairs165
in descending order and `delay` is the unscaled wire value. STREAM frames166
carry `stream-id`, `offset` (zero when absent) and `data`; the numeric type167
preserves OFF/LEN/FIN flags. `frame-fin?` and `frame-ack-eliciting?` expose168
those common classifications. CRYPTO frames carry `offset` and `data`.170
Frame decoding checks type encoding, payload/field bounds, role/level171
placement, ACK arithmetic, CID lengths and 62-bit end offsets. Limits are172
65,527 payload bytes, 256 frames and 256 ACK ranges; consecutive padding is173
represented by one frame with a `length` field. Local decode work exhaustion174
raises an exception recognized by `frame-work-limit?`; the connection drops175
that entire packet before applying frames, recording an ACK or refreshing176
receive activity. The peer must retransmit its data within these budgets.177
Invalid wire encodings still produce transport errors. Local encoders enforce178
the same frame/range limits. Connection policy must still179
check stream ownership/flow control, ACKs against sent packets, CID inventory180
and path validation. `QUIC_FRAME_RED=1 sigil test test/test-frame.sgl` must181
fail eight independent wire controls, including the two RFC 9001 payloads,182
before the normal suite passes.184
`(sigil quic reassembly)` provides fixed-capacity byte-offset windows for185
CRYPTO and stream delivery. `make-byte-reassembler capacity` allocates data186
and presence rings of that size, with a 1 MiB maximum. CRYPTO callers must187
budget at least 4096 bytes and use a separate receiver per encryption level.188
`reassembler-insert! receiver offset bytes` returns the newly buffered byte189
count. It checks the whole incoming range before mutation, requires buffered190
overlaps to agree, discards already delivered prefixes and rejects data beyond191
the moving receive window. Offsets never determine allocation size.193
`reassembler-read! receiver` returns the available contiguous prefix; an194
optional byte limit allows partial reads. `reassembler-offset` tracks bytes195
delivered, `reassembler-buffered` counts pending unique bytes, and196
`reassembler-highest` records the highest accepted nonempty end offset.197
Empty inserts leave that watermark unchanged. Returned/input data is copied;198
`reassembler-close!` clears storage and prevents further insertion/reading.199
`reassembly-error?` and `reassembly-error-kind` distinguish `capacity` and200
`conflict` failures without changing state. The connection maps CRYPTO window201
exhaustion to CRYPTO_BUFFER_EXCEEDED and conflicting buffered bytes to202
PROTOCOL_VIOLATION. Invalid local arguments remain ordinary exceptions.203
The connection layer must enforce stream flow control/final size and handle204
reassembly errors. `QUIC_REASSEMBLY_RED=1 sigil test test/test-reassembly.sgl`205
must fail four byte controls before the normal suite passes. An integration206
test completes both TLS roles with HRR through reordered CRYPTO-frame bytes.208
`(sigil quic packet header)` parses packet boundaries with209
`decode-packet-header datagram offset short-dcid-length` and builds unprotected210
v1 Initial/Handshake/short headers with `encode-packet-header`. Header `start`211
and `end` are absolute datagram offsets; `pn-offset` is relative to `start`.212
Short headers consume the remaining datagram. Parsing caps datagrams at213
65,527 bytes, v1 CIDs at 20 bytes and VN version lists at 256 entries. VN,214
Retry and unsupported versions are recognized separately. Retry integrity helpers215
are available in `(sigil quic packet retry)` and re-exported by the packet façade:216
`encode-retry-packet original-id destination-id source-id token` and217
`valid-retry-packet? original-id wire`. The encoder accepts `unused:` from 0 to 15;218
the validator drops malformed peer packets. Both bound CIDs and datagram size.219
The standardized public integrity tag does not authenticate a server or validate220
an address. Private token admission, version negotiation and connection-ID policy221
remain separate from this packet helper; the private loopback endpoint has an222
opt-in Retry admission path described below.224
`(sigil quic retry token)` provides private server tokens through225
`make-retry-token-manager`, `make-retry-token`, `validate-retry-token` and226
`close-retry-token-manager!`. Managers own a fresh 32-byte key by default;227
an optional `key:` is copied for explicit shared-server key management.228
`lifetime:` defaults to 10,000 ms and is bounded to 1–60,000 ms. Close each229
manager explicitly when retiring its key; tokens from other keys stop validating.231
`make-retry-token manager address original-id retry-id client-id now` authenticates232
a Retry-only version, issuance time, random nonce and original destination CID233
with HMAC-SHA256. Canonical address bytes (1–64 bytes, including IP and port),234
Retry source CID and client source CID are length-delimited authenticated context.235
The token contains no address bytes and is not encrypted. It is not a NEW_TOKEN236
format. The original CID already appears in the same handshake's first Initial.237
`validate-retry-token manager address retry-id client-id token now` returns an238
owned original CID or `#f` for malformed, forged, future or expired tokens.239
Times must use the same monotonic millisecond clock; expiry is exclusive.240
Replay is limited to the bound address/CIDs and validity window. Local argument241
errors and use after close raise. Operational crypto errors retire the key and242
raise. Endpoint token admission is not integrated yet; no listener uses this API.244
`(sigil quic packet)` re-exports those helpers and provides245
`seal-quic-packet material kind dcid scid number plaintext` with optional246
`token:`, `pn-length:`, `length-width:`, `key-phase:` and `spin:` keywords.247
Kinds are `initial`, `handshake` and `application`. It pads tiny payloads248
enough for a confined header-protection sample. The caller must separately249
ensure the 1200-byte Initial datagram minimum and peer/MTU limits.251
`protect-payload` and `seal-quic-packet` are stateless cryptographic primitives.252
The caller owns packet-number commitments and AEAD usage accounting for each253
directional AES key/IV. That state covers both entry points and every copy of254
the same key material: copying a key vector preserves its nonce space. Commit255
a fresh PN for each encryption attempt. If encryption might have used it,256
retire that PN even when a later allocation or header-protection step raises;257
retry with a fresh PN, or retire the key when commitment state is uncertain.258
`(sigil quic connection)` manages these commitments, usage ceilings and failure259
cleanup for normal connection traffic.261
`open-quic-packet datagram offset short-dcid-length material largest`262
reconstructs the PN (`largest = -1` for an empty space) and authenticates one263
packet. Successful results expose its header, number, payload, key phase and264
spin through `opened-quic-packet-*` accessors. The input remains unchanged.266
AEAD failure returns `#f`; unauthenticated framing/PN errors throw and require267
packet discard. Nonzero reserved bits are checked only after authentication268
and require a connection-level PROTOCOL_VIOLATION. HP sampling is restricted269
to the packet's own boundary even in coalesced datagrams. `traffic-keys`270
derives owned QUIC key material from a 32-byte traffic secret using the same271
vector layout as `initial-keys`; `discard-packet-keys!` clears and disables it.272
The connection layer owns receive PN tracking, duplicate detection, packet-key273
lifetimes and key-phase transitions. `QUIC_PACKET_RED=1 sigil test274
test/test-packet.sgl` must fail eight RFC 9000/9001 controls before the normal275
suite passes.277
Connections clear their private traffic-secret copies after deriving packet278
keys, including the application read-key candidate used to authenticate an279
unsupported update. AES, IV and HP bytes remain live until their packet space280
is discarded. This preserves the low-level packet factories' caller-owned281
traffic-secret component and `next-traffic-keys` API. Actual key-update support282
will require retaining the appropriate update secret again.283
Packet factories clear their private Initial extraction/side intermediates and284
discard partial key material if a later derivation throws. Borrowed inputs and285
complete returned vectors keep their caller's ownership.287
Authenticated PATH_CHALLENGE frames receive matching PATH_RESPONSE frames,288
independently of an application handler. Address-bound connections route each289
response to the challenge's source. Responses precede application backlog,290
expire while blocked and are not retransmitted on PTO. Independent candidate291
and previous-path validation uses fresh, paced probes and separate three-times292
received-byte budgets. Promotion requires reachability and a 1200-byte MTU293
check. The UDP endpoint below supplies this address-bound adapter on numeric interfaces.295
Zero-length CID policy is enforced after packet authentication and before any296
application handler: NEW_CONNECTION_ID is forbidden when sending a zero-length297
destination CID, and RETIRE_CONNECTION_ID is forbidden after issuing a298
zero-length local CID. Both close with PROTOCOL_VIOLATION and the offending299
frame type. RETIRE_CONNECTION_ID above the largest issued sequence also closes300
with PROTOCOL_VIOLATION. A server's preferred-address CID has sequence 1; other301
caller-issued NEW_CONNECTION_ID sequences count only after packet emission,302
including PTO retransmission, rather than queue admission. Address-bound303
connections own spare-ID issuance and path assignment: reservations become304
routable only after emission, retired aliases stop routing immediately, and305
RETIRE_CONNECTION_ID remains pending until its carrying packet is acknowledged.306
These pools enforce the negotiated active limit and bounded lifetime inventory.308
`(sigil quic connection space)` provides bounded PN/ACK bookkeeping for309
each encryption level. `make-packet-space level` accepts `range-limit:`,310
`pending-limit:` and `byte-limit:` budgets (defaults 64, 128 and 262144).311
`packet-space-received-status` classifies a PN as `new`, `duplicate` or `old`;312
apply a new packet's frames before recording it with `packet-space-receive!`.313
Received intervals merge, and retiring old intervals advances a replay floor.314
ACK-only packets enter history without requesting another ACK.315
`packet-space-take-ack!` drains an immediate zero-delay ACK when needed.317
Check `packet-space-can-send?` before sealing `packet-space-next`; then commit318
that exact PN through `packet-space-record-sent!` with its size, monotonic319
millisecond timestamp and ACK-eliciting flag. Failed admission after sealing320
requires discarding the packet and closing; reuse must never encrypt different321
data at that PN. `packet-space-ack!` rejects ACKs of unsent numbers and releases322
matching in-flight metadata/credit. `packet-space-retire!` frees loss metadata323
without resetting the PN, and `packet-space-discard!` permanently closes the324
space. This bookkeeping does not implement congestion control, loss timers325
or frame retransmission; those belong to the connection.327
`(sigil quic error)` attaches transport code/frame metadata to standard Sigil328
error objects via `raise-quic-error`; inspect with `quic-error?` and its329
code/frame-type/reason accessors. Authenticated reserved bits, forbidden frame330
placement and ACKs of unsent packets retain PROTOCOL_VIOLATION metadata.331
An empty payload raises typed PROTOCOL_VIOLATION; it is not a frame encoding332
error. Generic frame parse exceptions still require FRAME_ENCODING_ERROR mapping333
after packet authentication in the connection. `QUIC_SPACE_RED=1 sigil test334
test/test-connection-space.sgl` must fail four controls before the normal suite335
passes.337
`(sigil quic connection)` integrates TLS with protected datagrams without338
opening a socket. Construct a client/server with explicit ALPN, parameters,339
certificate policy and CIDs; the connection supplies its CID transport340
parameters. Start clients with `quic-start! connection now`, feed datagrams341
with `quic-receive! connection bytes now`, call `quic-tick! connection now`342
and immediately send the ordered list from `quic-take-datagrams! connection now`.343
Times are monotonic exact milliseconds. The UDP endpoint binds the original344
peer address before starting or receiving the handshake.346
A transport adapter can instead call `quic-bind-peer-address! connection bytes`347
once before starting or receiving the handshake. The adapter supplies canonical348
IP-and-port bytes, bounded to 1–64 bytes, and must pass the actual source through349
`quic-receive! connection bytes now address: source`. It drains protected output350
with `quic-take-addressed-datagrams! connection now`. Each output has copied351
bytes, destination address and destination CID through `quic-output-bytes`,352
`quic-output-address` and `quic-output-id`. Check `quic-output-valid? connection353
output` immediately before sending retained output: path promotion, CID354
retirement or closure can invalidate a previously queued datagram. Raw datagram355
output is unavailable after binding an address.357
`quic-peer-address` returns the current validated destination. Drain up to sixteen358
retained diagnostics with `quic-take-path-events!`; each is a vector containing359
`path-changed`, `path-validated` or `path-failed`, owned address bytes and a reason360
symbol. A changed-path event does not authorize sending application data there.361
Only authenticated, replay-checked, handler-ready packets earn path credit;362
clients discard unknown server sources. Server migration uses validated paths363
and separate peer CIDs, requeues reliable flight under fresh packet numbers and364
resets congestion accounting. DATAGRAM payloads are never retransmitted.366
After validating a Retry token, the caller can pass `retry-source-id:` to367
`make-quic-server`. The original positional destination ID remains the first368
client DCID; the keyword is the server's distinct Retry source CID. The server369
derives Initial keys from the Retry CID and supplies both original and Retry370
CID transport parameters. Retransmitted Initials route to the Retry or server371
local CID. All supplied IDs are copied. This metadata does not validate an372
address by itself: the caller owns token validation, and the constructor retains373
the conservative amplification bound until authenticated Handshake traffic.375
The connection pads Initial datagrams to 1200 bytes, limits unvalidated server376
output to three times received bytes, bounds deferred packets/CRYPTO/queues,377
tracks directional keys and PN spaces, and confirms with HANDSHAKE_DONE.378
It uses immediate ACKs, a conservative send window, bounded fixed-base PTO379
backoff and fresh-PN frame retransmission, rather than full RFC 9002 recovery.380
RFC 9221 DATAGRAM payloads are excluded from retransmission; their loss timer381
uses a PING probe while retaining ordinary congestion and ACK bookkeeping.382
Handshake timeout defaults to 10 seconds. A client accepts one valid routed Retry383
after sending its first Initial and before processing a server Initial. It keeps384
the original ClientHello, client source CID and packet-number progression, changes385
Initial keys and destination CID, and includes the copied token on retransmissions.386
Retry tokens over 1024 bytes are dropped; the retained first ClientHello is capped387
at 64 KiB. CRYPTO fragmentation accounts for the token within 1200-byte Initials.388
Retry does not restart the handshake deadline. The first accepted server Initial389
binds the original, server Initial and Retry source IDs to the TLS transport checks.390
VN, key updates, migration and connection-ID rotation391
are not implemented. Stream ownership/flow control and392
path/CID policy still belong to the layers above this primitive. No public393
listener is provided, and independent security review is still required.395
Require `quic-complete?` for authenticated application delivery;396
`quic-confirmed?` reports handshake confirmation. Attach an application-frame397
handler with `quic-set-frame-handler!` and queue application frames with398
`quic-send-frame!`. Before attachment, authenticated packets containing STREAM,399
RESET_STREAM, STOP_SENDING or application flow-control frames are dropped whole,400
without applying a prefix, recording their PN, acknowledging them or refreshing401
idle activity. The peer can retransmit after attachment; no additional input402
buffer is retained. Transport-only packets still drive handshake confirmation,403
ACKs, path responses, CID validation and close without an application handler.404
A frame exceeding the connection's 1,200-byte packet budget405
(including its header and tag) raises synchronously before queue mutation;406
previously queued work and the connection remain usable. On `quic-closed?`,407
drain final close output and close the dedicated endpoint socket.408
`quic-failure` exposes local failure or the peer's409
close frame. Closure erases traffic keys, pending data and TLS secrets;410
`tls-abort!` provides the same idempotent TLS cleanup to standalone callers.412
To accept RFC 9221 DATAGRAM messages, include transport parameter `0x20`413
(`max_datagram_frame_size`) in the constructor's parameters, for example414
`(cons 32 (encode-varint 65535))`. The value includes the frame type, optional415
Length field and payload. Omission or zero disables receiving; receiving an416
unsupported or oversized frame closes with PROTOCOL_VIOLATION. Received limits417
use the actual wire size, including nonminimal Length-varint encodings.419
`quic-send-datagram! connection bytes` requires a complete authenticated420
handshake and a nonzero peer advertisement. It copies one whole message,421
queues a length-bearing frame (`0x31`) and returns `#t`; use `length?: #f` for422
the lengthless `0x30` form. Invalid inputs and peer or 1,200-byte packet size423
excess raise before queue mutation. No fragmentation is performed. A full424
send queue returns `#f`: at most `quic-datagram-queue-limit` (32) DATAGRAM425
messages may wait alongside the existing bounded frame queue. A full queue426
does not overwrite earlier messages. Sending through `quic-send-frame!` also427
enforces negotiation, size and count limits, but raises on queue refusal.429
`quic-read-datagram! connection` returns the oldest received message, or `#f`430
when none is available, the handshake is incomplete, or the connection is431
closed. An empty bytevector is a valid message. Receive dispatch is independent432
of the stream-frame handler. It retains at most 32 messages and433
`quic-datagram-byte-limit` (65,536) payload bytes; new arrivals beyond either434
budget are dropped while normal packet ACK processing continues. Reads release435
credit, and connection closure clears queued messages. DATAGRAM messages are436
unreliable, do not consume STREAM flow-control credit and are never retransmitted.437
Applications supply any flow identifiers inside their payloads.439
DATAGRAM codec/transport tests are in `test/test-datagram-codec.sgl`; protected440
connection tests in `test/test-datagram.sgl` use a standalone TLS peer that owns441
its keys. On a remote test machine, `node scripts/native-tls-tests.mjs --datagram`442
selects both files for the native test package described above. They are also443
included in the default bytecode and generated native suites.445
Server Initial packets carrying a token are discarded before CID pinning,446
authentication, receive credit or closing replay. During the handshake, other447
coalesced packets remain eligible for processing. ClientHello must have an448
empty legacy session ID; the server reports PROTOCOL_VIOLATION for a nonempty449
ID (RFC 9001 §8.4).451
Client receive tolerates authenticated server Initials in short datagrams.452
Our send path still pads ack-eliciting server Initials and all client Initials;453
servers still discard client Initials in datagrams under 1,200 bytes.454
Well-formed NewSessionTickets are discarded regardless of lifetime without455
retiring completed TLS. Ticket parsing and the 64-message work limit still apply.456
The ticket's optional `early_data` extension must contain the four-byte QUIC457
sentinel `0xffffffff`; another value closes with PROTOCOL_VIOLATION, while a458
malformed extension length produces TLS decode_error. No ticket enables 0-RTT.460
`QUIC_CONNECTION_RED=1 sigil test test/test-connection.sgl` must fail two461
completion controls. `QUIC_HP_SABOTAGE=1 sigil test test/test-connection.sgl`462
must fail only the dedicated positive handshake completion assertion: one463
protected PN byte is corrupted on every client Initial transmission and retry.464
A single transient corrupt datagram is recoverable and has a separate loss test.466
`(sigil quic stream)` provides one client-initiated bidirectional stream (ID 0).467
Use `stream-transport-parameters role receive-window: size` when constructing468
the connection, then attach `make-quic-stream connection` before starting or469
receiving packets. It validates its fixed allocation against the advertised470
stream/connection limits and owns the connection's application-frame handler.471
The default receive window is 65536 bytes, with a 1 MiB maximum.473
After authentication, `quic-stream-write! stream bytes fin?: boolean` accepts474
up to 900 bytes and returns the accepted count; retry the remainder after475
pumping datagrams and credit. A zero-byte FIN can return zero successfully;476
`quic-stream-send-closed?` distinguishes it from a blocked write.477
`quic-stream-read! stream maximum: count` returns copied ordered bytes and478
advertises additional absolute credit as storage is freed. Empty reads can479
mean a gap or no data; use `quic-stream-eof?` for FIN completion and480
`quic-stream-reset-code` for a peer reset (including code zero).481
`quic-stream-reset!` and `quic-stream-stop!` take application error codes.482
STOP_SENDING cancels queued/in-flight STREAM retransmissions before RESET;483
FIN/RESET final sizes, credit, stream ownership and limits remain checked.484
Connection closure clears the stream's receive storage.486
The pure state layer is `(sigil quic stream state)`; its input frames must487
already have passed the frame codec. `make-quic-stream connection488
maximum-streams: count` optionally permits up to 16 sequential streams (one489
by default), with one active receive window. `quic-stream-id` reports its ID.490
Call `quic-stream-advance!` after both directions finish; it returns true only491
after peer FIN has been consumed, all outgoing STREAM/FIN data acknowledged,492
and enough control-queue capacity is available. A false result changes493
nothing. Servers then grant the next absolute MAX_STREAMS count; clients wait494
for that grant before writing their successor. Stream-specific cancellation495
and retransmission accounting use the current ID. Reset streams do not advance.496
The pure state constructor also accepts `maximum-streams:` from 1 (default)497
to 16, allowing bounded sequential IDs 0, 4, 8, ... through498
`stream-state-advance!`. Advancing requires fully consumed receiving FIN and499
a sending FIN; the caller must first ensure every outgoing STREAM/FIN is500
acknowledged. The operation wipes the previous receive window, preserves501
cumulative connection credit and retains only numeric final-size tombstones502
for retired IDs. It returns absolute credit frames, or false without changing503
state when advancement is unavailable. Reset streams cannot advance.504
`QUIC_SEQUENCE_RED=1 sigil test test/test-stream-sequence.sgl` must fail505
two independent wire controls before the full suite passes. Connection-ID506
rotation and path policy remain separate work.507
`QUIC_STREAM_RED=1 sigil test test/test-stream.sgl` must fail two byte controls508
before the full suite passes. Stream tests include protected bidirectional509
transfer beyond the receive-window capacity and reset/cancellation under loss.511
`(sigil quic endpoint)` uses a dedicated nonblocking IPv4 or IPv6 UDP socket512
for one connection. It binds the original peer before the handshake, sends513
each protected datagram to its recorded destination and validates confirmed514
server peer address changes. Clients keep their original server source.515
Multiple connections and cross-family migration remain outside this adapter.517
`(open-quic-endpoint host: "<assigned-numeric-IP>" port: 4433)` chooses the518
socket family from the checked host. The default host is `127.0.0.1`; port 0519
chooses an ephemeral port. IPv4 `0.0.0.0` and IPv6 `::` select wildcard binds;520
IPv6 sockets are IPv6-only. Numeric decimal IPv6 scope IDs are supported;521
hostnames and interface-name scope IDs are rejected. `quic-endpoint-host`,522
`quic-endpoint-family` and `quic-endpoint-port` expose the actual local bind.523
The host accessor returns an owned string.525
Attach a fresh client connection/stream with526
`(quic-endpoint-attach! endpoint connection peer-port peer-host: "<numeric-peer-IP>")`;527
this starts its TLS handshake. The peer must match the socket family; its528
omitted host defaults to that family's loopback. A server calls529
`quic-endpoint-accept! endpoint factory` instead. Its factory receives original530
destination/client source CIDs, constructs a server connection, attaches its531
stream handler and returns that connection. Optional `peer-host:` and532
`peer-port:` filters restrict admission independently; the first authenticated533
Initial pins any unspecified values. Before invoking the factory, the endpoint534
opens that Initial with ephemeral client Initial keys and requires a decoded,535
nonempty CRYPTO frame at offset zero. Keys are discarded after this check.536
Initial integrity is not address validation: Retry remains necessary before537
public operation. Failed candidates before confirmation release the slot and538
discard their output while preserving the factory and both configured filters.539
After confirmation, server candidate sources go through authenticated path540
validation; the admission filters do not prevent NAT rebinding. The endpoint541
retains one connection throughout.543
`(sigil quic address)` supplies bounded canonical peer keys through544
`quic-address`, `quic-address?`, `quic-address-host`, `quic-address-port` and545
`quic-address-family`. IPv4 retains its original six-byte address/port tuple.546
IPv6 uses distinct bounded framing with a canonical numeric host and scope;547
these keys are local path/Retry identities and never QUIC wire addresses.549
`quic-endpoint-peer-address` returns owned canonical peer bytes or `#f` before550
admission. `quic-endpoint-take-path-events!` drains the connection's bounded551
path events. Application data moves only after validation; a `path-changed`552
event alone does not change its destination. Retained ciphertext is checked553
again before each send, so CID retirement and path promotion can invalidate it.555
For private Retry testing, call `quic-endpoint-accept-retry! endpoint factory`556
instead. Its factory receives three copied IDs: original destination, client557
source and Retry source. Construct the server with the third ID as558
`retry-source-id:`, attach its stream handler, and return the owned connection.559
The endpoint checks the returned connection's CID metadata and aborts a560
rejected return. Optional `peer-host:` and `peer-port:` restrict admission;561
`token-lifetime:` is 1–60,000 milliseconds, default 10,000.563
The endpoint issues a challenge only after authenticating a tokenless Initial564
of at least 1,200 bytes with nonempty CRYPTO at offset zero. It retains no565
challenge queue or peer pin. Before invoking the factory or pinning a source,566
it validates the private token against the actual canonical source host and UDP567
port, current source/destination CIDs and monotonic time, then authenticates568
the retried Initial. Invalid token-bearing Initials drop without another Retry.569
Each receive pass permits at most 32 challenge attempts; each challenge fits570
1,200 bytes and the three-times-received budget. A blocked challenge send drops.571
The endpoint owns a fresh token key, keeps it across failed tentative572
connections, and retires it on confirmation or endpoint close. The connection573
keeps its conservative amplification limit until authenticated Handshake.574
This adapter remains experimental and requires independent review before public use.576
Call `quic-endpoint-step! endpoint wait-ms: milliseconds` repeatedly alongside577
application reads/writes. Each call waits at most 50 milliseconds and drives578
receive, timers and protected output. Each flush attempts at most 32 retained579
plus 32 fresh protected datagrams, once per record, and retains at most 32580
failed sends. One blocked address cannot stop validation controls for another.581
Each retained record keeps its original one-second deadline; expiry and582
overflow drop ciphertext as UDP loss. Reliable frames remain owned by the583
connection's retransmission machinery, while DATAGRAM data is unreliable.584
Malformed output and partial datagram sends close the socket and connection.585
`quic-endpoint-connection`, `quic-endpoint-closed?` and586
`quic-endpoint-failure` expose progress. `quic-endpoint-close!` is idempotent,587
clears connection/stream secrets and storage, attempts final close output,588
and closes the dedicated socket. Cleanup also runs if initiating connection589
closure raises; the exception propagates after socket/cache release.590
`quic-close!` closes a standalone connection591
with an application `code:` and UTF-8 `reason:` (at most 1,024 bytes). At592
1-RTT it sends application CONNECTION_CLOSE (0x1d); Initial/Handshake closes593
use transport APPLICATION_ERROR (0x0c) with an empty reason. Local application594
details remain available through `quic-application-error?`,595
`quic-application-error-code` and `quic-application-error-reason` in596
`(sigil quic error)`. Invalid application metadata raises before closing.597
`quic-transport-close!` explicitly sends a transport `code:`/`frame-type:`;598
its `reason:` remains a local diagnostic. Both paths are idempotent and retain599
the first failure. Either close frame may use the final reserved AEAD seal.600
Before confirmation, a local close is attempted at every available write601
level, ordered Initial, Handshake, then 1-RTT. Each copy retains its AEAD and602
anti-amplification checks. After confirmation, only 1-RTT is used. Traffic603
secrets are erased after the close copies are sealed.605
Standalone connections retain owned copies of those protected packets for606
three current PTOs. `quic-closed?` stays true; `quic-closing?` reports the607
remaining closing state while `quic-receive!`, `quic-tick!` and608
`quic-take-datagrams!` advance its monotonic clock. Routed incoming packets609
can trigger at most one byte-exact replay per PTO, without new encryption or610
a deadline extension. Replays use only the pre-close receive credit and stay611
within its cumulative 3x send limit, even for validated peers. Replays can612
therefore be suppressed after asymmetric traffic. `quic-abort!` immediately613
discards cached output and retires an open connection silently. The dedicated614
endpoint adapter ends closing early when it releases its UDP socket, as615
permitted by RFC 9000 §10.2, and discards the connection's cached output.616
Abandoned admission candidates also lose their cache before the slot is reused.618
Connections advertise a 30000 ms `max_idle_timeout` unless parameter 1 is619
explicitly supplied. The effective value is the minimum nonzero local and620
authenticated peer value; both zero disables expiry. The period is floored at621
three current PTOs (including the prototype's capped backoff). New processed622
authenticated packets restart it, as does only the first eliciting send since623
such a receipt. Corrupt/replayed packets, ACK-only output and repeated sends624
without a peer response do not restart it. `quic-tick!`, receive and output625
checks expire before accepting late activity. Idle expiry silently discards626
keys/queues and invokes close handlers; `quic-idle-expired?` reports this627
normal close with no transport failure. The endpoint discards retained output628
and closes its dedicated socket.630
Each key is limited to 2^23 AES-GCM encryptions, including ACKs and retransmits.631
The connection reserves its last permitted encryption for a typed632
`AEAD_LIMIT_REACHED` close (0x0f). Invalid packets accumulate across all read633
keys for the lifetime of the connection, with the standard 2^52 ceiling.634
Constructor options `aead-packet-limit:` and `aead-failure-limit:` can lower635
these ceilings; they cannot raise them. Invalid packets count once even if636
both current and candidate read keys are tried.638
Full key update is not implemented yet. Authenticated unexpected key phases639
close with `KEY_UPDATE_ERROR` (0x0e) before applying frames. A next-read640
candidate is precomputed with `next-traffic-keys`, using the QUIC `quic ku`641
label and preserving HP. Forged apparent updates are discarded unless the642
integrity ceiling is reached. Generic TLS `traffic-update` uses `traffic upd`643
and must not be used to derive QUIC updates. Candidate keys are disposed with644
their encryption level.646
On the test machine, `QUIC_ENDPOINT_RED=1 sigil test test/test-endpoint.sgl`647
must fail exactly two controls before the full suite passes. Endpoint tests648
use actual loopback UDP, arbitrary binary payloads beyond the receive window,649
peer-port filtering, bounded admission and failure/timeout cleanup.650
The focused native selector `scripts/native-tls-tests.mjs --endpoint-bind`651
adds canonical address tests and Retry/stream/DATAGRAM exchanges on IPv4, IPv6652
and wildcard binds. Assigned-interface cases accept `QUIC_TEST_INTERFACE_IPV4`653
and `QUIC_TEST_INTERFACE_IPV6`; absent values use loopback fixtures. Run these654
tests on a runtime providing the shared socket APIs described above.656
Receive work is bounded to eight parsed packets per datagram, including657
unrouted packets and authentication failures. Excess coalesced packets are658
dropped without closing the connection or undoing its accepted prefix.659
Each endpoint step handles at most 32 datagrams admitted to its connection660
and drains at most 96 total datagrams, so rejected source ports do not consume661
the connection budget and a noise flood still yields to the caller.663
Server ACK-only Initial packets are unpadded; client Initial packets and664
ack-eliciting server Initial packets retain the 1,200-byte minimum. Until a665
Handshake ACK or handshake confirmation proves the server validated the666
client, the client probes even with no data in flight: a Handshake PING if667
keys exist, otherwise a padded Initial PING. Initial ACKs preserve probe668
backoff, and existing deadline, idle and key-use limits still apply.670
To execute the same test bodies in a native binary on the test machine:672
```sh673
node scripts/native-tls-tests.mjs674
cd build/native-tests675
sigil deps install676
sigil build --config native677
# This control exits 1 with eleven vector failures.678
QUIC_TLS_EXT_RED=1 build/native/bin/quic-native-tests679
# This control exits 1 with seven authentication vector failures.680
QUIC_TLS_AUTH_RED=1 build/native/bin/quic-native-tests681
# This control exits 1 with four engine secret-comparison failures.682
QUIC_TLS_ENGINE_RED=1 build/native/bin/quic-native-tests683
# This control exits 1 with eight frame wire-comparison failures.684
QUIC_FRAME_RED=1 build/native/bin/quic-native-tests685
# This control exits 1 with four reassembly byte-comparison failures.686
QUIC_REASSEMBLY_RED=1 build/native/bin/quic-native-tests687
# This control exits 1 with eight packet/header/PN comparison failures.688
QUIC_PACKET_RED=1 build/native/bin/quic-native-tests689
# This control exits 1 with four packet-space/error comparison failures.690
QUIC_SPACE_RED=1 build/native/bin/quic-native-tests691
build/native/bin/quic-native-tests692
```694
The benchmark creates, protects, sends, receives, authenticates and parses695
1,200-byte packets on UDP loopback. It uses one process pinned to one CPU,696
warms up, and reports three samples for the full path and three controls:697
build/parse, UDP without crypto, and crypto without UDP. Controls include698
allocation and parsing overhead and should not be treated as additive699
isolated component costs. Timings include both sender and receiver work.700
Packet numbers increase throughout each run; traffic keys are fresh per701
process. The outer timeout bounds blocking UDP failures.703
Regenerate fixtures from RFC Editor plain texts with:705
```sh706
node scripts/extract-vectors.mjs rfc8448.txt rfc9001.txt707
node scripts/extract-handshake-vectors.mjs rfc8448.txt708
```