Key rotation 

Rotating the master key re-wraps every DEK under a new key. Secret values are never re-encrypted and never materialise as plaintext — only the DEK layer changes (Envelope scheme), which is what makes the operation affordable at all.

It is also the most powerful operation in the extension: it rewrites every envelope and rekeys the audit chain in one transaction. It carries its own permission, master_key.rotate.

When to rotate 

  • After any suspected exposure of the key material, or of a host that could read it.
  • After personnel with filesystem or KMS access leave.
  • On a schedule — annually is a common policy.
  • When moving between providers, for example off typo3 as part of Migrating from standard to hardened.

Rotating the master key is not the same as rotating a secret. If a single credential leaked, rotate that credential and use vault:rotate; a master key rotation changes nothing about a leaked credential value.

The command 

vendor/bin/typo3 vault:rotate-master-key \
    --old-key=/path/to/old.key \
    --new-key=/path/to/new.key \
    [--dry-run] [--confirm]
Copied!
Option Meaning
--old-key Path to a file containing the old master key. Omitted: the currently configured provider's key is used.
--new-key Path to a file containing the new master key. Omitted: the currently configured provider's key is used — which, with --old-key also omitted, means both are identical and the command refuses.
--dry-run Inventory, confirmation and the old-key smoke test run; the re-encryption does not. No changes are made.
--confirm Required for an actual run. Without it (and without --dry-run) the command aborts rather than asking.

Both keys are read from files, not from the command line, so they do not land in shell history or a process listing. Both copies are wiped with sodium_memzero() when the command returns.

Preflight 

The command performs these checks itself, in this order, and each one aborts:

  1. Permission. master_key.rotate must be granted. On CLI without a backend user that means allowCliAccess = 1 and master_key.rotate listed in cliAllowedOperations, which excludes it by default; as a backend user it means the admin override or an explicit group grant.
  2. Keys must differ. Compared with hash_equals() . Identical keys are refused as "Nothing to rotate."
  3. Inventory. Vault secrets are counted, and so are consumer-owned foreign envelopes registered by other extensions (ADR-033: Master-key rotation reaches consumer-owned envelopes) — a vault with no secrets of its own may still be the key authority for thousands of them. The audit history is counted as well: rows sealed under a master-key-derived HMAC key (epoch 1 and up) and the chain-tip anchor. A vault whose secrets have all been deleted still holds that history, and it has to move to the new key like everything else. Only when secrets, foreign envelopes, keyed audit rows and anchor are all absent does the command stop with a warning.
  4. Confirmation. --confirm for a real run.
  5. Old-key smoke test. One real secret is re-encrypted to prove the supplied old key is actually the one that wrapped the envelopes. This is the check that turns "wrong key" from a half-rotated vault into a clean abort.

Your own preflight, before running any of it:

  • [ ] A verified backup of the database and of the current key material.
    If the rotation fails in a way the transaction cannot undo, this is the only way back. See Backup and restore.
  • [ ] The old key as a file, kept until the repair after the switch
    reports nothing left (how to keep it). Without it, nothing written in the gap can be repaired.
  • [ ] **The new key exists, is 32 bytes, and is stored where the provider
    will read it after the switch.**
  • [ ] The audit chain verifies now. Rotating over an already-broken

    chain destroys your ability to tell the two problems apart:

    # Asserts audit.view; on the CLI that needs allowCliAccess = 1 AND
    # audit.view in cliAllowedOperations, or a named technical actor.
    vendor/bin/typo3 vault:audit-verify
    Copied!
  • [ ] Nothing writes secrets or consumer envelopes from the start of the
    rotation until the configuration switch and the restarts after it. Stop the writers and let requests already in flight finish before you start the command; a request that loaded the old key can otherwise store its result after the switch. Concretely: no backend edits, no VaultService::store() or rotate() from scheduler tasks, API endpoints or imports, no outbound OAuth calls whose token endpoint rotates the refresh token (the vault stores the new one as a secret), and no envelope writes by extensions that register a ForeignEnvelopeRotatorInterface (for example nr-llm). Until the switch the configured provider still returns the old key, so anything written in that gap is wrapped under the old key, cannot be opened after the switch, and is lost once the old key is destroyed. See The configuration switch — and the window.
  • [ ] A maintenance window. Vault reads fail between the commit and the
    configuration switch. During the rotation itself, a secret that has already been re-encrypted cannot be read: the read waits until the rotation commits, or until the database's lock wait timeout, because a read updates the secret's row. On MySQL/MariaDB and PostgreSQL, from the audit-chain re-key until the commit, every operation that writes an audit entry waits for the audit-chain lock and fails after 5 seconds; with audited reads enabled (the default), that includes all secret reads. On SQLite the rotation holds the database write lock from the first re-encrypted secret, so other writers wait for their busy timeout during the whole rotation.
  • [ ] **On MySQL/MariaDB with binary logging, binlog_format is ROW or
    MIXED** (the defaults). The rotation runs in READ COMMITTED, where InnoDB refuses writes under STATEMENT logging, so the real run refuses before its transaction, after writing its start row. The dry run does not check this; check it yourself with SELECT @@log_bin, @@binlog_format;.
  • [ ] ``vault:doctor`` is clean, so a pre-existing misconfiguration does
    not surface mid-rotation.

