Rotate keys
This guide shows you how to rotate the master key or change where it lives, while the app runs. No event is re-encrypted: the master key only wraps one key per tenant.
Follow this order
Section titled “Follow this order”A running instance wraps new tenant keys with its own key. An instance that lacks that key cannot unwrap them, and stops with DBX029. So every instance must hold both keys before any instance wraps with the new one, and until no row uses the old one:
- Deploy every instance with the old key as the key mode, and the new key for unwrap only.
- Deploy every instance with the new key as the key mode, and the old key for unwrap only.
- Run
deedbox keys rewrap --from <old> --to <new>. Run it again until it reports 0. - Deploy without the old key.
Finish each deploy before you start the next step. Do not re-wrap before step 2 is complete: an instance that still wraps with the old key cannot read rows under the new one.
AlsoUnwrapWith inside Keys(...) adds a key for unwrap only. It takes the same methods as the key mode, such as k => k.StoreInDatabase() or k => k.FromEnvironment("DEEDBOX_NEW_MASTER_KEY"). A key ring needs no AlsoUnwrapWith for its own versions: its first key wraps, and its other keys only unwrap.
Rotate a key ring
Section titled “Rotate a key ring”-
Generate a new 32-byte key:
openssl rand -base64 32. -
Add it after the old key:
v1:<old key>,v2:<new key>. Deploy. Every instance still wraps withv1, and can now unwrapv2. -
Put the new key first:
v2:<new key>,v1:<old key>. Deploy. New tenant keys usev2; existing ones still unwrap withv1. -
Re-wrap the existing tenant keys. Run the command again until it reports 0:
Terminal window deedbox keys rewrap --from env:DEEDBOX_MASTER_KEY --to env:DEEDBOX_MASTER_KEY --provider postgres -
Remove
v1from the ring and deploy again.
// DEEDBOX_MASTER_KEY holds a key ring: v2:<base64 of 32 random bytes>,v1:<older key>services.AddDeedbox(es => es .UsePostgres(connStr) .Keys(keys => keys .FromEnvironment("DEEDBOX_MASTER_KEY") .RedactWith("[erased]")) .Stream<Manuscript>(s => s.Events<ReviewerInvited, CoAuthorAdded>()));Move out of the database
Section titled “Move out of the database”- Set the new key ring in
DEEDBOX_NEW_MASTER_KEY. - Keep
StoreInDatabase()as the key mode, and add.AlsoUnwrapWith(k => k.FromEnvironment("DEEDBOX_NEW_MASTER_KEY")). Deploy. - Change the key mode to
FromEnvironment("DEEDBOX_NEW_MASTER_KEY"), and add.AlsoUnwrapWith(k => k.StoreInDatabase()). Deploy. - Run
deedbox keys rewrap --from database --to env:DEEDBOX_NEW_MASTER_KEY. This also deletes the master key stored in the database. Run it again until it reports 0. - Remove the
AlsoUnwrapWithcall and deploy.
Step 3 looks like this:
// Step 3: the new key wraps. The database key stays for unwrap only, until the re-wrap is done.services.AddDeedbox(es => es .UsePostgres(connStr) .Keys(keys => keys .FromEnvironment("DEEDBOX_NEW_MASTER_KEY") .AlsoUnwrapWith(old => old.StoreInDatabase())) .Stream<Manuscript>(s => s.Events<ReviewerInvited, CoAuthorAdded>()));In database mode, an instance reads the master key for each wrap. It keeps no copy that can outlive a re-wrap.
Use Azure Key Vault
Section titled “Use Azure Key Vault”services.AddDeedbox(es => es .UsePostgres(connStr) .Keys(keys => keys.UseAzureKeyVault( new Uri("https://my-vault.vault.azure.net/keys/deedbox"), new DefaultAzureCredential())) .Stream<Manuscript>(s => s.Events<ReviewerInvited, CoAuthorAdded>()));Follow the same order to move to Key Vault. In step 1, name the Key Vault key in AlsoUnwrapWith, as k => k.UseAzureKeyVault(keyId, credential). In step 3, run deedbox keys rewrap --from <old> --to azure:https://my-vault.vault.azure.net/keys/deedbox. The CLI signs in with DefaultAzureCredential.
Each wrapped key records the Key Vault key version that wrapped it. When the Key Vault key rotates, existing rows still unwrap with their recorded version.
Shred a whole tenant
Section titled “Shred a whole tenant”To erase every personal field of a tenant at once, destroy its key:
await admin.ShredTenantAsync("acme");From the CLI: deedbox tenant shred acme --yes. This cannot be undone.