From d2264021e06681b5531ba8ab2d966c9c0b511b57 Mon Sep 17 00:00:00 2001 From: JC-000 <3798556+JC-000@users.noreply.github.com> Date: Sat, 17 Oct 2026 17:42:00 -0500 Subject: [PATCH 1/4] PQ P5: hybrid key schedule (mlkem_ss || x25519_ss), secret zeroing, oracle on app traffic secrets, tests and mutants Co-Authored-By: Claude Sonnet 5.5 --- src/crypto/pq_hybrid.s | 6 +- src/tls_keyschedule.s | 45 ++++++++++++ tools/mutate_pq_sh.py | 33 ++++++++- tools/pq_keylog_check.py | 108 +++++++++++++++++----------- tools/run_all_tests.py | 1 + tools/test_pq_kem.py | 26 +++++-- tools/test_pq_keylog_check.py | 52 ++++++++++---- tools/test_pq_keyschedule.py | 130 ++++++++++++++++++++++++++++++++++ tools/uci/rig_https_local.py | 9 ++- 9 files changed, 343 insertions(+), 67 deletions(-) create mode 100644 tools/test_pq_keyschedule.py diff --git a/src/crypto/pq_hybrid.s b/src/crypto/pq_hybrid.s index 5a453ad..ca11063 100644 --- a/src/crypto/pq_hybrid.s +++ b/src/crypto/pq_hybrid.s @@ -229,11 +229,9 @@ pq_sh_decaps: bne @done jsr pq_set_args jsr pq_mlkem_decaps_seed ; A = status; C=1/A=$FF refused - php pha - jsr pq_mlkem_scrub ; y/e1/e2 in $D000, m'/K'/r' in the window, any outcome - pla - plp + jsr pq_mlkem_scrub ; y/e1/e2 in $D000, m'/K'/r' in the window, any outcome (preserves C) + pla ; pla leaves C alone bcs @fail cmp #0 bne @fail diff --git a/src/tls_keyschedule.s b/src/tls_keyschedule.s index 72d4814..7fe14ea 100644 --- a/src/tls_keyschedule.s +++ b/src/tls_keyschedule.s @@ -44,6 +44,9 @@ ; TLS state / buffers (data.asm) .import tls_shared_secret +.ifdef PQ_HYBRID +.import tls_mlkem_ss, tls_kex_group +.endif .import tls_transcript .import tls_early_secret .import tls_handshake_secret @@ -172,8 +175,50 @@ tls_derive_handshake_keys: lda #32 sta hkdf_ikm_len +.ifdef PQ_HYBRID + ; X25519MLKEM768 (draft-ietf-tls-ecdhe-mlkem): the shared secret is + ; mlkem_ss || x25519_ss (ML-KEM first), 64 B. Concatenate into + ; input_buffer (dead scratch since step 1) and point the IKM at it. + lda tls_kex_group + cmp #$EC + bne @dhk_ikm_ready + ldx #31 +@dhk_cat: + lda tls_mlkem_ss,x + sta input_buffer,x + lda tls_shared_secret,x + sta input_buffer+32,x + dex + bpl @dhk_cat + lda #input_buffer + sta hkdf_ikm_ptr+1 + lda #64 + sta hkdf_ikm_len +@dhk_ikm_ready: +.endif + jsr hkdf_extract +.ifdef PQ_HYBRID + ; Both shared secrets (and the concatenation and hkdf_extract's copy + ; of it in hmac_data_buf) are dead once the handshake secret exists. + lda #0 + ldx #63 +@dhk_zero: + sta input_buffer,x + sta hmac_data_buf,x + dex + bpl @dhk_zero + ldx #31 +@dhk_zss: + sta tls_shared_secret,x + sta tls_mlkem_ss,x + dex + bpl @dhk_zss +.endif + ; Copy hkdf_prk → tls_handshake_secret ldx #31 @dhk_c3: diff --git a/tools/mutate_pq_sh.py b/tools/mutate_pq_sh.py index b07cb4a..ad57887 100644 --- a/tools/mutate_pq_sh.py +++ b/tools/mutate_pq_sh.py @@ -38,6 +38,8 @@ SH3 = ["tools/test_pq_sh.py", "3"] SH4 = ["tools/test_pq_sh.py", "4"] KEM = ["tools/test_pq_kem.py"] +KS = ["tools/test_pq_keyschedule.py"] +KSF = "src/tls_keyschedule.s" SCRUB_BODY = """pq_mlkem_scrub: @@ -192,7 +194,7 @@ def nop(n): ("M48", "pq_sh_init does not reset tls_kex_group", H, " sta shs_seen\n sta tls_kex_group\n", " sta shs_seen\n" + nop(3), SH3), ("M49", "Decaps leaves y/e1/e2 and m'/K'/r' behind", H, - " jsr pq_mlkem_scrub ; y/e1/e2 in $D000, m'/K'/r' in the window, any outcome\n", nop(3), KEM + ["decaps"]), + " jsr pq_mlkem_scrub ; y/e1/e2 in $D000, m'/K'/r' in the window, any outcome (preserves C)\n", nop(3), KEM + ["decaps"]), ("M50", "KeyGen leaves s_hat behind", H, " jsr pq_mlkem_scrub ; s_hat in $D000 and the sponge/ring residue in the window\n", nop(3), KEM + ["prep"]), ("M51", "the scrub misses the last polynomial page", "src/crypto/mlkem_link.s", @@ -223,6 +225,33 @@ def nop(n): ("M56", "the SH loop ignores the ERROR latch", T13, " bpl :+ ; record header while waiting for the SH\n", " jmp :+\n", KEM + ["oversize"]), + # --- P5: the hybrid key schedule (suite: tools/test_pq_keyschedule.py) --- + ("K01", "wrong IKM order: x25519_ss || mlkem_ss", KSF, + " lda tls_mlkem_ss,x\n sta input_buffer,x\n lda tls_shared_secret,x\n sta input_buffer+32,x\n", + " lda tls_mlkem_ss,x\n sta input_buffer+32,x\n lda tls_shared_secret,x\n sta input_buffer,x\n", KS), + ("K02", "IKM length 32 instead of 64", KSF, + " lda #64\n sta hkdf_ikm_len\n", " lda #32\n sta hkdf_ikm_len\n", KS), + ("K03", "group test inverted (hybrid only for a non-11EC group)", KSF, + " cmp #$EC\n bne @dhk_ikm_ready\n", " cmp #$EC\n beq @dhk_ikm_ready\n", KS), + ("K04", "group test compares 001D instead of 11EC", KSF, + " cmp #$EC\n bne @dhk_ikm_ready\n", " cmp #$1D\n bne @dhk_ikm_ready\n", KS), + ("K05", "the hybrid IKM is never selected (always classic)", KSF, + " cmp #$EC\n bne @dhk_ikm_ready\n", " cmp #$EC\n jmp @dhk_ikm_ready\n", KS), + ("K06", "the IKM pointer still names tls_shared_secret", KSF, + " lda #input_buffer\n sta hkdf_ikm_ptr+1\n lda #64\n", + " lda #64\n", KS), + ("K07", "the concatenation stops one byte short", KSF, + " ldx #31\n@dhk_cat:", " ldx #30\n@dhk_cat:", KS), + ("K08", "the x25519 ss is not zeroed after the extract", KSF, + "@dhk_zss:\n sta tls_shared_secret,x\n", "@dhk_zss:\n" + nop(3), KS), + ("K09", "tls_mlkem_ss is not zeroed after the extract", KSF, + " sta tls_mlkem_ss,x\n dex\n bpl @dhk_zss\n", nop(3) + " dex\n bpl @dhk_zss\n", KS), + ("K10", "the IKM concatenation in input_buffer is not zeroed", KSF, + "@dhk_zero:\n sta input_buffer,x\n", "@dhk_zero:\n" + nop(3), KS), + ("K11", "hkdf_extract's copy of the IKM (hmac_data_buf) is not zeroed", KSF, + " sta hmac_data_buf,x\n dex\n bpl @dhk_zero\n", nop(3) + " dex\n bpl @dhk_zero\n", KS), + ("K12", "the IKM zeroing covers only 32 of the 64 bytes", KSF, + " lda #0\n ldx #63\n@dhk_zero:", " lda #0\n ldx #31\n@dhk_zero:", KS), ] @@ -255,7 +284,7 @@ def main(): if "--no-control" not in sys.argv: # A mutant "killed" by a suite that is red on the unmodified tree # proves nothing: the controls go first. - for c in (SH, KEM): + for c in (SH, KEM, KS): crc, cout = run(c, env={"C64_FAIL_FAST": "0"}) print(f"control {' '.join(c)}: rc={crc}", flush=True) if crc: diff --git a/tools/pq_keylog_check.py b/tools/pq_keylog_check.py index c335e3f..83868fc 100644 --- a/tools/pq_keylog_check.py +++ b/tools/pq_keylog_check.py @@ -1,16 +1,17 @@ #!/usr/bin/env python3 """pq_keylog_check.py - did the C64's Decaps agree with the server's Encaps? -The oracle for the X25519MLKEM768 hardware rig (PQC phase P4). OpenSSL's -`s_server -keylogfile` writes the handshake traffic secrets it derived: +The oracle for the X25519MLKEM768 hardware rig (PQC phases P4/P5). OpenSSL's +`s_server -keylogfile` writes the traffic secrets it derived: SERVER_HANDSHAKE_TRAFFIC_SECRET CLIENT_HANDSHAKE_TRAFFIC_SECRET -The C64 (P4) does not run the hybrid key schedule yet, so it cannot read the -first encrypted record - but its Decaps output, its X25519 shared secret and -its transcript hash are in RAM. This tool runs the RFC 8446 section 7.1 -schedule on them OFFLINE (hashlib/hmac only) with the hybrid input +--state (P5, the rig mode): the C64 runs the hybrid key schedule and zeroes both +shared secrets, so the verdict compares its application traffic secrets with +the keylog's CLIENT/SERVER_TRAFFIC_SECRET_0, gated on tls_reached_connected. +The explicit mode below (P4) takes the secrets as arguments: it runs the +RFC 8446 section 7.1 schedule on them OFFLINE (hashlib/hmac only) with the hybrid input IKM = mlkem_ss || x25519_ss (draft-ietf-tls-ecdhe-mlkem: ML-KEM first) @@ -26,6 +27,7 @@ Exit 0: both secrets match. 1: mismatch (it also says if the OTHER ikm order, x25519 || mlkem, would have matched). 2: usage / missing keylog line. 78: --state mode and the run did not reach the point (the sentinel gate). +In --state mode exit 1 is also a RESIDUE failure (a hybrid secret left in RAM). """ import argparse @@ -93,29 +95,44 @@ def check(keylog_text, client_random, mlkem_ss, x25519_ss, transcript): def check_state(state, keylog_text): - """*state* is tools/uci/rig_https_local.py's PQ_DUMP pq_state.json. - Returns (verdict, message): True / False as check(); None = a usage - problem; "inconclusive" when the run provably did not reach the point - whose memory is being quoted (the sentinel gate: a run that stopped - earlier leaves plausible-looking bytes in uninitialised memory).""" + """*state* is tools/uci/rig_https_local.py's PQ_DUMP pq_state.json (P5). + Returns (verdict, message): True / False; None = a usage problem; + "inconclusive" when the run provably did not reach the point whose memory + is being quoted (the sentinel gate: a run that stopped earlier leaves + plausible-looking bytes in uninitialised memory). + + Since P5 the C64 zeroes both shared secrets once the handshake secret is + extracted, so the secrets themselves are no longer there to compare. What + stays is the APPLICATION traffic secrets (tls_c_hs_secret / tls_s_hs_secret + are reused for them): a pure function of the hybrid handshake secret and + the transcript through the server Finished, which OpenSSL logs as + CLIENT_TRAFFIC_SECRET_0 / SERVER_TRAFFIC_SECRET_0. Equal bytes prove the + C64's key schedule ran with the server's own mlkem_ss || x25519_ss. The + gate is the tls_reached_connected latch (#204), not tls_state, which is + IDLE again after tls_close.""" h = lambda k: bytes.fromhex(state[k]) # noqa: E731 if h("tls_kex_group") != b"\xec": - return "inconclusive", f"tls_kex_group=${state['tls_kex_group']}: the server did not choose 11EC, no ML-KEM secret to check" + return "inconclusive", f"tls_kex_group=${state['tls_kex_group']}: the server did not choose 11EC, no hybrid run to check" if h("tls_sh_err") != b"\x00": return "inconclusive", f"tls_sh_err=${state['tls_sh_err']}: the ServerHello was refused" - # A failed run ends in ERROR ($FF) with tls_last_state = the state it failed - # in; only a run still in a normal state is judged by tls_state itself. - reached = h("tls_last_state")[0] if h("tls_state")[0] == 0xFF else h("tls_state")[0] - if reached < 3: - return "inconclusive", (f"the run never got past ServerHello (reached state {reached}: " - f"tls_state=${state['tls_state']}, last_state=${state['tls_last_state']})") - if h("tls_pq_seed") != bytes(64): - return "inconclusive", "tls_pq_seed is not zero: Decaps did not finish and scrub (or the error exit did not run)" - for k in ("tls_mlkem_ss", "tls_shared_secret", "tls_transcript"): - if h(k) == bytes(len(h(k))): + if h("tls_reached_connected") != b"\x07": + return "inconclusive", (f"tls_reached_connected=${state['tls_reached_connected']}: the handshake never " + f"completed (tls_state=${state['tls_state']}, last_state=${state['tls_last_state']})") + for k in ("tls_c_hs_secret", "tls_s_hs_secret"): + if h(k) == bytes(32): return "inconclusive", f"{k} is all zero: not produced" - return check(keylog_text, h("tls_client_random"), h("tls_mlkem_ss"), - h("tls_shared_secret"), h("tls_transcript")) + # Hygiene first: a connected run must have scrubbed every hybrid secret. + for k in ("tls_pq_seed", "tls_mlkem_ss", "tls_shared_secret"): + if h(k) != bytes(len(h(k))): + return False, f"RESIDUE: {k} is not zero after the handshake secret was extracted" + log = parse_keylog(keylog_text, h("tls_client_random").hex()) + need = ("CLIENT_TRAFFIC_SECRET_0", "SERVER_TRAFFIC_SECRET_0") + for n in need: + if n not in log: + return None, f"keylog has no {n} for client_random {state['tls_client_random']}" + if log[need[0]] == h("tls_c_hs_secret") and log[need[1]] == h("tls_s_hs_secret"): + return True, "match: the C64's application traffic secrets equal the server's CLIENT/SERVER_TRAFFIC_SECRET_0 (hybrid key schedule agreed)" + return False, "MISMATCH: the C64's application traffic secrets differ from the server's (key schedule, secret or transcript disagree)" def selftest(): @@ -166,27 +183,38 @@ def expect(cond, what): expect(r is False and "did not run the hybrid" in m, "red: a classic-only server is named") r, m = check(log, bytes(31) + b"\x01", mk, xs, th) expect(r is None, "a keylog without the client_random's lines is a usage error, not a pass") - # --- state-file mode and its sentinel gate --- - good = {"tls_mlkem_ss": mk.hex(), "tls_shared_secret": xs.hex(), - "tls_transcript": th.hex(), "tls_client_random": rnd.hex(), - "tls_kex_group": "ec", "tls_sh_err": "00", "tls_state": "ff", - "tls_last_state": "03", "tls_pq_seed": "00" * 64} - r, m = check_state(good, log) - expect(r is True, "state mode: a run that reached the point matches") + # --- state-file mode (P5): application traffic secrets + sentinel gate --- + ca, sa = bytes(range(1, 33)), bytes(range(50, 82)) + log3 = log + (f"CLIENT_TRAFFIC_SECRET_0 {rnd.hex()} {ca.hex()}\n" + f"SERVER_TRAFFIC_SECRET_0 {rnd.hex()} {sa.hex()}\n") + good = {"tls_c_hs_secret": ca.hex(), "tls_s_hs_secret": sa.hex(), + "tls_client_random": rnd.hex(), "tls_kex_group": "ec", "tls_sh_err": "00", + "tls_state": "00", "tls_last_state": "00", "tls_reached_connected": "07", + "tls_pq_seed": "00" * 64, "tls_mlkem_ss": "00" * 32, "tls_shared_secret": "00" * 32} + r, m = check_state(good, log3) + expect(r is True, "state mode: a CONNECTED-then-closed run (tls_state=0) matches") for key, val, why in (("tls_kex_group", "1d", "11EC"), ("tls_sh_err", "07", "refused"), - ("tls_last_state", "02", "past ServerHello, failed run (ERROR, last_state 2)"), - ("tls_last_state", "01", "past ServerHello, failed run (ERROR, last_state 1)"), - ("tls_pq_seed", "11" * 64, "seed"), - ("tls_mlkem_ss", "00" * 32, "all zero")): + ("tls_reached_connected", "00", "never connected"), + ("tls_reached_connected", "03", "stopped at ServerHello"), + ("tls_c_hs_secret", "00" * 32, "client secret all zero"), + ("tls_s_hs_secret", "00" * 32, "server secret all zero")): bad = dict(good) bad[key] = val - r, m = check_state(bad, log) + r, m = check_state(bad, log3) expect(r == "inconclusive", f"state mode: gate ({why}) -> inconclusive, not a verdict") - bad = dict(good) - bad["tls_mlkem_ss"] = bytes(range(32)).hex() - r, m = check_state(bad, log) - expect(r is False, "state mode: a wrong ML-KEM secret is a mismatch") + for key in ("tls_pq_seed", "tls_mlkem_ss", "tls_shared_secret"): + bad = dict(good) + bad[key] = "11" * len(bytes.fromhex(good[key])) + r, m = check_state(bad, log3) + expect(r is False and "RESIDUE" in m, f"state mode: {key} left non-zero is a RESIDUE failure") + for key in ("tls_c_hs_secret", "tls_s_hs_secret"): + bad = dict(good) + bad[key] = bytes(range(9, 41)).hex() + r, m = check_state(bad, log3) + expect(r is False, f"state mode: a wrong {key} is a mismatch") + r, m = check_state(good, log) + expect(r is None, "state mode: a keylog without the traffic-secret lines is a usage error") print("SELFTEST " + ("PASS" if ok else "FAIL")) return 0 if ok else 1 diff --git a/tools/run_all_tests.py b/tools/run_all_tests.py index 71d3f1d..9581e64 100644 --- a/tools/run_all_tests.py +++ b/tools/run_all_tests.py @@ -75,6 +75,7 @@ # tools/test_mlkem_linked.py the image runs: copy, KeyGen, Decaps (#313) # tools/test_pq_sh.py the streaming ServerHello reader (P4) # tools/test_pq_kem.py KeyGen / CH / Decaps / tls_connect (P4) +# tools/test_pq_keyschedule.py hybrid IKM mlkem_ss || x25519_ss + zeroing (P5) # tools/mutate_pq_sh.py breaks each P4 check, expects red (P4) # tools/test_pq_keylog_check.py the hardware oracle (pytest, no VICE) diff --git a/tools/test_pq_kem.py b/tools/test_pq_kem.py index b182171..49456ce 100644 --- a/tools/test_pq_kem.py +++ b/tools/test_pq_kem.py @@ -274,6 +274,19 @@ def run_connect(s, t, tag, kind): == len(ref) + len(msg), "transcript has folded exactly CH + SH (byte count)") delete_breakpoint(s.tr, bp_ecdh) + # P5: stop at the key schedule. Both secrets are final there and the + # schedule is about to consume them; afterwards they are zero. + bp_dk = set_breakpoint(s.tr, L("tls_derive_handshake_keys")) + s.tr.resume() + wait_for_pc(s.tr, L("tls_derive_handshake_keys"), timeout=7200.0) + ss_x = s.rd(L("tls_shared_secret"), 32) + t.check(ss_x == x25519(priv, spub), "at the key schedule the X25519 shared secret is correct (after Decaps rebuilt the window)") + t.check(s.rd(L("tls_mlkem_ss"), 32) == (K if kind == "hyb" else bytes(32)), + "...and the ML-KEM secret is the reference K (zero on the classic path)") + th = hashlib.sha256(ref + msg).digest() + t.check(s.rd(L("tls_transcript"), 32) == th, "tls_transcript = SHA-256(CH || SH) as the host computes it") + ikm = (K + ss_x) if kind == "hyb" else ss_x + delete_breakpoint(s.tr, bp_dk) s.tr.resume() wait_for_pc(s.tr, end, timeout=7200.0) finally: @@ -284,18 +297,19 @@ def run_connect(s, t, tag, kind): pass write_bytes(s.tr, L("net_tcp_send"), orig) carry = s.rd(CARRY, 1)[0] - ss_x = s.rd(L("tls_shared_secret"), 32) - t.check(ss_x == x25519(priv, spub), "the X25519 shared secret is correct (after Decaps rebuilt the window)") t.check(s.rd(L("tls_server_pubkey"), 32) == spub, "the server's x25519 share was extracted") t.check(s.group() == (0xEC if kind == "hyb" else 0x1D), "tls_kex_group recorded") t.check(s.rd(L("tls_last_state"), 1)[0] == 3 and carry == 1, "the run got past ServerHello and failed at EncryptedExtensions (tls_last_state = 3, C=1)", f"last_state={s.rd(L('tls_last_state'), 1)[0]} carry={carry}") - t.check(carry == 1, "P4 state: the handshake does not complete (key schedule not hybrid yet / no server)") + t.check(carry == 1, "no server behind the fake network: the handshake stops at EncryptedExtensions") t.check(s.rd(L("tls_pq_seed"), 64) == bytes(64), "after tls_connect's error exit the seed is zero") - ss_end = s.rd(L("tls_mlkem_ss"), 32) - t.check(ss_end == (K if kind == "hyb" else bytes(32)), - "...and the ML-KEM secret is still there for the oracle/P5 (scrubbed by 'Q')") + t.check(s.rd(L("tls_mlkem_ss"), 32) == bytes(32) and s.rd(L("tls_shared_secret"), 32) == bytes(32), + "after the key schedule both shared secrets are zero (P5)") + # the handshake secret the C64 derived is the host's, for the IKM the group implies + from test_pq_keyschedule import host_schedule + t.check(s.rd(L("tls_handshake_secret"), 32) == host_schedule(ikm, th)[0], + "tls_handshake_secret == host HKDF over " + ("mlkem_ss || x25519_ss" if kind == "hyb" else "x25519_ss")) return K diff --git a/tools/test_pq_keylog_check.py b/tools/test_pq_keylog_check.py index dfc152e..0056a09 100644 --- a/tools/test_pq_keylog_check.py +++ b/tools/test_pq_keylog_check.py @@ -34,11 +34,19 @@ def _log(ikm=MK + XS, th=TH, rnd=RND): f"CLIENT_HANDSHAKE_TRAFFIC_SECRET {rnd.hex()} {c.hex()}\n") +CA, SA = bytes(range(1, 33)), bytes(range(50, 82)) + + +def _log3(): + return _log() + (f"CLIENT_TRAFFIC_SECRET_0 {RND.hex()} {CA.hex()}\n" + f"SERVER_TRAFFIC_SECRET_0 {RND.hex()} {SA.hex()}\n") + + def _state(**over): - st = {"tls_mlkem_ss": MK.hex(), "tls_shared_secret": XS.hex(), - "tls_transcript": TH.hex(), "tls_client_random": RND.hex(), - "tls_kex_group": "ec", "tls_sh_err": "00", "tls_state": "ff", - "tls_last_state": "03", "tls_pq_seed": "00" * 64} + st = {"tls_c_hs_secret": CA.hex(), "tls_s_hs_secret": SA.hex(), + "tls_client_random": RND.hex(), "tls_kex_group": "ec", "tls_sh_err": "00", + "tls_state": "00", "tls_last_state": "00", "tls_reached_connected": "07", + "tls_pq_seed": "00" * 64, "tls_mlkem_ss": "00" * 32, "tls_shared_secret": "00" * 32} st.update(over) return st @@ -81,19 +89,37 @@ def test_a_keylog_without_the_run_is_a_usage_error(): assert K.check(_log(), bytes(31) + b"\x01", MK, XS, TH)[0] is None -def test_state_mode_green_and_red(): - assert K.check_state(_state(), _log())[0] is True - assert K.check_state(_state(tls_mlkem_ss=bytes(range(32)).hex()), _log())[0] is False +def test_state_mode_green_for_a_connected_then_closed_run(): + # tls_state=00 / last_state=00 is what CONNECTED-then-tls_close looks like (#204) + assert K.check_state(_state(), _log3())[0] is True + + +def test_state_mode_red_on_either_secret(): + for k in ("tls_c_hs_secret", "tls_s_hs_secret"): + assert K.check_state(_state(**{k: bytes(range(9, 41)).hex()}), _log3())[0] is False + # swapped client/server secrets are also a mismatch + assert K.check_state(_state(tls_c_hs_secret=SA.hex(), tls_s_hs_secret=CA.hex()), + _log3())[0] is False + + +def test_state_mode_residue_is_a_failure_not_a_pass(): + for k, n in (("tls_pq_seed", 64), ("tls_mlkem_ss", 32), ("tls_shared_secret", 32)): + r, msg = K.check_state(_state(**{k: "11" * n}), _log3()) + assert r is False and "RESIDUE" in msg, k + + +def test_state_mode_log_without_traffic_secret_lines_is_a_usage_error(): + assert K.check_state(_state(), _log())[0] is None def test_the_sentinel_gate_never_gives_a_verdict_from_unreached_memory(): - cases = [dict(tls_kex_group="1d"), dict(tls_sh_err="07"), - dict(tls_last_state="02"), dict(tls_last_state="01"), - dict(tls_last_state="03", tls_state="02"), # not ERROR: judged by tls_state - dict(tls_pq_seed="11" * 64), dict(tls_mlkem_ss="00" * 32), - dict(tls_shared_secret="00" * 32), dict(tls_transcript="00" * 32)] + cases = [dict(tls_kex_group="1d"), dict(tls_kex_group="00"), dict(tls_sh_err="07"), + dict(tls_reached_connected="00"), dict(tls_reached_connected="03"), + dict(tls_c_hs_secret="00" * 32), dict(tls_s_hs_secret="00" * 32)] for over in cases: - assert K.check_state(_state(**over), _log())[0] == "inconclusive", over + assert K.check_state(_state(**over), _log3())[0] == "inconclusive", over + # tls_state / tls_last_state are NOT the gate: ERROR with a stale latch of 0 + assert K.check_state(_state(tls_state="ff", tls_last_state="06"), _log3())[0] is True def main() -> int: diff --git a/tools/test_pq_keyschedule.py b/tools/test_pq_keyschedule.py new file mode 100644 index 0000000..89db989 --- /dev/null +++ b/tools/test_pq_keyschedule.py @@ -0,0 +1,130 @@ +#!/usr/bin/env python3 +"""test_pq_keyschedule.py - the PQ_HYBRID hybrid key schedule (PQC phase P5). + +A VICE boot of the BACKEND=uci USE_NISTCURVES_ONCHIP=1 PQ_HYBRID=1 image. Each +case plants tls_shared_secret (X25519), tls_mlkem_ss, tls_kex_group and a +transcript hash, runs tls_derive_handshake_keys, and compares everything it +leaves behind against a HOST reference (hashlib/hmac HKDF, tools/pq_keylog_check +.handshake_secrets' schedule) computed from the same inputs: + + [1] group $EC: IKM = mlkem_ss || x25519_ss (64 B, ML-KEM first). The + handshake secret, both handshake traffic secrets and the four traffic + key/iv buffers equal the host values for that IKM, and differ from the + classic-IKM and the swapped-order values (so a wrong IKM cannot pass). + [2] group $1D and group 0: the classic 32 B x25519 IKM, unchanged. + [3] hygiene: afterwards tls_shared_secret, tls_mlkem_ss, the 64 B IKM + concatenation in input_buffer are zero, and no 8-byte window of the IKM + survives in hmac_data_buf (hkdf_extract's copy); nothing past the first + 64 bytes of input_buffer was touched. + + python3 tools/test_pq_keyschedule.py # builds the PQ image first + C64_SKIP_BUILD=1 python3 tools/test_pq_keyschedule.py +""" + +import hashlib +import random +import shutil +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +from _pq_testlib import Tally, Session, build_or_reuse, require_pq_image # noqa: E402 +from _skip_policy import cannot_run, verdict # noqa: E402 +import pq_keylog_check as K # noqa: E402 + +RNG = random.Random(0x50355035) +SENT = 0xA5 + + +def rb(n): + return bytes(RNG.getrandbits(8) for _ in range(n)) + + +MK, XS, TH = rb(32), rb(32), rb(32) + + +def host_schedule(ikm, th): + """(handshake_secret, c_hs, s_hs, c_key, c_iv, s_key, s_iv).""" + early = K.hkdf_extract(bytes(32), bytes(32)) + derived = K.expand_label(early, b"derived", hashlib.sha256(b"").digest(), 32) + hs = K.hkdf_extract(derived, ikm) + c = K.expand_label(hs, b"c hs traffic", th, 32) + s = K.expand_label(hs, b"s hs traffic", th, 32) + return (hs, c, s, K.expand_label(c, b"key", b"", 32), K.expand_label(c, b"iv", b"", 12), + K.expand_label(s, b"key", b"", 32), K.expand_label(s, b"iv", b"", 12)) + + +NAMES = ("handshake_secret", "client hs traffic secret", "server hs traffic secret", + "client write key", "client write iv", "server read key", "server read iv") + + +def case(s, t, tag, group, ikm): + s.wr(s.L("tls_kex_group"), [group]) + s.wr(s.L("tls_mlkem_ss"), MK) + s.wr(s.L("tls_shared_secret"), XS) + s.wr(s.L("tls_transcript"), TH) + s.wr(s.L("input_buffer"), bytes([SENT]) * 256) + s.wr(s.L("hmac_data_buf"), bytes([SENT]) * 97) + a, p = s.call("tls_derive_handshake_keys") + t.check(p & 1 == 0, f"{tag}: tls_derive_handshake_keys returns (C=0)", f"P=${p:02X}") + got = (s.rd(s.L("tls_handshake_secret"), 32), s.rd(s.L("tls_c_hs_secret"), 32), + s.rd(s.L("tls_s_hs_secret"), 32), s.rd(s.L("tls_hs_write_key"), 32), + s.rd(s.L("tls_hs_write_iv"), 12), s.rd(s.L("tls_hs_read_key"), 32), + s.rd(s.L("tls_hs_read_iv"), 12)) + want = host_schedule(ikm, TH) + for n, g, w in zip(NAMES, got, want): + t.check(g == w, f"{tag}: {n} == host HKDF over the expected IKM", + f"got {g[:6].hex()}.. want {w[:6].hex()}..") + return got + + +def hygiene(s, t, tag, ikm): + z = lambda n, addr, ln: t.check(s.rd(s.L(addr), ln) == bytes(ln), # noqa: E731 + f"{tag}: {n} is zero afterwards") + z("tls_shared_secret (x25519 ss)", "tls_shared_secret", 32) + z("tls_mlkem_ss", "tls_mlkem_ss", 32) + z("input_buffer[0:64] (the IKM concatenation)", "input_buffer", 64) + # Later HKDF calls reuse hmac_data_buf for their (public) info strings, so + # the copy hkdf_extract made of the IKM is checked by content: no 8-byte + # window of the IKM survives anywhere in the buffer. + buf = s.rd(s.L("hmac_data_buf"), 97) + left = [i for i in range(len(ikm) - 7) if ikm[i:i + 8] in buf] + t.check(not left, f"{tag}: no 8-byte window of the IKM survives in hmac_data_buf", + f"windows at IKM offsets {left[:6]}") + t.check(s.rd(s.L("input_buffer") + 64, 192) == bytes([SENT]) * 192, + f"{tag}: input_buffer past the 64 B is untouched") + + +def main(): + t = Tally() + if shutil.which("ca65") is None: + return cannot_run("cc65 not found", certifies="the PQ hybrid key schedule") + rc, out = build_or_reuse() + if rc != 0: + print(out[-1500:]) + return cannot_run("the PQ_HYBRID build failed", certifies="the PQ hybrid key schedule") + why = require_pq_image() + if why: + return cannot_run(why, certifies="the PQ hybrid key schedule") + classic = host_schedule(XS, TH) + swapped = host_schedule(XS + MK, TH) + hyb = host_schedule(MK + XS, TH) + t.check(hyb[0] != classic[0] and hyb[0] != swapped[0] and classic[0] != swapped[0], + "host references: hybrid, classic and swapped-order handshake secrets all differ") + with Session() as s: + print("\n[1] group $EC: IKM = mlkem_ss || x25519_ss") + case(s, t, "EC", 0xEC, MK + XS) + hygiene(s, t, "EC", MK + XS) + print("\n[2] group $1D and group 0: the classic 32 B IKM") + case(s, t, "1D", 0x1D, XS) + hygiene(s, t, "1D", XS) + case(s, t, "0", 0x00, XS) + hygiene(s, t, "0", XS) + print("\n[3] a second hybrid run on the same boot (state does not leak across runs)") + case(s, t, "EC again", 0xEC, MK + XS) + print(f"\nRESULTS: {t.passed}/{t.passed + t.failed} passed, {t.failed} failed") + return verdict(t.passed, t.failed, certifies="the PQ hybrid key schedule") + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tools/uci/rig_https_local.py b/tools/uci/rig_https_local.py index 61a0071..0128293 100644 --- a/tools/uci/rig_https_local.py +++ b/tools/uci/rig_https_local.py @@ -267,8 +267,8 @@ def _ensure_certs_or_fail() -> int: # --- PQ_HYBRID post-run dump (PQC phase P4) ------------------------------- # PQ_DUMP= writes /pq_state.json after the fetch, success or not: -# the ML-KEM secret, the X25519 secret, the SH transcript hash and the other -# P4 state, read with the CPU parked and all RAM banked in (the $A000+ BSS +# the ML-KEM secret, the X25519 secret (both zero since P5), the SH transcript +# hash, the application traffic secrets and the other P4/P5 state, read with the CPU parked and all RAM banked in (the $A000+ BSS # reads as the BASIC ROM otherwise). tools/pq_keylog_check.py consumes it. PQ_DUMP_DIR = os.environ.get("PQ_DUMP", "") PQ_PARK_ADDR: int = -1 @@ -299,6 +299,11 @@ def rd(name, n): "tls_sh_err": rd("tls_sh_err", 1), "tls_state": rd("tls_state", 1), "tls_last_state": rd("tls_last_state", 1), + # P5: the oracle's inputs after the secrets are zeroed (the application + # traffic secrets reuse these two buffers) and its sentinel gate (#204) + "tls_c_hs_secret": rd("tls_c_hs_secret", 32), + "tls_s_hs_secret": rd("tls_s_hs_secret", 32), + "tls_reached_connected": rd("tls_reached_connected", 1), } Path(outdir).mkdir(parents=True, exist_ok=True) (Path(outdir) / "pq_state.json").write_text(json.dumps(state, indent=1)) From 90b9e463c3511857aef79dd73d142112b7cfdef3 Mon Sep 17 00:00:00 2001 From: JC-000 <3798556+JC-000@users.noreply.github.com> Date: Sat, 17 Oct 2026 18:22:47 -0500 Subject: [PATCH 2/4] PQ P5: listener --groups default / --trace, rig diag shows kex group and df_last_err Co-Authored-By: Claude Sonnet 5.5 --- tools/https_e2e/openssl_listener.py | 10 +++++++++- tools/uci/rig_https_local.py | 4 ++-- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/tools/https_e2e/openssl_listener.py b/tools/https_e2e/openssl_listener.py index 864212f..21ef9c0 100644 --- a/tools/https_e2e/openssl_listener.py +++ b/tools/https_e2e/openssl_listener.py @@ -10,6 +10,7 @@ openssl_listener.py --groups X25519 --port 4433 --keylog /tmp/k.log openssl_listener.py --groups X25519MLKEM768 ... + openssl_listener.py --groups default --trace ... # OpenSSL's own group list Prints "LISTENING " once the server accepts, then runs until killed. Group selection is the server's whole policy: under @@ -57,6 +58,9 @@ def main(argv=None): ap.add_argument("--port", type=int, default=4433) ap.add_argument("--keylog", required=True) ap.add_argument("--bind", default="0.0.0.0") + ap.add_argument("--trace", action="store_true", + help="s_server -trace: the console shows each message, including the " + "negotiated key_share group (the which-group evidence for P5 runs)") a = ap.parse_args(argv) from ensure_certs import ensure_certs cert, key = ensure_certs("p256") @@ -64,7 +68,11 @@ def main(argv=None): Path(a.keylog).unlink(missing_ok=True) cmd = [exe, "s_server", "-accept", f"{a.bind}:{a.port}", "-cert", str(cert), "-key", str(key), "-tls1_3", "-ciphersuites", "TLS_CHACHA20_POLY1305_SHA256", - "-groups", a.groups, "-keylogfile", a.keylog, "-num_tickets", "0", "-state"] + "-keylogfile", a.keylog, "-num_tickets", "0", "-state"] + if a.groups != "default": # "default" = no -groups: OpenSSL's own list and preference + cmd += ["-groups", a.groups] + if a.trace: + cmd.append("-trace") # A pty, not pipes: s_server block-buffers stdout on a pipe, and the request # line would sit in its buffer instead of reaching us. master, slave = pty.openpty() diff --git a/tools/uci/rig_https_local.py b/tools/uci/rig_https_local.py index 0128293..73c566e 100644 --- a/tools/uci/rig_https_local.py +++ b/tools/uci/rig_https_local.py @@ -780,11 +780,11 @@ def r16(name: str) -> int: print() print("--- adapter / TLS state ---") for name in ("net_last_error", "net_tcp_state", "uci_socket_id", - "net_initialized", "reu_dma_timeout"): + "net_initialized", "reu_dma_timeout", "df_last_err", "tls_sh_err"): if name in labels: print(f" {name:22s} : 0x{r8(name):02X}") for name in ("tls_state", "tls_last_state", "tls_reached_connected", - "tls_recv_progress", "tls_recv_sub_progress"): + "tls_recv_progress", "tls_recv_sub_progress", "tls_kex_group"): if name in labels: print(f" {name:22s} : 0x{r8(name):02X}") for name in ("tcp_recv_head", "tcp_recv_tail", "uci_req_len", "uci_read_hdr", From 0c9ffb9bf86a4667a8923050846ebb8ad2c1ceff Mon Sep 17 00:00:00 2001 From: JC-000 <3798556+JC-000@users.noreply.github.com> Date: Sat, 17 Oct 2026 18:37:25 -0500 Subject: [PATCH 3/4] PQ P5: CLAUDE.md terse edits, engineering-notes P5 section Co-Authored-By: Claude Sonnet 5.5 --- CLAUDE.md | 15 +++++++---- docs/engineering-notes.md | 57 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 66 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 24bcc2b..4ec6d99 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -143,10 +143,10 @@ Variables: both exist for uci only, so there is no ip65 comb build. Confirm from the `ld65 -C` line, not from the profile name. - `PQ_HYBRID=1` — links `libs/mlkem` (c64-mlkem v0.6.0, ABI 3) for the - X25519MLKEM768 hybrid (P4: `tls_connect` runs KeyGen and offers 11EC; - a 11EC ServerHello is read and Decapsed, but the **key schedule is not - hybrid yet** (P5), so against an 11EC server the handshake fails at the - first encrypted record; a 001D server completes as before). uci + X25519MLKEM768 hybrid (`tls_connect` runs KeyGen and offers 11EC; an 11EC + ServerHello is read and Decapsed and the handshake secret is extracted + from `mlkem_ss || x25519_ss` (P5), so an 11EC server completes HTTPS; a + 001D server completes as before). uci + `USE_NISTCURVES_ONCHIP=1` or `_COMB=1`, with or without `TRUST_STORE`; `$(error)` on ip65, uci-m3 and the uci REU profile. Unset = byte-identical PRG on every profile. Layout in Memory layout; asserts in @@ -587,6 +587,11 @@ never exercised: during the multi-minute crypto stall. - Cloudflare is out of scope: ignores MFL and enforces a ~15 s deadline. +PQ_HYBRID (P5): X25519MLKEM768 handshakes complete on the U64E (OpenSSL 3.6.5 +`s_server`, browserleaks.com, en.wikipedia.org), onchip and comb; github.com and +lwn.net do not offer 11EC (handshake_failure to a hybrid-only hello). Hashes and timings: the P5 section of +engineering-notes. + Handshake flow, both backends: CH → SH (X25519) → EE, Certificate, CertificateVerify (P-256 via sibling) → server Finished verified → client Finished → traffic keys, seq counters reset (§5.3) → GET → response. @@ -693,7 +698,7 @@ already refused a step later, as `DF_ERR_TYPE = $04`). Test: UCI CH is sectioned (`CH_SECTIONED`, follows `TLS_STREAM_DEFRAME`): `tls_ch_ks_ptr/len` (16-bit, BSS, one-shot) name a bulk key-share that `tls_ch_send_sections` streams from its own buffer between the head and tail staged in `tls_rec_buf`, as ONE record; 0 = classic X25519-only hello (every build without PQ_HYBRID). Under PQ_HYBRID=1 `tls_connect` arms it itself (`pq_connect_prep`, `src/crypto/pq_hybrid.s`: DRBG seed, KeyGen, dk zeroed at once, ek in `cert_buf`; 11EC = ek || x25519, then 001D also offered); no caller arms anything. The sender clears it on every exit. HRR random -> `tls_sh_err=$01` (both backends). Test: `test_tls_handshake.py` [2d-2k], [3d]. -PQ_HYBRID ServerHello (P4): `pq_sh_feed` streams the SH across any number of plaintext records (`pq_hybrid.s`; `tls_parse_server_hello` is assembled out), 11EC needs exactly 1,120 B = ct 1,088 (into `cert_buf`) || x25519 32; ct must be Decapsed (`pq_sh_decaps`, before the X25519 mult) before anything writes `cert_buf`. unsolicited SH extensions and a malformed/oversize record header while waiting for the SH are refused (fail fast, `$0D`/`$0E`); KeyGen and Decaps end with `pq_mlkem_scrub` (polys + `$B100` window zeroed); `tls_sh_err` codes `$01-$0E` are in `src/constants.inc`; `tls_kex_group` ($1D/$EC) and `tls_mlkem_ss` are P5's inputs; seed + ss are one scrub span. Tests: `tools/test_pq_sh.py` (fast), `tools/test_pq_kem.py` (KeyGen/Decaps/tls_connect), oracle `tools/pq_keylog_check.py` (hardware, vs `openssl s_server -keylogfile`). +PQ_HYBRID ServerHello (P4): `pq_sh_feed` streams the SH across any number of plaintext records (`pq_hybrid.s`; `tls_parse_server_hello` is assembled out), 11EC needs exactly 1,120 B = ct 1,088 (into `cert_buf`) || x25519 32; ct must be Decapsed (`pq_sh_decaps`, before the X25519 mult) before anything writes `cert_buf`. unsolicited SH extensions and a malformed/oversize record header while waiting for the SH are refused (fail fast, `$0D`/`$0E`); KeyGen and Decaps end with `pq_mlkem_scrub` (polys + `$B100` window zeroed); `tls_sh_err` codes `$01-$0E` are in `src/constants.inc`; `tls_kex_group` ($1D/$EC) picks the key-schedule IKM in `tls_derive_handshake_keys` (P5: $EC = the 64 B `tls_mlkem_ss || tls_shared_secret` concatenated in `input_buffer`, ML-KEM first; else the 32 B x25519 secret) and both secrets, the concatenation and `hkdf_extract`'s copy are zeroed right after the extract; seed + ss are one scrub span. Tests: `tools/test_pq_sh.py` (fast), `tools/test_pq_kem.py` (KeyGen/Decaps/tls_connect), `tools/test_pq_keyschedule.py` (hybrid IKM vs host HKDF, zeroing), oracle `tools/pq_keylog_check.py --state` (hardware: the C64's application traffic secrets vs `openssl s_server -keylogfile`'s `*_TRAFFIC_SECRET_0`, gated on `tls_reached_connected`). ### VIC-II blanking — worth 6.3%, not the fleet's "20-25%" diff --git a/docs/engineering-notes.md b/docs/engineering-notes.md index dba3107..421cfc1 100644 --- a/docs/engineering-notes.md +++ b/docs/engineering-notes.md @@ -4235,10 +4235,65 @@ Decisions and findings: cannot READ such a hello. A ChangeCipherSpec record between SH fragments is skipped by the record layer, as before. -Oracle (hardware): the C64 cannot read the first encrypted record yet, so +Oracle (hardware, P4; superseded by the P5 section below): the C64 cannot read the first encrypted record yet, so `tools/pq_keylog_check.py` runs the RFC 8446 schedule offline on the C64's `tls_mlkem_ss || tls_shared_secret` and `tls_transcript` (read with the CPU parked and all RAM banked in: `PQ_DUMP=` in `rig_https_local.py`) and compares with `s_server -keylogfile`. A match proves Decaps agreed with the server's Encaps and that both sides hashed the same CH || SH. A run that did not reach Decaps is INCONCLUSIVE (exit 78), never a verdict. + +## PQ_HYBRID P5: hybrid key schedule, first X25519MLKEM768 handshake (2026-10-17) + +`tls_derive_handshake_keys` (src/tls_keyschedule.s, `.ifdef PQ_HYBRID`) now takes +the handshake-secret IKM from the group the ServerHello chose: `tls_kex_group` += `$EC` gives HKDF-Extract(salt = derived, IKM = `tls_mlkem_ss || tls_shared_secret`) +(draft-ietf-tls-ecdhe-mlkem: ML-KEM first, then X25519, 64 B), `$1D` (or 0, a test +that calls the routine bare) the unchanged 32 B x25519 secret. Everything after +the extract is the existing schedule; the transcript is the same SHA-256. + +Decisions and findings: + + - **A small concat, not a contiguous span.** `tls_mlkem_ss` sits in + NET_BSS_TAIL (below `$4200`) and `tls_shared_secret` in data.s BSS, so the + 64 B IKM is copied into `input_buffer` (256 B scratch, dead since the + early-secret step) and the HKDF IKM pointer/length retargeted. Net -61 B of + NET_CODE free on every PQ profile (about 63 B of TLS_CODE, 2 B back from + `pq_sh_decaps`; `tools/measure_margins.py`). `hkdf_extract` + copies the IKM into `hmac_data_buf` (97 B) and HMACs it as the message, so 64 + is within its limit; nothing there treats it as a key. + - **Zeroed at the extract, not at 'Q'.** Right after `hkdf_extract` the two + 32 B secrets, the 64 B concatenation (`input_buffer`) and `hkdf_extract`'s + copy (`hmac_data_buf[0:64]`) are zeroed, for BOTH groups. Later HKDF calls + reuse `hmac_data_buf` for public info strings, so the copy is checked by + content (no 8-byte window of the IKM survives), and the span matters: with the + `hmac_data_buf` zeroing removed (mutant K11) IKM bytes around offset 55-63 + were still there after the schedule ran. Not zeroed (unchanged, same on classic builds): + `tls_ecdhe_privkey` (until 'Q'), and SHA-256's internal block/schedule + buffers (not inspected; the following HMACs of the same routine rewrite them). Only PQ builds pay for the zeroing; the seven + knob-off PRGs are byte-identical. + - **The oracle changed with it.** With the secrets gone, `pq_keylog_check.py + --state` compares what stays: `tls_c_hs_secret` / `tls_s_hs_secret` are reused + for the APPLICATION traffic secrets after `tls_derive_traffic_keys`, which are + a pure function of the hybrid handshake secret and the transcript through the + server Finished, and `s_server -keylogfile` logs them as `CLIENT_TRAFFIC_SECRET_0` + / `SERVER_TRAFFIC_SECRET_0`. Gate: `tls_reached_connected == 7` (#204; a run + that connected and then called `tls_close` reads `tls_state = 0`), `tls_kex_group + == $EC`, `tls_sh_err == 0`, both secrets non-zero; a non-zero seed/ss/shared + secret in a connected run is a RESIDUE failure, not a pass. The P4 offline mode + (explicit secrets as arguments) is unchanged. + - **pq_sh_decaps** lost its redundant outer `php`/`plp` (`pq_mlkem_scrub` saves + and restores P itself); 2 B back in PQ_GLUE. + - **Which-group evidence on hardware:** `openssl_listener.py --trace` prints the + ServerHello key_share group (`X25519MLKEM768 (4588)` = 0x11EC); `--groups + default` runs `s_server` without `-groups`, and OpenSSL 3.6.5 then picks + X25519MLKEM768 for our hello (it prefers it). + - **Trap: `HTTPS_SNI=` on a live run.** A PQ image built with `HTTPS_SNI=www.foo.invalid` + (for the local self-signed listener) fails a LIVE host with `df_last_err = $05` + (DF_ERR_CERT_FMT: the SAN check runs against the baked name). It looked like a + hybrid defect for one run; the same image without the override passes. Build + live images without `HTTPS_SNI`. + - **Real servers.** browserleaks.com and en.wikipedia.org negotiate 11EC (they + complete `openssl s_client -groups X25519MLKEM768 -maxfraglen 512`); github.com + and lwn.net answer `handshake_failure` to a hybrid-only hello (they would pick + 001D for our dual hello). From 7790ce89d0907528d61ea40a091162aa3da75689 Mon Sep 17 00:00:00 2001 From: JC-000 <3798556+JC-000@users.noreply.github.com> Date: Sat, 17 Oct 2026 19:15:42 -0500 Subject: [PATCH 4/4] PQ P5 round 1: comment/doc fixes, EB/ED/FF group cases, X02 mutant, KILLED requires a FAIL line (no code byte change) Co-Authored-By: Claude Sonnet 5.5 --- CLAUDE.md | 9 +++++---- docs/engineering-notes.md | 28 +++++++++++++++++++++++++--- src/crypto/pq_hybrid.s | 7 ++++--- src/tls13.s | 3 ++- src/tls_keyschedule.s | 5 +++++ tools/mutate_pq_sh.py | 13 ++++++++++--- tools/test_pq_keyschedule.py | 7 ++++++- 7 files changed, 57 insertions(+), 15 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4ec6d99..b6f8a65 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -587,10 +587,11 @@ never exercised: during the multi-minute crypto stall. - Cloudflare is out of scope: ignores MFL and enforces a ~15 s deadline. -PQ_HYBRID (P5): X25519MLKEM768 handshakes complete on the U64E (OpenSSL 3.6.5 -`s_server`, browserleaks.com, en.wikipedia.org), onchip and comb; github.com and -lwn.net do not offer 11EC (handshake_failure to a hybrid-only hello). Hashes and timings: the P5 section of -engineering-notes. +PQ_HYBRID (P5): X25519MLKEM768 handshakes complete on the U64E against a local +OpenSSL 3.6.5 `s_server`, onchip and comb images. Live servers, comb image only: +browserleaks.com (HTTP 200) and en.wikipedia.org (HTTP 301 at `/`); github.com and +lwn.net do not offer 11EC (handshake_failure to a hybrid-only hello). Image hashes, +make lines and timings: the P5 section of engineering-notes. Handshake flow, both backends: CH → SH (X25519) → EE, Certificate, CertificateVerify (P-256 via sibling) → server Finished verified → client diff --git a/docs/engineering-notes.md b/docs/engineering-notes.md index 421cfc1..db6e324 100644 --- a/docs/engineering-notes.md +++ b/docs/engineering-notes.md @@ -4257,9 +4257,11 @@ Decisions and findings: - **A small concat, not a contiguous span.** `tls_mlkem_ss` sits in NET_BSS_TAIL (below `$4200`) and `tls_shared_secret` in data.s BSS, so the 64 B IKM is copied into `input_buffer` (256 B scratch, dead since the - early-secret step) and the HKDF IKM pointer/length retargeted. Net -61 B of - NET_CODE free on every PQ profile (about 63 B of TLS_CODE, 2 B back from - `pq_sh_decaps`; `tools/measure_margins.py`). `hkdf_extract` + early-secret step) and the HKDF IKM pointer/length retargeted. NET_CODE + free drops by 61 B on the onchip profiles (166 -> 105) and 63 B on the comb + profiles (335 -> 272, 197 -> 134): about 63 B of TLS_CODE, and on onchip + 2 B come back from `pq_sh_decaps` (on comb its PQ_GLUE sits in CRYPTO_HOT, + +2 there). `tools/measure_margins.py`. `hkdf_extract` copies the IKM into `hmac_data_buf` (97 B) and HMACs it as the message, so 64 is within its limit; nothing there treats it as a key. - **Zeroed at the extract, not at 'Q'.** Right after `hkdf_extract` the two @@ -4297,3 +4299,23 @@ Decisions and findings: complete `openssl s_client -groups X25519MLKEM768 -maxfraglen 512`); github.com and lwn.net answer `handshake_failure` to a hybrid-only hello (they would pick 001D for our dual hello). + +Hardware record (U64E 10.43.23.81, 48 MHz, DeviceLock, OpenSSL 3.6.5 `s_server`; +all runs full HTTPS PASS, tls_kex_group $EC unless noted): + + - onchip, `make BACKEND=uci USE_NISTCURVES_ONCHIP=1 PQ_HYBRID=1 + HTTPS_SNI=www.foo.invalid`, sha256 + `ab85014cdc8bb074fc9cb99180c90dc8a74ac4d8ed9f68cfda32e7d311cf5e0f`: + rig wall-clock 108 s (`-groups X25519MLKEM768`), 107 s (`-groups X25519`, + $1D), 109 s (default groups, OpenSSL picks 11EC). + - comb (REU 16 MB, `C64_INIT_WAIT=90`), `make BACKEND=uci + USE_NISTCURVES_ONCHIP_COMB=1 PQ_HYBRID=1 HTTPS_SNI=www.foo.invalid`, sha256 + `265c4c583c2b5a2430daf3a7ee2a3e546d99a8b7c1c4173476e8455097cfa042`: 165 s / + 164 s ($1D) / 166 s. With `PHASE_TIMING=1` (1 s poll, n=1 each) trigger to + client Finished 43.7 s hybrid vs 42.0 s X25519-only: about +1.7 s. + - live (`tools/uci/rig_https_live.py`), comb image WITHOUT `HTTPS_SNI`, `make + BACKEND=uci USE_NISTCURVES_ONCHIP_COMB=1 PQ_HYBRID=1`, sha256 + `b8677dd79968fb57e475baaa0995c8979d670b159ae753b207a947d5e8be8d61`: + browserleaks.com HTTP 200 (Finished at 44.1 s; the non-PQ comb image + `ad85797b...` 42.3 s), en.wikipedia.org HTTP 301 at `/` (39.8 s). Onchip was + not run against live servers. diff --git a/src/crypto/pq_hybrid.s b/src/crypto/pq_hybrid.s index ca11063..5b79012 100644 --- a/src/crypto/pq_hybrid.s +++ b/src/crypto/pq_hybrid.s @@ -219,9 +219,10 @@ pq_connect_prep: ; pq_sh_decaps - Decaps the ServerHello's ct if the server chose 11EC. ; The args are rewritten here: nothing may sit between them and the call. ; The seed is zeroed on every successful exit (no longer needed) and by -; tls_connect's error exit; tls_mlkem_ss is kept like tls_shared_secret (the -; hardware oracle reads it) and scrubbed by 'Q' (src/session_scrub.s) or by -; the next connection's pq_connect_prep. +; tls_connect's error exit. tls_mlkem_ss is zeroed by tls_derive_handshake_keys +; right after the handshake secret is extracted (P5); on a connect that fails +; BEFORE that point it is kept like tls_shared_secret and scrubbed by 'Q' +; (src/session_scrub.s) or by the next connection's pq_connect_prep. ; ----------------------------------------------------------------------------- pq_sh_decaps: lda tls_kex_group diff --git a/src/tls13.s b/src/tls13.s index 5fd2d4d..2ebf8f9 100644 --- a/src/tls13.s +++ b/src/tls13.s @@ -345,7 +345,8 @@ tls_connect: @error: .ifdef PQ_HYBRID jsr pq_seed_zero ; the d||z seed never outlives a failed connect (the - ; ML-KEM secret stays, like tls_shared_secret: 'Q' scrubs) + ; ML-KEM secret stays if the key schedule never ran, like + ; tls_shared_secret: 'Q' scrubs; P5 zeroes both after the extract) .endif lda tls_state ; preserve last attempted state bmi :+ ; already ERROR: the record layer aborted diff --git a/src/tls_keyschedule.s b/src/tls_keyschedule.s index 7fe14ea..b2eb288 100644 --- a/src/tls_keyschedule.s +++ b/src/tls_keyschedule.s @@ -74,7 +74,12 @@ ; ; Input: tls_shared_secret (32 bytes) = x25519 result ; tls_transcript (32 bytes) = hash of ClientHello || ServerHello +; PQ_HYBRID only: tls_kex_group = $EC makes the step-3 IKM the 64 B +; tls_mlkem_ss || tls_shared_secret (ML-KEM first, copied into +; input_buffer); any other value keeps the 32 B x25519 IKM. ; Output: tls_hs_write_key/iv, tls_hs_read_key/iv filled +; PQ_HYBRID only: tls_shared_secret, tls_mlkem_ss, input_buffer[0:64] +; and hmac_data_buf[0:64] are zeroed right after step 3 (both groups) ; tls_handshake_secret saved for later use ; tls_early_secret saved for reference ; diff --git a/tools/mutate_pq_sh.py b/tools/mutate_pq_sh.py index ad57887..ce7b14d 100644 --- a/tools/mutate_pq_sh.py +++ b/tools/mutate_pq_sh.py @@ -252,6 +252,8 @@ def nop(n): " sta hmac_data_buf,x\n dex\n bpl @dhk_zero\n", nop(3) + " dex\n bpl @dhk_zero\n", KS), ("K12", "the IKM zeroing covers only 32 of the 64 bytes", KSF, " lda #0\n ldx #63\n@dhk_zero:", " lda #0\n ldx #31\n@dhk_zero:", KS), + ("X02", "hybrid for any group >= $EC (bne -> bcc after the compare)", KSF, + " cmp #$EC\n bne @dhk_ikm_ready\n", " cmp #$EC\n bcc @dhk_ikm_ready\n", KS), ] @@ -307,9 +309,14 @@ def main(): else: rc, out = run(suite) killed = [ln for ln in out.splitlines() if "FAIL" in ln][:1] - verdict = "KILLED" if rc != 0 else "SURVIVED" - if killed: - verdict += f" by: {killed[0].strip()[:110]}" + if rc == 0: + verdict = "SURVIVED" + elif killed: + verdict = f"KILLED by: {killed[0].strip()[:110]}" + else: + # non-zero exit without an assertion FAIL line: a crash, + # hang or harness error, not a kill by a check + verdict = f"CRASH-OR-HANG (rc={rc}, no FAIL line; NOT a kill): {out.strip()[-120:]!r}" finally: p.write_text(orig) print(f"{mid} {what}: {verdict} ({time.monotonic() - t0:.0f} s)", flush=True) diff --git a/tools/test_pq_keyschedule.py b/tools/test_pq_keyschedule.py index 89db989..b0ee35f 100644 --- a/tools/test_pq_keyschedule.py +++ b/tools/test_pq_keyschedule.py @@ -115,11 +115,16 @@ def main(): print("\n[1] group $EC: IKM = mlkem_ss || x25519_ss") case(s, t, "EC", 0xEC, MK + XS) hygiene(s, t, "EC", MK + XS) - print("\n[2] group $1D and group 0: the classic 32 B IKM") + print("\n[2] group $1D, 0, $EB, $ED, $FF: the classic 32 B IKM") case(s, t, "1D", 0x1D, XS) hygiene(s, t, "1D", XS) case(s, t, "0", 0x00, XS) hygiene(s, t, "0", XS) + # Only $EC is hybrid: neighbours and the top of the range stay classic + # (kills a `bcc`/`bcs` in place of the `bne` after `cmp #$EC`). + for g in (0xEB, 0xED, 0xFF): + case(s, t, f"{g:02X}", g, XS) + hygiene(s, t, f"{g:02X}", XS) print("\n[3] a second hybrid run on the same boot (state does not leak across runs)") case(s, t, "EC again", 0xEC, MK + XS) print(f"\nRESULTS: {t.passed}/{t.passed + t.failed} passed, {t.failed} failed")