Protecting the bunker key

How the key is kept

The bunker keeps its key in ./data/bunker-key.enc, encrypted with XChaCha20-Poly1305 under a root credential. The root credential is 32 random bytes, written as 64 hex characters in ./secrets/bancwr_root_key.

  • Compose mounts the root credential read-only into the bunker as a secret. The bunker reads it at every start, through BANCWR_ROOT_KEY_FILE.
  • The key file on its own, or a backup of ./data, is no use without the root credential.
  • The two files together are the key. Keep them apart: never put the root credential in a backup of ./data, or in the same place as one.

Every other identity the bunker holds is encrypted under the same root credential, and kept in the database. See Signing identities.

What this does not protect against

Anyone who controls the server can read both files, or the bunker's memory, and so the key. Encryption at rest protects copies of ./data and backups that leave the server. It does not protect a server someone else controls. The threat model lists this and the other known limits.

Every identity a bunker holds shares the one root credential, in the one process. Whoever controls the server has them all. Run separate bunkers for keys that must not share that fate.

What a copy of ./data reveals

A copy of…Reveals the key?Also holds
./data on its ownNo. The key file is encrypted.The team and their roles, connection tokens (only a hash of each secret), connected apps, the signing log and the bunker relays.
./data and ./secrets/bancwr_root_keyYes.Everything above.
A bunker backup archive on its ownNo. It is encrypted under the backup passphrase, and the key inside it is still encrypted under the root credential.The same as ./data, once decrypted.
./sessionsNo.Sign-in sessions, named by a hash of their id. A copy is no way to sign in.

The database names every member and every connected app, so keep copies of ./data and backups as private as the server.

Importing the key

The key is imported once, with bunker import-key, from a plain copy mounted for that one command. See Import the key on the installation page.

  • The import encrypts the key under the root credential and prints the bunker's npub.
  • It never replaces an existing ./data/bunker-key.enc. To start again, stop the bunker and remove that file first.
  • Delete the plain copy straight after. Check for any other copy too: in .env, in any compose.override.yaml, in editor backups such as bunker_nsec~, or in your shell history.

The console never imports a key, so a key never passes through a browser.

When the bunker will not sign

The bunker never reads a plain key while it runs. It starts locked, and signs nothing, when:

  • BUNKER_NSEC or BUNKER_NSEC_FILE is still set, whether or not the key has been imported,
  • BANCWR_ROOT_KEY_FILE is not set, or its file cannot be read or is not 64 hex characters,
  • ./data/bunker-key.enc is missing or cannot be read,
  • the root credential does not decrypt the key file: either it is the wrong credential, or the key file has been altered,
  • another identity in the database cannot be decrypted. The status names it by its label.

A locked bunker keeps running so it can say why. NIP-46 does not start, and every console page except the dashboard's health answers with an error.

Finding out why

The container shows as unhealthy, and the reason appears in three places:

  • the health check:
    podman exec bancwr-bunker bunker healthcheck
    
  • the bunker's log:
    podman logs bancwr-bunker
    
  • the console's dashboard, where the Signer check is red with the same words.

Fixing it

Fix the cause, then recreate the bunker:

podman compose up -d
  • A plain key is still set. Find where:
    podman inspect bancwr-bunker --format '{{range .Config.Env}}{{println .}}{{end}}' | grep NSEC
    

    Remove it from .env or compose.override.yaml.
  • The root credential cannot be read. Check ./secrets/bancwr_root_key exists, holds 64 hex characters, belongs to user ID 65532 and has mode 0400. See Hand the files to the bunker's user.
  • The key file is missing. Import the key, or restore a backup.
  • The wrong credential, or an altered key file or identity. Put back the root credential that was used for the import, from where you kept it. If the key file or the database was altered, restore it from a backup.

Keep copies somewhere else

If the server is lost, the key goes with it, and so does the bunker's identity. Keep, each apart from the others:

  • The plain key, one copy offline, in a password manager or on an encrypted drive.
  • The root credential, somewhere other than the backups of ./data. Without it, bunker-key.enc cannot be decrypted, and a restored bunker stays locked unless you import the plain key again.
  • The backup passphrase, apart from both the root credential and the backups. Without it, a backup cannot be opened.

Your own user cannot read the secrets once they belong to user ID 65532. To read or replace one, use podman unshare with rootless Podman, or sudo with Docker.

The bunker's key never signs in

The bunker's key, and every other identity it holds, can never sign in to the console or be registered as a member. The bunker signs for other people, so anyone it signs for could otherwise get it to sign a Bancwr sign-in. See Why the bunker's key can never sign in.