# Getting started with AWS CloudHSM The following topics help you create, initialize, and activate a cluster in AWS CloudHSM. After you complete these procedures, you'll be ready to manage users, manage clusters, and use the included software libraries to perform cryptographic operations. For the best experience, follow the topics in the listed order. **Topics** + [ # Create IAM administrative groups for AWS CloudHSM ](create-iam-user.md) + [ # Create a virtual private cloud (VPC) for AWS CloudHSM ](create-vpc.md) + [ # Create a cluster in AWS CloudHSM ](create-cluster.md) + [ # Review the security group for your cluster in AWS CloudHSM ](configure-sg.md) + [ # Launch an Amazon EC2 client instance for interacting with AWS CloudHSM ](launch-client-instance.md) + [ # Configure the Client Amazon EC2 instance security groups for AWS CloudHSM ](configure-sg-client-instance.md) + [ # Create an HSM in AWS CloudHSM ](create-hsm.md) + [ # Verify the identity and authenticity of your cluster's HSM in AWS CloudHSM (optional) ](verify-hsm-identity.md) + [ # Initialize the cluster in AWS CloudHSM ](initialize-cluster.md) + [ # Install and configure CloudHSM CLI ](gs_cloudhsm_cli-install.md) + [ # Activate the cluster in AWS CloudHSM ](activate-cluster.md) + [ # Set up mutual TLS between client and AWS CloudHSM (recommended) ](getting-started-setup-mtls.md) + [ # Create and use keys in AWS CloudHSM ](create-apps.md) # Create IAM administrative groups for AWS CloudHSM The first step to getting started with AWS CloudHSM is to set up IAM permissions. As a [best practice](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#create-iam-users), don't use your AWS account root user to interact with AWS, including AWS CloudHSM. Instead, use AWS Identity and Access Management (IAM) to create an IAM user, IAM role, or federated user. Follow the steps in the section [Create an IAM user and administrator group](#create-iam-admin) to create an administrator group and attach the **AdministratorAccess** policy to it. Then create a new administrator user and add the user to the group. Add additional users to the group as needed. Each user you add inherits the **AdministratorAccess** policy from the group. Another best practice is to create an AWS CloudHSM administrator group that has only the permissions required to run AWS CloudHSM. Add individual users to this group as needed. Each user inherits the limited permissions that are attached to the group rather than full AWS access. The [Customer managed policies for AWS CloudHSM](identity-access-management.md#permissions-for-cloudhsm) section that follows contains the policy that you should attach to your AWS CloudHSM administrator group. AWS CloudHSM defines a [service–linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role) for your AWS account. The service–linked role currently defines permissions that allow your account to log AWS CloudHSM events. The role can be created automatically by AWS CloudHSM or manually by you. You cannot edit the role, but you can delete it. For more information, see [Service-linked roles for AWS CloudHSM](service-linked-roles.md). ## Create an IAM user and administrator group Start by creating an IAM user along with an administrator group for that user. ### Sign up for an AWS account If you do not have an AWS account, complete the following steps to create one. **To sign up for an AWS account** 1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup). 1. Follow the online instructions. Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad. When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks). AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [https://aws.amazon.com/](https://aws.amazon.com/) and choosing **My Account**. ### Create a user with administrative access After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks. **Secure your AWS account root user** 1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password. For help signing in by using root user, see [Signing in as the root user](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial) in the *AWS Sign-In User Guide*. 1. Turn on multi-factor authentication (MFA) for your root user. For instructions, see [Enable a virtual MFA device for your AWS account root user (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html) in the *IAM User Guide*. **Create a user with administrative access** 1. Enable IAM Identity Center. For instructions, see [Enabling AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html) in the *AWS IAM Identity Center User Guide*. 1. In IAM Identity Center, grant administrative access to a user. For a tutorial about using the IAM Identity Center directory as your identity source, see [ Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html) in the *AWS IAM Identity Center User Guide*. **Sign in as the user with administrative access** + To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user. For help signing in using an IAM Identity Center user, see [Signing in to the AWS access portal](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html) in the *AWS Sign-In User Guide*. **Assign access to additional users** 1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions. For instructions, see [ Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html) in the *AWS IAM Identity Center User Guide*. 1. Assign users to a group, and then assign single sign-on access to the group. For instructions, see [ Add groups](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html) in the *AWS IAM Identity Center User Guide*. For example policies for AWS CloudHSM that you can attach to your IAM user group, see [Identity and access management for AWS CloudHSM](identity-access-management.md). # Create a virtual private cloud (VPC) for AWS CloudHSM You need a virtual private cloud (VPC) for your cluster in AWS CloudHSM. If you don't already have one, follow the steps in this topic to create a VPC. **Note** Following these steps will result in the creation of public and private subnets. **To create a VPC** 1. Open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/). 1. On the navigation bar, use the region selector to choose one of the [AWS Regions where AWS CloudHSM is currently supported](https://docs.aws.amazon.com/general/latest/gr/rande.html#cloudhsm_region). 1. Select the **Create VPC** button. 1. For **Resources to create**, choose **VPC and more**. 1. For **Name tag auto-generation**, type an identifiable name such as **CloudHSM**. 1. For **IPv6 CIDR block**, select **Amazon-provided IPv6 CIDR block** to use IPv6 connectivity for your HSMs and have AWS allocate an IPv6 CIDR block for your cluster. This setting supports the dual-stack Network Type. Keep the default setting if you don't need IPv6 connectivity. 1. Leave all other options set to their defaults. 1. Choose **Create VPC**. 1. After the VPC is created, select **View VPC** to view the VPC you just created. # Create a cluster in AWS CloudHSM A cluster is a collection of individual hardware security modules (HSMs). AWS CloudHSM synchronizes the HSMs in each cluster so that they function as a logical unit. AWS CloudHSM offers two types of HSMs: *hsm1.medium* and *hsm2m.medium*. When you create a cluster, you choose which of the two will be in your cluster. For details on the differences between each HSM type and cluster mode, see [AWS CloudHSM cluster modes](cluster-hsm-types.md). When you create a cluster, AWS CloudHSM creates a security group for the cluster on your behalf. This security group controls network access to the HSMs in the cluster. It allows inbound connections only from Amazon Elastic Compute Cloud (Amazon EC2) instances that are in the security group. By default, the security group doesn't contain any instances. Later, you [launch a client instance](launch-client-instance.md) and [configure the cluster's security group](configure-sg.md) to allow communication and connections with the HSM. **Considerations** + The following are some considerations when creating a cluster in AWS CloudHSM: + When you create a cluster, AWS CloudHSM creates a [service-linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html) named AWSServiceRoleForCloudHSM. If AWS CloudHSM cannot create the role or the role does not already exist, you may not be able to create a cluster. For more information, see [Resolving AWS CloudHSM cluster creation failures](troubleshooting-create-cluster.md). For more information about service–linked roles, see [Service-linked roles for AWS CloudHSM](service-linked-roles.md). + If you are using the [AWS CloudHSM dual-stack endpoint](https://docs.aws.amazon.com/general/latest/gr/cloudhsm.html) (that is, cloudhsmv2.**.api.aws), ensure that your IAM policies are updated to handle IPv6. For more information, see the [Upgrade IAM policies to IPv6 section under Security](https://docs.aws.amazon.com/cloudhsm/latest/userguide/ip-access.html). You can create a cluster from the [AWS CloudHSM console](https://console.aws.amazon.com/cloudhsm/), the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), or the AWS CloudHSM API. For details on cluster arguments and APIs, see [https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/create-cluster.html](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/create-cluster.html) in the AWS CLI Command Reference. ------ #### [ Console ] **To create a cluster (console)** 1. Open the AWS CloudHSM console at [https://console.aws.amazon.com/cloudhsm/home](https://console.aws.amazon.com/cloudhsm/home). 1. On the navigation bar, use the region selector to choose one of the [AWS Regions where AWS CloudHSM is currently supported](https://docs.aws.amazon.com/general/latest/gr/rande.html#cloudhsm_region). 1. Choose **Create cluster**. 1. In the **Cluster configuration** section, do the following: 1. For **VPC**, select the VPC that you created in [Create a virtual private cloud (VPC) for AWS CloudHSM](create-vpc.md). 1. For **Availability Zone(s)**, next to each Availability Zone, choose the private subnet that you created. **Note** Even if AWS CloudHSM is not supported in a given Availability Zone, performance should not be affected, as AWS CloudHSM automatically load balances across all HSMs in a cluster. See [AWS CloudHSM Regions and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#cloudhsm_region) in the *AWS General Reference* to see Availability Zone support for AWS CloudHSM. 1. For **HSM type**, select the HSM type that can be created in your cluster along with the desired mode of the cluster. To see what HSM types are supported in each region, see the [AWS CloudHSM pricing calculator](https://aws.amazon.com/cloudhsm/pricing/). **Important** After the cluster is created, the cluster mode cannot be changed. For information on which type and mode is right for your use case, see [AWS CloudHSM cluster modes](cluster-hsm-types.md). 1. For **Network Type**, choose the IP address protocols for accessing your HSMs. IPv4 limits communication between your application and HSMs to IPv4 only. This is the default option. Dual-stack enables both IPv4 and IPv6 communication. To use dual-stack, add both IPv4 and IPv6 CIDRs to your VPC and subnet configurations. The Network Type is difficult to change after initial setup. To modify it, create a backup of your existing cluster and restore a new cluster with the desired Network Type. For more information, see [Creating AWS CloudHSM clusters from backups](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html) 1. For **Cluster source**, specify whether you want to create a new cluster or restore one from an existing backup. + Backups of clusters in non-FIPS mode can only be used to restore clusters that are in non-FIPS mode. + Backups of clusters in FIPS mode can only be used to restore clusters that are in FIPS mode. 1. Choose **Next**. 1. Specify how long the service should retain backups. 1. Accept the default retention period of 90 days or type a new value between 7 and 379 days. The service will automatically delete backups in this cluster older than the value you specify here. You can change this later. For more information, see [Configure backup retention](manage-backup-retention.md). 1. Choose **Next**. 1. (Optional) Type a tag key and an optional tag value. To add more than one tag to the cluster, choose **Add tag**. 1. Choose **Review**. 1. Review your cluster configuration, and then choose **Create cluster**. If your attempts to create a cluster fail, it might be related to problems with the AWS CloudHSM service-linked roles. For help on resolving the failure, see [Resolving AWS CloudHSM cluster creation failures](troubleshooting-create-cluster.md). ------ #### [ AWS CLI ] **To create a cluster ([AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/))** + At a command prompt, run the **[create-cluster](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/create-cluster.html)** command. Specify the HSM instance type, the backup retention period, and the subnet IDs of the subnets where you plan to create HSMs. Use the subnet IDs of the private subnets that you created. Specify only one subnet per Availability Zone. ``` $ aws cloudhsmv2 create-cluster --hsm-type hsm2m.medium \ --backup-retention-policy Type=DAYS,Value= \ --subnet-ids \ --mode \ --network-type { "Cluster": { "BackupPolicy": "DEFAULT", "BackupRetentionPolicy": { "Type": "DAYS", "Value": 90 }, "VpcId": "vpc-50ae0636", "SubnetMapping": { "us-west-2b": "subnet-49a1bc00", "us-west-2c": "subnet-6f950334", "us-west-2a": "subnet-fd54af9b" }, "SecurityGroup": "sg-6cb2c216", "HsmType": "hsm2m.medium", "NetworkType": "IPV4", "Certificates": {}, "State": "CREATE_IN_PROGRESS", "Hsms": [], "ClusterId": "cluster-igklspoyj5v", "ClusterMode": "FIPS", "CreateTimestamp": 1502423370.069 } } ``` **Note** `ClusterMode` is a required parameter for all hsm types except hsm1.medium.`--mode`: ``` $ aws cloudhsmv2 create-cluster --hsm-type hsm2m.medium \ --backup-retention-policy Type=DAYS,Value= \ --subnet-ids \ --mode NON_FIPS ``` If your attempts to create a cluster fail, it might be related to problems with the AWS CloudHSM service-linked roles. For help on resolving the failure, see [Resolving AWS CloudHSM cluster creation failures](troubleshooting-create-cluster.md). ------ #### [ AWS CloudHSM API ] **To create a cluster (AWS CloudHSM API)** + Send a [https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateCluster.html](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateCluster.html) request. Specify the HSM instance type, the backup retention policy, and the subnet IDs of the subnets where you plan to create HSMs. Use the subnet IDs of the private subnets that you created. Specify only one subnet per Availability Zone. If your attempts to create a cluster fail, it might be related to problems with the AWS CloudHSM service-linked roles. For help on resolving the failure, see [Resolving AWS CloudHSM cluster creation failures](troubleshooting-create-cluster.md). ------ # Review the security group for your cluster in AWS CloudHSM When you create a cluster or add an HSM to a cluster, AWS CloudHSM creates a security group with the name `cloudhsm-cluster--sg` if one doesn't already exist. This security group contains a preconfigured TCP rule that allows inbound and outbound communication within the cluster security group over ports 2223-2225. This SG allows your EC2 instances to use your VPC to talk to HSMs in your cluster. **Warning** Do not delete or modify the preconfigured TCP rule, which is populated in the cluster security group. This rule can prevent connectivity issues and unauthorized access to your HSMs. The cluster security group prevents unauthorized access to your HSMs. Anyone that can access instances in the security group can access your HSMs. Most operations require a user to log in to the HSM. However, it's possible to zeroize HSMs without authentication, which destroys the key material, certificates, and other data. If this happens, data created or modified after the most recent backup is lost and unrecoverable. To prevent unauthorized access, ensure that only trusted administrators can modify or access the instances in the default security group. The hsm2m.medium clusters introduces mTLS feature to restrict unauthorized users from connecting to the cluster. Unauthorized users will require a valid mTLS credentials to successfully connect to cluster before attempting zeroization. In the next step, you can [launch an Amazon EC2 instance](launch-client-instance.md) and connect it to your HSMs by [attaching the cluster security group](configure-sg-client-instance.md) to it. # Launch an Amazon EC2 client instance for interacting with AWS CloudHSM To interact with and manage your AWS CloudHSM cluster and HSM instances, you must be able to communicate with the elastic network interfaces of your HSMs. The easiest way to do this is to use an EC2 instance in the same VPC as your cluster. You can also use the following AWS resources to connect to your cluster: + [Amazon VPC Peering](https://docs.aws.amazon.com/vpc/latest/peering/Welcome.html) + [Direct Connect](https://docs.aws.amazon.com/directconnect/latest/UserGuide/Welcome.html) + [VPN Connections](https://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/vpn-connections.html) **Note** This guide provides a simplified example of how to connect an EC2 instance to your AWS CloudHSM cluster. For best practices around secure network configurations, refer to [Secure access to your cluster](bp-cluster-management.md#bp-secure-access). The AWS CloudHSM documentation typically assumes that you are using an EC2 instance in the same VPC and Availability Zone (AZ) in which you create your cluster. **To create an EC2 instance** 1. Open the **EC2 Dashboard** at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. Select **Launch instance**. From the drop-down menu, choose **Launch instance**. 1. In the **Name** field, enter a name for your EC2 instance. 1. In the **Applications and OS Images (Amazon Machine Image)** section, choose an Amazon Machine Image (AMI) that corresponds to a platform CloudHSM supports. For more information, see [AWS CloudHSM Client SDK 5 supported platforms](client-supported-platforms.md). 1. In the **Instance Type** section, choose an instance type. 1. In the **Key pair** section, use an existing key pair or select **Create new key pair** and complete the following steps: 1. For **Key pair name**, enter a name for the key pair. 1. For **Key pair type**, choose a key pair type. 1. For **Private key file format**, choose the private key file format. 1. Select **Create key pair**. 1. Download and save the private key file. **Important** This is your only chance to save the private key file. Download and store the file in a safe place. You must provide the name of your key pair when you launch an instance. Additionally, you must provide the corresponding private key each time you connect to the instance and choose the key pair that you created when setting up. 1. In **Network settings**, select **Edit**. 1. For **VPC**, choose the VPC that you previously created for your cluster. 1. For **Subnet**, choose the public subnet that you created for the VPC. 1. For **Auto-assign Public IP**, choose **Enable**. 1. For **Auto-assign IPv6 IP**, choose **Enable** to use IPv6 connectivity with your clusters and the Dual-stack NetworkType. If you enable this option, update your Amazon EC2 instance's security group rules, VPC and subnet route tables, and network ACLs to allow IPv6 outbound traffic from the instance to the HSMs. 1. Choose **Select an existing security group**. 1. In **Common security groups**, select the default security group from the drop-down menu. 1. In **Configure Storage**, use the drop-down menus to choose a storage configuration. 1. In the **Summary** window, select **Launch instance**. **Note** Completing this step will start the process for creating your EC2 instance. For more information about creating a Linux Amazon EC2 client, see [Getting Started with Amazon EC2 Linux Instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html). For information about connecting to the running client, see the following topics: + [Connecting to Your Linux Instance Using SSH](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstancesLinux.html) + [Connecting to Your Linux Instance from Windows Using PuTTY](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/putty.html) The Amazon EC2 user guide contains detailed instructions for setting up and using your Amazon EC2 instances. The following list provides an overview of available documentation for Linux and Windows Amazon EC2 clients: + To create a Linux Amazon EC2 client, see [Getting Started with Amazon EC2 Linux Instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html). For information about connecting to the running client, see the following topics: + [Connecting to your Linux Instance Using SSH](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstancesLinux.html) + [Connecting to Your Linux Instance from Windows Using PuTTY](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/putty.html) + To create a Windows Amazon EC2 client, see [Getting Started with Amazon EC2 Windows Instances](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/EC2_GetStarted.html). For more information about connecting to your Windows client, see [Connect to Your Windows Instance](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/EC2_GetStarted.html#ec2-connect-to-instance-windows). **Note** Your EC2 instance can run all of the AWS CLI commands contained in this guide. If the AWS CLI is not installed, you can download it from [AWS Command Line Interface](https://aws.amazon.com/cli/). If you are using Windows, you can download and run a 64-bit or 32-bit Windows installer. If you are using Linux or macOS, you can install the CLI using pip. # Configure the Client Amazon EC2 instance security groups for AWS CloudHSM When you launched an Amazon EC2 instance for your cluster in AWS CloudHSM, you associated it with a default Amazon VPC security group. This topic explains how to associate the cluster security group with the EC2 instance. This association allows the AWS CloudHSM client running on your EC2 instance to communicate with your HSMs. To connect your EC2 instance to your AWS CloudHSM cluster, you must properly configure the VPC default security group *and* associate the cluster security group with the instance. Use the following steps to complete the configuration changes. **Topics** + [ ## Step 1. Modify the default security group ](#configure-sg-client-instance-modify-default-security-group) + [ ## Step 2. Connect the Amazon EC2 instance to the AWS CloudHSM cluster ](#configure-sg-client-instance-connect-the-ec2-instance-to-the-HSM-cluster) ## Step 1. Modify the default security group You need to modify the default security group to permit the SSH or RDP connection so that you can download and install client software, and interact with your HSM. **To modify the default security group** 1. Open the **EC2 Dashboard** at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. Select **Instances (running)** and then select the check box next to the EC2 instance you want to install the AWS CloudHSM client. 1. Under the **Security** tab, choose the security group named **Default**. 1. At the top of the page, choose **Actions**, and then **Edit Inbound Rules**. 1. Select **Add Rule**. 1. For **Type**, do one of the following: + For a Windows Server Amazon EC2 instance, choose **RDP**. The port `3389` is automatically populated. + For a Linux Amazon EC2 instance, choose **SSH**. The port range `22` is automatically populated. 1. For either option, set **Source** to **My IP** to allow you to communicate with your Amazon EC2 instance. **Important** Do not specify 0.0.0.0/0 as the CIDR range to avoid allowing anyone to access your instance. 1. Choose **Save**. ## Step 2. Connect the Amazon EC2 instance to the AWS CloudHSM cluster You must attach the cluster security group to the EC2 instance so that the EC2 instance can communicate with HSMs in your cluster. The cluster security group contains a preconfigured rule that allows inbound communication over ports 2223-2225. **To connect the EC2 instance to the AWS CloudHSM cluster** 1. Open the **EC2 Dashboard** at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. Select **Instances (running)** and then select the check box for the EC2 instance on which you want to install the AWS CloudHSM client. 1. At the top of the page, choose **Actions**, **Security**, and then **Change Security Groups**. 1. Select the security group with the group name that matches your cluster ID, such as `cloudhsm-cluster--sg`. 1. Choose **Add Security Groups**. 1. Select **Save**. **Note** You can assign a maximum of five security groups to an Amazon EC2 instance. If you have reached the maximum limit, you must modify the default security group of the Amazon EC2 instance and the cluster security group: In the default security group, do the following: Add an inbound rule to permit traffic using the TCP protocol over ports `2223-2225` from the cluster security group. In the cluster security group, do the following: Add an inbound rule to permit traffic using the TCP protocol over ports `2223-2225` from the default security group. # Create an HSM in AWS CloudHSM After you create a cluster in AWS CloudHSM, you can create a hardware security module (HSM). However, before you can create an HSM in your cluster, the cluster must be in the uninitialized state. To determine the cluster's state, view the [clusters page in the AWS CloudHSM console](https://console.aws.amazon.com/cloudhsm/home), use the AWS CLI to run the **[describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html)** command, or send a [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) request in the AWS CloudHSM API. You can create an HSM from the [AWS CloudHSM console](https://console.aws.amazon.com/cloudhsm/), the [AWS CLI](https://aws.amazon.com/cli/), or the AWS CloudHSM API. **Important** Only create one HSM while your cluster is in the uninitialized state. ------ #### [ Console ] **To create an HSM (console)** 1. Open the AWS CloudHSM console at [https://console.aws.amazon.com/cloudhsm/home](https://console.aws.amazon.com/cloudhsm/home). 1. Select the radio button next to the ID of the cluster you want to create an HSM for. 1. Select **Actions**. From the drop down menu, choose **Initialize**. 1. Choose an Availability Zone (AZ) for the HSM that you are creating. 1. Select **Create**. After you create a cluster and HSM, you can optionally [verify the identity of the HSM](verify-hsm-identity.md), or proceed directly to [Initialize the cluster](initialize-cluster.md). ------ #### [ AWS CLI ] **To create an HSM ([AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/))** + At a command prompt, run the **[create-hsm](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/create-hsm.html)** command. Specify the cluster ID of the cluster that you created previously and an Availability Zone for the HSM. Specify the Availability Zone in the form of `us-west-2a`, `us-west-2b`, etc. ``` $ aws cloudhsmv2 create-hsm --cluster-id --availability-zone { "Hsm": { "HsmId": "hsm-ted36yp5b2x", "EniIp": "10.0.1.12", "EniIpV6": "2600:113f:404:be09:310e:ed34:3412:f733", "AvailabilityZone": "us-west-2a", "ClusterId": "cluster-igklspoyj5v", "EniId": "eni-5d7ade72", "SubnetId": "subnet-fd54af9b", "State": "CREATE_IN_PROGRESS" } } ``` After you create a cluster and HSM, you can optionally [verify the identity of the HSM](verify-hsm-identity.md), or proceed directly to [Initialize the cluster](initialize-cluster.md). ------ #### [ AWS CloudHSM API ] **To create an HSM (AWS CloudHSM API)** + Send a [https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateHsm.html](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateHsm.html) request. Specify the cluster ID of the cluster that you created previously and an Availability Zone for the HSM. After you create a cluster and HSM, you can optionally [verify the identity of the HSM](verify-hsm-identity.md), or proceed directly to [Initialize the cluster](initialize-cluster.md). ------ # Verify the identity and authenticity of your cluster's HSM in AWS CloudHSM (optional) To initialize your cluster in AWS CloudHSM, you sign a certificate signing request (CSR) generated by the cluster's first hardware security module (HSM). Before you do this, you might want to verify the identity and authenticity of the HSM. **Note** This process is optional. However, it works only until a cluster is initialized. After the cluster is initialized, you cannot use this process to get the certificates or verify the HSMs. To verify the identity of your cluster's first HSM, complete the following steps: 1. [Get the certificates and CSR](#get-certificates) – In this step, you get three certificates and a CSR from the HSM. You also get two root certificates, one from AWS CloudHSM and one from the HSM hardware manufacturer. 1. [Verify the certificate chains](#verify-certificate-chains) – In this step, you construct two certificate chains, one to the AWS CloudHSM root certificate and one to the manufacturer root certificate. Then you verify the HSM certificate with these certificate chains to determine that AWS CloudHSM and the hardware manufacturer both attest to the identity and authenticity of the HSM. 1. [Compare public keys](#compare-public-keys) – In this step, you extract and compare the public keys in the HSM certificate and the cluster CSR, to ensure that they are the same. This should give you confidence that the CSR was generated by an authentic, trusted HSM. The following diagram shows the CSR, the certificates, and their relationship to each other. The subsequent list defines each certificate. ![\[The HSM certificates and their relationships.\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/hsm-certificate-relationships.png) **AWS Root Certificate** This is AWS CloudHSM's root certificate. **Manufacturer Root Certificate** This is the hardware manufacturer's root certificate. **AWS Hardware Certificate** AWS CloudHSM created this certificate when the HSM hardware was added to the fleet. This certificate asserts that AWS CloudHSM owns the hardware. **Manufacturer Hardware Certificate** The HSM hardware manufacturer created this certificate when it manufactured the HSM hardware. This certificate asserts that the manufacturer created the hardware. **HSM Certificate** The HSM certificate is generated by the FIPS-validated hardware when you create the first HSM in the cluster. This certificate asserts that the HSM hardware created the HSM. **Cluster CSR** The first HSM creates the cluster CSR. When you [sign the cluster CSR](initialize-cluster.md#sign-csr), you claim the cluster. Then, you can use the signed CSR to [initialize the cluster](initialize-cluster.md#initialize). ## Step 1. Get certificates from the HSM To verify the identity and authenticity of your HSM, start by getting a CSR and five certificates. You get three of the certificates from the HSM, which you can do with the [AWS CloudHSM console](https://console.aws.amazon.com/cloudhsm/), the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), or the AWS CloudHSM API. ------ #### [ Console ] **To get the CSR and HSM certificates (console)** 1. Open the AWS CloudHSM console at [https://console.aws.amazon.com/cloudhsm/home](https://console.aws.amazon.com/cloudhsm/home). 1. Select the radio button next to the cluster ID with the HSM you want to verify. 1. Select **Actions**. From the drop down menu, choose **Initialize**. 1. If you did not complete the [previous step](create-hsm.md) to create an HSM, choose an Availability Zone (AZ) for the HSM that you are creating. Then select **Create**. 1. When the certificates and CSR are ready, you see links to download them. ![\[The download certificate signing request page in the AWS CloudHSM console.\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/download-csr-hsm-cert.png) 1. Choose each link to download and save the CSR and certificates. To simplify the subsequent steps, save all of the files to the same directory and use the default file names. ------ #### [ AWS CLI ] **To get the CSR and HSM certificates ([AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/))** + At a command prompt, run the **[describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html)** command four times, extracting the CSR and different certificates each time and saving them to files. 1. Issue the following command to extract the cluster CSR. Replace ** with the ID of the cluster that you created previously. ``` $ aws cloudhsmv2 describe-clusters --filters clusterIds= \ --output text \ --query 'Clusters[].Certificates.ClusterCsr' \ > _ClusterCsr.csr ``` 1. Issue the following command to extract the HSM certificate. Replace ** with the ID of the cluster that you created previously. ``` $ aws cloudhsmv2 describe-clusters --filters clusterIds= \ --output text \ --query 'Clusters[].Certificates.HsmCertificate' \ > _HsmCertificate.crt ``` 1. Issue the following command to extract the AWS hardware certificate. Replace ** with the ID of the cluster that you created previously. ``` $ aws cloudhsmv2 describe-clusters --filters clusterIds= \ --output text \ --query 'Clusters[].Certificates.AwsHardwareCertificate' \ > _AwsHardwareCertificate.crt ``` 1. Issue the following command to extract the manufacturer hardware certificate. Replace ** with the ID of the cluster that you created previously. ``` $ aws cloudhsmv2 describe-clusters --filters clusterIds= \ --output text \ --query 'Clusters[].Certificates.ManufacturerHardwareCertificate' \ > _ManufacturerHardwareCertificate.crt ``` ------ #### [ AWS CloudHSM API ] **To get the CSR and HSM certificates (AWS CloudHSM API)** + Send a [https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) request, then extract and save the CSR and certificates from the response. ------ ## Step 2. Get the root certificates Follow these steps to get the root certificates for AWS CloudHSM and the manufacturer. Save the root certificate files to the directory that contains the CSR and HSM certificate files. **To get the AWS CloudHSM and manufacturer root certificates** 1. Download the AWS CloudHSM root certificate: [AWS\$1CloudHSM\$1Root-G1.zip](samples/AWS_CloudHSM_Root-G1.zip) 1. Download the right manufacturer root certificate for your HSM type: + hsm1.medium manufacturer root certificate: [liquid\$1security\$1certificate.zip](https://www.marvell.com/content/dam/marvell/en/public-collateral/security-solutions/liquid_security_certificate.zip) + hsm2m.medium manufacturer root certificate: [liquid\$1security\$1certificate.zip](https://www.marvell.com/content/dam/marvell/en/public-collateral/security-solutions/liquidsecurity2_ar_v1.zip) **Note** To download each certificate from its landing page, use the following links: Landing page for hsm1.medium's [manufacturer root certificate](https://www.marvell.com/products/security-solutions/liquid-security-hsm-adapters-and-appliances/liquidsecurity-certificate.html) Landing page for hsm2m.medium's [manufacturer root certificate](https://www.marvell.com/products/security-solutions/nitrox-hs-adapters/liquidsecurity2-certificate-ls2-g-axxx-ar-f-bo-v1.html) You might need to right-click the **Download Certificate** link and then choose **Save Link As...** to save the certificate file. 1. After you download the files, extract (unzip) the contents. ## Step 3. Verify certificate chains In this step, you construct two certificate chains, one to the AWS CloudHSM root certificate and one to the manufacturer root certificate. Then use OpenSSL to verify the HSM certificate with each certificate chain. To create the certificate chains, open a Linux shell. You need OpenSSL, which is available in most Linux shells, and you need the [root certificate](#get-root-certificates) and [HSM certificate files](#get-certificates) that you downloaded. However, you do not need the AWS CLI for this step, and the shell does not need to be associated with your AWS account. **To verify the HSM certificate with the AWS CloudHSM root certificate** 1. Navigate to the directory where you saved the [root certificate](#get-root-certificates) and [HSM certificate files](#get-certificates) that you downloaded. The following commands assume that all of the certificates are in the current directory and use the default file names. Use the following command to create a certificate chain that includes the AWS hardware certificate and the AWS CloudHSM root certificate, in that order. Replace ** with the ID of the cluster that you created previously. ``` $ cat _AwsHardwareCertificate.crt \ AWS_CloudHSM_Root-G1.crt \ > _AWS_chain.crt ``` 1. Use the following OpenSSL command to verify the HSM certificate with the AWS certificate chain. Replace ** with the ID of the cluster that you created previously. ``` $ openssl verify -CAfile _AWS_chain.crt _HsmCertificate.crt _HsmCertificate.crt: OK ``` **To verify the HSM certificate with the manufacturer root certificate** 1. Use the following command to create a certificate chain that includes the manufacturer hardware certificate and the manufacturer root certificate, in that order. Replace ** with the ID of the cluster that you created previously. ``` $ cat _ManufacturerHardwareCertificate.crt \ liquid_security_certificate.crt \ > _manufacturer_chain.crt ``` 1. Use the following OpenSSL command to verify the HSM certificate with the manufacturer certificate chain. Replace ** with the ID of the cluster that you created previously. ``` $ openssl verify -CAfile _manufacturer_chain.crt _HsmCertificate.crt _HsmCertificate.crt: OK ``` ## Step 4. Extract and compare public keys Use OpenSSL to extract and compare the public keys in the HSM certificate and the cluster CSR, to ensure that they are the same. To compare the public keys, use your Linux shell. You need OpenSSL, which is available in most Linux shells, but you do not need the AWS CLI for this step. The shell does not need to be associated with your AWS account. **To extract and compare the public keys** 1. Use the following command to extract the public key from the HSM certificate. ``` $ openssl x509 -in _HsmCertificate.crt -pubkey -noout > _HsmCertificate.pub ``` 1. Use the following command to extract the public key from the cluster CSR. ``` $ openssl req -in _ClusterCsr.csr -pubkey -noout > _ClusterCsr.pub ``` 1. Use the following command to compare the public keys. If the public keys are identical, the following command produces no output. ``` $ diff _HsmCertificate.pub _ClusterCsr.pub ``` After you verify the identity and authenticity of the HSM, proceed to [Initialize the cluster](initialize-cluster.md). # Initialize the cluster in AWS CloudHSM After you create your cluster and add your hardware security module (HSM) in AWS CloudHSM, you can initialize the cluster. Complete the steps in the following topics to initialize your cluster. **Note** Before you initialize the cluster, review the process by which you can [verify the identity and authenticity of the HSMs](verify-hsm-identity.md). This process is optional and works only until a cluster is initialized. After the cluster is initialized, you cannot use this process to get your certificates or verify the HSMs. **Topics** + [ ## Overview ](#initialize-cluster-overview) + [ ## Step 1. Get the cluster CSR ](#get-csr) + [ ## Step 2. Create a private key for your Root CA ](#sign-csr-create-key) + [ ## Step 3. Sign the CSR ](#sign-csr) + [ ## Step 4. Initialize the cluster ](#initialize) ## Overview The cluster initialization process establishes your ownership and control over the cluster and your HSMs through a certificate-based authentication system. This process cryptographically proves that you are the sole owner of the HSMs in your cluster and creates the foundation of trust that will be required for all future connections to your HSMs. This page will show you how to do the following: + Retrieve your cluster's certificate signing request (CSR). + Generate and use the private key(s) to create a self-signed root certificate or a certificate chain. + Sign your cluster's CSR to produce a signed HSM certificate. + Initialize your cluster using the signed HSM certificate and self-signed certificate or certificate chain. When you're ready to get started, go to [Step 1. Get the cluster CSR](#get-csr). ## Step 1. Get the cluster CSR Before you can initialize the cluster, you must download and sign a certificate signing request (CSR) that is generated by the cluster's first HSM. If you followed the steps to [verify the identity of your cluster's HSM](verify-hsm-identity.md), you already have the CSR and you can sign it. Otherwise, get the CSR now by using the [AWS CloudHSM console](https://console.aws.amazon.com/cloudhsm/), the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), or the AWS CloudHSM API. ------ #### [ Console ] **To get the CSR (console)** 1. Open the AWS CloudHSM console at [https://console.aws.amazon.com/cloudhsm/home](https://console.aws.amazon.com/cloudhsm/home). 1. Select the radio button next to the cluster ID with the HSM you want to verify. 1. Select **Actions**. From the drop down menu, choose **Initialize**. 1. If you did not complete the [previous step](create-hsm.md) to create an HSM, choose an Availability Zone (AZ) for the HSM that you are creating. Then select **Create**. 1. When the CSR is ready, you see a link to download it. ![\[Download certificate signing request page in the AWS CloudHSM console.\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/download-csr-hsm-cert.png) 1. Choose **Cluster CSR** to download and save the CSR. ------ #### [ AWS CLI ] **To get the CSR ([AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/))** + At a command prompt, run the following **[describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html)** command, which extracts the CSR and saves it to a file. Replace ** with the ID of the cluster that you [created previously](create-cluster.md). ``` $ aws cloudhsmv2 describe-clusters --filters clusterIds= \ --output text \ --query 'Clusters[].Certificates.ClusterCsr' \ > _ClusterCsr.csr ``` ------ #### [ AWS CloudHSM API ] **To get the CSR (AWS CloudHSM API)** 1. Send a [https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) request. 1. Extract and save the CSR from the response. ------ ## Step 2. Create a private key for your Root CA **Note** For a production cluster, the key you are about to create should be created in a secure manner using a trusted source of randomness. We recommend that you use a secured offsite and offline HSM or the equivalent. Store the key safely. The key establishes the identity of the cluster and your sole control over the HSMs it contains. For development and testing, you can use any convenient tool (such as OpenSSL) to create and sign the cluster certificate. The following example shows you how to create a key. After you have used the key to create a self-signed certificate (see below), you should store it in a safe manner. To sign into your AWS CloudHSM instance, the certificate must be present, but the private key does not. The table below outlines the supported algorithms, key sizes, and curves for certificate generation. | Algorithms | Size/Curves | | --- | --- | | **RSA PKCSv1.5** | 2048, 3072, 4096 | | **RSA-PSS** | 2048, 3072, 4096 | | **ECDSA** | prime256v1, secp384r1, secp521r1 | | **Digest** | SHA-224, SHA-256, SHA-384, and SHA-512 | Use the following example command to create a private key for your self-signed Root CA. ``` $ openssl genrsa -aes256 -out customerRootCA.key 2048 Generating RSA private key, 2048 bit long modulus ........+++ ............+++ e is 65537 (0x10001) Enter pass phrase for customerRootCA.key: Verifying - Enter pass phrase for customerRootCA.key: ``` ## Step 3. Sign the CSR In the previous steps, you retrieved your cluster's CSR and created a private key for your root CA. In this step, you will use your private key to generate a signing certificate in order to sign your cluster's CSR. The topics below will guide you through the process of creating a single self-signed certificate, or a certificate chain, using OpenSSL. You do not need the AWS CLI for this step, and the shell does not need to be associated with your AWS account. **Important** To initialize your cluster, your trust anchor must comply with [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280) and meet the following requirements: If using X509v3 extensions, the X509v3 Basic Constraints extension must be present. The trust anchor must be a self-signed certificate. Extension values must not conflict with each other. Choose one of the following approaches to sign your cluster's CSR: ### Choose your certificate approach You must choose one of the following two approaches. Do not complete both approaches. **Option A: Single self-signed certificate** Create a single self-signed root certificate to sign your cluster's CSR. This is the most simple, direct method of establishing trust. **Recommended for:** + Environments where an external PKI is not required + Test and development environments where simplicity is preferred Go to: [Create a single self-signed certificate](#self-signed-certificate) **Option B: Certificate chain with intermediate CA** Create a certificate chain using an intermediate certificate authority. An intermediate certificate chain provides enhanced security, scalability, and flexibility by allowing root Certificate Authorities (CAs) to remain offline while delegating certificate issuance to intermediate CAs, thereby reducing the risk of compromising the root CA. **Recommended for:** + Environments where an external PKI is required + Integration with AWS Private Certificate Authority (PCA) **AWS PCA Integration Example:** You can use AWS Private Certificate Authority to create and manage your intermediate CA certificates. This provides automated certificate lifecycle management, including renewal and revocation, while maintaining the security benefits of keeping your root CA offline. For more information on AWS PCA, see the [AWS Private Certificate Authority User Guide](https://docs.aws.amazon.com/privateca/latest/userguide/PcaWelcome.html). Go to: [Create an intermediate certificate authority (ICA) chain](#certificate-chain) ### Create a single self-signed certificate The trusted hardware that you use to create the private key for your production cluster should also provide a software tool to generate a self-signed certificate using that key. The following example uses OpenSSL and the private key that you created in the previous step to create a self-signed root CA signing certificate. The certificate is valid for 10 years (3652 days). Read the on-screen instructions and follow the prompts. ``` $ openssl req -new -x509 -days 3652 -key customerRootCA.key -out customerRootCA.crt Enter pass phrase for customerRootCA.key: You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]: State or Province Name (full name) [Some-State]: Locality Name (eg, city) []: Organization Name (eg, company) [Internet Widgits Pty Ltd]: Organizational Unit Name (eg, section) []: Common Name (e.g. server FQDN or YOUR name) []: Email Address []: ``` This command creates a certificate file named `customerRootCA.crt`. Put this certificate on every host from which you will connect to your AWS CloudHSM cluster. If you give the file a different name or store it in a path other than the root of your host, you should edit your client configuration file accordingly. Use the certificate and the private key you just created to sign the cluster certificate signing request (CSR) in the next step. #### Sign the cluster CSR with your self-signed Root CA The trusted hardware that you use to create your private key for your production cluster should also provide a tool to sign the CSR using that key. The following example uses OpenSSL to sign the cluster's CSR. The example command below signs the CSR with the self-signed `customerRootCA.crt` ``` $ openssl x509 -req -days 3652 -in _ClusterCsr.csr \ -CA .crt \ -CAkey .key \ -CAcreateserial \ -out _CustomerHsmCertificate.crt Signature ok subject=/C=US/ST=CA/O=Cavium/OU=N3FIPS/L=SanJose/CN=HSM::PARTN:, for FIPS mode Getting CA Private Key Enter pass phrase for .key: ``` This command creates a file named `_CustomerHsmCertificate.crt`. Use this file as the signed certificate when you initialize the cluster. Verify the signed certificate against the root CA (optional): ``` $ openssl verify -purpose sslserver -CAfile customerRootCA.crt _CustomerHsmCertificate.crt _CustomerHsmCertificate.crt: OK ``` After producing the signed HSM certificate with your self-signed Root CA, go to [Step 4. Initialize the cluster](#initialize). ### Create an intermediate certificate authority (ICA) chain The following examples will walk you through creating a certificate chain of length 2, consisting of a root Certificate Authority (CA) and an intermediate CA. You'll first create a self-signed root CA certificate, then generate an intermediate CA that is signed by the root CA. Finally, you'll use the intermediate CA to sign your cluster's CSR, creating a complete trust chain from your HSM certificate back to the root CA. This approach provides enhanced security by keeping the root CA offline while using the intermediate CA for day-to-day certificate operations. **Important** To initialize your cluster with a certificate chain, your chain must meet the following requirements: The chain must be ordered, starting with the Intermediate CA that signs the cluster CSR. In this order, the first ICA should have an issuer that matches the subject of the next ICA in the chain, and so forth. Only the Root CA should be self-signed, meaning its issuer and subject should be identical. The chain must consist of no more than 4 certificates (including the Root CA at the end), and the total size of the chain must not exceed 16 kb (kilobytes). All Certificate Authorities (CAs) should conform to the [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280) guidelines. This section provides examples for creating an intermediate certificate authority chain using two different approaches: OpenSSL for local certificate generation, and AWS Private Certificate Authority (PCA) for managed certificate services. Choose the approach that best fits your environment and security requirements. **Note** The following examples are general use case and are both simplified, using the most basic configuration. For production environments, review additional configuration options and security requirements specific to your use case. ------ #### [ OpenSSL ] Create OpenSSL configuration file with common v3 extensions for CA: ``` $ cat > ca-extensions.conf < chainCA.crt -----BEGIN CERTIFICATE----- [Intermediate CA] -----END CERTIFICATE----- ... ... -----BEGIN CERTIFICATE----- [Root CA] -----END CERTIFICATE----- ``` Sign the cluster CSR with your intermediate CA: ``` $ openssl x509 -req -days 3652 -in _ClusterCsr.csr \ -CA intermediateCA.crt \ -CAkey intermediateCA.key \ -CAcreateserial \ -out _CustomerHsmCertificate.crt Signature ok subject=/C=US/ST=CA/O=Cavium/OU=N3FIPS/L=SanJose/CN=HSM::PARTN:, for FIPS mode Getting CA Private Key Enter pass phrase for intermediateCA.key: ``` ------ #### [ AWS PCA ] Create and activate a Root CA using AWS Private Certificate Authority: ``` $ # 1. Create Root CA aws acm-pca create-certificate-authority \ --certificate-authority-configuration \ "KeyAlgorithm=RSA_4096, SigningAlgorithm=SHA256WITHRSA, Subject={Country=US,Organization=MyOrg,OrganizationalUnit=IT,CommonName=RootCA}" \ --certificate-authority-type ROOT # Store the Root CA Authority ARN from the previous output ROOT_CA_AUTHORITY_ARN="arn:aws:acm-pca:::certificate-authority/" # 2. Generate Root CA CSR aws acm-pca get-certificate-authority-csr \ --certificate-authority-arn $ROOT_CA_AUTHORITY_ARN \ --output text > customerRootCA.csr # 3. Self-sign Root CA Certificate aws acm-pca issue-certificate \ --certificate-authority-arn $ROOT_CA_AUTHORITY_ARN \ --csr fileb://customerRootCA.csr \ --signing-algorithm SHA256WITHRSA \ --template-arn arn:aws:acm-pca:::template/RootCACertificate/V1 \ --validity Value=3652,Type=DAYS # Store the Root CA certificate ARN from the previous output ROOT_CA_ARN="arn:aws:acm-pca:::certificate-authority//certificate/" # 4. Retrieve the Root CA certificate aws acm-pca get-certificate \ --certificate-authority-arn $ROOT_CA_AUTHORITY_ARN \ --certificate-arn $ROOT_CA_ARN \ --output text > customerRootCA.crt # 5. Import the Root CA Certificate aws acm-pca import-certificate-authority-certificate \ --certificate-authority-arn $ROOT_CA_AUTHORITY_ARN \ --certificate fileb://customerRootCA.crt ``` Create and activate a subordinate CA (also known as an intermediate CA): ``` $ # 6. Create Subordinate CA aws acm-pca create-certificate-authority \ --certificate-authority-configuration \ "KeyAlgorithm=RSA_4096, SigningAlgorithm=SHA256WITHRSA, Subject={Country=US,Organization=MyOrg,OrganizationalUnit=IT,CommonName=SubordinateCA}" \ --certificate-authority-type SUBORDINATE # Store the Subordinate CA Authority ARN from the previous output SUB_CA_AUTHORITY_ARN="arn:aws:acm-pca:::certificate-authority/" # 7. Generate Subordinate CA CSR aws acm-pca get-certificate-authority-csr \ --certificate-authority-arn $SUB_CA_AUTHORITY_ARN \ --output text > intermediateCA.csr # 8. Issue Subordinate CA Certificate using Root CA aws acm-pca issue-certificate \ --certificate-authority-arn $ROOT_CA_AUTHORITY_ARN \ --csr fileb://intermediateCA.csr \ --signing-algorithm SHA256WITHRSA \ --template-arn arn:aws:acm-pca:::template/SubordinateCACertificate_PathLen0/V1 \ --validity Value=3651,Type=DAYS # Store the Subordinate CA certificate ARN from the previous output SUB_CA_ARN="arn:aws:acm-pca:::certificate-authority/" # 9. Retrieve Subordinate CA Certificate aws acm-pca get-certificate \ --certificate-authority-arn $ROOT_CA_AUTHORITY_ARN \ --certificate-arn $SUB_CA_ARN \ --query 'Certificate' \ --output text > intermediateCA.crt # 10. Import the Subordinate CA Certificate aws acm-pca import-certificate-authority-certificate \ --certificate-authority-arn $SUB_CA_AUTHORITY_ARN \ --certificate fileb://intermediateCA.crt \ --certificate-chain fileb://customerRootCA.crt ``` Combine the certificates into a chain file: ``` $ cat intermediateCA.crt customerRootCA.crt > chainCA.crt -----BEGIN CERTIFICATE----- [Intermediate CA] -----END CERTIFICATE----- ... ... -----BEGIN CERTIFICATE----- [Root CA] -----END CERTIFICATE----- ``` Sign the cluster CSR using AWS PCA: ``` $ aws acm-pca issue-certificate \ --certificate-authority-arn $SUB_CA_AUTHORITY_ARN \ --csr fileb://_ClusterCsr.csr \ --signing-algorithm SHA256WITHRSA \ --template-arn arn:aws:acm-pca:::template/EndEntityCertificate/V1 \ --validity Value=3650,Type=DAYS # Store your cluster's cert ARN from the previous output CLUSTER_CERT_ARN="arn:aws:acm-pca:::certificate-authority/" ``` Download the signed cluster certificate: ``` $ aws acm-pca get-certificate \ --certificate-authority-arn $SUB_CA_AUTHORITY_ARN \ --certificate-arn $CLUSTER_CERT_ARN \ --output text --query Certificate > _CustomerHsmCertificate.crt ``` ------ This command creates a file named `_CustomerHsmCertificate.crt`. Use this file as the signed certificate when you initialize the cluster. Verify the signed certificate against the certificate chain (optional): ``` $ openssl verify -purpose sslserver -CAfile chainCA.crt _CustomerHsmCertificate.crt _CustomerHsmCertificate.crt: OK ``` After producing the signed HSM certificate with your intermediate CA, go to [Step 4. Initialize the cluster](#initialize). ## Step 4. Initialize the cluster Use your signed HSM certificate and your signing certificate to initialize your cluster. You can use the [AWS CloudHSM console](https://console.aws.amazon.com/cloudhsm/), the [AWS CLI](https://aws.amazon.com/cli/), or the AWS CloudHSM API. ------ #### [ Console ] **To initialize a cluster (console)** 1. Open the AWS CloudHSM console at [https://console.aws.amazon.com/cloudhsm/home](https://console.aws.amazon.com/cloudhsm/home). 1. Select the radio button next to the cluster ID with the HSM you want to verify. 1. Select **Actions**. From the drop down menu, choose **Initialize**. 1. If you did not complete the [previous step](create-hsm.md) to create an HSM, choose an Availability Zone (AZ) for the HSM that you are creating. Then select **Create**. 1. On the **Download certificate signing request** page, choose **Next**. If **Next** is not available, first choose one of the CSR or certificate links. Then choose **Next**. 1. On the **Sign certificate signing request (CSR)** page, choose **Next**. 1. On the **Upload the certificates** page, do the following: 1. Next to **Cluster certificate**, choose **Upload file**. Then locate and select the HSM certificate that you signed previously. If you completed the steps in the previous section, select the file named `_CustomerHsmCertificate.crt`. 1. Next to **Issuing certificate**, choose **Upload file**. Then select your signing certificate based on the approach you chose: + **If you chose Option A (single self-signed certificate):** Select the file named `.crt` + **If you chose Option B (certificate chain):** Select the file named `.crt` 1. Choose **Upload and initialize**. ------ #### [ AWS CLI ] **To initialize a cluster ([AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/))** + At a command prompt, run the **[initialize-cluster](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/initialize-cluster.html)** command. Provide the following: + The ID of the cluster that you created previously. + The HSM certificate that you signed previously. If you completed the steps in the previous section, it's saved in a file named `_CustomerHsmCertificate.crt`. + Your signing certificate based on the approach you chose: + **If you chose Option A (single self-signed certificate):** Use the file named `.crt` + **If you chose Option B (certificate chain):** Use the file named `.crt` ``` $ aws cloudhsmv2 initialize-cluster --cluster-id \ --signed-cert file://_CustomerHsmCertificate.crt \ --trust-anchor file:// { "State": "INITIALIZE_IN_PROGRESS", "StateMessage": "Cluster is initializing. State will change to INITIALIZED upon completion." } ``` ------ #### [ AWS CloudHSM API ] **To initialize a cluster (AWS CloudHSM API)** + Send an [https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_InitializeCluster.html](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_InitializeCluster.html) request with the following: + The ID of the cluster that you created previously. + The HSM certificate that you signed previously. If you completed the steps in the previous section, it's saved in a file named `_CustomerHsmCertificate.crt`. + Your signing certificate based on the approach you chose: + **If you chose Option A (single self-signed certificate):** Use the file named `.crt` + **If you chose Option B (certificate chain):** Use the file named `.crt` ------ # Install and configure CloudHSM CLI To interact with the HSM in your AWS CloudHSM cluster, you need the CloudHSM CLI. Connect to your client instance and run the following commands to download and install the AWS CloudHSM command line tools. For more information, see [Launch an Amazon EC2 client instance for interacting with AWS CloudHSM](launch-client-instance.md). ------ #### [ Amazon Linux 2023 ] Amazon Linux 2023 on x86\$164 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-cli-latest.amzn2023.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-cli-latest.amzn2023.x86_64.rpm ``` Amazon Linux 2023 on ARM64 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-cli-latest.amzn2023.aarch64.rpm ``` ``` $ sudo yum install ./cloudhsm-cli-latest.amzn2023.aarch64.rpm ``` ------ #### [ Amazon Linux 2 ] Amazon Linux 2 on x86\$164 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-cli-latest.el7.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-cli-latest.el7.x86_64.rpm ``` Amazon Linux 2 on ARM64 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-cli-latest.el7.aarch64.rpm ``` ``` $ sudo yum install ./cloudhsm-cli-latest.el7.aarch64.rpm ``` ------ #### [ RHEL 10 (10.0\$1) ] RHEL 10 on x86\$164 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-cli-latest.el10.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-cli-latest.el10.x86_64.rpm ``` RHEL 10 on ARM64 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-cli-latest.el10.aarch64.rpm ``` ``` $ sudo yum install ./cloudhsm-cli-latest.el10.aarch64.rpm ``` ------ #### [ RHEL 9 (9.2\$1) ] RHEL 9 on x86\$164 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-cli-latest.el9.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-cli-latest.el9.x86_64.rpm ``` RHEL 9 on ARM64 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-cli-latest.el9.aarch64.rpm ``` ``` $ sudo yum install ./cloudhsm-cli-latest.el9.aarch64.rpm ``` ------ #### [ RHEL 8 (8.3\$1) ] RHEL 8 on x86\$164 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-cli-latest.el8.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-cli-latest.el8.x86_64.rpm ``` RHEL 8 on ARM64 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-cli-latest.el8.aarch64.rpm ``` ``` $ sudo yum install ./cloudhsm-cli-latest.el8.aarch64.rpm ``` ------ #### [ Ubuntu 24.04 LTS ] Ubuntu 24.04 LTS on x86\$164 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-cli_latest_u24.04_amd64.deb ``` ``` $ sudo apt install ./cloudhsm-cli_latest_u24.04_amd64.deb ``` Ubuntu 24.04 LTS on ARM64 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-cli_latest_u24.04_arm64.deb ``` ``` $ sudo apt install ./cloudhsm-cli_latest_u24.04_arm64.deb ``` ------ #### [ Ubuntu 22.04 LTS ] Ubuntu 22.04 LTS on x86\$164 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-cli_latest_u22.04_amd64.deb ``` ``` $ sudo apt install ./cloudhsm-cli_latest_u22.04_amd64.deb ``` Ubuntu 22.04 LTS on ARM64 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-cli_latest_u22.04_arm64.deb ``` ``` $ sudo apt install ./cloudhsm-cli_latest_u22.04_arm64.deb ``` ------ #### [ Windows Server 2022 ] For Windows Server 2022 on x86\$164 architecture, open PowerShell as an administrator and run the following command: ``` PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMCLI-latest.msi -Outfile C:\AWSCloudHSMCLI-latest.msi ``` ``` PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMCLI-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait ``` ------ #### [ Windows Server 2019 ] For Windows Server 2019 on x86\$164 architecture, open PowerShell as an administrator and run the following command: ``` PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMCLI-latest.msi -Outfile C:\AWSCloudHSMCLI-latest.msi ``` ``` PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMCLI-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait ``` ------ #### [ Windows Server 2016 ] For Windows Server 2016 on x86\$164 architecture, open PowerShell as an administrator and run the following command: ``` PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMCLI-latest.msi -Outfile C:\AWSCloudHSMCLI-latest.msi ``` ``` PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMCLI-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait ``` ------ Use the following commands to configure CloudHSM CLI. **To bootstrap a Linux EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of the HSM(s) in your cluster. ``` $ sudo /opt/cloudhsm/bin/configure-cli -a ``` **To bootstrap a Windows EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of the HSM(s) in your cluster. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" -a ``` # Activate the cluster in AWS CloudHSM When you activate an AWS CloudHSM cluster, the cluster's state changes from initialized to active. You can then [manage the hardware security module (HSM) users](manage-hsm-users.md) and [use the HSM](use-hsm.md). **Important** Before you can activate the cluster, you must first copy the issuing certificate to the default location for the platform on each EC2 instance that connects to the cluster (you create the issuing certificate when you initialize the cluster). Use the appropriate certificate file based on the approach you chose during cluster initialization: **If you chose Option A (single self-signed certificate):** Copy `customerRootCA.crt` **If you chose Option B (certificate chain):** Copy `chainCA.crt` **Linux location:** ``` /opt/cloudhsm/etc/ ``` **Windows location:** ``` C:\ProgramData\Amazon\CloudHSM\ ``` After copying the certificate file, edit the `/opt/cloudhsm/etc/cloudhsm-cli.cfg` file to ensure the certificate file name matches the name of the CA certificate you copied. After placing the issuing certificate, install CloudHSM CLI and run the [**cluster activate**](cloudhsm_cli-cluster-activate.md) command on your first HSM. You will notice the admin account on the first HSM in your cluster has the [unactivated-admin](understanding-users.md) role. This a temporary role that only exists prior to cluster activation. When you activate your cluster, the unactivated-admin role changes to admin. **To activate a cluster** 1. Connect to the client instance that you previously launched in. For more information, see [Launch an Amazon EC2 client instance for interacting with AWS CloudHSM](launch-client-instance.md). You can launch a Linux instance or a Windows Server. 1. Run the CloudHSM CLI in interactive mode. ------ #### [ Linux ] ``` $ /opt/cloudhsm/bin/cloudhsm-cli interactive ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" interactive ``` ------ 1. (Optional) Use the **user list** command to display the existing users. ``` aws-cloudhsm > user list { "error_code": 0, "data": { "users": [ { "username": "admin", "role": "unactivated-admin", "locked": "false", "mfa": [], "cluster-coverage": "full" }, { "username": "app_user", "role": "internal(APPLIANCE_USER)", "locked": "false", "mfa": [], "cluster-coverage": "full" } ] } } ``` 1. Use the **cluster activate** command to set the initial admin password. ``` aws-cloudhsm > cluster activate Enter password: Confirm password: { "error_code": 0, "data": "Cluster activation successful" } ``` We recommend that you write down the new password on a password worksheet. Do not lose the worksheet. We recommend that you print a copy of the password worksheet, use it to record your critical HSM passwords, and then store it in a secure place. We also recommended that you store a copy of this worksheet in secure off-site storage. 1. (Optional) Use the **user list** command to verify that the user's type changed to [admin/CO](understanding-users-cmu.md#crypto-officer). ``` aws-cloudhsm > user list { "error_code": 0, "data": { "users": [ { "username": "admin", "role": "admin", "locked": "false", "mfa": [], "cluster-coverage": "full" }, { "username": "app_user", "role": "internal(APPLIANCE_USER)", "locked": "false", "mfa": [], "cluster-coverage": "full" } ] } } ``` 1. Use the **quit** command to stop the CloudHSM CLI tool. ``` aws-cloudhsm > quit ``` For more information about working with CloudHSM CLI or the CMU, see [Understanding HSM Users](understanding-users.md) and [Understanding HSM User Management with CMU](understand-users.md). # Set up mutual TLS between client and AWS CloudHSM (recommended) The following topics describe the steps that you must complete to enable the mutual Transport Layer Security (mTLS) between client and AWS CloudHSM. **Considerations** + Currently this feature is exclusively available on hsm2m.medium. For more information about HSM type, see [AWS CloudHSM cluster modes](cluster-hsm-types.md). + mTLS is not supported for AWS CloudHSM key stores used with AWS Key Management Service. **Topics** + [ ## Step 1. Create and register a trust anchor onto the HSM ](#setup-mtls-create-and-register-trust-anchor) + [ ## Step 2. Enable mTLS for AWS CloudHSM ](#getting-start-setup-mtl-sdk) + [ ## Step 3. Set the mTLS enforcement for AWS CloudHSM ](#getting-start-setup-mtls-enforcement) ## Step 1. Create and register a trust anchor onto the HSM A trust anchor must be created and registered onto the HSM before enabling mTLS. This is a two-step process: **Topics** + [ ### Create a private key and self-signed root certificate ](#setup-mtls-create-trust-anchor) + [ ### Register the trust anchor onto the HSM ](#setup-mtls-register-trust-anchor) ### Create a private key and self-signed root certificate **Note** For a production cluster, the key you are about to create should be created in a secure manner using a trusted source of randomness. We recommend that you use a secured offsite and offline HSM or the equivalent. Store the key safely. For development and testing, you can use any convenient tool (such as OpenSSL) to create the key and self-sign a root certificate. You will need the key and root certificate to sign the client certificate in the [enable mTLS for AWS CloudHSM](#getting-start-setup-mtl-sdk). The following examples show how to create a private key and self-signed root certificate with [OpenSSL](https://www.openssl.org/). **Example – Create a private key with OpenSSL** Use the following command to create a 4096-bit RSA key encrypted with the AES-256 algorithm. To use this example, replace ** with the name of the file where you want to store the key. ``` $ openssl genrsa -out -aes256 4096 Generating RSA private key, 4096 bit long modulus .....................................+++ .+++ e is 65537 (0x10001) Enter pass phrase for mtls_ca_root_1.key: Verifying - Enter pass phrase for mtls_ca_root_1.key: ``` **Example – Create a self-signed root certificate with OpenSSL** Use the following command to create a self-signed root certificate named `mtls_ca_root_1.crt` from the private key you just created. The certificate is valid for 25 years (9130 days). Read the on-screen instructions and follow the prompts. ``` $ openssl req -new -x509 -days 9130 -key mtls_ca_root_1.key -out mtls_ca_root_1.crt Enter pass phrase for mtls_ca_root_1.key: You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]: State or Province Name (full name) [Some-State]: Locality Name (eg, city) []: Organization Name (eg, company) [Internet Widgits Pty Ltd]: Organizational Unit Name (eg, section) []: Common Name (e.g. server FQDN or YOUR name) []: Email Address []: ``` ### Register the trust anchor onto the HSM After creating a self-signed root certificate, the admin must register it as the trust anchor with the AWS CloudHSM cluster. **To register a trust anchor with the HSM** 1. Use the following command to start CloudHSM CLI: ------ #### [ Linux ] ``` $ /opt/cloudhsm/bin/cloudhsm-cli interactive ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" interactive ``` ------ 1. Using CloudHSM CLI, log in as an admin. ``` aws-cloudhsm > login --username --role admin Enter password: { "error_code": 0, "data": { "username": "", "role": "admin" } } ``` 1. Use the ** [Register a trust anchor with CloudHSM CLI](cloudhsm_cli-cluster-mtls-register-trust-anchor.md) ** command to register the trust anchor. For more information, see the following example or use the **help cluster mtls register-trust-anchor** command. **Example – Register a trust anchor with AWS CloudHSM cluster** The following example shows how to use the **cluster mtls register-trust-anchor** command in CloudHSM CLI to register an trust anchor onto the HSM. To use this command, the admin must be logged in to the HSM. Replace these values with your own: ``` aws-cloudhsm > cluster mtls register-trust-anchor --path { "error_code": 0, "data": { "trust_anchor": { "certificate-reference": "0x01", "certificate": "", "cluster-coverage": "full" } } } ``` AWS CloudHSM supports registering intermediate certificates as trust anchor. In such cases, the entire PEM-encoded certificate chain file needs to be registered onto the HSM, with the certificates in hierarchical order. AWS CloudHSM supports a certificate chain of 6980 bytes. After successfully registering the trust anchor, you can run the **cluster mtls list-trust-anchors** command to check the current registered trust anchors, as shown below: ``` aws-cloudhsm > cluster mtls list-trust-anchors { "error_code": 0, "data": { "trust_anchors": [ { "certificate-reference": "0x01", "certificate": "", "cluster-coverage": "full" } ] } } ``` The maximum number of trust anchors can be registered onto hsm2m.medium is two (2). ## Step 2. Enable mTLS for AWS CloudHSM To enable the mTLS for AWS CloudHSM, you need to create a private key and a client certificate signed by the root certificate we generated in [Create and register a trust anchor onto the HSM](#setup-mtls-create-and-register-trust-anchor), and then use any of the Client SDK 5 configure tool to setup the private key path and client certificate chain path. **Topics** + [ ### Create a private key and client certificate chain ](#create-client-ssl) + [ ### Configure mTLS for Client SDK 5 ](#enable-ssl-5) ### Create a private key and client certificate chain **Example – Create a private key with OpenSSL** Use the following command to create a 4096-bit RSA key. To use this example, replace ** with the name of the file where you want to store the key. ``` $ openssl genrsa -out 4096 Generating RSA private key, 4096 bit long modulus .....................................+++ .+++ e is 65537 (0x10001) ``` **Example – Generate a certificate signing request (CSR) with OpenSSL** Use the following command to generate a certificate signing request (CSR) from the private key you just created. Read the on-screen instructions and follow the prompts. ``` $ openssl req -new -key -out You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]: State or Province Name (full name) [Some-State]: Locality Name (eg, city) []: Organization Name (eg, company) [Internet Widgits Pty Ltd]: Organizational Unit Name (eg, section) []: Common Name (e.g. server FQDN or YOUR name) []: Email Address []: ``` **Example – Sign the CSR with the root certificate** Use the following command to sign the CSR with the root certificate we created and registered in [Create and register a trust anchor onto the HSM](#setup-mtls-create-and-register-trust-anchor) and create a client certificate named `ssl-client.crt`. The certificate is valid for 5 years (1826 days). ``` $ openssl x509 -req -days 1826 -in -CA -CAkey -CAcreateserial -out ``` **Example – Create a client certificate chain** Use the following command to combine the client certificate and root certificate we created and registered in [Create and register a trust anchor onto the HSM](#setup-mtls-create-and-register-trust-anchor) and create a client certificate chain named `ssl-client.pem`, which will be used to configure in next step. ``` $ cat > ``` If you registered intermediate certificates in [Create and register a trust anchor onto the HSM](#setup-mtls-create-and-register-trust-anchor) as trust anchor, make sure to combine the client certificate with the entire certificate chain to create a client certificate chain. ### Configure mTLS for Client SDK 5 Use any of the Client SDK 5 configure tools to enable the mutual TLS by providing the right client key path and client certificate chain path. For more information about configure tool for Client SDK 5, see [AWS CloudHSM Client SDK 5 configure tool](configure-sdk-5.md) . ------ #### [ PKCS \$111 library ] **To use a custom certificate and key for TLS client-HSM mutual authentication with Client SDK 5 on Linux** 1. Copy your key and certificate to the appropriate directory. ``` $ sudo cp ssl-client.pem $ sudo cp ssl-client.key ``` 1. Use the configure tool to specify `ssl-client.pem` and `ssl-client.key`. ``` $ sudo /opt/cloudhsm/bin/configure-pkcs11 \ --client-cert-hsm-tls-file \ --client-key-hsm-tls-file ``` **To use a custom certificate and key for TLS client-HSM mutual authentication with Client SDK 5 on Windows** 1. Copy your key and certificate to the appropriate directory. ``` cp ssl-client.pem cp ssl-client.key ``` 1. With a PowerShell interpreter, use the configure tool to specify `ssl-client.pem` and `ssl-client.key`. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" ` --client-cert-hsm-tls-file ` --client-key-hsm-tls-file ``` ------ #### [ OpenSSL Dynamic Engine ] **To use a custom certificate and key for TLS client-HSM mutual authentication with Client SDK 5 on Linux** 1. Copy your key and certificate to the appropriate directory. ``` $ sudo cp ssl-client.pem sudo cp ssl-client.key ``` 1. Use the configure tool to specify `ssl-client.pem` and `ssl-client.key`. ``` $ sudo /opt/cloudhsm/bin/configure-dyn \ --client-cert-hsm-tls-file \ --client-key-hsm-tls-file ``` ------ #### [ Key Storage Provider (KSP) ] **To use a custom certificate and key for TLS client-HSM mutual authentication with Client SDK 5 on Windows** 1. Copy your key and certificate to the appropriate directory. ``` cp ssl-client.pem cp ssl-client.key ``` 1. With a PowerShell interpreter, use the configure tool to specify `ssl-client.pem` and `ssl-client.key`. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" ` --client-cert-hsm-tls-file ` --client-key-hsm-tls-file ``` ------ #### [ JCE provider ] **To use a custom certificate and key for TLS client-HSM mutual authentication with Client SDK 5 on Linux** 1. Copy your key and certificate to the appropriate directory. ``` $ sudo cp ssl-client.pem sudo cp ssl-client.key ``` 1. Use the configure tool to specify `ssl-client.pem` and `ssl-client.key`. ``` $ sudo /opt/cloudhsm/bin/configure-jce \ --client-cert-hsm-tls-file \ --client-key-hsm-tls-file ``` **To use a custom certificate and key for TLS client-HSM mutual authentication with Client SDK 5 on Windows** 1. Copy your key and certificate to the appropriate directory. ``` cp ssl-client.pem cp ssl-client.key ``` 1. With a PowerShell interpreter, use the configure tool to specify `ssl-client.pem` and `ssl-client.key`. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" ` --client-cert-hsm-tls-file ` --client-key-hsm-tls-file ``` ------ #### [ CloudHSM CLI ] **To use a custom certificate and key for TLS client-HSM mutual authentication with Client SDK 5 on Linux** 1. Copy your key and certificate to the appropriate directory. ``` $ sudo cp ssl-client.pem sudo cp ssl-client.key ``` 1. Use the configure tool to specify `ssl-client.pem` and `ssl-client.key`. ``` $ sudo /opt/cloudhsm/bin/configure-cli \ --client-cert-hsm-tls-file \ --client-key-hsm-tls-file ``` **To use a custom certificate and key for TLS client-HSM mutual authentication with Client SDK 5 on Windows** 1. Copy your key and certificate to the appropriate directory. ``` cp ssl-client.pem cp ssl-client.key ``` 1. With a PowerShell interpreter, use the configure tool to specify `ssl-client.pem` and `ssl-client.key`. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" ` --client-cert-hsm-tls-file ` --client-key-hsm-tls-file ``` ------ ## Step 3. Set the mTLS enforcement for AWS CloudHSM After configuring with any of the Client SDK 5 configure tools, connection between client and AWS CloudHSM will be mutual TLS in the cluster. However, removing the private key path and client certificate chain path from the config file will turn the connection into regular TLS again. You can use CloudHSM CLI to set the mtls enforcement in the cluster by completing the following steps: 1. Use the following command to start CloudHSM CLI: ------ #### [ Linux ] ``` $ /opt/cloudhsm/bin/cloudhsm-cli interactive ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" interactive ``` ------ 1. Using CloudHSM CLI, log in as an admin. ``` aws-cloudhsm > login --username --role admin Enter password: { "error_code": 0, "data": { "username": "", "role": "admin" } } ``` **Note** 1. Make sure you have configured the CloudHSM CLI and start the CloudHSM CLI under a mTLS connection. 2. You must be logged in as the default admin user with username as **admin** before set mTLS enforcement. 1. Use the ** [Set the mTLS enforcement level with CloudHSM CLI](cloudhsm_cli-cluster-mtls-set-enforcement.md) ** command to set the enforcement. For more information, see the following example or use the **help cluster mtls set-enforcement** command. **Example – Set mTLS enforcement with AWS CloudHSM cluster** The following example shows how to use the **cluster mtls set-enforcement** command in CloudHSM CLI to set the mTLS enforcement with the HSM. To use this command, the admin with username as admin must be logged in to the HSM. ``` aws-cloudhsm > cluster mtls set-enforcement --level cluster { "error_code": 0, "data": { "message": "Mtls enforcement level set to Cluster successfully" } } ``` **Warning** After you enforce mTLS usage in the cluster, all existing non-mTLS connections will be dropped and you can only connect to the cluster with mTLS certificates. # Create and use keys in AWS CloudHSM Before you can create and use keys in your new cluster, create a hardware security module (HSM) user with the AWS CloudHSM CLI For more information, see [Understanding HSM User Management Tasks](understand-users.md), [Getting started with AWS CloudHSM Command Line Interface (CLI)](cloudhsm_cli-getting-started.md), and [How to Manage HSM Users](manage-hsm-users.md). **Note** If using Client SDK 3, use [CloudHSM Management Utility (CMU)](cloudhsm_mgmt_util.md) instead of CloudHSM CLI. After you create HSM users, you can sign in to the HSM and manage keys using any of these options: + Use [key management utility, a command line tool](key_mgmt_util-getting-started.md) + Build a C application using the [PKCS \$111 library](pkcs11-library.md) + Build a Java application using the [JCE provider](java-library.md) + Use the [OpenSSL Dynamic Engine directly from the command line](openssl-library.md) + Use the OpenSSL Dynamic Engine for TLS offload with [NGINX and Apache web servers](ssl-offload.md) + Use the Key Storage Provider (KSP) for AWS CloudHSM with [Microsoft Windows Server Certificate Authority (CA)](win-ca-overview-sdk5.md) + Use the Key Storage Provider (KSP) for AWS CloudHSM with [Microsoft Sign Tool](signtool-sdk5.md) + Use the Key Storage Provider (KSP) for TLS offload with [Internet Information Server (IIS) web server](ssl-offload.md)