Skip to content
Deedboxlatest

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.

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:

  1. Deploy every instance with the old key as the key mode, and the new key for unwrap only.
  2. Deploy every instance with the new key as the key mode, and the old key for unwrap only.
  3. Run deedbox keys rewrap --from <old> --to <new>. Run it again until it reports 0.
  4. 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.

  1. Generate a new 32-byte key: openssl rand -base64 32.

  2. Add it after the old key: v1:<old key>,v2:<new key>. Deploy. Every instance still wraps with v1, and can now unwrap v2.

  3. Put the new key first: v2:<new key>,v1:<old key>. Deploy. New tenant keys use v2; existing ones still unwrap with v1.

  4. 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
  5. Remove v1 from 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>()));
  1. Set the new key ring in DEEDBOX_NEW_MASTER_KEY.
  2. Keep StoreInDatabase() as the key mode, and add .AlsoUnwrapWith(k => k.FromEnvironment("DEEDBOX_NEW_MASTER_KEY")). Deploy.
  3. Change the key mode to FromEnvironment("DEEDBOX_NEW_MASTER_KEY"), and add .AlsoUnwrapWith(k => k.StoreInDatabase()). Deploy.
  4. 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.
  5. Remove the AlsoUnwrapWith call 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.

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.

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.