AtlatestRepositorysigil-quic

sigil-quic / tree / docsimplementation.md

Read it rendered

1# sigil-quic
2
3Experimental QUIC v1 packet protection and a TLS 1.3 handshake engine in Sigil.
4The experimental endpoint supports private numeric IPv4/IPv6 interface testing.
5
6`(sigil quic tls)` exports SHA-256 HKDF-Expand-Label, key-schedule
7transitions, traffic updates, Finished MACs and the client/server handshake.
8`(sigil quic packet)`
9derives Initial keys, seals/opens payloads and applies/removes header
10protection with the AES-128 single-block primitive in sigil-crypto.
12The package requires sigil-crypto ^0.18.1, which includes the AES block API.
13Install released dependencies normally, without development redirects.
14Configured UDP endpoints additionally require the shared `(sigil socket)`
15family-aware `udp-socket` and `socket-normalize-address` APIs, introduced by
16Sigil commit `d237e25c6d881300cf37eedbc657b2203badec0f`. That shared runtime
17change has not been released yet: the current published runtime alone cannot
18run the configured endpoint. The focused endpoint gate uses a runtime built
19with that change; upstream availability is required for normal consumption.
20RFC 9001 tests derive real AES masks and check complete client/server Initial
21packets, sample selection, payload authentication and inverse processing.
23Build on a Linux measurement machine:
25```sh
26sigil deps install
27sigil build --config native
28scripts/run-gates.sh build/native/bin/quic-probe
29```
31The gate runs a red invocation first, changing one byte in every expected
32vector and requiring every comparison to fail, then the original vectors.
33It also checks rejection after changing each ciphertext/tag byte and the AAD.
34RFC 8448 section 3 checks chain actual X25519 and transcript hashes through
35the handshake, master, traffic, exporter and resumption secrets.
37TLS wire helpers live in `(sigil quic tls codec)`, `(sigil quic tls messages)`
38and `(sigil quic tls signature)`. They provide bounded handshake framing,
39duplicate-rejecting extensions, Hello codecs and P-256 CertificateVerify
40encoding/signing. Run `sigil test` for
41their truncation, malformed-input and signature-binding checks. The control
42`QUIC_TLS_CODEC_RED=1 sigil test test/test-tls-codec.sgl` must fail exactly
43the four known-byte comparisons before the normal suite passes.
45`(sigil quic tls extensions)` handles ALPN, SNI, negotiation lists, key
46shares, cookies and server extension placement. `(sigil quic wire)` provides
47exact 62-bit varints; `(sigil quic transport parameters)` checks parameter
48bounds, role restrictions and connection ID bindings. Transport parameters
49become authenticated when the handshake verifies Finished.
50`QUIC_TLS_EXT_RED=1 sigil test test/test-tls-extensions.sgl` must fail its
51eleven known-byte comparisons before the normal suite passes.
53`(sigil quic tls authentication)` encodes and bounds authentication-flight
54messages with opaque certificate entries. `(sigil quic tls transcript)`
55tracks SHA-256 transcript hashes and the one-time HelloRetryRequest
56message_hash transformation, with message-count and byte limits.
57`QUIC_TLS_AUTH_RED=1 sigil test test/test-tls-authentication.sgl` must fail
58seven published-byte/hash controls before the normal suite passes.
60The handshake engine supports TLS_AES_128_GCM_SHA256, X25519,
61ecdsa_secp256r1_sha256, ALPN, optional SNI, QUIC transport parameters and one
62HelloRetryRequest. It has no TLS records, sockets, PSK authentication, 0-RTT
63acceptance or client identity. Unknown PSK offers are structurally validated
64and fall back to the full X25519/certificate handshake. Retry allows updated
65ticket ages/binders and removal of identities, while rejecting new or reordered
66identities and a repeated early-data offer. No PSK or early-data selection is sent.
67An optional CertificateRequest is declined with an empty Certificate. Bounded
68NewSessionTicket messages are checked and discarded; TLS KeyUpdate is rejected.
70Extension and client key-share duplicate tracking use fixed 8 KiB bitmaps for
71the complete uint16 identifier space. Marking each ID takes constant time;
72the existing wire-size bounds and duplicate rejection remain in force.
73Incoming SNI values outside the supported DNS syntax are treated as
74unrecognized: the server continues with its configured certificate and omits
75the SNI acknowledgement. Empty host names, duplicate name types and malformed
76vectors still fail. Outgoing client SNI retains strict DNS-name validation;
77the client verifier must authenticate the intended identity or pin.
79`make-tls-client` takes ALPN bytevectors, an explicit identity, local transport
80parameters and a verifier. A DNS-name identity requires a callback that receives
81the DER chain and requested name, validates both the chain and name, and returns
82the authenticated leaf's raw 65-byte P-256 public key or `#f` to reject. There
83is no built-in X.509 trust store. An unnamed `#f` identity is rejected.
85For an independently trusted raw public key, use identity `'pinned-key` and
86`(make-tls-pin-verifier public-key)`. This mode sends no SNI and authenticates
87possession of that key through CertificateVerify and Finished. It requires
88the library-created verifier token; arbitrary callbacks are rejected in pin
89mode. The optional `certificate:` bytevector additionally pins the exact leaf
90DER. The factory copies both inputs and never adopts a key from the peer's
91certificate. Pinning authenticates the configured key; it performs no X.509
92path, expiry or DNS-name validation. `make-quic-client` uses the same contract.
93`make-tls-server` takes ALPN preferences, local parameters, a DER certificate
94chain and a 32-byte P-256 private key. Each engine owns its copied signing key.
96Call `tls-bind-peer!` once with the original destination CID, peer's initial
97source CID and Retry source CID (`#f` without QUIC Retry), taken from packet
98headers. Bind before peer transport parameters arrive. Start clients with
99`tls-start!`; deliver ordered, reassembled CRYPTO bytes through
100`tls-input! engine level bytes`, where level is `initial`, `handshake` or
101`application`. The four-byte header is checked against the current state
102before its body is accepted. Hello, EncryptedExtensions, CertificateRequest
103and discarded tickets are limited to 16 KiB; ECDSA CertificateVerify to 76
104bytes, Finished to exactly 32 bytes, and Certificate to 1 MiB. Input storage
105grows only as bytes arrive, with bounded geometric slack and wiped replaced
106prefixes. Transcript/ticket counts are bounded; completion and failure clear
107and drop the retained transcript. `tls-retained-input-bytes` reports input
108capacity plus retained transcript bytes, excluding secrets and outbound events.
110`tls-take-events!` drains ordered events. A `crypto` event carries its level
111and handshake bytes. A `secrets` event carries its level and a pair of
112read/write traffic secrets; `#f` means that direction is not installed by
113that event. These keys are provisional packet-protection material. Require
114`tls-complete?` before accepting application data; `tls-negotiated-alpn` and
115`tls-peer-parameters` return authenticated copies only after completion.
116Failure permanently closes the engine, clears retained secrets and discards
117queued events. The caller must also discard already installed packet keys.
118The implementation still needs independent security review before public use.
120The key schedule clears its owned derived HKDF salts and Finished HMAC keys
121on return and exception; borrowed inputs and returned results remain owned by
122the caller. Zeroization is best-effort: these writes clear reachable mutable
123buffers, without guaranteeing erasure of compiler, garbage-collector or
124native-library copies. In sigil-crypto 0.18.1, internal HKDF MAC-chain and
125accumulator buffers and native HMAC stack outputs are not exposed to this
126library and cannot be cleared here. Cleanup requires normal return or stack
127unwinding; process termination and failures that prevent unwinding can bypass it.
129The engine clears its private key share after deriving handshake secrets and
130its master secret after deriving application traffic secrets. Completion or
131abort clears copied signing keys and remaining engine-owned traffic secrets.
132The server clears its owned server handshake-traffic secret after emitting
133Finished; queued packet-key event copies remain owned by the caller. Its
134client handshake-traffic secret stays live until the peer Finished verifies,
135and clients retain their server handshake-traffic secret until authentication.
136Handshake derivation also clears its owned shared, early and handshake-secret
137intermediates when a later primitive throws, as well as on normal return.
138Fresh key-share private bytes belong to the engine before public-key generation,
139so an exception from that primitive also reaches the engine's abort cleanup.
140Secret-event copies stay in a cleanup scope until queued; a later copy or
141queue failure clears partial results. Drained event copies belong to the caller
142and remain live until the caller clears them.
143Server construction clears its copied signing key if engine creation fails.
144QUIC construction retains ownership of its fresh TLS engine and any installed
145Initial keys until initialization succeeds, clearing them on an exception.
147`raise-tls-alert`, `tls-alert?`, `tls-alert-code` and `tls-alert-reason`
148preserve TLS alert metadata. Connections map these to QUIC CRYPTO_ERROR
1490x0100 plus the alert: failed/absent ALPN is 0x0178, missing transport
150parameters 0x016d, and TLS KeyUpdate/unexpected handshake types 0x010a.
151QUIC transport errors keep their own codes; unclassified TLS failures retain
152the generic handshake_failure fallback.
154`QUIC_TLS_ENGINE_RED=1 sigil test test/test-tls-handshake.sgl` must fail four
155directional-secret controls before the normal suite passes. Engine tests
156exercise both roles in memory, fragmented/coalesced flights, HRR, explicit
157certificate rejection, signature/MAC corruption, CID bindings and level/order
158failures. 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 9000
162types 0x00 through 0x1e. Construct a frame with `make-quic-frame type fields`,
163where fields is an alist; use `quic-frame-type`, `quic-frame-fields` and
164`frame-ref` to inspect it. ACK `ranges` are inclusive `(low . high)` pairs
165in descending order and `delay` is the unscaled wire value. STREAM frames
166carry `stream-id`, `offset` (zero when absent) and `data`; the numeric type
167preserves OFF/LEN/FIN flags. `frame-fin?` and `frame-ack-eliciting?` expose
168those common classifications. CRYPTO frames carry `offset` and `data`.
170Frame decoding checks type encoding, payload/field bounds, role/level
171placement, ACK arithmetic, CID lengths and 62-bit end offsets. Limits are
17265,527 payload bytes, 256 frames and 256 ACK ranges; consecutive padding is
173represented by one frame with a `length` field. Local decode work exhaustion
174raises an exception recognized by `frame-work-limit?`; the connection drops
175that entire packet before applying frames, recording an ACK or refreshing
176receive activity. The peer must retransmit its data within these budgets.
177Invalid wire encodings still produce transport errors. Local encoders enforce
178the same frame/range limits. Connection policy must still
179check stream ownership/flow control, ACKs against sent packets, CID inventory
180and path validation. `QUIC_FRAME_RED=1 sigil test test/test-frame.sgl` must
181fail eight independent wire controls, including the two RFC 9001 payloads,
182before the normal suite passes.
184`(sigil quic reassembly)` provides fixed-capacity byte-offset windows for
185CRYPTO and stream delivery. `make-byte-reassembler capacity` allocates data
186and presence rings of that size, with a 1 MiB maximum. CRYPTO callers must
187budget at least 4096 bytes and use a separate receiver per encryption level.
188`reassembler-insert! receiver offset bytes` returns the newly buffered byte
189count. It checks the whole incoming range before mutation, requires buffered
190overlaps to agree, discards already delivered prefixes and rejects data beyond
191the moving receive window. Offsets never determine allocation size.
193`reassembler-read! receiver` returns the available contiguous prefix; an
194optional byte limit allows partial reads. `reassembler-offset` tracks bytes
195delivered, `reassembler-buffered` counts pending unique bytes, and
196`reassembler-highest` records the highest accepted nonempty end offset.
197Empty 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` and
200`conflict` failures without changing state. The connection maps CRYPTO window
201exhaustion to CRYPTO_BUFFER_EXCEEDED and conflicting buffered bytes to
202PROTOCOL_VIOLATION. Invalid local arguments remain ordinary exceptions.
203The connection layer must enforce stream flow control/final size and handle
204reassembly errors. `QUIC_REASSEMBLY_RED=1 sigil test test/test-reassembly.sgl`
205must fail four byte controls before the normal suite passes. An integration
206test completes both TLS roles with HRR through reordered CRYPTO-frame bytes.
208`(sigil quic packet header)` parses packet boundaries with
209`decode-packet-header datagram offset short-dcid-length` and builds unprotected
210v1 Initial/Handshake/short headers with `encode-packet-header`. Header `start`
211and `end` are absolute datagram offsets; `pn-offset` is relative to `start`.
212Short headers consume the remaining datagram. Parsing caps datagrams at
21365,527 bytes, v1 CIDs at 20 bytes and VN version lists at 256 entries. VN,
214Retry and unsupported versions are recognized separately. Retry integrity helpers
215are 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` and
217`valid-retry-packet? original-id wire`. The encoder accepts `unused:` from 0 to 15;
218the validator drops malformed peer packets. Both bound CIDs and datagram size.
219The standardized public integrity tag does not authenticate a server or validate
220an address. Private token admission, version negotiation and connection-ID policy
221remain separate from this packet helper; the private loopback endpoint has an
222opt-in Retry admission path described below.
224`(sigil quic retry token)` provides private server tokens through
225`make-retry-token-manager`, `make-retry-token`, `validate-retry-token` and
226`close-retry-token-manager!`. Managers own a fresh 32-byte key by default;
227an 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 each
229manager explicitly when retiring its key; tokens from other keys stop validating.
231`make-retry-token manager address original-id retry-id client-id now` authenticates
232a Retry-only version, issuance time, random nonce and original destination CID
233with HMAC-SHA256. Canonical address bytes (1–64 bytes, including IP and port),
234Retry source CID and client source CID are length-delimited authenticated context.
235The token contains no address bytes and is not encrypted. It is not a NEW_TOKEN
236format. 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 an
238owned original CID or `#f` for malformed, forged, future or expired tokens.
239Times must use the same monotonic millisecond clock; expiry is exclusive.
240Replay is limited to the bound address/CIDs and validity window. Local argument
241errors and use after close raise. Operational crypto errors retire the key and
242raise. Endpoint token admission is not integrated yet; no listener uses this API.
244`(sigil quic packet)` re-exports those helpers and provides
245`seal-quic-packet material kind dcid scid number plaintext` with optional
246`token:`, `pn-length:`, `length-width:`, `key-phase:` and `spin:` keywords.
247Kinds are `initial`, `handshake` and `application`. It pads tiny payloads
248enough for a confined header-protection sample. The caller must separately
249ensure the 1200-byte Initial datagram minimum and peer/MTU limits.
251`protect-payload` and `seal-quic-packet` are stateless cryptographic primitives.
252The caller owns packet-number commitments and AEAD usage accounting for each
253directional AES key/IV. That state covers both entry points and every copy of
254the same key material: copying a key vector preserves its nonce space. Commit
255a fresh PN for each encryption attempt. If encryption might have used it,
256retire that PN even when a later allocation or header-protection step raises;
257retry with a fresh PN, or retire the key when commitment state is uncertain.
258`(sigil quic connection)` manages these commitments, usage ceilings and failure
259cleanup for normal connection traffic.
261`open-quic-packet datagram offset short-dcid-length material largest`
262reconstructs the PN (`largest = -1` for an empty space) and authenticates one
263packet. Successful results expose its header, number, payload, key phase and
264spin through `opened-quic-packet-*` accessors. The input remains unchanged.
266AEAD failure returns `#f`; unauthenticated framing/PN errors throw and require
267packet discard. Nonzero reserved bits are checked only after authentication
268and require a connection-level PROTOCOL_VIOLATION. HP sampling is restricted
269to the packet's own boundary even in coalesced datagrams. `traffic-keys`
270derives owned QUIC key material from a 32-byte traffic secret using the same
271vector layout as `initial-keys`; `discard-packet-keys!` clears and disables it.
272The connection layer owns receive PN tracking, duplicate detection, packet-key
273lifetimes and key-phase transitions. `QUIC_PACKET_RED=1 sigil test
274test/test-packet.sgl` must fail eight RFC 9000/9001 controls before the normal
275suite passes.
277Connections clear their private traffic-secret copies after deriving packet
278keys, including the application read-key candidate used to authenticate an
279unsupported update. AES, IV and HP bytes remain live until their packet space
280is discarded. This preserves the low-level packet factories' caller-owned
281traffic-secret component and `next-traffic-keys` API. Actual key-update support
282will require retaining the appropriate update secret again.
283Packet factories clear their private Initial extraction/side intermediates and
284discard partial key material if a later derivation throws. Borrowed inputs and
285complete returned vectors keep their caller's ownership.
287Authenticated PATH_CHALLENGE frames receive matching PATH_RESPONSE frames,
288independently of an application handler. Address-bound connections route each
289response to the challenge's source. Responses precede application backlog,
290expire while blocked and are not retransmitted on PTO. Independent candidate
291and previous-path validation uses fresh, paced probes and separate three-times
292received-byte budgets. Promotion requires reachability and a 1200-byte MTU
293check. The UDP endpoint below supplies this address-bound adapter on numeric interfaces.
295Zero-length CID policy is enforced after packet authentication and before any
296application handler: NEW_CONNECTION_ID is forbidden when sending a zero-length
297destination CID, and RETIRE_CONNECTION_ID is forbidden after issuing a
298zero-length local CID. Both close with PROTOCOL_VIOLATION and the offending
299frame type. RETIRE_CONNECTION_ID above the largest issued sequence also closes
300with PROTOCOL_VIOLATION. A server's preferred-address CID has sequence 1; other
301caller-issued NEW_CONNECTION_ID sequences count only after packet emission,
302including PTO retransmission, rather than queue admission. Address-bound
303connections own spare-ID issuance and path assignment: reservations become
304routable only after emission, retired aliases stop routing immediately, and
305RETIRE_CONNECTION_ID remains pending until its carrying packet is acknowledged.
306These pools enforce the negotiated active limit and bounded lifetime inventory.
308`(sigil quic connection space)` provides bounded PN/ACK bookkeeping for
309each 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`;
312apply a new packet's frames before recording it with `packet-space-receive!`.
313Received intervals merge, and retiring old intervals advances a replay floor.
314ACK-only packets enter history without requesting another ACK.
315`packet-space-take-ack!` drains an immediate zero-delay ACK when needed.
317Check `packet-space-can-send?` before sealing `packet-space-next`; then commit
318that exact PN through `packet-space-record-sent!` with its size, monotonic
319millisecond timestamp and ACK-eliciting flag. Failed admission after sealing
320requires discarding the packet and closing; reuse must never encrypt different
321data at that PN. `packet-space-ack!` rejects ACKs of unsent numbers and releases
322matching in-flight metadata/credit. `packet-space-retire!` frees loss metadata
323without resetting the PN, and `packet-space-discard!` permanently closes the
324space. This bookkeeping does not implement congestion control, loss timers
325or frame retransmission; those belong to the connection.
327`(sigil quic error)` attaches transport code/frame metadata to standard Sigil
328error objects via `raise-quic-error`; inspect with `quic-error?` and its
329code/frame-type/reason accessors. Authenticated reserved bits, forbidden frame
330placement and ACKs of unsent packets retain PROTOCOL_VIOLATION metadata.
331An empty payload raises typed PROTOCOL_VIOLATION; it is not a frame encoding
332error. Generic frame parse exceptions still require FRAME_ENCODING_ERROR mapping
333after packet authentication in the connection. `QUIC_SPACE_RED=1 sigil test
334test/test-connection-space.sgl` must fail four controls before the normal suite
335passes.
337`(sigil quic connection)` integrates TLS with protected datagrams without
338opening a socket. Construct a client/server with explicit ALPN, parameters,
339certificate policy and CIDs; the connection supplies its CID transport
340parameters. Start clients with `quic-start! connection now`, feed datagrams
341with `quic-receive! connection bytes now`, call `quic-tick! connection now`
342and immediately send the ordered list from `quic-take-datagrams! connection now`.
343Times are monotonic exact milliseconds. The UDP endpoint binds the original
344peer address before starting or receiving the handshake.
346A transport adapter can instead call `quic-bind-peer-address! connection bytes`
347once before starting or receiving the handshake. The adapter supplies canonical
348IP-and-port bytes, bounded to 1–64 bytes, and must pass the actual source through
349`quic-receive! connection bytes now address: source`. It drains protected output
350with `quic-take-addressed-datagrams! connection now`. Each output has copied
351bytes, destination address and destination CID through `quic-output-bytes`,
352`quic-output-address` and `quic-output-id`. Check `quic-output-valid? connection
353output` immediately before sending retained output: path promotion, CID
354retirement or closure can invalidate a previously queued datagram. Raw datagram
355output is unavailable after binding an address.
357`quic-peer-address` returns the current validated destination. Drain up to sixteen
358retained diagnostics with `quic-take-path-events!`; each is a vector containing
359`path-changed`, `path-validated` or `path-failed`, owned address bytes and a reason
360symbol. A changed-path event does not authorize sending application data there.
361Only authenticated, replay-checked, handler-ready packets earn path credit;
362clients discard unknown server sources. Server migration uses validated paths
363and separate peer CIDs, requeues reliable flight under fresh packet numbers and
364resets congestion accounting. DATAGRAM payloads are never retransmitted.
366After validating a Retry token, the caller can pass `retry-source-id:` to
367`make-quic-server`. The original positional destination ID remains the first
368client DCID; the keyword is the server's distinct Retry source CID. The server
369derives Initial keys from the Retry CID and supplies both original and Retry
370CID transport parameters. Retransmitted Initials route to the Retry or server
371local CID. All supplied IDs are copied. This metadata does not validate an
372address by itself: the caller owns token validation, and the constructor retains
373the conservative amplification bound until authenticated Handshake traffic.
375The connection pads Initial datagrams to 1200 bytes, limits unvalidated server
376output to three times received bytes, bounds deferred packets/CRYPTO/queues,
377tracks directional keys and PN spaces, and confirms with HANDSHAKE_DONE.
378It uses immediate ACKs, a conservative send window, bounded fixed-base PTO
379backoff and fresh-PN frame retransmission, rather than full RFC 9002 recovery.
380RFC 9221 DATAGRAM payloads are excluded from retransmission; their loss timer
381uses a PING probe while retaining ordinary congestion and ACK bookkeeping.
382Handshake timeout defaults to 10 seconds. A client accepts one valid routed Retry
383after sending its first Initial and before processing a server Initial. It keeps
384the original ClientHello, client source CID and packet-number progression, changes
385Initial keys and destination CID, and includes the copied token on retransmissions.
386Retry tokens over 1024 bytes are dropped; the retained first ClientHello is capped
387at 64 KiB. CRYPTO fragmentation accounts for the token within 1200-byte Initials.
388Retry does not restart the handshake deadline. The first accepted server Initial
389binds the original, server Initial and Retry source IDs to the TLS transport checks.
390VN, key updates, migration and connection-ID rotation
391are not implemented. Stream ownership/flow control and
392path/CID policy still belong to the layers above this primitive. No public
393listener is provided, and independent security review is still required.
395Require `quic-complete?` for authenticated application delivery;
396`quic-confirmed?` reports handshake confirmation. Attach an application-frame
397handler with `quic-set-frame-handler!` and queue application frames with
398`quic-send-frame!`. Before attachment, authenticated packets containing STREAM,
399RESET_STREAM, STOP_SENDING or application flow-control frames are dropped whole,
400without applying a prefix, recording their PN, acknowledging them or refreshing
401idle activity. The peer can retransmit after attachment; no additional input
402buffer is retained. Transport-only packets still drive handshake confirmation,
403ACKs, path responses, CID validation and close without an application handler.
404A frame exceeding the connection's 1,200-byte packet budget
405(including its header and tag) raises synchronously before queue mutation;
406previously queued work and the connection remain usable. On `quic-closed?`,
407drain final close output and close the dedicated endpoint socket.
408`quic-failure` exposes local failure or the peer's
409close frame. Closure erases traffic keys, pending data and TLS secrets;
410`tls-abort!` provides the same idempotent TLS cleanup to standalone callers.
412To accept RFC 9221 DATAGRAM messages, include transport parameter `0x20`
413(`max_datagram_frame_size`) in the constructor's parameters, for example
414`(cons 32 (encode-varint 65535))`. The value includes the frame type, optional
415Length field and payload. Omission or zero disables receiving; receiving an
416unsupported or oversized frame closes with PROTOCOL_VIOLATION. Received limits
417use the actual wire size, including nonminimal Length-varint encodings.
419`quic-send-datagram! connection bytes` requires a complete authenticated
420handshake and a nonzero peer advertisement. It copies one whole message,
421queues a length-bearing frame (`0x31`) and returns `#t`; use `length?: #f` for
422the lengthless `0x30` form. Invalid inputs and peer or 1,200-byte packet size
423excess raise before queue mutation. No fragmentation is performed. A full
424send queue returns `#f`: at most `quic-datagram-queue-limit` (32) DATAGRAM
425messages may wait alongside the existing bounded frame queue. A full queue
426does not overwrite earlier messages. Sending through `quic-send-frame!` also
427enforces negotiation, size and count limits, but raises on queue refusal.
429`quic-read-datagram! connection` returns the oldest received message, or `#f`
430when none is available, the handshake is incomplete, or the connection is
431closed. An empty bytevector is a valid message. Receive dispatch is independent
432of the stream-frame handler. It retains at most 32 messages and
433`quic-datagram-byte-limit` (65,536) payload bytes; new arrivals beyond either
434budget are dropped while normal packet ACK processing continues. Reads release
435credit, and connection closure clears queued messages. DATAGRAM messages are
436unreliable, do not consume STREAM flow-control credit and are never retransmitted.
437Applications supply any flow identifiers inside their payloads.
439DATAGRAM codec/transport tests are in `test/test-datagram-codec.sgl`; protected
440connection tests in `test/test-datagram.sgl` use a standalone TLS peer that owns
441its keys. On a remote test machine, `node scripts/native-tls-tests.mjs --datagram`
442selects both files for the native test package described above. They are also
443included in the default bytecode and generated native suites.
445Server Initial packets carrying a token are discarded before CID pinning,
446authentication, receive credit or closing replay. During the handshake, other
447coalesced packets remain eligible for processing. ClientHello must have an
448empty legacy session ID; the server reports PROTOCOL_VIOLATION for a nonempty
449ID (RFC 9001 §8.4).
451Client receive tolerates authenticated server Initials in short datagrams.
452Our send path still pads ack-eliciting server Initials and all client Initials;
453servers still discard client Initials in datagrams under 1,200 bytes.
454Well-formed NewSessionTickets are discarded regardless of lifetime without
455retiring completed TLS. Ticket parsing and the 64-message work limit still apply.
456The ticket's optional `early_data` extension must contain the four-byte QUIC
457sentinel `0xffffffff`; another value closes with PROTOCOL_VIOLATION, while a
458malformed extension length produces TLS decode_error. No ticket enables 0-RTT.
460`QUIC_CONNECTION_RED=1 sigil test test/test-connection.sgl` must fail two
461completion controls. `QUIC_HP_SABOTAGE=1 sigil test test/test-connection.sgl`
462must fail only the dedicated positive handshake completion assertion: one
463protected PN byte is corrupted on every client Initial transmission and retry.
464A single transient corrupt datagram is recoverable and has a separate loss test.
466`(sigil quic stream)` provides one client-initiated bidirectional stream (ID 0).
467Use `stream-transport-parameters role receive-window: size` when constructing
468the connection, then attach `make-quic-stream connection` before starting or
469receiving packets. It validates its fixed allocation against the advertised
470stream/connection limits and owns the connection's application-frame handler.
471The default receive window is 65536 bytes, with a 1 MiB maximum.
473After authentication, `quic-stream-write! stream bytes fin?: boolean` accepts
474up to 900 bytes and returns the accepted count; retry the remainder after
475pumping 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 and
478advertises additional absolute credit as storage is freed. Empty reads can
479mean a gap or no data; use `quic-stream-eof?` for FIN completion and
480`quic-stream-reset-code` for a peer reset (including code zero).
481`quic-stream-reset!` and `quic-stream-stop!` take application error codes.
482STOP_SENDING cancels queued/in-flight STREAM retransmissions before RESET;
483FIN/RESET final sizes, credit, stream ownership and limits remain checked.
484Connection closure clears the stream's receive storage.
486The pure state layer is `(sigil quic stream state)`; its input frames must
487already have passed the frame codec. `make-quic-stream connection
488maximum-streams: count` optionally permits up to 16 sequential streams (one
489by default), with one active receive window. `quic-stream-id` reports its ID.
490Call `quic-stream-advance!` after both directions finish; it returns true only
491after peer FIN has been consumed, all outgoing STREAM/FIN data acknowledged,
492and enough control-queue capacity is available. A false result changes
493nothing. Servers then grant the next absolute MAX_STREAMS count; clients wait
494for that grant before writing their successor. Stream-specific cancellation
495and retransmission accounting use the current ID. Reset streams do not advance.
496The pure state constructor also accepts `maximum-streams:` from 1 (default)
497to 16, allowing bounded sequential IDs 0, 4, 8, ... through
498`stream-state-advance!`. Advancing requires fully consumed receiving FIN and
499a sending FIN; the caller must first ensure every outgoing STREAM/FIN is
500acknowledged. The operation wipes the previous receive window, preserves
501cumulative connection credit and retains only numeric final-size tombstones
502for retired IDs. It returns absolute credit frames, or false without changing
503state when advancement is unavailable. Reset streams cannot advance.
504`QUIC_SEQUENCE_RED=1 sigil test test/test-stream-sequence.sgl` must fail
505two independent wire controls before the full suite passes. Connection-ID
506rotation and path policy remain separate work.
507`QUIC_STREAM_RED=1 sigil test test/test-stream.sgl` must fail two byte controls
508before the full suite passes. Stream tests include protected bidirectional
509transfer beyond the receive-window capacity and reset/cancellation under loss.
511`(sigil quic endpoint)` uses a dedicated nonblocking IPv4 or IPv6 UDP socket
512for one connection. It binds the original peer before the handshake, sends
513each protected datagram to its recorded destination and validates confirmed
514server peer address changes. Clients keep their original server source.
515Multiple connections and cross-family migration remain outside this adapter.
517`(open-quic-endpoint host: "<assigned-numeric-IP>" port: 4433)` chooses the
518socket family from the checked host. The default host is `127.0.0.1`; port 0
519chooses an ephemeral port. IPv4 `0.0.0.0` and IPv6 `::` select wildcard binds;
520IPv6 sockets are IPv6-only. Numeric decimal IPv6 scope IDs are supported;
521hostnames and interface-name scope IDs are rejected. `quic-endpoint-host`,
522`quic-endpoint-family` and `quic-endpoint-port` expose the actual local bind.
523The host accessor returns an owned string.
525Attach a fresh client connection/stream with
526`(quic-endpoint-attach! endpoint connection peer-port peer-host: "<numeric-peer-IP>")`;
527this starts its TLS handshake. The peer must match the socket family; its
528omitted host defaults to that family's loopback. A server calls
529`quic-endpoint-accept! endpoint factory` instead. Its factory receives original
530destination/client source CIDs, constructs a server connection, attaches its
531stream handler and returns that connection. Optional `peer-host:` and
532`peer-port:` filters restrict admission independently; the first authenticated
533Initial pins any unspecified values. Before invoking the factory, the endpoint
534opens that Initial with ephemeral client Initial keys and requires a decoded,
535nonempty CRYPTO frame at offset zero. Keys are discarded after this check.
536Initial integrity is not address validation: Retry remains necessary before
537public operation. Failed candidates before confirmation release the slot and
538discard their output while preserving the factory and both configured filters.
539After confirmation, server candidate sources go through authenticated path
540validation; the admission filters do not prevent NAT rebinding. The endpoint
541retains one connection throughout.
543`(sigil quic address)` supplies bounded canonical peer keys through
544`quic-address`, `quic-address?`, `quic-address-host`, `quic-address-port` and
545`quic-address-family`. IPv4 retains its original six-byte address/port tuple.
546IPv6 uses distinct bounded framing with a canonical numeric host and scope;
547these keys are local path/Retry identities and never QUIC wire addresses.
549`quic-endpoint-peer-address` returns owned canonical peer bytes or `#f` before
550admission. `quic-endpoint-take-path-events!` drains the connection's bounded
551path events. Application data moves only after validation; a `path-changed`
552event alone does not change its destination. Retained ciphertext is checked
553again before each send, so CID retirement and path promotion can invalidate it.
555For private Retry testing, call `quic-endpoint-accept-retry! endpoint factory`
556instead. Its factory receives three copied IDs: original destination, client
557source and Retry source. Construct the server with the third ID as
558`retry-source-id:`, attach its stream handler, and return the owned connection.
559The endpoint checks the returned connection's CID metadata and aborts a
560rejected return. Optional `peer-host:` and `peer-port:` restrict admission;
561`token-lifetime:` is 1–60,000 milliseconds, default 10,000.
563The endpoint issues a challenge only after authenticating a tokenless Initial
564of at least 1,200 bytes with nonempty CRYPTO at offset zero. It retains no
565challenge queue or peer pin. Before invoking the factory or pinning a source,
566it validates the private token against the actual canonical source host and UDP
567port, current source/destination CIDs and monotonic time, then authenticates
568the retried Initial. Invalid token-bearing Initials drop without another Retry.
569Each receive pass permits at most 32 challenge attempts; each challenge fits
5701,200 bytes and the three-times-received budget. A blocked challenge send drops.
571The endpoint owns a fresh token key, keeps it across failed tentative
572connections, and retires it on confirmation or endpoint close. The connection
573keeps its conservative amplification limit until authenticated Handshake.
574This adapter remains experimental and requires independent review before public use.
576Call `quic-endpoint-step! endpoint wait-ms: milliseconds` repeatedly alongside
577application reads/writes. Each call waits at most 50 milliseconds and drives
578receive, timers and protected output. Each flush attempts at most 32 retained
579plus 32 fresh protected datagrams, once per record, and retains at most 32
580failed sends. One blocked address cannot stop validation controls for another.
581Each retained record keeps its original one-second deadline; expiry and
582overflow drop ciphertext as UDP loss. Reliable frames remain owned by the
583connection's retransmission machinery, while DATAGRAM data is unreliable.
584Malformed output and partial datagram sends close the socket and connection.
585`quic-endpoint-connection`, `quic-endpoint-closed?` and
586`quic-endpoint-failure` expose progress. `quic-endpoint-close!` is idempotent,
587clears connection/stream secrets and storage, attempts final close output,
588and closes the dedicated socket. Cleanup also runs if initiating connection
589closure raises; the exception propagates after socket/cache release.
590`quic-close!` closes a standalone connection
591with an application `code:` and UTF-8 `reason:` (at most 1,024 bytes). At
5921-RTT it sends application CONNECTION_CLOSE (0x1d); Initial/Handshake closes
593use transport APPLICATION_ERROR (0x0c) with an empty reason. Local application
594details remain available through `quic-application-error?`,
595`quic-application-error-code` and `quic-application-error-reason` in
596`(sigil quic error)`. Invalid application metadata raises before closing.
597`quic-transport-close!` explicitly sends a transport `code:`/`frame-type:`;
598its `reason:` remains a local diagnostic. Both paths are idempotent and retain
599the first failure. Either close frame may use the final reserved AEAD seal.
600Before confirmation, a local close is attempted at every available write
601level, ordered Initial, Handshake, then 1-RTT. Each copy retains its AEAD and
602anti-amplification checks. After confirmation, only 1-RTT is used. Traffic
603secrets are erased after the close copies are sealed.
605Standalone connections retain owned copies of those protected packets for
606three current PTOs. `quic-closed?` stays true; `quic-closing?` reports the
607remaining closing state while `quic-receive!`, `quic-tick!` and
608`quic-take-datagrams!` advance its monotonic clock. Routed incoming packets
609can trigger at most one byte-exact replay per PTO, without new encryption or
610a deadline extension. Replays use only the pre-close receive credit and stay
611within its cumulative 3x send limit, even for validated peers. Replays can
612therefore be suppressed after asymmetric traffic. `quic-abort!` immediately
613discards cached output and retires an open connection silently. The dedicated
614endpoint adapter ends closing early when it releases its UDP socket, as
615permitted by RFC 9000 §10.2, and discards the connection's cached output.
616Abandoned admission candidates also lose their cache before the slot is reused.
618Connections advertise a 30000 ms `max_idle_timeout` unless parameter 1 is
619explicitly supplied. The effective value is the minimum nonzero local and
620authenticated peer value; both zero disables expiry. The period is floored at
621three current PTOs (including the prototype's capped backoff). New processed
622authenticated packets restart it, as does only the first eliciting send since
623such a receipt. Corrupt/replayed packets, ACK-only output and repeated sends
624without a peer response do not restart it. `quic-tick!`, receive and output
625checks expire before accepting late activity. Idle expiry silently discards
626keys/queues and invokes close handlers; `quic-idle-expired?` reports this
627normal close with no transport failure. The endpoint discards retained output
628and closes its dedicated socket.
630Each key is limited to 2^23 AES-GCM encryptions, including ACKs and retransmits.
631The connection reserves its last permitted encryption for a typed
632`AEAD_LIMIT_REACHED` close (0x0f). Invalid packets accumulate across all read
633keys for the lifetime of the connection, with the standard 2^52 ceiling.
634Constructor options `aead-packet-limit:` and `aead-failure-limit:` can lower
635these ceilings; they cannot raise them. Invalid packets count once even if
636both current and candidate read keys are tried.
638Full key update is not implemented yet. Authenticated unexpected key phases
639close with `KEY_UPDATE_ERROR` (0x0e) before applying frames. A next-read
640candidate is precomputed with `next-traffic-keys`, using the QUIC `quic ku`
641label and preserving HP. Forged apparent updates are discarded unless the
642integrity ceiling is reached. Generic TLS `traffic-update` uses `traffic upd`
643and must not be used to derive QUIC updates. Candidate keys are disposed with
644their encryption level.
646On the test machine, `QUIC_ENDPOINT_RED=1 sigil test test/test-endpoint.sgl`
647must fail exactly two controls before the full suite passes. Endpoint tests
648use actual loopback UDP, arbitrary binary payloads beyond the receive window,
649peer-port filtering, bounded admission and failure/timeout cleanup.
650The focused native selector `scripts/native-tls-tests.mjs --endpoint-bind`
651adds canonical address tests and Retry/stream/DATAGRAM exchanges on IPv4, IPv6
652and wildcard binds. Assigned-interface cases accept `QUIC_TEST_INTERFACE_IPV4`
653and `QUIC_TEST_INTERFACE_IPV6`; absent values use loopback fixtures. Run these
654tests on a runtime providing the shared socket APIs described above.
656Receive work is bounded to eight parsed packets per datagram, including
657unrouted packets and authentication failures. Excess coalesced packets are
658dropped without closing the connection or undoing its accepted prefix.
659Each endpoint step handles at most 32 datagrams admitted to its connection
660and drains at most 96 total datagrams, so rejected source ports do not consume
661the connection budget and a noise flood still yields to the caller.
663Server ACK-only Initial packets are unpadded; client Initial packets and
664ack-eliciting server Initial packets retain the 1,200-byte minimum. Until a
665Handshake ACK or handshake confirmation proves the server validated the
666client, the client probes even with no data in flight: a Handshake PING if
667keys exist, otherwise a padded Initial PING. Initial ACKs preserve probe
668backoff, and existing deadline, idle and key-use limits still apply.
670To execute the same test bodies in a native binary on the test machine:
672```sh
673node scripts/native-tls-tests.mjs
674cd build/native-tests
675sigil deps install
676sigil build --config native
677# This control exits 1 with eleven vector failures.
678QUIC_TLS_EXT_RED=1 build/native/bin/quic-native-tests
679# This control exits 1 with seven authentication vector failures.
680QUIC_TLS_AUTH_RED=1 build/native/bin/quic-native-tests
681# This control exits 1 with four engine secret-comparison failures.
682QUIC_TLS_ENGINE_RED=1 build/native/bin/quic-native-tests
683# This control exits 1 with eight frame wire-comparison failures.
684QUIC_FRAME_RED=1 build/native/bin/quic-native-tests
685# This control exits 1 with four reassembly byte-comparison failures.
686QUIC_REASSEMBLY_RED=1 build/native/bin/quic-native-tests
687# This control exits 1 with eight packet/header/PN comparison failures.
688QUIC_PACKET_RED=1 build/native/bin/quic-native-tests
689# This control exits 1 with four packet-space/error comparison failures.
690QUIC_SPACE_RED=1 build/native/bin/quic-native-tests
691build/native/bin/quic-native-tests
692```
694The benchmark creates, protects, sends, receives, authenticates and parses
6951,200-byte packets on UDP loopback. It uses one process pinned to one CPU,
696warms up, and reports three samples for the full path and three controls:
697build/parse, UDP without crypto, and crypto without UDP. Controls include
698allocation and parsing overhead and should not be treated as additive
699isolated component costs. Timings include both sender and receiver work.
700Packet numbers increase throughout each run; traffic keys are fresh per
701process. The outer timeout bounds blocking UDP failures.
703Regenerate fixtures from RFC Editor plain texts with:
705```sh
706node scripts/extract-vectors.mjs rfc8448.txt rfc9001.txt
707node scripts/extract-handshake-vectors.mjs rfc8448.txt
708```