# Key Management System (KMS) (/docs/sombra/deploying/customizing-sombra/key-management)

The `KMS_PROVIDER` environment variable can be set to one of `AWS` or `local`. If you want to use your own Key Management System (KMS), you can set this value to the hosting provider you're using and Sombra will integrate with your KMS for key management. Otherwise, Sombra will use its own internal KMS (`local`). Defaults to `local`.

## KMS use cases [#kms-use-cases]

#### What it does [#what-it-does]

- Generates and manages content encryption keys (CEKs) for DSR file encryption
- Encrypts/decrypts content encryption keys used by Sombra

#### What it doesn't do [#what-it-doesnt-do]

- Store or manage your `JWT_ECDSA_KEY`
- Sign Sombra payloads (webhooks still use `JWT_ECDSA_KEY`)
- Automatically migrate or re-encrypt historical data

### Local KMS [#local-kms]

By default, Sombra uses a runtime KMS implementation. When using local KMS, `JWT_ECDSA_KEY` serves two purposes:

- Signing Sombra payloads (like webhooks)
- Input keying material for deriving content encryption keys

When `KMS_PROVIDER=local` (the default), the following environment variables are required:

`JWT_ECDSA_KEY`: The JSON Web Token asymmetric key(s) for signing Sombra payloads. This should be a comma-separated list of keys, where the first entry is the current key. Each entry is a PEM-formatted private key, which is then base64-encoded. It should start with `LS0tLS1CRUdJT`.

If you want to set the key-value via an external secret store, see [our secrets management guide](./secrets-management.mdx).

### AWS Key Management Service (KMS) [#aws-key-management-service-kms]

You can create a new AWS KMS key for Sombra to use. See the [AWS docs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html) for more information on how to create an AWS KMS key. _Note: AWS previously referred to this as a "customer master key (CMK)"_.

#### How AWS KMS Integration Works [#how-aws-kms-integration-works]

Sombra can use AWS KMS for:

- Generating content encryption keys
- Encrypting and decrypting content (e.g., files uploaded in DSARs)

Note that the `JWT_ECDSA_KEY` is still required even when using AWS KMS, as it is used for signing Sombra payloads (like webhooks). AWS KMS is not used for storing sensitive configuration values like the `JWT_ECDSA_KEY`. For secure storage of these values, we recommend using the [External Secrets Operator](./secrets-management.mdx).

When `KMS_PROVIDER=AWS`, the following environment variables are required:

- `AWS_KMS_KEY_ARN`: The Amazon Resource Name (ARN) for the AWS KMS. The ARN starts with `arn:aws:kms:`.
- `AWS_REGION`: The AWS Region where the AWS KMS is hosted. For example, "us-east-1".

The following environment variables are optional:

- `AWS_KMS_THROW_PERMISSIONS_ERRORS`: (optional) Boolean flag to throw errors related to a lack of permissions when using the AWS KMS provider (defaults to `false`).
- `AWS_KMS_CUSTOM_KEY_STORE_ID`: (optional) The ID of a Custom AWS CloudHSM key store to use. The ID starts with `cks-`. External key store IDs are not valid for this parameter. For more information, see [AWS CloudHSM key stores](https://docs.aws.amazon.com/kms/latest/developerguide/keystore-cloudhsm.html).

#### Amazon KMS Setup: [#amazon-kms-setup]

Create a KMS key in [AWS Console](https://console.aws.amazon.com/kms/home):

1. Click Create key.
2. Give it an alias, such as "sombra-key", and a description such as "Used by Transcend's Sombra gateway to perform encryption on user data download requests".
3. Click through to "Define key usage permissions" and select the new user you just created.
4. Click through and click "Finish".
5. Open your new key and copy the ARN into the `AWS_KMS_KEY_ARN` environment variable.

This completes the basic setup for key management in Sombra.

### Migration from Local KMS to a Cloud KMS [#migration-from-local-kms-to-a-cloud-kms]

Changing KMS providers after you have begun processing requests is not officially supported as a hybrid or gradual migration—Sombra cannot use multiple KMS providers at the same time. We highly recommend deciding on your KMS provider before processing live data subject requests.

If you must change providers post‑implementation, you will need a hard cutover during a maintenance window and should plan for implications to in‑flight and historical requests. For a step‑by‑step overview, see: [Migrate from Local KMS to Cloud KMS (AWS example)](./migrating-local-to-cloud-kms.mdx)