]> git.kaiwu.me - haproxy.git/commitdiff
REGTESTS: quic: add a Python QUIC client
authorFrederic Lecaille <flecaille@haproxy.com>
Wed, 18 Nov 2026 16:36:19 +0000 (17:36 +0100)
committerFrederic Lecaille <flecaille@haproxy.com>
Wed, 18 Nov 2026 17:00:24 +0000 (18:00 +0100)
Replaying some QUIC bugs requires a peer that completes a handshake and
then sends specific frames. Hand-crafted datagrams cannot do that.

Add a minimal QUIC v1 + TLS 1.3 + HTTP/3 client in reg-tests/quic/qclient:

  - qcrypto.py: RFC 9001 packet protection (HKDF, initial keys, varints,
    long and short header protection).

  - qclient.py: a QClient object over a real socket, with the received
    frames exposed. Hooks on the send and handshake paths let a caller
    alter packets, and the helpers cover key updates, connection migration
    and HTTP/3 requests, so tests can drive whatever scenario they need.

Both need the 'cryptography' package. Tests using them will carry
'#REGTEST_EXTRA=qclient' and run only when requested.

reg-tests/quic/qclient/qclient.py [new file with mode: 0644]
reg-tests/quic/qclient/qcrypto.py [new file with mode: 0644]

