Key Rotation

Key lifecycle

Each Cosmictron signing key has a lifecycle:

Generated ──► Active ──► Retiring ──► Retired
                │
           Cross-signed
           by new key

• Active — used to sign new events
• Retiring — new key is now active; old key is kept for verification of historical events
• Retired — key is archived; its public key remains in the key registry for verification

Rotating the signing key

1. Generate the new key

   cosmictron-cli keys generate --type ed25519 --name signing-2026-04

2. Cross-sign the new key with the old key

   This produces a certificate binding the new public key to the old key’s trust chain:

   cosmictron-cli keys cross-sign \
     --old-key signing-2025-10 \
     --new-key signing-2026-04

3. Activate the new key

   cosmictron-cli keys activate signing-2026-04

   From this point, new events are signed with the new key. Old events remain valid under the old key.

4. Verify continuity

   cosmictron-cli audit verify --check key-continuity

   The verifier confirms that every event is signed by a key in the continuous trust chain.

5. Retire the old key

   After a retention period (typically 90 days):

   cosmictron-cli keys retire signing-2025-10

Key registry

The key registry records all keys and their lifecycle state:

cosmictron-cli keys list

ID                  Status     Created              Expires
signing-2025-10     retiring   2025-10-01T00:00:00  2026-04-01T00:00:00
signing-2026-04     active     2026-04-01T00:00:00  2026-10-01T00:00:00

Emergency key rotation

If a key is compromised:

# Immediately stop signing with the compromised key
cosmictron-cli keys revoke signing-2025-10 --reason "key compromise"

# Generate emergency replacement
cosmictron-cli keys generate --type ed25519 --name signing-emergency-2026-04

# Activate immediately (cannot cross-sign from compromised key)
cosmictron-cli keys activate signing-emergency-2026-04 --emergency

Caution

Emergency rotation without cross-signing creates a trust chain break. Events signed after the break cannot be automatically linked to events before. Document the rotation event in your incident log for audit purposes.

Automated rotation

Set a rotation schedule in config.toml:

[compliance.key_rotation]
rotation_interval_days = 180
auto_cross_sign = true
notify_on_rotation = "compliance@yourorg.com"

Key storage recommendations

Environment	Recommendation
Development	File system (keys/ directory)
Staging	HashiCorp Vault or AWS Secrets Manager
Production	HSM (Hardware Security Module) or Vault with HSM backend
Multi-party	FROST threshold shares distributed across key holders