Skip to main content

Secret Zero — Bootstrap Trust Chain

Arcan never stores the master key in the database. It stores a reference to where the key lives.

Bootstrap by Mode​

ModeKey SourceBootstrap
Standalone (default)Auto-generated file at ~/.arcan/master.keyCreated on first arcan server — zero config
Standalone + KMS (recommended)AWS KMS / GCP KMS / Azure Key VaultOperator runs arcan master-key setup --provider aws once
Multi-nodeKMS (required)All nodes share the same KMS key reference — config via env vars or config file

The Rule​

The master key (or its KMS reference) is the only secret Arcan needs to start. Everything else (database credentials, API tokens, plugin auth keys) is either derived from the master key via HKDF or encrypted by it.

Standalone Auto-Key​

On first arcan server, if no master key is configured:

  1. Generates a cryptographically random 256-bit (32-byte) key
  2. Writes to ~/.arcan/master.key with 0600 permissions (owner read/write only)
  3. Logs: Master key auto-generated at ~/.arcan/master.key
  4. Derives all other keys via HKDF (see Key Hierarchy)

This is production-grade encryption — same AES-256-GCM as KMS-backed mode. The only difference is where the master key lives (local file vs HSM). For real-world deployments handling sensitive secrets, KMS is recommended because:

  • The master key never exists outside the HSM
  • Envelope encryption — data key is encrypted by KMS, decrypted only in memory
  • Automatic key rotation (provider-managed)
  • Audit trail on key usage (CloudTrail, GCP Audit Logs, etc.)

Multi-node Key Requirement​

Multi-node mode requires KMS. File-based master keys cannot be safely shared across nodes:

  • Copying a key file to multiple servers increases exposure surface
  • No audit trail on key access
  • No automatic rotation
  • Key revocation requires touching every node

Arcan refuses to start in Multi-node with a file-based key:

✗ Multi-node mode requires KMS for the master key.
  A file-based master key cannot be safely shared across nodes.
  Configure KMS: arcan master-key setup --provider aws|gcp|azure

Upgrade Path: File → KMS​

# Set up KMS key
arcan master-key setup --provider aws --key-id alias/arcan-master

# Re-wrap existing data encryption key with new KMS key
arcan master-key rewrap

# Remove the old file-based key
rm ~/.arcan/master.key

# Restart — now using KMS
arcan server

No data re-encryption needed. The rewrap command re-encrypts the Data Encryption Key (DEK) with the new KMS key. All stored secrets remain encrypted with the same DEK.