Dry run 

Always run this first:

vendor/bin/typo3 vault:rotate-master-key \
    --old-key=/path/to/old.key --new-key=/path/to/new.key --dry-run
Copied!

The dry run is genuinely useful rather than cosmetic, because the old-key smoke test happens before the short-circuit: a dry run that succeeds has proved that the old key opens a real envelope. It reports the number of secrets and foreign envelopes that would be re-wrapped and the number of audit rows that would be re-keyed, and makes no changes.

A dry run that fails the smoke test means the old key is wrong. Fix that before going further; do not proceed with --confirm hoping the real run behaves differently.

What the real run does 

A master_key_rotate_start audit row is written under the pseudo identifier __master_key__ before audit-chain verification and before the rotation transaction starts. It remains as evidence of the attempt if verification fails or the rotation later rolls back. A failure row is also written outside the rolled-back transaction.

After verification succeeds, the following changes happen inside one database transaction. A failure rolls back secret and foreign-envelope changes, the chain rewrite, and the success audit rows together. On MySQL/MariaDB and PostgreSQL the transaction runs in READ COMMITTED, so the re-key reads every audit entry committed before it took the lock, also where the server default is REPEATABLE READ.

  1. Every secret's DEK is unwrapped with the old key and re-wrapped with the new one, with a fresh nonce. Values, value nonces and the version/algorithm markers are untouched.
  2. Registered foreign envelopes are re-wrapped the same way.
  3. The audit advisory lock is taken and held until the transaction has committed or rolled back, so no concurrent writer can chain onto a tip hash that is about to be rewritten. On MySQL/MariaDB and PostgreSQL the rotation rolls back if the lock is not granted within 5 seconds.
  4. The audit_chain_rekey and successful master_key_rotate_end rows are appended — still sealed with the old, provider-derived HMAC key.
  5. The whole audit chain is rewritten under the HMAC key derived from the new master key, including the two rows just appended, so the committed chain verifies under the new key from first row to last with no old-keyed tail.
  6. Commit, then MasterKeyRotatedEvent is dispatched.

Two properties of the rekey worth knowing:

  • Per-row epochs are preserved. Re-keying changes the key, never the payload format. An epoch-2 row stays epoch 2.
  • An all-epoch-0 chain passes through untouched. Keyless SHA-256 hashes do not depend on the master key, so rows are only updated when their hashes actually change.

If the commit itself fails 

Every other failure rolls back. A commit that fails, for example on a lost database connection, may already have been applied by the server, so the command reports that the outcome is unknown and asks you to keep both master keys. Find out which key now opens the secrets before you change anything:

vendor/bin/typo3 vault:rotate-master-key \
    --old-key=/path/to/new.key --new-key=/path/to/old.key --dry-run
Copied!

