AWS Cloud Key Management (AWS KMS) Integration

KMES Series 3 Integration Guide

aws marketplace cloud payment hsm
key management service KMES Series 3

Table of Contents

Overview of the AWS KMS / KMES Series 3 Integration

About AWS Key Management Service (KMS)

From AWS’s website: “AWS Key Management Service (KMS) makes it easy for you to create and manage cryptographic keys and control their use across a wide range of AWS services and in your applications. AWS KMS is a secure and resilient service that uses hardware security modules that have been validated under FIPS 140-2, or are in the process of being validated, to protect your keys. AWS KMS is integrated with AWS CloudTrail to provide you with logs of all key usage to help meet your regulatory and compliance needs.”

Please refer to the following URL on the AWS documentation website for more information about AWS Key Management Service (KMS): https://docs.aws.amazon.com/kms/index.html

Download this guide as a PDF

Customer Managed Keys

Customer managed keys are KMS keys in your AWS account that you create, own, and manage. You have full control over these KMS keys, including establishing and maintaining their key policies, IAM policies, and grants, enabling and disabling them, rotating their cryptographic material, adding tags, creating aliases that refer to the KMS keys, and scheduling the KMS keys for deletion.

Customer managed keys appear on the Customer managed keys page of the AWS Management Console for AWS KMS.

The customer managed keys feature also allows you to import existing symmetric keys into AWS KMS. For this integration, this means being able to create symmetric HSM Protected keys on a KMES Series 3 device, and then pushing those keys to AWS KMS from the KMES application interface.

Keys that are pushed to AWS KMS can be used with other services inside AWS, such as the following:

  • Amazon S3
  • The Transparent Data Encryption functionality in Amazon RDS and Amazon DynamoDB
  • Amazon Route 53
  • AWS Lambda

AWS KMS also has its own API that customers can use with their own applications to access and use keys stored in AWS KMS.

For this integration, keys will be created and stored on the KMES Series 3, synchronized to AWS KMS, and then subsequently managed via the KMES application interface.

Benefits of the Integration

The AWS KMS / KMES Series 3 integration provides several benefits:

  • Key provenance: You are the sole owner of your keys, so you have the ability to control the location and distribution of them.
  • Added assurance: Keys that are created on the KMES and imported into AWS KMS never leave the HSM boundary. Because, even once in AWS KMS, the keys are stored on hardware security modules on the backend.
  • Centralized key management: You can manage your keys and access policies from a single location and user interface, whether the data they protect resides in the cloud or on your premises.
  • Audit compliance: Many audits require you to escrow keys outside of the cloud provider. This is accomplished with this integration.

Futurex Certification Process

