| ParlorNet Turn-based game server for any computer, old or new | |
| Clients | Protocols | Browsers | Telnet programs | Docs | Source |
For after the current deploy; for Eric to decide. Direction: every process in its own container; the core and each server extension hold their own keypair (Ed25519); the core holds a list of the extensions' public keys, each extension holds the core's public key pinned as SSH known_hosts pins a host key; both sides authenticate on connect. Keys are added, rotated and revoked by editing those lists. No certificate authority.
Today (docs/security-design.md, Extension channel): TLS 1.3 with an external pre-shared key per server extension (parlord/frontends.py, CoreClient.connect in adapters/common.py). The same 32-byte secret sits in the core's key directory (/data/frontends/NAME.key) and in the extension's container.
| Threat | Today: PSK per extension | Keypairs |
|---|---|---|
| Extension's key file stolen | holder acts as that extension to the core, and can pose as the core to that extension (the key is symmetric) | holder acts as that extension to the core; cannot pose as the core |
| Core's key directory stolen (a copy of /data, a backup) | every extension's key: act as any extension, and pose as the core to every extension | public keys only; nothing usable. The core's private key is kept outside /data (section 3) |
| Compromised extension (code execution) | its own sessions, its own SRC; in split mode nothing else | the same: no change |
| Compromised core | everything (the database); also every extension key | everything (the database); no extension's private key |
| Replay | none: fresh handshake randoms, psk_dhe_ke (ephemeral DH), no 0-RTT (Python's ssl has no early data) | none: TLS 1.3 CertificateVerify signs the handshake transcript, ephemeral DH |
| Impersonating the core | needs that extension's PSK | needs the core's private key |
| Enrolment | the secret key file is copied to the extension's host | only public keys move; a private key never leaves where it was made |
The gain is in the two key-theft rows and in enrolment. Against a compromised process it adds nothing: that is the container layout's job (section 4).
(a) TLS 1.3, self-signed certificates as key carriers, pinned on both sides (standard library only). Each process has an Ed25519 key and a self-signed certificate for it (CN=name, basicConstraints=critical,CA:FALSE, a validity of 100 years, since OpenSSL checks the dates of a trust anchor and Python cannot turn that off). Python's ssl has no verify callback, so pinning is two steps: (1) each side loads the other side's listed certificates as its only trust anchors (load_verify_locations(cadata=...)), verify_mode = CERT_REQUIRED, check_hostname = False; OpenSSL then accepts exactly the listed certificates and checks the CertificateVerify signature; (2) after the handshake each side takes getpeercert(binary_form=True), computes the fingerprint (SHA-256 of the SubjectPublicKeyInfo, found by a short DER walk) and looks it up in its list; the name and role come from the matching line, never from the certificate's subject. Tested here with Python 3.13.18 and OpenSSL 3.5.9: a listed Ed25519 client certificate completes the handshake and maps to its name; an unlisted one fails with CERTIFICATE_VERIFY_FAILED: self-signed certificate. So yes, mutual pinning works without a CA; the custom step is the fingerprint lookup after the handshake. Key generation is not in the standard library: openssl req -x509 -newkey ed25519 -nodes -keyout NAME.pem -out NAME.crt -days 36500 -subj /CN=NAME -addext basicConstraints=critical,CA:FALSE on the host (OpenSSL 1.1.1 or later; macOS's /usr/bin/openssl, LibreSSL 3.3.6, has no Ed25519; Debian's has).
(b) TLS 1.3 raw public keys (RFC 7250). Exactly the model, with no certificate at all. OpenSSL has it since 3.2, but Python's ssl exposes no API for it (3.13). Not usable.
(c) A signed-challenge step inside the existing PSK channel (Ed25519). After the PSK handshake each side sends a nonce and signs both nonces, both names and the channel binding. Python has no tls-exporter (no export_keying_material); get_channel_binding("tls-unique") returns matching 32-byte values on both ends of a TLS 1.3 PSK connection (tested), though RFC 9266 does not define tls-unique for TLS 1.3. Without a binding, someone holding the PSK and on the path can relay the challenge. Keeps the PSK (two secrets per extension). Needs the cryptography package (the standard library has no Ed25519): a new dependency, which needs Eric's approval.
**(d) Noise (SSH-like), e.g. Noise_KK_25519_ChaChaPoly_BLAKE2s.** Both static keys known in advance, which is this model. Replaces TLS with a hand-wired framing; uses X25519 keys, not Ed25519; needs cryptography and a Noise library (or an own implementation). Most new code to review.
Recommendation: (a).
| Cost | (a) |
|---|---|
| Dependencies | none in the image; openssl (1.1.1+) on the host to make keys |
| Python | no change (3.13 stays; (a) itself does not need 3.13) |
| Code | about 200 lines: contexts and the fingerprint lookup in parlord/frontends.py and CoreClient.connect (PSK callbacks go), a list reader, the key tool (add, remove, list, fingerprint), key making and mounts in deploy/install-split.sh, the sweep keyed by fingerprint, tests |
| Operations | list lines carry a certificate (about 400 characters of base64), not a bare 32-byte key; certificates are made once and do not expire in practice |
| File | Lives | Mounted |
|---|---|---|
| core: its private key and certificate | host /srv/parlornet-keys/core.pem, core.crt, uid 10042, mode 400 | core, read-only, /run/parlornet/ |
| core: extensions (the extensions' public keys) | host /srv/parlornet-keys/extensions, mode 444 | core, read-only |
| each extension: its private key and certificate | host /srv/parlornet-keys/NAME/key.pem, .crt, its uid, mode 400 | that extension only, read-only |
| each extension: known_cores (the core's public key) | host /srv/parlornet-keys/known_cores, mode 444 | every extension, read-only |
The core's private key is not in /data, so a copy of the database does not carry it.
Format, one key per line, # comments:
web frontend ed25519-cert MIIBNjCB6aADAgECAhR... made 2026-12-01 admin admin ed25519-cert MIIBOTCB7KADAgECAhR... parlord core ed25519-cert MIIBMjCB5aADAgECAhR... (known_cores)
A name may have two lines (overlap). Fingerprints are shown as SHA256: and the unpadded base64 of SHA-256 over the SubjectPublicKeyInfo, the same form as ssh-keygen -l, and checkable without our code: openssl pkey -in key.pem -pubout -outform DER | openssl dgst -sha256 -binary | base64.
The layout of deploy/install-split.sh; the keypair change only replaces its key copies with the mounts above.
| Port | Container | Bound to | Reached by |
|---|---|---|---|
| 6500, 6502, 6503, 6505, 6506 (Outland's 4000) | web, telnet, ios, fibs, outland | its address on its own network parlor-NAME (no NAT) | published on the host |
| 6501 | core | its address on parlor (its way out to SMTP) | published on the host |
| 6590, 6599 | core | its address on parlor-int (--internal) only | the extensions over parlor-int; never published |
| 6510 | admin | its address on parlor-admin | published on the host's loopback only |
Every container: --user its own uid, --cap-drop ALL, no capability added, no-new-privileges, read-only root, no host networking.
What keypairs do about the Docker Desktop reach (Residuals, R2-4): nothing directly. The reach is network-level: an extension reaching the core's 6501, other extensions' published ports, the admin container's 6510, and the host's loopback through host.docker.internal. Keypairs change who can complete the handshake on 6590 and 6599, which already needs a key. The fix belongs to the host:
Docker Desktop cannot be fixed this way (its VM and port forwarder are not the host's firewall); split mode there is for development only.
The check must not run on a production host, because it creates networks and containers and floods 6590. It also can't run on a host whose Docker daemon has iptables, ip-forward or the default bridge turned off, since Docker then enforces neither --internal nor bridge isolation, or on a host whose own firewall drops traffic by default, since every result would then come from that firewall and not from Docker.
The check needs a throwaway Linux VM with a stock Docker Engine (iptables on) and no restrictive host firewall. Its outbound traffic should be cut at the hypervisor, and the VM deleted afterwards.
Needs: Docker Engine with root (sudo), python3 on the host, the repository at main on the VM, ports 6500-6510 free on the VM's loopback. Run from the repository root:
sudo docker build -t parlornet:splitcheck . sudo PARLOR_PREFIX=pnrt PARLOR_NET=pnrt PARLOR_SUBNET=172.31.4.0/24 PARLOR_NET_BASE=172.31 \ PARLOR_DATA=/srv/pnrt PARLOR_KEYDIR=/srv/pnrt-keys PARLOR_PUBLISH_IP=127.0.0.1 \ PARLOR_AUTH=password PARLOR_SIGNUP=password sh deploy/install-split.sh parlornet:splitcheck
for c in pnrt-web pnrt-admin; do sudo docker exec -i $c python - \ 172.31.5.2:6590 172.31.5.2:6599 172.31.4.10:6501 \ 172.31.12.2:6502 172.31.13.2:6503 172.31.14.2:6505 172.31.15.2:4000 172.31.16.2:6510 172.31.11.2:6500 \ 172.31.11.1:22 172.31.11.1:6501 172.31.5.1:22 HOST_LAN_IP:22 HOST_LAN_IP:6501 \ OUTSIDE_IP:8080 < review/split2_probe.py; done
python3 review/split2_check.py 20 baseline sudo docker exec -i pnrt-web python - flood 172.31.5.2 6590 40 < review/split2_probe.py & sleep 3; python3 review/split2_check.py 20 flood; wait
sudo iptables -S FORWARD; sudo iptables -S DOCKER-ISOLATION-STAGE-1; sudo iptables -S DOCKER-ISOLATION-STAGE-2 sysctl net.ipv4.conf.all.route_localnet
Passing: each probe prints its own uid (10043 web, 10049 admin) and reach only for 172.31.5.2:6590 and 172.31.5.2:6599; every other target blocked (a container's own address excepted). The host-gateway and LAN targets may be reachable until the input rules above are in place; that is recorded as a finding, then re-run with the rules. split2_check.py shows 20/20 and 3/3 both times. If route_localnet is 1, a check from another LAN machine that 6510 (loopback-only) is not reachable is added.
Clean up:
sudo docker rm -f pnrt-core pnrt-web pnrt-telnet pnrt-ios pnrt-fibs pnrt-outland pnrt-admin sudo docker network rm pnrt pnrt-int pnrt-web pnrt-telnet pnrt-ios pnrt-fibs pnrt-outland pnrt-admin sudo rm -rf /srv/pnrt /srv/pnrt-keys sudo docker image rm parlornet:splitcheck
The result holds for the Docker version tested. Compare the production host's Docker version before relying on it there.
All processes run on one host and are replaced together, so there is no period with both channels: the new version speaks only (a).
Every stored session ends once (their fingerprints are PSK fingerprints): players sign in again.
Rollback: docker rm -f parlornet-core parlornet-web parlornet-telnet parlornet-ios parlornet-fibs parlornet-outland parlornet-admin, then sh install.sh parlornet:OLD. The old container uses /srv/parlornet and its PSK keys as before; sessions issued in split mode end at their first resume. If the new version changed the database schema, restore the copy from step 2 (games since then are lost). The extra networks can stay or be removed.
| These pages cover every ParlorNet server. | Source code | ParlorNet is free software. |