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 is

Showing the first 500 of 709 diff lines for this file. This diff is INCOMPLETE; read the file or clone the repository for the rest.