Migrate Local KMS to Cloud KMS

This guide explains how to migrate a self‑hosted Sombra from Local KMS to a cloud KMS. It uses AWS KMS as the concrete example, and is generalizable if other KMS providers are supported in the future.

• No hybrid KMS: Sombra does not support using multiple KMS providers at the same time
• Hard cutover required: a maintenance window is needed to switch providers
• Encryption context mismatch: CEKs produced under Local KMS cannot be decrypted under a cloud KMS and vice‑versa

In‑flight requests created under Local KMS will not be decryptable after you switch to a cloud KMS. Complete or cancel them before migration, or plan to restart them after cutover. See Pause Processing and Cancelling a Request.

• In‑progress DSRs started under Local KMS cannot proceed after cutover
• Files attached to requests that were encrypted under Local KMS will not be decryptable post‑cutover
• Focus on draining or pausing in‑flight requests before the cutover

1. Cloud KMS setup (AWS example)
   • Create a KMS key in your cloud provider
   • Grant Sombra permissions to use the key (for AWS, via IAM policy)
   • Obtain the key identifier (for AWS, the KMS key ARN)
2. Key management
   • Generate a new JWT_ECDSA_KEY for signing
   • Keep the old JWT_ECDSA_KEY alongside the new key (comma‑separated, new first). See Migrating from Transcend‑Hosted Sombra.
   • Store keys in your external secrets manager (e.g., External Secrets Operator, Vault). See Secrets Management.
3. Request status
   • Prefer to complete/cancel all in‑progress requests
   • Alternatively, pause DSR processing during the cutover and be prepared to restart previously in‑flight requests

Plan a 1–2 hour maintenance window. During this window:

• Sombra is stopped
• Environment variables are switched to the cloud KMS
• Sombra is restarted and validated

• Understand access before/after: Prior to migration, files from completed requests encrypted under Local KMS can be downloaded by data subjects (and via API/CLI). After migration, those files will no longer be decryptable.
• Optionally download completed requests for record‑keeping:
  • API reference: Download keys for request files and Download individual files
  • CLI: Transcend request download-files
  • Admin Dashboard: Incoming Requests
• Set up the cloud KMS key and access permissions
• Generate a new JWT_ECDSA_KEY and prepare both new and old keys for deployment
• Complete/cancel in‑progress requests, or plan to pause processing

1. Stop Sombra
2. Update environment variables (AWS example):

KMS_PROVIDER=AWS
AWS_KMS_KEY_ARN=<your-kms-key-arn>
AWS_REGION=<your-region>
JWT_ECDSA_KEY=<new-key>,<old-key>  # comma-separated, new first

1. Start Sombra
2. Verify the service starts and health checks pass

• All new DSR requests use the cloud KMS
• Old requests remain visible in the admin UI, but associated files encrypted under Local KMS will not be decryptable
• Monitor logs and error rates; address any configuration or permission issues

If issues occur during the window:

1. Stop Sombra
2. Revert KMS_PROVIDER=local
3. Start Sombra

Requests created under the cloud KMS after cutover cannot be decrypted under Local KMS if you roll back.

• Can we run two KMS providers at once?
  • No. Hybrid operation is not supported; perform a hard cutover.
• What happens to historical downloads?
  • Files encrypted under Local KMS will not be decryptable after cutover; download what you need beforehand.
• Where should JWT_ECDSA_KEY be stored?
  • In external secrets management. Cloud KMS does not hold or sign with this key.
• How do we rotate keys post‑migration?
  • See the key rotation guide linked below.

• Key Management
• Secrets Management
• Rotating Sombra Keys