Skip to main content
Rotating the wrapping key replaces the key that protects the master key. The master key itself never changes and is never exposed, so no stored data is re-encrypted — rotation takes the same amount of time on a vault of 1,000 records as on one of 100 million.

​
When to rotate

  • On a schedule — every 90 days or annually is typical, and several frameworks expect a defined interval.
  • When someone who had access to the wrapping key leaves, or the key may have been exposed.
  • As part of a compliance exercise, where you need to evidence that rotation works rather than that it is merely possible.
Rotate on a schedule you have actually rehearsed. The procedure below touches the credential your vault needs in order to boot, so the first time you run it should not be during an incident.

​
Before you start

  • Three of your five Shamir key shares, hex-encoded, as issued at setup.
  • The root access token of the main tenant. Only the main-tenant administrator can rotate the wrapping key.
  • A running, healthy instance. Rotation is performed against a live vault — see What is recoverable if yours is already down.
  • Write access to wherever the wrapping key is configured: your secret manager and your deployment config.
  • A maintenance window. The vault keeps serving traffic during the API call, but it has to be restarted afterwards.

​
Rotate the key

1

Call SystemGenerateWrappingKey

Send any three of the five shares. They are hex-encoded, and the API rejects anything else.
Databunker Pro reconstructs the recovery key from the shares, uses it to recover the master key, and confirms the result matches the master key the running instance already holds. Only then does it mint a new wrapping key and re-wrap the master key with it.
The new wrapping key is returned once, in the response body, and is not stored anywhere you can read it back. If you lose it before completing the next step, the vault will not restart. Do not run this call in a way that leaves the response in shell history, CI logs, or terminal scrollback.
2

Store the new key before restarting

Write wrappingkey to both places it needs to exist:
  • Your secret manager — AWS Secrets Manager, HashiCorp Vault, Google Secret Manager, or equivalent.
  • The deployment configuration the container reads at boot: DATABUNKER_WRAPPINGKEY, DATABUNKER_WRAPPINGKEY_FILE, or the -wrappingkey argument. With Docker Compose this is the .env file; on Kubernetes it is the secret mounted into the pod.
Keep the previous value until the restart has succeeded. Updating one location and not the other is the most common way this procedure goes wrong.
3

Restart Databunker Pro

The running process continues with the key it already holds in memory; the new key only takes effect on restart.
On Kubernetes, roll the deployment after updating the secret.
4

Verify

Confirm the service is up:
Then read back a known record with UserGet. A successful decryption proves the new wrapping key resolves to the same master key. Once verified, discard the old wrapping key.
Your five Shamir shares remain valid after rotation and do not need to be reissued or redistributed. They protect a separate recovery wrapping of the master key, which rotation does not modify — see Two independent wrappings.

​
Errors

​
What is recoverable

Three shares is a hard floor. Below it, a lost wrapping key means permanent loss of every record in the vault. This is a property of the design, not a support limitation: Databunker Pro holds no copy of your keys and no escrow, which is precisely why a breach of our systems cannot expose your data. Audit the location and availability of all five shares on a schedule, and verify you can still reach three of them.
A wrapping key lost while the vault is still running is routine to recover; the same loss discovered after it has stopped is not. If you find the key is missing, rotate before anything triggers a restart.