Skip to main content

AWS hosted key

To allow root keys to be hosted externally, a number of key providers are supported. One such provider is AWS KMS. Currently, Antimatter supports two methods for hosting the domain Root Encryption Key (REK) in Amazon Web Services Key Management Service (AWS KMS):

  • Hold the key in AWS KMS and delegate access to the key to the Antimatter account.
  • Hold the key in AWS KMS and create a service account for Antimatter to use to access the key.

Both options are covered below. For this guide, we assume that the Antimatter CLI has been installed (see CLI) and that a domain has been created.

Access the key management page.​

If using the dashboard, navigate to Domain Configuration -> Encryption Rotation and select the option: "Change Root Encryption Key Configuration"

Dahsboard UI

This will redirect you to the key management modal where the REK source can be selected.

Adding an AWS Root Key​

To delegate a key hosted in an AWS KMS for use by Antimatter, the following operations need to occur:

  • A key must be created if it does not already exist.
  • A key alias must be created that includes the domain ID in the form alias/<domain-id>
  • Permission must be given to allow the Antimatter AWS account to access the key for the following actions:
{
  kms:DescribeKey,
  kms:GenerateDataKeyWithoutPlaintext,
  kms:Decrypt,
  kms:ReEncryptFrom,
  kms:ReEncryptTo
}

The simplest way to perform the above steps is through the key management UI, however, it is also possible to add a key through the CLI.

From the key management UI, adding a delegated AWS key is done by first selecting the option; "I want to configure my own externally-held key." and then selecting 'Next'. The user can then select a provider to host the key, for this example, select "AWS key management" and click 'Next'.

Onboarding UI

You will now be given the option to use either an existing key, or be guided through the process of creating a new one. In both cases, the next step will require access to a terminal with the AWS CLI installed and authenticated. This can either be done locally, or via a CloudShell in the AWS web console.

If you wish to use an existing key, then select "I have an existing REK I wish to use for wrapping" and click 'Next'. On the subsequent pane, you will be provided with a script that must be run in a terminal with the AWS CLI available.

Onboarding UI

note

While this script is intended to be used as-is, it does require one modification. You will be required to include the key ID to be shared with Antimatter on the first line, in the form. This must be added in place of <enter your key ID here>.

The script will perform the following actions:

  1. Fetch the account number of the current user executing the script.
  2. Create an alias of the key of the form /alias/<domain-id>/antimatter.
  3. Printout the key alias resource name.

The key alias name here is important as it must have the form /alias/<domain-id>/antimatter. This is required so that Antimatter can confirm that the alias supplied is intended for the domain. Removing the alias or supplying one that does not contain the above form will result in Antimatter being unable to use it as a Root Key. Additionally, note the permissions added to the alias. These are the minimal permissions required to allow Antimatter to describe the key and use it to wrap internally generated keys used for encryption.

Once run, the script will return: Key alias (save this for next step): arn:aws:kms:REGION:aaaaaaaaaa:key/alias/<domain-id>/antimatter. Note this down for the final step.

After running the generated script, return to the key management page and click 'Next'. On the new pane you will be asked to submit the key ARN that was printed out after running the script. After pasting, click 'Apply' and wait for the paring check to complete. Once complete, click 'Done'.