Migrating to a new key management service is not a key copy: keys generated inside a cloud KMS or HSM are normally designed never to leave it, so a migration is really a programme to re-wrap or re-encrypt every piece of data the old keys protect, and to retire the old keys without destroying anything you still need to read. Organisations move between key management services when they change cloud provider, consolidate accounts after a merger, refresh or exit hardware security modules, move workloads between regions, or bring keys under their own custody for sovereignty reasons. This playbook covers the migration itself: what has to move, the re-encryption patterns and when to use each, the dual-key period, signing keys, the identities that run the migration, and the safe retirement of old keys. It is vendor-neutral and based on NIST SP 800-57, NIST SP 800-38F and the OWASP Key Management Cheat Sheet. Deploying a KMS for the first time is covered in the Cloud key management service (KMS) rollout playbook, and custody choices in the Cloud Customer-Managed Keys and BYOK/HYOK Decision Guide.
Key takeaways
- You move ciphertext, not keys. Plan for every protected object to be re-wrapped or re-encrypted under target keys; treat moving key material itself as the exception that needs a strong reason.
- Re-wrap where envelope encryption allows it. When data is protected by data keys wrapped under a key encryption key, re-wrapping the data keys moves the protection without touching bulk data.
- New writes first, then backfill. Switch every writer to the target key before re-encrypting existing data, or the backlog keeps growing.
- Old keys go decrypt-only, then disabled, then destroyed. Destroying an old key while backups, archives or replicas still depend on it is permanent data loss.
- The migration job can decrypt everything. Its identity needs decrypt on the old keys and encrypt on the new ones; scope it by wave, log it and remove it at the end.
What a KMS migration actually moves
| Object | Migration approach | Watch for |
|---|---|---|
| Symmetric keys generated in the KMS | Create new keys in the target; re-wrap or re-encrypt the data | Key material is normally not exportable; plan on re-encryption |
| Wrapped data keys (envelope encryption) | Unwrap with the old key, wrap with the new key, store alongside the data | Key ID and algorithm recorded with each ciphertext so readers know which key to call |
| Service-side encrypted storage, databases and volumes | Copy or re-encrypt the resource under a target key using the platform's copy or re-key feature | Snapshots, replicas and backups made before the change stay under the old key |
| Asymmetric encryption keys | New key pair; publish the new public key; re-encrypt or let old messages age out | Senders still caching the old public key |
| Signing keys | New key pair; publish both public keys during overlap; switch signers, then verifiers | Signatures that must stay verifiable for years (code, documents, tokens) |
| Imported key material (BYOK) | Re-import from your own copy into the target, if policy and design allow | Same material in two services widens exposure; see below |
| Key policies, grants and role bindings | Translate by intent; separate key administrators from key users | Broad decrypt rights added "temporarily" |
| Aliases and key references in code and configuration | Inventory every reference; switch via configuration, not code edits | Hard-coded key identifiers in applications and infrastructure templates |
| Audit logs of key use | Archive source logs for their retention period | Logs deleted with the old account or HSM |
Re-encryption patterns and when to use each
| Pattern | How it works | Choose it when | Trade-off |
|---|---|---|---|
| Re-wrap data keys | Decrypt each wrapped data key with the old key encryption key and encrypt it with the new one | Data uses envelope encryption with stored wrapped data keys | Fast and cheap; the data keys themselves are unchanged, so it does not help if a data key was exposed |
| Full re-encryption | Decrypt data and encrypt under a new data key protected by the target key | Direct encryption with the KMS key, suspected compromise, or algorithm change | Plaintext passes through the migration compute; cost and time scale with data volume |
| Copy with re-encryption | Copy storage objects, volumes or databases to a destination encrypted with the target key | Data is moving location anyway (new cloud, region or account) | Needs a cutover of consumers to the new location |
| Age out | Write new data under the target key; let old data expire under its retention policy | Short-lived data such as logs, caches and temporary files | Old key must remain available for decryption until the last object expires |
| Re-import key material | Import a wrapped copy of key material you generated and hold outside both services | The design already relies on customer-held material and re-encryption is impractical | Same key in two places during overlap; depends on a secure original copy |
The OWASP Key Management Cheat Sheet says that retiring a key encryption key means re-wrapping the data keys under the new key before destroying the old one, that re-wrapping does not reset the data keys' cryptoperiods, and that replacing a data key requires re-encrypting the data it protects. That is the core decision: re-wrap for a provider or platform move, re-encrypt when the data keys themselves need replacing. The application-side mechanics are in the Envelope Encryption and KMS Integration Patterns Guide.
If key material must move
- Wrap it in transit: OWASP advises wrapping keys with a key encryption key of equal or greater strength before export, using a method that detects tampering. NIST SP 800-38F specifies the AES Key Wrap (KW) and Key Wrap with Padding (KWP) modes for this.
- Handle it only in validated modules (our recommendation): generate and unwrap inside FIPS 140-2 or 140-3 validated hardware, and never let a person see plaintext material.
- Use split knowledge for manual steps (our recommendation): where an import needs people, use multiple custodians. Log each step with the timestamp, operator identity and authorisation reference, as OWASP recommends for manual rotation events.
- Close the overlap: once the target is serving, disable the material in the source on a dated plan.
The dual-key period
NIST SP 800-57 Part 1 describes keys moving through states from active to deactivated, where a deactivated key is no longer used to protect new data but may still be used to process data it protected earlier. A migration uses exactly that model.
- Target key active: all new encryption uses the target key. Every reader can decrypt with either key, chosen by the key identifier stored with the ciphertext.
- Source key decrypt-only: remove encrypt permissions on the source key for every identity, so nothing new is written under it.
- Backfill: re-wrap or re-encrypt existing data in tracked batches. Record per object or per partition which key protects it.
- Verify: sample-decrypt migrated objects with the target key and compare checksums with the originals.
- Disable, do not destroy: disable the source key and watch for decryption failures. Disabling is reversible; destruction is not.
- Destroy on a dated plan: only after the longest dependent retention (backups, archives, legal holds, replicas) has passed or been re-encrypted. OWASP notes that key destruction must include backup, archived and in-memory copies.
Signing keys
Signing keys migrate differently, because the ciphertext you must keep working is a signature held by someone else.
- Publish before you sign: add the new public key to every verifier, trust store or key set first, then switch signers. For token signing keys see the JWKS Signing Key Rotation Guide.
- Keep the old public key for the verification period: code and document signatures may need verifying long after the private key is retired. Retire the private key; keep the public key and its validity record.
- Never escrow signing keys: OWASP advises escrowing encryption keys where needed, but never signing keys; migrate by issuing new signing keys, not by exporting old ones.
Where identity fits
Every KMS call is made by an identity, and most are non-human: storage services, databases, application roles and pipeline jobs. The migration adds one more powerful identity.
- Migration job identity: decrypt on source keys and encrypt on target keys, granted per wave and revoked when the wave completes. Federate it rather than issuing a static credential.
- Separate administration from use: key administrators who can change policies and schedule deletion should not be the identities that decrypt data (NIST SP 800-53 AC-5, separation of duties).
- Rebuild grants from usage: use the source's key usage logs to list which identities decrypt with which keys, and grant only those in the target.
- Remove old access: after cutover, remove every role binding and grant on source keys, then disable them.
The wider key lifecycle is in the Cryptographic Key Management Guide.
The phased playbook
- Inventory: list every key, its purpose, algorithm, policy and protected resources. Use 90 days of key usage logs (our recommendation) to find every caller, including batch jobs. OWASP recommends an inventory of all keys and their uses as part of compromise recovery planning.
- Design the target hierarchy: one key per purpose and data class, separate keys per environment, key administrators separated from key users, deletion protection and a waiting period on scheduled deletion.
- Pilot: migrate one service end to end, including backup restore under the new key and a rehearsed rollback to the old key.
- Switch writers: point every writer at the target key through configuration. Confirm in the logs that the source key receives no new encrypt calls.
- Backfill in waves: lowest-risk data first; highest-value and largest stores last, with throughput limits so jobs do not hit KMS request quotas.
- Handle backups and replicas: decide per store whether to re-encrypt backups or keep the source key decrypt-only until they expire. Write the decision down with the expiry date.
- Disable and wait: disable source keys and watch for failures for at least one full business cycle (our recommendation: 30 days, longer if quarterly or annual jobs exist).
- Destroy and record: schedule destruction, archive the audit logs, record the destruction in the key inventory (NIST SP 800-53 SC-12), and sanitise any HSM, backup media or exported material you retire following NIST SP 800-88 Rev. 2.
Rollback: until source keys are destroyed, rollback means re-enabling the source key and reverting the configuration that points writers at the target. Data already re-encrypted under the target stays readable as long as the target key is retained, so keep both keys usable until the migration is signed off. Small organisations with a handful of keys can often re-encrypt everything in one pass; large estates need the wave model, tracking per object, and quota planning.
Detection and measurement
| Metric or signal | Why it matters | Target (our recommendation) |
|---|---|---|
| Share of protected objects under target keys | Progress of the backfill | 100% before source keys are disabled |
| Encrypt calls on source keys after writer switch | A writer was missed | Zero |
| Decrypt calls on source keys, by caller | Finds remaining readers | Falling to zero before disable |
| Decryption failures after disable | Unmigrated data or consumers | Zero, investigated within one day |
| Key policy or grant changes outside change control | Access widened during migration | Zero unexplained |
| Migration identity use outside approved runs | Misuse of a broad decrypt identity | Zero; alert on any |
OWASP's cheat sheet asks that key access be logged with key identity, user and usage time, and that unusual events be reviewed. Keep these logs from both services in one place for the whole migration.
Common failure patterns
- Destroying the source key too early: backups, cold archives or a disaster recovery replica were still under it, and the data is gone.
- Re-wrapping when re-encryption was needed: data keys that may have been exposed are re-wrapped under a shiny new key and keep protecting the data.
- Backfill without switching writers: new data keeps arriving under the old key, so the migration never ends.
- Broad decrypt grants for the job: a migration role with decrypt on every key and no end date.
- Hard-coded key identifiers: applications and templates referencing source key IDs that fail after disable.
- Quota exhaustion: a bulk re-encryption job hits KMS request limits and causes outages for production callers.
Framework mapping
| Activity | NIST SP 800-53 Rev 5 | NIST CSF 2.0 |
|---|---|---|
| Key generation, states and destruction | SC-12 | PR.DS-01 |
| Re-encryption of data at rest | SC-13, SC-28 | PR.DS-01 |
| Separation of key administrators and key users | AC-5, AC-6 | PR.AA-05 |
| Migration change control | CM-3 | PR.PS-01 |
| Key usage logging and retention | AU-2, AU-11 | DE.CM-09 |
| Backups under old keys | CP-9, CP-10 | PR.DS-01 |
Practitioner checklist
- Inventory keys, purposes, protected resources and callers from usage logs.
- Choose per data store: re-wrap, full re-encryption, copy with re-encryption, age out or re-import.
- Switch all writers to target keys before backfilling existing data.
- Set source keys to decrypt-only, then disabled, and destroy only after dependent retention ends.
- Decide and record how backups, archives and replicas under old keys are handled.
- Scope the migration identity per wave, federate it and alert on use outside runs.
- Separate key administrators from key users in the target.
- For signing keys, publish new public keys first and keep old public keys for verification.
- Wrap any key material in transit with KW or KWP inside validated modules.
- Archive both services' key usage logs for their retention period.
Standards and references
- NIST: SP 800-57 Part 1 Rev. 5, Recommendation for Key Management
- NIST: SP 800-38F, Methods for Key Wrapping
- OWASP: Key Management Cheat Sheet
- AWS: Data protection in AWS Key Management Service (example of non-exportable key material)
- NIST: SP 800-88 Rev. 2, Guidelines for Media Sanitization
- NIST: SP 800-53 Rev 5, Security and Privacy Controls
- NIST: Cybersecurity Framework 2.0
Related NHI Mgmt Group resources: Cloud key management service (KMS) rollout playbook · Envelope Encryption and KMS Integration Patterns Guide · Cryptographic Key Management Guide · BYOK, HYOK and External Key Management Guide