Key Management System (KMS)

The KMS_PROVIDER environment variable can be set to one of AWS or local (coming soon: GCP (Google Cloud Platform), Azure, IBM). 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.

By default, Sombra uses a runtime KMS implementation. Sombra uses key-derivation functions to generate the root KMS secret by deriving it from the entropy in your JWT_ECDSA_KEY.

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 a HashiCorp Vault secret store and to have the value fetched dynamically at runtime, see our documentation here.

You can create a new AWS KMS key for Sombra to use. See the AWS docs for more information on how to create an AWS KMS key. Note: AWS previously referred to this as a "customer master key (CMK)".

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.

Create a KMS key in AWS Console:

  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.