diff --git a/reg-tests/quic/qclient/qclient.py b/reg-tests/quic/qclient/qclient.py
new file mode 100644 (file)
index 0000000..b6fbc91
--- /dev/null
@@ -0,0 +1,400 @@
+"""Minimal QUIC v1 + TLS 1.3 + HTTP/3 client for local testing (no cert check).
+
+QClient(addr).handshake() completes the handshake, then send_1rtt()/request()
+can be used. Hooks allow a fuzzer to tamper with frames and packets.
+"""
+import os, socket, struct, hashlib, hmac, time
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey
+from cryptography.hazmat.primitives import serialization
+from qcrypto import (Keys, initial_keys, varint, read_varint, protect_long,
+                     protect_short, unprotect, hkdf_extract, hkdf_label)
+
+H = hashlib.sha256
+ZERO = b"\x00" * 32
+
+def tls_hs(t, body):
+    return bytes([t]) + struct.pack(">I", len(body))[1:] + body
+
+def ext(t, data):
+    return struct.pack(">HH", t, len(data)) + data
+
+def tp_encode(params):
+    out = b""
+    for k, v in params:
+        out += varint(k) + varint(len(v)) + v
+    return out
+
+def client_hello(pub, scid, sni=b"localhost", alpn=b"h3", tp=None, extra_ext=b""):
+    if tp is None:
+        tp = tp_encode([(0x0f, scid), (0x04, varint(1 << 20)), (0x05, varint(1 << 18)),
+                        (0x06, varint(1 << 18)), (0x07, varint(1 << 18)), (0x08, varint(100)),
+                        (0x09, varint(100)), (0x01, varint(30000)), (0x03, varint(1500))])
+    exts = (ext(0, struct.pack(">HBH", len(sni) + 3, 0, len(sni)) + sni) +
+            ext(10, b"\x00\x02\x00\x1d") +
+            ext(13, b"\x00\x08\x04\x03\x08\x04\x04\x01\x05\x03") +
+            ext(16, struct.pack(">HB", len(alpn) + 1, len(alpn)) + alpn) +
+            ext(43, b"\x02\x03\x04") +
+            ext(51, struct.pack(">HHH", 36, 0x1d, 32) + pub) +
+            ext(0x39, tp) + extra_ext)
+    body = b"\x03\x03" + os.urandom(32) + b"\x00" + b"\x00\x02\x13\x01" + b"\x01\x00" + struct.pack(">H", len(exts)) + exts
+    return tls_hs(1, body)
+
+def parse_frames(pt):
+    """Yield (type, info) for the frames in a decrypted payload."""
+    i = 0; out = []
+    while i < len(pt):
+        t, i = read_varint(pt, i)
+        if t == 0x00:
+            continue
+        if t == 0x01 or t == 0x1e:
+            out.append((t, None)); continue
+        if t in (0x02, 0x03):
+            la, i = read_varint(pt, i); adelay, i = read_varint(pt, i); rc, i = read_varint(pt, i); _, i = read_varint(pt, i)
+            for _ in range(rc):
+                _, i = read_varint(pt, i); _, i = read_varint(pt, i)
+            if t == 0x03:
+                for _ in range(3): _, i = read_varint(pt, i)
+            out.append((t, (la, adelay))); continue
+        if t == 0x06:
+            off, i = read_varint(pt, i); ln, i = read_varint(pt, i)
+            out.append((t, (off, pt[i:i + ln]))); i += ln; continue
+        if t == 0x07:
+            ln, i = read_varint(pt, i); i += ln; out.append((t, None)); continue
+        if 0x08 <= t <= 0x0f:
+            sid, i = read_varint(pt, i); off = 0
+            if t & 4: off, i = read_varint(pt, i)
+            if t & 2: ln, i = read_varint(pt, i)
+            else: ln = len(pt) - i
+            out.append((t, (sid, off, pt[i:i + ln], bool(t & 1)))); i += ln; continue
+        if t in (0x10, 0x12, 0x13, 0x14, 0x16, 0x17, 0x19):
+            v, i = read_varint(pt, i); out.append((t, v)); continue
+        if t in (0x11, 0x15):
+            a, i = read_varint(pt, i); b, i = read_varint(pt, i); out.append((t, (a, b))); continue
+        if t == 0x04:
+            for _ in range(3): _, i = read_varint(pt, i)
+            out.append((t, None)); continue
+        if t == 0x05:
+            for _ in range(2): _, i = read_varint(pt, i)
+            out.append((t, None)); continue
+        if t == 0x18:
+            seq, i = read_varint(pt, i); rpt, i = read_varint(pt, i); l = pt[i]
+            cid = pt[i + 1:i + 1 + l]; tok = pt[i + 1 + l:i + 1 + l + 16]; i += 1 + l + 16
+            out.append((t, (seq, rpt, cid, tok))); continue
+        if t in (0x1a, 0x1b):
+            out.append((t, pt[i:i + 8])); i += 8; continue
+        if t in (0x1c, 0x1d):
+            ec, i = read_varint(pt, i)
+            if t == 0x1c: _, i = read_varint(pt, i)
+            ln, i = read_varint(pt, i); out.append((t, (ec, pt[i:i + ln]))); i += ln; continue
+        out.append(("unknown", t)); break
+    return out
+
+class QClient:
+    def __init__(self, addr, timeout=1.0):
+        self.addr = addr
+        self.sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        self.sock.settimeout(timeout)
+        self.dcid = os.urandom(8); self.scid = os.urandom(8)
+        self.ck_init, self.sk_init = initial_keys(self.dcid)
+        self.pn = {0: 0, 2: 0, 3: 0}
+        self.largest = {0: -1, 2: -1, 3: -1}
+        self.crypto = {0: {}, 2: {}, 3: {}}
+        self.closed = None
+        self.streams = {}
+        self.ck_hs = self.sk_hs = self.ck_ap = self.sk_ap = None
+        self.server_cid = None
+        self.events = []
+        self.socks = [self.sock]
+        self.rx_pns = {0: set(), 2: set(), 3: set()}
+        self.kp_send = 0
+        self.challenges = []
+        self.peer_cids = {}
+
+    # ---- sending ----
+    def send_long(self, ptype, payload, pad_to=0, token=b"", dcid=None, raw_hook=None):
+        keys = self.ck_init if ptype == 0 else self.ck_hs
+        pn = self.pn[ptype]; self.pn[ptype] += 1
+        if pad_to:
+            est = 1 + 4 + 1 + 8 + 1 + 8 + 1 + len(token) + 2 + 4 + 16
+            if est + len(payload) < pad_to:
+                payload = payload + b"\x00" * (pad_to - est - len(payload))
+        pkt = protect_long(keys, ptype, dcid or self.server_cid or self.dcid, self.scid, pn, payload, token)
+        if raw_hook: pkt = raw_hook(pkt)
+        self.sock.sendto(pkt, self.addr)
+        return pkt
+
+    def send_1rtt(self, payload, raw_hook=None, dcid=None):
+        pn = self.pn[3]; self.pn[3] += 1
+        if len(payload) < 4: payload += b"\x00" * (4 - len(payload))
+        pkt = protect_short(self.ck_ap, dcid or self.server_cid, pn, payload, key_phase=self.kp_send)
+        if raw_hook: pkt = raw_hook(pkt)
+        self.sock.sendto(pkt, self.addr)
+
+    @staticmethod
+    def next_keys(k):
+        from qcrypto import hkdf_label as hl
+        n = Keys(hl(k.secret, b"quic ku", b"", 32)); n.hp = k.hp; return n
+
+    def key_update(self):
+        """Switch to the next 1-RTT send keys (RFC 9001 6.1)."""
+        self.ck_ap = self.next_keys(self.ck_ap); self.kp_send ^= 1
+
+    def migrate(self):
+        """Continue sending from a new local UDP port."""
+        ns = socket.socket(socket.AF_INET, socket.SOCK_DGRAM); ns.settimeout(self.sock.gettimeout())
+        self.socks.append(ns); self.sock = ns
+
+    def ack_frame(self, space):
+        la = self.largest[space]
+        if la < 0: return b""
+        return b"\x02" + varint(la) + varint(0) + varint(0) + varint(la)
+
+    @staticmethod
+    def ack_for(pns, delay=0):
+        """ACK frame acknowledging exactly the packet numbers in <pns>."""
+        p = sorted(set(pns), reverse=True)
+        if not p: return b""
+        ranges = []; hi = lo = p[0]
+        for x in p[1:]:
+            if x == lo - 1: lo = x
+            else: ranges.append((hi, lo)); hi = lo = x
+        ranges.append((hi, lo))
+        f = b"\x02" + varint(ranges[0][0]) + varint(delay) + varint(len(ranges) - 1) + varint(ranges[0][0] - ranges[0][1])
+        prev_lo = ranges[0][1]
+        for hi, lo in ranges[1:]:
+            f += varint(prev_lo - hi - 2) + varint(hi - lo); prev_lo = lo
+        return f
+
+    # ---- receiving ----
+    def recv_all(self, wait=0.5, until=None):
+        end = time.time() + wait
+        while time.time() < end:
+            import select
+            try:
+                r, _, _ = select.select(self.socks, [], [], max(0.01, end - time.time()))
+            except ValueError:
+                return
+            if not r:
+                break
+            for sk in r:
+                try:
+                    d, _ = sk.recvfrom(65536)
+                except (ConnectionRefusedError, BlockingIOError, socket.timeout):
+                    continue
+                self.on_datagram(d)
+            if until and until(): return
+
+    def on_datagram(self, d):
+        i = 0
+        while i < len(d):
+            first = d[i]
+            if first & 0x80:
+                ver = struct.unpack(">I", d[i + 1:i + 5])[0]
+                j = i + 5; dl = d[j]; dcid = d[j + 1:j + 1 + dl]; j += 1 + dl
+                sl = d[j]; scid = d[j + 1:j + 1 + sl]; j += 1 + sl
+                ptype = (first >> 4) & 3
+                if ver == 0:
+                    self.events.append(("vneg", None)); return
+                if ptype == 3:
+                    self.events.append(("retry", d[j:])); return
+                if ptype == 0:
+                    tl, j = read_varint(d, j); j += tl
+                ln, j = read_varint(d, j)
+                end = j + ln
+                keys = {0: self.sk_init, 2: self.sk_hs}.get(ptype)
+                if self.server_cid is None: self.server_cid = scid
+                if keys is None:
+                    i = end; continue
+                try:
+                    pn, pt, _ = unprotect(keys, d[i:end], j - i, True, end - i, max(self.largest[ptype], 0))
+                except Exception as e:
+                    self.events.append(("decrypt-fail", ptype)); i = end; continue
+                self.largest[ptype] = max(self.largest[ptype], pn)
+                self.rx_pns[ptype].add(pn)
+                self.on_frames(ptype, parse_frames(pt))
+                # Derive the next keys as soon as the CRYPTO data allowing
+                # it has been consumed: the following packets may be
+                # coalesced in the same datagram and need them.
+                if ptype == 0:
+                    self._try_sh()
+                elif ptype == 2:
+                    self._try_fin()
+                i = end
+            else:
+                if not self.sk_ap: return
+                try:
+                    pn, pt, _ = unprotect(self.sk_ap, d[i:], i + 1 + len(self.scid), False, len(d) - i, max(self.largest[3], 0))
+                except Exception:
+                    try:
+                        nk = self.next_keys(self.sk_ap)
+                        pn, pt, _ = unprotect(nk, d[i:], i + 1 + len(self.scid), False, len(d) - i, max(self.largest[3], 0))
+                        self.sk_ap = nk; self.events.append(("peer-key-update", None))
+                    except Exception:
+                        self.events.append(("decrypt-fail", 3)); return
+                self.largest[3] = max(self.largest[3], pn)
+                self.rx_pns[3].add(pn)
+                self.on_frames(3, parse_frames(pt))
+                return
+
+    def on_frames(self, space, frames):
+        for t, info in frames:
+            if t == 0x06:
+                off, data = info; self.crypto[space][off] = data
+            elif 0x08 <= (t if isinstance(t, int) else 0) <= 0x0f:
+                sid, off, data, fin = info
+                st = self.streams.setdefault(sid, {"data": {}, "fin": None})
+                st["data"][off] = data
+                if fin: st["fin"] = off + len(data)
+            elif t in (0x1c, 0x1d):
+                self.closed = info
+            elif t == 0x1e:
+                self.events.append(("hs_done", None))
+            elif t == 0x18:
+                self.events.append(("ncid", info)); self.peer_cids[info[0]] = info[2]
+            elif t == 0x1a:
+                self.challenges.append(info)
+            elif t in (0x02, 0x03):
+                self.events.append(("ack", space, info))
+            elif t == "unknown":
+                self.events.append(("unknown-frame", info))
+
+    def crypto_stream(self, space):
+        buf = b""; parts = self.crypto[space]
+        while len(buf) in parts:
+            nxt = parts[len(buf)]
+            if not nxt: break
+            buf += nxt
+        # handle overlaps
+        for off in sorted(parts):
+            if off < len(buf) < off + len(parts[off]):
+                buf += parts[off][len(buf) - off:]
+        return buf
+
+    def stream_data(self, sid):
+        st = self.streams.get(sid)
+        if not st: return b"", False
+        buf = b""
+        while True:
+            for off, data in st["data"].items():
+                if off <= len(buf) < off + len(data):
+                    buf += data[len(buf) - off:]; break
+            else:
+                break
+        return buf, st["fin"] is not None and len(buf) >= st["fin"]
+
+    # ---- handshake ----
+    def handshake(self, ch_hook=None, wait=2.0):
+        self.priv = X25519PrivateKey.generate()
+        pub = self.priv.public_key().public_bytes(serialization.Encoding.Raw, serialization.PublicFormat.Raw)
+        self.ch = client_hello(pub, self.scid)
+        if ch_hook:
+            ch_hook(self)
+        else:
+            self.send_long(0, b"\x06" + varint(0) + varint(len(self.ch)) + self.ch, pad_to=1200)
+        # wait for ServerHello
+        self.recv_all(wait, until=lambda: self._try_sh())
+        if not self._try_sh():
+            print("handshake: no ServerHello crypto0=%d events=%r" %
+                  (len(self.crypto_stream(0)), self.events), flush=True)
+            return False
+        # wait for server Finished
+        self.recv_all(wait, until=lambda: self._try_fin())
+        if not self._try_fin():
+            print("handshake: no Finished crypto0=%d crypto2=%d events=%r" %
+                  (len(self.crypto_stream(0)), len(self.crypto_stream(2)),
+                   self.events), flush=True)
+            return False
+        # send client Finished
+        fk = hkdf_label(self.c_hs, b"finished", b"", 32)
+        vd = hmac.new(fk, self.th_sfin, H).digest()
+        fin = tls_hs(20, vd)
+        self.send_long(0, self.ack_frame(0), pad_to=0) if self.largest[0] >= 0 else None
+        self.send_long(2, self.ack_frame(2) + b"\x06" + varint(0) + varint(len(fin)) + fin)
+        return True
+
+    def _try_sh(self):
+        if self.ck_hs: return True
+        b = self.crypto_stream(0)
+        if len(b) < 4: return False
+        ln = struct.unpack(">I", b"\x00" + b[1:4])[0]
+        if b[0] != 2 or len(b) < 4 + ln: return False
+        sh = b[:4 + ln]
+        body = sh[4:]
+        i = 2 + 32; sl = body[i]; i += 1 + sl + 2 + 1
+        el = struct.unpack(">H", body[i:i + 2])[0]; i += 2; end = i + el
+        spub = None
+        while i < end:
+            t, l = struct.unpack(">HH", body[i:i + 4]); i += 4
+            if t == 51: spub = body[i + 4:i + 4 + 32]
+            i += l
+        if spub is None: return False
+        from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PublicKey
+        shared = self.priv.exchange(X25519PublicKey.from_public_bytes(spub))
+        self.transcript = self.ch + sh
+        early = hkdf_extract(ZERO, ZERO)
+        derived = hkdf_label(early, b"derived", H(b"").digest(), 32)
+        hs = hkdf_extract(derived, shared)
+        th = H(self.transcript).digest()
+        self.c_hs = hkdf_label(hs, b"c hs traffic", th, 32)
+        s_hs = hkdf_label(hs, b"s hs traffic", th, 32)
+        self.ck_hs, self.sk_hs = Keys(self.c_hs), Keys(s_hs)
+        self.master = hkdf_extract(hkdf_label(hs, b"derived", H(b"").digest(), 32), ZERO)
+        return True
+
+    def _try_fin(self):
+        if self.ck_ap: return True
+        b = self.crypto_stream(2); i = 0; msgs = b""
+        while i + 4 <= len(b):
+            ln = struct.unpack(">I", b"\x00" + b[i + 1:i + 4])[0]
+            if i + 4 + ln > len(b): return False
+            t = b[i]; msgs += b[i:i + 4 + ln]; i += 4 + ln
+            if t == 20:
+                self.transcript += msgs
+                th = H(self.transcript).digest()
+                c_ap = hkdf_label(self.master, b"c ap traffic", th, 32)
+                s_ap = hkdf_label(self.master, b"s ap traffic", th, 32)
+                self.ck_ap, self.sk_ap = Keys(c_ap), Keys(s_ap)
+                self.th_sfin = th
+                return True
+        return False
+
+    # ---- HTTP/3 ----
+    @staticmethod
+    def stream_frame(sid, data, off=0, fin=True):
+        t = 0x08 | 0x02 | (0x04 if off else 0) | (0x01 if fin else 0)
+        return bytes([t]) + varint(sid) + (varint(off) if off else b"") + varint(len(data)) + data
+
+    @staticmethod
+    def qpack_get(path=b"/", authority=b"localhost", extra=b""):
+        def lit_nameref(idx, val):  # 0101NNNN static name ref, never-indexed=0
+            assert idx < 15
+            return bytes([0x50 | idx]) + bytes([len(val)]) + val if len(val) < 127 else None
+        return b"\x00\x00" + b"\xd1" + b"\xd7" + lit_nameref(0, authority) + lit_nameref(1, path) + extra
+
+    @staticmethod
+    def h3_frame(t, payload):
+        return varint(t) + varint(len(payload)) + payload
+
+    def h3_setup(self):
+        ctrl = b"\x00" + self.h3_frame(0x04, b"")
+        self.send_1rtt(self.ack_frame(3) + self.stream_frame(2, ctrl, fin=False))
+
+    def request(self, sid=0, path=b"/", body=None, wait=1.0):
+        hdrs = self.h3_frame(0x01, self.qpack_get(path))
+        data = hdrs + (self.h3_frame(0x00, body) if body else b"")
+        self.send_1rtt(self.ack_frame(3) + self.stream_frame(sid, data))
+        self.recv_all(wait, until=lambda: self.stream_data(sid)[1] or self.closed)
+        return self.stream_data(sid)
+
+
+if __name__ == "__main__":
+    import sys
+    port = int(sys.argv[1]) if len(sys.argv) > 1 else 19443
+    c = QClient(("127.0.0.1", port))
+    ok = c.handshake()
+    print("handshake", ok, "events", c.events, "closed", c.closed)
+    if ok:
+        c.h3_setup()
+        data, fin = c.request(0)
+        print("stream0 fin=%s len=%d data=%r" % (fin, len(data), data[:80]))
+        print("closed", c.closed, "events", c.events)
diff --git a/reg-tests/quic/qclient/qcrypto.py b/reg-tests/quic/qclient/qcrypto.py
new file mode 100644 (file)
index 0000000..a960a9e
--- /dev/null
@@ -0,0 +1,105 @@
+"""Minimal QUIC v1 packet protection (RFC 9001) with the cryptography package."""
+import hmac, hashlib, struct
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+SALT_V1 = bytes.fromhex("38762cf7f55934b34d179ae6a4c80cadccbb7f0a")
+
+def hkdf_extract(salt, ikm, h=hashlib.sha256):
+    return hmac.new(salt, ikm, h).digest()
+
+def hkdf_expand(prk, info, length, h=hashlib.sha256):
+    out, t, i = b"", b"", 1
+    while len(out) < length:
+        t = hmac.new(prk, t + info + bytes([i]), h).digest(); out += t; i += 1
+    return out[:length]
+
+def hkdf_label(secret, label, ctx, length, h=hashlib.sha256):
+    full = b"tls13 " + label
+    info = struct.pack(">H", length) + bytes([len(full)]) + full + bytes([len(ctx)]) + ctx
+    return hkdf_expand(secret, info, length, h)
+
+class Keys:
+    def __init__(self, secret, h=hashlib.sha256, klen=16):
+        self.secret = secret
+        self.key = hkdf_label(secret, b"quic key", b"", klen, h)
+        self.iv = hkdf_label(secret, b"quic iv", b"", 12, h)
+        self.hp = hkdf_label(secret, b"quic hp", b"", klen, h)
+        self.aead = AESGCM(self.key)
+    def mask(self, sample):
+        e = Cipher(algorithms.AES(self.hp), modes.ECB()).encryptor()
+        return e.update(sample) + e.finalize()
+    def nonce(self, pn):
+        return bytes(a ^ b for a, b in zip(self.iv, pn.to_bytes(12, "big")))
+
+def initial_keys(dcid):
+    s = hkdf_extract(SALT_V1, dcid)
+    return Keys(hkdf_label(s, b"client in", b"", 32)), Keys(hkdf_label(s, b"server in", b"", 32))
+
+def varint(v):
+    if v < 0x40: return bytes([v])
+    if v < 0x4000: return struct.pack(">H", v | 0x4000)
+    if v < 0x40000000: return struct.pack(">I", v | 0x80000000)
+    return struct.pack(">Q", v | 0xC000000000000000)
+
+def read_varint(b, i):
+    l = 1 << (b[i] >> 6); v = b[i] & 0x3f
+    for k in range(1, l): v = (v << 8) | b[i + k]
+    return v, i + l
+
+def protect_long(keys, ptype, dcid, scid, pn, payload, token=b"", pn_len=4, version=1):
+    """ptype: 0 Initial, 2 Handshake. Returns protected packet bytes."""
+    first = 0xC0 | (ptype << 4) | (pn_len - 1)
+    hdr = bytes([first]) + struct.pack(">I", version) + bytes([len(dcid)]) + dcid + bytes([len(scid)]) + scid
+    if ptype == 0: hdr += varint(len(token)) + token
+    length = pn_len + len(payload) + 16
+    hdr += varint(length)
+    pn_off = len(hdr)
+    hdr += (pn & ((1 << (8 * pn_len)) - 1)).to_bytes(pn_len, "big")
+    ct = keys.aead.encrypt(keys.nonce(pn), payload, hdr)
+    pkt = bytearray(hdr + ct)
+    m = keys.mask(bytes(pkt[pn_off + 4:pn_off + 20]))
+    pkt[0] ^= m[0] & 0x0f
+    for k in range(pn_len): pkt[pn_off + k] ^= m[1 + k]
+    return bytes(pkt)
+
+def protect_short(keys, dcid, pn, payload, pn_len=4, key_phase=0):
+    first = 0x40 | (key_phase << 2) | (pn_len - 1)
+    hdr = bytes([first]) + dcid
+    pn_off = len(hdr)
+    hdr += (pn & ((1 << (8 * pn_len)) - 1)).to_bytes(pn_len, "big")
+    ct = keys.aead.encrypt(keys.nonce(pn), payload, hdr)
+    pkt = bytearray(hdr + ct)
+    m = keys.mask(bytes(pkt[pn_off + 4:pn_off + 20]))
+    pkt[0] ^= m[0] & 0x1f
+    for k in range(pn_len): pkt[pn_off + k] ^= m[1 + k]
+    return bytes(pkt)
+
+def unprotect(keys, pkt, pn_off, long_hdr, end, largest=0):
+    """Remove protection of the packet pkt[0:end] whose pn starts at pn_off."""
+    pkt = bytearray(pkt[:end])
+    m = keys.mask(bytes(pkt[pn_off + 4:pn_off + 20]))
+    pkt[0] ^= m[0] & (0x0f if long_hdr else 0x1f)
+    pn_len = (pkt[0] & 3) + 1
+    pn = 0
+    for k in range(pn_len):
+        pkt[pn_off + k] ^= m[1 + k]; pn = (pn << 8) | pkt[pn_off + k]
+    # pn reconstruction (RFC 9000 A.3)
+    win = 1 << (8 * pn_len); exp = largest + 1
+    cand = (exp & ~(win - 1)) | pn
+    if cand <= exp - win // 2 and cand < (1 << 62) - win: cand += win
+    elif cand > exp + win // 2 and cand >= win: cand -= win
+    hdr = bytes(pkt[:pn_off + pn_len])
+    pt = keys.aead.decrypt(keys.nonce(cand), bytes(pkt[pn_off + pn_len:]), hdr)
+    return cand, pt, pkt[0]
+
+if __name__ == "__main__":
+    # RFC 9001 appendix A.1
+    c, s = initial_keys(bytes.fromhex("8394c8f03e515708"))
+    assert c.key.hex() == "1f369613dd76d5467730efcbe3b1a22d", c.key.hex()
+    assert c.iv.hex() == "fa044b2f42a3fd3b46fb255c"
+    assert c.hp.hex() == "9f50449e04a0e810283a1e9933adedd2"
+    assert s.key.hex() == "cf3a5331653c364c88f0f379b6067e37"
+    assert s.hp.hex() == "c206b8d9b9f0f37644430b490eeaa314"
+    # A.5 ChaCha is not used; A.2 client initial header protection check
+    print("RFC 9001 A.1 vectors OK")