Last updated May 12, 2022

This article describes how to use AWS Key Management Service (KMS) to create a Customer Master Key (CMK) to encrypt Heroku Redis in Private Spaces. This process involves three high-level steps:

1. Create an Customer Master Key (CMK) in your AWS KMS
2. Apply an IAM policy to that CMK to permit Heroku Data to use the key on your behalf
3. Create a Heroku Redis database with the encryption key

AWS Prerequisites

You perform the steps in this section from your Amazon KMS dashboard. Alternatively, you can use the AWS CLI as shown below.

Step 1: Create a Customer Master Key

Once logged into the AWS web console, navigate to Key Management Service and click Create Key.

Step 2: Select Symmetric Key

Select Symmetric Key and click Next.

We use S3 to store backups and it only supports symmetric CMKs.

Step 3: Add Details and Set Permissions

Add an alias (eg: heroku-data) and press Next. There is no requirement to further configure key administrative permissions. Click Next.

When defining key usage permissions, scroll to the bottom to Add another AWS account. Enter the Heroku Data AWS Account ID (021876802972) in the box and press Next.

Step 4: Review and Complete

Review the key policy and complete creation. Note the Amazon Resource Name (ARN) of your CMK.

Step 5: Enable Automatic Key Rotation

You can enable automatic key rotation by opening the info page for your key. At the bottom of the page, select the Key Rotation tab, check the box, and press Save.

Alternative: Use the AWS CLI

You can use the AWS CLI to create your Customer Master Key (CMK) with the appropriate key policy.

$ export AWS_ACCOUNT_ID=`aws sts get-caller-identity --output text --query 'Account'`
$ export HEROKU_DATA_ACCOUNT_ID=021876802972
$ curl -s -o key-policy.json https://gist.githubusercontent.com/jdowning/8d146cd238de828141e81b458dc546f0/raw/fc2a69603dc1364f1bc2fd2b5beb0af210150444/key-policy.json
$ aws kms create-key --description 'heroku-data-test' --policy $(envsubst < key-policy.json)

The output of the create-key command will include the key’s ARN which you will need during provisioning. This will be referred to has CMK_ARN in later steps.

We recommend you enable automatic key rotation on your CMK:

$ aws enable-key-rotation --key-id CMK_ARN

Create a Heroku Redis database with an encryption key

Now that you have a Customer Master Key with the appropriate permissions configured, you can use that key to encrypt your data managed by Heroku Data. You will need the full Amazon Resource Name (ARN) of your CMK. You can use the --encryption-key provisioning flag when creating your database.

$ heroku addons:create heroku-redis:private-7 --encryption-key CMK_ARN --app your-app-name

Migrate a Heroku Redis Database to One Using an Encryption Key

If you have an existing Heroku Redis database, you can create a fork database using your encryption key to migrate your data.

$ heroku addons:create heroku-redis:private-7 \
  --fork redis://h:<password>@<hostname>:<port> \
  --encryption-key CMK_ARN \
  --app your-app-name

Once your fork is created and caught up to the leader, you can promote it.

$ heroku redis:promote <redis-addon-name> --app example-app

Promoting a forked Redis instance will update the REDIS_URL config var, and will restart the application.

Disabling Your Encryption Key

As part of the lifecycle of your encryption key, you may need to disable the key. When performing this action, all data encrypted with the key will be rendered inaccessible.

You can disable your encryption key via the AWS web console or the AWS CLI.

$ aws kms disable-key --key-id CMK_ARN

Once we receive notification of the key disablement, there is a 10 minute waiting period before action is taken. This helps make sure accidental changes to the key status do not unnecessarily alter resources that depend on the key.

After the 10 minute waiting period, we will shutdown all services that use the encryption key. Next we will stop all servers that run those services. Finally, we will send an email notification to application administrators notifying them of the disabled action. Expect approximately 20 minutes to elapse between key disablement and service shutdown.

Enabling Your Encryption Key

If you need to regain access to data that is encrypted with your encryption key, you may enable that key to restore. You can enable your encryption key via the AWS web console or the AWS CLI.

$ aws kms enable-key --key-id CMK_ARN

Once we receive notification of the key enablement, we will start previously stopped servers. Once they are running, we will start affected services. Finally, we will send an email notification to application administrators notifying them of the enabled action. Expect approximately five minutes to elapse between key enablement and service restart.

Limitations

There are limitations that apply to databases encrypted with a customer encryption key.

• This feature is only available for Heroku Redis on Private and Shield plans.