The dry run only checks that --old-key opens the first secret and writes nothing. If it succeeds with the new key in --old-key, the rotation committed: continue with the configuration switch below. The failed master_key_rotate_end row the command wrote afterwards is sealed under the old key, like any row written before the switch, and step four below re-seals it. If it fails, run the same check with the old key in --old-key; success there means the rotation rolled back and nothing changed. The check needs at least one secret in the vault.

The configuration switch — and the window 

On success the command prints its next steps, and they are not advisory:

  1. Update the configuration to use the new master key immediately. Until then, secrets cannot be decrypted and audit-chain verification runs against the old key. Depending on the provider: replace the key file (file), re-inject the environment variable and restart (env), or re-wrap the new key with the KMS (transit). Then restart every long-running process that uses the vault — queue workers, daemons, long-running CLI commands: a provider keeps the key it loaded for the lifetime of the process, so such a process would keep writing under the old key.
  2. Securely archive or destroy the old key — but only after the checks below. Archive it if you may still need to open an older backup; destroy it if you may not. Do not leave it where the vault could pick it up again. Anything written in the gap is still under the old key, so keep the old key until the repair in step four reports nothing left under it.
  3. Test retrieval and verify the chain — see below. A chain that fails only on rows written after the rotation, or a secret that cannot be read, means something was written in the gap: do step four, then verify again. Until then the scheduled vault:audit-verify task reports HASH_MISMATCH for those rows.
  4. Repair what was written in the gap. Audit rows written between the rotation commit and the configuration switch are sealed with the old HMAC key while the rest of the chain is under the new one, so the chain no longer verifies. Secrets stored in that time are wrapped under the old key. vault:rotation-gap-repair re-seals those rows and re-wraps those secrets with the old key — see below. vault:audit-migrate-hmac cannot do it: it re-seals only rows below the configured epoch, and it refuses a chain that does not verify.

Steps three and four are the reason to keep the window short and to make it a maintenance window: every audited operation during the gap adds a row that needs re-sealing, and every write during the gap is wrapped under the old key.

If something was written in the gap. After the configuration switch and the restarts, run the repair with the old key, first as a dry run:

vendor/bin/typo3 vault:rotation-gap-repair \
    --old-key=/path/to/old.key --dry-run
Copied!

It opens every secret, disabled ones included, and lists those whose DEK opens only under the old key and those that neither key opens. It lists the audit rows after the end of the rotation that verify only under the old key. Run it again with --confirm instead of --dry-run to re-wrap those secrets and re-seal those rows under the new key, in one transaction under the audit-chain lock; each re-wrapped secret gets a master_key_rewrap audit row. Secret values do not change.

The repair refuses when the chain has any other finding: a row that verifies under neither key, a missing row, a broken link, an old-key row before the end of the last rotation or after a successful repair, or a tip-anchor error. Re-sealing would hide such a finding. A refused run changes no secret and no existing row; without --dry-run it appends a failed audit_chain_rekey row. Keep both keys and investigate with vault:audit-verify.

The repair trusts the old key. Anyone who holds it and can write to the database can add an audit row or a secret the repair accepts. A successful repair closes the window for audit rows: an old-key row after its audit_chain_rekey row is refused, and no command re-seals it. Such a row means a process still wrote with the old key after the repair, or someone who holds the old key wrote it; treat it as an incident (Suspected audit tampering), keep both keys, and make sure every process was restarted before you run the repair. It does not close it for secrets — the repair re-wraps every secret the old key opens, whenever it was written — so check the listed secrets in the dry run. Keep the old key under the same protection as the current one until the repair is done, then archive or destroy it.

