config.yaml
Cluster
| Key | Required | Description |
|---|---|---|
mpc_threshold | yes | Signing threshold t. Must satisfy t ≥ ⌊n/2⌋ + 1 for n nodes; 2 for a three-node cluster. |
environment | yes | development or production. In production, NATS connections require TLS client certificates and credentials. |
chain_code | yes | 32 bytes as 64 hexadecimal characters, generated once with openssl rand -hex 32. Used for hierarchical key derivation; must be identical on every node. The node refuses to start without it. |
event_initiator_pubkey | yes | Hex public key of the event initiator (citadel-api). Requests not signed by this key are rejected. |
event_initiator_algorithm | no | ed25519 (default) or p256. |
session_warm_up_delay_ms | no | Delay before a signing session starts, to let peers settle. Production template sets 100. |
max_concurrent_keygen | no | Key-generation sessions the node runs at once. Default 2. |
max_concurrent_signing | no | Signing sessions the node runs at once. Default 10. |
Storage and backups
| Key | Required | Description |
|---|---|---|
badger_password | yes | Encryption password for the share store (AES-256). Do not set this in the file in production, use --password-file or --prompt-credentials. |
db_path | no | Directory holding the share store; the node’s name is appended. Default ./db. |
backup_enabled | no | Periodic encrypted backups of the share store. Default true. |
backup_period_seconds | no | Interval between backups. Default 300. |
backup_dir | no | Where backups are written. Default ./backups. Backups are encrypted with the share-store password. |
Messaging and discovery
| Key | Required | Description |
|---|---|---|
nats.url | yes | NATS server URL, tls://… in production. May be left empty and supplied as NATS_URL. |
nats.username, nats.password | production | NATS credentials. |
nats.tls.client_cert, nats.tls.client_key, nats.tls.ca_cert | production | Paths to the client certificate, key and CA. If omitted in production the node looks in ./certs/. |
consul.address | yes | Consul address. May be left empty and supplied as CONSUL_ADDRESS. |
consul.username, consul.password, consul.token | no | Consul credentials or ACL token. |
Health and authorisation
| Key | Required | Description |
|---|---|---|
healthcheck.enabled | no | Serve GET /health. Default false; enable for container platforms. |
healthcheck.address | no | Listen address. Default 0.0.0.0:8080; use 0.0.0.0 (not localhost) inside containers. |
authorization.enabled | no | Require additional named authorizers to co-sign every keygen, signing and reshare request. |
authorization.required_authorizers | with authorization | Names of the authorizers whose signatures must be present. |
authorization.authorizer_public_keys.<name>.public_key / .algorithm | with authorization | Each authorizer’s public key and algorithm (ed25519 or p256). Generate with citadel-core-cli generate-authorizer. |
Environment variables
| Variable | Effect |
|---|---|
NATS_URL | Overrides nats.url. |
CONSUL_ADDRESS | Overrides consul.address. |
ENVIRONMENT | Default for citadel-core-cli register-peers --environment. |
CITADEL_CORE_NODE_NAME | Used by the systemd unit to pass --name. |
citadel-core start
citadel-core start --name <node> [flags]
| Flag | Description |
|---|---|
--name, -n | Required. The node’s name as it appears in peers.json. |
--config, -c | Path to config.yaml. |
--peers | Path to peers.json; new entries are synced into Consul at start-up. |
--password-file, -f | File containing the share-store password. |
--identity-password-file, -k | File containing the password for the node’s age-encrypted private key. |
--decrypt-private-key, -d | The node’s private key is encrypted; decrypt it at start-up. |
--prompt-credentials, -p | Prompt for the share-store password interactively instead of reading a file. |
--debug | Debug logging. |
citadel-core version prints the version.
citadel-core-cli
| Command | Purpose |
|---|---|
generate-peers -n <count> [-o peers.json] | Create the peer registry. |
register-peers [-p peers.json] [-e <environment>] --config <file> | Write the registry into Consul. |
generate-identity --node <name> [-p peers.json] [-o identity] [--encrypt] [--overwrite] | Create a node’s Ed25519 identity, optionally with the private key encrypted by age. |
generate-initiator [-n event_initiator] [-o .] [--encrypt] [-a ed25519|p256] | Create the event initiator’s key pair. |
generate-authorizer --name <name> [-o .] [--encrypt] [-a ed25519|p256] | Create an authorizer key pair for the optional authorization layer. |
recover --backup-dir <dir> --recovery-path <path> [--force] | Rebuild a share store from encrypted backups. |
version | Print the CLI version. |
Files a node uses
| File | Content | Sensitivity |
|---|---|---|
peers.json | Every node’s name and ID. | Shared with all nodes. |
identity/<node>_identity.json | A node’s public key and metadata. | Shared with all nodes. |
identity/<node>_private.key or .key.age | This node’s private key (plain or encrypted). | Secret: this node only. |
event_initiator.identity.json | The initiator’s public key. | Shared. |
event_initiator.key.age | The initiator’s private key. | Secret: citadel-api only. |
db/<node>/ | Encrypted share store. | Secret. |
backups/*.enc | Encrypted share-store backups. | Secret. |