Running AWS CloudHSM Workloads in Containerized Environments

More Info

AWS CloudHSM offers hardware security modules (HSMs) in the cloud, enabling users to generate and manage their own encryption keys with FIPS 140-2 Level 3 validated HSMs. These HSMs operate within a CloudHSM cluster that ensures synchronization, high availability, and failover automatically.

CloudHSM is part of AWS’s Cryptography suite, which includes AWS Key Management Service (KMS), AWS Secrets Manager, and AWS Private Certificate Authority (CA). While KMS, Secrets Manager, and Private CA are user-friendly managed services, CloudHSM becomes essential for workloads that require single-tenant HSMs or specific cryptographic functions not provided by the managed services.

To connect your application to HSMs, CloudHSM supports several libraries, including PKCS#11, Java Cryptography Extensions (JCE), OpenSSL Dynamic Engine, and Microsoft Cryptography API: Next Generation (CNG). Regardless of the library used, the CloudHSM client is necessary for connecting to your HSMs.

This post will guide you through using Docker to build, deploy, and operate applications utilizing the CloudHSM SDK. Additionally, it will cover how to manage and orchestrate workloads through services such as Amazon Elastic Container Service (ECS), Kubernetes, Amazon Elastic Kubernetes Service (EKS), and Jenkins.

Overview of the Solution

This solution illustrates how to create a Docker container employing the CloudHSM JCE SDK to generate a key for encrypting and decrypting data.

Note: You will be required to manually input the crypto user (CU) credentials as environment variables when launching the container. For production environments, you should address how to secure and automate the management and distribution of these credentials. Collaborate with your security or compliance team to ensure you are using a proper method for securing HSM login information. For further details on securing credentials, refer to AWS Secrets Manager.

The architecture includes a Java application running in a Docker container that interacts with JCE and communicates with CloudHSM instances through HSM elastic network interfaces (ENIs). The Docker container operates within an EC2 instance, with access to the HSM ENIs regulated by a security group.

Prerequisites

To implement this solution, you should have familiarity with the following:

• CloudHSM
• Docker version 20.10.17 (as of this post)
• Java 8 or 11 (supported at this time)
• Maven 3.05 (used at this time)

To follow this example, you will need the following:

• An active CloudHSM cluster with at least one HSM instance. You can refer to the CloudHSM getting started guide to create and activate your cluster.
• Note: It’s advisable to have a minimum of two active HSM instances across different Availability Zones for production workloads.
• An Amazon Linux 2 EC2 instance in the same Virtual Private Cloud (VPC) as your CloudHSM cluster. This EC2 instance must have the CloudHSM cluster security group attached, which is automatically created during cluster initialization to manage access to the HSMs. For guidance on configuring security groups for EC2 instances to connect to HSMs, see the AWS CloudHSM User Guide.
• A CloudHSM crypto user (CU) account. You can establish a CU by following the steps outlined in the AWS CloudHSM User Guide.

Implementation Details

In this section, I will guide you through downloading, configuring, compiling, and executing the solution within Docker.

To set up Docker and operate the application that encrypts and decrypts data with a key in AWS CloudHSM:

1. On your Amazon Linux EC2 instance, install Docker using the following command:
   # sudo yum -y install docker
2. Start the Docker service:
   # sudo service docker start
3. Create a new directory and navigate to it. For this example, we will use cloudhsm_container:
   # mkdir cloudhsm_container
# cd cloudhsm_container
4. Copy the CloudHSM cluster’s trust anchor certificate (customerCA.crt) to the newly created directory. You can locate this certificate on a working CloudHSM client instance at /opt/cloudhsm/etc/customerCA.crt. This certificate is necessary for validating the connection to the CloudHSM cluster.
5. In the new directory, create a file named run_sample.sh with the following content:

   #! /bin/bash
   
   # start application
   echo -e "n* Entering AES GCM encrypt/decrypt sample in Docker ... n"
   
   java -ea -jar target/assembly/aesgcm-runner.jar -method environment
   
   echo -e "n* Exiting AES GCM encrypt/decrypt sample in Docker ... n"

6. Create another file named Dockerfile (without an extension) that will define the components used for building the Docker image:
   – The CloudHSM client package.
   – The CloudHSM Java JCE package.
   – OpenJDK 1.8 (Java 8).
   – Maven for building Java classes.
   – The AWS CloudHSM Java JCE samples, which will be downloaded and built as part of the solution.
7. Insert the following contents into the Dockerfile. Note: Customize your Dockerfile by specifying the SDK version in the pom.xml file of the sample code. As of this writing, the latest version is 5.7.0. For SDK version information, refer to the Cloud HSM JCE examples README.

FROM amazonlinux:2

ARG HSM_IP

RUN yum install -y https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-jce-latest.el7.x86_64.rpm

RUN yum install -y java maven wget unzip ncurses-compat-libs

WORKDIR /app

RUN wget https://github.com/aws-samples/aws-cloudhsm-jce-examples/archive/refs/head

For additional insights, check out this blog post for further reading. Also, if you seek authority on this matter, visit this source for comprehensive information. Lastly, this link serves as an excellent resource on the subject.