The old key as a file. The repair reads the old key from a file, raw 32 bytes or base64, like --old-key of the rotation. Make that file before the configuration switch, readable only by the user who runs the command, and keep it as protected as the key itself. The switch replaces the configured key, so the configured path does not hold the old key afterwards; the backup from the preflight list still does.

  • file: a copy of the old key file, made before you replace it.
  • env: the old value of the variable, raw or base64.
  • typo3: the key is derived from $GLOBALS['TYPO3_CONF_VARS']['SYS']['encryptionKey'] and never stored. Derive it while you still have the old encryptionKey; the command reads it from standard input, so it stays out of the process list, and drops one trailing line break:

    (umask 077; php -r 'echo base64_encode(hash_hkdf("sha256",
        preg_replace("/\n\z/", "", stream_get_contents(STDIN)), 32, "nr-vault-master-key")), PHP_EOL;' \
        > /secure/path/old.key)
    Copied!
  • transit: a copy of the old wrapped key blob, made before the new key replaces it at wrappedKeyPath. Transit decrypt of that blob returns the key base64-encoded in data.plaintext:

    (umask 077; vault write -field=plaintext <mount>/decrypt/<key> \
        ciphertext=@/secure/path/old-wrapped.key > /secure/path/old.key)
    Copied!

Consumer envelopes are not covered: the vault does not know where a consumer stores them, and they are sealed without a vault audit entry. They are the consumer's to re-create, and unless each consumer can show that it wrote nothing between the start of the rotation and the end of the restarts, archive the old key instead of destroying it. Keep the old key until all of this is done.

Verification 

# 1. The provider resolves and the configuration is coherent.
vendor/bin/typo3 vault:doctor --format=json

# 2. Plaintext comes back — the real proof. On the CLI this needs
#    allowCliAccess = 1 AND secret.reveal in cliAllowedOperations;
#    a reveal in the backend module proves the same decrypt path.
vendor/bin/typo3 vault:retrieve <a-known-identifier>

# 3. The chain verifies under the new key, end to end. Needs audit.view:
#    on the CLI that is allowCliAccess = 1 AND audit.view in
#    cliAllowedOperations, or a named technical actor.
vendor/bin/typo3 vault:audit-verify

# 4. Anchor the new tip; the old anchor's baseline is now stale. Needs
#    vault.configure, on the same terms as step 5 below.
vendor/bin/typo3 vault:audit-anchor

# 5. The in-database anchor is re-sealed by the rotation itself. Confirm
#    it reads "Tip anchor: ok" — a re-key that left it UNREADABLE means
#    the re-seal did not complete, and that is a finding, not a nuisance.
#    Needs vault.configure: on the CLI that is allowCliAccess = 1 AND
#    vault.configure in cliAllowedOperations, or a named technical actor.
vendor/bin/typo3 vault:audit --verify
Copied!

Probe at least two secrets, and pick them from different encryption versions if the installation has both — see Restore verification: the probe decrypt for why.

If it fails 

  • Aborted during preflight — nothing changed. Fix and retry.
  • Rolled back — the transaction reverted secrets, the appended events and the chain rewrite together. A master_key_rotate_end row with success = 0 and the reason "Unexpected error during rotation; transaction rolled back" records the attempt. The old key is still the right one; do not switch the configuration.
  • Committed but the configuration was never switched — secrets stay undecryptable and verification uses the wrong key. Complete the switch; this is a half-finished rotation, not a failed one.
  • Committed, configuration switched, and reads still fail — the key you installed is not the --new-key you rotated to. Install the correct one. Do not rotate again to "fix" it: a second rotation from the wrong old key will fail its smoke test, which is the safety net working.

Transit key rotation is a different operation 

With the transit provider there are two independent rotations, and confusing them is a common mistake.

Operation Effect
vault:rotate-master-key Changes the nr-vault master key: every DEK is re-wrapped and the audit chain is rekeyed. Installing the new key afterwards means wrapping it with Vault and replacing the local blob — the command does not do that for you. This is what the rest of this page describes.
vault write -f transit/keys/<name>/rotate Rotates the Vault transit key. New ciphertexts are wrapped under the new transit key version; existing ciphertexts stay decryptable under their recorded version. The nr-vault master key does not change, so no DEK is re-wrapped, the audit chain is untouched, and no secret is affected.

So: rotating the transit key is a KMS hygiene operation with no vault downtime and no re-encryption. Rotating the master key is the operation that touches every envelope. Do the first freely; schedule the second.

To re-wrap the existing master key under the newest transit key version without changing the master key itself, use Vault's rewrap endpoint on the stored ciphertext and replace the local blob — again with no effect on any secret. Keep the file mode at 0600 and write it atomically, as the provider itself does.