Skip to content
Merged
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
42 changes: 15 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,40 +11,29 @@ An HTTPS client for the Commodore 64 in 6502 assembly. Implements TLS 1.3 over T
> handshakes and HTTP GETs against real public servers on the open internet —
> **github.com, browserleaks.com and lwn.net** all return HTTP 200. It also
> streams the **Wikipedia article about the Commodore 64** over TLS into a
> 16 MB REU and scrolls it on the C64's own screen — but **that body is not
> verified**: `http_get` intermittently reports success on a truncated body
> (issue #211), so treat the large-body demo as a demo. The handshake result
> is unaffected. Requires the UCI backend at turbo (comb profile). See the
> 16 MB REU and scrolls it on the C64's own screen. Requires the UCI backend
> at turbo (comb profile). See the
> Project Status section and the "End-to-end HTTPS status" notes in
> `CLAUDE.md`.

## I just want to run it

Grab a release — latest is
[**v0.4.3**](https://github.com/JC-000/c64-https/releases/tag/v0.4.3), a
**security release**.
**If you have any earlier release, replace it.** v0.4.3 carries two
client-side TLS fixes that v0.4.2 and everything before it lack: the X25519
shared secret is now rejected when it comes out all zero (issue #153 — without
that check, a passive observer who merely recorded the session could derive
the traffic keys), and the handshake message sequence is now enforced (issue
#152 — without that, four handshake messages of one harmless type satisfied
the whole flight, so the client could report success having verified no
signature at all). v0.4.0 additionally had a P-384 certificate hang, fixed in
v0.4.1; no real server triggered that one.
[**v0.5.0**](https://github.com/JC-000/c64-https/releases/tag/v0.5.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. **Three products,
one disk each** — the label is the whole contents, and `MANIFEST.txt` in the
release walks you through the choice:
No assembler, no cc65, no Python packages, no build step. `MANIFEST.txt` in
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-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
HTTPS_HOST=...`). On the two **UCI** images, `G` first asks for a host and a
HTTPS_HOST=...`). On the **UCI** images, `G` first asks for a host and a
path (`HOST [default]:`, `PATH [default]:`); RETURN on an empty field keeps
the default, a typed host is lowercased and gets the same name check, and an
entry the prompt cannot take whole (over 63 / 100 characters, a character
Expand All @@ -64,12 +53,12 @@ built — and **that default changed between v0.4.2 and v0.4.3**:
`cdf02b4`, and v0.4.3 is the first release to carry it.

Either way, point the name at the bundled test listener via your local DNS, or
rebuild with your own `HTTPS_HOST=`. New in v0.4.2: the two **UCI** images
rebuild with your own `HTTPS_HOST=`. New in v0.4.2: the **UCI** images
check the server's certificate actually names the host they asked for.
`ip65-onchip` does not — the check is 491 B and no free block in that layout
comes close (issue #135). Read ["What this client does NOT
authenticate"](#what-this-client-does-not-authenticate) before relying on
either: there is still no certificate chain validation on any image, so this
either: there is still no certificate chain validation, so this
is not server authentication.

The screen blanks during the slow crypto on every image — that is deliberate,
Expand Down Expand Up @@ -184,9 +173,8 @@ anywhere in `src/crypto/`.
Worth stating plainly, because "TLS 1.3 / HTTPS client" reasonably implies
otherwise, and nothing here said it before:

- **No certificate chain validation.** There is no trust store, no root CAs,
no issuer check — `src/der_decode.s` skips the issuer field outright
(grep `Skip SEQUENCE issuer`).
- **No certificate chain validation.** `src/der_decode.s` skips the issuer
field outright (grep `Skip SEQUENCE issuer`).
- **Server name validation exists, but only on the UCI images** (`uci-onchip`,
`uci-comb`). Since v0.4.2 they check the certificate's subjectAltName
`dNSName` entries against the host you built for, case-insensitively, with
Expand Down Expand Up @@ -549,14 +537,14 @@ Progress:
- ip65 on **real RR-Net silicon — a first, 2026-09-05.** An RR-Net (CS8900a) cartridge in a cartridge port, on its own wired 10.0.66.0/24 segment, ran the whole path at **stock 1 MHz with no turbo and no REU**: DHCP (the C64 took the pinned lease, read back from its own `net_local_ip` rather than from the server's lease file), a DNS lookup over the cartridge, a 141-byte ClientHello with the correct SNI on the cable, application data both ways, and **HTTP 200** with the body byte-checked out of `http_resp_buf` and `net_last_error` `$00`. Every check the rig ran passed. They are not all wire checks: the wire assertions that attribute traffic to the cartridge discriminate it by Ethernet source address, the rest read the C64's own memory back over DMA or assert host-side preconditions, and `tests/rig_ip65_rrnet_hw.py` says which is which. **1,979 s (33.0 min)** from `G` to done, n=1 on both sides — faster than the same profile in VICE at honest 1 MHz, and by **at least** the ~8% the raw figures show, because the VICE number predates the current `libs/nistcurves` pin and the newer pin is slower (the first Known Issues bullet below carries both that figure and the pin caveat). Our first measurement of the real cartridge port. The "body never appears on the wire in clear" check passed *conclusively*, because its positive control — the SNI, which genuinely is in the clear in the ClientHello — was found, making that a claim about the wire rather than about the searcher. **Scope:** this is `ip65-onchip` against the bundled local listener. It does not exercise ip65 against a real internet server, it says nothing about the two UCI images, and it does not touch the chain-validation or name-validation caveats above — `ip65-onchip` still does neither.
- The same cartridge at **48 MHz turbo, 2026-09-06.** `TURBO_MHZ=48` on the same rig, the same build configuration and the same `G`-to-`CONNECTION CLOSED` boundary: **43.1 s, a 46x speed-up** over the 1 MHz run above. That comparison is like-for-like — same rig, same cartridge, real silicon on both sides — and is a different kind of claim from the VICE comparison in the bullet above, which crosses a `libs/nistcurves` pin and therefore stays a lower bound. The open risk was CS8900a register timing at turbo, which is the reason the rig defaults to stock speed, and it did not materialise: DHCP completed on the automatic attempt with no retries, because ip65's ~15 s budget rides CIA2 timer B and the CIA timers run at real phi2 at every CPU clock (measured, with the negative control that separates that from a CPU still at 1 MHz, in `docs/engineering-notes.md`; reproducer `tools/probe_cia_timer_rate.py`). **24 of 25 checks passed, and the one that failed has to be read before this run is quoted.** `check_tls_connected` samples `tls_state` over DMA, and at 48 MHz the window in which that value exists — between the traffic-key derivation and `tls_close` — fits inside a single poll. So the handshake's completion at turbo is **inference from converging evidence** (HTTP 200 and the exact body out of the C64's own buffer, `TLS HANDSHAKE OK` on screen, application data both ways on the cable) **rather than the direct observation the 1 MHz run had.** It is the weaker of the two results and the check was left red rather than softened; `tests/rig_ip65_rrnet_hw.py` says why, and issue #204 tracks the fix. **Nothing else widens:** still one device, one cartridge, one local listener, the same port-only deviation from the shipped image, and still no server-name validation on ip65. This adds a second clock and no more.
- [x] **Real public-internet HTTPS (UCI/comb, turbo)** — github.com, browserleaks.com and lwn.net all return `http_status=200` on real U64E hardware at 48 MHz. Needed three pieces of work over the local-listener path: a streaming handshake-message deframer (`src/tls_deframe.s`) for flights where handshake messages don't align with TLS records; a 2048 B `cert_buf` under UCI so larger real leaves fit; and — the last blocker — clamping the UCI adapter's `SOCKET_READ` request to the receive ring's free space, without which any flight over ~4 KB lost its tail to a ring-wrap drop. Build-time target is `make HTTPS_HOST=<host>` / `HTTPS_PATH=<path>`; the rig is `tools/uci/rig_https_live.py`.
- [x] **Wikipedia article into REU + on-screen viewer (stretch goal, UCI/comb) — demonstrated, body NOT verified.** `make HTTPS_HOST=en.wikipedia.org HTTPS_PATH='/w/index.php?title=Commodore_64&action=raw' HTTPS_BODY_TO_REU=1` streams the article body into REU bank 16 (`$10:0000`) and drops into a scroll viewer (`src/viewer.s`, CRSR/SPACE/F1/HOME/Q); the handshake, the GET and the viewer all work on a U64E @ 48 MHz. **What does not hold is the byte count.** This entry used to claim 125,235 B byte-checked against a host-side reference fetch; that does not reproduce on either tree. `http_get` returns `carry=0` with `http_status=200` on bodies tens of kilobytes short of their `Content-Length`, intermittently and not as a function of size — reproduced offline against a local listener with no chunking involved, and seen live at 117,192 / 89,526 / 73,720 B against a same-day 125,703 B `curl` anchor. Those are device runs of three different images and #211 names the PRG sha256 of each, which is what identifies them — a commit stops identifying an image the moment a docs commit lands on top of it. That is **issue #211**, and until it is closed no large-body fetch on any image should be treated as complete. It survived because the one rig on that path could not go red on a short body (**issue #210**). The defect is in the body path only: the handshake result above is unaffected, and nothing here changes what the client does or does not authenticate. **ip65 has never been tested against a body large enough to show this** — at any size, in fact, beyond the local listener's short one. Rig: `tools/uci/rig_https_wiki.py`.
- [x] **Wikipedia article into REU + on-screen viewer (stretch goal, UCI/comb) — demonstrated.** `make HTTPS_HOST=en.wikipedia.org HTTPS_PATH='/w/index.php?title=Commodore_64&action=raw' HTTPS_BODY_TO_REU=1` streams the article body into REU bank 16 (`$10:0000`) and drops into a scroll viewer (`src/viewer.s`, CRSR/SPACE/F1/HOME/Q); the handshake, the GET and the viewer all work on a U64E @ 48 MHz. Rig: `tools/uci/rig_https_wiki.py`.

### Known Issues

- **The handshake is slow, and the ECDSA P-256 verify dominates it.** Every figure here is quoted from the measurement record in `CLAUDE.md`. Except where noted they were taken at the **`libs/nistcurves` v0.6.0 pin**, and the pin is now v0.14.0, so treat them as a baseline rather than as current. The one profile re-measured since is comb, at the v0.11.2 pin: 46.986 / 24.440 / 16.402 s verify at 16 / 32 / 48 MHz (U64E, n=3, VIC blanking active). End-to-end handshake + GET against the local listener, U64E, master 2ceb5b1: **80.8 s** (REU profile, 48 MHz), **45.5 s** (onchip profile, 48 MHz), **1,157.7 s** (REU, stock 1 MHz). One point of that sweep has been carried forward: 48 MHz REU measures **82.1 s** at v0.9.1 and **82.4 s** at v0.10.1 (n=1 each, so the 0.4% step between them is noise; the 1.6% from v0.6.0 is the FIPS 186-5 public-key validation gate v0.7.0 added). No other clock or profile has been re-measured. On the REU-less stock-C64 path (ip65 + onchip, no REU, honest 1 MHz in VICE) the whole run measured **2,159.7 s = 36.0 min**, of which the verify stretch alone was 1,416.7 s. That is fine for the local listener, which holds the connection open; it exceeds a typical 10-30 s real-world server handshake window.
- **P-384 is parked, and doubly gated — it is not merely "stubbed".** An earlier version of this entry said the dispatcher "advertises `ecdsa_secp384r1_sha384` (0x0503)". It does not, and has not since v0.4.1: `sig_algs_ext_data` in `src/tls_handshake.s` carries exactly one scheme, `ecdsa_secp256r1_sha256` (0x0403), and `src/crypto/ecdsa_verify.s` compiles its P-384 arm to a `sec` reject unless `ENABLE_P384_VERIFY=1`. Both gates matter, because the curve comes from the certificate rather than from what we advertised — that combination is what closed the v0.4.0 hang in which a P-384 certificate made the overlay swap DMA over live resident code. Separately, **no P-384 build target has ever completed**: `make p384-overlay` from a clean tree stops at `No rule to make target 'build/labels.txt'`, and once a main build has produced that file it stops at `Segment 'LIB_NISTCURVES_SHA384_TABLES' overflows memory area 'OVERLAY_REGION' by 1536 bytes`. Certificates requiring P-384 are rejected, not verified. From the v0.14.0 pin the lane is gated at the **link line** as well: `src/crypto/ecdsa_verify_384.s` and `src/crypto/p384_force_link.s` link only under `ENABLE_P384_VERIFY=1`. They used to be in every shipped image and reachable from none of it — ca65 emits no import record for an `.import` nothing references, so the wildcard pulled them in — at a cost of 332 B (299 B of `CRYPTO_AUX_CODE` + 33 B of `CRYPTO_RODATA`), which is the space that made the v0.14.0 bump fit on ip65 at all. `ENABLE_P384_VERIFY=1` now also applies on all five profiles: it used to be silently dropped by the two REU-profile builds, which is issue #207 — the mutation control that was supposed to fail under it passed vacuously there.
- **Real-server reach is UCI/comb + turbo only, and has size limits.** The public-internet HTTPS above works on the comb profile at turbo; the stock-C64 ip65 path is far too slow for a real server's connection window (~36 min/handshake). Among real leaves, en.wikipedia.org's 1636 B leaf needs the 2048 B UCI `cert_buf` (fits); anything larger, or a server that ignores `max_fragment_length` and sends >548 B records (e.g. Cloudflare), is out of scope. Cloudflare additionally enforces a ~15 s connect-to-first-request deadline the C64 cannot meet and is deliberately unsupported.
- **The wikipedia stall was a client bug, now fixed.** Historical note for anyone bisecting: TLS flights larger than the ~4 KB UCI receive ring used to stall permanently, because `net_poll` requested a fixed 512 B and its fill loop dropped bytes past the ring's current free space (discarded as "delivered"). Fixed by clamping the `SOCKET_READ` request to ring free space (`src/net/uci/net.s`). It was never a firmware bug; github/browserleaks/lwn flights are under 4 KB and were unaffected. **That fix is not the end of the large-body story** — the body path still terminates early and reports success, intermittently, on both trees (issue #211). Do not read this bullet as saying large fetches are now sound.
- **The wikipedia stall was a client bug, now fixed.** Historical note for anyone bisecting: TLS flights larger than the ~4 KB UCI receive ring used to stall permanently, because `net_poll` requested a fixed 512 B and its fill loop dropped bytes past the ring's current free space (discarded as "delivered"). Fixed by clamping the `SOCKET_READ` request to ring free space (`src/net/uci/net.s`). It was never a firmware bug; github/browserleaks/lwn flights are under 4 KB and were unaffected.
- **VICE 3.9** previously appeared to crash on chained HMAC-SHA256 calls (backend-independent — affects the crypto-only test suites), but this was caused by hardcoded port numbers bypassing the test harness port allocator. With proper `ViceInstanceManager` usage (no hardcoded ports), all N=1..10 chained calls succeed reliably.

## Test Automation
Expand Down Expand Up @@ -819,7 +807,7 @@ python3 tools/uci/rig_http_local.py # HTTP GET against local listener
python3 tools/uci/rig_http_live.py # HTTP GET against a real server
python3 tools/uci/rig_https_local.py # HTTPS GET (TLS 1.3 + ECDSA-P256)
python3 tools/uci/rig_https_live.py # HTTPS against a real public server
python3 tools/uci/rig_https_wiki.py # the Wikipedia fetch into the REU (body unverified, #211/#210)
python3 tools/uci/rig_https_wiki.py # the Wikipedia fetch into the REU
python3 tools/uci/rig_https_banner.py # the only rig that walks the menu into do_https_get
python3 tools/uci/rig_https_print_body.py # wrapper: print the response body
python3 tools/uci/rig_https_bad_finished.py # client must ABORT on a forged server Finished
Expand Down