Migrate Between Key Backends
This page describes the intended design recorded in ADR#0023 (accepted) and ADR#0030 and ADR#0033 (both draft). None of it is implemented yet. It is the model the implementation must satisfy, not current behavior.
When to use this
Use this procedure to move a tenant's existing envelopes from one bound key to another. This is a custody change, not an incident response. Typical reasons to migrate: a tenant adopts a customer managed key after starting on the managed key tier, a tenant moves between two customer managed backends, a tenant leaves a customer managed key and returns to the managed tier or the dedicated key tier, or a tenant moves to a replica of a multi-Region AWS key. Migration works in either direction between tiers (ADR#0033 Decision 4).
A replica of a multi-Region AWS key has its own key state and key policy, and the platform never fails over to it. Moving to a replica is always an explicit migration: bind the replica's own key ARN as a new KeyRef and follow this procedure (ADR#0030 Decision 4).
Do not use this procedure if you suspect the old key-encryption key (KEK) is compromised. Rewrapping under a new key does not change who already had access to the plaintext Dek the old key protected, so a suspected compromise requires new Dek values and re-encryption of the payload, not a rewrap of the existing ciphertext (per ADR#0030 Decision 4). See Handle Unusable Keys for that procedure instead.
Preconditions
Before you start a migration, confirm all of the following:
- Both the old backend and the new backend must be available for the entire migration. There is no partial-availability path: if either backend cannot serve
wrap_dekorunwrap_dekrequests, the migration cannot proceed. - Neither the old backend registration nor the new one is paused. A paused registration denies migration source use and migration target use with
KeyUseDeniedand the denial reasonBackendPaused, and the platform makes no provider call for it. If a registration is paused partway through, the migration cannot continue until its owner resumes it, and resume validates the registration's current configuration end to end (per ADR#0030 Decision 6). - The new key does not need to be bound ahead of time through a separate procedure. When the new key is a customer managed key, binding it through
BindExternalKeyis the first step of the migration flow described below, and it must complete before any envelope'sDekis rewrapped under the newKeyRef(per ADR#0030 Decision 4). When the new key is a managed or dedicated key, the platform operates it, so you do not bind it yourself: the platform supplies the tenant'sKeyReffor that tier. - If a customer disables the old key before migration completes, they have chosen unavailability over recoverability. The platform cannot unwrap the envelopes still referencing a disabled old key, and it cannot recover them by any other means.
- The source key must still allow unwrap (active or decrypt-only), and the target key must allow wrap (active). See Key States for the full state and operation matrix.
How migration works
Migration follows the rewrap flow that ADR#0030 Decision 4 defines. The console and API request shapes that trigger it are an open decision that ADR#0033 leaves for later work; what follows is the operation sequence the implementation must satisfy, not a concrete request format:
- Bind the new key, producing a new
KeyRef. For a managed or dedicated target, the platform supplies the tenant'sKeyReffor that tier instead. This step must complete before any envelope migrates. - Cut over new writes before rewrapping anything: set the new
KeyRefas the default wrapping key for every purpose whose default is currently the oldKeyRef. Defaults are resolved server-side on wrap (per ADR#0030 Decision 3), so after this step no new envelope can be wrapped under the oldKeyRef, and the set of envelopes to migrate stops growing. A wrap already in flight when the default changes may still commit under the oldKeyRef; such operations are bounded by their operation deadline, and the completion check below catches anything they commit. - For each envelope, unwrap its
Dekwith the oldKeyRef, then wrap that sameDekwith the newKeyRef, producing a newWrappedDek. - Commit the new
KeyRefand the newWrappedDektogether, as one transactional or compare-and-set mutation against the envelope's expected version. That mutation records a stable migration operation ID. - If the mutation conflicts, nothing partial is committed and the currently committed pair remains authoritative. A retry rereads the envelope: it recognizes its own operation ID as already committed when applicable, and otherwise recomputes only if no different migration has superseded it.
- A mismatched
KeyRefandWrappedDekpair, one that does not name the key that actually produced it, is never visible to any reader.
Rules
- There is no configuration-only cutover between backends, and no fallback from one backend to another. Every backend change goes through this explicit rewrap.
- Setting the default wrapping key for new envelopes and migrating existing envelopes are separate actions. Changing a tenant's default affects only envelopes created after the change; it does not migrate anything already written. In a migration they compose in a fixed order: the default cutover comes first, so the set of envelopes referencing the old
KeyRefstops growing before the rewrap and the final reference scan. - The old
KeyRefstays immutable: its binding to a backend and provider locator never changes in place. It is retired only after no purpose still selects it as a default wrapping key and no envelope references it any longer.
Verifying completion
- Confirm that no purpose still selects the old
KeyRefas its default wrapping key. The cutover in the migration flow makes this true before any envelope is rewrapped; this check guards against a default added concurrently. - Run the reference scan only after wrap operations that could have resolved the old default before the cutover have drained, which their operation deadline bounds. Then confirm that no envelope still references the old
KeyRef. - Retire the old
KeyRefonly after both checks pass. - Expect the audit record for each migrated envelope to carry the tenant, the
KeyRef, theKeyBackendId, the purpose, the provider, the outcome, and a correlation ID (per ADR#0030 Decision 7). The record also lists each provider attempt with the request identifier the provider returned, or an explicit absence reason,NotProvidedByProviderorNoResponse. This page does not claim that a recorded identifier matches an entry in the provider's own audit log.
