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
299 changes: 249 additions & 50 deletions CLAUDE.md

Large diffs are not rendered by default.

9 changes: 9 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,15 @@ endif
ifdef HTTPS_PORT
CA65FLAGS += -D HTTPS_PORT=$(HTTPS_PORT)
endif
# VIC-II blanking around the CPU-bound crypto primitives (src/vic.s).
# ON by default and that is what ships; `make VIC_BLANK=0` degrades
# vic_blank/vic_unblank to bare RTS so the badline tax can be measured
# A/B with everything else in the image identical. That control build is
# a measurement tool, not a shipping configuration — see the "VIC-II
# blanking" section of CLAUDE.md for the numbers it produced.
ifeq ($(VIC_BLANK),0)
CA65FLAGS += -D NO_VIC_BLANK=1
endif
# Lazy (=) so the USE_NISTCURVES_ONCHIP_COMB block below can retarget
# CFG to the cfg variant after this line.
LD65FLAGS = -C $(CFG) -Ln build/labels.txt -m build/c64-https.map --dbgfile build/c64-https.dbg
Expand Down
34 changes: 19 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,20 @@ An HTTPS client for the Commodore 64 in 6502 assembly. Implements TLS 1.3 over T
Grab a release — latest is
[**v0.2.0**](https://github.com/JC-000/c64-https/releases/tag/v0.2.0).
Every build is prebuilt, as a `.prg` and as a bootable `.d64`.
No assembler, no cc65, no Python packages, no build step. Two questions pick
your image, and `MANIFEST.txt` in the release walks through them:
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:

| | REU present | no REU |
| image | for | note |
|---|---|---|
| **Ultimate 64 / C64 Ultimate** | `c64-https-uci-reu` | `c64-https-uci-onchip` |
| **stock C64 + RR-Net** | `c64-https-ip65-reu` | `c64-https-ip65-onchip` |
| `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. |

The `reu` images are faster below roughly 18 MHz — which is every real stock
C64 — because they offload the ECDSA verify to REU DMA. The `onchip` images
need no REU at all and win above that crossover, so they are the right pick
for Ultimate turbo modes. `ip65-onchip` is the only image a bone-stock
machine with no expansion RAM can run end to end.
The screen blanks during the slow crypto on every image — that is deliberate,
it stops the VIC-II stealing bus cycles and buys ~6.5%. The progress line
returns between handshake phases, so a blank screen for minutes at a time is
the crypto running, not a hang.

`c64-https-listener.py` in the same release is a single self-extracting file
that stands up the server side to point the C64 at: it mints its own
Expand Down Expand Up @@ -213,9 +214,10 @@ cd c64-https
make # build/c64-https.prg (default BACKEND=ip65, REU profile)
make BACKEND=uci # the Ultimate 64 / C64 Ultimate (UCI) variant
make USE_NISTCURVES_ONCHIP=1 # the no-REU "onchip" P-256 verify profile
make VIC_BLANK=0 # measurement control only: VIC blanking off (never ship)
make run # build and launch in VICE (x64sc)
make clean # remove build artifacts
make package # all four backend x profile release artifacts into dist/
make package # the three release products into dist/
```

**Run `make clean` whenever you change `BACKEND=` or any flag.** make
Expand Down Expand Up @@ -274,7 +276,8 @@ Progress:
- [x] ip65 submodule integration — 6.8 KB binary blob at $2000 (TCP/UDP/DNS/DHCP/ARP + RR-Net CS8900a)
- [x] Network wrapper with ZP time-sharing — save/restore $02-$1B around ip65 calls
- [x] Crypto primitives — ChaCha20, Poly1305, AEAD (from c64-wireguard), SHA-256, HMAC-DRBG (from c64-aes256-ecdsa)
- [x] Optimized X25519/fe25519 — REU DMA multiply tables, mult66 quarter-square, self-mod code, 4x-unrolled cswap. `tools/bench_x25519.py` measures one basepoint scalar multiply at **12,635 jiffies = 211 s (3.5 min)** of C64 time (NTSC, VIC-II blanked, ~14 s wall clock under VICE warp)
- [x] Optimized X25519/fe25519 — REU DMA multiply tables, mult66 quarter-square, self-mod code, 4x-unrolled cswap. `tools/bench_x25519.py` measures one basepoint scalar multiply at **12,637 jiffies = 211 s (3.5 min)** of C64 time (NTSC, VIC-II blanked, ~21 s wall clock under VICE warp); the same multiply costs 13,494 jiffies unblanked
- [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
Expand All @@ -291,9 +294,9 @@ Progress:

### 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.10.1, so treat them as a baseline rather than as current. 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.
- **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.11.0, so treat them as a baseline rather than as current. The one profile re-measured at the current pin is comb: 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** ECDSA is stubbed at the TLS layer. The dispatcher advertises `ecdsa_secp384r1_sha384` (0x0503) and routes to `src/crypto/ecdsa_verify_384.s`, but no P-384 build target completes. Measured 2026-08-14: `make p384-overlay` from a clean tree stops at `No rule to make target 'build/labels.txt'`, and after a main build has produced that file it stops at `Segment 'LIB_NISTCURVES_SHA384_TABLES' overflows memory area 'OVERLAY_REGION' by 1536 bytes`. Cert chains requiring P-384 will not verify.
- **`USE_X25519_SIBLING=1` now links under UCI, and still does not under ip65.** The duplicate-symbol failure this entry used to record — `ld65: Error: Duplicate external identifier: 'reu_mul_tables_init'`, on **both** backends — was closed by the `libs/nistcurves` v0.10.1 / `libs/x25519` v0.11.0 bump plus one line of archive surgery: `tools/integration/build_nistcurves_p256.sh` now also drops `reu_mul_init.o`, the SPEC §8.2 `reu_mul` provider that `src/boot.s` supplies itself. Measured at those pins: `make clean && make BACKEND=uci USE_X25519_SIBLING=1` produces a 62,977 B PRG, and ip65 stops instead at `Segment 'X25519_RODATA' overflows memory area 'CRYPTO_OVERLAY' by 3584 bytes` — a placement problem (ip65's overlay slot is 4,212 B against UCI's 7,680 B), not a symbol collision. The flag remains **off by default** and no shipped artifact contains the sibling; the in-tree X25519 in `src/crypto/{x25519,fe25519}.s` is what every release PRG is built from. Flipping the default is a separate decision that wants a hardware handshake behind it.
- **`USE_X25519_SIBLING=1` now links under UCI, and still does not under ip65.** The duplicate-symbol failure this entry used to record — `ld65: Error: Duplicate external identifier: 'reu_mul_tables_init'`, on **both** backends — was closed by the `libs/nistcurves` v0.10.1 / `libs/x25519` v0.11.0 bump plus one line of archive surgery: `tools/integration/build_nistcurves_p256.sh` now also drops `reu_mul_init.o`, the SPEC §8.2 `reu_mul` provider that `src/boot.s` supplies itself. Re-measured at the current v0.11.0 / v0.11.1 pins, unchanged: `make clean && make BACKEND=uci USE_X25519_SIBLING=1` produces a 62,977 B PRG, and ip65 stops instead at `Segment 'X25519_RODATA' overflows memory area 'CRYPTO_OVERLAY' by 3584 bytes` — a placement problem (ip65's overlay slot is 4,212 B against UCI's 7,680 B), not a symbol collision. The flag remains **off by default** and no shipped artifact contains the sibling; the in-tree X25519 in `src/crypto/{x25519,fe25519}.s` is what every release PRG is built from. Flipping the default is a separate decision that wants a hardware handshake behind it.
- **Live internet HTTP GET (UCI backend)** has not been re-verified since the FPGA-fence rework; only the local multi-segment listener is exercised regularly.
- **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.

Expand Down Expand Up @@ -341,7 +344,8 @@ python3 tools/test_package_verify.py # 31 cases: pure-logic tests for the rele
python3 tools/test_pytest_boundary.py # 5 checks: the pytest collection boundary below is intact

# Benchmark
python3 tools/bench_x25519.py # X25519 basepoint multiply: 12,635 jiffies / 211 s C64 time, ~14 s wall under warp
python3 tools/bench_x25519.py # X25519 basepoint multiply: 12,637 jiffies / 211 s C64 time (VIC blanked)
python3 tools/bench_x25519.py --no-blank # same multiply unblanked: 13,494 jiffies — the badline A/B

# Integration tests (require the bridge/TAP rig + dnsmasq; see scripts/setup-bridge-tap.sh below)
python3 tools/test_dns.py # 4 tests: DNS resolution via ip65 over TAP (label, known host, second host, unknown host)
Expand Down
62 changes: 33 additions & 29 deletions src/contract_footprint_asserts.s
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,11 @@
; profile-dependent in a way the §1/§3/§8.0/§13.3 gates are not (see the
; comb exclusion below).
;
; Contract: https://github.com/JC-000/c64-lib-contract — read SPEC.md on
; `main`, NOT the newest git tag (tags lag; main is v0.10.0 as of
; 2026-08-15). Clause referenced here: §6.6 (consumer footprint asserts).
; Contract: https://github.com/JC-000/c64-lib-contract — pin the tag
; (v0.10.3 or later; the old "read `main`, tags lag" advice inverted at
; that release — see the header of src/lib_contract_asserts.s, including
; the one hole in the tag series). Clause referenced here: §6.6 (consumer
; footprint asserts).
;
; ---------------------------------------------------------------------
; WHAT §6.6 IS FOR
Expand Down Expand Up @@ -70,36 +72,39 @@
; leaving an opaque segment overflow to be bisected.
;
; ---------------------------------------------------------------------
; WHY THE COMB PROFILE IS EXCLUDED
; THE COMB EXCLUSION IS GONE (libs/nistcurves v0.11.0)
; ---------------------------------------------------------------------
; The comb archive would FAIL this assert today (27,000 + 1,650 = 28,650
; against 16,384) and the failure would be a false alarm: the comb PRG
; links and runs, so the declared number is wrong, not the build.
; This file used to wrap everything below in `.ifndef USE_NISTCURVES_COMB`,
; because the comb archive would have FAILED the assert with 27,000 + 1,650
; = 28,650 against 16,384 — and that failure would have been a false alarm:
; the comb PRG linked and ran, so the declared number was wrong, not the
; build.
;
; The cause is ours, not upstream's. `tools/integration/build_nistcurves_p256.sh`
; builds the comb profile from upstream's FULL `lib-onchip` archive and
; then `rm -f`s ~7 members (fp384, mod384, curve384, points384_*, ...) to
; narrow it to the P-256 comb set. Upstream's `lib_manifest_onchip.o`
; legitimately describes the archive upstream shipped; it survives our
; member surgery still describing the pre-surgery set. The `reu` and
; `onchip` profiles are unaffected because they build from upstream's
; already-minimal `lib-p256-verify` / `lib-p256-verify-onchip` targets,
; which carry per-variant manifests.
; The cause was ours. `tools/integration/build_nistcurves_p256.sh` built the
; comb profile from upstream's FULL `lib-onchip` archive and then `rm -f`d
; ~13 non-P-256 members to narrow it. Upstream's `lib_manifest_onchip.o`
; legitimately described the archive upstream shipped, and it survived that
; surgery still describing the pre-surgery set — exactly the harm SPEC §6.1
; names ("an archive whose member set a consumer has edited is outside every
; §5/§8.0 manifest claim it ships").
;
; This is precisely the harm SPEC §6.1 names: "an archive whose member set
; a consumer has edited is outside every §5/§8.0 manifest claim it ships."
; The sanctioned remedy is §6.2 `CONTRACT_DEFINES` / `CONTRACT_ZP_DEFINES`
; plus §6.3's `lib-app-owned` target, so the configuration is reachable
; without surgery. Neither exists in the pinned v0.9.1; both ARE implemented
; on libs/nistcurves master (v0.10.1, measured). Retiring the surgery is
; therefore unblocked by the wave bump and is sequenced in c64-https#70 —
; when it lands, delete the .ifdef below and the comb profile is covered
; by the same assert as the other two.
; Fixed at the v0.11.0 pin. Upstream added `lib-p256-comb` /
; `lib-p256-comb-onchip` in response to c64-nist-curves#117, each carrying
; its own §6.4 manifest triple under the `LIB_P256_COMB_ONLY` switch, so the
; wrapper stages a narrow archive that upstream actually ships and the
; declared footprint describes what we link. The comb profile is now covered
; by the same assert as `reu` and `onchip`, with no gating at all.
;
; The comb profile is deliberately excluded from `make package`, so no
; shipped artifact is affected by the gap this exclusion leaves open.
; Two things worth knowing if this ever needs re-litigating:
; - the switch was PRG-NEUTRAL — the comb image is byte-identical
; (`63c7ce868cdd…`) built either way, so the archive change altered the
; manifest and nothing else;
; - the wrapper still drops three members for other reasons
; (`mul_8x8.o`, `data_shared.o`, `reu_mul_init.o` — the §8.0 APP_OWNED
; collision set, c64-https#119). That surgery does not affect the
; numbers this assert reads, because those are per-variant §6.4 values,
; but it is why the §8.0 disjointness asserts are still not writable.

.ifndef USE_NISTCURVES_COMB

.import LIB_NISTCURVES_RESIDENT_BYTES
.import LIB_NISTCURVES_COLD_BYTES
Expand All @@ -116,4 +121,3 @@
.assert LIB_NISTCURVES_RESIDENT_BYTES + LIB_NISTCURVES_COLD_BYTES <= __CRYPTO_RESIDENT_SIZE__, lderror, "libs/nistcurves declared footprint (LIB_NISTCURVES_RESIDENT_BYTES + _COLD_BYTES) exceeds CRYPTO_RESIDENT. Contract SPEC 6.6. Most likely cause is a 6.4 regression: the archive ships a whole-library manifest instead of a per-variant one (27000 B is the whole-library value). Check with od65 --dump-exports on the staged lib_manifest*.o before assuming the library really grew."
.endif

.endif ; USE_NISTCURVES_COMB
34 changes: 30 additions & 4 deletions src/crypto/ecdsa_verify.s
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,10 @@

.include "constants.inc"

; --- VIC-II blanking around the CPU-bound verify (src/vic.s) ---
.import vic_blank
.import vic_unblank

; --- External sibling (c64-nist-curves) entry points ---
.import ecdsa_verify_256
.import ec_scalar_mul_var
Expand Down Expand Up @@ -87,12 +91,28 @@ ecdsa_verify:
; Boot banks out BASIC ROM before any crypto runs (src/boot.s
; writes $36 to $01); the legacy defensive re-bank here was
; redundant and has been removed to save bytes.
;
; Blank the VIC across the whole dispatch: this is the single
; longest CPU-bound stretch of the handshake, and it produces no
; screen output of its own, so badline DMA here is pure loss.
; At the v0.6.0 REU pin the verify was 59.2 s of a U64E's 80.8 s
; handshake at 48 MHz, and 1,416.7 s of a stock 1 MHz ip65 run's
; 2,159.7 s — i.e. roughly two thirds of the whole handshake in
; both cases. See src/vic.s for why blanking is scoped to the
; heavy primitives rather than wrapped around tls_connect.
;
; Both dispatch arms were tail-calls before blanking landed. They
; are now JSRs so there is a return site to unblank at; the carry
; that each arm returns is the verify result and is preserved
; across the unblank by the PHP/PLP pair below.
jsr vic_blank

lda ecdsa_curve_id
beq @p256
; Phase 4a: P-384 dispatcher composes the dual-overlay swap
; (sha384 -> curve) + sibling ecdsa_verify_384. Tail-call so
; the dispatcher's carry return propagates as our return.
jmp ecdsa_verify_384_tls
; (sha384 -> curve) + sibling ecdsa_verify_384.
jsr ecdsa_verify_384_tls
jmp @done

@p256:
; The TLS-populated ecdsa_sig_r, ecdsa_sig_s, ecdsa_hash,
Expand All @@ -101,7 +121,13 @@ ecdsa_verify:
; the sibling's ecdsa_verify_256 ingests. Just hand it the base.
lda #<ecdsa_sig_r
ldx #>ecdsa_sig_r
jmp ecdsa_verify_256 ; carry = verify result, returns to caller
jsr ecdsa_verify_256 ; carry = verify result

@done:
php ; save the verify carry
jsr vic_unblank
plp ; ...and hand it to our caller
rts


; =============================================================================
Expand Down
Loading