Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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%"

Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions cfg/c64-https-uci-onchip-cold.cfg
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions cfg/c64-https-uci-onchip.cfg
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions cfg/c64-https-uci.cfg
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
75 changes: 75 additions & 0 deletions docs/engineering-notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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=<dir>` 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.
2 changes: 2 additions & 0 deletions pytest.ini
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
43 changes: 33 additions & 10 deletions src/constants.inc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
38 changes: 37 additions & 1 deletion src/crypto/mlkem_link.s
Original file line number Diff line number Diff line change
Expand Up @@ -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"

Expand Down Expand Up @@ -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
Loading