Commit774ad07cRecorded18 Oct 2026Repositorysigil-quic
Add bounded private Retry token authentication and lifetime management
Changed
README.md | 20 ++++++++++++++++++
scripts/native-tls-tests.mjs | 9 +++++++--
src/sigil/quic/retry/token.sgl | 116 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
test/test-retry-token.sgl | 179 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
4 files changed, 322 insertions(+), 2 deletions(-)Diff
README.mdmodified
@@ -214,6 +214,26 @@ The standardized public integrity tag does not authenticate a server or validate
214
an address. Private token admission, version negotiation and connection-ID policy 215
remain separate; no server listener issues Retry yet. 216
+217
`(sigil quic retry token)` provides private server tokens through+218
`make-retry-token-manager`, `make-retry-token`, `validate-retry-token` and+219
`close-retry-token-manager!`. Managers own a fresh 32-byte key by default;+220
an optional `key:` is copied for explicit shared-server key management.+221
`lifetime:` defaults to 10,000 ms and is bounded to 1–60,000 ms. Close each+222
manager explicitly when retiring its key; tokens from other keys stop validating.+223
+224
`make-retry-token manager address original-id retry-id client-id now` authenticates+225
a Retry-only version, issuance time, random nonce and original destination CID+226
with HMAC-SHA256. Canonical address bytes (1–64 bytes, including IP and port),+227
Retry source CID and client source CID are length-delimited authenticated context.+228
The token contains no address bytes and is not encrypted. It is not a NEW_TOKEN+229
format. The original CID already appears in the same handshake's first Initial.+230
`validate-retry-token manager address retry-id client-id token now` returns an+231
owned original CID or `#f` for malformed, forged, future or expired tokens.+232
Times must use the same monotonic millisecond clock; expiry is exclusive.+233
Replay is limited to the bound address/CIDs and validity window. Local argument+234
errors and use after close raise. Operational crypto errors retire the key and+235
raise. Endpoint token admission is not integrated yet; no listener uses this API.+236
237
`(sigil quic packet)` re-exports those helpers and provides 238
`seal-quic-packet material kind dcid scid number plaintext` with optional 239
`token:`, `pn-length:`, `length-width:`, `key-phase:` and `spin:` keywords.scripts/native-tls-tests.mjsmodified
@@ -23,6 +23,7 @@ const files = [
23
'test-packet.sgl', 24
'test-retry-packet.sgl', 25
'test-client-retry.sgl',+26
'test-retry-token.sgl', 27
'test-connection-space.sgl', 28
'test-connection.sgl', 29
'test-aead-limits.sgl',@@ -70,7 +71,8 @@ const retryPolicy = process.argv.includes('--retry-policy');
71
const earlyPackets = process.argv.includes('--early-packets'); 72
const retryPacket = process.argv.includes('--retry-packet'); 73
const clientRetry = process.argv.includes('--client-retry');−73
if ([cleanupFaults, secretCleanup, secretRetention, handshakeCleanup, packetRetention, factoryCleanup, eventCleanup, constructionCleanup, pathResponse, cidZero, cidSequence, handlerReadiness, seenBudget, ticketValidation, negotiation, certificatePolicy, retryPolicy, earlyPackets, retryPacket, clientRetry].filter(Boolean).length > 1) {+74
const retryToken = process.argv.includes('--retry-token');+75
if ([cleanupFaults, secretCleanup, secretRetention, handshakeCleanup, packetRetention, factoryCleanup, eventCleanup, constructionCleanup, pathResponse, cidZero, cidSequence, handlerReadiness, seenBudget, ticketValidation, negotiation, certificatePolicy, retryPolicy, earlyPackets, retryPacket, clientRetry, retryToken].filter(Boolean).length > 1) { 76
throw new Error('Select one focused test suite'); 77
} 78
if (cleanupFaults) {@@ -133,6 +135,9 @@ if (retryPacket) {
135
if (clientRetry) { 136
files.splice(0, files.length, 'test-client-retry.sgl'); 137
}+138
if (retryToken) {+139
files.splice(0, files.length, 'test-retry-token.sgl');+140
} 141
const bodies = files.map(file => { 142
const text = readFileSync(join(root, 'test', file), 'utf8'); 143
const boundary = text.indexOf('\n\n');@@ -153,7 +158,7 @@ writeFileSync(join(source, 'native.sgl'), `(define-library (sigil quic tests nat
158
(sigil quic wire) 159
(sigil quic frame) 160
(sigil quic reassembly)−156
(sigil quic packet)+161
(sigil quic packet)${files.includes('test-retry-token.sgl') ? '\n (sigil quic retry token)' : ''} 162
(sigil quic error) 163
(sigil quic connection space) 164
(sigil quic connection)src/sigil/quic/retry/token.sgladded
@@ -0,0 +1,116 @@
+1
;;; Private server Retry tokens. This local format is not NEW_TOKEN.+2
;;; The caller supplies canonical IP-and-port bytes and monotonic milliseconds.+3
(define-library (sigil quic retry token)+4
(import (sigil crypto)+5
(sigil io)+6
(sigil math)+7
(sigil struct)+8
(sigil quic bytes)+9
(sigil quic wire))+10
(export make-retry-token-manager retry-token-manager? close-retry-token-manager!+11
make-retry-token validate-retry-token)+12
(begin+13
(define domain (string->utf8 "sigil quic Retry token v1"))+14
+15
(define-struct retry-token-manager+16
(key mutable: #t)+17
(lifetime))+18
+19
(define (wipe! bytes)+20
(when (bytevector? bytes)+21
(do ((index 0 (+ index 1))) ((= index (bytevector-length bytes)))+22
(bytevector-u8-set! bytes index 0))))+23
+24
(define (uint? value maximum)+25
(and (integer? value) (exact? value) (<= 0 value maximum)))+26
+27
;; Supplied keys are copied for explicit shared-server key management.+28
;; A fresh private key is the default; no getter exposes the owned copy.+29
(define (make-retry-token-manager (keys: (lifetime 10000) (key #f)))+30
(unless (and (uint? lifetime 60000) (> lifetime 0)+31
(or (not key) (and (bytevector? key) (= 32 (bytevector-length key)))))+32
(error "QUIC Retry token: invalid lifetime or key"))+33
(let ((owned #f) (transferred? #f))+34
(dynamic-wind+35
(lambda () #t)+36
(lambda ()+37
(set! owned (if key (bytevector-copy key) (random-bytes 32)))+38
(let ((manager (retry-token-manager key: owned lifetime: lifetime)))+39
(set! transferred? #t)+40
manager))+41
(lambda () (unless transferred? (wipe! owned))))))+42
+43
(define (close-retry-token-manager! manager)+44
(unless (retry-token-manager? manager) (error "QUIC Retry token: expected manager"))+45
(let ((key (retry-token-manager-key manager)))+46
(set-retry-token-manager-key! manager #f)+47
(wipe! key)))+48
+49
(define (require-open! manager)+50
(unless (and (retry-token-manager? manager) (retry-token-manager-key manager))+51
(error "QUIC Retry token: manager is invalid or closed")))+52
+53
(define (require-id! id minimum)+54
(unless (and (bytevector? id) (<= minimum (bytevector-length id) 20))+55
(error "QUIC Retry token: invalid connection ID")))+56
+57
(define (require-context! manager address retry-id client-id now)+58
(require-open! manager)+59
(unless (and (bytevector? address) (<= 1 (bytevector-length address) 64)+60
(uint? now quic-varint-maximum))+61
(error "QUIC Retry token: invalid canonical address or time"))+62
(require-id! retry-id 0)+63
(require-id! client-id 0))+64
+65
(define (timestamp-bytes now)+66
(let ((out (make-bytevector 8 0)))+67
(do ((index 7 (- index 1)) (value now (quotient value 256))) ((< index 0) out)+68
(bytevector-u8-set! out index (modulo value 256)))))+69
+70
(define (timestamp-value token)+71
(let loop ((index 2) (value 0))+72
(if (= index 10) value+73
(loop (+ index 1) (+ (* value 256) (bytevector-u8-ref token index))))))+74
+75
;; Length prefixes bind field boundaries, not just concatenated bytes.+76
;; Address bytes are authenticated input and are never put in the token.+77
(define (token-mac manager address retry-id client-id body)+78
(let ((mac (hmac-sha256-bytes (retry-token-manager-key manager)+79
(bytes-append domain+80
(bytevector (bytevector-length address)) address+81
(bytevector (bytevector-length retry-id)) retry-id+82
(bytevector (bytevector-length client-id)) client-id body))))+83
(unless (and (bytevector? mac) (= 32 (bytevector-length mac)))+84
(error "QUIC Retry token: HMAC computation failed"))+85
mac))+86
+87
(define (make-retry-token manager address original-id retry-id client-id now)+88
(require-context! manager address retry-id client-id now)+89
(require-id! original-id 8)+90
(when (bytes=? original-id retry-id)+91
(error "QUIC Retry token: Retry source must differ from original destination"))+92
(guard (exn (else (close-retry-token-manager! manager) (raise exn)))+93
(let ((body (bytes-append #u8(82 1) (timestamp-bytes now) (random-bytes 16)+94
(bytevector (bytevector-length original-id)) original-id)))+95
(bytes-append body (token-mac manager address retry-id client-id body)))))+96
+97
;; Peer bytes are bounded before copying/MAC work. Local context errors+98
;; raise; malformed, forged, future or expired tokens return #f.+99
;; Native crypto failures retire the owned key and remain exceptions.+100
(define (validate-retry-token manager address retry-id client-id token now)+101
(require-context! manager address retry-id client-id now)+102
(and (bytevector? token) (<= 67 (bytevector-length token) 79)+103
(= 82 (bytevector-u8-ref token 0)) (= 1 (bytevector-u8-ref token 1))+104
(let ((length (bytevector-u8-ref token 26)))+105
(and (<= 8 length 20) (= (+ 59 length) (bytevector-length token))+106
(guard (exn (else (close-retry-token-manager! manager) (raise exn)))+107
(let* ((end (- (bytevector-length token) 32))+108
(body (bytevector-copy token 0 end))+109
(tag (bytevector-copy token end))+110
(mac (token-mac manager address retry-id client-id body)))+111
(and (bytes-timing-safe=? tag mac)+112
(let ((issued (timestamp-value token)))+113
(and (<= issued now quic-varint-maximum)+114
(< (- now issued) (retry-token-manager-lifetime manager))+115
(let ((original (bytevector-copy token 27 end)))+116
(and (not (bytes=? original retry-id)) original)))))))))))))test/test-retry-token.sgladded
@@ -0,0 +1,179 @@
+1
(import (sigil test)+2
(sigil io)+3
(sigil process)+4
(sigil math)+5
(sigil crypto)+6
(sigil quic bytes)+7
(sigil quic wire)+8
(sigil quic retry token))+9
+10
(define rt-key (make-bytevector 32 17))+11
(define rt-address #u8(127 0 0 1 31 144))+12
(define rt-original #u8(1 2 3 4 5 6 7 8))+13
(define rt-retry #u8(11 12 13 14 15 16 17 18))+14
(define rt-client #u8(21 22 23 24 25 26 27 28))+15
+16
(define (rt-with-manager procedure (keys: (lifetime 10000) (key rt-key)))+17
(let ((manager (make-retry-token-manager lifetime: lifetime key: key)))+18
(dynamic-wind+19
(lambda () #t)+20
(lambda () (procedure manager))+21
(lambda () (close-retry-token-manager! manager)))))+22
+23
(define (rt-mint manager now)+24
(make-retry-token manager rt-address rt-original rt-retry rt-client now))+25
+26
(define (rt-open manager token now)+27
(validate-retry-token manager rt-address rt-retry rt-client token now))+28
+29
;; This test-side signer uses the documented private wire format and a supplied+30
;; fixture key. It never reads the manager's private key or implementation.+31
(define (rt-independent-tag body address retry client)+32
(hmac-sha256-bytes rt-key+33
(bytes-append (string->utf8 "sigil quic Retry token v1")+34
(bytevector (bytevector-length address)) address+35
(bytevector (bytevector-length retry)) retry+36
(bytevector (bytevector-length client)) client body)))+37
+38
(define (rt-sign body)+39
(bytes-append body (rt-independent-tag body rt-address rt-retry rt-client)))+40
+41
(test-group "Bounded private Retry address tokens"+42
(test "ql12-token-vector: independent HMAC covers purpose body address and both current CIDs"+43
(rt-with-manager+44
(lambda (manager)+45
(let* ((token (rt-mint manager 100))+46
(end (- (bytevector-length token) 32))+47
(expected (rt-independent-tag (bytevector-copy token 0 end) rt-address rt-retry rt-client)))+48
(assert-true+49
(bytes=? (if (equal? "1" (getenv "QUIC_RETRY_TOKEN_RED")) (flip-byte expected 0) expected)+50
(bytevector-copy token end)))))))+51
(test "ql12-token-control: exact version timestamp and original-ID format round trips"+52
(rt-with-manager+53
(lambda (manager)+54
(let ((token (rt-mint manager 16909060)))+55
(assert-equal 67 (bytevector-length token))+56
(assert-equal #u8(82 1 0 0 0 0 1 2 3 4) (bytevector-copy token 0 10))+57
(assert-equal (bytes-append #u8(8) rt-original) (bytevector-copy token 26 35))+58
(assert-equal rt-original (rt-open manager token 16909060))))))+59
(test "ql12-token-control: every wire bit truncation and excessive peer length is a drop"+60
(rt-with-manager+61
(lambda (manager)+62
(let ((token (rt-mint manager 100)))+63
(do ((index 0 (+ index 1))) ((= index (bytevector-length token)))+64
(do ((bit 1 (* bit 2))) ((= bit 256))+65
(let* ((changed (bytevector-copy token)) (value (bytevector-u8-ref changed index)))+66
(bytevector-u8-set! changed index (bitwise-xor value bit))+67
(assert-false (rt-open manager changed 100)))))+68
(do ((end 0 (+ end 1))) ((= end (bytevector-length token)))+69
(assert-false (rt-open manager (bytevector-copy token 0 end) 100)))+70
(for-each (lambda (bad) (assert-false (rt-open manager bad 100)))+71
(list #f "token" (make-bytevector 1024 0) (bytes-append token #u8(0))))+72
(assert-equal rt-original (rt-open manager token 100))))))+73
(test "ql12-token-control: changed IP port Retry CID client CID or manager cannot validate"+74
(rt-with-manager+75
(lambda (manager)+76
(let ((token (rt-mint manager 100)))+77
(do ((index 0 (+ index 1))) ((= index (bytevector-length rt-address)))+78
(assert-false (validate-retry-token manager (flip-byte rt-address index) rt-retry rt-client token 100)))+79
(do ((index 0 (+ index 1))) ((= index 8))+80
(assert-false (validate-retry-token manager rt-address (flip-byte rt-retry index) rt-client token 100))+81
(assert-false (validate-retry-token manager rt-address rt-retry (flip-byte rt-client index) token 100)))+82
(rt-with-manager (lambda (other) (assert-false (rt-open other token 100))) key: #f)+83
(rt-with-manager (lambda (shared) (assert-equal rt-original (rt-open shared token 100))))))))+84
(test "ql12-token-control: future time and the exact expiry boundary reject"+85
(rt-with-manager+86
(lambda (manager)+87
(let ((token (rt-mint manager 100)))+88
(assert-false (rt-open manager token 99))+89
(assert-equal rt-original (rt-open manager token 100))+90
(assert-equal rt-original (rt-open manager token 109))+91
(assert-false (rt-open manager token 110))+92
(assert-false (rt-open manager token 111)))) lifetime: 10))+93
(test "ql12-token-control: zero and maximum context fields are length-delimited"+94
(rt-with-manager+95
(lambda (manager)+96
(for-each+97
(lambda (fields)+98
(let* ((address (car fields)) (original (cadr fields))+99
(retry (caddr fields)) (client (cadddr fields))+100
(token (make-retry-token manager address original retry client 0)))+101
(assert-equal original (validate-retry-token manager address retry client token 0))))+102
(list (list #u8(1) rt-original #u8() #u8())+103
(list (make-bytevector 64 1) (make-bytevector 20 2)+104
(make-bytevector 20 3) (make-bytevector 20 4))))+105
(let ((token (make-retry-token manager #u8(1) rt-original #u8(2 3) rt-client 0)))+106
(assert-false (validate-retry-token manager #u8(1 2) #u8(3) rt-client token 0))))))+107
(test "ql12-token-control: repeated issuance uses independent random nonce bytes"+108
(rt-with-manager+109
(lambda (manager)+110
(let ((first (rt-mint manager 100)) (second (rt-mint manager 100)))+111
(assert-false (bytes=? (bytevector-copy first 10 26) (bytevector-copy second 10 26)))+112
(assert-equal rt-original (rt-open manager first 100))+113
(assert-equal rt-original (rt-open manager second 100))))))+114
(test "ql12-token-control: supplied keys inputs and validated original IDs have separate ownership"+115
(let ((key (bytevector-copy rt-key)) (original (bytevector-copy rt-original)))+116
(rt-with-manager+117
(lambda (manager)+118
(let* ((token (make-retry-token manager rt-address original rt-retry rt-client 100))+119
(saved (bytevector-copy token)) (decoded (rt-open manager token 100)))+120
(assert-equal rt-original original)+121
(assert-equal rt-key key)+122
(bytevector-u8-set! key 0 0)+123
(bytevector-u8-set! original 0 0)+124
(bytevector-u8-set! decoded 0 0)+125
(assert-equal rt-original (rt-open manager token 100))+126
(assert-equal saved token)+127
(close-retry-token-manager! manager)+128
(assert-equal 0 (bytevector-u8-ref key 0))+129
(assert-equal 17 (bytevector-u8-ref key 1)))) key: key)))+130
(test "ql12-token-control: close is idempotent and all subsequent token operations raise"+131
(rt-with-manager+132
(lambda (manager)+133
(let ((token (rt-mint manager 100)))+134
(assert-true (retry-token-manager? manager))+135
(close-retry-token-manager! manager)+136
(close-retry-token-manager! manager)+137
(assert-error (rt-mint manager 100))+138
(assert-error (rt-open manager token 100))+139
(assert-error (close-retry-token-manager! #f))))))+140
(test "ql12-token-control: invalid local context or original IDs raise without closing the manager"+141
(rt-with-manager+142
(lambda (manager)+143
(let ((token (rt-mint manager 100)))+144
(for-each+145
(lambda (bad) (assert-error (make-retry-token manager rt-address bad rt-retry rt-client 100)))+146
(list #f "id" #u8() (make-bytevector 7 0) (make-bytevector 21 0) rt-retry))+147
(for-each+148
(lambda (bad)+149
(assert-error (make-retry-token manager rt-address rt-original bad rt-client 100))+150
(assert-error (validate-retry-token manager rt-address rt-retry bad token 100)))+151
(list #f "id" (make-bytevector 21 0)))+152
(for-each+153
(lambda (bad) (assert-error (validate-retry-token manager bad rt-retry rt-client token 100)))+154
(list #f "address" #u8() (make-bytevector 65 0)))+155
(for-each (lambda (bad) (assert-error (rt-open manager token bad)))+156
(list -1 1.5 #f (+ quic-varint-maximum 1)))+157
(assert-equal rt-original (rt-open manager token 100))))))+158
(test "ql12-token-control: manager rejects invalid keys and lifetimes before use"+159
(for-each (lambda (bad) (assert-error (make-retry-token-manager key: bad)))+160
(list "key" #u8() (make-bytevector 31 0) (make-bytevector 33 0)))+161
(for-each (lambda (bad) (assert-error (make-retry-token-manager lifetime: bad)))+162
(list #f 0 -1 1.5 60001))+163
(rt-with-manager+164
(lambda (manager)+165
(let ((token (rt-mint manager 0)))+166
(assert-equal rt-original (rt-open manager token 59999))+167
(assert-false (rt-open manager token 60000)))) lifetime: 60000))+168
(test "ql12-token-control: even independently authenticated forbidden bodies cannot validate"+169
(rt-with-manager+170
(lambda (manager)+171
(let* ((token (rt-mint manager 100)) (body (bytevector-copy token 0 35))+172
(same-source (bytes-append (bytevector-copy body 0 27) rt-retry))+173
(other-purpose (bytevector-copy body)) (future (bytevector-copy body)))+174
(bytevector-u8-set! other-purpose 0 78)+175
(bytevector-u8-set! future 2 255)+176
(for-each (lambda (bad) (assert-false (rt-open manager (rt-sign bad) 100)))+177
(list same-source other-purpose future+178
(bytes-append (bytevector-copy body 0 26) #u8(7) (make-bytevector 7 0))+179
(bytes-append (bytevector-copy body 0 26) #u8(21) (make-bytevector 21 0)))))))))