diff --git a/CLAUDE.md b/CLAUDE.md
index ea30e25..24bcc2b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -143,7 +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
- planned X25519MLKEM768 hybrid; **placement only, nothing calls it**. uci
+ 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
+ `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
@@ -688,7 +691,9 @@ already refused a step later, as `DF_ERR_TYPE = $04`). Test:
### ClientHello shape
-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 (all builds today). Rule: arm `tls_ch_ks_ptr/len` after TCP connect, immediately before `jsr tls_connect`; the sender clears it on every exit. HRR random -> `tls_sh_err=$01` (both backends). Test: `test_tls_handshake.py` [2d-2k], [3d].
+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`).
### VIC-II blanking — worth 6.3%, not the fleet's "20-25%"
@@ -788,8 +793,9 @@ UCI (`cfg/c64-https-uci.cfg`, W1 hot/cold split — the reference):
$0801-$1FFF LOADER BASIC stub + boot + HTTP + net wrapper
$2000-$3B65 NET_CODE UCI adapter + LOADER_OVERFLOW + TLS_CODE
+ CRYPTO_AUX_CODE
- $3B66-$41FF NET_BSS_TAIL NET_BSS_TAIL segment (deframer/viewer BSS),
- then free. NOT `BSS_TAIL` and NOT `UCI_BSS`
+ $3B66-$41FF NET_BSS_TAIL NET_BSS_TAIL segment (deframer/viewer BSS;
+ PQ_HYBRID: `tls_pq_seed` + `tls_mlkem_ss`,
+ 96 B, one scrub span), then free. NOT `BSS_TAIL` and NOT `UCI_BSS`
— both are elsewhere (below, and
CRYPTO_HOT). Read the map.
$4200-$5FFF CRYPTO_OVERLAY 7.5 KB. Resident tenants in every UCI
diff --git a/Makefile b/Makefile
index c566542..80b3a01 100644
--- a/Makefile
+++ b/Makefile
@@ -469,7 +469,7 @@ endif
CA65FLAGS += -D PQ_HYBRID=1
SIBLING_LIB_ARCHIVES += build/lib/mlkem.a
else
-CRYPTO_SRCS_EFFECTIVE := $(filter-out src/crypto/mlkem_link.s,$(CRYPTO_SRCS_EFFECTIVE))
+CRYPTO_SRCS_EFFECTIVE := $(filter-out src/crypto/mlkem_link.s src/crypto/pq_hybrid.s,$(CRYPTO_SRCS_EFFECTIVE))
endif
# #155 phase 2 memory reclaims: code no shipped image reaches is assembled
diff --git a/cfg/c64-https-uci-onchip-cold.cfg b/cfg/c64-https-uci-onchip-cold.cfg
index 4f4bdde..d2c676d 100644
--- a/cfg/c64-https-uci-onchip-cold.cfg
+++ b/cfg/c64-https-uci-onchip-cold.cfg
@@ -535,6 +535,10 @@ SEGMENTS {
# load = COLD_FILE ($A000, file bytes), run = MLKEM_CODE_RAM ($E000).
# align_load keeps the load image the same shape as the run image, so
# one block copy moves both (asserted in src/crypto/mlkem_link.s).
+ # PQ_HYBRID=1 only (src/crypto/pq_hybrid.s; optional, so an unset build is
+ # byte-identical): the ServerHello machine and the KeyGen/Decaps glue.
+ PQ_CODE: load = CRYPTO_HOT, type = ro, optional = yes;
+ PQ_GLUE: load = CRYPTO_HOT, type = ro, optional = yes;
LIB_MLKEM_CODE: load = COLD_FILE, run = MLKEM_CODE_RAM, type = ro, optional = yes, define = yes;
LIB_MLKEM_RODATA: load = COLD_FILE, run = MLKEM_CODE_RAM, type = ro, optional = yes, align = $40, align_load = $40, define = yes;
# One byte, last in the load image: boot checks it before copying, so a
diff --git a/cfg/c64-https-uci-onchip.cfg b/cfg/c64-https-uci-onchip.cfg
index bac2933..695b6cc 100644
--- a/cfg/c64-https-uci-onchip.cfg
+++ b/cfg/c64-https-uci-onchip.cfg
@@ -498,6 +498,10 @@ SEGMENTS {
# load = COLD_FILE ($A000, file bytes), run = MLKEM_CODE_RAM ($E000).
# align_load keeps the load image the same shape as the run image, so
# one block copy moves both (asserted in src/crypto/mlkem_link.s).
+ # PQ_HYBRID=1 only (src/crypto/pq_hybrid.s; optional, so an unset build is
+ # byte-identical): the ServerHello machine and the KeyGen/Decaps glue.
+ PQ_CODE: load = CRYPTO_HOT, type = ro, optional = yes;
+ PQ_GLUE: load = CRYPTO_HOT, type = ro, optional = yes;
LIB_MLKEM_CODE: load = COLD_FILE, run = MLKEM_CODE_RAM, type = ro, optional = yes, define = yes;
LIB_MLKEM_RODATA: load = COLD_FILE, run = MLKEM_CODE_RAM, type = ro, optional = yes, align = $40, align_load = $40, define = yes;
# One byte, last in the load image: boot checks it before copying, so a
diff --git a/cfg/c64-https-uci.cfg b/cfg/c64-https-uci.cfg
index 650fbec..5a4a406 100644
--- a/cfg/c64-https-uci.cfg
+++ b/cfg/c64-https-uci.cfg
@@ -454,6 +454,10 @@ SEGMENTS {
# load = COLD_FILE ($A000, file bytes), run = MLKEM_CODE_RAM ($E000).
# align_load keeps the load image the same shape as the run image, so
# one block copy moves both (asserted in src/crypto/mlkem_link.s).
+ # PQ_HYBRID=1 only (src/crypto/pq_hybrid.s; optional, so an unset build is
+ # byte-identical): the ServerHello machine and the KeyGen/Decaps glue.
+ PQ_CODE: load = LOADER, type = ro, optional = yes;
+ PQ_GLUE: load = NET_CODE, type = ro, optional = yes;
LIB_MLKEM_CODE: load = COLD_FILE, run = MLKEM_CODE_RAM, type = ro, optional = yes, define = yes;
LIB_MLKEM_RODATA: load = COLD_FILE, run = MLKEM_CODE_RAM, type = ro, optional = yes, align = $40, align_load = $40, define = yes;
# One byte, last in the load image: boot checks it before copying, so a
diff --git a/docs/engineering-notes.md b/docs/engineering-notes.md
index 89ca9d1..dba3107 100644
--- a/docs/engineering-notes.md
+++ b/docs/engineering-notes.md
@@ -4167,3 +4167,78 @@ Findings that changed the plan:
`pq_mlkem_call` is load-bearing: CIA1's IRQ is level-triggered and an RTI
stub acknowledges nothing (I/O in or out), so an IRQ reaching it would
re-enter at once and livelock the call. The `sei` prevents that.
+
+## PQ_HYBRID P4: hybrid ServerHello, KeyGen in tls_connect, Decaps (2026-10-17)
+
+`tls_connect` now offers X25519MLKEM768 and reads the answer; the key schedule
+is NOT hybrid yet (P5), so an 11EC server is Decapsed and then fails at the
+first encrypted record. A 001D server completes HTTPS as before.
+
+Decisions and findings:
+
+ - **Both shares are offered** (11EC = ek || x25519, then 001D with the same
+ x25519 key), exactly the hello #312 sent to OpenSSL 3.6.5. Under
+ `-groups X25519` OpenSSL answers 001D, under `-groups X25519MLKEM768` 11EC
+ with a 1,120 B key_exchange (ct 1,088 || x25519 32), fragmented 512+512+154
+ because we send max_fragment_length.
+ - **The ServerHello is not buffered**: a byte-at-a-time machine (gather N
+ bytes to a destination, then a handler arms the next state) in
+ `src/crypto/pq_hybrid.s`. It costs ~930 B, three times the first estimate;
+ most of it is the handlers (each keeps local error stubs because a branch
+ reaches 127 B). `tls_parse_server_hello` (~280 B of LOADER) is assembled out
+ under PQ_HYBRID, which is where the LOADER bytes came from. The PQ code
+ rides two optional segments, `PQ_CODE` (machine) and `PQ_GLUE` (KeyGen,
+ Decaps, scrubs): LOADER/NET_CODE on `cfg/c64-https-uci.cfg`, CRYPTO_HOT on
+ the two comb cfgs, because comb-store-pq has 55 B of CRYPTO_OVERLAY and
+ 243 B of NET_CODE. Margins: `tools/measure_margins.py`.
+ - **Stricter than the single-record parser, on purpose**: an EMPTY session id
+ echo (what we send), the extension block must fill the message exactly,
+ supported_versions and key_share exactly once each, group 11EC only if it
+ was offered, and EVERY other extension refused (`SH_ERR_EXT $0D`; RFC 8446
+ 4.2: we requested only those two). legacy_version is ignored (RFC 8446
+ 4.2.1). `tls_sh_err` codes `$01-$0E` (`src/constants.inc`); `$01` (HRR)
+ keeps its meaning. Hardware: OpenSSL 3.6.5 sends nothing else in either SH.
+ - **Handshake order (#152)**: `TLS_HS_SEQ_CHECK` is not reused. It derives the
+ one legal type from `tls_state` for the post-ServerHello dispatchers; the
+ machine's header state checks type 2 and its length bound plus DONE refuse
+ a second message, which is the same rule for the first message.
+ - **cert_buf is the home of the ek AND the ct.** The ek is dead once the CH is
+ sent, the ct once Decaps returns, and Decaps runs before anything can write
+ cert_buf (Certificate comes later; the comb cold bank refuses to run while
+ `tls_state` is not IDLE/ERROR). The 64 B seed and the 32 B secret are in
+ NET_BSS_TAIL, below `$4200`: not cert_buf, not `tls_rec_buf`
+ (X25519_SCRATCH), not the `$B100` ML-KEM window, not `$D000`, not the ring.
+ - **Order in `tls_recv_server_hello`**: per-record fold into the transcript
+ right after the record's bytes were parsed (so the fold precedes X25519
+ scratch reuse of `tls_rec_buf`), then the drain, then `pq_sh_decaps`, then
+ the X25519 mult (its `_fresh` entries rebuild the tables ML-KEM overwrote).
+ The failed-poll budget is ONE for the whole SH (like `tls_recv_encrypted`);
+ a fresh budget per record let 1-byte records stall ~1,500 x 65,536 polls.
+ - **Secrets**: the dk (2,400 B in the ring) is zeroed straight after KeyGen
+ even when KeyGen was refused; the seed is zeroed after Decaps and by
+ `tls_connect`'s error exit; `tls_mlkem_ss` is KEPT on error (like
+ `tls_shared_secret`; the hardware oracle reads it) and is scrubbed by 'Q'
+ (one 96 B span) or the next connection's prep.
+ - **Residue**: `pq_mlkem_scrub` (next to `pq_mlkem_call`, same sei / `$01=$34`
+ discipline) zeroes the polynomial area (`$D000-$DFFF`: s_hat after KeyGen,
+ y/e1/e2 after Decaps) and the whole rest-BSS window (`$B100-$BBFF`: m', K',
+ r', the Keccak state; X25519_TABLES shares it and x25519_*_fresh rebuilds
+ it, while mul_dma is per-row scratch regenerated before each row reads it,
+ so stale entries are never read) after KeyGen and after Decaps, on every outcome. ~7,000 stores,
+ ~80K cycles. Without it zeroing the seed bought nothing: the same secret
+ lived on in kem_hb until 'Q'.
+ - **A hybrid SH sent as ONE record** (a server that ignores
+ max_fragment_length; `tls_rec_buf` is 548 B) used to be resynced through
+ byte by byte and time out after ~43 min. A malformed or oversize header
+ while waiting for the SH is now fatal (`tls_rec_frame_fail`, PQ only) and
+ `tls_recv_server_hello` fails at once with `SH_ERR_RECORD $0E`. It still
+ 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
+`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.
diff --git a/pytest.ini b/pytest.ini
index abfe395..81d78c4 100644
--- a/pytest.ini
+++ b/pytest.ini
@@ -57,7 +57,9 @@ testpaths =
tools/test_net_err_registry.py
tools/test_net_families_drift.py
tools/test_net_test_env.py
+ tools/test_openssl_listener.py
tools/test_package_verify.py
+ tools/test_pq_keylog_check.py
tools/test_pins.py
tools/test_prg_io_range.py
tools/test_prg_load.py
diff --git a/src/constants.inc b/src/constants.inc
index bf12da2..036357e 100644
--- a/src/constants.inc
+++ b/src/constants.inc
@@ -233,11 +233,11 @@ tcp_recv_buf = $c000
; CH_SECTIONED: the sectioned/hybrid ClientHello (16-bit bulk key-share
; section, supported_groups 11EC,001D). Build-time switch, NOT a Makefile
; knob: it follows TLS_STREAM_DEFRAME (UCI only). ip65 has no bytes to
-; spare and is excluded from PQ. Note a ~1.2 KB hybrid ServerHello is NOT
-; deframed today (tls_recv_server_hello is single-record; a server fragments
-; it under MFL=512): that is the next phase (ServerHello on the streaming
-; deframer). Without CH_SECTIONED the builder still uses the same templates
-; and emits the X25519-only hello, byte-identical.
+; spare and is excluded from PQ. Without CH_SECTIONED the builder still uses
+; the same templates and emits the X25519-only hello, byte-identical. Under
+; PQ_HYBRID=1 tls_connect arms it (pq_connect_prep) and the ~1.2 KB hybrid
+; ServerHello, which a server fragments under MFL=512, is read by the streaming
+; reader in src/crypto/pq_hybrid.s.
.ifdef TLS_STREAM_DEFRAME
CH_SECTIONED = 1
.endif
@@ -253,10 +253,33 @@ CH_SECTIONED = 1
; net_poll. Size >= 2,400 and the polys above it: src/crypto/mlkem_link.s.
; Comb: COLD_IMAGE is staged at $C000 but cold_bank_init stashes it to the
; REU once at boot and never reads it again, so the ring is dead by then.
-; Also owed by the callers (later phases; no home exists yet): the 64 B d||z
-; seed that mlkem_decaps_seed re-reads needs a BSS home outside the unions
-; below AND a session_scrub span (P5); and ML-KEM never interleaves with
-; X25519 or fp_mul (the BSS window is X25519_TABLES + mul_dma): call it only
-; through pq_mlkem_keygen / pq_mlkem_decaps_seed (src/crypto/mlkem_link.s).
+; The caller is pq_connect_prep (src/crypto/pq_hybrid.s), from tls_connect: it
+; zeroes the dk at once. The 64 B d||z seed lives in NET_BSS_TAIL (tls_pq_seed,
+; with tls_mlkem_ss after it; one session_scrub span). ML-KEM never
+; interleaves with X25519 or fp_mul (the BSS window is X25519_TABLES +
+; mul_dma): call it only through pq_mlkem_keygen / pq_mlkem_decaps_seed
+; (src/crypto/mlkem_link.s).
mlkem_dk_scratch = tcp_recv_buf
MLKEM_DK_SIZE = 2400
+MLKEM_EK_SIZE = 1184 ; ML-KEM-768 encapsulation key
+MLKEM_CT_SIZE = 1088 ; ML-KEM-768 ciphertext
+MLKEM_HYB_SH_KEY = 1120 ; 11EC ServerHello key_exchange: ct || x25519
+MLKEM_SEED_SIZE = 64 ; d || z
+MLKEM_SS_SIZE = 32
+
+; ServerHello refusal codes, tls_sh_err (0 = none). $01 predates the
+; streaming reader; $02-$0E are PQ_HYBRID's (src/crypto/pq_hybrid.s).
+SH_ERR_HRR = $01 ; HelloRetryRequest random
+SH_ERR_RECTYPE = $02 ; non-handshake or empty record mid-message
+SH_ERR_HDR = $03 ; not a ServerHello, or message length out of range
+SH_ERR_FIXED = $04 ; legacy_version / session id / suite / compression
+SH_ERR_EXTLEN = $05 ; extension framing
+SH_ERR_VERSION = $06 ; supported_versions wrong or duplicated
+SH_ERR_GROUP = $07 ; key_share group unknown or not offered
+SH_ERR_KSLEN = $08 ; key_share length wrong for its group, or duplicate
+SH_ERR_TRAIL = $09 ; bytes after the ServerHello
+SH_ERR_MISSING = $0A ; supported_versions or key_share absent
+SH_ERR_PQ_DECAPS = $0B ; ML-KEM Decaps refused
+SH_ERR_PQ_KEYGEN = $0C ; ML-KEM KeyGen refused (set before the ClientHello)
+SH_ERR_EXT = $0D ; an extension we did not request (RFC 8446 4.2)
+SH_ERR_RECORD = $0E ; malformed/oversize record header while waiting for the SH
diff --git a/src/crypto/mlkem_link.s b/src/crypto/mlkem_link.s
index 8cefd00..07a379d 100644
--- a/src/crypto/mlkem_link.s
+++ b/src/crypto/mlkem_link.s
@@ -270,7 +270,7 @@ SQTAB_GUARD "COLD_RUN_TRUST", __COLD_RUN_TRUST_START__, __COLD_RUN_TRUST
; Code (NET_CODE via LOADER_OVERFLOW; always RAM, so the SMC below is legal)
; =============================================================================
.export mlkem_copied
-.export mlkem_boot_init, pq_mlkem_call, pq_mlkem_keygen, pq_mlkem_decaps_seed
+.export mlkem_boot_init, pq_mlkem_call, pq_mlkem_keygen, pq_mlkem_decaps_seed, pq_mlkem_scrub
.segment "LOADER_OVERFLOW"
@@ -390,6 +390,42 @@ pq_mlkem_decaps_seed:
ldx #>mlkem_decaps_seed
jmp pq_mlkem_call
+; pq_mlkem_scrub - zero everything ML-KEM leaves secret: the eight polynomials
+; ($D000-$DFFF: s_hat after KeyGen, y/e1/e2 after Decaps) and the whole rest-BSS
+; window ($B100-$BBFF: m', K', r', the Keccak state; X25519_TABLES shares it and
+; x25519_*_fresh rebuilds it; mul_dma is per-row scratch regenerated before each
+; row reads it, so stale entries are never read). Same banking discipline as
+; pq_mlkem_call: sei, $01 = $34, restored. ~7,000 stores, ~80K cycles.
+; Clobbers A, X, Y, zp_ptr. Preserves the caller's I flag.
+pq_mlkem_scrub:
+ php
+ sei
+ lda $01
+ pha
+ lda #$34
+ sta $01
+ lda #>__MLKEM_POLY_RAM_START__
+ ldx #>__MLKEM_POLY_RAM_SIZE__
+ jsr @zero
+ lda #>__MLKEM_BSS_RAM_START__
+ ldx #>__MLKEM_BSS_RAM_SIZE__
+ jsr @zero
+ pla
+ sta $01
+ plp
+ rts
+@zero: sta zp_ptr+1
+ ldy #0
+ sty zp_ptr
+ tya
+: sta (zp_ptr),y
+ iny
+ bne :-
+ inc zp_ptr+1
+ dex
+ bne :-
+ rts
+
.segment "LIB_MLKEM_MARK"
mlkem_mark:
.byte MLKEM_MARK
diff --git a/src/crypto/pq_hybrid.s b/src/crypto/pq_hybrid.s
new file mode 100644
index 0000000..5a453ad
--- /dev/null
+++ b/src/crypto/pq_hybrid.s
@@ -0,0 +1,569 @@
+; =============================================================================
+; pq_hybrid.s - PQ_HYBRID=1: X25519MLKEM768 client side, PQC plan phase P4.
+; Linked only under PQ_HYBRID=1 (the Makefile filters it out otherwise), so an
+; unset build is byte-identical to one that has never heard of it.
+;
+; pq_connect_prep tls_connect, between the X25519 keypair and the
+; ClientHello: DRBG-fill the 64 B d||z seed, KeyGen, zero
+; the 2,400 B dk at once, arm the sectioned ClientHello
+; with the ek. C=1: refused (tls_sh_err = SH_ERR_PQ_KEYGEN).
+; pq_sh_init start of tls_recv_server_hello.
+; pq_sh_feed once per plaintext record: feed the record's bytes to the
+; ServerHello state machine and fold them into the
+; transcript. C=1: refused (tls_sh_err); C=0 with Z=1: the
+; message is complete; C=0 with Z=0: wait for another record.
+; pq_sh_decaps after the ServerHello (and the drain): if the server chose
+; 11EC, Decaps the ct into tls_mlkem_ss; always scrubs the
+; seed. C=1: refused (SH_ERR_PQ_DECAPS).
+; pq_seed_zero tls_connect's error exit: the seed. pq_secrets_zero (seed + ss)
+; is pq_connect_prep's first step.
+;
+; The ServerHello is NOT buffered. A hybrid one is 1,178 B and a server
+; fragments it under max_fragment_length (OpenSSL: 512 + 512 + 154), while the
+; record buffer is 548 B, so it is read through a byte-at-a-time machine:
+; each state is "gather N bytes to a destination, then run a handler". The
+; handlers check the fields and arm the next state; nothing is held but the
+; 16-bit field count, the 16-bit bytes-left-in-message and a 6 B gather
+; buffer. Every record's bytes are folded into the transcript exactly once,
+; in wire order, right after its bytes were parsed (before the next record
+; overwrites tls_rec_buf, and before X25519_SCRATCH, which overlays it, runs).
+;
+; WHAT IT ACCEPTS (everything else is refused with a distinct tls_sh_err,
+; src/constants.inc): handshake type 2, total length 40..1535; legacy_version
+; ignored (RFC 8446 4.2.1); an EMPTY session id echo (what we sent); suite 1303;
+; compression 0; extension block exactly filling the message; supported_versions
+; = 0304 once; key_share once, group 001D with a 32 B share, or group 11EC with
+; a 1,120 B share (ML-KEM ct 1,088 || x25519 32) and only if the hybrid was
+; offered. Any OTHER extension is refused (SH_ERR_EXT): the ClientHello
+; requests no others (RFC 8446 4.2). The HelloRetryRequest random is a refusal
+; (SH_ERR_HRR). A zero-length record, a non-handshake record mid-message and any
+; byte after the message are refusals.
+;
+; HANDSHAKE ORDER (#152). TLS_HS_SEQ_CHECK derives the one legal type from
+; tls_state and is wired to the post-ServerHello dispatchers; here the first
+; message is checked by the machine's own header state (type must be 2), which
+; is the same rule - the ServerHello is the only legal first message - and a
+; second message type cannot get in, because the length field bounds the
+; machine and DONE refuses every further byte. Reusing the macro would only add
+; its table lookup in front of the same comparison.
+;
+; WHERE THINGS LIVE. ek (1,184 B) and ct (1,088 B) both use cert_buf: the ek is
+; dead once the ClientHello is sent, the ct once Decaps returns, and nothing
+; writes cert_buf between KeyGen and Certificate except the comb cold bank,
+; which refuses to run while tls_state is not IDLE/ERROR. The 64 B seed and the
+; 32 B ML-KEM secret are in NET_BSS_TAIL, below $4200: not cert_buf, not
+; tls_rec_buf (X25519_SCRATCH), not the $B100 ML-KEM window, not $D000-$DFFF,
+; not the TCP ring. src/session_scrub.s zeroes both.
+; =============================================================================
+
+.ifndef PQ_HYBRID
+.error "pq_hybrid.s is PQ_HYBRID-only; the Makefile filters it out otherwise"
+.endif
+
+.include "constants.inc"
+
+.export pq_connect_prep, pq_sh_init, pq_sh_feed, pq_sh_decaps
+.export pq_secrets_zero, pq_seed_zero
+.export tls_pq_seed, tls_mlkem_ss, tls_kex_group, tls_pq_offered
+.export shs_state
+
+.import cert_buf
+.import tls_server_random, tls_server_pubkey
+.import tls_rec_buf, tls_rec_len, tls_rec_type
+.import tls_sh_err, tls_sh_chk_hrr
+.import tls_ch_ks_ptr, tls_ch_ks_len
+.import tls_transcript_update
+.import drbg_fill_bytes
+.import pq_mlkem_keygen, pq_mlkem_decaps_seed, pq_mlkem_scrub
+.import mlkem_arg_ek, mlkem_arg_dk, mlkem_arg_ct, mlkem_arg_key, mlkem_arg_seed, mlkem_arg_z
+.import __NET_BSS_TAIL_START__
+
+; --- Secrets and state (NET_BSS_TAIL: file-backed zero, below cert_buf) ------
+.segment "NET_BSS_TAIL"
+tls_pq_seed: .res MLKEM_SEED_SIZE ; d || z, DRBG output; live KeyGen..Decaps
+tls_mlkem_ss: .res MLKEM_SS_SIZE ; Decaps' K (P5: mlkem_ss || x25519_ss)
+tls_kex_group: .res 1 ; 0 none yet, $1D x25519, $EC hybrid (P5 reads)
+tls_pq_offered: .res 1 ; 1 = this connection's ClientHello offered 11EC
+shs_state: .res 1
+shs_cnt: .res 2 ; bytes left in the current field
+shs_rem: .res 2 ; bytes left in the message after its header
+shs_d: .res 2 ; length of the extension being read
+shs_f: .res 6 ; gather buffer for the small fields
+shs_seen: .res 1 ; bit0 supported_versions, bit1 key_share
+
+; The seed + ss pair is one scrub span (src/session_scrub.s) and must sit in
+; the free tail of the NET_BSS_TAIL region, below cert_buf and clear of every
+; union the ML-KEM, X25519 and P-256 buffers use.
+.assert tls_mlkem_ss = tls_pq_seed + MLKEM_SEED_SIZE, lderror, "tls_mlkem_ss must follow tls_pq_seed (one scrub span)"
+.assert tls_pq_seed >= __NET_BSS_TAIL_START__, lderror, "tls_pq_seed is below NET_BSS_TAIL"
+.assert tls_mlkem_ss + MLKEM_SS_SIZE <= cert_buf, lderror, "PQ secrets overlap cert_buf"
+; pq_set_args writes the library's parameter block as one 12-byte struct.
+.assert mlkem_arg_dk = mlkem_arg_ek + 2, lderror, "mlkem_arg_* is no longer one contiguous struct (dk)"
+.assert mlkem_arg_ct = mlkem_arg_ek + 4, lderror, "mlkem_arg_* is no longer one contiguous struct (ct)"
+.assert mlkem_arg_key = mlkem_arg_ek + 6, lderror, "mlkem_arg_* is no longer one contiguous struct (key)"
+.assert mlkem_arg_seed = mlkem_arg_ek + 8, lderror, "mlkem_arg_* is no longer one contiguous struct (seed)"
+.assert mlkem_arg_z = mlkem_arg_ek + 10, lderror, "mlkem_arg_* is no longer one contiguous struct (z)"
+.assert (tls_pq_seed + MLKEM_SEED_SIZE + MLKEM_SS_SIZE) < $4200, lderror, "PQ secrets are not below $4200"
+
+SS_HDR = 0
+SS_VER = 1
+SS_RND = 2
+SS_FIX = 3
+SS_EXH = 4
+SS_SV = 5
+SS_KSH = 6
+SS_CT = 7
+SS_PUB = 8
+SS_DONE = 9
+
+SHS_MAX_HI = 6 ; message length < 6*256 = 1536
+
+ .segment "PQ_GLUE"
+
+; -----------------------------------------------------------------------------
+; The parameter block. libs/mlkem keeps six 16-bit pointers (ek dk ct key seed
+; z) contiguous in LIB_MLKEM_BSS, a window X25519 rebuilds: fill it after the
+; last X25519 and right before the call. One table serves KeyGen (ek, dk, d, z)
+; and Decaps-from-seed (seed = d||z, ct, key); each ignores the rest.
+; -----------------------------------------------------------------------------
+pq_set_args:
+ ldx #11
+: lda pq_arg_tab,x
+ sta mlkem_arg_ek,x
+ dex
+ bpl :-
+ rts
+pq_arg_tab:
+ .word cert_buf, mlkem_dk_scratch, cert_buf, tls_mlkem_ss
+ .word tls_pq_seed, tls_pq_seed + 32
+
+; pq_secrets_zero / pq_seed_zero: zero seed + ss (96 B) / the seed (64 B).
+pq_secrets_zero:
+ ldx #MLKEM_SEED_SIZE + MLKEM_SS_SIZE
+ bne pq_zero_x
+pq_seed_zero:
+ ldx #MLKEM_SEED_SIZE
+pq_zero_x:
+ lda #0
+: dex
+ sta tls_pq_seed,x
+ bne :-
+ rts
+
+; pq_dk_zero: zero the 2,400 B dk scratch (the TCP ring base).
+pq_dk_zero:
+ lda #mlkem_dk_scratch
+ sta zp_ptr+1
+ ldx #>MLKEM_DK_SIZE
+ ldy #0
+ tya
+: sta (zp_ptr),y
+ iny
+ bne :-
+ inc zp_ptr+1
+ dex
+ bne :-
+: sta (zp_ptr),y ; the last tls_pq_seed
+ sta zp_ptr+1
+ lda #MLKEM_SEED_SIZE
+ jsr drbg_fill_bytes
+ jsr pq_set_args
+ jsr pq_mlkem_keygen ; C=1/A=$FF refused; C=0: A = status
+ pha
+ jsr pq_dk_zero ; BEFORE anything else, success or not
+ jsr pq_mlkem_scrub ; s_hat in $D000 and the sponge/ring residue in the window
+ pla
+ bne @fail ; refusal ($FF) or a non-zero status
+ lda #cert_buf
+ sta tls_ch_ks_ptr+1
+ lda #MLKEM_EK_SIZE
+ sta tls_ch_ks_len+1
+ inc tls_pq_offered
+ clc
+ rts
+@fail: lda #SH_ERR_PQ_KEYGEN
+ sta tls_sh_err
+ sec
+ rts
+
+; -----------------------------------------------------------------------------
+; 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.
+; -----------------------------------------------------------------------------
+pq_sh_decaps:
+ lda tls_kex_group
+ cmp #$EC
+ 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
+ bcs @fail
+ cmp #0
+ bne @fail
+@done: jsr pq_seed_zero
+ clc
+ rts
+@fail: lda #SH_ERR_PQ_DECAPS
+ sta tls_sh_err
+ sec
+ rts
+
+ .segment "PQ_CODE"
+
+; -----------------------------------------------------------------------------
+; The ServerHello machine. State tables, indexed by SS_*: field length, and the
+; destination (high byte 0 = discard).
+; -----------------------------------------------------------------------------
+tab_cl: .byte 4, 2, 32, 6, 4, 2, 4, MLKEM_CT_SIZE, 0, 0
+tab_dl: .byte shs_f, 0, >tls_server_random, >shs_f, >shs_f, >shs_f, >shs_f, >cert_buf, >tls_server_pubkey, 0
+
+; Handlers, entered by RTS-dispatch from shs_byte with the field complete.
+; Out: C=0 (next state armed) or C=1, tls_sh_err set.
+hnd_l: .byte <(h_hdr-1), <(h_ver-1), <(h_rnd-1), <(h_fix-1), <(h_exh-1), <(h_sv-1), <(h_ksh-1), <(h_ct-1), <(h_pub-1)
+hnd_h: .byte >(h_hdr-1), >(h_ver-1), >(h_rnd-1), >(h_fix-1), >(h_exh-1), >(h_sv-1), >(h_ksh-1), >(h_ct-1), >(h_pub-1)
+
+; pq_sh_init - fresh machine, clean error code.
+pq_sh_init:
+ lda #0
+ sta tls_sh_err
+ sta shs_seen
+ sta tls_kex_group
+ lda #SS_HDR
+ ; fall through
+
+; shs_arm - A = state: load its count and destination. Out: C=0.
+shs_arm:
+ sta shs_state
+ tax
+ lda tab_cl,x
+ sta shs_cnt
+ lda tab_ch,x
+ sta shs_cnt+1
+ lda tab_dl,x
+ sta shs_st+1
+ lda tab_dh,x
+ sta shs_st+2
+ clc
+ rts
+
+shs_fail:
+ sta tls_sh_err
+ sec
+ rts
+
+; shs_byte - A = the next ServerHello byte. Out: C=0, or C=1 with tls_sh_err.
+shs_byte:
+ ldx shs_state
+ cpx #SS_DONE
+ bne shs_live
+ lda #SH_ERR_TRAIL
+ bne shs_fail
+shs_live: ldy shs_st+2
+ beq shs_nost
+shs_st: sta $FFFF ; operand patched by shs_arm
+ inc shs_st+1
+ bne shs_nost
+ inc shs_st+2
+shs_nost: cpx #SS_HDR ; the header is not counted in the length
+ beq shs_nodec
+ lda shs_rem
+ bne :+
+ dec shs_rem+1
+: dec shs_rem
+shs_nodec: lda shs_cnt
+ bne :+
+ dec shs_cnt+1
+: dec shs_cnt
+ lda shs_cnt
+ ora shs_cnt+1
+ beq shs_field
+ clc
+ rts
+shs_field: lda hnd_h,x
+ pha
+ lda hnd_l,x
+ pha
+ rts ; "returns" into the handler
+
+; --- handlers ----------------------------------------------------------------
+; Each handler keeps its own error stubs: a branch reaches only +-127 B and the
+; handlers together are ~400 B, so one shared stub block would be out of range.
+h_hdr: lda shs_f ; type
+ cmp #TLS_HS_SERVER_HELLO
+ bne @bad
+ lda shs_f+1 ; length is 24-bit: top byte 0
+ bne @bad
+ lda shs_f+2
+ cmp #SHS_MAX_HI
+ bcs @bad
+ sta shs_rem+1
+ lda shs_f+3
+ sta shs_rem
+ lda shs_rem+1
+ bne @len_ok
+ lda shs_rem
+ cmp #40 ; version 2 + random 32 + fixed 6
+ bcc @bad
+@len_ok:
+ lda #SS_VER
+ jmp shs_arm
+@bad: lda #SH_ERR_HDR
+ jmp shs_fail
+
+h_ver: lda #SS_RND ; legacy_version is ignored (RFC 8446 4.2.1)
+ jmp shs_arm
+
+h_rnd: jsr tls_sh_chk_hrr ; C=1: tls_sh_err = SH_ERR_HRR
+ bcs @hrr
+ lda #SS_FIX
+ jmp shs_arm
+@hrr: lda #SH_ERR_HRR
+ jmp shs_fail
+
+h_fix: lda shs_f ; session id echo length 0
+ bne @bad
+ lda shs_f+1 ; suite 1303
+ cmp #$13
+ bne @bad
+ lda shs_f+2
+ cmp #$03
+ bne @bad
+ lda shs_f+3 ; compression null
+ bne @bad
+ lda shs_f+4 ; extensions_length == what is left
+ cmp shs_rem+1
+ bne @ext
+ lda shs_f+5
+ cmp shs_rem
+ bne @ext
+ jmp ext_next
+@bad: lda #SH_ERR_FIXED
+ jmp shs_fail
+@ext: lda #SH_ERR_EXTLEN
+ jmp shs_fail
+
+; ext_next - the previous extension is complete: another header, or the end.
+ext_next:
+ lda shs_rem
+ ora shs_rem+1
+ bne @more
+ lda shs_seen ; end of message
+ cmp #3
+ bne @missing
+ lda #SS_DONE
+ jmp shs_arm
+@more: lda shs_rem+1
+ bne @hdr
+ lda shs_rem
+ cmp #4
+ bcc @ext
+@hdr: lda #SS_EXH
+ jmp shs_arm
+@missing:
+ lda #SH_ERR_MISSING
+ jmp shs_fail
+@ext: lda #SH_ERR_EXTLEN
+ jmp shs_fail
+
+h_exh: lda shs_f+2 ; D = data length
+ sta shs_d+1
+ lda shs_f+3
+ sta shs_d
+ lda shs_rem ; D must fit in what is left
+ cmp shs_d
+ lda shs_rem+1
+ sbc shs_d+1
+ bcc @ext
+ lda shs_f ; type
+ bne @other
+ lda shs_f+1
+ cmp #$2b
+ beq @sv
+ cmp #$33
+ beq @ks
+@other: lda #SH_ERR_EXT ; we requested only these two (RFC 8446 4.2)
+ jmp shs_fail
+@sv: lda shs_seen
+ and #1
+ bne @ver
+ lda shs_d+1
+ bne @ver
+ lda shs_d
+ cmp #2
+ bne @ver
+ lda #SS_SV
+ jmp shs_arm
+@ks: lda shs_seen
+ and #2
+ bne @kslen
+ lda shs_d+1
+ bne @ks_ok
+ lda shs_d
+ cmp #4
+ bcc @kslen
+@ks_ok: lda #SS_KSH
+ jmp shs_arm
+@ext: lda #SH_ERR_EXTLEN
+ jmp shs_fail
+@ver: lda #SH_ERR_VERSION
+ jmp shs_fail
+@kslen: lda #SH_ERR_KSLEN
+ jmp shs_fail
+
+h_sv: lda shs_f
+ cmp #$03
+ bne @bad
+ lda shs_f+1
+ cmp #$04
+ bne @bad
+ lda shs_seen
+ ora #1
+ sta shs_seen
+ jmp ext_next
+@bad: lda #SH_ERR_VERSION
+ jmp shs_fail
+
+h_ksh: lda shs_f+3 ; key length + 4 must equal D
+ clc
+ adc #4
+ tax
+ lda shs_f+2
+ adc #0
+ cmp shs_d+1
+ bne @kslen
+ cpx shs_d
+ bne @kslen
+ lda shs_f ; group
+ beq @g00
+ cmp #$11
+ bne @grp
+ lda shs_f+1
+ cmp #$ec
+ bne @grp
+ lda tls_pq_offered ; 11EC only if this hello offered it
+ beq @grp
+ lda shs_f+2 ; exactly 1,120
+ cmp #>MLKEM_HYB_SH_KEY
+ bne @kslen
+ lda shs_f+3
+ cmp #tls_rec_buf
+ sta zp_ptr+1
+ lda tls_rec_len
+ sta zp_count
+ lda tls_rec_len+1
+ sta zp_count+1
+@byte: ldy #0
+ lda (zp_ptr),y
+ jsr shs_byte
+ bcs @out
+ inc zp_ptr
+ bne :+
+ inc zp_ptr+1
+: lda zp_count
+ bne :+
+ dec zp_count+1
+: dec zp_count
+ lda zp_count
+ ora zp_count+1
+ bne @byte
+ lda #tls_rec_buf
+ sta zp_ptr+1
+ lda tls_rec_len
+ sta zp_count
+ lda tls_rec_len+1
+ sta zp_count+1
+ jsr tls_transcript_update
+ clc
+ lda shs_state
+ eor #SS_DONE ; Z=1: complete; C stays 0
+@out: rts
diff --git a/src/session_scrub.s b/src/session_scrub.s
index 2b44902..f70caaf 100644
--- a/src/session_scrub.s
+++ b/src/session_scrub.s
@@ -56,6 +56,10 @@
; caller forgot to zero it (the ring
; is otherwise ciphertext, not
; scrubbed).
+; tls_pq_seed..tls_mlkem_ss+32, 96 B the 64 B d||z seed (secret from KeyGen
+; until Decaps) and the 32 B ML-KEM
+; shared secret (src/crypto/pq_hybrid.s;
+; NET_BSS_TAIL, one adjacent pair).
;
; The multi-buffer spans zero whatever their module declares between the
; two ends, so each length is asserted exactly: a field added inside a span
@@ -109,6 +113,7 @@
.ifdef PQ_HYBRID
.import mul38_lo_tab
.import __LIB_MLKEM_POLY_BSS_RUN__, __LIB_MLKEM_POLY_BSS_SIZE__
+ .import tls_pq_seed, tls_mlkem_ss
.endif
.import drbg_init_entropy
@@ -187,6 +192,7 @@ scrub_spans:
SPAN mul38_lo_tab, mul_dma_hi + 256, 2816
SPAN __LIB_MLKEM_POLY_BSS_RUN__, __LIB_MLKEM_POLY_BSS_RUN__ + __LIB_MLKEM_POLY_BSS_SIZE__, 4096
SPAN tcp_recv_buf, tcp_recv_buf + MLKEM_DK_SIZE, 2400
+ SPAN tls_pq_seed, tls_mlkem_ss + 32, 96
.else
SPAN mul_dma_lo, mul_dma_hi + 256, 512
.endif
diff --git a/src/tls13.s b/src/tls13.s
index 36b777e..5fd2d4d 100644
--- a/src/tls13.s
+++ b/src/tls13.s
@@ -71,7 +71,12 @@
; --- ClientHello / ServerHello builders & parsers (tls_handshake) ---
.import tls_build_client_hello
+.ifndef PQ_HYBRID
.import tls_parse_server_hello
+.else
+.import tls_sh_err
+.import pq_connect_prep, pq_sh_init, pq_sh_feed, pq_sh_decaps, pq_seed_zero
+.endif
.ifdef CH_SECTIONED
.import tls_ch_ks_ptr
.import tls_ch_ks_len
@@ -175,6 +180,12 @@ tls_connect:
; --- send ClientHello ---
lda #TLS_STATE_CLIENT_HELLO
sta tls_state
+.ifdef PQ_HYBRID
+ jsr pq_connect_prep ; KeyGen + arm the hybrid key share (C=1: refused)
+ bcc :+
+ jmp @error
+:
+.endif
jsr tls_send_client_hello
bcc @ok1
jmp @error
@@ -332,6 +343,10 @@ tls_connect:
rts
@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)
+.endif
lda tls_state ; preserve last attempted state
bmi :+ ; already ERROR: the record layer aborted
; (#239) and recorded the state itself
@@ -438,12 +453,13 @@ tls_close:
; before any max_fragment_length agreement (MFL, RFC 6066 4), so the 2^14
; record bound applies to it and a ~1.4 KB hello is a legal single record
; with no reassembly needed in the peer.
-; Arming contract: set tls_ch_ks_ptr/len immediately before jsr tls_connect,
-; i.e. after DNS and TCP connect succeeded. tls_connect reaches this routine
-; with no branch in between, and the sectioned sender clears the length on
-; every exit (success or send failure), so nothing stays armed past one
-; ClientHello. A clear at tls_connect ENTRY cannot help: the caller arms
-; before the call, so an entry clear would also discard a fresh arm.
+; Arming: under PQ_HYBRID=1 tls_connect arms tls_ch_ks_ptr/len itself
+; (pq_connect_prep, src/crypto/pq_hybrid.s: KeyGen, then the ek in cert_buf)
+; between the X25519 keypair and this routine, with no branch in between. No
+; caller arms anything, and there is no build in which one does. The sectioned
+; sender clears the length on every exit (success or send failure), so nothing
+; stays armed past one ClientHello. A clear at tls_connect ENTRY would be
+; harmless now (nothing is armed before it) but buys nothing.
; =============================================================================
tls_send_client_hello:
; initialize transcript hash
@@ -592,6 +608,9 @@ ch_sec_ptr: .res 2
tls_recv_server_hello:
lda #$01
sta tls_recv_progress
+.ifdef PQ_HYBRID
+ jsr pq_sh_init ; the streaming reader (src/crypto/pq_hybrid.s)
+.endif
lda #0
sta sh_timeout
sta sh_timeout+1
@@ -605,6 +624,15 @@ tls_recv_server_hello:
jsr net_poll
jsr tls_record_recv_and_decrypt
bcc @sh_got_record
+.ifdef PQ_HYBRID
+ bit tls_state ; ERROR latched: a malformed or oversize
+ bpl :+ ; record header while waiting for the SH
+ lda #SH_ERR_RECORD ; (a hybrid SH sent as ONE record does
+ sta tls_sh_err ; not fit tls_rec_buf): fail now, do not
+ sec ; resync through the payload for ~43 min
+ rts
+:
+.endif
inc sh_timeout
bne @sh_wait
inc sh_timeout+1
@@ -615,6 +643,20 @@ tls_recv_server_hello:
@sh_got_record:
lda #$02
sta tls_recv_progress
+.ifdef PQ_HYBRID
+ ; PQ_HYBRID: a hybrid ServerHello is ~1.2 KB and a server sends it as
+ ; several plaintext handshake records (OpenSSL under MFL 512: 512 +
+ ; 512 + 154). pq_sh_feed streams this record's bytes through the
+ ; ServerHello machine and folds them into the transcript (so this is
+ ; the last read of tls_rec_buf for the record, as below). Z=1: the
+ ; message is complete; Z=0: wait for the next record (the failed-poll
+ ; budget is shared by the whole message, like tls_recv_encrypted's).
+ jsr pq_sh_feed
+ bcs @sh_error
+ bne @sh_wait ; Z=0: more records; ONE timeout budget for the whole SH
+ lda #$05
+ sta tls_recv_progress
+.else
; verify content type is handshake
lda tls_rec_type
cmp #TLS_CT_HANDSHAKE
@@ -654,6 +696,8 @@ tls_recv_server_hello:
sta zp_count+1
jsr tls_transcript_update
+.endif
+
; Drain frames already at the NIC and ACK them BEFORE the
; multi-minute ECDHE stall. The server's post-SH flight is on
; the wire/in the chip by now (it splits at the 512 B default
@@ -697,6 +741,13 @@ tls_recv_server_hello:
; C=1 means the server's key_share drove the shared secret to all
; zeros (RFC 8446 §7.4.2 / RFC 7748 §6.1) — abort, see the comment in
; src/tls_ecdh.s. This used to be an unconditional `clc`.
+ ; PQ_HYBRID: the server chose 11EC -> Decaps its ct now, BEFORE the
+ ; X25519 mult: the ML-KEM BSS overlays X25519_TABLES, which the
+ ; x25519_*_fresh entries rebuild. C=1: refused.
+.ifdef PQ_HYBRID
+ jsr pq_sh_decaps
+ bcs @sh_error
+.endif
jsr tls_ecdh_compute_shared
bcs @sh_error
diff --git a/src/tls_handshake.s b/src/tls_handshake.s
index edf6529..c9d2b97 100644
--- a/src/tls_handshake.s
+++ b/src/tls_handshake.s
@@ -16,7 +16,9 @@
; --- Exports ---
.export tls_build_client_hello
+.ifndef PQ_HYBRID
.export tls_parse_server_hello
+.endif
.export tls_parse_encrypted_extensions
.export tls_hostname
.export tls_hostname_len
@@ -251,6 +253,11 @@ ch_put_pub:
+; PQ_HYBRID: the single-record parser below is replaced by the streaming
+; reader in src/crypto/pq_hybrid.s (a hybrid ServerHello is ~1.2 KB and
+; arrives in several records), so it is assembled out there: the LOADER bytes
+; go to the glue that calls the reader.
+.ifndef PQ_HYBRID
; =============================================================================
; tls_parse_server_hello - parse ServerHello message
;
@@ -484,6 +491,8 @@ tls_parse_server_hello:
rts
+.endif ; !PQ_HYBRID
+
; =============================================================================
; tls_sh_chk_hrr - is tls_server_random the HelloRetryRequest magic?
; Out: C=1 and tls_sh_err = SH_ERR_HRR if so, else C=0 (tls_sh_err is
@@ -491,8 +500,6 @@ tls_parse_server_hello:
; ip65: CODE (LOADER has room, the CRYPTO_OVERLAY pool does not); UCI:
; TLS_CODE (uci-comb-demo-store's LOADER would be left with 5 B).
; =============================================================================
-SH_ERR_HRR = $01
-
.ifdef TLS_STREAM_DEFRAME
.segment "TLS_CODE"
.endif
@@ -536,8 +543,10 @@ tls_parse_encrypted_extensions:
; =============================================================================
.segment "BSS"
+.ifndef PQ_HYBRID
sh_found_ver: .res 1
sh_found_ks: .res 1
+.endif
; Optional bulk key-share section for the ClientHello (see
; tls_build_client_hello). BSS is zeroed at boot, so the default is
diff --git a/src/tls_record_io.s b/src/tls_record_io.s
index b6b4f2d..aea45d3 100644
--- a/src/tls_record_io.s
+++ b/src/tls_record_io.s
@@ -492,7 +492,11 @@ tls_rec_decrypt_chk:
tls_rec_frame_fail:
jsr tls_rec_reader_reset
lda tls_state
+.ifdef PQ_HYBRID
+ cmp #TLS_STATE_SERVER_HELLO ; a hybrid SH is read record by record: a bad
+.else ; header while waiting for it is fatal too
cmp #TLS_STATE_ENCRYPTED_EXT
+.endif
bcc tls_rec_fail_ret ; plaintext phase: resync, not fatal
lda #$0C ; sub-progress: bad/short header after keys
bne tls_rec_latch ; always
diff --git a/tools/_pq_testlib.py b/tools/_pq_testlib.py
new file mode 100644
index 0000000..b765727
--- /dev/null
+++ b/tools/_pq_testlib.py
@@ -0,0 +1,305 @@
+"""tools/_pq_testlib.py - shared pieces of the PQ_HYBRID P4 suites.
+
+ test_pq_sh.py the ServerHello machine, fast (no ML-KEM, no X25519)
+ test_pq_kem.py KeyGen / Decaps / the full tls_recv_server_hello path, slow
+
+Not a test module (no test_ prefix, no run_tests): helpers only.
+"""
+
+import hashlib
+import os
+import struct
+import subprocess
+import sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO / "tools"))
+sys.path.insert(0, str(REPO / "libs" / "mlkem" / "tools"))
+
+from c64_test_harness import ( # noqa: E402
+ Labels, ViceInstanceManager, jsr, read_bytes, write_bytes, wait_for_text,
+)
+from _vice_helpers import default_vice_config, menu_wait # noqa: E402
+
+PRG = REPO / "build" / "c64-https.prg"
+LABELS = REPO / "build" / "labels.txt"
+PQ_ARGS = ["BACKEND=uci", "USE_NISTCURVES_ONCHIP=1", "PQ_HYBRID=1"]
+
+# tls_sh_err codes (src/constants.inc)
+E_HRR, E_RECTYPE, E_HDR, E_FIXED, E_EXTLEN = 1, 2, 3, 4, 5
+E_VERSION, E_GROUP, E_KSLEN, E_TRAIL, E_MISSING = 6, 7, 8, 9, 10
+E_DECAPS, E_KEYGEN, E_EXT, E_RECORD = 11, 12, 13, 14
+
+HRR_MAGIC = bytes.fromhex(
+ "cf21ad74e59a6111be1d8c021e65b891c2a211167abb8c5e079e09e2c8a8339c")
+GROUP_HYB, GROUP_X = 0x11EC, 0x001D
+CT_LEN, EK_LEN = 1088, 1184
+
+
+class Tally:
+ def __init__(self):
+ self.passed = self.failed = 0
+
+ def check(self, ok, what, detail=""):
+ if ok:
+ self.passed += 1
+ print(f" PASS {what}")
+ else:
+ self.failed += 1
+ print(f" FAIL {what}" + (f": {detail}" if detail else ""))
+ if os.environ.get("C64_FAIL_FAST") == "1": # tools/mutate_pq_sh.py
+ sys.stdout.flush()
+ raise SystemExit(1)
+ return ok
+
+
+def make(args=None, extra=(), clean=True):
+ if clean:
+ subprocess.run(["make", "clean"], cwd=REPO, capture_output=True)
+ r = subprocess.run(["make"] + list(args or PQ_ARGS) + list(extra), cwd=REPO,
+ capture_output=True, text=True)
+ return r.returncode, r.stdout + r.stderr
+
+
+def require_pq_image():
+ """None if build/ holds a PQ_HYBRID P4 image, else the reason it does not
+ (callers route it to cannot_run: exit 2, never a KeyError traceback)."""
+ if not PRG.exists() or not LABELS.exists():
+ return f"{PRG} / {LABELS} missing: build with PQ_HYBRID=1 first"
+ names = set()
+ for ln in LABELS.read_text().splitlines():
+ p = ln.split()
+ if len(p) >= 3:
+ names.add(p[2].lstrip("."))
+ for n in ("pq_sh_feed", "pq_connect_prep", "pq_mlkem_scrub"):
+ if n not in names:
+ return (f"the build in build/ is not a PQ_HYBRID=1 P4 image (no {n}); "
+ "build BACKEND=uci USE_NISTCURVES_ONCHIP=1 PQ_HYBRID=1")
+ return None
+
+
+def build_or_reuse():
+ """Build the PQ uci-onchip image unless C64_SKIP_BUILD=1 (the suite then
+ reuses build/, which must be that image)."""
+ if os.environ.get("C64_SKIP_BUILD") == "1" and PRG.exists():
+ return 0, ""
+ return make()
+
+
+# --------------------------------------------------------------------------
+# ServerHello builders
+# --------------------------------------------------------------------------
+def ext(t, data):
+ return struct.pack(">HH", t, len(data)) + data
+
+
+def sv_ext(v=b"\x03\x04"):
+ return ext(0x2B, v)
+
+
+def ks_ext(group, key):
+ return ext(0x33, struct.pack(">HH", group, len(key)) + key)
+
+
+def sh_message(exts, random=None, version=b"\x03\x03", sid=b"", suite=b"\x13\x03",
+ comp=b"\x00", hdr_type=2, ext_len=None, msg_len=None, len_top=0):
+ """A ServerHello handshake message; every field overridable so a refusal
+ case can break exactly one thing."""
+ if random is None:
+ random = bytes((7 * i + 3) & 255 for i in range(32))
+ el = len(exts) if ext_len is None else ext_len
+ body = (version + random + bytes([len(sid)]) + sid + suite + comp
+ + struct.pack(">H", el) + exts)
+ ml = len(body) if msg_len is None else msg_len
+ return bytes([hdr_type, len_top]) + struct.pack(">H", ml) + body
+
+
+def split_at(data, cuts, maxrec=512):
+ """Records: data cut at *cuts* (sorted offsets), each piece further cut
+ into <= maxrec bytes."""
+ out, prev = [], 0
+ for c in list(cuts) + [len(data)]:
+ piece = data[prev:c]
+ for i in range(0, len(piece), maxrec):
+ out.append(piece[i:i + maxrec])
+ prev = c
+ return out
+
+
+def chunks(data, sizes):
+ """Cut *data* into pieces of the given sizes (the last size repeats)."""
+ out, i, k = [], 0, 0
+ while i < len(data):
+ n = sizes[min(k, len(sizes) - 1)]
+ out.append(data[i:i + n])
+ i += n
+ k += 1
+ return out
+
+
+# --------------------------------------------------------------------------
+# X25519 (RFC 7748), host side
+# --------------------------------------------------------------------------
+_P = 2 ** 255 - 19
+
+
+def x25519(k, u):
+ k = bytearray(k)
+ k[0] &= 248
+ k[31] &= 127
+ k[31] |= 64
+ k = int.from_bytes(k, "little")
+ x1 = int.from_bytes(u, "little") & ((1 << 255) - 1)
+ x2, z2, x3, z3, swap = 1, 0, x1, 1, 0
+ for t in reversed(range(255)):
+ kt = (k >> t) & 1
+ swap ^= kt
+ if swap:
+ x2, x3, z2, z3 = x3, x2, z3, z2
+ swap = kt
+ a = (x2 + z2) % _P
+ aa = a * a % _P
+ b = (x2 - z2) % _P
+ bb = b * b % _P
+ e = (aa - bb) % _P
+ c = (x3 + z3) % _P
+ d = (x3 - z3) % _P
+ da = d * a % _P
+ cb = c * b % _P
+ x3 = (da + cb) ** 2 % _P
+ z3 = x1 * ((da - cb) ** 2) % _P
+ x2 = aa * bb % _P
+ z2 = e * (aa + 121665 * e) % _P
+ if swap:
+ x2, x3, z2, z3 = x3, x2, z3, z2
+ return (x2 * pow(z2, _P - 2, _P) % _P).to_bytes(32, "little")
+
+
+def x25519_pub(sk):
+ return x25519(sk, (9).to_bytes(32, "little"))
+
+
+# --------------------------------------------------------------------------
+# VICE session
+# --------------------------------------------------------------------------
+class Session:
+ """One VICE boot of the PQ image with the page-3 call stub."""
+ RES = 0x03B0 # +0 A, +1 P after the call
+ STUB = 0x03C0
+
+ def __init__(self, prg=PRG, reu=True):
+ self.labels = Labels.from_file(str(LABELS))
+ self.config = default_vice_config(prg_path=str(prg), warp=True,
+ ntsc=True, sound=False)
+ self.mgr = None
+ self.tr = None
+
+ def __enter__(self):
+ self.mgr = ViceInstanceManager(config=self.config)
+ self.mgr.__enter__()
+ self.inst = self.mgr.acquire()
+ self.tr = self.inst.transport
+ if wait_for_text(self.tr, "Q=QUIT", timeout=menu_wait(60),
+ verbose=False) is None:
+ raise RuntimeError("the menu never appeared")
+ return self
+
+ def __exit__(self, *exc):
+ try:
+ self.mgr.release(self.inst)
+ finally:
+ self.mgr.__exit__(*exc)
+
+ def L(self, name):
+ return self.labels[name]
+
+ def rd(self, addr, n):
+ return bytes(read_bytes(self.tr, addr, n))
+
+ def wr(self, addr, data):
+ write_bytes(self.tr, addr, bytes(data))
+
+ def call(self, name, timeout=900.0):
+ """jsr *name*; return (A, P)."""
+ w = self.L(name)
+ stub = bytes([0x20, w & 255, w >> 8,
+ 0x8D, self.RES & 255, self.RES >> 8,
+ 0x08, 0x68,
+ 0x8D, (self.RES + 1) & 255, self.RES >> 8,
+ 0x60])
+ self.wr(self.STUB, stub)
+ jsr(self.tr, self.STUB, timeout=timeout)
+ a, p = self.rd(self.RES, 2)
+ return a, p
+
+ def call_port(self, name, iflag, timeout=1800.0):
+ """jsr *name* entered with the I flag clear (iflag=0, cli) or set
+ (iflag=1, sei). Returns (A, P_after, port_after): P and $01 as the
+ routine left them. NOTE: a routine that leaks $01 = $34 AND leaves I
+ clear livelocks on the first IRQ (the RTI vector acknowledges nothing),
+ so callers check $01 under iflag=1 first and only then enter with I clear. The explicit restore checks of pq_mlkem_scrub's
+ callers read these (a leaked $01 = $34 or I flag fails an assertion
+ instead of hanging the next monitor access)."""
+ w = self.L(name)
+ r = self.RES
+ stub = bytes([0x78 if iflag else 0x58,
+ 0x20, w & 255, w >> 8,
+ 0x8D, r & 255, r >> 8, # sta RES (A)
+ 0x08, 0x68, # php / pla
+ 0x8D, (r + 1) & 255, r >> 8, # sta RES+1 (P)
+ 0xA5, 0x01, # lda $01
+ 0x8D, (r + 2) & 255, r >> 8, # sta RES+2
+ 0x60])
+ self.wr(self.STUB, stub)
+ jsr(self.tr, self.STUB, timeout=timeout)
+ a, p, port = self.rd(r, 3)
+ return a, p, port
+
+ # --- the reader's state, as the tests see it ---
+ def feed(self, rec, rtype=0x16):
+ """Put *rec* in the record buffer and run pq_sh_feed. Returns
+ (carry, zero)."""
+ assert len(rec) <= 548
+ self.wr(self.L("tls_rec_buf"), rec)
+ self.wr(self.L("tls_rec_len"), [len(rec) & 255, len(rec) >> 8])
+ self.wr(self.L("tls_rec_type"), [rtype])
+ a, p = self.call("pq_sh_feed")
+ return p & 1, (p >> 1) & 1
+
+ def begin(self, offered=True):
+ self.call("tls_transcript_init")
+ self.wr(self.L("tls_pq_offered"), [1 if offered else 0])
+ self.call("pq_sh_init")
+
+ # RAM under the I/O page and the ROMs: bank to all-RAM around the access
+ def ram_rd(self, addr, n):
+ old = self.rd(1, 1)
+ self.wr(1, b"\x34")
+ try:
+ return self.rd(addr, n)
+ finally:
+ self.wr(1, old)
+
+ def ram_wr(self, addr, data):
+ old = self.rd(1, 1)
+ self.wr(1, b"\x34")
+ try:
+ self.wr(addr, data)
+ finally:
+ self.wr(1, old)
+
+ def err(self):
+ return self.rd(self.L("tls_sh_err"), 1)[0]
+
+ def group(self):
+ return self.rd(self.L("tls_kex_group"), 1)[0]
+
+ def transcript(self):
+ self.call("tls_transcript_hash")
+ return self.rd(self.L("tls_transcript"), 32)
+
+
+def ref_secret_pair(seed_d, seed_z):
+ import mlkem_ref as R
+ return R.mlkem_keygen(seed_d, seed_z)
diff --git a/tools/https_e2e/openssl_listener.py b/tools/https_e2e/openssl_listener.py
new file mode 100644
index 0000000..864212f
--- /dev/null
+++ b/tools/https_e2e/openssl_listener.py
@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""openssl_listener.py - an OpenSSL 3.5+ `s_server` for the PQ_HYBRID rigs.
+
+Python's ssl module (and macOS /usr/bin/openssl, which is LibreSSL) cannot do
+X25519MLKEM768; Homebrew's openssl@3 can. This launches its `s_server` with the
+repo's throwaway P-256 test certificate (tools/https_e2e/ensure_certs.py),
+TLS 1.3, the one suite this client offers, a chosen group list, a key log, and a
+reply to GET (sent through s_server's stdin) carrying the body
+tools/uci/rig_https_local.py expects.
+
+ openssl_listener.py --groups X25519 --port 4433 --keylog /tmp/k.log
+ openssl_listener.py --groups X25519MLKEM768 ...
+
+Prints "LISTENING " once the server accepts, then runs
+until killed. Group selection is the server's whole policy: under
+`-groups X25519` it answers 001D to a hybrid ClientHello, under
+`-groups X25519MLKEM768` it answers 11EC (a 1,120 B key_exchange).
+"""
+
+import argparse
+import os
+import pty
+import select
+import termios
+import shutil
+import signal
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+
+# Sent through s_server's own stdin once the request line arrives: the
+# interactive server forwards stdin lines to the peer, and `Q` closes the
+# connection. (-HTTP/-WWW cannot serve "GET /": they open the empty file name.)
+BODY = (b"HTTP/1.0 200 OK\r\nContent-Length: 22\r\n\r\nHELLO FROM TLS SERVER\n")
+
+
+def find_openssl():
+ cands = [os.environ.get("OPENSSL"), "/opt/homebrew/opt/openssl@3/bin/openssl",
+ "/usr/local/opt/openssl@3/bin/openssl", shutil.which("openssl")]
+ for c in cands:
+ if c and Path(c).exists():
+ out = subprocess.run([c, "version"], capture_output=True, text=True).stdout
+ if out.startswith("OpenSSL 3."):
+ return c, out.strip()
+ raise SystemExit("no OpenSSL 3.x `openssl` found (macOS /usr/bin/openssl is LibreSSL); "
+ "brew install openssl@3 or set OPENSSL=")
+
+
+def main(argv=None):
+ ap = argparse.ArgumentParser()
+ ap.add_argument("--groups", default="X25519MLKEM768:X25519")
+ ap.add_argument("--port", type=int, default=4433)
+ ap.add_argument("--keylog", required=True)
+ ap.add_argument("--bind", default="0.0.0.0")
+ a = ap.parse_args(argv)
+ from ensure_certs import ensure_certs
+ cert, key = ensure_certs("p256")
+ exe, ver = find_openssl()
+ 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"]
+ # 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()
+ # canonical mode (s_server parses the `Q` line) but no CR/LF translation,
+ # so the CRLFs of the HTTP response reach the peer as written
+ attrs = termios.tcgetattr(slave)
+ attrs[0] &= ~(termios.ICRNL | termios.INLCR | termios.IGNCR)
+ attrs[1] &= ~termios.OPOST
+ attrs[3] &= ~termios.ECHO
+ termios.tcsetattr(slave, termios.TCSANOW, attrs)
+ proc = subprocess.Popen(cmd, stdin=slave, stdout=slave, stderr=slave, close_fds=True)
+ os.close(slave)
+
+ def stop(*_):
+ proc.terminate()
+ signal.signal(signal.SIGTERM, stop)
+ signal.signal(signal.SIGINT, stop)
+ # LISTENING only when s_server itself reports it is accepting ("ACCEPT"
+ # on its console). Probing the port instead would "succeed" against a
+ # foreign process already holding it, with our s_server dead behind it.
+ boot = b""
+ deadline = time.monotonic() + 15
+ while b"ACCEPT" not in boot:
+ if proc.poll() is not None or time.monotonic() > deadline \
+ or b"Address already in use" in boot or b"unable to bind" in boot:
+ proc.terminate()
+ sys.stderr.write(boot.decode("latin-1") + "\nERROR: s_server is not listening on "
+ f"{a.bind}:{a.port} (port in use, or it died)\n")
+ return 2
+ r, _, _ = select.select([master], [], [], 0.2)
+ if r:
+ try:
+ boot += os.read(master, 4096)
+ except OSError:
+ pass
+ sys.stdout.write(boot.decode("latin-1").replace("\r\n", "\n"))
+ print(f"LISTENING {a.port} {ver} groups={a.groups}", flush=True)
+ buf = b""
+ try:
+ while True:
+ try:
+ chunk = os.read(master, 4096)
+ except OSError:
+ break
+ if not chunk:
+ break
+ sys.stdout.write(chunk.decode("latin-1").replace("\r\n", "\n"))
+ sys.stdout.flush()
+ buf += chunk
+ if b"GET " in buf:
+ buf = b""
+ os.write(master, BODY + b"Q\n")
+ finally:
+ proc.terminate()
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/mutate_pq_sh.py b/tools/mutate_pq_sh.py
new file mode 100644
index 0000000..b07cb4a
--- /dev/null
+++ b/tools/mutate_pq_sh.py
@@ -0,0 +1,299 @@
+#!/usr/bin/env python3
+"""mutate_pq_sh.py - break each check of the PQ_HYBRID P4 code, prove a test notices.
+
+For every mutant: the source file is edited in place (the edit must match
+exactly once), the PQ image is rebuilt from clean, and the named suite runs
+with C64_FAIL_FAST=1. The mutant is KILLED if the suite exits non-zero; a
+mutant that builds and passes is a hole in the tests (SURVIVED) and a mutant
+that does not build is reported BUILD-FAIL (not a kill: the check was not
+what stopped it). Every edited file is restored in a finally block and the
+control is rebuilt and re-run at the end.
+
+ python3 tools/mutate_pq_sh.py # all mutants
+ python3 tools/mutate_pq_sh.py M03 M11 # some
+ python3 tools/mutate_pq_sh.py --list
+ python3 tools/mutate_pq_sh.py --no-control ... # skip the green control runs
+
+Needs a toolchain and VICE; ~2-4 min per mutant (the kem suites are slow).
+Builds in THIS checkout (overwrites build/): run it in a scratch worktree.
+"""
+
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+PQ_ARGS = ["BACKEND=uci", "USE_NISTCURVES_ONCHIP=1", "PQ_HYBRID=1"]
+
+H = "src/crypto/pq_hybrid.s"
+T13 = "src/tls13.s"
+SCR = "src/session_scrub.s"
+
+# (id, what it breaks, file, old, new, suite command)
+SH = ["tools/test_pq_sh.py"]
+SH1 = ["tools/test_pq_sh.py", "1"]
+SH2 = ["tools/test_pq_sh.py", "2"]
+SH3 = ["tools/test_pq_sh.py", "3"]
+SH4 = ["tools/test_pq_sh.py", "4"]
+KEM = ["tools/test_pq_kem.py"]
+
+
+SCRUB_BODY = """pq_mlkem_scrub:
+ php
+ sei
+ lda $01
+ pha
+ lda #$34
+ sta $01
+ lda #>__MLKEM_POLY_RAM_START__
+ ldx #>__MLKEM_POLY_RAM_SIZE__
+ jsr @zero
+ lda #>__MLKEM_BSS_RAM_START__
+ ldx #>__MLKEM_BSS_RAM_SIZE__
+ jsr @zero
+ pla
+ sta $01
+ plp
+ rts
+@zero:"""
+
+
+def nop(n):
+ return " nop\n" * n
+
+
+MUTANTS = [
+ ("M01", "key_exchange length: the low byte of 1,120 is not checked", H,
+ " lda shs_f+3\n cmp #MLKEM_HYB_SH_KEY\n bne @kslen\n",
+ " cmp #>MLKEM_HYB_SH_KEY\n" + nop(2), SH2),
+ ("M03", "group: the 11EC low byte is not checked", H,
+ " lda shs_f+1\n cmp #$ec\n bne @grp\n",
+ " lda shs_f+1\n cmp #$ec\n" + nop(2), SH2),
+ ("M04", "group: the 11EC high byte is not checked", H,
+ " cmp #$11\n bne @grp\n", " cmp #$11\n" + nop(2), SH2),
+ ("M05", "group: the 001D low byte is not checked", H,
+ "@g00: lda shs_f+1\n cmp #$1d\n bne @grp\n",
+ "@g00: lda shs_f+1\n cmp #$1d\n" + nop(2), SH2),
+ ("M06", "group: 11EC accepted although it was not offered", H,
+ " lda tls_pq_offered ; 11EC only if this hello offered it\n beq @grp\n",
+ " lda tls_pq_offered\n" + nop(2), SH2),
+ ("M07", "001D share length: the low byte is not checked", H,
+ " lda shs_f+3\n cmp #32\n bne @kslen\n",
+ " lda shs_f+3\n cmp #32\n" + nop(2), SH2),
+ ("M08", "ct copy bound: one byte too many", H,
+ "tab_cl: .byte 4, 2, 32, 6, 4, 2, 4, tls_rec_buf\n sta zp_ptr+1\n lda tls_rec_len\n sta zp_count\n lda tls_rec_len+1\n sta zp_count+1\n jsr tls_transcript_update\n clc\n lda shs_state\n", SH1),
+ ("M13", "transcript: the fold stops one byte short", H,
+ " lda tls_rec_len\n sta zp_count\n lda tls_rec_len+1\n sta zp_count+1\n jsr tls_transcript_update",
+ " lda tls_rec_len\n sec\n sbc #1\n sta zp_count\n lda tls_rec_len+1\n sta zp_count+1\n jsr tls_transcript_update", SH1),
+ ("M14", "fragmenting: the field counter does not borrow across 256", H,
+ " bne :+\n dec shs_cnt+1\n: dec shs_cnt\n",
+ " bne :+\n" + nop(2) + ": dec shs_cnt\n", SH1),
+ ("M15", "fragmenting: the record byte count does not borrow across 256", H,
+ " bne :+\n dec zp_count+1\n: dec zp_count\n",
+ " bne :+\n" + nop(2) + ": dec zp_count\n", SH1),
+ ("M16", "fragmenting: the message-left counter does not borrow", H,
+ " bne :+\n dec shs_rem+1\n: dec shs_rem\n",
+ " bne :+\n" + nop(2) + ": dec shs_rem\n", SH1),
+ ("M17", "Decaps outcome ignored (refusal and status)", H,
+ " bcs @fail\n cmp #0\n bne @fail\n@done: jsr pq_seed_zero\n",
+ nop(5) + "@done: jsr pq_seed_zero\n", SH3),
+ ("M18", "dk scratch: the tail loop bound is wrong", H,
+ " cpy #MLKEM_DK_SIZE\n", " ldx #(>MLKEM_DK_SIZE)-1\n", SH3),
+ ("M20", "dk scratch: not zeroed on a KeyGen that was refused", H,
+ " jsr pq_mlkem_keygen ; C=1/A=$FF refused; C=0: A = status\n pha\n jsr pq_dk_zero ; BEFORE anything else, success or not\n",
+ " jsr pq_mlkem_keygen\n cmp #0\n bne @fail\n pha\n jsr pq_dk_zero\n", SH3),
+ ("M21", "KeyGen status ignored: a refused KeyGen still arms", H,
+ " pla\n bne @fail ; refusal ($FF) or a non-zero status\n",
+ " pla\n" + nop(2), SH3),
+ ("M22", "the ek length armed is off by one", H,
+ " lda #__MLKEM_POLY_RAM_SIZE__\n", " ldx #(>__MLKEM_POLY_RAM_SIZE__)-1\n", SH + ["5"]),
+ ("M52", "the scrub misses the last window page", "src/crypto/mlkem_link.s",
+ " ldx #>__MLKEM_BSS_RAM_SIZE__\n", " ldx #(>__MLKEM_BSS_RAM_SIZE__)-1\n", SH + ["5"]),
+ ("M53", "a malformed record header while waiting for the SH is not fatal", "src/tls_record_io.s",
+ " cmp #TLS_STATE_SERVER_HELLO ; a hybrid SH is read record by record: a bad\n",
+ " cmp #TLS_STATE_ENCRYPTED_EXT\n", KEM + ["oversize"]),
+ ("M54", "the oversize-record refusal sets no tls_sh_err", T13,
+ " sta tls_sh_err ; not fit tls_rec_buf): fail now, do not\n", nop(3), KEM + ["oversize"]),
+ ("M55", "001D key length: the high byte is not checked", H,
+ " lda shs_f+2 ; exactly 32\n bne @kslen\n", " lda shs_f+2\n" + nop(2), SH2),
+ ("Y3", "pq_mlkem_scrub does not restore $01", "src/crypto/mlkem_link.s",
+ " jsr @zero\n pla\n sta $01\n plp\n rts\n@zero:",
+ " jsr @zero\n pla\n" + nop(2) + " plp\n rts\n@zero:", SH + ["5"]),
+ ("Y4", "pq_mlkem_scrub does not save/restore the I flag", "src/crypto/mlkem_link.s",
+ SCRUB_BODY,
+ SCRUB_BODY.replace("pq_mlkem_scrub:\n php\n", "pq_mlkem_scrub:\n nop\n")
+ .replace(" sta $01\n plp\n rts\n@zero:", " sta $01\n nop\n rts\n@zero:"), SH + ["5"]),
+ ("Y3p", "$01 leaks out of the post-KeyGen scrub", "src/crypto/mlkem_link.s",
+ " jsr @zero\n pla\n sta $01\n plp\n rts\n@zero:",
+ " jsr @zero\n pla\n" + nop(2) + " plp\n rts\n@zero:", KEM + ["prep"]),
+ ("Y4d", "the I flag leaks out of the post-Decaps scrub", "src/crypto/mlkem_link.s",
+ SCRUB_BODY,
+ SCRUB_BODY.replace("pq_mlkem_scrub:\n php\n", "pq_mlkem_scrub:\n nop\n")
+ .replace(" sta $01\n plp\n rts\n@zero:", " sta $01\n nop\n rts\n@zero:"), KEM + ["decaps"]),
+ ("M56", "the SH loop ignores the ERROR latch", T13,
+ " bpl :+ ; record header while waiting for the SH\n",
+ " jmp :+\n", KEM + ["oversize"]),
+]
+
+
+def run(cmd, env=None, timeout=3600):
+ e = dict(os.environ, C64_SKIP_BUILD="1", C64_FAIL_FAST="1")
+ e.update(env or {})
+ r = subprocess.run([sys.executable] + cmd, cwd=REPO, env=e,
+ capture_output=True, text=True, timeout=timeout)
+ return r.returncode, r.stdout + r.stderr
+
+
+def build():
+ subprocess.run(["make", "clean"], cwd=REPO, capture_output=True)
+ r = subprocess.run(["make"] + PQ_ARGS, cwd=REPO, capture_output=True, text=True)
+ return r.returncode, r.stdout + r.stderr
+
+
+def main():
+ args = [a for a in sys.argv[1:] if not a.startswith("-")]
+ if "--list" in sys.argv:
+ for mid, what, f, _o, _n, suite in MUTANTS:
+ print(f"{mid} {what} [{f}] -> {' '.join(suite)}")
+ return 0
+ want = [m for m in MUTANTS if not args or m[0] in args]
+ results = []
+ rc, out = build()
+ if rc:
+ print(out[-2000:])
+ return 2
+ 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):
+ crc, cout = run(c, env={"C64_FAIL_FAST": "0"})
+ print(f"control {' '.join(c)}: rc={crc}", flush=True)
+ if crc:
+ print(cout[-2500:])
+ return 2
+ for mid, what, f, old, new, suite in want:
+ p = REPO / f
+ orig = p.read_text()
+ if orig.count(old) != 1:
+ print(f"{mid}: pattern matches {orig.count(old)} times in {f}: FIX THE MUTANT")
+ results.append((mid, what, "BAD-PATTERN"))
+ continue
+ t0 = time.monotonic()
+ try:
+ p.write_text(orig.replace(old, new, 1))
+ rc, out = build()
+ if rc:
+ verdict = "BUILD-FAIL"
+ print(out[-600:])
+ 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]}"
+ finally:
+ p.write_text(orig)
+ print(f"{mid} {what}: {verdict} ({time.monotonic() - t0:.0f} s)", flush=True)
+ results.append((mid, what, verdict))
+ rc, out = build()
+ ctl = run(SH)[0] if rc == 0 else rc
+ print(f"\ncontrol after restore: build rc={rc}, test_pq_sh rc={ctl}")
+ bad = [r for r in results if not r[2].startswith("KILLED")]
+ print(f"{len(results) - len(bad)}/{len(results)} mutants killed")
+ for r in bad:
+ print(" NOT KILLED:", r)
+ return 0 if not bad and ctl == 0 else 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/pq_keylog_check.py b/tools/pq_keylog_check.py
new file mode 100644
index 0000000..c335e3f
--- /dev/null
+++ b/tools/pq_keylog_check.py
@@ -0,0 +1,225 @@
+#!/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:
+
+ 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
+
+ IKM = mlkem_ss || x25519_ss (draft-ietf-tls-ecdhe-mlkem: ML-KEM first)
+
+and compares the derived handshake traffic secrets with the keylog's. A match
+proves the C64's ML-KEM secret equals the server's Encaps secret AND that the
+transcript the C64 folded (CH || SH) is the one the server hashed: nothing else
+reproduces 32 bytes of HKDF output.
+
+ pq_keylog_check.py --keylog K --client-random HEX --mlkem-ss HEX \
+ --x25519-ss HEX --transcript HEX
+ pq_keylog_check.py --selftest
+
+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).
+"""
+
+import argparse
+import hashlib
+import hmac
+import struct
+import sys
+
+
+def hkdf_extract(salt, ikm):
+ return hmac.new(salt, ikm, hashlib.sha256).digest()
+
+
+def hkdf_expand(prk, info, n):
+ out, t, i = b"", b"", 1
+ while len(out) < n:
+ t = hmac.new(prk, t + info + bytes([i]), hashlib.sha256).digest()
+ out += t
+ i += 1
+ return out[:n]
+
+
+def expand_label(secret, label, context, n):
+ full = b"tls13 " + label
+ info = struct.pack(">H", n) + bytes([len(full)]) + full + bytes([len(context)]) + context
+ return hkdf_expand(secret, info, n)
+
+
+def handshake_secrets(ikm, transcript_hash):
+ """(client, server) handshake traffic secrets for *ikm* and the hash of
+ ClientHello..ServerHello."""
+ early = hkdf_extract(bytes(32), bytes(32))
+ derived = expand_label(early, b"derived", hashlib.sha256(b"").digest(), 32)
+ hs = hkdf_extract(derived, ikm)
+ return (expand_label(hs, b"c hs traffic", transcript_hash, 32),
+ expand_label(hs, b"s hs traffic", transcript_hash, 32))
+
+
+def parse_keylog(text, client_random_hex):
+ found = {}
+ for line in text.splitlines():
+ parts = line.split()
+ if len(parts) == 3 and parts[1].lower() == client_random_hex.lower():
+ found[parts[0]] = bytes.fromhex(parts[2])
+ return found
+
+
+def check(keylog_text, client_random, mlkem_ss, x25519_ss, transcript):
+ """Returns (ok, message)."""
+ log = parse_keylog(keylog_text, client_random.hex())
+ need = ("SERVER_HANDSHAKE_TRAFFIC_SECRET", "CLIENT_HANDSHAKE_TRAFFIC_SECRET")
+ for n in need:
+ if n not in log:
+ return None, f"keylog has no {n} for client_random {client_random.hex()}"
+ c, s = handshake_secrets(mlkem_ss + x25519_ss, transcript)
+ if c == log[need[1]] and s == log[need[0]]:
+ return True, "match: mlkem_ss || x25519_ss reproduces the server and client handshake traffic secrets"
+ c2, s2 = handshake_secrets(x25519_ss + mlkem_ss, transcript)
+ if s2 == log[need[0]]:
+ return False, "MISMATCH, but x25519_ss || mlkem_ss matches: the concatenation order is swapped"
+ c3, s3 = handshake_secrets(x25519_ss, transcript)
+ if s3 == log[need[0]]:
+ return False, "MISMATCH, but x25519_ss alone matches: the server did not run the hybrid"
+ return False, "MISMATCH: neither IKM order reproduces the server's secret (wrong ML-KEM secret, X25519 secret or 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)."""
+ 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"
+ 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))):
+ 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"))
+
+
+def selftest():
+ import os
+ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+ import test_tls_handshake as TH # the repo's own HKDF reference
+ ok = True
+
+ def expect(cond, what):
+ nonlocal ok
+ print((" PASS " if cond else " FAIL ") + what)
+ ok = ok and cond
+
+ rnd = bytes(range(32))
+ mk, xs = bytes(range(100, 132)), bytes(range(200, 232))
+ th = hashlib.sha256(b"ch||sh").digest()
+ # independent derivation through the repo's reference functions
+ early = TH.hkdf_extract_ref(bytes(32), bytes(32))
+ derived = TH.derive_secret_ref(early, b"derived", hashlib.sha256(b"").digest())
+ hs = TH.hkdf_extract_ref(derived, mk + xs)
+ s_ref = TH.hkdf_expand_label_ref(hs, b"s hs traffic", th, 32)
+ c_ref = TH.hkdf_expand_label_ref(hs, b"c hs traffic", th, 32)
+ c, s = handshake_secrets(mk + xs, th)
+ expect((c, s) == (c_ref, s_ref), "agrees with the repo's HKDF reference (test_tls_handshake)")
+ log = (f"SERVER_HANDSHAKE_TRAFFIC_SECRET {rnd.hex()} {s.hex()}\n"
+ f"CLIENT_HANDSHAKE_TRAFFIC_SECRET {rnd.hex()} {c.hex()}\n"
+ f"SERVER_HANDSHAKE_TRAFFIC_SECRET {bytes(32).hex()} {bytes(32).hex()}\n")
+ r, m = check(log, rnd, mk, xs, th)
+ expect(r is True, "green: matching secrets accepted")
+ bad = bytearray(mk)
+ bad[5] ^= 1
+ r, m = check(log, rnd, bytes(bad), xs, th)
+ expect(r is False, "red: one flipped bit in the ML-KEM secret is a mismatch")
+ bad = bytearray(xs)
+ bad[31] ^= 0x80
+ r, m = check(log, rnd, mk, bytes(bad), th)
+ expect(r is False, "red: one flipped bit in the X25519 secret is a mismatch")
+ bad = bytearray(th)
+ bad[0] ^= 1
+ r, m = check(log, rnd, mk, xs, bytes(bad))
+ expect(r is False, "red: one flipped bit in the transcript hash is a mismatch")
+ r, m = check(log, rnd, xs, mk, th)
+ expect(r is False and "swapped" in m, "red: swapped concatenation order is named")
+ log2 = (f"SERVER_HANDSHAKE_TRAFFIC_SECRET {rnd.hex()} "
+ f"{handshake_secrets(xs, th)[1].hex()}\n"
+ f"CLIENT_HANDSHAKE_TRAFFIC_SECRET {rnd.hex()} {c.hex()}\n")
+ r, m = check(log2, rnd, mk, xs, th)
+ 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")
+ 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")):
+ bad = dict(good)
+ bad[key] = val
+ r, m = check_state(bad, log)
+ 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")
+ print("SELFTEST " + ("PASS" if ok else "FAIL"))
+ return 0 if ok else 1
+
+
+def main(argv=None):
+ ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+ ap.add_argument("--keylog")
+ ap.add_argument("--client-random")
+ ap.add_argument("--mlkem-ss")
+ ap.add_argument("--x25519-ss")
+ ap.add_argument("--transcript", help="SHA-256(ClientHello || ServerHello), as the C64 hashed it")
+ ap.add_argument("--state", help="pq_state.json from rig_https_local.py with PQ_DUMP= "
+ "(replaces --client-random/--mlkem-ss/--x25519-ss/--transcript)")
+ ap.add_argument("--selftest", action="store_true")
+ a = ap.parse_args(argv)
+ if a.selftest:
+ return selftest()
+ if a.state:
+ import json
+ if not a.keylog:
+ ap.error("--keylog is required")
+ r, msg = check_state(json.load(open(a.state)), open(a.keylog).read())
+ print(msg)
+ return 78 if r == "inconclusive" else (0 if r else (2 if r is None else 1))
+ for n in ("keylog", "client_random", "mlkem_ss", "x25519_ss", "transcript"):
+ if getattr(a, n) is None:
+ ap.error(f"--{n.replace('_', '-')} is required")
+ text = open(a.keylog).read()
+ r, msg = check(text, bytes.fromhex(a.client_random), bytes.fromhex(a.mlkem_ss),
+ bytes.fromhex(a.x25519_ss), bytes.fromhex(a.transcript))
+ print(msg)
+ return 0 if r else (2 if r is None else 1)
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/run_all_tests.py b/tools/run_all_tests.py
index eeb9835..71d3f1d 100644
--- a/tools/run_all_tests.py
+++ b/tools/run_all_tests.py
@@ -66,6 +66,18 @@
"curve_refusal",
)
+# PQ_HYBRID=1 suites. They are standalone main() programs (no run_tests()), so
+# the coverage guard below does not reach them, and this runner builds the
+# default ip65 image, which they cannot run on. Run them directly, each builds
+# (or with C64_SKIP_BUILD=1 reuses) the BACKEND=uci USE_NISTCURVES_ONCHIP=1
+# PQ_HYBRID=1 image:
+# tools/test_mlkem_placement.py link-time placement + mutants (#313)
+# 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/mutate_pq_sh.py breaks each P4 check, expects red (P4)
+# tools/test_pq_keylog_check.py the hardware oracle (pytest, no VICE)
+
# Suites that define run_tests() but are deliberately NOT dispatched here,
# as {module: why}. Anything absent from both this and SUITE_ORDER fails
# tools/test_runner_coverage.py.
diff --git a/tools/test_mlkem_linked.py b/tools/test_mlkem_linked.py
index 879cfb0..6d47852 100644
--- a/tools/test_mlkem_linked.py
+++ b/tools/test_mlkem_linked.py
@@ -338,7 +338,7 @@ def comb_refusal(t):
with ViceInstanceManager(config=config) as mgr:
inst = mgr.acquire()
tr = inst.transport
- if not t.check(wait_for_text(tr, "Q=QUIT", timeout=2400, verbose=False)
+ if not t.check(wait_for_text(tr, "Q=QUIT", timeout=menu_wait(2400), verbose=False)
is not None, "the comb image reached the menu "
f"({time.monotonic() - t0:.0f} s)"):
mgr.release(inst)
diff --git a/tools/test_openssl_listener.py b/tools/test_openssl_listener.py
new file mode 100644
index 0000000..cddde9f
--- /dev/null
+++ b/tools/test_openssl_listener.py
@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""tools/test_openssl_listener.py - the PQ rigs' OpenSSL listener cannot lie.
+
+openssl_listener.py once printed LISTENING after probing the port: when
+another process already held it (the fleet's 4433), the probe connected to THAT
+process while our s_server had died on the bind, and a rig then ran against a
+stranger's server. It now reports LISTENING only when s_server prints ACCEPT.
+Red case: occupy a port, the launcher must exit non-zero and never print
+LISTENING. Green control: a free port prints LISTENING. Needs OpenSSL 3.x
+(Homebrew openssl@3; the launcher says so if it is missing, and that is a
+failure here, not a skip).
+
+ pytest tools/test_openssl_listener.py
+"""
+from __future__ import annotations
+
+import socket
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+LISTENER = REPO / "tools" / "https_e2e" / "openssl_listener.py"
+
+
+def _free_port() -> int:
+ with socket.socket() as s:
+ s.bind(("0.0.0.0", 0))
+ return s.getsockname()[1]
+
+
+def _run(port, wait):
+ keylog = Path(tempfile.mkdtemp(prefix="listener_test_")) / "k"
+ p = subprocess.Popen([sys.executable, str(LISTENER), "--port", str(port), "--keylog", str(keylog),
+ "--groups", "X25519"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ try:
+ out, err = p.communicate(timeout=wait)
+ return p.returncode, out, err
+ except subprocess.TimeoutExpired:
+ p.terminate()
+ out, err = p.communicate(timeout=10)
+ return None, out, err
+
+
+def test_a_port_held_by_someone_else_is_an_error():
+ holder = socket.socket()
+ holder.bind(("0.0.0.0", 0))
+ holder.listen(1)
+ try:
+ rc, out, err = _run(holder.getsockname()[1], 30)
+ finally:
+ holder.close()
+ assert rc not in (None, 0), f"rc={rc}\n{out}\n{err}"
+ assert "LISTENING" not in out, out
+
+
+def test_a_free_port_reports_listening():
+ rc, out, err = _run(_free_port(), 8)
+ assert rc is None and "LISTENING" in out, f"rc={rc}\n{out}\n{err}"
+
+
+def main() -> int:
+ tests = [(n, f) for n, f in sorted(globals().items()) if n.startswith("test_") and callable(f)]
+ failed = 0
+ for name, fn in tests:
+ try:
+ fn()
+ print(f" PASS {name}")
+ except AssertionError as exc:
+ failed += 1
+ print(f" FAIL {name}: {exc}")
+ print(f"\n{len(tests) - failed}/{len(tests)} passed")
+ sys.path.insert(0, str(REPO / "tools"))
+ from _skip_policy import verdict
+ return verdict(len(tests) - failed, failed, certifies="the OpenSSL test listener")
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/test_pq_kem.py b/tools/test_pq_kem.py
new file mode 100644
index 0000000..b182171
--- /dev/null
+++ b/tools/test_pq_kem.py
@@ -0,0 +1,486 @@
+#!/usr/bin/env python3
+"""test_pq_kem.py - KeyGen, ClientHello, Decaps and tls_connect (PQC phase P4).
+
+The slow half of the P4 suites (tools/test_pq_sh.py is the fast one): real
+ML-KEM runs in a VICE boot of the BACKEND=uci USE_NISTCURVES_ONCHIP=1
+PQ_HYBRID=1 image, checked against libs/mlkem/tools/mlkem_ref.py.
+
+ [1] pq_connect_prep: the 64 B seed the DRBG produced is dumped, the ek in
+ cert_buf equals the reference's KeyGen(d, z).ek, the 2,400 B dk scratch
+ is all zero afterwards, tls_ch_ks_ptr/len are armed with the ek and the
+ hybrid is marked offered. Twice: two preps give two different seeds.
+ [2] tls_send_client_hello after prep: the wire bytes equal a Python
+ reference ClientHello carrying THAT ek (11EC = ek || x25519, then 001D),
+ the transcript is SHA-256 of it, the arm is one-shot.
+ [3] Decaps KAT: the host encapsulates to the C64's ek; the 11EC ServerHello
+ (ct || x25519) goes in as 512+512+154; pq_sh_decaps leaves K in
+ tls_mlkem_ss; the seed is zeroed. A flipped ct bit gives the reference's
+ implicit-rejection key (not K).
+ [4] tls_connect end to end with net_tcp_send replaced by a recorder:
+ KeyGen runs inside it (breakpoint at tls_recv_server_hello: ek valid for
+ the dumped seed, dk zero, CH recorded), the ServerHello is injected into
+ the TCP ring as three records, and the run continues through Decaps and
+ the X25519 mult to the first encrypted record. Group 11EC and group
+ 001D (classic fallback: HTTPS proceeds as before). The expected end state
+ is the P4 documented one: the key schedule is not hybrid yet, so the
+ first encrypted record cannot be read (tls_last_state = ENCRYPTED_EXT).
+ Afterwards (error exit) the seed is zero and the ML-KEM secret kept.
+
+ python3 tools/test_pq_kem.py # builds the PQ image first
+ C64_SKIP_BUILD=1 python3 tools/test_pq_kem.py
+"""
+
+import hashlib
+import os
+import shutil
+import struct
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _pq_testlib import ( # noqa: E402
+ Tally, Session, build_or_reuse, require_pq_image, sh_message, ks_ext, sv_ext, split_at,
+ x25519, x25519_pub, GROUP_HYB, GROUP_X, CT_LEN, EK_LEN, E_DECAPS,
+)
+from _skip_policy import cannot_run, verdict # noqa: E402
+from c64_test_harness import ( # noqa: E402
+ set_breakpoint, delete_breakpoint, wait_for_pc, goto, write_bytes,
+ read_bytes,
+)
+import mlkem_ref as R # noqa: E402
+import test_tls_handshake as TH # noqa: E402
+
+HOST = "example.com"
+M_FIXED = bytes(range(201, 233))
+
+
+def prep(s, check=None, iflag=0):
+ a, p, port = s.call_port("pq_connect_prep", iflag)
+ if check is not None:
+ check.check(port & 7 == 6, f"pq_connect_prep (KeyGen + scrub) restores $01 (entered with I={iflag})",
+ f"$01=${port:02X}")
+ check.check((p >> 2) & 1 == iflag, f"...and the caller's I flag (entered with I={iflag})", f"P=${p:02X}")
+ seed = s.rd(s.L("tls_pq_seed"), 64)
+ ek = s.rd(s.L("cert_buf"), EK_LEN)
+ return a, p, seed, ek
+
+
+def phase_prep(s, t):
+ print("\n[1] pq_connect_prep")
+ s.wr(0xC000, bytes([0xEE]) * 2400)
+ a, p, seed, ek = prep(s, t, 1) # sei first: see Session.call_port
+ t.check(not p & 1, "pq_connect_prep: C=0", f"P=${p:02X}")
+ ek_ref, dk_ref = R.mlkem_keygen(seed[:32], seed[32:])
+ t.check(seed != bytes(64), "the DRBG filled the 64 B seed")
+ t.check(ek == ek_ref, "cert_buf holds the reference's ek for that seed",
+ f"first diff at +{next((i for i in range(EK_LEN) if ek[i] != ek_ref[i]), -1)}")
+ dk = s.rd(0xC000, 2400)
+ t.check(dk == bytes(2400), "the 2,400 B dk scratch is all zero",
+ f"{sum(1 for b in dk if b)} non-zero bytes")
+ ptr = s.rd(s.L("tls_ch_ks_ptr"), 2)
+ ln = s.rd(s.L("tls_ch_ks_len"), 2)
+ t.check(ptr[0] | ptr[1] << 8 == s.L("cert_buf"), "tls_ch_ks_ptr = cert_buf")
+ t.check(ln[0] | ln[1] << 8 == EK_LEN, "tls_ch_ks_len = 1,184")
+ t.check(s.rd(s.L("tls_pq_offered"), 1) == b"\x01", "the hybrid is marked offered")
+ t.check(s.ram_rd(0xD000, 4096) == bytes(4096), "KeyGen's s_hat is gone: $D000-$DFFF is zero after prep")
+ t.check(s.rd(s.L("mul38_lo_tab"), 0xB00) == bytes(0xB00), "the ML-KEM window ($B100-$BBFF) is zero after prep")
+ # a second prep: a different seed, again a matching ek
+ a2, p2, seed2, ek2 = prep(s, t, 0)
+ t.check(seed2 != seed, "a second prep draws a different seed")
+ t.check(ek2 == R.mlkem_keygen(seed2[:32], seed2[32:])[0],
+ "...and its ek matches the reference too")
+ return seed2, ek2
+
+
+def phase_ch(s, t, ek):
+ print("\n[2] ClientHello carries the ek")
+ rnd = bytes((3 * i + 1) & 255 for i in range(32))
+ pub = bytes((5 * i + 2) & 255 for i in range(32))
+ carry, secs, wire, th, ks_after = TH.capture_client_hello(
+ s.tr, s.labels, rnd, pub, HOST, None)
+ ref = TH.ref_client_hello(rnd, pub, HOST, ek)
+ ref_wire = b"\x16\x03\x03" + struct.pack(">H", len(ref)) + ref
+ t.check(carry == 0, "tls_send_client_hello: C=0")
+ t.check(wire == ref_wire, "wire == reference hybrid ClientHello (11EC = ek || x25519, then 001D)",
+ f"{len(wire)} vs {len(ref_wire)} B")
+ t.check(th == hashlib.sha256(ref).digest(), "transcript == SHA-256 of the message")
+ t.check(len(secs) == 4 and ks_after == b"\x00\x00",
+ "four sends, tls_ch_ks_len cleared (one-shot)", f"{len(secs)} {ks_after}")
+
+
+def hybrid_sh(ct, pub, rnd=None):
+ msg = sh_message(sv_ext() + ks_ext(GROUP_HYB, ct + pub),
+ random=rnd or bytes(range(32, 64)))
+ return msg
+
+
+def phase_decaps(s, t, seed, ek):
+ print("\n[3] Decaps KAT")
+ d, z = seed[:32], seed[32:]
+ ek_ref, dk_ref = R.mlkem_keygen(d, z)
+ K, ct = R.mlkem_encaps(ek_ref, M_FIXED)
+ spub = x25519_pub(bytes(range(90, 122)))
+ msg = hybrid_sh(ct, spub)
+ s.begin(True)
+ for rec in split_at(msg, [512, 1024]):
+ c, z_ = s.feed(rec)
+ assert not c
+ a, p, port = s.call_port("pq_sh_decaps", 1)
+ ss = s.rd(s.L("tls_mlkem_ss"), 32)
+ t.check(port & 7 == 6, "pq_sh_decaps (Decaps + scrub) restores $01 (entered with I=1)", f"$01=${port:02X}")
+ t.check((p >> 2) & 1 == 1, "...and the caller's I flag (entered with I=1)", f"P=${p:02X}")
+ t.check(not p & 1, "pq_sh_decaps: C=0", f"A={a:02X} P=${p:02X}")
+ t.check(ss == K, "tls_mlkem_ss == the reference's K", ss.hex())
+ t.check(s.rd(s.L("tls_pq_seed"), 64) == bytes(64), "the seed is zeroed after Decaps")
+ t.check(s.group() == 0xEC, "tls_kex_group = $EC")
+ t.check(s.ram_rd(0xD000, 4096) == bytes(4096), "Decaps' y/e1/e2 are gone: $D000-$DFFF is zero")
+ t.check(s.rd(s.L("mul38_lo_tab"), 0xB00) == bytes(0xB00),
+ "m'/K'/r' are gone: the ML-KEM window ($B100-$BBFF) is zero after Decaps")
+ # implicit rejection: same seed, a corrupted ct
+ bad = bytearray(ct)
+ bad[100] ^= 0x10
+ K_rej = R.mlkem_decaps(dk_ref, bytes(bad))
+ t.check(K_rej != K, "(reference) the rejection key differs from K")
+ s.wr(s.L("tls_pq_seed"), seed)
+ s.begin(True)
+ for rec in split_at(hybrid_sh(bytes(bad), spub), [512, 1024]):
+ s.feed(rec)
+ a, p, port = s.call_port("pq_sh_decaps", 0)
+ ss2 = s.rd(s.L("tls_mlkem_ss"), 32)
+ t.check(port & 7 == 6 and (p >> 2) & 1 == 0, "the second Decaps (entered with I clear) restores $01 and the I flag",
+ f"$01=${port:02X} P=${p:02X}")
+ t.check(not p & 1 and ss2 == K_rej, "a flipped ct bit gives the reference's implicit-rejection key",
+ ss2.hex())
+
+
+# ---------------------------------------------------------------------------
+# [4] tls_connect, end to end
+# ---------------------------------------------------------------------------
+CTL = 0x0334 # the harness trampoline
+CARRY = 0x033F
+REC_STUB = 0x0350 # net_tcp_send recorder
+REC_IDX = 0x037F
+REC_TBL = 0x0380 # 4 B per call: ptr, len
+
+
+def recorder(s):
+ """Replace net_tcp_send by a recorder (as capture_client_hello does) and
+ return the original 3 bytes."""
+ L = s.L
+ nsl = L("net_send_len")
+ stub = bytearray([0xAC, REC_IDX & 255, REC_IDX >> 8])
+ for off, ld in ((0, None), (1, "x"), (2, nsl), (3, nsl + 1)):
+ if ld == "x":
+ stub += bytes([0x8A])
+ elif ld is not None:
+ stub += bytes([0xAD, ld & 255, ld >> 8])
+ stub += bytes([0x99, (REC_TBL + off) & 255, (REC_TBL + off) >> 8])
+ stub += bytes([0xC8] * 4 + [0x8C, REC_IDX & 255, REC_IDX >> 8, 0x18, 0x60])
+ s.wr(REC_STUB, bytes(stub))
+ s.wr(REC_IDX, [0])
+ orig = s.rd(L("net_tcp_send"), 3)
+ s.wr(L("net_tcp_send"), bytes([0x4C, REC_STUB & 255, REC_STUB >> 8]))
+ return orig
+
+
+def wire_sent(s):
+ n = s.rd(REC_IDX, 1)[0] // 4
+ tbl = s.rd(REC_TBL, 4 * n) if n else b""
+ out = b""
+ for i in range(n):
+ ptr = tbl[4 * i] | tbl[4 * i + 1] << 8
+ ln = tbl[4 * i + 2] | tbl[4 * i + 3] << 8
+ out += s.rd(ptr, ln) if ln else b""
+ return out
+
+
+def inject(s, records):
+ """Append plaintext handshake records to the (empty) TCP ring."""
+ L = s.L
+ tail = s.rd(L("tcp_recv_tail"), 2)
+ off = tail[0] | tail[1] << 8
+ start = off
+ data = b"".join(b"\x16\x03\x03" + struct.pack(">H", len(r)) + r for r in records)
+ assert off + len(data) <= 0x1000
+ s.wr(0xC000 + off, data)
+ off += len(data)
+ s.wr(L("tcp_recv_tail"), [off & 255, off >> 8])
+ return start
+
+
+def run_connect(s, t, tag, kind):
+ """tls_connect with the network faked. kind: 'hyb' or 'x'."""
+ L = s.L
+ sk_c = bytes((11 * i + 7) & 255 for i in range(32))
+ sk_s = bytes((13 * i + 1) & 255 for i in range(32))
+ spub = x25519_pub(sk_s)
+ print(f"\n[4] tls_connect, {tag}")
+ s.wr(L("tls_hostname"), HOST.encode())
+ s.wr(L("tls_hostname_len"), [len(HOST)])
+ orig = recorder(s)
+ # tls_connect draws its own private key; we need to know it, so pin the
+ # DRBG output: tls_connect fills tls_ecdhe_privkey from the DRBG, which we
+ # cannot predict, so read it back at the breakpoint instead.
+ tramp = bytes([0x20, L("tls_connect") & 255, L("tls_connect") >> 8,
+ 0xA9, 0, 0x2A, 0x8D, CARRY & 255, CARRY >> 8, 0xEA, 0xEA])
+ s.wr(CTL, tramp)
+ end = CTL + len(tramp) - 2
+ bp_sh = set_breakpoint(s.tr, L("tls_recv_server_hello"))
+ bp_end = set_breakpoint(s.tr, end)
+ try:
+ goto(s.tr, CTL)
+ wait_for_pc(s.tr, L("tls_recv_server_hello"), timeout=3600.0)
+ # --- KeyGen has run inside tls_connect, the CH has been "sent" ---
+ seed = s.rd(L("tls_pq_seed"), 64)
+ ek = s.rd(L("cert_buf"), EK_LEN)
+ priv = s.rd(L("tls_ecdhe_privkey"), 32)
+ pub = s.rd(L("tls_ecdhe_pubkey"), 32)
+ rnd = s.rd(L("tls_client_random"), 32)
+ ek_ref, dk_ref = R.mlkem_keygen(seed[:32], seed[32:])
+ t.check(ek == ek_ref and seed != bytes(64),
+ "tls_connect ran KeyGen: cert_buf = the reference ek for the seed it drew")
+ t.check(s.rd(0xC000, 2400) == bytes(2400), "tls_connect left the dk scratch zero")
+ t.check(s.rd(L("tls_pq_offered"), 1) == b"\x01", "hybrid offered")
+ wire = wire_sent(s)
+ ref = TH.ref_client_hello(rnd, pub, HOST, ek)
+ t.check(wire == b"\x16\x03\x03" + struct.pack(">H", len(ref)) + ref,
+ "the ClientHello tls_connect sent is the hybrid one carrying that ek")
+ t.check(pub == x25519_pub(priv), "tls_ecdhe_pubkey is the public key of tls_ecdhe_privkey")
+ # --- the server's answer ---
+ if kind == "hyb":
+ K, ct = R.mlkem_encaps(ek_ref, M_FIXED)
+ msg = hybrid_sh(ct, spub)
+ recs = split_at(msg, [512, 1024])
+ else:
+ K = None
+ msg = sh_message(sv_ext() + ks_ext(GROUP_X, spub),
+ random=bytes(range(32, 64)))
+ recs = [msg]
+ inject(s, recs)
+ # tls_connect has already issued tls_rx_reset; the ring is ours now
+ bp_ecdh = set_breakpoint(s.tr, L("tls_ecdh_compute_shared"))
+ s.tr.resume()
+ wait_for_pc(s.tr, L("tls_ecdh_compute_shared"), timeout=7200.0)
+ # Decaps (if any) has run and the X25519 mult has NOT: the ML-KEM
+ # secret is final and the seed is gone.
+ t.check(s.rd(L("tls_pq_seed"), 64) == bytes(64),
+ "at the X25519 mult the seed is already zero")
+ ss_k = s.rd(L("tls_mlkem_ss"), 32)
+ if kind == "hyb":
+ t.check(ss_k == K, "tls_mlkem_ss == the reference K, before the X25519 mult", ss_k.hex())
+ else:
+ t.check(ss_k == bytes(32), "classic path: no ML-KEM secret was produced")
+ t.check(s.rd(L("tls_transcript_total_lo"), 2)[0] | s.rd(L("tls_transcript_total_lo"), 2)[1] << 8
+ == len(ref) + len(msg),
+ "transcript has folded exactly CH + SH (byte count)")
+ delete_breakpoint(s.tr, bp_ecdh)
+ s.tr.resume()
+ wait_for_pc(s.tr, end, timeout=7200.0)
+ finally:
+ for b in (bp_sh, bp_end):
+ try:
+ delete_breakpoint(s.tr, b)
+ except Exception:
+ 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(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')")
+ return K
+
+
+def run_connect_bad(s, t):
+ """A refused ServerHello through the real tls_connect: C=1 at SERVER_HELLO,
+ the machine's code in tls_sh_err, no Decaps, no X25519, seed scrubbed."""
+ L = s.L
+ print("\n[5] tls_connect, refused ServerHello (11EC with a 1,119 B key_exchange)")
+ s.wr(L("tls_hostname"), HOST.encode())
+ s.wr(L("tls_hostname_len"), [len(HOST)])
+ orig = recorder(s)
+ tramp = bytes([0x20, L("tls_connect") & 255, L("tls_connect") >> 8,
+ 0xA9, 0, 0x2A, 0x8D, CARRY & 255, CARRY >> 8, 0xEA, 0xEA])
+ s.wr(CTL, tramp)
+ end = CTL + len(tramp) - 2
+ bp_sh = set_breakpoint(s.tr, L("tls_recv_server_hello"))
+ bp_end = set_breakpoint(s.tr, end)
+ try:
+ goto(s.tr, CTL)
+ wait_for_pc(s.tr, L("tls_recv_server_hello"), timeout=3600.0)
+ ek = s.rd(L("cert_buf"), EK_LEN)
+ seed = s.rd(L("tls_pq_seed"), 64)
+ ek_ref, _ = R.mlkem_keygen(seed[:32], seed[32:])
+ K, ct = R.mlkem_encaps(ek_ref, M_FIXED)
+ key = (ct + bytes(32))[:1119]
+ msg = sh_message(sv_ext() + ks_ext(GROUP_HYB, key), random=bytes(range(32, 64)))
+ s.wr(L("tls_mlkem_ss"), bytes([0x33]) * 32) # must stay untouched
+ start = inject(s, split_at(msg, [512, 1024]))
+ s.tr.resume()
+ wait_for_pc(s.tr, end, timeout=3600.0)
+ finally:
+ for b in (bp_sh, bp_end):
+ try:
+ delete_breakpoint(s.tr, b)
+ except Exception:
+ pass
+ write_bytes(s.tr, L("net_tcp_send"), orig)
+ t.check(s.rd(CARRY, 1)[0] == 1, "tls_connect fails")
+ t.check(s.err() == 8, "tls_sh_err = SH_ERR_KSLEN", f"${s.err():02X}")
+ t.check(s.rd(L("tls_last_state"), 1)[0] == 2, "failed in SERVER_HELLO (tls_last_state = 2)")
+ t.check(s.rd(L("tls_mlkem_ss"), 32) == bytes([0x33]) * 32, "no Decaps ran")
+ t.check(s.rd(L("tls_pq_seed"), 64) == bytes(64), "the seed is scrubbed by the error exit")
+ t.check(s.group() == 0, "no group recorded")
+ head = s.rd(L("tcp_recv_head"), 2)
+ t.check(head[0] | head[1] << 8 == start + 5 + 512,
+ "the refusal came at once: only the first record was consumed from the ring",
+ f"head={head[0] | head[1] << 8:#x} start={start:#x}")
+
+
+def run_connect_refused(s, t):
+ """KeyGen refused (the ML-KEM image not resident) inside tls_connect:
+ the handshake stops BEFORE the ClientHello is sent."""
+ L = s.L
+ print("\n[6] tls_connect, KeyGen refused")
+ s.wr(L("tls_hostname"), HOST.encode())
+ s.wr(L("tls_hostname_len"), [len(HOST)])
+ s.wr(0xC000, bytes([0xEE]) * 2400)
+ orig = recorder(s)
+ s.wr(L("mlkem_copied"), [0])
+ tramp = bytes([0x20, L("tls_connect") & 255, L("tls_connect") >> 8,
+ 0xA9, 0, 0x2A, 0x8D, CARRY & 255, CARRY >> 8, 0xEA, 0xEA])
+ s.wr(CTL, tramp)
+ end = CTL + len(tramp) - 2
+ bp_end = set_breakpoint(s.tr, end)
+ try:
+ goto(s.tr, CTL)
+ wait_for_pc(s.tr, end, timeout=3600.0)
+ finally:
+ delete_breakpoint(s.tr, bp_end)
+ write_bytes(s.tr, L("net_tcp_send"), orig)
+ t.check(s.rd(CARRY, 1)[0] == 1, "tls_connect fails")
+ t.check(s.err() == 12, "tls_sh_err = SH_ERR_PQ_KEYGEN", f"${s.err():02X}")
+ t.check(s.rd(L("tls_last_state"), 1)[0] == 1, "failed in CLIENT_HELLO (tls_last_state = 1)")
+ t.check(s.rd(REC_IDX, 1)[0] == 0, "no ClientHello was sent")
+ t.check(s.rd(0xC000, 2400) == bytes(2400), "the dk scratch is zero")
+
+
+def run_recv_sh(s, t, tag, setup, expect):
+ """tls_recv_server_hello alone (tls_state = SERVER_HELLO, ring filled by
+ *setup*), breakpoint-free; returns (carry, tls_sh_err, tls_state, polls)."""
+ L = s.L
+ s.wr(L("tls_state"), [2])
+ s.call("tls_rx_reset")
+ setup()
+ a, p = s.call("tls_recv_server_hello", timeout=3600.0)
+ pc = s.rd(L("tls_recv_poll_count"), 2)
+ return p & 1, s.err(), s.rd(L("tls_state"), 1)[0], pc[0] | pc[1] << 8
+
+
+def ring_put(s, data):
+ tail = s.rd(s.L("tcp_recv_tail"), 2)
+ off = tail[0] | tail[1] << 8
+ s.wr(0xC000 + off, data)
+ off += len(data)
+ s.wr(s.L("tcp_recv_tail"), [off & 255, off >> 8])
+
+
+def phase_oversize(s, t):
+ print("\n[7] a ServerHello sent as ONE oversize record fails fast")
+ hdr = b"\x16\x03\x03" + struct.pack(">H", 1178)
+ c, err, st, polls = run_recv_sh(s, t, "oversize", lambda: ring_put(s, hdr + bytes(100)), None)
+ t.check(c == 1, "tls_recv_server_hello fails")
+ t.check(err == 14, "tls_sh_err = SH_ERR_RECORD", f"${err:02X}")
+ t.check(st == 0xFF, "the connection is ERROR-latched, not left to time out", f"tls_state=${st:02X}")
+ t.check(polls < 8, "...after a handful of polls, not 65,536", f"{polls} polls")
+
+
+def phase_timeout(s, t):
+ """ONE failed-poll budget for the whole ServerHello: after the first record
+ is fed, make the budget nearly spent and the next failures must end it."""
+ L = s.L
+ print("\n[8] the ServerHello shares one timeout budget")
+ msg = hybrid_sh(bytes(CT_LEN), bytes(32))
+ first = msg[:300]
+ s.wr(L("tls_pq_offered"), [1])
+ s.wr(L("tls_state"), [2])
+ s.call("tls_rx_reset")
+ ring_put(s, b"\x16\x03\x03" + struct.pack(">H", len(first)) + first)
+ tramp = bytes([0x20, L("tls_recv_server_hello") & 255, L("tls_recv_server_hello") >> 8,
+ 0xA9, 0, 0x2A, 0x8D, CARRY & 255, CARRY >> 8, 0xEA, 0xEA])
+ s.wr(CTL, tramp)
+ end = CTL + len(tramp) - 2
+ bp_feed = set_breakpoint(s.tr, L("pq_sh_feed"))
+ bp_end = set_breakpoint(s.tr, end)
+ try:
+ goto(s.tr, CTL)
+ wait_for_pc(s.tr, L("pq_sh_feed"), timeout=600.0)
+ s.wr(L("sh_timeout"), [0xFC, 0xFF]) # four failed polls from timing out
+ delete_breakpoint(s.tr, bp_feed)
+ s.tr.resume()
+ wait_for_pc(s.tr, end, timeout=3600.0)
+ finally:
+ for b in (bp_feed, bp_end):
+ try:
+ delete_breakpoint(s.tr, b)
+ except Exception:
+ pass
+ pc = s.rd(L("tls_recv_poll_count"), 2)
+ polls = pc[0] | pc[1] << 8
+ t.check(s.rd(CARRY, 1)[0] == 1, "tls_recv_server_hello times out")
+ t.check(2 <= polls <= 16, "...after the few polls the shared budget had left, not a fresh 65,536",
+ f"{polls} polls")
+
+
+def main():
+ t = Tally()
+ if shutil.which("ca65") is None:
+ return cannot_run("cc65 not found", certifies="the PQ KeyGen/Decaps path")
+ rc, out = build_or_reuse()
+ if rc != 0:
+ print(out[-1500:])
+ return cannot_run("the PQ_HYBRID build failed", certifies="the PQ KeyGen/Decaps path")
+ why = require_pq_image()
+ if why:
+ return cannot_run(why, certifies="the PQ KeyGen/Decaps path")
+ allsec = {"prep", "ch", "decaps", "connect", "bad", "refused", "oversize", "timeout"}
+ want = {a for a in sys.argv[1:] if not a.startswith("-")} & allsec or allsec
+ if want & {"prep", "ch", "decaps"}:
+ with Session() as s:
+ seed, ek = phase_prep(s, t)
+ if "ch" in want:
+ phase_ch(s, t, ek)
+ if "decaps" in want:
+ phase_decaps(s, t, seed, ek)
+ if "connect" in want:
+ with Session() as s:
+ run_connect(s, t, "hybrid ServerHello (11EC)", "hyb")
+ with Session() as s:
+ run_connect(s, t, "classic ServerHello (001D)", "x")
+ if "bad" in want:
+ with Session() as s:
+ run_connect_bad(s, t)
+ if "refused" in want:
+ with Session() as s:
+ run_connect_refused(s, t)
+ if want & {"oversize", "timeout"}:
+ with Session() as s:
+ if "oversize" in want:
+ phase_oversize(s, t)
+ with Session() as s:
+ if "timeout" in want:
+ phase_timeout(s, t)
+ print(f"\nRESULTS: {t.passed}/{t.passed + t.failed} passed, {t.failed} failed")
+ return verdict(t.passed, t.failed, certifies="the PQ KeyGen/Decaps path")
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/test_pq_keylog_check.py b/tools/test_pq_keylog_check.py
new file mode 100644
index 0000000..dfc152e
--- /dev/null
+++ b/tools/test_pq_keylog_check.py
@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""tools/test_pq_keylog_check.py - the hardware oracle can go RED.
+
+tools/pq_keylog_check.py decides whether the C64's Decaps agreed with an
+OpenSSL server's Encaps by reproducing the server's handshake traffic secrets
+from the C64's memory. A verdict that cannot fail proves nothing (the #210
+lesson), so every input is flipped here and the verdict must change, the HKDF
+is checked against the repo's own independent reference, and the sentinel gate
+(a run that never reached Decaps must be INCONCLUSIVE, never a pass or a
+mismatch) is exercised arm by arm. No VICE, no hardware.
+
+ pytest tools/test_pq_keylog_check.py
+ python3 tools/test_pq_keylog_check.py
+"""
+from __future__ import annotations
+
+import hashlib
+import sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO / "tools"))
+
+import pq_keylog_check as K # noqa: E402
+
+RND = bytes(range(32))
+MK, XS = bytes(range(100, 132)), bytes(range(200, 232))
+TH = hashlib.sha256(b"ch||sh").digest()
+
+
+def _log(ikm=MK + XS, th=TH, rnd=RND):
+ c, s = K.handshake_secrets(ikm, th)
+ return (f"SERVER_HANDSHAKE_TRAFFIC_SECRET {rnd.hex()} {s.hex()}\n"
+ f"CLIENT_HANDSHAKE_TRAFFIC_SECRET {rnd.hex()} {c.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.update(over)
+ return st
+
+
+def test_schedule_matches_the_repo_reference():
+ import test_tls_handshake as TH_
+ early = TH_.hkdf_extract_ref(bytes(32), bytes(32))
+ derived = TH_.derive_secret_ref(early, b"derived", hashlib.sha256(b"").digest())
+ hs = TH_.hkdf_extract_ref(derived, MK + XS)
+ c, s = K.handshake_secrets(MK + XS, TH)
+ assert s == TH_.hkdf_expand_label_ref(hs, b"s hs traffic", TH, 32)
+ assert c == TH_.hkdf_expand_label_ref(hs, b"c hs traffic", TH, 32)
+
+
+def test_green_control():
+ assert K.check(_log(), RND, MK, XS, TH)[0] is True
+
+
+def test_every_input_is_load_bearing():
+ flip = lambda b, i: b[:i] + bytes([b[i] ^ 1]) + b[i + 1:] # noqa: E731
+ for i in (0, 15, 31):
+ assert K.check(_log(), RND, flip(MK, i), XS, TH)[0] is False
+ assert K.check(_log(), RND, MK, flip(XS, i), TH)[0] is False
+ assert K.check(_log(), RND, MK, XS, flip(TH, i))[0] is False
+
+
+def test_concatenation_order_is_named():
+ r, msg = K.check(_log(), RND, XS, MK, TH)
+ assert r is False and "swapped" in msg
+ r, msg = K.check(_log(MK + XS), RND, MK, XS, TH)
+ assert r is True
+
+
+def test_a_classic_only_server_is_named():
+ r, msg = K.check(_log(ikm=XS), RND, MK, XS, TH)
+ assert r is False and "did not run the hybrid" in msg
+
+
+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_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)]
+ for over in cases:
+ assert K.check_state(_state(**over), _log())[0] == "inconclusive", over
+
+
+def main() -> int:
+ tests = [(n, f) for n, f in sorted(globals().items())
+ if n.startswith("test_") and callable(f)]
+ failed = 0
+ for name, fn in tests:
+ try:
+ fn()
+ print(f" PASS {name}")
+ except AssertionError as exc:
+ failed += 1
+ print(f" FAIL {name}: {exc}")
+ print(f"\n{len(tests) - failed}/{len(tests)} passed")
+ from _skip_policy import verdict
+ return verdict(len(tests) - failed, failed,
+ certifies="the PQ hardware oracle")
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/test_pq_sh.py b/tools/test_pq_sh.py
new file mode 100644
index 0000000..98d0ada
--- /dev/null
+++ b/tools/test_pq_sh.py
@@ -0,0 +1,442 @@
+#!/usr/bin/env python3
+"""test_pq_sh.py - the PQ_HYBRID streaming ServerHello reader (PQC phase P4).
+
+Fast: no ML-KEM and no X25519 run (the slow half is tools/test_pq_kem.py).
+A VICE boot of the BACKEND=uci USE_NISTCURVES_ONCHIP=1 PQ_HYBRID=1 image; each
+case writes records straight into the record buffer and runs pq_sh_feed (the
+routine tls_recv_server_hello calls once per plaintext record), so the
+fragmentation is exactly the test's and nothing depends on the TCP ring.
+
+ [1] accepted: hybrid 11EC in 512+512+154, with the key_share first, in
+ 1-byte and 1-2-3-byte fragments, split at every offset of the header and
+ extension area and around both ct boundaries; classic 001D in one
+ record and byte by byte; unknown extensions skipped. For each: the ct
+ lands in cert_buf exactly (and not one byte past it), the x25519 share
+ in tls_server_pubkey, the random in tls_server_random, tls_kex_group,
+ tls_sh_err = 0, and the transcript hash == SHA-256 of the whole message
+ (every byte folded once, in order).
+ [2] refused, each with its own tls_sh_err and C=1 (see src/constants.inc).
+ [3] glue: pq_sh_decaps on the classic path zeroes the seed without running
+ ML-KEM; pq_sh_decaps / pq_connect_prep with the ML-KEM image refused
+ return C=1 with SH_ERR_PQ_DECAPS / SH_ERR_PQ_KEYGEN and the dk scratch
+ zero; pq_secrets_zero.
+
+ python3 tools/test_pq_sh.py # builds the PQ image first
+ C64_SKIP_BUILD=1 python3 tools/test_pq_sh.py
+"""
+
+import hashlib
+import os
+import random
+import shutil
+import struct
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _pq_testlib import ( # noqa: E402
+ Tally, Session, build_or_reuse, require_pq_image, sh_message, ks_ext, sv_ext, ext, split_at,
+ chunks, HRR_MAGIC, GROUP_HYB, GROUP_X, CT_LEN,
+ E_HRR, E_RECTYPE, E_HDR, E_FIXED, E_EXTLEN, E_VERSION, E_GROUP, E_KSLEN,
+ E_TRAIL, E_MISSING, E_DECAPS, E_KEYGEN, E_EXT,
+)
+from _skip_policy import cannot_run, verdict # noqa: E402
+
+RNG = random.Random(0x50514832)
+SENT = 0xA5
+
+
+def rb(n):
+ return bytes(RNG.getrandbits(8) for _ in range(n))
+
+
+CT = rb(CT_LEN)
+PUB = rb(32)
+SRND = bytes(RNG.getrandbits(8) for _ in range(32))
+HYB_KEY = CT + PUB
+
+
+def hybrid_msg(**kw):
+ exts = kw.pop("exts", None)
+ if exts is None:
+ exts = sv_ext() + ks_ext(GROUP_HYB, HYB_KEY)
+ return sh_message(exts, random=SRND, **kw)
+
+
+def classic_msg(exts=None, **kw):
+ if exts is None:
+ exts = sv_ext() + ks_ext(GROUP_X, PUB)
+ return sh_message(exts, random=SRND, **kw)
+
+
+def run_ok(s, t, tag, msg, records, kind, offered=True, unknown_exts=False):
+ """Feed *records*, expect acceptance after the last one and not before."""
+ s.begin(offered)
+ s.wr(s.L("cert_buf"), bytes([SENT]) * 2048)
+ ok = True
+ for i, rec in enumerate(records):
+ c, z = s.feed(rec)
+ last = i == len(records) - 1
+ if c or z != (1 if last else 0):
+ t.check(False, f"{tag}: record {i}/{len(records)} C={c} Z={z} "
+ f"err={s.err()}")
+ return False
+ th = s.transcript()
+ ct = s.rd(s.L("cert_buf"), 2048)
+ pub = s.rd(s.L("tls_server_pubkey"), 32)
+ srnd = s.rd(s.L("tls_server_random"), 32)
+ probs = []
+ if s.err() != 0:
+ probs.append(f"tls_sh_err={s.err()}")
+ if th != hashlib.sha256(msg).digest():
+ probs.append("transcript != sha256(message)")
+ if srnd != SRND:
+ probs.append("server_random")
+ if kind == "hyb":
+ if s.group() != 0xEC:
+ probs.append(f"group ${s.group():02X}")
+ if ct[:CT_LEN] != CT:
+ probs.append("ct bytes")
+ if ct[CT_LEN:] != bytes([SENT]) * (2048 - CT_LEN):
+ probs.append("cert_buf written past the ct")
+ else:
+ if s.group() != 0x1D:
+ probs.append(f"group ${s.group():02X}")
+ if ct != bytes([SENT]) * 2048:
+ probs.append("cert_buf touched by a classic share")
+ if pub != PUB:
+ probs.append("x25519 share")
+ return t.check(not probs, tag, "; ".join(probs))
+
+
+def run_err(s, t, tag, records, code, offered=True, rtypes=None):
+ """Feed records until one is refused; the refusal must carry *code*."""
+ s.begin(offered)
+ for i, rec in enumerate(records):
+ rt = rtypes[i] if rtypes else 0x16
+ c, z = s.feed(rec, rt)
+ if c:
+ return t.check(s.err() == code,
+ f"{tag} -> refused at record {i} with ${s.err():02X}"
+ f" (want ${code:02X})")
+ if z:
+ break
+ return t.check(False, f"{tag}: not refused (want ${code:02X})",
+ f"err=${s.err():02X}")
+
+
+def accepted(s, t):
+ print("\n[1] accepted shapes")
+ msg = hybrid_msg()
+ assert len(msg) == 1178, len(msg)
+ run_ok(s, t, "11EC, 512+512+154", msg, split_at(msg, [512, 1024]), "hyb")
+ msg2 = hybrid_msg(exts=ks_ext(GROUP_HYB, HYB_KEY) + sv_ext())
+ run_ok(s, t, "11EC, key_share before supported_versions", msg2,
+ split_at(msg2, [512, 1024]), "hyb")
+ # pathological: 1-byte records over the whole header/extension prefix and
+ # into the ct, then 1-2-3-5-8 growth, then big records
+ recs = chunks(msg[:140], [1]) + chunks(msg[140:300], [2, 3, 5, 8]) \
+ + split_at(msg[300:], [])
+ run_ok(s, t, "11EC, 1-byte records over the first 140 bytes", msg,
+ recs, "hyb")
+ # every cut inside the fixed prefix + extension headers (offsets 1..60)
+ for c in range(1, 61):
+ run_ok(s, t, f"11EC, cut at {c}", msg, split_at(msg, [c, 512]), "hyb")
+ ct_start = msg.index(CT)
+ ct_end = ct_start + CT_LEN
+ for c in (ct_start - 2, ct_start - 1, ct_start, ct_start + 1,
+ ct_end - 1, ct_end, ct_end + 1, ct_end + 31, len(msg) - 1):
+ run_ok(s, t, f"11EC, cut at {c} (ct ${ct_start}..{ct_end})", msg,
+ split_at(msg, [c]), "hyb")
+ # the boundary between records falling exactly on the key_share header
+ for w in (4, 5, 6, 7, 8, 9, 10):
+ run_ok(s, t, f"11EC, three cuts {w} bytes either side of the ks header",
+ msg, split_at(msg, [ct_start - w, ct_start - w + 3, ct_start + w]),
+ "hyb")
+ cm = classic_msg()
+ run_ok(s, t, "001D, one record", cm, [cm], "x")
+ run_ok(s, t, "001D, byte by byte", cm, chunks(cm, [1]), "x")
+ run_ok(s, t, "001D with the hybrid NOT offered", cm, [cm], "x", offered=False)
+ for v in (b"\x03\x02", b"\x03\x04", b"\x00\x00"):
+ cv = classic_msg(version=v)
+ run_ok(s, t, f"001D with legacy_version {v.hex()} (ignored, RFC 8446 4.2.1)", cv, [cv], "x")
+ hv = hybrid_msg(version=b"\x03\x01")
+ run_ok(s, t, "11EC with legacy_version 0301", hv, split_at(hv, [512, 1024]), "hyb")
+
+
+def refused(s, t):
+ print("\n[2] refusals")
+ big = hybrid_msg()
+ run_err(s, t, "HRR random", [sh_message(sv_ext() + ks_ext(GROUP_X, PUB),
+ random=HRR_MAGIC)], E_HRR)
+ # a HelloRetryRequest-shaped body: selected_group only, 2-byte key_share
+ hrr = sh_message(sv_ext() + ext(0x33, struct.pack(">H", GROUP_X)),
+ random=HRR_MAGIC)
+ run_err(s, t, "HRR (real shape)", [hrr], E_HRR)
+ # key_share lengths
+ for n in (1119, 1121, 0, 1088, 1152, 864, 1376):
+ key = (CT + PUB + bytes(300))[:n]
+ run_err(s, t, f"11EC key_exchange of {n} B",
+ split_at(sh_message(sv_ext() + ks_ext(GROUP_HYB, key),
+ random=SRND), [512, 1024]), E_KSLEN)
+ run_err(s, t, "11EC when the hybrid was NOT offered",
+ split_at(big, [512, 1024]), E_GROUP, offered=False)
+ run_err(s, t, "unknown group 0x0017 (secp256r1, 65 B)",
+ [sh_message(sv_ext() + ks_ext(0x0017, rb(65)), random=SRND)], E_GROUP)
+ run_err(s, t, "unknown group 0x6399", [classic_msg(
+ exts=sv_ext() + ks_ext(0x6399, PUB))], E_GROUP)
+ run_err(s, t, "group 0x021D (hi byte set)", [classic_msg(
+ exts=sv_ext() + ks_ext(0x021D, PUB))], E_GROUP)
+ run_err(s, t, "group 0x11ED (hybrid look-alike, low byte)", split_at(classic_msg(
+ exts=sv_ext() + ks_ext(0x11ED, HYB_KEY)), [512, 1024]), E_GROUP)
+ run_err(s, t, "group 0x12EC (hybrid look-alike)", split_at(classic_msg(
+ exts=sv_ext() + ks_ext(0x12EC, HYB_KEY)), [512, 1024]), E_GROUP)
+ for n in (31, 33, 64, 0, 288):
+ run_err(s, t, f"001D with a {n} B share", [classic_msg(
+ exts=sv_ext() + ks_ext(GROUP_X, rb(n)))], E_KSLEN)
+ # key_share whose own key length disagrees with its extension length
+ bad = ext(0x33, struct.pack(">HH", GROUP_X, 32) + rb(33))
+ run_err(s, t, "key_share: key length + 4 != extension length",
+ [classic_msg(exts=sv_ext() + bad)], E_KSLEN)
+ bad = ext(0x33, struct.pack(">HH", GROUP_X, 33) + rb(32))
+ run_err(s, t, "key_share: key length claims more than the extension holds",
+ [classic_msg(exts=sv_ext() + bad)], E_KSLEN)
+ run_err(s, t, "key_share extension shorter than its 4-byte header",
+ [classic_msg(exts=sv_ext() + ext(0x33, b"\x00\x1d\x00"))], E_KSLEN)
+ # fixed fields
+ run_err(s, t, "cipher suite 0x1301", [classic_msg(suite=b"\x13\x01")], E_FIXED)
+ run_err(s, t, "cipher suite 0x1302", [classic_msg(suite=b"\x13\x02")], E_FIXED)
+ run_err(s, t, "cipher suite 0x0303 (low byte right, high byte wrong)",
+ [classic_msg(suite=b"\x03\x03")], E_FIXED)
+ run_err(s, t, "cipher suite 0x1203", [classic_msg(suite=b"\x12\x03")], E_FIXED)
+ # a 3-byte session id crafted so the bytes after it parse as a valid
+ # suite/compression/extensions_length: only the session-id length check
+ # itself can refuse it
+ ex = sv_ext() + ks_ext(GROUP_X, PUB)
+ crafted = sh_message(ex, random=SRND, sid=b"\x13\x03\x00", suite=struct.pack(">H", 3 + len(ex)))
+ run_err(s, t, "session id echo of 3 B that mimics the fixed fields", [crafted], E_FIXED)
+ # extensions we did not request (RFC 8446 4.2): every type but the two
+ for typ, data, name in ((0x1234, b"\x01" * 7, "unknown 0x1234"),
+ (0x0029, b"\x00\x00", "pre_shared_key 0x0029"),
+ (0x002C, b"\x00\x01\x02", "cookie 0x002C"),
+ (0x000A, b"", "supported_groups, empty"),
+ (0xFF01, b"\x00", "renegotiation_info"),
+ (0x0000, b"", "server_name, empty")):
+ for order, ex in (("before", ext(typ, data) + sv_ext() + ks_ext(GROUP_X, PUB)),
+ ("between", sv_ext() + ext(typ, data) + ks_ext(GROUP_X, PUB)),
+ ("after", sv_ext() + ks_ext(GROUP_X, PUB) + ext(typ, data))):
+ run_err(s, t, f"{name} {order} the required extensions", [classic_msg(exts=ex)], E_EXT)
+ run_err(s, t, "unsolicited extension after a fragmented hybrid key_share",
+ split_at(hybrid_msg(exts=sv_ext() + ks_ext(GROUP_HYB, HYB_KEY) + ext(0x0029, b"\x00\x00")),
+ [512, 1024]), E_EXT)
+ run_err(s, t, "session id echo of 32 B", [classic_msg(sid=bytes(32))], E_FIXED)
+ run_err(s, t, "compression method 1", [classic_msg(comp=b"\x01")], E_FIXED)
+ # required extensions
+ run_err(s, t, "no supported_versions", [classic_msg(
+ exts=ks_ext(GROUP_X, PUB))], E_MISSING)
+ run_err(s, t, "no key_share", [classic_msg(exts=sv_ext())], E_MISSING)
+ run_err(s, t, "no extensions at all", [classic_msg(exts=b"")], E_MISSING)
+ run_err(s, t, "key_share look-alike 0x0133 is an unsolicited extension, not a key_share", [classic_msg(
+ exts=sv_ext() + ext(0x0133, struct.pack(">HH", GROUP_X, 32) + PUB))],
+ E_EXT)
+ run_err(s, t, "supported_versions look-alike 0x012B is unsolicited", [classic_msg(
+ exts=ext(0x012B, b"\x03\x04") + ks_ext(GROUP_X, PUB))], E_EXT)
+ run_err(s, t, "duplicate key_share", [classic_msg(
+ exts=sv_ext() + ks_ext(GROUP_X, PUB) + ks_ext(GROUP_X, PUB))], E_KSLEN)
+ run_err(s, t, "duplicate supported_versions", [classic_msg(
+ exts=sv_ext() + sv_ext() + ks_ext(GROUP_X, PUB))], E_VERSION)
+ run_err(s, t, "supported_versions 0x0303", [classic_msg(
+ exts=sv_ext(b"\x03\x03") + ks_ext(GROUP_X, PUB))], E_VERSION)
+ run_err(s, t, "supported_versions of 3 B", [classic_msg(
+ exts=ext(0x2B, b"\x03\x04\x00") + ks_ext(GROUP_X, PUB))], E_VERSION)
+ run_err(s, t, "supported_versions of 0 B", [classic_msg(
+ exts=ext(0x2B, b"") + ks_ext(GROUP_X, PUB))], E_VERSION)
+ # message header
+ cm = classic_msg()
+ run_err(s, t, "handshake type 8 (EncryptedExtensions) first",
+ [classic_msg(hdr_type=8)], E_HDR)
+ run_err(s, t, "handshake type 1", [classic_msg(hdr_type=1)], E_HDR)
+ run_err(s, t, "24-bit length with a non-zero top byte",
+ [classic_msg(len_top=1)], E_HDR)
+ run_err(s, t, "message length 0x0600 (past the cap)",
+ [classic_msg(msg_len=0x0600)], E_HDR)
+ run_err(s, t, "message length 39 (shorter than the fixed fields)",
+ [classic_msg(msg_len=39)], E_HDR)
+ run_err(s, t, "message length 0", [classic_msg(msg_len=0)], E_HDR)
+ # extension framing
+ run_err(s, t, "extensions_length one too long",
+ [classic_msg(ext_len=len(sv_ext() + ks_ext(GROUP_X, PUB)) + 1)], E_EXTLEN)
+ run_err(s, t, "extensions_length one too short",
+ [classic_msg(ext_len=len(sv_ext() + ks_ext(GROUP_X, PUB)) - 1)], E_EXTLEN)
+ run_err(s, t, "extension data longer than what is left", [classic_msg(
+ exts=sv_ext() + ks_ext(GROUP_X, PUB) + struct.pack(">HH", 0x1234, 100)
+ + b"\x00" * 3)], E_EXTLEN)
+ run_err(s, t, "2 stray bytes where an extension header should be",
+ [classic_msg(exts=sv_ext() + ks_ext(GROUP_X, PUB) + b"\x00\x00")],
+ E_EXTLEN)
+ run_err(s, t, "key_share ext length one more than the bytes present",
+ [classic_msg(exts=sv_ext() + struct.pack(">HH", 0x33, 37)
+ + struct.pack(">HH", GROUP_X, 32) + PUB)], E_EXTLEN)
+ # bytes after the message
+ run_err(s, t, "one trailing byte in the last record", [cm + b"\x00"], E_TRAIL)
+ run_err(s, t, "a whole EncryptedExtensions header after the SH, same record",
+ [cm + bytes([8, 0, 0, 2, 0, 0])], E_TRAIL)
+ hm = hybrid_msg()
+ run_err(s, t, "trailing byte after a fragmented hybrid SH",
+ split_at(hm + b"\x16", [512, 1024]), E_TRAIL)
+ # a further record after completion
+ s.begin(True)
+ c, z = s.feed(cm)
+ c2, _ = s.feed(b"\x00")
+ t.check(c == 0 and z == 1 and c2 == 1 and s.err() == E_TRAIL,
+ "a record after the message is complete is refused (TRAIL)")
+ # record layer
+ run_err(s, t, "first record is application data (23)", [cm], E_RECTYPE,
+ rtypes=[23])
+ run_err(s, t, "first record is an alert (21)", [cm], E_RECTYPE, rtypes=[21])
+ run_err(s, t, "alert record in the middle of the message",
+ split_at(hm, [300, 700]), E_RECTYPE, rtypes=[0x16, 21, 0x16])
+ run_err(s, t, "handshake type after a CCS-typed record (20) mid-message",
+ split_at(hm, [300]), E_RECTYPE, rtypes=[0x16, 20])
+ s.begin(True)
+ s.wr(s.L("tls_rec_len"), [0, 0])
+ s.wr(s.L("tls_rec_type"), [0x16])
+ a, p = s.call("pq_sh_feed")
+ t.check((p & 1) == 1 and s.err() == E_RECTYPE,
+ "a zero-length handshake record is refused")
+ s.begin(True)
+ s.feed(hm[:100])
+ s.wr(s.L("tls_rec_len"), [0, 0])
+ a, p = s.call("pq_sh_feed")
+ t.check((p & 1) == 1 and s.err() == E_RECTYPE,
+ "a zero-length record mid-message is refused")
+
+
+def glue(s, t):
+ print("\n[3] glue")
+ L = s.L
+ # pq_sh_init resets the recorded group: a refusal after a success leaves none
+ cm0 = classic_msg()
+ run_ok(s, t, "(setup) 001D accepted, group recorded", cm0, [cm0], "x")
+ s.begin(True)
+ c, z = s.feed(sh_message(sv_ext() + ks_ext(0x0017, rb(65)), random=SRND))
+ t.check(c == 1 and s.group() == 0, "a refusal after a success leaves tls_kex_group reset",
+ f"group=${s.group():02X}")
+ # classic path: no ML-KEM, seed scrubbed, ss untouched
+ s.wr(L("tls_pq_seed"), bytes([0x77]) * 64)
+ s.wr(L("tls_mlkem_ss"), bytes([0x66]) * 32)
+ s.wr(L("tls_kex_group"), [0x1D])
+ a, p = s.call("pq_sh_decaps")
+ t.check(not p & 1 and a is not None, "classic path: C=0")
+ t.check(s.rd(L("tls_pq_seed"), 64) == bytes(64),
+ "classic path: the seed is zeroed")
+ t.check(s.rd(L("tls_mlkem_ss"), 32) == bytes([0x66]) * 32,
+ "classic path: the ML-KEM secret is not touched")
+ # Decaps refused (image not resident): C=1, SH_ERR_PQ_DECAPS, nothing ran
+ s.wr(L("tls_pq_seed"), bytes([0x77]) * 64)
+ s.wr(L("tls_kex_group"), [0xEC])
+ saved = s.rd(L("mlkem_copied"), 1)
+ s.wr(L("mlkem_copied"), [0])
+ a, p = s.call("pq_sh_decaps")
+ t.check(p & 1 and s.err() == E_DECAPS,
+ "Decaps refused by the wrapper: C=1, SH_ERR_PQ_DECAPS",
+ f"P=${p:02X} err={s.err()}")
+ t.check(s.rd(L("tls_pq_seed"), 64) == bytes([0x77]) * 64,
+ "refused Decaps leaves the seed for tls_connect's error exit")
+ # pq_secrets_zero clears seed + ss
+ s.wr(L("tls_mlkem_ss"), bytes([0x66]) * 32)
+ s.call("pq_secrets_zero")
+ t.check(s.rd(L("tls_pq_seed"), 96) == bytes(96),
+ "pq_secrets_zero zeroes the seed and the ML-KEM secret")
+ # KeyGen refused: C=1, SH_ERR_PQ_KEYGEN, dk scratch zero, nothing armed
+ dk = 0xC000 # mlkem_dk_scratch = tcp_recv_buf
+ s.wr(L("tls_mlkem_ss"), bytes([0x66]) * 32)
+ s.wr(L("tls_pq_seed"), bytes([0x77]) * 64)
+ s.wr(dk, bytes([0xEE]) * 2400)
+ s.wr(dk + 2400, bytes([0xEE]) * 16)
+ s.wr(L("tls_ch_ks_len"), [0, 0])
+ s.wr(L("tls_pq_offered"), [1])
+ a, p = s.call("pq_connect_prep")
+ t.check(p & 1 and s.err() == E_KEYGEN,
+ "KeyGen refused by the wrapper: C=1, SH_ERR_PQ_KEYGEN",
+ f"P=${p:02X} err={s.err()}")
+ t.check(s.rd(dk, 2400) == bytes(2400),
+ "the 2,400 B dk scratch is zero even when KeyGen was refused")
+ t.check(s.rd(dk + 2400, 16) == bytes([0xEE]) * 16,
+ "...and the zeroing stops at 2,400 B")
+ t.check(s.rd(L("tls_mlkem_ss"), 32) == bytes(32),
+ "the next connection's prep scrubs the previous tls_mlkem_ss")
+ t.check(s.rd(L("tls_pq_seed"), 64) != bytes([0x77]) * 64,
+ "...and replaces the previous seed")
+ t.check(s.rd(L("tls_ch_ks_len"), 2) == b"\x00\x00",
+ "a refused KeyGen arms nothing")
+ t.check(s.rd(L("tls_pq_offered"), 1) == b"\x00",
+ "a refused KeyGen leaves the hybrid not offered")
+ s.wr(L("mlkem_copied"), saved)
+
+
+def scrub(s, t):
+ print("\n[4] 'Q' scrub (session_scrub) covers the PQ secrets")
+ L = s.L
+ s.wr(L("tls_pq_seed"), bytes([0x5A]) * 64)
+ s.wr(L("tls_mlkem_ss"), bytes([0x5B]) * 32)
+ s.call("session_scrub", timeout=300.0)
+ t.check(s.rd(L("tls_pq_seed"), 96) == bytes(96),
+ "session_scrub zeroes tls_pq_seed and tls_mlkem_ss")
+
+
+def scrub_wrapper(s, t):
+ print("\n[5] pq_mlkem_scrub")
+ L = s.L
+ win = L("mul38_lo_tab")
+ assert win == 0xB100
+ s.ram_wr(0xD000, bytes([0xEE]) * 4096)
+ s.wr(win - 1, b"\xEE")
+ s.wr(win, bytes([0xEE]) * 0xB00)
+ s.wr(0xBC00, b"\xEE")
+ for iflag in (1, 0): # sei first: a leaked $01 with I clear would livelock the next IRQ
+ a, p, port = s.call_port("pq_mlkem_scrub", iflag, timeout=60.0)
+ ok = t.check(port & 7 == 6, f"$01 restored (BASIC out, KERNAL and I/O in) after a scrub entered with I={iflag}",
+ f"$01=${port:02X}")
+ t.check((p >> 2) & 1 == iflag, f"the I flag is restored: entered with I={iflag}",
+ f"P=${p:02X}")
+ if not ok:
+ break
+ t.check(s.ram_rd(0xD000, 4096) == bytes(4096), "the 4 KB polynomial area ($D000) is zero")
+ t.check(s.rd(win, 0xB00) == bytes(0xB00), "the ML-KEM rest-BSS window ($B100-$BBFF) is zero")
+ t.check(s.rd(win - 1, 1) == b"\xEE" and s.rd(0xBC00, 1) == b"\xEE",
+ "...and the bytes either side of the window are not touched (sqtab at $BC00)")
+ t.check(s.ram_rd(0xD000, 1) == bytes(1) and s.rd(1, 1)[0] & 7 == 6,
+ "$01 is back where it was (BASIC out, KERNAL and I/O in)", f"${s.rd(1, 1)[0]:02X}")
+
+
+def main():
+ t = Tally()
+ if shutil.which("ca65") is None:
+ return cannot_run("cc65 not found", certifies="the PQ ServerHello reader")
+ rc, out = build_or_reuse()
+ if rc != 0:
+ print(out[-1500:])
+ return cannot_run("the PQ_HYBRID build failed",
+ certifies="the PQ ServerHello reader")
+ why = require_pq_image()
+ if why:
+ return cannot_run(why, certifies="the PQ ServerHello reader")
+ only = [a for a in sys.argv[1:] if not a.startswith("-")]
+ with Session() as s:
+ if not only or "1" in only:
+ accepted(s, t)
+ if not only or "2" in only:
+ refused(s, t)
+ if not only or "3" in only:
+ glue(s, t)
+ if not only or "4" in only:
+ scrub(s, t)
+ if not only or "5" in only:
+ scrub_wrapper(s, t)
+ print(f"\nRESULTS: {t.passed}/{t.passed + t.failed} passed, {t.failed} failed")
+ return verdict(t.passed, t.failed, certifies="the PQ ServerHello reader")
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/uci/rig_https_local.py b/tools/uci/rig_https_local.py
index de31a43..61a0071 100644
--- a/tools/uci/rig_https_local.py
+++ b/tools/uci/rig_https_local.py
@@ -153,8 +153,11 @@ def _keep_cycle(word: int) -> bool:
HOST = os.environ.get("U64_HOST", "192.168.1.81")
REPO_ROOT = Path(__file__).resolve().parents[2]
-PRG_PATH = REPO_ROOT / "build" / "c64-https.prg"
-LABELS_PATH = REPO_ROOT / "build" / "labels.txt"
+# C64_PRG / C64_LABELS name a saved build (rig_mlkem_hw.py's convention), so a
+# run that queues for the device does not depend on what build/ holds by the
+# time it gets the lock. Both default to build/.
+PRG_PATH = Path(os.environ.get("C64_PRG", str(REPO_ROOT / "build" / "c64-https.prg")))
+LABELS_PATH = Path(os.environ.get("C64_LABELS", str(REPO_ROOT / "build" / "labels.txt")))
CERT_PATH = REPO_ROOT / "tools" / "https_e2e" / "certs" / "server.pem"
KEY_PATH = REPO_ROOT / "tools" / "https_e2e" / "certs" / "server.key"
@@ -262,6 +265,46 @@ def _ensure_certs_or_fail() -> int:
EXTERNAL_HOST = os.environ.get("EXTERNAL_HOST", "")
EXTERNAL_PORT = int(os.environ.get("EXTERNAL_PORT", "4433"))
+# --- 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
+# 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
+
+
+def _pq_dump(client, transport, labels, outdir: str) -> None:
+ """Park the CPU (sei / $01=$34 / jmp *) and dump the P4 state to JSON."""
+ park = bytes([0x78, 0xA9, 0x34, 0x85, 0x01,
+ 0x4C, (PQ_PARK_ADDR + 5) & 255, PQ_PARK_ADDR >> 8])
+ transport.write_memory(PQ_PARK_ADDR, park)
+ park_cmd = "sys%d\r" % PQ_PARK_ADDR # parks the CPU; not a fetch trigger
+ send_text(transport, park_cmd)
+ time.sleep(3.0)
+
+ def rd(name, n):
+ return bytes(client.read_mem(labels[name], n)).hex()
+
+ state = {
+ "prg_sha256": hashlib.sha256(PRG_PATH.read_bytes()).hexdigest(),
+ "tls_mlkem_ss": rd("tls_mlkem_ss", 32),
+ "tls_pq_seed": rd("tls_pq_seed", 64),
+ "tls_shared_secret": rd("tls_shared_secret", 32),
+ "tls_transcript": rd("tls_transcript", 32),
+ "tls_client_random": rd("tls_client_random", 32),
+ "tls_server_pubkey": rd("tls_server_pubkey", 32),
+ "tls_kex_group": rd("tls_kex_group", 1),
+ "tls_pq_offered": rd("tls_pq_offered", 1),
+ "tls_sh_err": rd("tls_sh_err", 1),
+ "tls_state": rd("tls_state", 1),
+ "tls_last_state": rd("tls_last_state", 1),
+ }
+ Path(outdir).mkdir(parents=True, exist_ok=True)
+ (Path(outdir) / "pq_state.json").write_text(json.dumps(state, indent=1))
+ print(f"PQ state -> {outdir}/pq_state.json (kex group ${state['tls_kex_group']}, "
+ f"sh_err ${state['tls_sh_err']}, last_state ${state['tls_last_state']})")
+
def _detect_local_ip(target: str) -> str:
s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
@@ -1418,6 +1461,9 @@ def main() -> int:
ROUTINE_ADDR = 0
routine_len = len(_build_http_routine(labels, 0)[0])
ROUTINE_ADDR = arbiter.alloc(routine_len, name="trampoline")
+ global PQ_PARK_ADDR
+ if PQ_DUMP_DIR:
+ PQ_PARK_ADDR = arbiter.alloc(8, name="pq park stub")
print(
f"\nMemoryPolicy reserved {len(memory_policy.reserved_regions)}"
f" region(s); arbiter allocations:"
@@ -1648,7 +1694,7 @@ def main() -> int:
print("load_prg(PRG), verify, SYS (#199)...")
try:
- load_verified_and_run(client, prg)
+ load_verified_and_run(client, prg, labels_path=LABELS_PATH)
except PrgLoadError as exc:
print(f"[fatal] {exc}", file=sys.stderr)
return 4
@@ -1771,6 +1817,8 @@ def main() -> int:
if server_thread is not None:
server_thread.join(timeout=1.0)
_dump_full(transport, labels, server_result, run_dir=run_dir)
+ if PQ_DUMP_DIR:
+ _pq_dump(client, transport, labels, PQ_DUMP_DIR)
outcome = "TIMEOUT"
exit_code = 1
return exit_code
@@ -1780,6 +1828,8 @@ def main() -> int:
if server_thread is not None:
server_thread.join(timeout=5.0)
_dump_full(transport, labels, server_result, run_dir=run_dir)
+ if PQ_DUMP_DIR:
+ _pq_dump(client, transport, labels, PQ_DUMP_DIR)
# Reread resp_data + screen_text for the assertion logic below.
resp_len_raw = transport.read_memory(labels["http_resp_len"], 2)