Skip to content

Key management

Key material and bearer credentials are the most important operational assets in a Witness deployment. The project is pre-1.0 and unaudited; use protected hosts, access-controlled files, and a credential process appropriate to the deployment. Do not commit keys, tokens, or secret-bearing network.json or witness.json files.

Witness signing keys

Each witness has one Ed25519 private key or one BLS12-381 secret key share. Generate it with the node binary and a secure operating-system random source:

target/release/witness-node --generate-key
target/release/witness-node --generate-key --bls

The private key belongs in the witness's protected witness.json; share only the public key with the network coordinator. The declared signature scheme and the gateway's network.json must agree. A private key compromise can let an attacker produce that witness's signatures.

Bearer credentials

Protect all of these separately and use high-entropy, deployment-specific values:

  • each witness signing_auth_token in witness.json and matching gateway auth_token in network.json;
  • federation peer auth_token values and inbound_auth_token values;
  • WITNESS_ADMIN_API_KEY;
  • WITNESS_METRICS_TOKEN and WITNESS_WS_AUTH_TOKEN; and
  • external anchor credentials and private keys.

The gateway validates that every witness auth_token is present and non-empty at startup. Network verification responses omit these operational tokens; do not assume that a raw configuration file is safe to publish.

Rotation boundaries

The current node accepts previous_signing_auth_token as well as the current token during a transition, and federation accepts previous_inbound_auth_token. This creates an overlap window for a coordinated configuration change. It is not a general revoke mechanism. Do not claim a credential is revoked unless the deployment has actually removed access and the affected configuration has been reviewed by clients.

Keep keys and tokens out of logs, backups that lack access control, shell history, and incident reports. The node zeroizes configured key/token strings when its configuration is dropped, but this does not protect the source files, running host, or previously exposed copies.