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 optionalscripts/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-versionssrc/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))))