Commit565208c6Recorded25 Oct 2026Repositorysigil-quic
Introduce QUIC APIs, status and test instructions
Changed
README.md | 730 ++++++++++++-------------------------------------------------------------------------------------------------------------------------------------------------------------
docs/implementation.md | 708 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 759 insertions(+), 679 deletions(-)Diff
README.mdmodified
@@ -1,708 +1,80 @@
1
# sigil-quic 2
−3
Experimental QUIC v1 packet protection and a TLS 1.3 handshake engine in Sigil.−4
The experimental endpoint supports private numeric IPv4/IPv6 interface testing.+3
Experimental QUIC v1 for [Sigil](https://codeberg.org/sigil/sigil), including+4
packet protection, a TLS 1.3 handshake engine, bounded connection and stream+5
state, and a UDP endpoint adapter. 6
−6
`(sigil quic tls)` exports SHA-256 HKDF-Expand-Label, key-schedule−7
transitions, traffic updates, Finished MACs and the client/server handshake.−8
`(sigil quic packet)`−9
derives Initial keys, seals/opens payloads and applies/removes header−10
protection with the AES-128 single-block primitive in sigil-crypto.+7
## Status 8
−12
The package requires sigil-crypto ^0.18.1, which includes the AES block API.−13
Install released dependencies normally, without development redirects.−14
Configured UDP endpoints additionally require the shared `(sigil socket)`−15
family-aware `udp-socket` and `socket-normalize-address` APIs, introduced by−16
Sigil commit `d237e25c6d881300cf37eedbc657b2203badec0f`. That shared runtime−17
change has not been released yet: the current published runtime alone cannot−18
run the configured endpoint. The focused endpoint gate uses a runtime built−19
with that change; upstream availability is required for normal consumption.−20
RFC 9001 tests derive real AES masks and check complete client/server Initial−21
packets, sample selection, payload authentication and inverse processing.+9
Early development. Client/server handshakes, authenticated Retry, sequential+10
bidirectional streams, RFC 9221 DATAGRAM, authenticated path migration, and+11
numeric IPv4/IPv6 endpoints are implemented and covered by tests. TLS uses+12
AES-128-GCM/SHA-256, X25519, and P-256 signatures. HQ interoperability tools+13
are included. Full QUIC key update, 0-RTT, PSK authentication, and a built-in+14
X.509 trust store are not implemented. Applications must provide a certificate+15
verifier or an independently trusted public-key pin. The library needs+16
independent security review before production use. 17
−23
Build on a Linux measurement machine:+18
## Dependency 19
−25
```sh−26
sigil deps install−27
sigil build --config native−28
scripts/run-gates.sh build/native/bin/quic-probe−29
```−30
−31
The gate runs a red invocation first, changing one byte in every expected−32
vector and requiring every comparison to fail, then the original vectors.−33
It also checks rejection after changing each ciphertext/tag byte and the AAD.−34
RFC 8448 section 3 checks chain actual X25519 and transcript hashes through−35
the handshake, master, traffic, exporter and resumption secrets.−36
−37
TLS wire helpers live in `(sigil quic tls codec)`, `(sigil quic tls messages)`−38
and `(sigil quic tls signature)`. They provide bounded handshake framing,−39
duplicate-rejecting extensions, Hello codecs and P-256 CertificateVerify−40
encoding/signing. Run `sigil test` for−41
their 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−43
the four known-byte comparisons before the normal suite passes.−44
−45
`(sigil quic tls extensions)` handles ALPN, SNI, negotiation lists, key−46
shares, cookies and server extension placement. `(sigil quic wire)` provides−47
exact 62-bit varints; `(sigil quic transport parameters)` checks parameter−48
bounds, role restrictions and connection ID bindings. Transport parameters−49
become authenticated when the handshake verifies Finished.−50
`QUIC_TLS_EXT_RED=1 sigil test test/test-tls-extensions.sgl` must fail its−51
eleven known-byte comparisons before the normal suite passes.−52
−53
`(sigil quic tls authentication)` encodes and bounds authentication-flight−54
messages with opaque certificate entries. `(sigil quic tls transcript)`−55
tracks SHA-256 transcript hashes and the one-time HelloRetryRequest−56
message_hash transformation, with message-count and byte limits.−57
`QUIC_TLS_AUTH_RED=1 sigil test test/test-tls-authentication.sgl` must fail−58
seven published-byte/hash controls before the normal suite passes.−59
−60
The handshake engine supports TLS_AES_128_GCM_SHA256, X25519,−61
ecdsa_secp256r1_sha256, ALPN, optional SNI, QUIC transport parameters and one−62
HelloRetryRequest. It has no TLS records, sockets, PSK authentication, 0-RTT−63
acceptance or client identity. Unknown PSK offers are structurally validated−64
and fall back to the full X25519/certificate handshake. Retry allows updated−65
ticket ages/binders and removal of identities, while rejecting new or reordered−66
identities and a repeated early-data offer. No PSK or early-data selection is sent.−67
An optional CertificateRequest is declined with an empty Certificate. Bounded−68
NewSessionTicket messages are checked and discarded; TLS KeyUpdate is rejected.−69
−70
Extension and client key-share duplicate tracking use fixed 8 KiB bitmaps for−71
the complete uint16 identifier space. Marking each ID takes constant time;−72
the existing wire-size bounds and duplicate rejection remain in force.−73
Incoming SNI values outside the supported DNS syntax are treated as−74
unrecognized: the server continues with its configured certificate and omits−75
the SNI acknowledgement. Empty host names, duplicate name types and malformed−76
vectors still fail. Outgoing client SNI retains strict DNS-name validation;−77
the client verifier must authenticate the intended identity or pin.−78
−79
`make-tls-client` takes ALPN bytevectors, an explicit identity, local transport−80
parameters and a verifier. A DNS-name identity requires a callback that receives−81
the DER chain and requested name, validates both the chain and name, and returns−82
the authenticated leaf's raw 65-byte P-256 public key or `#f` to reject. There−83
is no built-in X.509 trust store. An unnamed `#f` identity is rejected.−84
−85
For 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−87
possession of that key through CertificateVerify and Finished. It requires−88
the library-created verifier token; arbitrary callbacks are rejected in pin−89
mode. The optional `certificate:` bytevector additionally pins the exact leaf−90
DER. The factory copies both inputs and never adopts a key from the peer's−91
certificate. Pinning authenticates the configured key; it performs no X.509−92
path, expiry or DNS-name validation. `make-quic-client` uses the same contract.−93
`make-tls-server` takes ALPN preferences, local parameters, a DER certificate−94
chain and a 32-byte P-256 private key. Each engine owns its copied signing key.−95
−96
Call `tls-bind-peer!` once with the original destination CID, peer's initial−97
source CID and Retry source CID (`#f` without QUIC Retry), taken from packet−98
headers. 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−102
before its body is accepted. Hello, EncryptedExtensions, CertificateRequest−103
and discarded tickets are limited to 16 KiB; ECDSA CertificateVerify to 76−104
bytes, Finished to exactly 32 bytes, and Certificate to 1 MiB. Input storage−105
grows only as bytes arrive, with bounded geometric slack and wiped replaced−106
prefixes. Transcript/ticket counts are bounded; completion and failure clear−107
and drop the retained transcript. `tls-retained-input-bytes` reports input−108
capacity plus retained transcript bytes, excluding secrets and outbound events.−109
−110
`tls-take-events!` drains ordered events. A `crypto` event carries its level−111
and handshake bytes. A `secrets` event carries its level and a pair of−112
read/write traffic secrets; `#f` means that direction is not installed by−113
that 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.−116
Failure permanently closes the engine, clears retained secrets and discards−117
queued events. The caller must also discard already installed packet keys.−118
The implementation still needs independent security review before public use.−119
−120
The key schedule clears its owned derived HKDF salts and Finished HMAC keys−121
on return and exception; borrowed inputs and returned results remain owned by−122
the caller. Zeroization is best-effort: these writes clear reachable mutable−123
buffers, without guaranteeing erasure of compiler, garbage-collector or−124
native-library copies. In sigil-crypto 0.18.1, internal HKDF MAC-chain and−125
accumulator buffers and native HMAC stack outputs are not exposed to this−126
library and cannot be cleared here. Cleanup requires normal return or stack−127
unwinding; process termination and failures that prevent unwinding can bypass it.−128
−129
The engine clears its private key share after deriving handshake secrets and−130
its master secret after deriving application traffic secrets. Completion or−131
abort clears copied signing keys and remaining engine-owned traffic secrets.−132
The server clears its owned server handshake-traffic secret after emitting−133
Finished; queued packet-key event copies remain owned by the caller. Its−134
client handshake-traffic secret stays live until the peer Finished verifies,−135
and clients retain their server handshake-traffic secret until authentication.−136
Handshake derivation also clears its owned shared, early and handshake-secret−137
intermediates when a later primitive throws, as well as on normal return.−138
Fresh key-share private bytes belong to the engine before public-key generation,−139
so an exception from that primitive also reaches the engine's abort cleanup.−140
Secret-event copies stay in a cleanup scope until queued; a later copy or−141
queue failure clears partial results. Drained event copies belong to the caller−142
and remain live until the caller clears them.−143
Server construction clears its copied signing key if engine creation fails.−144
QUIC construction retains ownership of its fresh TLS engine and any installed−145
Initial keys until initialization succeeds, clearing them on an exception.−146
−147
`raise-tls-alert`, `tls-alert?`, `tls-alert-code` and `tls-alert-reason`−148
preserve TLS alert metadata. Connections map these to QUIC CRYPTO_ERROR−149
0x0100 plus the alert: failed/absent ALPN is 0x0178, missing transport−150
parameters 0x016d, and TLS KeyUpdate/unexpected handshake types 0x010a.−151
QUIC transport errors keep their own codes; unclassified TLS failures retain−152
the generic handshake_failure fallback.−153
−154
`QUIC_TLS_ENGINE_RED=1 sigil test test/test-tls-handshake.sgl` must fail four−155
directional-secret controls before the normal suite passes. Engine tests−156
exercise both roles in memory, fragmented/coalesced flights, HRR, explicit−157
certificate rejection, signature/MAC corruption, CID bindings and level/order−158
failures. These tests do not replace independent QUIC interoperability checks.−159
−160
`(sigil quic frame)` provides `decode-frames payload level sender`,−161
`encode-frame frame` and `encode-frames frames level sender` for RFC 9000−162
types 0x00 through 0x1e. Construct a frame with `make-quic-frame type fields`,−163
where fields is an alist; use `quic-frame-type`, `quic-frame-fields` and−164
`frame-ref` to inspect it. ACK `ranges` are inclusive `(low . high)` pairs−165
in descending order and `delay` is the unscaled wire value. STREAM frames−166
carry `stream-id`, `offset` (zero when absent) and `data`; the numeric type−167
preserves OFF/LEN/FIN flags. `frame-fin?` and `frame-ack-eliciting?` expose−168
those common classifications. CRYPTO frames carry `offset` and `data`.−169
−170
Frame decoding checks type encoding, payload/field bounds, role/level−171
placement, ACK arithmetic, CID lengths and 62-bit end offsets. Limits are−172
65,527 payload bytes, 256 frames and 256 ACK ranges; consecutive padding is−173
represented by one frame with a `length` field. Local decode work exhaustion−174
raises an exception recognized by `frame-work-limit?`; the connection drops−175
that entire packet before applying frames, recording an ACK or refreshing−176
receive activity. The peer must retransmit its data within these budgets.−177
Invalid wire encodings still produce transport errors. Local encoders enforce−178
the same frame/range limits. Connection policy must still−179
check stream ownership/flow control, ACKs against sent packets, CID inventory−180
and path validation. `QUIC_FRAME_RED=1 sigil test test/test-frame.sgl` must−181
fail eight independent wire controls, including the two RFC 9001 payloads,−182
before the normal suite passes.−183
−184
`(sigil quic reassembly)` provides fixed-capacity byte-offset windows for−185
CRYPTO and stream delivery. `make-byte-reassembler capacity` allocates data−186
and presence rings of that size, with a 1 MiB maximum. CRYPTO callers must−187
budget at least 4096 bytes and use a separate receiver per encryption level.−188
`reassembler-insert! receiver offset bytes` returns the newly buffered byte−189
count. It checks the whole incoming range before mutation, requires buffered−190
overlaps to agree, discards already delivered prefixes and rejects data beyond−191
the moving receive window. Offsets never determine allocation size.−192
−193
`reassembler-read! receiver` returns the available contiguous prefix; an−194
optional byte limit allows partial reads. `reassembler-offset` tracks bytes−195
delivered, `reassembler-buffered` counts pending unique bytes, and−196
`reassembler-highest` records the highest accepted nonempty end offset.−197
Empty inserts leave that watermark unchanged. Returned/input data is copied;−198
`reassembler-close!` clears storage and prevents further insertion/reading.−199
`reassembly-error?` and `reassembly-error-kind` distinguish `capacity` and−200
`conflict` failures without changing state. The connection maps CRYPTO window−201
exhaustion to CRYPTO_BUFFER_EXCEEDED and conflicting buffered bytes to−202
PROTOCOL_VIOLATION. Invalid local arguments remain ordinary exceptions.−203
The connection layer must enforce stream flow control/final size and handle−204
reassembly errors. `QUIC_REASSEMBLY_RED=1 sigil test test/test-reassembly.sgl`−205
must fail four byte controls before the normal suite passes. An integration−206
test completes both TLS roles with HRR through reordered CRYPTO-frame bytes.−207
−208
`(sigil quic packet header)` parses packet boundaries with−209
`decode-packet-header datagram offset short-dcid-length` and builds unprotected−210
v1 Initial/Handshake/short headers with `encode-packet-header`. Header `start`−211
and `end` are absolute datagram offsets; `pn-offset` is relative to `start`.−212
Short headers consume the remaining datagram. Parsing caps datagrams at−213
65,527 bytes, v1 CIDs at 20 bytes and VN version lists at 256 entries. VN,−214
Retry and unsupported versions are recognized separately. Retry integrity helpers−215
are available in `(sigil quic packet retry)` and re-exported by the packet façade:−216
`encode-retry-packet original-id destination-id source-id token` and−217
`valid-retry-packet? original-id wire`. The encoder accepts `unused:` from 0 to 15;−218
the validator drops malformed peer packets. Both bound CIDs and datagram size.−219
The standardized public integrity tag does not authenticate a server or validate−220
an address. Private token admission, version negotiation and connection-ID policy−221
remain separate from this packet helper; the private loopback endpoint has an−222
opt-in Retry admission path described below.−223
−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;−227
an optional `key:` is copied for explicit shared-server key management.−228
`lifetime:` defaults to 10,000 ms and is bounded to 1–60,000 ms. Close each−229
manager explicitly when retiring its key; tokens from other keys stop validating.−230
−231
`make-retry-token manager address original-id retry-id client-id now` authenticates−232
a Retry-only version, issuance time, random nonce and original destination CID−233
with HMAC-SHA256. Canonical address bytes (1–64 bytes, including IP and port),−234
Retry source CID and client source CID are length-delimited authenticated context.−235
The token contains no address bytes and is not encrypted. It is not a NEW_TOKEN−236
format. The original CID already appears in the same handshake's first Initial.−237
`validate-retry-token manager address retry-id client-id token now` returns an−238
owned original CID or `#f` for malformed, forged, future or expired tokens.−239
Times must use the same monotonic millisecond clock; expiry is exclusive.−240
Replay is limited to the bound address/CIDs and validity window. Local argument−241
errors and use after close raise. Operational crypto errors retire the key and−242
raise. Endpoint token admission is not integrated yet; no listener uses this API.−243
−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.−247
Kinds are `initial`, `handshake` and `application`. It pads tiny payloads−248
enough for a confined header-protection sample. The caller must separately−249
ensure the 1200-byte Initial datagram minimum and peer/MTU limits.−250
−251
`protect-payload` and `seal-quic-packet` are stateless cryptographic primitives.−252
The caller owns packet-number commitments and AEAD usage accounting for each−253
directional AES key/IV. That state covers both entry points and every copy of−254
the same key material: copying a key vector preserves its nonce space. Commit−255
a fresh PN for each encryption attempt. If encryption might have used it,−256
retire that PN even when a later allocation or header-protection step raises;−257
retry with a fresh PN, or retire the key when commitment state is uncertain.−258
`(sigil quic connection)` manages these commitments, usage ceilings and failure−259
cleanup for normal connection traffic.−260
−261
`open-quic-packet datagram offset short-dcid-length material largest`−262
reconstructs the PN (`largest = -1` for an empty space) and authenticates one−263
packet. Successful results expose its header, number, payload, key phase and−264
spin through `opened-quic-packet-*` accessors. The input remains unchanged.−265
−266
AEAD failure returns `#f`; unauthenticated framing/PN errors throw and require−267
packet discard. Nonzero reserved bits are checked only after authentication−268
and require a connection-level PROTOCOL_VIOLATION. HP sampling is restricted−269
to the packet's own boundary even in coalesced datagrams. `traffic-keys`−270
derives owned QUIC key material from a 32-byte traffic secret using the same−271
vector layout as `initial-keys`; `discard-packet-keys!` clears and disables it.−272
The connection layer owns receive PN tracking, duplicate detection, packet-key−273
lifetimes and key-phase transitions. `QUIC_PACKET_RED=1 sigil test−274
test/test-packet.sgl` must fail eight RFC 9000/9001 controls before the normal−275
suite passes.−276
−277
Connections clear their private traffic-secret copies after deriving packet−278
keys, including the application read-key candidate used to authenticate an−279
unsupported update. AES, IV and HP bytes remain live until their packet space−280
is discarded. This preserves the low-level packet factories' caller-owned−281
traffic-secret component and `next-traffic-keys` API. Actual key-update support−282
will require retaining the appropriate update secret again.−283
Packet factories clear their private Initial extraction/side intermediates and−284
discard partial key material if a later derivation throws. Borrowed inputs and−285
complete returned vectors keep their caller's ownership.−286
−287
Authenticated PATH_CHALLENGE frames receive matching PATH_RESPONSE frames,−288
independently of an application handler. Address-bound connections route each−289
response to the challenge's source. Responses precede application backlog,−290
expire while blocked and are not retransmitted on PTO. Independent candidate−291
and previous-path validation uses fresh, paced probes and separate three-times−292
received-byte budgets. Promotion requires reachability and a 1200-byte MTU−293
check. The UDP endpoint below supplies this address-bound adapter on numeric interfaces.−294
−295
Zero-length CID policy is enforced after packet authentication and before any−296
application handler: NEW_CONNECTION_ID is forbidden when sending a zero-length−297
destination CID, and RETIRE_CONNECTION_ID is forbidden after issuing a−298
zero-length local CID. Both close with PROTOCOL_VIOLATION and the offending−299
frame type. RETIRE_CONNECTION_ID above the largest issued sequence also closes−300
with PROTOCOL_VIOLATION. A server's preferred-address CID has sequence 1; other−301
caller-issued NEW_CONNECTION_ID sequences count only after packet emission,−302
including PTO retransmission, rather than queue admission. Address-bound−303
connections own spare-ID issuance and path assignment: reservations become−304
routable only after emission, retired aliases stop routing immediately, and−305
RETIRE_CONNECTION_ID remains pending until its carrying packet is acknowledged.−306
These pools enforce the negotiated active limit and bounded lifetime inventory.−307
−308
`(sigil quic connection space)` provides bounded PN/ACK bookkeeping for−309
each encryption level. `make-packet-space level` accepts `range-limit:`,−310
`pending-limit:` and `byte-limit:` budgets (defaults 64, 128 and 262144).−311
`packet-space-received-status` classifies a PN as `new`, `duplicate` or `old`;−312
apply a new packet's frames before recording it with `packet-space-receive!`.−313
Received intervals merge, and retiring old intervals advances a replay floor.−314
ACK-only packets enter history without requesting another ACK.−315
`packet-space-take-ack!` drains an immediate zero-delay ACK when needed.+20
Add this entry to your `package.sgl` dependencies, then run `sigil deps install`: 21
−317
Check `packet-space-can-send?` before sealing `packet-space-next`; then commit−318
that exact PN through `packet-space-record-sent!` with its size, monotonic−319
millisecond timestamp and ACK-eliciting flag. Failed admission after sealing−320
requires discarding the packet and closing; reuse must never encrypt different−321
data at that PN. `packet-space-ack!` rejects ACKs of unsent numbers and releases−322
matching in-flight metadata/credit. `packet-space-retire!` frees loss metadata−323
without resetting the PN, and `packet-space-discard!` permanently closes the−324
space. This bookkeeping does not implement congestion control, loss timers−325
or frame retransmission; those belong to the connection.−326
−327
`(sigil quic error)` attaches transport code/frame metadata to standard Sigil−328
error objects via `raise-quic-error`; inspect with `quic-error?` and its−329
code/frame-type/reason accessors. Authenticated reserved bits, forbidden frame−330
placement and ACKs of unsent packets retain PROTOCOL_VIOLATION metadata.−331
An empty payload raises typed PROTOCOL_VIOLATION; it is not a frame encoding−332
error. Generic frame parse exceptions still require FRAME_ENCODING_ERROR mapping−333
after packet authentication in the connection. `QUIC_SPACE_RED=1 sigil test−334
test/test-connection-space.sgl` must fail four controls before the normal suite−335
passes.−336
−337
`(sigil quic connection)` integrates TLS with protected datagrams without−338
opening a socket. Construct a client/server with explicit ALPN, parameters,−339
certificate policy and CIDs; the connection supplies its CID transport−340
parameters. Start clients with `quic-start! connection now`, feed datagrams−341
with `quic-receive! connection bytes now`, call `quic-tick! connection now`−342
and immediately send the ordered list from `quic-take-datagrams! connection now`.−343
Times are monotonic exact milliseconds. The UDP endpoint binds the original−344
peer address before starting or receiving the handshake.−345
−346
A transport adapter can instead call `quic-bind-peer-address! connection bytes`−347
once before starting or receiving the handshake. The adapter supplies canonical−348
IP-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−350
with `quic-take-addressed-datagrams! connection now`. Each output has copied−351
bytes, destination address and destination CID through `quic-output-bytes`,−352
`quic-output-address` and `quic-output-id`. Check `quic-output-valid? connection−353
output` immediately before sending retained output: path promotion, CID−354
retirement or closure can invalidate a previously queued datagram. Raw datagram−355
output is unavailable after binding an address.−356
−357
`quic-peer-address` returns the current validated destination. Drain up to sixteen−358
retained 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−360
symbol. A changed-path event does not authorize sending application data there.−361
Only authenticated, replay-checked, handler-ready packets earn path credit;−362
clients discard unknown server sources. Server migration uses validated paths−363
and separate peer CIDs, requeues reliable flight under fresh packet numbers and−364
resets congestion accounting. DATAGRAM payloads are never retransmitted.−365
−366
After validating a Retry token, the caller can pass `retry-source-id:` to−367
`make-quic-server`. The original positional destination ID remains the first−368
client DCID; the keyword is the server's distinct Retry source CID. The server−369
derives Initial keys from the Retry CID and supplies both original and Retry−370
CID transport parameters. Retransmitted Initials route to the Retry or server−371
local CID. All supplied IDs are copied. This metadata does not validate an−372
address by itself: the caller owns token validation, and the constructor retains−373
the conservative amplification bound until authenticated Handshake traffic.−374
−375
The connection pads Initial datagrams to 1200 bytes, limits unvalidated server−376
output to three times received bytes, bounds deferred packets/CRYPTO/queues,−377
tracks directional keys and PN spaces, and confirms with HANDSHAKE_DONE.−378
It uses immediate ACKs, a conservative send window, bounded fixed-base PTO−379
backoff and fresh-PN frame retransmission, rather than full RFC 9002 recovery.−380
RFC 9221 DATAGRAM payloads are excluded from retransmission; their loss timer−381
uses a PING probe while retaining ordinary congestion and ACK bookkeeping.−382
Handshake timeout defaults to 10 seconds. A client accepts one valid routed Retry−383
after sending its first Initial and before processing a server Initial. It keeps−384
the original ClientHello, client source CID and packet-number progression, changes−385
Initial keys and destination CID, and includes the copied token on retransmissions.−386
Retry tokens over 1024 bytes are dropped; the retained first ClientHello is capped−387
at 64 KiB. CRYPTO fragmentation accounts for the token within 1200-byte Initials.−388
Retry does not restart the handshake deadline. The first accepted server Initial−389
binds the original, server Initial and Retry source IDs to the TLS transport checks.−390
VN, key updates, migration and connection-ID rotation−391
are not implemented. Stream ownership/flow control and−392
path/CID policy still belong to the layers above this primitive. No public−393
listener is provided, and independent security review is still required.−394
−395
Require `quic-complete?` for authenticated application delivery;−396
`quic-confirmed?` reports handshake confirmation. Attach an application-frame−397
handler with `quic-set-frame-handler!` and queue application frames with−398
`quic-send-frame!`. Before attachment, authenticated packets containing STREAM,−399
RESET_STREAM, STOP_SENDING or application flow-control frames are dropped whole,−400
without applying a prefix, recording their PN, acknowledging them or refreshing−401
idle activity. The peer can retransmit after attachment; no additional input−402
buffer is retained. Transport-only packets still drive handshake confirmation,−403
ACKs, path responses, CID validation and close without an application handler.−404
A frame exceeding the connection's 1,200-byte packet budget−405
(including its header and tag) raises synchronously before queue mutation;−406
previously queued work and the connection remain usable. On `quic-closed?`,−407
drain final close output and close the dedicated endpoint socket.−408
`quic-failure` exposes local failure or the peer's−409
close frame. Closure erases traffic keys, pending data and TLS secrets;−410
`tls-abort!` provides the same idempotent TLS cleanup to standalone callers.−411
−412
To 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−415
Length field and payload. Omission or zero disables receiving; receiving an−416
unsupported or oversized frame closes with PROTOCOL_VIOLATION. Received limits−417
use the actual wire size, including nonminimal Length-varint encodings.−418
−419
`quic-send-datagram! connection bytes` requires a complete authenticated−420
handshake and a nonzero peer advertisement. It copies one whole message,−421
queues a length-bearing frame (`0x31`) and returns `#t`; use `length?: #f` for−422
the lengthless `0x30` form. Invalid inputs and peer or 1,200-byte packet size−423
excess raise before queue mutation. No fragmentation is performed. A full−424
send queue returns `#f`: at most `quic-datagram-queue-limit` (32) DATAGRAM−425
messages may wait alongside the existing bounded frame queue. A full queue−426
does not overwrite earlier messages. Sending through `quic-send-frame!` also−427
enforces negotiation, size and count limits, but raises on queue refusal.−428
−429
`quic-read-datagram! connection` returns the oldest received message, or `#f`−430
when none is available, the handshake is incomplete, or the connection is−431
closed. An empty bytevector is a valid message. Receive dispatch is independent−432
of the stream-frame handler. It retains at most 32 messages and−433
`quic-datagram-byte-limit` (65,536) payload bytes; new arrivals beyond either−434
budget are dropped while normal packet ACK processing continues. Reads release−435
credit, and connection closure clears queued messages. DATAGRAM messages are−436
unreliable, do not consume STREAM flow-control credit and are never retransmitted.−437
Applications supply any flow identifiers inside their payloads.−438
−439
DATAGRAM codec/transport tests are in `test/test-datagram-codec.sgl`; protected−440
connection tests in `test/test-datagram.sgl` use a standalone TLS peer that owns−441
its keys. On a remote test machine, `node scripts/native-tls-tests.mjs --datagram`−442
selects both files for the native test package described above. They are also−443
included in the default bytecode and generated native suites.−444
−445
Server Initial packets carrying a token are discarded before CID pinning,−446
authentication, receive credit or closing replay. During the handshake, other−447
coalesced packets remain eligible for processing. ClientHello must have an−448
empty legacy session ID; the server reports PROTOCOL_VIOLATION for a nonempty−449
ID (RFC 9001 §8.4).−450
−451
Client receive tolerates authenticated server Initials in short datagrams.−452
Our send path still pads ack-eliciting server Initials and all client Initials;−453
servers still discard client Initials in datagrams under 1,200 bytes.−454
Well-formed NewSessionTickets are discarded regardless of lifetime without−455
retiring completed TLS. Ticket parsing and the 64-message work limit still apply.−456
The ticket's optional `early_data` extension must contain the four-byte QUIC−457
sentinel `0xffffffff`; another value closes with PROTOCOL_VIOLATION, while a−458
malformed extension length produces TLS decode_error. No ticket enables 0-RTT.−459
−460
`QUIC_CONNECTION_RED=1 sigil test test/test-connection.sgl` must fail two−461
completion controls. `QUIC_HP_SABOTAGE=1 sigil test test/test-connection.sgl`−462
must fail only the dedicated positive handshake completion assertion: one−463
protected PN byte is corrupted on every client Initial transmission and retry.−464
A single transient corrupt datagram is recoverable and has a separate loss test.−465
−466
`(sigil quic stream)` provides one client-initiated bidirectional stream (ID 0).−467
Use `stream-transport-parameters role receive-window: size` when constructing−468
the connection, then attach `make-quic-stream connection` before starting or−469
receiving packets. It validates its fixed allocation against the advertised−470
stream/connection limits and owns the connection's application-frame handler.−471
The default receive window is 65536 bytes, with a 1 MiB maximum.−472
−473
After authentication, `quic-stream-write! stream bytes fin?: boolean` accepts−474
up to 900 bytes and returns the accepted count; retry the remainder after−475
pumping datagrams and credit. A zero-byte FIN can return zero successfully;−476
`quic-stream-send-closed?` distinguishes it from a blocked write.−477
`quic-stream-read! stream maximum: count` returns copied ordered bytes and−478
advertises additional absolute credit as storage is freed. Empty reads can−479
mean 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.−482
STOP_SENDING cancels queued/in-flight STREAM retransmissions before RESET;−483
FIN/RESET final sizes, credit, stream ownership and limits remain checked.−484
Connection closure clears the stream's receive storage.−485
Showing the first 500 of 760 diff lines for this file. This diff is INCOMPLETE; read the file or clone the repository for the rest.
docs/implementation.mdadded
@@ -0,0 +1,708 @@
+1
# sigil-quic+2
+3
Experimental QUIC v1 packet protection and a TLS 1.3 handshake engine in Sigil.+4
The experimental endpoint supports private numeric IPv4/IPv6 interface testing.+5
+6
`(sigil quic tls)` exports SHA-256 HKDF-Expand-Label, key-schedule+7
transitions, traffic updates, Finished MACs and the client/server handshake.+8
`(sigil quic packet)`+9
derives Initial keys, seals/opens payloads and applies/removes header+10
protection with the AES-128 single-block primitive in sigil-crypto.+11
+12
The package requires sigil-crypto ^0.18.1, which includes the AES block API.+13
Install released dependencies normally, without development redirects.+14
Configured UDP endpoints additionally require the shared `(sigil socket)`+15
family-aware `udp-socket` and `socket-normalize-address` APIs, introduced by+16
Sigil commit `d237e25c6d881300cf37eedbc657b2203badec0f`. That shared runtime+17
change has not been released yet: the current published runtime alone cannot+18
run the configured endpoint. The focused endpoint gate uses a runtime built+19
with that change; upstream availability is required for normal consumption.+20
RFC 9001 tests derive real AES masks and check complete client/server Initial+21
packets, sample selection, payload authentication and inverse processing.+22
+23
Build on a Linux measurement machine:+24
+25
```sh+26
sigil deps install+27
sigil build --config native+28
scripts/run-gates.sh build/native/bin/quic-probe+29
```+30
+31
The gate runs a red invocation first, changing one byte in every expected+32
vector and requiring every comparison to fail, then the original vectors.+33
It also checks rejection after changing each ciphertext/tag byte and the AAD.+34
RFC 8448 section 3 checks chain actual X25519 and transcript hashes through+35
the handshake, master, traffic, exporter and resumption secrets.+36
+37
TLS wire helpers live in `(sigil quic tls codec)`, `(sigil quic tls messages)`+38
and `(sigil quic tls signature)`. They provide bounded handshake framing,+39
duplicate-rejecting extensions, Hello codecs and P-256 CertificateVerify+40
encoding/signing. Run `sigil test` for+41
their 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+43
the four known-byte comparisons before the normal suite passes.+44
+45
`(sigil quic tls extensions)` handles ALPN, SNI, negotiation lists, key+46
shares, cookies and server extension placement. `(sigil quic wire)` provides+47
exact 62-bit varints; `(sigil quic transport parameters)` checks parameter+48
bounds, role restrictions and connection ID bindings. Transport parameters+49
become authenticated when the handshake verifies Finished.+50
`QUIC_TLS_EXT_RED=1 sigil test test/test-tls-extensions.sgl` must fail its+51
eleven known-byte comparisons before the normal suite passes.+52
+53
`(sigil quic tls authentication)` encodes and bounds authentication-flight+54
messages with opaque certificate entries. `(sigil quic tls transcript)`+55
tracks SHA-256 transcript hashes and the one-time HelloRetryRequest+56
message_hash transformation, with message-count and byte limits.+57
`QUIC_TLS_AUTH_RED=1 sigil test test/test-tls-authentication.sgl` must fail+58
seven published-byte/hash controls before the normal suite passes.+59
+60
The handshake engine supports TLS_AES_128_GCM_SHA256, X25519,+61
ecdsa_secp256r1_sha256, ALPN, optional SNI, QUIC transport parameters and one+62
HelloRetryRequest. It has no TLS records, sockets, PSK authentication, 0-RTT+63
acceptance or client identity. Unknown PSK offers are structurally validated+64
and fall back to the full X25519/certificate handshake. Retry allows updated+65
ticket ages/binders and removal of identities, while rejecting new or reordered+66
identities and a repeated early-data offer. No PSK or early-data selection is sent.+67
An optional CertificateRequest is declined with an empty Certificate. Bounded+68
NewSessionTicket messages are checked and discarded; TLS KeyUpdate is rejected.+69
+70
Extension and client key-share duplicate tracking use fixed 8 KiB bitmaps for+71
the complete uint16 identifier space. Marking each ID takes constant time;+72
the existing wire-size bounds and duplicate rejection remain in force.+73
Incoming SNI values outside the supported DNS syntax are treated as+74
unrecognized: the server continues with its configured certificate and omits+75
the SNI acknowledgement. Empty host names, duplicate name types and malformed+76
vectors still fail. Outgoing client SNI retains strict DNS-name validation;+77
the client verifier must authenticate the intended identity or pin.+78
+79
`make-tls-client` takes ALPN bytevectors, an explicit identity, local transport+80
parameters and a verifier. A DNS-name identity requires a callback that receives+81
the DER chain and requested name, validates both the chain and name, and returns+82
the authenticated leaf's raw 65-byte P-256 public key or `#f` to reject. There+83
is no built-in X.509 trust store. An unnamed `#f` identity is rejected.+84
+85
For 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+87
possession of that key through CertificateVerify and Finished. It requires+88
the library-created verifier token; arbitrary callbacks are rejected in pin+89
mode. The optional `certificate:` bytevector additionally pins the exact leaf+90
DER. The factory copies both inputs and never adopts a key from the peer's+91
certificate. Pinning authenticates the configured key; it performs no X.509+92
path, expiry or DNS-name validation. `make-quic-client` uses the same contract.+93
`make-tls-server` takes ALPN preferences, local parameters, a DER certificate+94
chain and a 32-byte P-256 private key. Each engine owns its copied signing key.+95
+96
Call `tls-bind-peer!` once with the original destination CID, peer's initial+97
source CID and Retry source CID (`#f` without QUIC Retry), taken from packet+98
headers. 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+102
before its body is accepted. Hello, EncryptedExtensions, CertificateRequest+103
and discarded tickets are limited to 16 KiB; ECDSA CertificateVerify to 76+104
bytes, Finished to exactly 32 bytes, and Certificate to 1 MiB. Input storage+105
grows only as bytes arrive, with bounded geometric slack and wiped replaced+106
prefixes. Transcript/ticket counts are bounded; completion and failure clear+107
and drop the retained transcript. `tls-retained-input-bytes` reports input+108
capacity plus retained transcript bytes, excluding secrets and outbound events.+109
+110
`tls-take-events!` drains ordered events. A `crypto` event carries its level+111
and handshake bytes. A `secrets` event carries its level and a pair of+112
read/write traffic secrets; `#f` means that direction is not installed by+113
that 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.+116
Failure permanently closes the engine, clears retained secrets and discards+117
queued events. The caller must also discard already installed packet keys.+118
The implementation still needs independent security review before public use.+119
+120
The key schedule clears its owned derived HKDF salts and Finished HMAC keys+121
on return and exception; borrowed inputs and returned results remain owned by+122
the caller. Zeroization is best-effort: these writes clear reachable mutable+123
buffers, without guaranteeing erasure of compiler, garbage-collector or+124
native-library copies. In sigil-crypto 0.18.1, internal HKDF MAC-chain and+125
accumulator buffers and native HMAC stack outputs are not exposed to this+126
library and cannot be cleared here. Cleanup requires normal return or stack+127
unwinding; process termination and failures that prevent unwinding can bypass it.+128
+129
The engine clears its private key share after deriving handshake secrets and+130
its master secret after deriving application traffic secrets. Completion or+131
abort clears copied signing keys and remaining engine-owned traffic secrets.+132
The server clears its owned server handshake-traffic secret after emitting+133
Finished; queued packet-key event copies remain owned by the caller. Its+134
client handshake-traffic secret stays live until the peer Finished verifies,+135
and clients retain their server handshake-traffic secret until authentication.+136
Handshake derivation also clears its owned shared, early and handshake-secret+137
intermediates when a later primitive throws, as well as on normal return.+138
Fresh key-share private bytes belong to the engine before public-key generation,+139
so an exception from that primitive also reaches the engine's abort cleanup.+140
Secret-event copies stay in a cleanup scope until queued; a later copy or+141
queue failure clears partial results. Drained event copies belong to the caller+142
and remain live until the caller clears them.+143
Server construction clears its copied signing key if engine creation fails.+144
QUIC construction retains ownership of its fresh TLS engine and any installed+145
Initial keys until initialization succeeds, clearing them on an exception.+146
+147
`raise-tls-alert`, `tls-alert?`, `tls-alert-code` and `tls-alert-reason`+148
preserve TLS alert metadata. Connections map these to QUIC CRYPTO_ERROR+149
0x0100 plus the alert: failed/absent ALPN is 0x0178, missing transport+150
parameters 0x016d, and TLS KeyUpdate/unexpected handshake types 0x010a.+151
QUIC transport errors keep their own codes; unclassified TLS failures retain+152
the generic handshake_failure fallback.+153
+154
`QUIC_TLS_ENGINE_RED=1 sigil test test/test-tls-handshake.sgl` must fail four+155
directional-secret controls before the normal suite passes. Engine tests+156
exercise both roles in memory, fragmented/coalesced flights, HRR, explicit+157
certificate rejection, signature/MAC corruption, CID bindings and level/order+158
failures. These tests do not replace independent QUIC interoperability checks.+159
+160
`(sigil quic frame)` provides `decode-frames payload level sender`,+161
`encode-frame frame` and `encode-frames frames level sender` for RFC 9000+162
types 0x00 through 0x1e. Construct a frame with `make-quic-frame type fields`,+163
where fields is an alist; use `quic-frame-type`, `quic-frame-fields` and+164
`frame-ref` to inspect it. ACK `ranges` are inclusive `(low . high)` pairs+165
in descending order and `delay` is the unscaled wire value. STREAM frames+166
carry `stream-id`, `offset` (zero when absent) and `data`; the numeric type+167
preserves OFF/LEN/FIN flags. `frame-fin?` and `frame-ack-eliciting?` expose+168
those common classifications. CRYPTO frames carry `offset` and `data`.+169
+170
Frame decoding checks type encoding, payload/field bounds, role/level+171
placement, ACK arithmetic, CID lengths and 62-bit end offsets. Limits are+172
65,527 payload bytes, 256 frames and 256 ACK ranges; consecutive padding is+173
represented by one frame with a `length` field. Local decode work exhaustion+174
raises an exception recognized by `frame-work-limit?`; the connection drops+175
that entire packet before applying frames, recording an ACK or refreshing+176
receive activity. The peer must retransmit its data within these budgets.+177
Invalid wire encodings still produce transport errors. Local encoders enforce+178
the same frame/range limits. Connection policy must still+179
check stream ownership/flow control, ACKs against sent packets, CID inventory+180
and path validation. `QUIC_FRAME_RED=1 sigil test test/test-frame.sgl` must+181
fail eight independent wire controls, including the two RFC 9001 payloads,+182
before the normal suite passes.+183
+184
`(sigil quic reassembly)` provides fixed-capacity byte-offset windows for+185
CRYPTO and stream delivery. `make-byte-reassembler capacity` allocates data+186
and presence rings of that size, with a 1 MiB maximum. CRYPTO callers must+187
budget at least 4096 bytes and use a separate receiver per encryption level.+188
`reassembler-insert! receiver offset bytes` returns the newly buffered byte+189
count. It checks the whole incoming range before mutation, requires buffered+190
overlaps to agree, discards already delivered prefixes and rejects data beyond+191
the moving receive window. Offsets never determine allocation size.+192
+193
`reassembler-read! receiver` returns the available contiguous prefix; an+194
optional byte limit allows partial reads. `reassembler-offset` tracks bytes+195
delivered, `reassembler-buffered` counts pending unique bytes, and+196
`reassembler-highest` records the highest accepted nonempty end offset.+197
Empty inserts leave that watermark unchanged. Returned/input data is copied;+198
`reassembler-close!` clears storage and prevents further insertion/reading.+199
`reassembly-error?` and `reassembly-error-kind` distinguish `capacity` and+200
`conflict` failures without changing state. The connection maps CRYPTO window+201
exhaustion to CRYPTO_BUFFER_EXCEEDED and conflicting buffered bytes to+202
PROTOCOL_VIOLATION. Invalid local arguments remain ordinary exceptions.+203
The connection layer must enforce stream flow control/final size and handle+204
reassembly errors. `QUIC_REASSEMBLY_RED=1 sigil test test/test-reassembly.sgl`+205
must fail four byte controls before the normal suite passes. An integration+206
test completes both TLS roles with HRR through reordered CRYPTO-frame bytes.+207
+208
`(sigil quic packet header)` parses packet boundaries with+209
`decode-packet-header datagram offset short-dcid-length` and builds unprotected+210
v1 Initial/Handshake/short headers with `encode-packet-header`. Header `start`+211
and `end` are absolute datagram offsets; `pn-offset` is relative to `start`.+212
Short headers consume the remaining datagram. Parsing caps datagrams at+213
65,527 bytes, v1 CIDs at 20 bytes and VN version lists at 256 entries. VN,+214
Retry and unsupported versions are recognized separately. Retry integrity helpers+215
are available in `(sigil quic packet retry)` and re-exported by the packet façade:+216
`encode-retry-packet original-id destination-id source-id token` and+217
`valid-retry-packet? original-id wire`. The encoder accepts `unused:` from 0 to 15;+218
the validator drops malformed peer packets. Both bound CIDs and datagram size.+219
The standardized public integrity tag does not authenticate a server or validate+220
an address. Private token admission, version negotiation and connection-ID policy+221
remain separate from this packet helper; the private loopback endpoint has an+222
opt-in Retry admission path described below.+223
+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;+227
an optional `key:` is copied for explicit shared-server key management.+228
`lifetime:` defaults to 10,000 ms and is bounded to 1–60,000 ms. Close each+229
manager explicitly when retiring its key; tokens from other keys stop validating.+230
+231
`make-retry-token manager address original-id retry-id client-id now` authenticates+232
a Retry-only version, issuance time, random nonce and original destination CID+233
with HMAC-SHA256. Canonical address bytes (1–64 bytes, including IP and port),+234
Retry source CID and client source CID are length-delimited authenticated context.+235
The token contains no address bytes and is not encrypted. It is not a NEW_TOKEN+236
format. The original CID already appears in the same handshake's first Initial.+237
`validate-retry-token manager address retry-id client-id token now` returns an+238
owned original CID or `#f` for malformed, forged, future or expired tokens.+239
Times must use the same monotonic millisecond clock; expiry is exclusive.+240
Replay is limited to the bound address/CIDs and validity window. Local argument+241
errors and use after close raise. Operational crypto errors retire the key and+242
raise. Endpoint token admission is not integrated yet; no listener uses this API.+243
+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.+247
Kinds are `initial`, `handshake` and `application`. It pads tiny payloads+248
enough for a confined header-protection sample. The caller must separately+249
ensure the 1200-byte Initial datagram minimum and peer/MTU limits.+250
+251
`protect-payload` and `seal-quic-packet` are stateless cryptographic primitives.+252
The caller owns packet-number commitments and AEAD usage accounting for each+253
directional AES key/IV. That state covers both entry points and every copy of+254
the same key material: copying a key vector preserves its nonce space. Commit+255
a fresh PN for each encryption attempt. If encryption might have used it,+256
retire that PN even when a later allocation or header-protection step raises;+257
retry with a fresh PN, or retire the key when commitment state is uncertain.+258
`(sigil quic connection)` manages these commitments, usage ceilings and failure+259
cleanup for normal connection traffic.+260
+261
`open-quic-packet datagram offset short-dcid-length material largest`+262
reconstructs the PN (`largest = -1` for an empty space) and authenticates one+263
packet. Successful results expose its header, number, payload, key phase and+264
spin through `opened-quic-packet-*` accessors. The input remains unchanged.+265
+266
AEAD failure returns `#f`; unauthenticated framing/PN errors throw and require+267
packet discard. Nonzero reserved bits are checked only after authentication+268
and require a connection-level PROTOCOL_VIOLATION. HP sampling is restricted+269
to the packet's own boundary even in coalesced datagrams. `traffic-keys`+270
derives owned QUIC key material from a 32-byte traffic secret using the same+271
vector layout as `initial-keys`; `discard-packet-keys!` clears and disables it.+272
The connection layer owns receive PN tracking, duplicate detection, packet-key+273
lifetimes and key-phase transitions. `QUIC_PACKET_RED=1 sigil test+274
test/test-packet.sgl` must fail eight RFC 9000/9001 controls before the normal+275
suite passes.+276
+277
Connections clear their private traffic-secret copies after deriving packet+278
keys, including the application read-key candidate used to authenticate an+279
unsupported update. AES, IV and HP bytes remain live until their packet space+280
is discarded. This preserves the low-level packet factories' caller-owned+281
traffic-secret component and `next-traffic-keys` API. Actual key-update support+282
will require retaining the appropriate update secret again.+283
Packet factories clear their private Initial extraction/side intermediates and+284
discard partial key material if a later derivation throws. Borrowed inputs and+285
complete returned vectors keep their caller's ownership.+286
+287
Authenticated PATH_CHALLENGE frames receive matching PATH_RESPONSE frames,+288
independently of an application handler. Address-bound connections route each+289
response to the challenge's source. Responses precede application backlog,+290
expire while blocked and are not retransmitted on PTO. Independent candidate+291
and previous-path validation uses fresh, paced probes and separate three-times+292
received-byte budgets. Promotion requires reachability and a 1200-byte MTU+293
check. The UDP endpoint below supplies this address-bound adapter on numeric interfaces.+294
+295
Zero-length CID policy is enforced after packet authentication and before any+296
application handler: NEW_CONNECTION_ID is forbidden when sending a zero-length+297
destination CID, and RETIRE_CONNECTION_ID is forbidden after issuing a+298
zero-length local CID. Both close with PROTOCOL_VIOLATION and the offending+299
frame type. RETIRE_CONNECTION_ID above the largest issued sequence also closes+300
with PROTOCOL_VIOLATION. A server's preferred-address CID has sequence 1; other+301
caller-issued NEW_CONNECTION_ID sequences count only after packet emission,+302
including PTO retransmission, rather than queue admission. Address-bound+303
connections own spare-ID issuance and path assignment: reservations become+304
routable only after emission, retired aliases stop routing immediately, and+305
RETIRE_CONNECTION_ID remains pending until its carrying packet is acknowledged.+306
These pools enforce the negotiated active limit and bounded lifetime inventory.+307
+308
`(sigil quic connection space)` provides bounded PN/ACK bookkeeping for+309
each encryption level. `make-packet-space level` accepts `range-limit:`,+310
`pending-limit:` and `byte-limit:` budgets (defaults 64, 128 and 262144).+311
`packet-space-received-status` classifies a PN as `new`, `duplicate` or `old`;+312
apply a new packet's frames before recording it with `packet-space-receive!`.+313
Received intervals merge, and retiring old intervals advances a replay floor.+314
ACK-only packets enter history without requesting another ACK.+315
`packet-space-take-ack!` drains an immediate zero-delay ACK when needed.+316
+317
Check `packet-space-can-send?` before sealing `packet-space-next`; then commit+318
that exact PN through `packet-space-record-sent!` with its size, monotonic+319
millisecond timestamp and ACK-eliciting flag. Failed admission after sealing+320
requires discarding the packet and closing; reuse must never encrypt different+321
data at that PN. `packet-space-ack!` rejects ACKs of unsent numbers and releases+322
matching in-flight metadata/credit. `packet-space-retire!` frees loss metadata+323
without resetting the PN, and `packet-space-discard!` permanently closes the+324
space. This bookkeeping does not implement congestion control, loss timers+325
or frame retransmission; those belong to the connection.+326
+327
`(sigil quic error)` attaches transport code/frame metadata to standard Sigil+328
error objects via `raise-quic-error`; inspect with `quic-error?` and its+329
code/frame-type/reason accessors. Authenticated reserved bits, forbidden frame+330
placement and ACKs of unsent packets retain PROTOCOL_VIOLATION metadata.+331
An empty payload raises typed PROTOCOL_VIOLATION; it is not a frame encoding+332
error. Generic frame parse exceptions still require FRAME_ENCODING_ERROR mapping+333
after packet authentication in the connection. `QUIC_SPACE_RED=1 sigil test+334
test/test-connection-space.sgl` must fail four controls before the normal suite+335
passes.+336
+337
`(sigil quic connection)` integrates TLS with protected datagrams without+338
opening a socket. Construct a client/server with explicit ALPN, parameters,+339
certificate policy and CIDs; the connection supplies its CID transport+340
parameters. Start clients with `quic-start! connection now`, feed datagrams+341
with `quic-receive! connection bytes now`, call `quic-tick! connection now`+342
and immediately send the ordered list from `quic-take-datagrams! connection now`.+343
Times are monotonic exact milliseconds. The UDP endpoint binds the original+344
peer address before starting or receiving the handshake.+345
+346
A transport adapter can instead call `quic-bind-peer-address! connection bytes`+347
once before starting or receiving the handshake. The adapter supplies canonical+348
IP-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+350
with `quic-take-addressed-datagrams! connection now`. Each output has copied+351
bytes, destination address and destination CID through `quic-output-bytes`,+352
`quic-output-address` and `quic-output-id`. Check `quic-output-valid? connection+353
output` immediately before sending retained output: path promotion, CID+354
retirement or closure can invalidate a previously queued datagram. Raw datagram+355
output is unavailable after binding an address.+356
+357
`quic-peer-address` returns the current validated destination. Drain up to sixteen+358
retained 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+360
symbol. A changed-path event does not authorize sending application data there.+361
Only authenticated, replay-checked, handler-ready packets earn path credit;+362
clients discard unknown server sources. Server migration uses validated paths+363
and separate peer CIDs, requeues reliable flight under fresh packet numbers and+364
resets congestion accounting. DATAGRAM payloads are never retransmitted.+365
+366
After validating a Retry token, the caller can pass `retry-source-id:` to+367
`make-quic-server`. The original positional destination ID remains the first+368
client DCID; the keyword is the server's distinct Retry source CID. The server+369
derives Initial keys from the Retry CID and supplies both original and Retry+370
CID transport parameters. Retransmitted Initials route to the Retry or server+371
local CID. All supplied IDs are copied. This metadata does not validate an+372
address by itself: the caller owns token validation, and the constructor retains+373
the conservative amplification bound until authenticated Handshake traffic.+374
+375
The connection pads Initial datagrams to 1200 bytes, limits unvalidated server+376
output to three times received bytes, bounds deferred packets/CRYPTO/queues,+377
tracks directional keys and PN spaces, and confirms with HANDSHAKE_DONE.+378
It uses immediate ACKs, a conservative send window, bounded fixed-base PTO+379
backoff and fresh-PN frame retransmission, rather than full RFC 9002 recovery.+380
RFC 9221 DATAGRAM payloads are excluded from retransmission; their loss timer+381
uses a PING probe while retaining ordinary congestion and ACK bookkeeping.+382
Handshake timeout defaults to 10 seconds. A client accepts one valid routed Retry+383
after sending its first Initial and before processing a server Initial. It keeps+384
the original ClientHello, client source CID and packet-number progression, changes+385
Initial keys and destination CID, and includes the copied token on retransmissions.+386
Retry tokens over 1024 bytes are dropped; the retained first ClientHello is capped+387
at 64 KiB. CRYPTO fragmentation accounts for the token within 1200-byte Initials.+388
Retry does not restart the handshake deadline. The first accepted server Initial+389
binds the original, server Initial and Retry source IDs to the TLS transport checks.+390
VN, key updates, migration and connection-ID rotation+391
are not implemented. Stream ownership/flow control and+392
path/CID policy still belong to the layers above this primitive. No public+393
listener is provided, and independent security review is still required.+394
+395
Require `quic-complete?` for authenticated application delivery;+396
`quic-confirmed?` reports handshake confirmation. Attach an application-frame+397
handler with `quic-set-frame-handler!` and queue application frames with+398
`quic-send-frame!`. Before attachment, authenticated packets containing STREAM,+399
RESET_STREAM, STOP_SENDING or application flow-control frames are dropped whole,+400
without applying a prefix, recording their PN, acknowledging them or refreshing+401
idle activity. The peer can retransmit after attachment; no additional input+402
buffer is retained. Transport-only packets still drive handshake confirmation,+403
ACKs, path responses, CID validation and close without an application handler.+404
A frame exceeding the connection's 1,200-byte packet budget+405
(including its header and tag) raises synchronously before queue mutation;+406
previously queued work and the connection remain usable. On `quic-closed?`,+407
drain final close output and close the dedicated endpoint socket.+408
`quic-failure` exposes local failure or the peer's+409
close frame. Closure erases traffic keys, pending data and TLS secrets;+410
`tls-abort!` provides the same idempotent TLS cleanup to standalone callers.+411
+412
To 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+415
Length field and payload. Omission or zero disables receiving; receiving an+416
unsupported or oversized frame closes with PROTOCOL_VIOLATION. Received limits+417
use the actual wire size, including nonminimal Length-varint encodings.+418
+419
`quic-send-datagram! connection bytes` requires a complete authenticated+420
handshake and a nonzero peer advertisement. It copies one whole message,+421
queues a length-bearing frame (`0x31`) and returns `#t`; use `length?: #f` for+422
the lengthless `0x30` form. Invalid inputs and peer or 1,200-byte packet size+423
excess raise before queue mutation. No fragmentation is performed. A full+424
send queue returns `#f`: at most `quic-datagram-queue-limit` (32) DATAGRAM+425
messages may wait alongside the existing bounded frame queue. A full queue+426
does not overwrite earlier messages. Sending through `quic-send-frame!` also+427
enforces negotiation, size and count limits, but raises on queue refusal.+428
+429
`quic-read-datagram! connection` returns the oldest received message, or `#f`+430
when none is available, the handshake is incomplete, or the connection is+431
closed. An empty bytevector is a valid message. Receive dispatch is independent+432
of the stream-frame handler. It retains at most 32 messages and+433
`quic-datagram-byte-limit` (65,536) payload bytes; new arrivals beyond either+434
budget are dropped while normal packet ACK processing continues. Reads release+435
credit, and connection closure clears queued messages. DATAGRAM messages are+436
unreliable, do not consume STREAM flow-control credit and are never retransmitted.+437
Applications supply any flow identifiers inside their payloads.+438
+439
DATAGRAM codec/transport tests are in `test/test-datagram-codec.sgl`; protected+440
connection tests in `test/test-datagram.sgl` use a standalone TLS peer that owns+441
its keys. On a remote test machine, `node scripts/native-tls-tests.mjs --datagram`+442
selects both files for the native test package described above. They are also+443
included in the default bytecode and generated native suites.+444
+445
Server Initial packets carrying a token are discarded before CID pinning,+446
authentication, receive credit or closing replay. During the handshake, other+447
coalesced packets remain eligible for processing. ClientHello must have an+448
empty legacy session ID; the server reports PROTOCOL_VIOLATION for a nonempty+449
ID (RFC 9001 §8.4).+450
+451
Client receive tolerates authenticated server Initials in short datagrams.+452
Our send path still pads ack-eliciting server Initials and all client Initials;+453
servers still discard client Initials in datagrams under 1,200 bytes.+454
Well-formed NewSessionTickets are discarded regardless of lifetime without+455
retiring completed TLS. Ticket parsing and the 64-message work limit still apply.+456
The ticket's optional `early_data` extension must contain the four-byte QUIC+457
sentinel `0xffffffff`; another value closes with PROTOCOL_VIOLATION, while a+458
malformed extension length produces TLS decode_error. No ticket enables 0-RTT.+459
+460
`QUIC_CONNECTION_RED=1 sigil test test/test-connection.sgl` must fail two+461
completion controls. `QUIC_HP_SABOTAGE=1 sigil test test/test-connection.sgl`+462
must fail only the dedicated positive handshake completion assertion: one+463
protected PN byte is corrupted on every client Initial transmission and retry.+464
A single transient corrupt datagram is recoverable and has a separate loss test.+465
+466
`(sigil quic stream)` provides one client-initiated bidirectional stream (ID 0).+467
Use `stream-transport-parameters role receive-window: size` when constructing+468
the connection, then attach `make-quic-stream connection` before starting or+469
receiving packets. It validates its fixed allocation against the advertised+470
stream/connection limits and owns the connection's application-frame handler.+471
The default receive window is 65536 bytes, with a 1 MiB maximum.+472
+473
After authentication, `quic-stream-write! stream bytes fin?: boolean` accepts+474
up to 900 bytes and returns the accepted count; retry the remainder after+475
pumping datagrams and credit. A zero-byte FIN can return zero successfully;+476
`quic-stream-send-closed?` distinguishes it from a blocked write.+477
`quic-stream-read! stream maximum: count` returns copied ordered bytes and+478
advertises additional absolute credit as storage is freed. Empty reads can+479
mean 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.+482
STOP_SENDING cancels queued/in-flight STREAM retransmissions before RESET;+483
FIN/RESET final sizes, credit, stream ownership and limits remain checked.+484
Connection closure clears the stream's receive storage.+485
+486
The pure state layer is `(sigil quic stream state)`; its input frames must+487
already have passed the frame codec. `make-quic-stream connection+488
maximum-streams: count` optionally permits up to 16 sequential streams (one+489
by default), with one active receive window. `quic-stream-id` reports its ID.+490
Call `quic-stream-advance!` after both directions finish; it returns true only+491
after peer FIN has been consumed, all outgoing STREAM/FIN data acknowledged,+492
and enough control-queue capacity is available. A false result changes+493
nothing. Servers then grant the next absolute MAX_STREAMS count; clients wait+494
for that grant before writing their successor. Stream-specific cancellation+495
and retransmission accounting use the current ID. Reset streams do not advance.+496
The pure state constructor also accepts `maximum-streams:` from 1 (default)+497
to 16, allowing bounded sequential IDs 0, 4, 8, ... through+498
`stream-state-advance!`. Advancing requires fully consumed receiving FIN and+499
a sending FIN; the caller must first ensure every outgoing STREAM/FIN isShowing the first 500 of 709 diff lines for this file. This diff is INCOMPLETE; read the file or clone the repository for the rest.