sigil-quic / tree / docsimplementation.md
sigil-quic
Experimental QUIC v1 packet protection and a TLS 1.3 handshake engine in Sigil. The experimental endpoint supports private numeric IPv4/IPv6 interface testing.
(sigil quic tls) exports SHA-256 HKDF-Expand-Label, key-schedule transitions, traffic updates, Finished MACs and the client/server handshake. (sigil quic packet) derives Initial keys, seals/opens payloads and applies/removes header protection with the AES-128 single-block primitive in sigil-crypto.
The package requires sigil-crypto ^0.18.1, which includes the AES block API. Install released dependencies normally, without development redirects. Configured UDP endpoints additionally require the shared (sigil socket) family-aware udp-socket and socket-normalize-address APIs, introduced by Sigil commit d237e25c6d881300cf37eedbc657b2203badec0f. That shared runtime change has not been released yet: the current published runtime alone cannot run the configured endpoint. The focused endpoint gate uses a runtime built with that change; upstream availability is required for normal consumption. RFC 9001 tests derive real AES masks and check complete client/server Initial packets, sample selection, payload authentication and inverse processing.
Build on a Linux measurement machine:
sigil deps install
sigil build --config native
scripts/run-gates.sh build/native/bin/quic-probeThe gate runs a red invocation first, changing one byte in every expected vector and requiring every comparison to fail, then the original vectors. It also checks rejection after changing each ciphertext/tag byte and the AAD. RFC 8448 section 3 checks chain actual X25519 and transcript hashes through the handshake, master, traffic, exporter and resumption secrets.
TLS wire helpers live in (sigil quic tls codec), (sigil quic tls messages) and (sigil quic tls signature). They provide bounded handshake framing, duplicate-rejecting extensions, Hello codecs and P-256 CertificateVerify encoding/signing. Run sigil test for their truncation, malformed-input and signature-binding checks. The control QUIC_TLS_CODEC_RED=1 sigil test test/test-tls-codec.sgl must fail exactly the four known-byte comparisons before the normal suite passes.
(sigil quic tls extensions) handles ALPN, SNI, negotiation lists, key shares, cookies and server extension placement. (sigil quic wire) provides exact 62-bit varints; (sigil quic transport parameters) checks parameter bounds, role restrictions and connection ID bindings. Transport parameters become authenticated when the handshake verifies Finished. QUIC_TLS_EXT_RED=1 sigil test test/test-tls-extensions.sgl must fail its eleven known-byte comparisons before the normal suite passes.
(sigil quic tls authentication) encodes and bounds authentication-flight messages with opaque certificate entries. (sigil quic tls transcript) tracks SHA-256 transcript hashes and the one-time HelloRetryRequest message_hash transformation, with message-count and byte limits. QUIC_TLS_AUTH_RED=1 sigil test test/test-tls-authentication.sgl must fail seven published-byte/hash controls before the normal suite passes.
The handshake engine supports TLS_AES_128_GCM_SHA256, X25519, ecdsa_secp256r1_sha256, ALPN, optional SNI, QUIC transport parameters and one HelloRetryRequest. It has no TLS records, sockets, PSK authentication, 0-RTT acceptance or client identity. Unknown PSK offers are structurally validated and fall back to the full X25519/certificate handshake. Retry allows updated ticket ages/binders and removal of identities, while rejecting new or reordered identities and a repeated early-data offer. No PSK or early-data selection is sent. An optional CertificateRequest is declined with an empty Certificate. Bounded NewSessionTicket messages are checked and discarded; TLS KeyUpdate is rejected.
Extension and client key-share duplicate tracking use fixed 8 KiB bitmaps for the complete uint16 identifier space. Marking each ID takes constant time; the existing wire-size bounds and duplicate rejection remain in force. Incoming SNI values outside the supported DNS syntax are treated as unrecognized: the server continues with its configured certificate and omits the SNI acknowledgement. Empty host names, duplicate name types and malformed vectors still fail. Outgoing client SNI retains strict DNS-name validation; the client verifier must authenticate the intended identity or pin.
make-tls-client takes ALPN bytevectors, an explicit identity, local transport parameters and a verifier. A DNS-name identity requires a callback that receives the DER chain and requested name, validates both the chain and name, and returns the authenticated leaf's raw 65-byte P-256 public key or #f to reject. There is no built-in X.509 trust store. An unnamed #f identity is rejected.
For an independently trusted raw public key, use identity 'pinned-key and (make-tls-pin-verifier public-key). This mode sends no SNI and authenticates possession of that key through CertificateVerify and Finished. It requires the library-created verifier token; arbitrary callbacks are rejected in pin mode. The optional certificate: bytevector additionally pins the exact leaf DER. The factory copies both inputs and never adopts a key from the peer's certificate. Pinning authenticates the configured key; it performs no X.509 path, expiry or DNS-name validation. make-quic-client uses the same contract. make-tls-server takes ALPN preferences, local parameters, a DER certificate chain and a 32-byte P-256 private key. Each engine owns its copied signing key.
Call tls-bind-peer! once with the original destination CID, peer's initial source CID and Retry source CID (#f without QUIC Retry), taken from packet headers. Bind before peer transport parameters arrive. Start clients with tls-start!; deliver ordered, reassembled CRYPTO bytes through tls-input! engine level bytes, where level is initial, handshake or application. The four-byte header is checked against the current state before its body is accepted. Hello, EncryptedExtensions, CertificateRequest and discarded tickets are limited to 16 KiB; ECDSA CertificateVerify to 76 bytes, Finished to exactly 32 bytes, and Certificate to 1 MiB. Input storage grows only as bytes arrive, with bounded geometric slack and wiped replaced prefixes. Transcript/ticket counts are bounded; completion and failure clear and drop the retained transcript. tls-retained-input-bytes reports input capacity plus retained transcript bytes, excluding secrets and outbound events.
tls-take-events! drains ordered events. A crypto event carries its level and handshake bytes. A secrets event carries its level and a pair of read/write traffic secrets; #f means that direction is not installed by that event. These keys are provisional packet-protection material. Require tls-complete? before accepting application data; tls-negotiated-alpn and tls-peer-parameters return authenticated copies only after completion. Failure permanently closes the engine, clears retained secrets and discards queued events. The caller must also discard already installed packet keys. The implementation still needs independent security review before public use.
The key schedule clears its owned derived HKDF salts and Finished HMAC keys on return and exception; borrowed inputs and returned results remain owned by the caller. Zeroization is best-effort: these writes clear reachable mutable buffers, without guaranteeing erasure of compiler, garbage-collector or native-library copies. In sigil-crypto 0.18.1, internal HKDF MAC-chain and accumulator buffers and native HMAC stack outputs are not exposed to this library and cannot be cleared here. Cleanup requires normal return or stack unwinding; process termination and failures that prevent unwinding can bypass it.
The engine clears its private key share after deriving handshake secrets and its master secret after deriving application traffic secrets. Completion or abort clears copied signing keys and remaining engine-owned traffic secrets. The server clears its owned server handshake-traffic secret after emitting Finished; queued packet-key event copies remain owned by the caller. Its client handshake-traffic secret stays live until the peer Finished verifies, and clients retain their server handshake-traffic secret until authentication. Handshake derivation also clears its owned shared, early and handshake-secret intermediates when a later primitive throws, as well as on normal return. Fresh key-share private bytes belong to the engine before public-key generation, so an exception from that primitive also reaches the engine's abort cleanup. Secret-event copies stay in a cleanup scope until queued; a later copy or queue failure clears partial results. Drained event copies belong to the caller and remain live until the caller clears them. Server construction clears its copied signing key if engine creation fails. QUIC construction retains ownership of its fresh TLS engine and any installed Initial keys until initialization succeeds, clearing them on an exception.
raise-tls-alert, tls-alert?, tls-alert-code and tls-alert-reason preserve TLS alert metadata. Connections map these to QUIC CRYPTO_ERROR 0x0100 plus the alert: failed/absent ALPN is 0x0178, missing transport parameters 0x016d, and TLS KeyUpdate/unexpected handshake types 0x010a. QUIC transport errors keep their own codes; unclassified TLS failures retain the generic handshake_failure fallback.
QUIC_TLS_ENGINE_RED=1 sigil test test/test-tls-handshake.sgl must fail four directional-secret controls before the normal suite passes. Engine tests exercise both roles in memory, fragmented/coalesced flights, HRR, explicit certificate rejection, signature/MAC corruption, CID bindings and level/order failures. These tests do not replace independent QUIC interoperability checks.
(sigil quic frame) provides decode-frames payload level sender, encode-frame frame and encode-frames frames level sender for RFC 9000 types 0x00 through 0x1e. Construct a frame with make-quic-frame type fields, where fields is an alist; use quic-frame-type, quic-frame-fields and frame-ref to inspect it. ACK ranges are inclusive (low . high) pairs in descending order and delay is the unscaled wire value. STREAM frames carry stream-id, offset (zero when absent) and data; the numeric type preserves OFF/LEN/FIN flags. frame-fin? and frame-ack-eliciting? expose those common classifications. CRYPTO frames carry offset and data.
Frame decoding checks type encoding, payload/field bounds, role/level placement, ACK arithmetic, CID lengths and 62-bit end offsets. Limits are 65,527 payload bytes, 256 frames and 256 ACK ranges; consecutive padding is represented by one frame with a length field. Local decode work exhaustion raises an exception recognized by frame-work-limit?; the connection drops that entire packet before applying frames, recording an ACK or refreshing receive activity. The peer must retransmit its data within these budgets. Invalid wire encodings still produce transport errors. Local encoders enforce the same frame/range limits. Connection policy must still check stream ownership/flow control, ACKs against sent packets, CID inventory and path validation. QUIC_FRAME_RED=1 sigil test test/test-frame.sgl must fail eight independent wire controls, including the two RFC 9001 payloads, before the normal suite passes.
(sigil quic reassembly) provides fixed-capacity byte-offset windows for CRYPTO and stream delivery. make-byte-reassembler capacity allocates data and presence rings of that size, with a 1 MiB maximum. CRYPTO callers must budget at least 4096 bytes and use a separate receiver per encryption level. reassembler-insert! receiver offset bytes returns the newly buffered byte count. It checks the whole incoming range before mutation, requires buffered overlaps to agree, discards already delivered prefixes and rejects data beyond the moving receive window. Offsets never determine allocation size.
reassembler-read! receiver returns the available contiguous prefix; an optional byte limit allows partial reads. reassembler-offset tracks bytes delivered, reassembler-buffered counts pending unique bytes, and reassembler-highest records the highest accepted nonempty end offset. Empty inserts leave that watermark unchanged. Returned/input data is copied; reassembler-close! clears storage and prevents further insertion/reading. reassembly-error? and reassembly-error-kind distinguish capacity and conflict failures without changing state. The connection maps CRYPTO window exhaustion to CRYPTO_BUFFER_EXCEEDED and conflicting buffered bytes to PROTOCOL_VIOLATION. Invalid local arguments remain ordinary exceptions. The connection layer must enforce stream flow control/final size and handle reassembly errors. QUIC_REASSEMBLY_RED=1 sigil test test/test-reassembly.sgl must fail four byte controls before the normal suite passes. An integration test completes both TLS roles with HRR through reordered CRYPTO-frame bytes.
(sigil quic packet header) parses packet boundaries with decode-packet-header datagram offset short-dcid-length and builds unprotected v1 Initial/Handshake/short headers with encode-packet-header. Header start and end are absolute datagram offsets; pn-offset is relative to start. Short headers consume the remaining datagram. Parsing caps datagrams at 65,527 bytes, v1 CIDs at 20 bytes and VN version lists at 256 entries. VN, Retry and unsupported versions are recognized separately. Retry integrity helpers are available in (sigil quic packet retry) and re-exported by the packet façade: encode-retry-packet original-id destination-id source-id token and valid-retry-packet? original-id wire. The encoder accepts unused: from 0 to 15; the validator drops malformed peer packets. Both bound CIDs and datagram size. The standardized public integrity tag does not authenticate a server or validate an address. Private token admission, version negotiation and connection-ID policy remain separate from this packet helper; the private loopback endpoint has an opt-in Retry admission path described below.
(sigil quic retry token) provides private server tokens through make-retry-token-manager, make-retry-token, validate-retry-token and close-retry-token-manager!. Managers own a fresh 32-byte key by default; an optional key: is copied for explicit shared-server key management. lifetime: defaults to 10,000 ms and is bounded to 1–60,000 ms. Close each manager explicitly when retiring its key; tokens from other keys stop validating.
make-retry-token manager address original-id retry-id client-id now authenticates a Retry-only version, issuance time, random nonce and original destination CID with HMAC-SHA256. Canonical address bytes (1–64 bytes, including IP and port), Retry source CID and client source CID are length-delimited authenticated context. The token contains no address bytes and is not encrypted. It is not a NEW_TOKEN format. The original CID already appears in the same handshake's first Initial. validate-retry-token manager address retry-id client-id token now returns an owned original CID or #f for malformed, forged, future or expired tokens. Times must use the same monotonic millisecond clock; expiry is exclusive. Replay is limited to the bound address/CIDs and validity window. Local argument errors and use after close raise. Operational crypto errors retire the key and raise. Endpoint token admission is not integrated yet; no listener uses this API.
(sigil quic packet) re-exports those helpers and provides seal-quic-packet material kind dcid scid number plaintext with optional token:, pn-length:, length-width:, key-phase: and spin: keywords. Kinds are initial, handshake and application. It pads tiny payloads enough for a confined header-protection sample. The caller must separately ensure the 1200-byte Initial datagram minimum and peer/MTU limits.
protect-payload and seal-quic-packet are stateless cryptographic primitives. The caller owns packet-number commitments and AEAD usage accounting for each directional AES key/IV. That state covers both entry points and every copy of the same key material: copying a key vector preserves its nonce space. Commit a fresh PN for each encryption attempt. If encryption might have used it, retire that PN even when a later allocation or header-protection step raises; retry with a fresh PN, or retire the key when commitment state is uncertain. (sigil quic connection) manages these commitments, usage ceilings and failure cleanup for normal connection traffic.
open-quic-packet datagram offset short-dcid-length material largest reconstructs the PN (largest = -1 for an empty space) and authenticates one packet. Successful results expose its header, number, payload, key phase and spin through opened-quic-packet-* accessors. The input remains unchanged.
AEAD failure returns #f; unauthenticated framing/PN errors throw and require packet discard. Nonzero reserved bits are checked only after authentication and require a connection-level PROTOCOL_VIOLATION. HP sampling is restricted to the packet's own boundary even in coalesced datagrams. traffic-keys derives owned QUIC key material from a 32-byte traffic secret using the same vector layout as initial-keys; discard-packet-keys! clears and disables it. The connection layer owns receive PN tracking, duplicate detection, packet-key lifetimes and key-phase transitions. QUIC_PACKET_RED=1 sigil test test/test-packet.sgl must fail eight RFC 9000/9001 controls before the normal suite passes.
Connections clear their private traffic-secret copies after deriving packet keys, including the application read-key candidate used to authenticate an unsupported update. AES, IV and HP bytes remain live until their packet space is discarded. This preserves the low-level packet factories' caller-owned traffic-secret component and next-traffic-keys API. Actual key-update support will require retaining the appropriate update secret again. Packet factories clear their private Initial extraction/side intermediates and discard partial key material if a later derivation throws. Borrowed inputs and complete returned vectors keep their caller's ownership.
Authenticated PATH_CHALLENGE frames receive matching PATH_RESPONSE frames, independently of an application handler. Address-bound connections route each response to the challenge's source. Responses precede application backlog, expire while blocked and are not retransmitted on PTO. Independent candidate and previous-path validation uses fresh, paced probes and separate three-times received-byte budgets. Promotion requires reachability and a 1200-byte MTU check. The UDP endpoint below supplies this address-bound adapter on numeric interfaces.
Zero-length CID policy is enforced after packet authentication and before any application handler: NEW_CONNECTION_ID is forbidden when sending a zero-length destination CID, and RETIRE_CONNECTION_ID is forbidden after issuing a zero-length local CID. Both close with PROTOCOL_VIOLATION and the offending frame type. RETIRE_CONNECTION_ID above the largest issued sequence also closes with PROTOCOL_VIOLATION. A server's preferred-address CID has sequence 1; other caller-issued NEW_CONNECTION_ID sequences count only after packet emission, including PTO retransmission, rather than queue admission. Address-bound connections own spare-ID issuance and path assignment: reservations become routable only after emission, retired aliases stop routing immediately, and RETIRE_CONNECTION_ID remains pending until its carrying packet is acknowledged. These pools enforce the negotiated active limit and bounded lifetime inventory.
(sigil quic connection space) provides bounded PN/ACK bookkeeping for each encryption level. make-packet-space level accepts range-limit:, pending-limit: and byte-limit: budgets (defaults 64, 128 and 262144). packet-space-received-status classifies a PN as new, duplicate or old; apply a new packet's frames before recording it with packet-space-receive!. Received intervals merge, and retiring old intervals advances a replay floor. ACK-only packets enter history without requesting another ACK. packet-space-take-ack! drains an immediate zero-delay ACK when needed.
Check packet-space-can-send? before sealing packet-space-next; then commit that exact PN through packet-space-record-sent! with its size, monotonic millisecond timestamp and ACK-eliciting flag. Failed admission after sealing requires discarding the packet and closing; reuse must never encrypt different data at that PN. packet-space-ack! rejects ACKs of unsent numbers and releases matching in-flight metadata/credit. packet-space-retire! frees loss metadata without resetting the PN, and packet-space-discard! permanently closes the space. This bookkeeping does not implement congestion control, loss timers or frame retransmission; those belong to the connection.
(sigil quic error) attaches transport code/frame metadata to standard Sigil error objects via raise-quic-error; inspect with quic-error? and its code/frame-type/reason accessors. Authenticated reserved bits, forbidden frame placement and ACKs of unsent packets retain PROTOCOL_VIOLATION metadata. An empty payload raises typed PROTOCOL_VIOLATION; it is not a frame encoding error. Generic frame parse exceptions still require FRAME_ENCODING_ERROR mapping after packet authentication in the connection. QUIC_SPACE_RED=1 sigil test test/test-connection-space.sgl must fail four controls before the normal suite passes.
(sigil quic connection) integrates TLS with protected datagrams without opening a socket. Construct a client/server with explicit ALPN, parameters, certificate policy and CIDs; the connection supplies its CID transport parameters. Start clients with quic-start! connection now, feed datagrams with quic-receive! connection bytes now, call quic-tick! connection now and immediately send the ordered list from quic-take-datagrams! connection now. Times are monotonic exact milliseconds. The UDP endpoint binds the original peer address before starting or receiving the handshake.
A transport adapter can instead call quic-bind-peer-address! connection bytes once before starting or receiving the handshake. The adapter supplies canonical IP-and-port bytes, bounded to 1–64 bytes, and must pass the actual source through quic-receive! connection bytes now address: source. It drains protected output with quic-take-addressed-datagrams! connection now. Each output has copied bytes, destination address and destination CID through quic-output-bytes, quic-output-address and quic-output-id. Check quic-output-valid? connection output immediately before sending retained output: path promotion, CID retirement or closure can invalidate a previously queued datagram. Raw datagram output is unavailable after binding an address.
quic-peer-address returns the current validated destination. Drain up to sixteen retained diagnostics with quic-take-path-events!; each is a vector containing path-changed, path-validated or path-failed, owned address bytes and a reason symbol. A changed-path event does not authorize sending application data there. Only authenticated, replay-checked, handler-ready packets earn path credit; clients discard unknown server sources. Server migration uses validated paths and separate peer CIDs, requeues reliable flight under fresh packet numbers and resets congestion accounting. DATAGRAM payloads are never retransmitted.
After validating a Retry token, the caller can pass retry-source-id: to make-quic-server. The original positional destination ID remains the first client DCID; the keyword is the server's distinct Retry source CID. The server derives Initial keys from the Retry CID and supplies both original and Retry CID transport parameters. Retransmitted Initials route to the Retry or server local CID. All supplied IDs are copied. This metadata does not validate an address by itself: the caller owns token validation, and the constructor retains the conservative amplification bound until authenticated Handshake traffic.
The connection pads Initial datagrams to 1200 bytes, limits unvalidated server output to three times received bytes, bounds deferred packets/CRYPTO/queues, tracks directional keys and PN spaces, and confirms with HANDSHAKE_DONE. It uses immediate ACKs, a conservative send window, bounded fixed-base PTO backoff and fresh-PN frame retransmission, rather than full RFC 9002 recovery. RFC 9221 DATAGRAM payloads are excluded from retransmission; their loss timer uses a PING probe while retaining ordinary congestion and ACK bookkeeping. Handshake timeout defaults to 10 seconds. A client accepts one valid routed Retry after sending its first Initial and before processing a server Initial. It keeps the original ClientHello, client source CID and packet-number progression, changes Initial keys and destination CID, and includes the copied token on retransmissions. Retry tokens over 1024 bytes are dropped; the retained first ClientHello is capped at 64 KiB. CRYPTO fragmentation accounts for the token within 1200-byte Initials. Retry does not restart the handshake deadline. The first accepted server Initial binds the original, server Initial and Retry source IDs to the TLS transport checks. VN, key updates, migration and connection-ID rotation are not implemented. Stream ownership/flow control and path/CID policy still belong to the layers above this primitive. No public listener is provided, and independent security review is still required.
Require quic-complete? for authenticated application delivery; quic-confirmed? reports handshake confirmation. Attach an application-frame handler with quic-set-frame-handler! and queue application frames with quic-send-frame!. Before attachment, authenticated packets containing STREAM, RESET_STREAM, STOP_SENDING or application flow-control frames are dropped whole, without applying a prefix, recording their PN, acknowledging them or refreshing idle activity. The peer can retransmit after attachment; no additional input buffer is retained. Transport-only packets still drive handshake confirmation, ACKs, path responses, CID validation and close without an application handler. A frame exceeding the connection's 1,200-byte packet budget (including its header and tag) raises synchronously before queue mutation; previously queued work and the connection remain usable. On quic-closed?, drain final close output and close the dedicated endpoint socket. quic-failure exposes local failure or the peer's close frame. Closure erases traffic keys, pending data and TLS secrets; tls-abort! provides the same idempotent TLS cleanup to standalone callers.
To accept RFC 9221 DATAGRAM messages, include transport parameter 0x20 (max_datagram_frame_size) in the constructor's parameters, for example (cons 32 (encode-varint 65535)). The value includes the frame type, optional Length field and payload. Omission or zero disables receiving; receiving an unsupported or oversized frame closes with PROTOCOL_VIOLATION. Received limits use the actual wire size, including nonminimal Length-varint encodings.
quic-send-datagram! connection bytes requires a complete authenticated handshake and a nonzero peer advertisement. It copies one whole message, queues a length-bearing frame (0x31) and returns #t; use length?: #f for the lengthless 0x30 form. Invalid inputs and peer or 1,200-byte packet size excess raise before queue mutation. No fragmentation is performed. A full send queue returns #f: at most quic-datagram-queue-limit (32) DATAGRAM messages may wait alongside the existing bounded frame queue. A full queue does not overwrite earlier messages. Sending through quic-send-frame! also enforces negotiation, size and count limits, but raises on queue refusal.
quic-read-datagram! connection returns the oldest received message, or #f when none is available, the handshake is incomplete, or the connection is closed. An empty bytevector is a valid message. Receive dispatch is independent of the stream-frame handler. It retains at most 32 messages and quic-datagram-byte-limit (65,536) payload bytes; new arrivals beyond either budget are dropped while normal packet ACK processing continues. Reads release credit, and connection closure clears queued messages. DATAGRAM messages are unreliable, do not consume STREAM flow-control credit and are never retransmitted. Applications supply any flow identifiers inside their payloads.
DATAGRAM codec/transport tests are in test/test-datagram-codec.sgl; protected connection tests in test/test-datagram.sgl use a standalone TLS peer that owns its keys. On a remote test machine, node scripts/native-tls-tests.mjs --datagram selects both files for the native test package described above. They are also included in the default bytecode and generated native suites.
Server Initial packets carrying a token are discarded before CID pinning, authentication, receive credit or closing replay. During the handshake, other coalesced packets remain eligible for processing. ClientHello must have an empty legacy session ID; the server reports PROTOCOL_VIOLATION for a nonempty ID (RFC 9001 §8.4).
Client receive tolerates authenticated server Initials in short datagrams. Our send path still pads ack-eliciting server Initials and all client Initials; servers still discard client Initials in datagrams under 1,200 bytes. Well-formed NewSessionTickets are discarded regardless of lifetime without retiring completed TLS. Ticket parsing and the 64-message work limit still apply. The ticket's optional early_data extension must contain the four-byte QUIC sentinel 0xffffffff; another value closes with PROTOCOL_VIOLATION, while a malformed extension length produces TLS decode_error. No ticket enables 0-RTT.
QUIC_CONNECTION_RED=1 sigil test test/test-connection.sgl must fail two completion controls. QUIC_HP_SABOTAGE=1 sigil test test/test-connection.sgl must fail only the dedicated positive handshake completion assertion: one protected PN byte is corrupted on every client Initial transmission and retry. A single transient corrupt datagram is recoverable and has a separate loss test.
(sigil quic stream) provides one client-initiated bidirectional stream (ID 0). Use stream-transport-parameters role receive-window: size when constructing the connection, then attach make-quic-stream connection before starting or receiving packets. It validates its fixed allocation against the advertised stream/connection limits and owns the connection's application-frame handler. The default receive window is 65536 bytes, with a 1 MiB maximum.
After authentication, quic-stream-write! stream bytes fin?: boolean accepts up to 900 bytes and returns the accepted count; retry the remainder after pumping datagrams and credit. A zero-byte FIN can return zero successfully; quic-stream-send-closed? distinguishes it from a blocked write. quic-stream-read! stream maximum: count returns copied ordered bytes and advertises additional absolute credit as storage is freed. Empty reads can mean a gap or no data; use quic-stream-eof? for FIN completion and quic-stream-reset-code for a peer reset (including code zero). quic-stream-reset! and quic-stream-stop! take application error codes. STOP_SENDING cancels queued/in-flight STREAM retransmissions before RESET; FIN/RESET final sizes, credit, stream ownership and limits remain checked. Connection closure clears the stream's receive storage.
The pure state layer is (sigil quic stream state); its input frames must already have passed the frame codec. make-quic-stream connection maximum-streams: count optionally permits up to 16 sequential streams (one by default), with one active receive window. quic-stream-id reports its ID. Call quic-stream-advance! after both directions finish; it returns true only after peer FIN has been consumed, all outgoing STREAM/FIN data acknowledged, and enough control-queue capacity is available. A false result changes nothing. Servers then grant the next absolute MAX_STREAMS count; clients wait for that grant before writing their successor. Stream-specific cancellation and retransmission accounting use the current ID. Reset streams do not advance. The pure state constructor also accepts maximum-streams: from 1 (default) to 16, allowing bounded sequential IDs 0, 4, 8, ... through stream-state-advance!. Advancing requires fully consumed receiving FIN and a sending FIN; the caller must first ensure every outgoing STREAM/FIN is acknowledged. The operation wipes the previous receive window, preserves cumulative connection credit and retains only numeric final-size tombstones for retired IDs. It returns absolute credit frames, or false without changing state when advancement is unavailable. Reset streams cannot advance. QUIC_SEQUENCE_RED=1 sigil test test/test-stream-sequence.sgl must fail two independent wire controls before the full suite passes. Connection-ID rotation and path policy remain separate work. QUIC_STREAM_RED=1 sigil test test/test-stream.sgl must fail two byte controls before the full suite passes. Stream tests include protected bidirectional transfer beyond the receive-window capacity and reset/cancellation under loss.
(sigil quic endpoint) uses a dedicated nonblocking IPv4 or IPv6 UDP socket for one connection. It binds the original peer before the handshake, sends each protected datagram to its recorded destination and validates confirmed server peer address changes. Clients keep their original server source. Multiple connections and cross-family migration remain outside this adapter.
(open-quic-endpoint host: "<assigned-numeric-IP>" port: 4433) chooses the socket family from the checked host. The default host is 127.0.0.1; port 0 chooses an ephemeral port. IPv4 0.0.0.0 and IPv6 :: select wildcard binds; IPv6 sockets are IPv6-only. Numeric decimal IPv6 scope IDs are supported; hostnames and interface-name scope IDs are rejected. quic-endpoint-host, quic-endpoint-family and quic-endpoint-port expose the actual local bind. The host accessor returns an owned string.
Attach a fresh client connection/stream with (quic-endpoint-attach! endpoint connection peer-port peer-host: "<numeric-peer-IP>"); this starts its TLS handshake. The peer must match the socket family; its omitted host defaults to that family's loopback. A server calls quic-endpoint-accept! endpoint factory instead. Its factory receives original destination/client source CIDs, constructs a server connection, attaches its stream handler and returns that connection. Optional peer-host: and peer-port: filters restrict admission independently; the first authenticated Initial pins any unspecified values. Before invoking the factory, the endpoint opens that Initial with ephemeral client Initial keys and requires a decoded, nonempty CRYPTO frame at offset zero. Keys are discarded after this check. Initial integrity is not address validation: Retry remains necessary before public operation. Failed candidates before confirmation release the slot and discard their output while preserving the factory and both configured filters. After confirmation, server candidate sources go through authenticated path validation; the admission filters do not prevent NAT rebinding. The endpoint retains one connection throughout.
(sigil quic address) supplies bounded canonical peer keys through quic-address, quic-address?, quic-address-host, quic-address-port and quic-address-family. IPv4 retains its original six-byte address/port tuple. IPv6 uses distinct bounded framing with a canonical numeric host and scope; these keys are local path/Retry identities and never QUIC wire addresses.
quic-endpoint-peer-address returns owned canonical peer bytes or #f before admission. quic-endpoint-take-path-events! drains the connection's bounded path events. Application data moves only after validation; a path-changed event alone does not change its destination. Retained ciphertext is checked again before each send, so CID retirement and path promotion can invalidate it.
For private Retry testing, call quic-endpoint-accept-retry! endpoint factory instead. Its factory receives three copied IDs: original destination, client source and Retry source. Construct the server with the third ID as retry-source-id:, attach its stream handler, and return the owned connection. The endpoint checks the returned connection's CID metadata and aborts a rejected return. Optional peer-host: and peer-port: restrict admission; token-lifetime: is 1–60,000 milliseconds, default 10,000.
The endpoint issues a challenge only after authenticating a tokenless Initial of at least 1,200 bytes with nonempty CRYPTO at offset zero. It retains no challenge queue or peer pin. Before invoking the factory or pinning a source, it validates the private token against the actual canonical source host and UDP port, current source/destination CIDs and monotonic time, then authenticates the retried Initial. Invalid token-bearing Initials drop without another Retry. Each receive pass permits at most 32 challenge attempts; each challenge fits 1,200 bytes and the three-times-received budget. A blocked challenge send drops. The endpoint owns a fresh token key, keeps it across failed tentative connections, and retires it on confirmation or endpoint close. The connection keeps its conservative amplification limit until authenticated Handshake. This adapter remains experimental and requires independent review before public use.
Call quic-endpoint-step! endpoint wait-ms: milliseconds repeatedly alongside application reads/writes. Each call waits at most 50 milliseconds and drives receive, timers and protected output. Each flush attempts at most 32 retained plus 32 fresh protected datagrams, once per record, and retains at most 32 failed sends. One blocked address cannot stop validation controls for another. Each retained record keeps its original one-second deadline; expiry and overflow drop ciphertext as UDP loss. Reliable frames remain owned by the connection's retransmission machinery, while DATAGRAM data is unreliable. Malformed output and partial datagram sends close the socket and connection. quic-endpoint-connection, quic-endpoint-closed? and quic-endpoint-failure expose progress. quic-endpoint-close! is idempotent, clears connection/stream secrets and storage, attempts final close output, and closes the dedicated socket. Cleanup also runs if initiating connection closure raises; the exception propagates after socket/cache release. quic-close! closes a standalone connection with an application code: and UTF-8 reason: (at most 1,024 bytes). At 1-RTT it sends application CONNECTION_CLOSE (0x1d); Initial/Handshake closes use transport APPLICATION_ERROR (0x0c) with an empty reason. Local application details remain available through quic-application-error?, quic-application-error-code and quic-application-error-reason in (sigil quic error). Invalid application metadata raises before closing. quic-transport-close! explicitly sends a transport code:/frame-type:; its reason: remains a local diagnostic. Both paths are idempotent and retain the first failure. Either close frame may use the final reserved AEAD seal. Before confirmation, a local close is attempted at every available write level, ordered Initial, Handshake, then 1-RTT. Each copy retains its AEAD and anti-amplification checks. After confirmation, only 1-RTT is used. Traffic secrets are erased after the close copies are sealed.
Standalone connections retain owned copies of those protected packets for three current PTOs. quic-closed? stays true; quic-closing? reports the remaining closing state while quic-receive!, quic-tick! and quic-take-datagrams! advance its monotonic clock. Routed incoming packets can trigger at most one byte-exact replay per PTO, without new encryption or a deadline extension. Replays use only the pre-close receive credit and stay within its cumulative 3x send limit, even for validated peers. Replays can therefore be suppressed after asymmetric traffic. quic-abort! immediately discards cached output and retires an open connection silently. The dedicated endpoint adapter ends closing early when it releases its UDP socket, as permitted by RFC 9000 §10.2, and discards the connection's cached output. Abandoned admission candidates also lose their cache before the slot is reused.
Connections advertise a 30000 ms max_idle_timeout unless parameter 1 is explicitly supplied. The effective value is the minimum nonzero local and authenticated peer value; both zero disables expiry. The period is floored at three current PTOs (including the prototype's capped backoff). New processed authenticated packets restart it, as does only the first eliciting send since such a receipt. Corrupt/replayed packets, ACK-only output and repeated sends without a peer response do not restart it. quic-tick!, receive and output checks expire before accepting late activity. Idle expiry silently discards keys/queues and invokes close handlers; quic-idle-expired? reports this normal close with no transport failure. The endpoint discards retained output and closes its dedicated socket.
Each key is limited to 2^23 AES-GCM encryptions, including ACKs and retransmits. The connection reserves its last permitted encryption for a typed AEAD_LIMIT_REACHED close (0x0f). Invalid packets accumulate across all read keys for the lifetime of the connection, with the standard 2^52 ceiling. Constructor options aead-packet-limit: and aead-failure-limit: can lower these ceilings; they cannot raise them. Invalid packets count once even if both current and candidate read keys are tried.
Full key update is not implemented yet. Authenticated unexpected key phases close with KEY_UPDATE_ERROR (0x0e) before applying frames. A next-read candidate is precomputed with next-traffic-keys, using the QUIC quic ku label and preserving HP. Forged apparent updates are discarded unless the integrity ceiling is reached. Generic TLS traffic-update uses traffic upd and must not be used to derive QUIC updates. Candidate keys are disposed with their encryption level.
On the test machine, QUIC_ENDPOINT_RED=1 sigil test test/test-endpoint.sgl must fail exactly two controls before the full suite passes. Endpoint tests use actual loopback UDP, arbitrary binary payloads beyond the receive window, peer-port filtering, bounded admission and failure/timeout cleanup. The focused native selector scripts/native-tls-tests.mjs --endpoint-bind adds canonical address tests and Retry/stream/DATAGRAM exchanges on IPv4, IPv6 and wildcard binds. Assigned-interface cases accept QUIC_TEST_INTERFACE_IPV4 and QUIC_TEST_INTERFACE_IPV6; absent values use loopback fixtures. Run these tests on a runtime providing the shared socket APIs described above.
Receive work is bounded to eight parsed packets per datagram, including unrouted packets and authentication failures. Excess coalesced packets are dropped without closing the connection or undoing its accepted prefix. Each endpoint step handles at most 32 datagrams admitted to its connection and drains at most 96 total datagrams, so rejected source ports do not consume the connection budget and a noise flood still yields to the caller.
Server ACK-only Initial packets are unpadded; client Initial packets and ack-eliciting server Initial packets retain the 1,200-byte minimum. Until a Handshake ACK or handshake confirmation proves the server validated the client, the client probes even with no data in flight: a Handshake PING if keys exist, otherwise a padded Initial PING. Initial ACKs preserve probe backoff, and existing deadline, idle and key-use limits still apply.
To execute the same test bodies in a native binary on the test machine:
node scripts/native-tls-tests.mjs
cd build/native-tests
sigil deps install
sigil build --config native
# This control exits 1 with eleven vector failures.
QUIC_TLS_EXT_RED=1 build/native/bin/quic-native-tests
# This control exits 1 with seven authentication vector failures.
QUIC_TLS_AUTH_RED=1 build/native/bin/quic-native-tests
# This control exits 1 with four engine secret-comparison failures.
QUIC_TLS_ENGINE_RED=1 build/native/bin/quic-native-tests
# This control exits 1 with eight frame wire-comparison failures.
QUIC_FRAME_RED=1 build/native/bin/quic-native-tests
# This control exits 1 with four reassembly byte-comparison failures.
QUIC_REASSEMBLY_RED=1 build/native/bin/quic-native-tests
# This control exits 1 with eight packet/header/PN comparison failures.
QUIC_PACKET_RED=1 build/native/bin/quic-native-tests
# This control exits 1 with four packet-space/error comparison failures.
QUIC_SPACE_RED=1 build/native/bin/quic-native-tests
build/native/bin/quic-native-testsThe benchmark creates, protects, sends, receives, authenticates and parses 1,200-byte packets on UDP loopback. It uses one process pinned to one CPU, warms up, and reports three samples for the full path and three controls: build/parse, UDP without crypto, and crypto without UDP. Controls include allocation and parsing overhead and should not be treated as additive isolated component costs. Timings include both sender and receiver work. Packet numbers increase throughout each run; traffic keys are fresh per process. The outer timeout bounds blocking UDP failures.
Regenerate fixtures from RFC Editor plain texts with:
node scripts/extract-vectors.mjs rfc8448.txt rfc9001.txt
node scripts/extract-handshake-vectors.mjs rfc8448.txt