Commit455f0e51Recorded17 Oct 2026Repositorysigil-quic

Document caller-owned packet sealing commitments

Changed
 README.md                       | 11 +++++++++++
 src/sigil/quic/packet.sgl       |  5 +++++
 src/sigil/quic/tls/schedule.sgl |  1 +
 3 files changed, 17 insertions(+)
Diff
README.mdmodified
@@ -210,6 +210,17 @@ version negotiation and connection-ID policy belong to the connection layer.
210
Kinds are `initial`, `handshake` and `application`. It pads tiny payloads
211
enough for a confined header-protection sample. The caller must separately
212
ensure the 1200-byte Initial datagram minimum and peer/MTU limits.
+213
+214
`protect-payload` and `seal-quic-packet` are stateless cryptographic primitives.
+215
The caller owns packet-number commitments and AEAD usage accounting for each
+216
directional AES key/IV. That state covers both entry points and every copy of
+217
the same key material: copying a key vector preserves its nonce space. Commit
+218
a fresh PN for each encryption attempt. If encryption might have used it,
+219
retire that PN even when a later allocation or header-protection step raises;
+220
retry with a fresh PN, or retire the key when commitment state is uncertain.
+221
`(sigil quic connection)` manages these commitments, usage ceilings and failure
+222
cleanup for normal connection traffic.
+223
224
`open-quic-packet datagram offset short-dcid-length material largest`
225
reconstructs the PN (`largest = -1` for an empty space) and authenticates one
226
packet. Successful results expose its header, number, payload, key phase and
src/sigil/quic/packet.sglmodified
@@ -60,6 +60,8 @@
60
(loop (- i 1) (quotient n 256))))
61
nonce))
62
+63
;; Stateless primitive. The caller owns PN commitments and AEAD budgets
+64
;; across both seal APIs and every copy of the same directional key/IV.
65
(define (protect-payload key iv packet-number header plaintext)
66
(let ((sealed (aes-128-gcm-encrypt key
67
(packet-nonce iv packet-number) header plaintext)))
@@ -180,6 +182,9 @@
182
(wipe-bytes! (vector-ref material i))
183
(vector-set! material i #f)))
184
+185
;; Encryption can consume this PN before a later allocation or HP error.
+186
;; The caller retires it on failure and shares state with protect-payload.
+187
;; The connection layer supplies managed PN/AEAD accounting and cleanup.
188
(define (seal-quic-packet material kind destination source number plaintext
189
(keys: (token #u8()) (pn-length 4) (length-width #f)
190
(key-phase 0) (spin 0)))
src/sigil/quic/tls/schedule.sglmodified
@@ -54,6 +54,7 @@
54
(derive-secret handshake "derived" (sha256-bytes #u8()))
55
(lambda (salt) (hkdf-sha256-extract salt (make-bytevector 32 0)))))
56
+57
;; TLS KeyUpdate label. QUIC uses next-traffic-keys and its "quic ku" label.
58
(define (traffic-update secret)
59
(hkdf-expand-label secret "traffic upd" #u8() 32))
60