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
51 changes: 19 additions & 32 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -540,34 +540,17 @@ engineering-notes.

## End-to-end HTTPS status

**Real servers work** (2026-08-21/22, U64E @ 48 MHz, comb): github.com,
browserleaks.com, lwn.net all HTTP 200 (~32-39 s to Finished), and
en.wikipedia.org's C64 article streamed into REU `$10:0000` via
`HTTPS_BODY_TO_REU=1` and shown by `src/viewer.s` — **handshake and GET
verified, body completeness NOT** (#211). This entry used to claim
125,235 B byte-verified; that does not reproduce on either tree. `http_get`
returns `carry=0`/`http_status=200` on bodies tens of KB short of their
`Content-Length`, intermittently and not as a function of size — measured
offline against a local listener with no chunking, and live at
117,192 / 89,526 / 73,720 B against a same-day 125,703 B anchor. It can also
hang outright. **Do not treat any large-body fetch as complete until #211
closes**; it went unnoticed because the only rig on that path could not go
red on a short body (#210, now fixed: `rig_https_banner.py` derives the
expected size from the response's own framing and gates its exit code on
it). That rig also **sets the CPU clock instead of inheriting it** — a
completeness verdict is clock-sensitive where the banner verdict was not,
and a device left at 1 MHz makes a slow fetch look like a truncated one.
**#211 reproduces on the shipped path.** Two runs of ONE artifact — PRG
`44e6c0dd605db65682131d6621fc9ad7b8b03cb0d22b0b241691abd3c35ed32a`,
`BACKEND=uci USE_NISTCURVES_ONCHIP=1 HTTPS_HOST=en.wikipedia.org
HTTPS_PATH=/wiki/Commodore_64`, U64E @ 48 MHz, `FETCH_TIMEOUT=900`, same
host, same day: one **PASS** (754,413 B consumed == Content-Length, HTTP
200) and one **FAIL** (frozen at 299,123 B, 455,290 B short). One of each:
treat neither as the norm, and do not quote the PASS on its own. The stall is
**abrupt** — the counter freezes and stays frozen for hundreds of seconds,
which is what #219's fast-expiry path predicts — not a trickle. 754,413 B
is the *rendered page* at that path and is not the 125,703 B raw-article
figure quoted above; they are different resources. The handshake results above are unaffected. The
**Real servers work** (U64E @ 48 MHz): github.com, browserleaks.com, lwn.net
HTTP 200, and en.wikipedia.org's C64 article (760,609 B at v0.6.0) completes
with consumed == Content-Length on both UCI products, comb and onchip, through
`rig_https_banner.py` — the only completeness oracle (it derives the expected
size from the response's own framing, #210, and **sets the CPU clock instead
of inheriting it**: a device left at 1 MHz makes a slow fetch look
truncated). Silent truncation (#211: `http_get` returning `carry=0`/HTTP 200
on a short body, or hanging) is **closed** (2026-09-24, PR #238); the
2026-08/09 truncated sizes and the shipped-path PASS/FAIL pair in the issue
predate that fix. A completeness claim still comes only from that rig's
verdict, never from `carry` or `http_status`. The
local-listener handshake works on both backends (UCI at 48 MHz and 1 MHz;
ip65 in VICE at honest 1 MHz, ~36 min).

Expand All @@ -588,8 +571,9 @@ never exercised:
- Cloudflare is out of scope: ignores MFL and enforces a ~15 s deadline.

PQ_HYBRID (P5): X25519MLKEM768 handshakes complete on the U64E against a local
OpenSSL 3.6.5 `s_server`, onchip and comb images. Live servers, comb image only:
browserleaks.com (HTTP 200) and en.wikipedia.org (HTTP 301 at `/`); github.com and
OpenSSL 3.6.5 `s_server`, onchip and comb images. Live: en.wikipedia.org's C64
article on both release images (see End-to-end status), browserleaks.com (HTTP 200)
and en.wikipedia.org `/` (HTTP 301) on comb; github.com and
lwn.net do not offer 11EC (handshake_failure to a hybrid-only hello). Image hashes,
make lines and timings: the P5 section of engineering-notes.

Expand Down Expand Up @@ -898,8 +882,11 @@ TABLES_BSS.
between each, matrix in `tools/package/_common.sh`:

c64-https-ip65-onchip.prg stock C64 + RR-Net, no REU, no turbo
c64-https-uci-onchip.prg turbo, no REU (TRUST_STORE=1)
c64-https-uci-comb.prg turbo + REU, fastest (needs bank 2 + boot precompute; TRUST_STORE=1)
c64-https-uci-onchip.prg turbo, no REU (TRUST_STORE=1 PQ_HYBRID=1)
c64-https-uci-comb.prg turbo + REU, fastest (needs bank 2 + boot precompute; TRUST_STORE=1 PQ_HYBRID=1)

Since v0.6.0 both UCI products are `PQ_HYBRID=1`; no classic UCI image ships
any more (build one by omitting `PQ_HYBRID=1`). `ip65-onchip` stays classic.

REU-profile images were retired (curation: still fastest below ~18 MHz,
one line in `PACKAGE_VARIANTS` to restore). **That line is a
Expand Down
59 changes: 48 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ An HTTPS client for the Commodore 64 in 6502 assembly. Implements TLS 1.3 over T
## I just want to run it

Grab a release — latest is
[**v0.5.1**](https://github.com/JC-000/c64-https/releases/tag/v0.5.1).
[**v0.6.0**](https://github.com/JC-000/c64-https/releases/tag/v0.6.0).
It replaces every earlier release; see its release notes for what changed.
Every build is prebuilt, as a `.prg` and as a bootable `.d64`.
No assembler, no cc65, no Python packages, no build step. `MANIFEST.txt` in
Expand All @@ -28,8 +28,8 @@ the release walks you through the choice:
| image | for | note |
|---|---|---|
| `c64-https-ip65-onchip` | bone-stock C64 + RR-Net cartridge | maximum compatibility: no REU, no turbo, nothing optional. If you are not sure what you have, this is the one that runs. ~36 min per handshake at 1 MHz. |
| `c64-https-uci-onchip` | Ultimate 64 / C64 Ultimate at turbo, REU off | boots straight to the menu |
| `c64-https-uci-comb` | Ultimate 64 / C64 Ultimate at turbo, REU **on** | fastest — 1.73x quicker verify (16.4 s vs 28.4 s, U64E at 48 MHz). Builds a 16 KB table into REU bank 2 at each boot first: ~34 s at 64 MHz, ~45 s at 48 MHz. |
| `c64-https-uci-onchip` | Ultimate 64 / C64 Ultimate at turbo, REU off | boots straight to the menu; offers the hybrid X25519MLKEM768 (post-quantum) key exchange (about +2.5 s, n=3 to client Finished) |
| `c64-https-uci-comb` | Ultimate 64 / C64 Ultimate at turbo, REU **on** | fastest — 1.73x quicker verify (16.4 s vs 28.4 s, U64E at 48 MHz). Builds a 16 KB table into REU bank 2 at each boot first: ~34 s at 64 MHz, ~45 s at 48 MHz. Also offers X25519MLKEM768 (about +2.5 s, n=3 to client Finished vs the same image without it). |
| `c64-https-uci-m3-demo` | Ultimate 64 with the M3 (ESP32 TLS) firmware | a secondary variant: TLS runs on the Ultimate's ESP32, not the 6510; needs M3 firmware. Its own README is in the release. |

Every image carries **one** default host, baked in at build time (`make
Expand Down Expand Up @@ -135,6 +135,10 @@ a venv mismatch reproduces #90 exactly after an install that appeared to succeed
make BACKEND=ip65 make BACKEND=uci
```

On the UCI images built `PQ_HYBRID=1` (both shipped ones) the key exchange
is X25519 plus ML-KEM-768 (X25519MLKEM768); the box above shows the classic
ECDHE only.

The TLS, HTTP, and crypto layers are backend-agnostic: switching backend
is a link-line change (different cfg + different `src/net/<backend>/*.o`),
not a call-site change.
Expand Down Expand Up @@ -166,7 +170,7 @@ anywhere in `src/crypto/`.

- **AEAD:** ChaCha20-Poly1305 — in-tree `src/crypto/{chacha20,poly1305,aead}.s`, originally from [c64-wireguard](https://github.com/JC-000/c64-wireguard)
- **Hash:** SHA-256 — in-tree `src/crypto/sha256.s`, originally from [c64-aes256-ecdsa](https://github.com/JC-000/c64-aes256-ecdsa)
- **Key exchange:** ECDHE with X25519 only — `supported_groups` and `key_share` carry the single group 0x001D (`src/tls_handshake.s`, grep `group = x25519`); the vendored `libs/x25519` sibling, built on-chip (no REU) on every profile
- **Key exchange:** `uci-onchip` and `uci-comb` (built `PQ_HYBRID=1`) offer X25519MLKEM768 (0x11EC: ML-KEM-768 encapsulation key || X25519 share) first and X25519 (0x001D) second, in `supported_groups` and `key_share`; the server picks. A 0x11EC answer feeds `mlkem_ss || x25519_ss` into the handshake secret (draft-ietf-tls-ecdhe-mlkem, ML-KEM first); a 0x001D answer uses X25519 alone. `ip65-onchip`, and any build without `PQ_HYBRID=1`, offers only 0x001D (`src/tls_handshake.s`, grep `group = x25519`). X25519 is the vendored `libs/x25519` sibling, built on-chip (no REU) on every profile; ML-KEM-768 is the vendored `libs/mlkem` (c64-mlkem), UCI only
- **Certificate signatures:** ECDSA P-256 (`ecdsa_secp256r1_sha256`, 0x0403) from the [c64-nist-curves](https://github.com/JC-000/c64-nist-curves) submodule at `libs/nistcurves`, via the thin dispatcher `src/crypto/ecdsa_verify.s`. P-384 (0x0503) is **retired**: not advertised, and refused — see Known Issues.
- **Key derivation:** HKDF-SHA256, built from HMAC-SHA256 (`src/hkdf.s`)
- **PRNG:** HMAC-DRBG seeded from SID voice 3 noise + CIA timer entropy (`src/entropy.s`, `src/crypto/hmac_drbg.s`)
Expand Down Expand Up @@ -213,9 +217,9 @@ otherwise, and nothing here said it before:
key change is not saved, so the old key still applies. To keep the
store elsewhere, build with the product's own arguments from
`tools/package/_common.sh` plus `TRUST_STORE_DIR=`, e.g. `make BACKEND=uci
USE_NISTCURVES_ONCHIP=1 TRUST_STORE=1 TRUST_STORE_DIR=/SD` for
USE_NISTCURVES_ONCHIP=1 TRUST_STORE=1 PQ_HYBRID=1 TRUST_STORE_DIR=/SD` for
`uci-onchip`, or `make BACKEND=uci USE_NISTCURVES_ONCHIP_COMB=1
TRUST_STORE=1 TRUST_STORE_DIR=/SD` for `uci-comb`. The directory must
TRUST_STORE=1 PQ_HYBRID=1 TRUST_STORE_DIR=/SD` for `uci-comb`. The directory must
already exist (the client never creates one) and be an absolute path of
`A-Za-z0-9_.-` components, at most 41 characters.

Expand Down Expand Up @@ -249,6 +253,19 @@ more ECDSA verifies at ~16-30 s each, and a root store means kilobytes of
resident keys — not an oversight. Treat the transport as confidential against
passive observers, not authenticated against active ones.

**What the post-quantum hybrid protects, and what it does not.** `PQ_HYBRID=1`
changes the key exchange only. A passive recorder who later has a quantum
computer cannot recover a session's keys from the recorded handshake unless it
can also break X25519 or ML-KEM-768 ("harvest now, decrypt later"). It changes
nothing about authentication, which stays classical: the server's
CertificateVerify is ECDSA P-256 and the UCI images' only pin is
trust-on-first-use of that leaf key, so forged or stolen P-256 keys, or an
attacker on the path at first use, are not stopped by it. And it is only as
strong as its secrets: this client's DRBG is seeded from SID voice 3 and CIA
timer noise (weak, as stated above), and both the ML-KEM seed and the X25519
private key come from it. Read it as a demonstration of the protocol path, not
as a claim of quantum safety.

Confidentiality against passive observers is the property this client keeps
after conceding authentication, so it is worth saying what upholds it. **As of
v0.4.3** the X25519 shared secret is rejected when it comes out all zero, as
Expand Down Expand Up @@ -305,8 +322,8 @@ section of `build/c64-https.map` for the **three shipped products**
| product | make args | cfg |
|---|---|---|
| `ip65-onchip` | `BACKEND=ip65 USE_NISTCURVES_ONCHIP=1` | `cfg/c64-https-ip65.cfg` |
| `uci-onchip` | `BACKEND=uci USE_NISTCURVES_ONCHIP=1` | `cfg/c64-https-uci.cfg` |
| `uci-comb` | `BACKEND=uci USE_NISTCURVES_ONCHIP_COMB=1` | `cfg/c64-https-uci-onchip-cold.cfg` (`COLD_BANK=0`: `cfg/c64-https-uci-onchip.cfg`) |
| `uci-onchip` | `BACKEND=uci USE_NISTCURVES_ONCHIP=1 PQ_HYBRID=1` | `cfg/c64-https-uci.cfg` |
| `uci-comb` | `BACKEND=uci USE_NISTCURVES_ONCHIP_COMB=1 PQ_HYBRID=1` | `cfg/c64-https-uci-onchip-cold.cfg` (`COLD_BANK=0`: `cfg/c64-https-uci-onchip.cfg`) |

Note the third row: the `-onchip*.cfg` swap is driven by
`USE_NISTCURVES_ONCHIP_COMB`, **not** by `USE_NISTCURVES_ONCHIP` — plain
Expand Down Expand Up @@ -378,6 +395,25 @@ $C000-$CFFF (no region) the 4 KB TCP ring, by equate; not in
$D000-$DFFF I/O never in the PRG (#288)
```

With `PQ_HYBRID=1` (both shipped UCI images) the same layout also carries:

```
$A000-$BFFF (file bytes) the staged ML-KEM image (7,490 B); boot copies
it to $E000 before zeroing the BSS
$B100-$BBFF ML-KEM rest BSS shares the window with the X25519 tables;
scrubbed after KeyGen and after Decaps
$C000-$C95F TCP ring, first the ML-KEM dk scratch (2,400 B), zeroed right
2,400 B after KeyGen; the ring itself is unused then
$D000-$DFFF RAM under I/O ML-KEM polynomial area (not in the PRG, the
CPU banks I/O out to reach it); scrubbed
$E000-$FDFF MLKEM_CODE_RAM the ML-KEM code, copied there at boot
NET_BSS_TAIL tls_pq_seed (64 B) + tls_mlkem_ss (32 B), below
$4200; the ek and the ct each share cert_buf
```

Exact extents: `tools/measure_margins.py` (the `*-pq` profiles) and
`src/crypto/mlkem_link.s`.

`CRYPTO_OVERLAY` is not empty in any shipped UCI image — it holds the
resident tenants listed above. Free space per region is **measured, not
tabulated here**, because it differs per profile and every hand-kept table
Expand Down Expand Up @@ -555,9 +591,9 @@ Progress:
- [x] VIC-II blanking during the CPU-bound crypto — `src/vic.s`, scoped to the two X25519 scalar multiplies and the ECDSA verify so the on-screen handshake progress markers stay visible between phases. Worth **6.3-6.8%**, measured both in VICE at 1 MHz and on a U64E at 8/16/48 MHz; see the VIC-II blanking section of `CLAUDE.md`
- [x] HKDF-SHA256 — Extract, Expand, Expand-Label, Derive-Secret (RFC 5869 + TLS 1.3)
- [x] TLS 1.3 record layer — encrypt/decrypt with ChaCha20-Poly1305, nonce construction, sequence numbers
- [x] TLS 1.3 handshake — ClientHello builder (x25519 key_share, SNI), ServerHello parser, streaming transcript hash
- [x] TLS 1.3 handshake — ClientHello builder (x25519 key_share, SNI; with `PQ_HYBRID=1` also the ML-KEM-768 key share), ServerHello parser (a streaming reader under `PQ_HYBRID=1`), streaming transcript hash
- [x] TLS 1.3 key schedule — early/handshake/master secrets, traffic key derivation, Finished MAC (RFC 8446 §7.1)
- [x] ECDHE x25519 key exchange — generate keypair, compute shared secret
- [x] ECDHE x25519 key exchange — generate keypair, compute shared secret; with `PQ_HYBRID=1` (UCI) also ML-KEM-768 KeyGen/Decaps and the hybrid key schedule (`libs/mlkem`)
- [x] TLS 1.3 key schedule integration testing — all 9 HKDF steps verified against RFC 8448 + Finished MAC
- [x] Entropy/DRBG initialization — SID voice 3 noise + CIA timer seeding at boot, DRBG fills for TLS random values
- [x] X.509 certificate parsing — DER parser extracts TBS, public key, signature (r,s), curve ID (the live TLS path accepts P-256 only)
Expand Down Expand Up @@ -913,6 +949,7 @@ Environment variables honored by `rig_https_local.py`:
Vendored as submodules and linked into the PRG:

- [c64-nist-curves](https://github.com/JC-000/c64-nist-curves) — `libs/nistcurves`, the ECDSA P-256 verify used for CertificateVerify
- [c64-mlkem](https://github.com/JC-000/c64-mlkem) — `libs/mlkem`, ML-KEM-768 for the X25519MLKEM768 hybrid; linked only under `PQ_HYBRID=1` (both shipped UCI images)
- [c64-x25519](https://github.com/JC-000/c64-x25519) — `libs/x25519`, the X25519 in every build since #245 (on-chip profile, via `tools/integration/build_x25519.sh`; lookup tables generated at runtime by `src/crypto/x25519_tables.s`).
- [ip65](https://github.com/cc65/ip65) — the TCP/IP stack behind the ip65 backend

Expand All @@ -921,7 +958,7 @@ Not vendored — origin of code that now lives in-tree, or tooling:
- [c64-wireguard](https://github.com/JC-000/c64-wireguard) — ChaCha20, Poly1305, ChaCha20-Poly1305 AEAD
- [c64-aes256-ecdsa](https://github.com/JC-000/c64-aes256-ecdsa) — AES-256, SHA-256, ECDSA P-256, HMAC-DRBG
- [c64-test-harness](https://github.com/JC-000/c64-test-harness) — VICE test automation framework
- [c64-lib-contract](https://github.com/JC-000/c64-lib-contract) — the segment-naming / manifest contract the two crypto submodules follow
- [c64-lib-contract](https://github.com/JC-000/c64-lib-contract) — the segment-naming / manifest contract the crypto submodules follow

## License

Expand Down
13 changes: 11 additions & 2 deletions docs/engineering-notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -4311,8 +4311,17 @@ all runs full HTTPS PASS, tls_kex_group $EC unless noted):
- comb (REU 16 MB, `C64_INIT_WAIT=90`), `make BACKEND=uci
USE_NISTCURVES_ONCHIP_COMB=1 PQ_HYBRID=1 HTTPS_SNI=www.foo.invalid`, sha256
`265c4c583c2b5a2430daf3a7ee2a3e546d99a8b7c1c4173476e8455097cfa042`: 165 s /
164 s ($1D) / 166 s. With `PHASE_TIMING=1` (1 s poll, n=1 each) trigger to
client Finished 43.7 s hybrid vs 42.0 s X25519-only: about +1.7 s.
164 s ($1D) / 166 s. (A `PHASE_TIMING=1` pair of 43.7 s hybrid vs 42.0 s
X25519-only on this one image was NOT the cost of PQ: both runs pay KeyGen,
since only the server's choice differed. Superseded by the next entry.)
- cost of PQ_HYBRID (v0.6.0 release review): classic image (same arguments, no
`PQ_HYBRID`) vs hybrid image, release arguments plus `HTTPS_SNI`, local
OpenSSL listener (hybrid group for the PQ image), SYS trigger to client
Finished, `PHASE_POLL=0.5`, n=3 each: onchip 52.4/52.1/52.6 s vs
55.2/54.8/54.6 s (+2.5 s), comb 41.0/41.3/40.6 s vs 43.9/43.1/43.4 s
(+2.5 s). The classic runs ended in a rig traceback after the fetch
(`rig_https_local.py`'s `PQ_DUMP` reads PQ-only labels); the CFIN marker and
the sentinel were already reached.
- live (`tools/uci/rig_https_live.py`), comb image WITHOUT `HTTPS_SNI`, `make
BACKEND=uci USE_NISTCURVES_ONCHIP_COMB=1 PQ_HYBRID=1`, sha256
`b8677dd79968fb57e475baaa0995c8979d670b159ae753b207a947d5e8be8d61`:
Expand Down
Loading