AWS KMS Group Setup

1.0  Introduction

This article describes how to set up a Cloud-Data-Control (CDC) group for Amazon Web Services (AWS) Key Management Service (KMS) using Fortanix-Data-Security-Manager (DSM).

The Fortanix solution for AWS KMS offers complete Cloud Native Key Management Service (CNKMS), Bring Your Own Key (BYOK), and Bring Your Own KMS (BYOKMS), with complete lifecycle management for automation.

This article will walk you through setting up a CDC group that will be used for both CNKMS and BYOK workflows.

2.0 Getting Started with Fortanix Cloud Data Control

To understand which solution between CNKMS, BYOK, Bring Your Own KMS (AWS XKS), or Bring Your Own Encryption (BYOE) is right for you, refer to Fortanix DSM - Cloud Data Control - Getting Started.

For BYOKMS using AWS External Key Store (XKS), refer to Fortanix DSM with AWS External Key Store (XKS).

3.0 Obtaining Access to Fortanix DSM

Create an account in Fortanix DSM if you do not have one already. For more information, refer to the User's Guide: Getting Started with Fortanix Data Security Manager - UI.

4.0  Fortanix DSM AWS KMS Group Setup

The following section describes the workflow to configure Fortanix DSM to interact with the AWS KMS. An AWS CDC KMS group is created in the Fortanix DSM account, and this group is configured to interact with the AWS KMS.

4.1  Prerequisites

To configure the AWS CDC group, the following are the AWS KMS permissions that the AWS Identity and Access Management (IAM) users must have to authenticate the Fortanix DSM group with AWS KMS.

LIST Permissions:

• ListKeys

• ListKeyPolicies

• ListRetirableGrants

• ListAliases

• ListGrants

• ListResourceTags

READ Permissions:

• DescribeKey

• GetPublicKey

• GetKeyRotationStatus

• GetKeyPolicy

• GetParametersForImport

WRITE Permissions:

• CreateKey

• ImportKeyMaterial

• DeleteImportedKeyMaterial

• EnableKey

• DisableKey

• ScheduleKeyDeletion

• CancelKeyDeletion

• EnableKeyRotation

• DisableKeyRotation

• CreateAlias

• DeleteAlias

• UpdateAlias

• PutKeyPolicy

• GenerateDataKey

• TagResource

• UntagResource

• CreateGrant

• RetireGrant

• RevokeGrant

4.2  Configure an AWS CDC Group

Perform the following steps to create an AWS CDC group:

1. In the DSM left navigation panel, click the Groups menu item, and then click ADD GROUP to create a new group.

2. On the Add new group form:

   1. Enter a name and description for your group.

   2. Click LINK HSM/EXTERNAL KMS to select the AWS KMS type, so that Fortanix DSM can connect to it.

   3. Select the Configure as HSM/External KMS group type as AWS Key Management Service from the drop down menu.

   4. In the Enter Region field, enter the AWS region code from which the keys should be imported. For a complete list of supported AWS regions, refer to AWS Regions.
      If you are a United States (US) government employee, you can enter from the following AWS GovCloud regions:

      • AWS GovCloud (US-East)

      • AWS GovCloud (US-West)

      When you enter an AWS GovCloud region, then the AWS BYOK key upload operations are executed against the KMS in that region and the uploaded keys will appear usable by AWS GovCloud.

      NOTE

      To use AWS GovCloud for the US Government, you need to be a US citizen associated with the US Federal Government or a US government contractor. Refer to the Cloud Providers official documentation about access to these environments.

   5. Enter the AWS KMS service account credentials: 

      • URL: The URL of the AWS region gets auto-populated based on the region selected. This is an editable field, so a user can also add a custom URL of the AWS region. In the case of a custom URL, the URL label will change to URL (Custom).

      • AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY: The Access Key and Secret Access Key are used for accessing the AWS services. Each AWS account has its unique login credentials; Fortanix DSM should allow you to log in and securely save AWS credentials to do native cloud key management and offline automation such as automatic key rotation based on a set schedule and so on. For more information on obtaining AWS credentials, refer to the AWS official documentation.

3. Add TLS configuration (optional). For more information, refer to Section 4.3: Add TLS Configuration (Optional).

4. Click TEST CONNECTION to test your AWS KMS connection. If Fortanix DSM can connects to AWS using your connection details, then it shows the status as “Connected” with a green tick   and fetches the key vaults associated with the Subscription ID. Otherwise, it shows the status as “Not Connected” with a yellow warning sign   .

   NOTE

   Though it is an optional step, you can save your group details even if the connection information might be incorrect or incomplete, you can edit these details later.

