Initialize the cluster in AWS CloudHSM - AWS CloudHSM

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. 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.

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, you already have the CSR and you can sign it. Otherwise, get the CSR now by using the AWS CloudHSM console, the AWS Command Line Interface (AWS CLI), or the AWS CloudHSM API.

Important

To initialize your cluster, your trust anchor must comply with RFC 5280 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.

Console
To get the CSR (console)
  1. Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/home.

  2. Select the radio button next to the cluster ID with the HSM you want to verify.

  3. Select Actions. From the drop down menu, choose Initialize.

  4. If you did not complete the previous step to create an HSM, choose an Availability Zone (AZ) for the HSM that you are creating. Then select Create.

  5. When the CSR is ready, you see a link to download it.

    Download certificate signing request page in the AWS CloudHSM console.
  6. Choose Cluster CSR to download and save the CSR.

AWS CLI
To get the CSR (AWS CLI)
  • At a command prompt, run the following describe-clusters command, which extracts the CSR and saves it to a file. Replace <cluster ID> with the ID of the cluster that you created previously.

    $ aws cloudhsmv2 describe-clusters --filters clusterIds=<cluster ID> \ --output text \ --query 'Clusters[].Certificates.ClusterCsr' \ > <cluster ID>_ClusterCsr.csr
AWS CloudHSM API
To get the CSR (AWS CloudHSM API)
  1. Send a DescribeClusters request.

  2. Extract and save the CSR from the response.

Step 2. Sign the CSR

Currently, you must create a self-signed signing certificate and use it to sign the CSR for your cluster. You do not need the AWS CLI for this step, and the shell does not need to be associated with your AWS account. To sign the CSR, you must do the following:

  1. Complete the previous section (see Step 1. Get the cluster CSR).

  2. Create a private key.

  3. Use the private key to create a signing certificate.

  4. Sign your cluster CSR.

Create a private key

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.

Use the following command to create a private key. When initializing an AWS CloudHSM cluster, you must use the RSA 2048 certificate or the RSA 4096 certificate.

$ openssl genrsa -aes256 -out customerCA.key 2048 Generating RSA private key, 2048 bit long modulus ........+++ ............+++ e is 65537 (0x10001) Enter pass phrase for customerCA.key: Verifying - Enter pass phrase for customerCA.key:

Use the private key to create a 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 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 customerCA.key -out customerCA.crt Enter pass phrase for customerCA.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 customerCA.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

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 uses your private key and the self-signed certificate that you created in the previous step.

$ openssl x509 -req -days 3652 -in <cluster ID>_ClusterCsr.csr \ -CA customerCA.crt \ -CAkey customerCA.key \ -CAcreateserial \ -out <cluster ID>_CustomerHsmCertificate.crt Signature ok subject=/C=US/ST=CA/O=Cavium/OU=N3FIPS/L=SanJose/CN=HSM:<HSM identifer>:PARTN:<partition number>, for FIPS mode Getting CA Private Key Enter pass phrase for customerCA.key:

This command creates a file named <cluster ID>_CustomerHsmCertificate.crt. Use this file as the signed certificate when you initialize the cluster.

Step 3. Initialize the cluster

Use your signed HSM certificate and your signing certificate to initialize your cluster. You can use the AWS CloudHSM console, the AWS 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.

  2. Select the radio button next to the cluster ID with the HSM you want to verify.

  3. Select Actions. From the drop down menu, choose Initialize.

  4. If you did not complete the previous step to create an HSM, choose an Availability Zone (AZ) for the HSM that you are creating. Then select Create.

  5. 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.

  6. On the Sign certificate signing request (CSR) page, choose Next.

  7. 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 <cluster ID>_CustomerHsmCertificate.crt.

    2. Next to Issuing certificate, choose Upload file. Then select your signing certificate. If you completed the steps in the previous section, select the file named customerCA.crt.

    3. Choose Upload and initialize.

AWS CLI
To initialize a cluster (AWS CLI)
  • At a command prompt, run the initialize-cluster 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 <cluster ID>_CustomerHsmCertificate.crt.

    • Your signing certificate. If you completed the steps in the previous section, the signing certificate is saved in a file named customerCA.crt.

    $ aws cloudhsmv2 initialize-cluster --cluster-id <cluster ID> \ --signed-cert file://<cluster ID>_CustomerHsmCertificate.crt \ --trust-anchor file://customerCA.crt { "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 InitializeCluster request with the following:

    • The ID of the cluster that you created previously.

    • The HSM certificate that you signed previously.

    • Your signing certificate.