Skip to content

Keys and TLS

A public server needs three secrets: a signing key, a cache secret, and a TLS certificate with its key. Keep all of them outside the data folder, readable only by the user that runs the server.

signing.key, cache.secret, and the TLS private key must deny access to the group and to others, for example mode 0600. The server refuses to start when another user can read one of them. The files you generate with the commands below already have this mode.

Never put a secret inside server.toml. The configuration only holds the paths: security.signing_key, security.cache_secret, network.tls_key.

The server signs every client script package and every manifest with an Ed25519 key. A client runs a package only when the signature matches one of the public keys compiled into the client.

Create the pair once for your game:

Terminal window
cargo xtask keys generate --out /etc/borne

It writes signing.key (mode 0600) and signing.pub, and prints the public key line. It never prints the private key and never overwrites a file. Build your clients with the public key in BORNE_SIGNING_PUBKEYS (a comma-separated list). Set security.signing_key = "/etc/borne/signing.key".

Clients accept a list of keys, so you can change the key without locking players out:

  1. Add the new public key to the list, and release a client build.
  2. When players have the new build, switch the server to the new private key.
  3. Drop the old public key in a later build.

Clients keep downloaded scripts in an encrypted cache. The key is derived from this secret and the account, so it is stable for one account on one server. Changing the secret makes every cache unreadable. Players then download their scripts again.

Make at least 32 random bytes, for example:

Terminal window
head -c 48 /dev/urandom > /etc/borne/cache.secret
chmod 600 /etc/borne/cache.secret

and set security.cache_secret = "/etc/borne/cache.secret".

The game and RC endpoints use TLS 1.3 only.

  • A certificate from a public authority. Set network.tls_cert and network.tls_key. Clients use the system trust store and need nothing else.
  • A self-signed certificate. Leave both keys out. The server creates the certificate under <data_dir>/tls at the first start and prints its SHA-256 fingerprint. Give the fingerprint to your players. A client pins it in its server list entry. A client that does not know the fingerprint asks the player once whether to trust the server. A later change of the certificate is a hard error, not a second question.

Plain ws:// is refused except with --dev or network.allow_insecure_localhost = true, and then only from the same computer. Never use this on a public server.

Client scripts are signed by the server and checked by the client before they run. The client cache is encrypted with a key that exists only in memory while the player is logged in. This keeps a modified or copied cache, and a man in the middle, from running code on a client. It does not make the client trustworthy. The server checks every rule again.

Engine version 0.1.0. Built 2026-11-18.