Commit804cc5cbRecorded18 Oct 2026Repositorysigil-quic

Add bounded QUIC v1 Retry framing and integrity helpers

Changed
 README.md                       |  10 ++++++++--
 scripts/native-tls-tests.mjs    |   7 ++++++-
 src/sigil/quic/packet.sgl       |   4 +++-
 src/sigil/quic/packet/retry.sgl |  55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 test/test-retry-packet.sgl      | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 202 insertions(+), 4 deletions(-)
Diff
README.mdmodified
@@ -205,8 +205,14 @@ v1 Initial/Handshake/short headers with `encode-packet-header`. Header `start`
205
and `end` are absolute datagram offsets; `pn-offset` is relative to `start`.
206
Short headers consume the remaining datagram. Parsing caps datagrams at
207
65,527 bytes, v1 CIDs at 20 bytes and VN version lists at 256 entries. VN,
−208
Retry and unsupported versions are recognized separately; Retry integrity,
−209
version negotiation and connection-ID policy belong to the connection layer.
+208
Retry and unsupported versions are recognized separately. Retry integrity helpers
+209
are available in `(sigil quic packet retry)` and re-exported by the packet façade:
+210
`encode-retry-packet original-id destination-id source-id token` and
+211
`valid-retry-packet? original-id wire`. The encoder accepts `unused:` from 0 to 15;
+212
the validator drops malformed peer packets. Both bound CIDs and datagram size.
+213
The standardized public integrity tag does not authenticate a server or validate
+214
an address. Connection Retry handling, private token admission, version negotiation
+215
and connection-ID policy remain separate; no listener uses these helpers yet.
216
217
`(sigil quic packet)` re-exports those helpers and provides
218
`seal-quic-packet material kind dcid scid number plaintext` with optional
scripts/native-tls-tests.mjsmodified
@@ -21,6 +21,7 @@ const files = [
21
'test-frame.sgl',
22
'test-reassembly.sgl',
23
'test-packet.sgl',
+24
'test-retry-packet.sgl',
25
'test-connection-space.sgl',
26
'test-connection.sgl',
27
'test-aead-limits.sgl',
@@ -66,7 +67,8 @@ const negotiation = process.argv.includes('--negotiation');
67
const certificatePolicy = process.argv.includes('--certificate-policy');
68
const retryPolicy = process.argv.includes('--retry-policy');
69
const earlyPackets = process.argv.includes('--early-packets');
−69
if ([cleanupFaults, secretCleanup, secretRetention, handshakeCleanup, packetRetention, factoryCleanup, eventCleanup, constructionCleanup, pathResponse, cidZero, cidSequence, handlerReadiness, seenBudget, ticketValidation, negotiation, certificatePolicy, retryPolicy, earlyPackets].filter(Boolean).length > 1) {
+70
const retryPacket = process.argv.includes('--retry-packet');
+71
if ([cleanupFaults, secretCleanup, secretRetention, handshakeCleanup, packetRetention, factoryCleanup, eventCleanup, constructionCleanup, pathResponse, cidZero, cidSequence, handlerReadiness, seenBudget, ticketValidation, negotiation, certificatePolicy, retryPolicy, earlyPackets, retryPacket].filter(Boolean).length > 1) {
72
throw new Error('Select one focused test suite');
73
}
74
if (cleanupFaults) {
@@ -123,6 +125,9 @@ if (retryPolicy) {
125
if (earlyPackets) {
126
files.splice(0, files.length, 'test-early-packets.sgl');
127
}
+128
if (retryPacket) {
+129
files.splice(0, files.length, 'test-retry-packet.sgl');
+130
}
131
const bodies = files.map(file => {
132
const text = readFileSync(join(root, 'test', file), 'utf8');
133
const boundary = text.indexOf('\n\n');
src/sigil/quic/packet.sglmodified
@@ -7,7 +7,8 @@
7
(sigil quic error)
8
(sigil quic bytes)
9
(sigil quic tls schedule)
−10
(sigil quic packet header))
+10
(sigil quic packet header)
+11
(sigil quic packet retry))
12
(export initial-secret initial-keys packet-nonce protect-payload open-payload
13
apply-header-mask! protect-header! unprotect-header!
14
traffic-keys next-traffic-keys discard-packet-keys! seal-quic-packet open-quic-packet
@@ -16,6 +17,7 @@
17
opened-quic-packet-payload opened-quic-packet-key-phase opened-quic-packet-spin
18
packet-datagram-limit decode-packet-header encode-packet-header
19
encode-packet-number read-packet-number reconstruct-packet-number
+20
encode-retry-packet valid-retry-packet?
21
quic-header? quic-header-kind quic-header-version
22
quic-header-destination-id quic-header-source-id quic-header-token
23
quic-header-integrity-tag quic-header-versions
src/sigil/quic/packet/retry.sgladded
@@ -0,0 +1,55 @@
+1
;;; QUIC v1 Retry framing and RFC 9001 section 5.8 integrity.
+2
;;; The public key/nonce are protocol constants, not peer authentication.
+3
;;; Connection routing, one-Retry policy and private address tokens are separate.
+4
(define-library (sigil quic packet retry)
+5
(import (sigil crypto)
+6
(sigil math)
+7
(sigil quic bytes)
+8
(sigil quic packet header))
+9
(export encode-retry-packet valid-retry-packet?)
+10
(begin
+11
(define retry-key (hex->bytes "be0c690b9f66575a1d766b54e368c84e"))
+12
(define retry-nonce (hex->bytes "461599d35d632bf2239825bb"))
+13
+14
(define (require-id! id)
+15
(unless (and (bytevector? id) (<= (bytevector-length id) 20))
+16
(error "QUIC Retry: expected a connection ID of at most twenty bytes")))
+17
+18
;; Only bounded, already framed Retry bytes reach this private helper.
+19
(define (integrity-tag original-id unsigned)
+20
(let* ((pseudo (bytes-append (bytevector (bytevector-length original-id)) original-id unsigned))
+21
(sealed (aes-128-gcm-encrypt retry-key retry-nonce pseudo #u8())))
+22
(unless (and (pair? sealed) (bytevector? (car sealed))
+23
(= 0 (bytevector-length (car sealed)))
+24
(bytevector? (cdr sealed)) (= 16 (bytevector-length (cdr sealed))))
+25
(error "QUIC Retry: integrity computation failed"))
+26
(cdr sealed)))
+27
+28
(define (encode-retry-packet original-id destination-id source-id token (keys: (unused 0)))
+29
(for-each require-id! (list original-id destination-id source-id))
+30
(unless (and (integer? unused) (exact? unused) (<= 0 unused 15)
+31
(bytevector? token) (> (bytevector-length token) 0))
+32
(error "QUIC Retry: invalid unused bits or empty token"))
+33
(when (bytes=? original-id source-id)
+34
(error "QUIC Retry: source ID must differ from the original destination ID"))
+35
(when (> (+ 7 (bytevector-length destination-id) (bytevector-length source-id)
+36
(bytevector-length token) 16) packet-datagram-limit)
+37
(error "QUIC Retry: packet exceeds the datagram bound"))
+38
(let ((unsigned
+39
(bytes-append (bytevector (+ 240 unused)) #u8(0 0 0 1)
+40
(bytevector (bytevector-length destination-id)) destination-id
+41
(bytevector (bytevector-length source-id)) source-id token)))
+42
(bytes-append unsigned (integrity-tag original-id unsigned))))
+43
+44
;; Invalid local ODCID arguments raise. Malformed peer bytes are drops;
+45
;; cryptographic setup failures remain errors rather than false matches.
+46
(define (valid-retry-packet? original-id wire)
+47
(require-id! original-id)
+48
(let ((header
+49
(and (bytevector? wire) (<= 1 (bytevector-length wire) packet-datagram-limit)
+50
(guard (exn (else #f)) (decode-packet-header wire 0 0)))))
+51
(and header (eq? (quic-header-kind header) 'retry)
+52
(= 1 (quic-header-version header))
+53
(not (bytes=? original-id (quic-header-source-id header)))
+54
(bytes-timing-safe=? (quic-header-integrity-tag header)
+55
(integrity-tag original-id (bytevector-copy wire 0 (- (bytevector-length wire) 16)))))))))
test/test-retry-packet.sgladded
@@ -0,0 +1,130 @@
+1
(import (sigil test)
+2
(sigil process)
+3
(sigil crypto)
+4
(sigil math)
+5
(sigil quic bytes)
+6
(sigil quic packet))
+7
+8
(define retry-test-original (hex->bytes "8394c8f03e515708"))
+9
(define retry-test-source (hex->bytes "f067a5502a4262b5"))
+10
(define retry-test-token (hex->bytes "746f6b656e"))
+11
(define retry-test-wire
+12
(hex->bytes "ff000000010008f067a5502a4262b5746f6b656e04a265ba2eff4d829058fb3f0f2496ba"))
+13
+14
(define (retry-test-encoded)
+15
(encode-retry-packet retry-test-original #u8() retry-test-source retry-test-token unused: 15))
+16
+17
(define (retry-test-vector! expected actual)
+18
(assert-true
+19
(bytes=?
+20
(if (equal? "1" (getenv "QUIC_RETRY_VECTOR_RED")) (flip-byte expected 0) expected)
+21
actual)))
+22
+23
;; Independently sign a forbidden shape with the standardized public constants.
+24
;; A valid tag must not bypass Retry's source-ID rule.
+25
(define (retry-test-sign original unsigned)
+26
(let ((sealed
+27
(aes-128-gcm-encrypt (hex->bytes "be0c690b9f66575a1d766b54e368c84e")
+28
(hex->bytes "461599d35d632bf2239825bb")
+29
(bytes-append (bytevector (bytevector-length original)) original unsigned) #u8())))
+30
(unless sealed (error "Retry fixture could not compute the independent tag"))
+31
(bytes-append unsigned (cdr sealed))))
+32
+33
(test-group "QUIC v1 Retry integrity and bounded framing"
+34
(test "ql12-retry-vector: RFC9001 Appendix A4 complete Retry packet"
+35
(retry-test-vector! retry-test-wire (retry-test-encoded)))
+36
(test "ql12-retry-vector: RFC9001 Appendix A4 Retry integrity tag"
+37
(let ((wire (retry-test-encoded)))
+38
(retry-test-vector! (hex->bytes "04a265ba2eff4d829058fb3f0f2496ba")
+39
(bytevector-copy wire (- (bytevector-length wire) 16)))))
+40
(test "ql12-retry-control: literal published packet validates and parses independently"
+41
(assert-true (valid-retry-packet? retry-test-original retry-test-wire))
+42
(let ((header (decode-packet-header retry-test-wire 0 0)))
+43
(assert-equal 'retry (quic-header-kind header))
+44
(assert-equal 1 (quic-header-version header))
+45
(assert-equal #u8() (quic-header-destination-id header))
+46
(assert-equal retry-test-source (quic-header-source-id header))
+47
(assert-equal retry-test-token (quic-header-token header))
+48
(assert-equal #f (quic-header-pn-offset header))
+49
(assert-equal (bytevector-length retry-test-wire) (quic-header-end header))))
+50
(test "ql12-retry-control: every single-bit mutation of the published packet is rejected"
+51
(do ((index 0 (+ index 1))) ((= index (bytevector-length retry-test-wire)))
+52
(do ((bit 1 (* bit 2))) ((= bit 256))
+53
(let ((wire (bytevector-copy retry-test-wire)))
+54
;; Toggle using integer arithmetic so no mutation shares storage.
+55
(let ((value (bytevector-u8-ref wire index)))
+56
(bytevector-u8-set! wire index
+57
(if (= 0 (modulo (quotient value bit) 2)) (+ value bit) (- value bit))))
+58
(assert-false (valid-retry-packet? retry-test-original wire))))))
+59
(test "ql12-retry-control: original destination bytes and length bind the integrity tag"
+60
(do ((index 0 (+ index 1))) ((= index (bytevector-length retry-test-original)))
+61
(assert-false (valid-retry-packet? (flip-byte retry-test-original index) retry-test-wire)))
+62
(assert-false (valid-retry-packet? #u8() retry-test-wire))
+63
(assert-false (valid-retry-packet? (bytes-append retry-test-original #u8(0)) retry-test-wire)))
+64
(test "ql12-retry-control: all sixteen unused fields are accepted only with matching tags"
+65
(do ((unused 0 (+ unused 1))) ((= unused 16))
+66
(let ((wire (encode-retry-packet retry-test-original #u8() retry-test-source #u8(1) unused: unused)))
+67
(assert-equal (+ 240 unused) (quic-header-first (decode-packet-header wire 0 0)))
+68
(assert-true (valid-retry-packet? retry-test-original wire))
+69
(assert-false (valid-retry-packet? retry-test-original (flip-byte wire 0))))))
+70
(test "ql12-retry-control: empty and twenty-byte connection IDs remain bounded"
+71
(for-each
+72
(lambda (ids)
+73
(let ((wire (encode-retry-packet (car ids) (cadr ids) (caddr ids) #u8(1))))
+74
(assert-true (valid-retry-packet? (car ids) wire))
+75
(assert-equal (cadr ids) (quic-header-destination-id (decode-packet-header wire 0 0)))
+76
(assert-equal (caddr ids) (quic-header-source-id (decode-packet-header wire 0 0)))))
+77
(list (list retry-test-original #u8() #u8())
+78
(list #u8() #u8() #u8(1))
+79
(list (make-bytevector 20 1) (make-bytevector 20 2) (make-bytevector 20 3)))))
+80
(test "ql12-retry-control: maximal token fits exactly and its next byte is rejected"
+81
(let* ((token (make-bytevector (- packet-datagram-limit 7 8 16) 7))
+82
(wire (encode-retry-packet retry-test-original #u8() retry-test-source token)))
+83
(assert-equal packet-datagram-limit (bytevector-length wire))
+84
(assert-true (valid-retry-packet? retry-test-original wire))
+85
(assert-error (encode-retry-packet retry-test-original #u8() retry-test-source
+86
(bytes-append token #u8(0))))))
+87
(test "ql12-retry-control: truncated malformed empty-token and oversized packets are drops"
+88
(do ((end 0 (+ end 1))) ((= end (bytevector-length retry-test-wire)))
+89
(assert-false (valid-retry-packet? retry-test-original (bytevector-copy retry-test-wire 0 end))))
+90
(for-each
+91
(lambda (wire) (assert-false (valid-retry-packet? retry-test-original wire)))
+92
(list #f "not a packet" (make-bytevector (+ packet-datagram-limit 1) 0)
+93
(bytes-append #u8(240 0 0 0 1 0 0) (make-bytevector 16 0))
+94
(bytes-append retry-test-wire #u8(0)))))
+95
(test "ql12-retry-control: even a matching tag cannot reuse the original destination as source"
+96
(assert-error (encode-retry-packet retry-test-original #u8() retry-test-original #u8(1)))
+97
(let ((unsigned (bytes-append #u8(240 0 0 0 1 0 8) retry-test-original #u8(1))))
+98
(assert-false (valid-retry-packet? retry-test-original (retry-test-sign retry-test-original unsigned)))))
+99
(test "ql12-retry-control: encoding and validation preserve and isolate caller-owned bytes"
+100
(let* ((original (bytevector-copy retry-test-original))
+101
(source (bytevector-copy retry-test-source))
+102
(token (bytevector-copy retry-test-token))
+103
(wire (encode-retry-packet original #u8() source token unused: 15))
+104
(saved (bytevector-copy wire)))
+105
(assert-true (valid-retry-packet? original wire))
+106
(assert-equal retry-test-original original)
+107
(assert-equal retry-test-source source)
+108
(assert-equal retry-test-token token)
+109
(bytevector-u8-set! source 0 0)
+110
(bytevector-u8-set! token 0 0)
+111
(assert-equal saved wire)
+112
(assert-true (valid-retry-packet? original wire))
+113
(bytevector-u8-set! original 0 0)
+114
(assert-false (valid-retry-packet? original wire))
+115
(assert-equal saved wire)))
+116
(test "ql12-retry-control: invalid local IDs tokens and unused values raise before encoding"
+117
(for-each
+118
(lambda (bad)
+119
(assert-error (encode-retry-packet bad #u8() retry-test-source #u8(1)))
+120
(assert-error (encode-retry-packet retry-test-original bad retry-test-source #u8(1)))
+121
(assert-error (encode-retry-packet retry-test-original #u8() bad #u8(1)))
+122
(assert-error (valid-retry-packet? bad retry-test-wire)))
+123
(list #f "id" (make-bytevector 21 0)))
+124
(for-each
+125
(lambda (bad) (assert-error (encode-retry-packet retry-test-original #u8() retry-test-source bad)))
+126
(list #f "token" #u8() (make-bytevector packet-datagram-limit 0)))
+127
(for-each
+128
(lambda (bad)
+129
(assert-error (encode-retry-packet retry-test-original #u8() retry-test-source #u8(1) unused: bad)))
+130
(list -1 16 1.5 #f))))