zitadel-masterkey-rotator

Offline ZITADEL masterkey rotation helper for PostgreSQL.

This tool only rewraps system.encryption_keys."key". It does not modify eventstore, eventstore.events2, or projection business data.

Safety

Before using this tool:

• Stop all ZITADEL instances.
• Create and verify a pg_dump.
• Test the full procedure on a test database before production.

Build

go build -o zitadel-masterkey-rotator .

Validate Only

Without --execute, the tool only validates that every encryption key can be decrypted with the old masterkey and re-encrypted with the new masterkey.

./zitadel-masterkey-rotator \
  --database-url "$DATABASE_URL" \
  --old-masterkey-file ./old.key \
  --new-masterkey-file ./new.key \
  --backup-sql ./encryption_keys_before.sql

Execute

--execute writes the rewrapped keys back to system.encryption_keys.

./zitadel-masterkey-rotator \
  --database-url "$DATABASE_URL" \
  --old-masterkey-file ./old.key \
  --new-masterkey-file ./new.key \
  --backup-sql ./encryption_keys_before.sql \
  --execute

Rollback

If --backup-sql was used, restore the original encrypted keys with:

psql "$DATABASE_URL" -f ./encryption_keys_before.sql

If no backup SQL was created, restore from your database backup.