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)