5. In the Key Material Mapping section, select either of the following two options:

   1. AWS key container maps to security object: Select this option to map an AWS KMS key container to a virtual security object in Fortanix DSM. Each virtual security object in DSM represents an AWS KMS key container. Rotating the virtual security object performs manual rotation of the AWS KMS key (that is, replacing the KMS key with a new key). As a result, the key material, Key ID, and key ARN change after rotation. Since a new KMS key is created, applications that reference the key may need to be updated unless they use an alias. This method can be used for all key types, including those that do not support AWS-native rotation.  

      NOTE

      After rotating a key if you update the key alias or add a key alias, the updates are applied to that specific key only.

   2. AWS key material maps to security object: Select this option to map AWS KMS key material to a virtual security object in Fortanix DSM. Each virtual security object in DSM represents an AWS KMS key material. Rotating the virtual security object performs AWS-native key rotation (that is, rotating key material within the same AWS KMS key). This rotation is performed using AWS KMS on-demand rotation APIs, which allow new key material to be activated without changing the KMS key identity. During rotation, only the underlying key material changes, while the Key ID and key ARN remain the same. Each rotation creates a new key material version (tracked using a key_material_id). Because the key identity does not change, applications do not need to update their references. Rotation is supported only for key types that allow AWS-native rotation (currently AES 256 keys).  

      NOTE

      • A key can be rotated up to 25 times using this option. Attempting to rotate the key beyond this limit (for example, a 26th rotation) results in an error. This limit is enforced by AWS KMS for on-demand rotation of imported key material.

      • After rotating a key if you update the key alias or add a key alias, the updates are applied to all the rotated versions of that key.  

      For information about rotation scenarios supported for each key material mapping option, refer to Section 6.0: Rotation Scenarios.

6. Click SAVE to create the group.

After you save your group details, your group is created, and you will see a detailed view of your group.

4.3  Add TLS Configuration (Optional)

In the TLS configuration section, click + ADD AUTHENTICATION CERTIFICATE to add a certificate for authenticating the AWS KMS. Fortanix's external KMS solution requires that the customer applications use one of the Fortanix DSM interfaces (REST, PKCS#11, KMIP, JCE, or CNG) to interact with Fortanix DSM for key management and cryptographic operations. These applications should be configured to authenticate to Fortanix DSM using a Certificate or Trusted Certificate Authority (CA) instead of directly communicating with AWS KMS.

1. Select the Validate Host check box to check if the certificate that the AWS KMS provided has the same subjectAltName or Common Name (CN) as the hostname that the server certificate is coming from.

2. You can select either of the following certificates:

   • Global Root CAs - Use this certificate if you are using a certificate that is signed by a well-known public CA. By default, every AWS CDC Group is configured with a Global Root CA Certificate.

   • Custom CA Certificate – Use this option when you as an enterprise want to self-sign the certificate using your own internal CA. You can override the default Global CA Certificate with a Custom CA Certificate for an AWS CDC group. You can either upload the certificate file or copy the contents of the certificate in the textbox provided.

     • CLIENT CERTIFICATE (optional): The Custom CA Certificate also has a Client Certificate section where you can configure a client certificate and a private key (Fortanix DSM Certificate and Key). This allows Fortanix DSM to authenticate itself to the AWS KMS and vice versa.

3. Click SAVE.

4.4 Not Connected Scenario

When you click the TEST CONNECTION, it is possible that Fortanix DSM is not able to connect to the AWS node. If that happens, it displays a “Not Connected” status with a warning symbol . You can save the details of the new connection details provided and edit them later.

4.5 HSM/KMS Tab

The group details now include an HSM/KMS tab displaying information about your KMS.

The HSM/KMS tab displays the details of the AWS Service Type, including the connection details of the Service Type such as the URL and access key. You can edit these connection details here. You can also see the selected AWS region name here.

After editing and saving, click TEST CONNECTION to check the connection.

Click SYNC KEYS to sync keys from the configured AWS KMS to the AWS CDC group.

4.6  Groups Table View

After saving the group details, you can view the list of all groups and notice the special symbol next to the newly created group. This symbol indicates that it is an AWS CDC group, distinguishing it from other groups.

4.7  User's View

Navigate to the Users menu item in the DSM left navigation panel and click the user that says “You” on the Users page to view the user’s detailed view.

The detailed view shows all the groups the user belongs to and indicates which groups are mapped to AWS KMS, displaying their status as "connected" or "not connected."

5.0 AWS KMS BYOK and Cloud Native Key Management

For more information on how to perform native key lifecycle management in AWS KMS using Fortanix DSM, refer to Fortanix DSM - AWS KMS Cloud Native Key Management Service.

For more information on how to perform BYOK key lifecycle management in AWS KMS using Fortanix DSM, refer to Fortanix DSM - AWS KMS Bring Your Own Key.

6.0 Rotation Scenarios

The following table lists the supported rotation scenarios based on the Key Material Mapping option selected when configuring the AWS CDC group.