ParlorNet
Turn-based game server for any computer, old or new
Clients | Protocols | Browsers | Telnet programs | Docs | Source

Design note: a keypair per process (proposal, not built)

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.

1. Today and what changes

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.

ThreatToday: PSK per extensionKeypairs
Extension's key file stolenholder 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 extensionpublic 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 elsethe same: no change
Compromised coreeverything (the database); also every extension keyeverything (the database); no extension's private key
Replaynone: 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 coreneeds that extension's PSKneeds the core's private key
Enrolmentthe secret key file is copied to the extension's hostonly 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).

2. Handshake options without a CA

(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)
Dependenciesnone in the image; openssl (1.1.1+) on the host to make keys
Pythonno change (3.13 stays; (a) itself does not need 3.13)
Codeabout 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
Operationslist 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

3. The key lists

FileLivesMounted
core: its private key and certificatehost /srv/parlornet-keys/core.pem, core.crt, uid 10042, mode 400core, read-only, /run/parlornet/
core: extensions (the extensions' public keys)host /srv/parlornet-keys/extensions, mode 444core, read-only
each extension: its private key and certificatehost /srv/parlornet-keys/NAME/key.pem, .crt, its uid, mode 400that extension only, read-only
each extension: known_cores (the core's public key)host /srv/parlornet-keys/known_cores, mode 444every 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:

name role algorithm key (base64 DER certificate) comment

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.

4. The container layout

The layout of deploy/install-split.sh; the keypair change only replaces its key copies with the mounts above.

PortContainerBound toReached by
6500, 6502, 6503, 6505, 6506 (Outland's 4000)web, telnet, ios, fibs, outlandits address on its own network parlor-NAME (no NAT)published on the host
6501coreits address on parlor (its way out to SMTP)published on the host
6590, 6599coreits address on parlor-int (--internal) onlythe extensions over parlor-int; never published
6510adminits address on parlor-adminpublished 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 Linux check (before split mode is recommended)

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

reach from a compromised extension (the web's and the admin container's view)

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

OUTSIDE_IP: a listener the tester starts on a separate network (not the internet)

slots: baseline, then with the web flooding the extension channel

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

the rules Docker made

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.

5. Migration and rollback

All processes run on one host and are replaced together, so there is no period with both channels: the new version speaks only (a).

  1. The Linux check passes on the test host, with the firewall rules.
  2. On the production host: docker stop parlornet; copy /srv/parlornet to /srv/parlornet.bak-DATE.
  3. install-split.sh (new version): makes the keys and lists under /srv/parlornet-keys, removes the parlornet container, starts the core and the extensions on the same ports. It leaves /srv/parlornet/frontends (the PSK keys) as it is.
  4. Add the bridge rules to the host firewall.
  5. Check: every public port answers; the core's log names each extension and fingerprint at its handshake; the console lists them.

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.

6. Open questions

  1. Option (a), standard library only, or (c)/(d) with the cryptography dependency?
  2. Rotation: keep an extension's sessions while its old and new keys are both listed (proposed), or end them at once as today?
  3. Admin console: show the lists and the host commands (proposed; the lists stay read-only mounts), or edit them (the core's list would move to a writable place the core controls)?
  4. Keypairs pay off with separate containers or remote extensions; in the single default container one user reads every file anyway. Build them only together with moving parlornet.org to split mode?
  5. The host firewall needs rules for the new bridges. Who makes that change, and when?
  6. Which host runs the Linux check? A throwaway VM with a stock Docker Engine is proposed.

This doc on GitHub


 These pages cover every ParlorNet server. | Source code | ParlorNet is free software.