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)))))))))