|
| 1 | +#!/usr/bin/env python3 |
| 2 | +""" |
| 3 | +Tessera v0 clean-room decoder (round 2 -- full recovery). |
| 4 | +
|
| 5 | +Built from spec.md + captured wire data ONLY (no reference to any existing |
| 6 | +implementation). See report.md for the compliance statement and gap list. |
| 7 | +
|
| 8 | +Pipeline: |
| 9 | + 1. Parse every datagram header (long-header handshake vs short-header data). |
| 10 | + 2. Skip F_INITIAL (top flag bit) datagrams as parse-only. |
| 11 | + 3. Derive per-direction packet keys from sessionKey per the amended spec's |
| 12 | + "Packet protection (v0)" section, remove header protection, open the |
| 13 | + ChaCha20-Poly1305 AEAD. |
| 14 | + 4. Parse frames; reassemble Msg fragments into application messages. |
| 15 | + 5. Print a census and compare against ground-truth.json (PASS/FAIL + verdict). |
| 16 | +""" |
| 17 | +import json, os |
| 18 | + |
| 19 | +from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305 |
| 20 | +from cryptography.hazmat.primitives.ciphers import Cipher, algorithms |
| 21 | +from cryptography.hazmat.primitives.kdf.hkdf import HKDFExpand |
| 22 | +from cryptography.hazmat.primitives.hashes import SHA256 |
| 23 | +from cryptography.hazmat.primitives.hmac import HMAC |
| 24 | + |
| 25 | +HERE = os.path.dirname(os.path.abspath(__file__)) |
| 26 | + |
| 27 | +F_INITIAL = 0x80 |
| 28 | +PN_OFFSET = 5 # flags(1) + shortConnId(4) |
| 29 | +SAMPLE_OFF = PN_OFFSET + 4 # sample assumes max pnLen 4 |
| 30 | +HP_FLAG_MASK = 0x63 # pnLen bits (5-6) + key-phase bits (0-1) |
| 31 | + |
| 32 | +FRAME_NAMES = { |
| 33 | + 0x02: "Ack", 0x03: "Grant", 0x04: "Repair", 0x05: "PathChallenge", |
| 34 | + 0x06: "Ping", 0x07: "PathResponse", 0x08: "Close", 0x09: "MaxData", |
| 35 | + 0x0A: "AckFrequency", 0x80: "Msg", 0x81: "Padding", |
| 36 | +} |
| 37 | + |
| 38 | +# -------------------------------------------------------------------------- |
| 39 | +# Key schedule (amended spec, "Packet protection (v0)") |
| 40 | +# HKDF = extract-then-expand, absent (zero) salt, ASCII label as expand info. |
| 41 | +# -------------------------------------------------------------------------- |
| 42 | +def hkdf(key, label, length): |
| 43 | + prk = HMAC(b"\x00" * 32, SHA256()) |
| 44 | + prk.update(key) |
| 45 | + return HKDFExpand(SHA256(), length, label.encode()).derive(prk.finalize()) |
| 46 | + |
| 47 | +def direction_keys(secret): |
| 48 | + return { |
| 49 | + "key": hkdf(secret, "tessera pkt key", 32), |
| 50 | + "iv": hkdf(secret, "tessera pkt iv", 12), |
| 51 | + "hp": hkdf(secret, "tessera hp", 32), |
| 52 | + } |
| 53 | + |
| 54 | +def hp_mask(hp_key, sample): |
| 55 | + enc = Cipher(algorithms.ChaCha20(hp_key, sample[:16]), mode=None).encryptor() |
| 56 | + return enc.update(b"\x00" * 5) |
| 57 | + |
| 58 | +# -------------------------------------------------------------------------- |
| 59 | +# QUIC-style truncated packet-number reconstruction (spec: "closest to |
| 60 | +# largestSeen+1 among candidates congruent to the truncation"). |
| 61 | +# -------------------------------------------------------------------------- |
| 62 | +def reconstruct_pn(truncated, pnlen, largest_seen): |
| 63 | + if largest_seen < 0: |
| 64 | + return truncated |
| 65 | + win = 1 << (8 * pnlen) |
| 66 | + base = (largest_seen + 1) & ~(win - 1) |
| 67 | + cand = base | truncated |
| 68 | + best = cand |
| 69 | + for c in (cand - win, cand, cand + win): |
| 70 | + if c >= 0 and abs(c - (largest_seen + 1)) < abs(best - (largest_seen + 1)): |
| 71 | + best = c |
| 72 | + return best |
| 73 | + |
| 74 | +def open_packet(raw, keys, largest): |
| 75 | + """Return (plaintext, pn, flags, pnlen) or raise on AEAD failure.""" |
| 76 | + b = bytearray(raw) |
| 77 | + mask = hp_mask(keys["hp"], bytes(b[SAMPLE_OFF:SAMPLE_OFF + 16])) |
| 78 | + flags = b[0] ^ (mask[0] & HP_FLAG_MASK) |
| 79 | + pnlen = ((flags >> 5) & 0x03) + 1 |
| 80 | + pn_bytes = bytearray(b[PN_OFFSET:PN_OFFSET + pnlen]) |
| 81 | + for i in range(pnlen): |
| 82 | + pn_bytes[i] ^= mask[1 + i] |
| 83 | + pn = reconstruct_pn(int.from_bytes(pn_bytes, "big"), pnlen, largest) |
| 84 | + |
| 85 | + nonce = bytearray(keys["iv"]) # nonce = iv, low 8 bytes XOR pn (BE) |
| 86 | + pnb = pn.to_bytes(8, "big") |
| 87 | + for i in range(8): |
| 88 | + nonce[4 + i] ^= pnb[i] |
| 89 | + aad = bytes([flags]) + bytes(b[1:PN_OFFSET]) + bytes(pn_bytes) # pre-HP header |
| 90 | + ct = bytes(b[PN_OFFSET + pnlen:]) |
| 91 | + pt = ChaCha20Poly1305(keys["key"]).decrypt(bytes(nonce), ct, aad) |
| 92 | + return pt, pn, flags, pnlen |
| 93 | + |
| 94 | +# -------------------------------------------------------------------------- |
| 95 | +# Frame / Msg decoding |
| 96 | +# -------------------------------------------------------------------------- |
| 97 | +def read_varint(buf, i): |
| 98 | + prefix = buf[i] >> 6 |
| 99 | + ln = 1 << prefix |
| 100 | + val = buf[i] & 0x3f |
| 101 | + for k in range(1, ln): |
| 102 | + val = (val << 8) | buf[i + k] |
| 103 | + return val, i + ln |
| 104 | + |
| 105 | +def parse_msg_frame(pt): |
| 106 | + """ |
| 107 | + Empirically decoded Msg frame (spec's compact Msg; the byte layout is not |
| 108 | + in the spec -- see gap R2-1): |
| 109 | + 0x80 0x02 fragSeq(2, BE) flags(1) msgId(1) [offset(varint) if flags&0x04] |
| 110 | + data...(implied length = to end of packet; Msg is the sole/first frame) |
| 111 | + flags bits: 0x10 base, 0x02 = FIN, 0x04 = OFFSET present. |
| 112 | + """ |
| 113 | + flags = pt[4] |
| 114 | + msg_id = pt[5] |
| 115 | + i = 6 |
| 116 | + offset = None |
| 117 | + if flags & 0x04: |
| 118 | + offset, i = read_varint(pt, i) |
| 119 | + fin = bool(flags & 0x02) |
| 120 | + return msg_id, flags, offset, fin, pt[i:] |
| 121 | + |
| 122 | +# -------------------------------------------------------------------------- |
| 123 | +def main(): |
| 124 | + ds = [json.loads(l) for l in open(os.path.join(HERE, "datagrams.jsonl"))] |
| 125 | + meta = json.load(open(os.path.join(HERE, "meta.json"))) |
| 126 | + gt = json.load(open(os.path.join(HERE, "ground-truth.json"))) |
| 127 | + session_key = bytes.fromhex(meta["sessionKeyHex"]) |
| 128 | + |
| 129 | + keys = { |
| 130 | + "c2s": direction_keys(hkdf(session_key, "tessera-v0.3 c2s", 32)), |
| 131 | + "s2c": direction_keys(hkdf(session_key, "tessera-v0.3 s2c", 32)), |
| 132 | + } |
| 133 | + |
| 134 | + census = {"c2s": 0, "s2c": 0} |
| 135 | + handshake = decrypted = failed = 0 |
| 136 | + frame_counts = {} |
| 137 | + largest = {"c2s": -1, "s2c": -1} |
| 138 | + reasm = {"c2s": {}, "s2c": {}} |
| 139 | + |
| 140 | + for d in ds: |
| 141 | + census[d["dir"]] += 1 |
| 142 | + raw = bytes.fromhex(d["hex"]) |
| 143 | + if raw[0] & F_INITIAL: |
| 144 | + handshake += 1 |
| 145 | + continue |
| 146 | + try: |
| 147 | + pt, pn, flags, pnlen = open_packet(raw, keys[d["dir"]], largest[d["dir"]]) |
| 148 | + except Exception: |
| 149 | + failed += 1 |
| 150 | + continue |
| 151 | + decrypted += 1 |
| 152 | + if pn > largest[d["dir"]]: |
| 153 | + largest[d["dir"]] = pn |
| 154 | + |
| 155 | + # A data packet begins with a Msg frame (0x80 0x02); other packets carry |
| 156 | + # Ack/Grant/Repair/etc. We count the leading frame type for the census |
| 157 | + # and only reassemble from true Msg frames (never from Repair copies). |
| 158 | + ftype = pt[0] if pt else None |
| 159 | + if ftype == 0x80 and len(pt) >= 2 and pt[1] == 0x02: |
| 160 | + name = "Msg" |
| 161 | + else: |
| 162 | + name = FRAME_NAMES.get(ftype, f"0x{ftype:02x}" if ftype is not None else "empty") |
| 163 | + frame_counts[name] = frame_counts.get(name, 0) + 1 |
| 164 | + |
| 165 | + if name == "Msg": |
| 166 | + mid, mflags, off, fin, data = parse_msg_frame(pt) |
| 167 | + R = reasm[d["dir"]].setdefault(mid, {"buf": bytearray(), "fin": False}) |
| 168 | + o = off if off is not None else len(R["buf"]) |
| 169 | + if o + len(data) > len(R["buf"]): |
| 170 | + R["buf"].extend(b"\x00" * (o + len(data) - len(R["buf"]))) |
| 171 | + R["buf"][o:o + len(data)] = data |
| 172 | + if fin: |
| 173 | + R["fin"] = True |
| 174 | + |
| 175 | + # Direction -> ground-truth index. Client msgId 0 was the 0-RTT payload |
| 176 | + # (carried in the parse-only initial), so post-handshake c2s msgIds are |
| 177 | + # 1-based; the server sent no 0-RTT, so s2c msgIds are 0-based. |
| 178 | + base = {"c2s": 1, "s2c": 0} |
| 179 | + |
| 180 | + def recovered(dirk, count): |
| 181 | + out = [] |
| 182 | + for idx in range(count): |
| 183 | + R = reasm[dirk].get(idx + base[dirk]) |
| 184 | + out.append(bytes(R["buf"]).hex() if R else None) |
| 185 | + return out |
| 186 | + |
| 187 | + rec = {"c2s": recovered("c2s", len(gt["clientToServer"])), |
| 188 | + "s2c": recovered("s2c", len(gt["serverToClient"]))} |
| 189 | + |
| 190 | + # ---- census ---- |
| 191 | + print("=" * 60) |
| 192 | + print("TESSERA CLEAN-ROOM DECODER -- CENSUS") |
| 193 | + print("=" * 60) |
| 194 | + print(f"datagrams: total={len(ds)} c2s={census['c2s']} s2c={census['s2c']}") |
| 195 | + print(f"handshake (F_INITIAL, parse-only): {handshake}") |
| 196 | + print(f"packets decrypted: {decrypted} failed: {failed}") |
| 197 | + print("leading-frame counts by type:") |
| 198 | + for k, v in sorted(frame_counts.items()): |
| 199 | + print(f" {k}: {v}") |
| 200 | + print("\nRecovered application messages (in order, hex):") |
| 201 | + for dirk in ("c2s", "s2c"): |
| 202 | + print(f" {dirk}: {sum(x is not None for x in rec[dirk])} message(s)") |
| 203 | + for h in rec[dirk]: |
| 204 | + shown = h if h and len(h) <= 64 else (h[:64] + "..." if h else "(missing)") |
| 205 | + print(" " + shown) |
| 206 | + |
| 207 | + # ---- verdict ---- |
| 208 | + print("\n" + "=" * 60) |
| 209 | + print("VERDICT vs ground-truth.json") |
| 210 | + print("=" * 60) |
| 211 | + total = passed = 0 |
| 212 | + for dirk, truth in (("c2s", gt["clientToServer"]), ("s2c", gt["serverToClient"])): |
| 213 | + for idx, exp in enumerate(truth): |
| 214 | + total += 1 |
| 215 | + got = rec[dirk][idx] |
| 216 | + ok = (got == exp) |
| 217 | + passed += ok |
| 218 | + if not ok: |
| 219 | + print(f" {dirk}[{idx:02d}] FAIL " |
| 220 | + f"(expected {len(exp)//2}B, got " |
| 221 | + f"{'-' if got is None else str(len(got)//2)+'B'})") |
| 222 | + print(f"\n {passed}/{total} messages byte-exact") |
| 223 | + print(f" OVERALL: {'PASS' if passed == total else 'FAIL'}") |
| 224 | + |
| 225 | + |
| 226 | +if __name__ == "__main__": |
| 227 | + main() |
0 commit comments