Master Key Rotation

Updated Jun 7, 2026 Edit this page

Master Key Rotation

The Master Encryption Key (SERVOS_MASTER_KEY) is the root of trust for your ServOS installation. It encrypts all sensitive data at rest, including:

  • Server SSH Private Keys & Passphrases
  • Service Environment Variables
  • Environment Variables (Environment-level)
  • Git Access Tokens
  • Registry Credentials
  • Storage Provider Secrets

When to Rotate

You should rotate your Master Key if:

  1. You suspect the servos.env file or the environment variables have been compromised.
  2. An administrator with access to the server has left the organization (and had access to the raw key).
  3. As part of a regular security compliance schedule (e.g., annually).

The Rotation Process

ServOS provides an automated API endpoint to handle the complex process of re-encrypting your database.

⚠️ WARNING: This is a dangerous operation. If the process is interrupted (e.g., power failure) in the middle of the transaction, your database could be left in an inconsistent state (though the database transaction should roll back, external factors can vary). Always backup your database before proceeding.

Step-by-Step Guide

1. Backup Your Database

Ensure you have a full SQL dump of your servos database.

# Example for SQLite
cp /var/lib/servos/servos.db /var/lib/servos/servos.db.backup

2. Generate a New Key

Generate a new 32-byte hex string. You can use OpenSSL:

openssl rand -hex 32

3. Call the API

Make a POST request to /api/maintenance/rotate-key. You will need your Old Key and the New Key.

curl -X POST https://servos.yourdomain.com/api/maintenance/rotate-key \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "old_key": "CURRENT_MASTER_KEY_HEX",
    "new_key": "NEW_GENERATED_KEY_HEX"
  }'

4. Update Configuration

Immediately after receiving a success response, you must update the servos.env file on your server with the new key.

# /etc/servos/servos.env
SERVOS_MASTER_KEY=<NEW_GENERATED_KEY_HEX>

5. Restart ServOS

Restart the service to load the new key.

sudo systemctl restart servos

IMPORTANT: The new key will not take effect until the service is restarted. If you skip this step, the API will continue trying to decrypt data with the old key (from memory) while writing new data with the new key (from the DB transaction), leading to immediate decryption errors.

Troubleshooting

  • “Integrity canary not found”: This entails your database is corrupted or was never initialized correctly with an integrity check.
  • “Old master key incorrect”: The key you provided in old_key does not match the one currently encrypting the data.