The Futurex Certification Process is a rigorous and standardized approach to testing and certifying integrations between third-party applications and Futurex’s HSMs and key management servers (i.e., KMES Series 3). The certification process is designed to ensure that third-party application integrations are fully tested and validated in a lab environment before they are deployed in a production environment. Futurex’s Integration Engineering team implements this process so that customers can have confidence that third-party applications will integrate seamlessly with Futurex’s HSMs and KMES Series 3 devices, and that all operations will result in the expected behavior. The certification process involves several steps, including research, testing, troubleshooting, and certification, and is fully documented in an integration guide for each integration. The full process is outlined below:

  1. Research the third-party application to gain a general understanding of the solution and the protocol it uses to integrate with an HSM or KMS device (i.e., PKCS #11, Microsoft CNG, JCE, OpenSSL Engine, KMIP).
  2. Determine the scope of the third-party application’s use of the HSM or KMS device, including the specific functionalities it utilizes (i.e., data encryption, key protection, entropy, etc.).
  3. Install and configure the third-party application in a lab environment, where all testing and validation will take place.
  4. Establish a connection between the third-party application and the Futurex device, which typically involves configuring TLS certificates and creating roles and identities that the third-party application will use to connect and authenticate to the Futurex device.
  5. Initiate a request from the third-party application to the Futurex device, such as generating keys or certificates, encrypting or decrypting data, or other cryptographic functions.
  6. If any errors occur during the testing process, the Integration Engineering team will diagnose the issues and take necessary corrective actions. If necessary, the team will also document the error(s) by creating engineering change requests (ECRs) to ensure all issues are addressed and resolved before certification.
  7. After any necessary engineering changes have been made, a new end-to-end test will be performed to ensure that all errors have been resolved and that all operations are successful.
  8. Certify the integration by creating an integration guide that covers all necessary prerequisites, configurations required in both the third-party application and the Futurex device, and how to test the functionality.

Overall, following these steps helps ensure that the integration between the third-party application and the Futurex device is fully tested and validated, and that any errors or issues are resolved before the integration is certified as fully supported.

Create Credentials for Communication Between the KMES Series 3 and AWS KMS

Before the KMES Series 3 can push key material to AWS KMS, credentials must be created in the AWS IAM service and then configured on the KMES. In AWS IAM, these credentials will take the form of an Access Key. On the KMES, the credentials will take the form of a Cloud Credential.

Create an Access Key in AWS IAM

  1. Log in to the AWS Management Console.
  2. Navigate to the Identity & Access Management (IAM) service: https://console.aws.amazon.com/iam/home
  3. On the right side of the page, under “Quick Links”, click on My security credentials.
  4. There are 3 tabs on this page: “AWS IAM credentials”, “AWS CodeCommit credentials”, and “Amazon MCS credentials”. Select the first tab (AWS IAM credentials).
  5. Under “Access keys for CLI, SDK, & API access”, click the Create access key button.
  6. Create a symmetric access key. Upon completion you will be given 2 values: “Access Key ID” and “Secret Access Key”. You may write these down and populate a CSV file with these values, or you can use the onpage option to download and save the CSV. It should be in the following format: 
    Access key ID,Secret access key
AccessID,AccessKey

    NOTE: This is the only time you will be able to view your secret key. Be sure to write it down/save it now.

  7. Copy or move the CSV file containing the Access Key to the storage medium that is configured on your KMES Series 3 device.

Create a Cloud Credential on the KMES

  1. Log in to the KMES Series 3 application interface using the default admin identities.
  2. Select Identity Management -> Cloud Credentials from the sidebar.
  3. Right-click and select Add -> Cloud Credential (or click the Add Cloud Credential button at the lowerright).
    1. Name = Any name of your choosing
    2. Service = Amazon Web Services
    3. Access Name = Leave this blank; it will auto-populate after import.
    4. Click Import and select the CSV file with your Key IDs.
    5. Click OK to save.

Create a Customer Managed Key in AWS KMS

This section will explain how to create a customer managed key in AWS KMS. The KMS key will be created devoid of key material so that the KMES can be the source of the key material. The process for pushing keys from the KMES to AWS KMS will be explained in a later section.

  1. Log in to the AWS Management Console.
  2. Navigate to the Key Management Service.
  3. Select Customer managed keys in the left menu, then click the orange Create key button in the upperright portion of the page.
  4. Step 1: Configure key
    1. Key type = Symmetric
    2. Key material origin = External
      NOTE: The “KMS” option also works, but it generates a key, so the KMES will not have the key material for this initial key. The “External” option will create a placeholder key without key material, allowing the KMES to provide key material in later steps.
    3. Regionality = Single-Region key
    4. Click the Next button.
  5. Step 2: Add labels
    1. Alias = Any nickname of your choosing
    2. Description = Optional
    3. Tags = Optional
    4. Click the Next button.
  6. Step 3: Define key administrative permissions
    1. Key administrators = Select your user account
    2. Key deletion = Check the box, “Allow key administrators to delete this key.”
    3. Click the Next button.
  7. Step 4: Define key usage permissions
    1. This account = Select your user account
    2. Other AWS accounts = Optional
    3. Click the Next button.
  8. Step 5: Review
    1. Ensure the top 3 fields (Key configuration, Alias and description, and Tags) are correct.
    2. The final (4th) field is “Key policy”. Copy and paste the contents of the key policy into a file and save with the JSON extension. This file needs to be copied or moved to the storage medium that is configured on your KMES Series 3 device.
    3. Click the Finish button.
  9. It will prompt you to download a wrapping key and import token. Click Cancel to skip it.
  10. Back on the main Key Management Service (KMS) page, make a copy of the generated key ID (should be formatted like “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”). This ID (and the policy) will be needed for the “AWS Properties” tab when creating an HSM Protected Key Group on the KMES in the next section.

Creating and Pushing Keys from the KMES Series 3 to AWS KMS

This section will explain how to create a new HSM Protected Key Group on the KMES and how the different key operations work for pushing keys to AWS KMS.

NOTE: If a firewall is configured in your environment, ensure that the *.amazonaws.com:443 endpoint is allowed from the KMES out to the internet. If a more specific endpoint is preferred or required, please refer to the following documentation: https://docs.aws.amazon.com/general/latest/gr/kms.html

Create a New HSM Protected Key Group

Key groups act as both a container for keys and a template by which keys are created within the key group, allowing you to define various key attributes, such as the type of key and the key rotation schedule, and the service to use (e.g., Amazon Web Services).

  1. Log in to the KMES Series 3 application interface using the default admin identities.
  2. Select Key Management -> Keys from the sidebar.
  3. Right-click and select Add -> Key Group (or click the Create button at the upper-right).
    1. Key Type = Symmetric
    2. Storage Location = HSM Protected
    3. Click OK.
      NOTE: Asymmetric keys are not supported for the AWS KMS integration.
  4. Group tab setup
    1. Name = Any name of your choosing
    2. Service = Amazon Web Services
    3. Credential = Click Select and choose the credential that was created from the CSV in the Create a Cloud Credential on the KMES section.
    4. Key Type = AES
    5. Key Length = AES-256
    6. Key Usage = Encrypt + Decrypt
    7. Rotate Key = Leave box checked if you want the key group to rotate keys on a schedule.
    8. Rotate every = Set the desired rotation interval.
    9. Keep key valid for = Set the length of time that keys created in the key group should remain valid.
  5. Info tab setup
    1. Leave blank/default
  6. AWS Properties tab setup
    1. Alias = Any nickname of your choosing
    2. Description = Optional
    3. Region = Select the AWS region where the KMS key was created in the Create a Customer Managed Key in AWS KMS section.
    4. Active Key ID = Enter the key ID formatted like “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx” (from step 10 of the instructions in Create a Customer Managed Key in AWS KMS).
    5. Policy = Click Import Policy and select the policy that was saved as a JSON file in step 8b of Create a Customer Managed Key in AWS KMS. The policy specifies the permissions used to access the customer master key in AWS.
    6. Disable key after rotating = Check/uncheck as desired
    7. Click OK to finish creating the HSM Protected Key Group.

Pushing Keys to AWS KMS

There are two main operations that can be performed on keys that are part of an AWS HSM Protected Key Group:

  • Rotate on an HSM Protected Key Group – This forces a new key to be generated on the KMES and then uploaded to AWS with the alias configured under the AWS Properties tab assigned to the key. On the “Customer managed keys” page in AWS KMS, you will see that if you keep rotating, the old key ID loses the alias, and the most recently created key has the alias assigned.
  • Synchronize on an HSM Protected Key – This updates the given key ID in AWS with the selected key. As an example, the key material can be deleted from AWS for a key, then you can right-click that same key in the KMES and synchronize it and re-add the key material. Key material can also be deleted from AWS by checking the appropriate check box when synchronizing in the KMES.

NOTE: For this integration, the only way that keys should be generated inside an AWS HSM Protected Key Group is by force rotating the key group or simply waiting for a key rotation to occur based on the configured rotation schedule.

For demonstration purposes, we will force rotate the HSM Protected Key Group to generate and push the first key to AWS KMS. To do so, please follow the steps outlined below:

  1. Make sure that the KMES is set to be the designated device for rotating key material (under Administration -> Configuration -> HSM Protected Key Options).
  2. Select Key Management -> Keys from the sidebar.
  3. Right-click on the HSM Protected Key Group that was created in the previous section, then select Cloud -> Force Rotate.
  4. A job will be started to rotate and synchronize this key to the AWS KMS account that was specified for the key group. Navigate to Logging and Reporting -> Jobs and double-click on the Rotate HSM protected keys job that was just started. If the synchronization is successful, a message similar to the following will be shown:pushing keys to aws kms rotate hsm protected keys success message
  5. Once the job is finished, navigate back to the Keys view and select the key group of the key that was just synchronized. We can see that the key is listed now under the key group:pushing keys to aws kms keys view group We can see the key in AWS KMS as well, with the alias assigned that was configured on the AWS Properties tab for the HSM Protected Key Group:aws kms assigned alias configured on the aws properties tab for hsm protected key group
  6. Right-click the AWS HSM Protected Key Group again and select Cloud -> Force Rotate. The new key that is generated (e.g., 1096ea6e…) will be listed with the first key that was generated in the key group:aws hsm protected key group cloud force rotate new key being assigned alias configured for hsm protected key group In AWS, this new key will now be assigned the alias configured for the HSM Protected Key Group (e.g., ig-alias) and the previously active Key ID will lose the alias.aws customer managed keys active ID losing alias
  7. The other key operation mentioned at the beginning of this section was synchronizing on an HSM Protected Key. This would mean synchronizing, or optionally deleting, key material for any of the previously active Key IDs. To do so, select the AWS HSM Protected Key Group, then right-click one of the previously active key IDs and select Cloud -> Synchronize. This will open the following dialog:aws hsm protected key group cloud synchronize dialogue
  8. The “Update Policy” and “Import Key Material” options will be selected by default. It would only make sense to import key material if the key material had been deleted for the associated Key ID previously, either in AWS KMS or via the “Delete Key Material” option shown here. Regardless of the synchronization option that is performed, a new job will be created on the Logging and Reporting -> Jobs page where the progress of the operation can be tracked.

Logging

This section will explain how to track the progress/status of jobs related to AWS HSM Protected Key Groups, as well as how to view AWS-related events in the Audit Log.

Tracking the Progress/Status of Jobs

It has already been mentioned in previous sections that the progress/status of jobs related to AWS can be viewed under Logging and Reporting -> Jobs. Events specific to this integration that would initiate a new job include the following:

  • Rotate HSM protected key(s)
  • Synchronize HSM protected key(s)

AWS-related events can also be viewed under Logging and Reporting -> Audit Logs. The following is an example of how these log entries would appear.aws related events logging and reporting audit logs example

Want to learn more?

If you are interested in our solution for AWS Cloud Key Management, or would like to inquire about a demo, please contact us.

Give us a call