Create and register a trust anchor onto the HSM Enable mTLS for AWS CloudHSM Set the mTLS enforcement for AWS CloudHSM

Setup mutual TLS between client and AWS CloudHSM (recommended)

The following topics describe the steps that you must complete to enable the mutual TLS (mTLS) between client and AWS CloudHSM. Currently this feature is exclusively available on hsm2m.medium. For more information about HSM type, see AWS CloudHSM cluster modes and HSM types .

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:

Create a private key and self-signed root certificate
Register the trust anchor onto the HSM

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.

The following examples show how to create a private key and self-signed root certificate with OpenSSL.

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 <mtls_ca_root_1.key> with the name of the file where you want to store the key.


$ openssl genrsa -out <mtls_ca_root_1.key> -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

Use the following command to start CloudHSM CLI:

Using CloudHSM CLI, log in as an admin.


aws-cloudhsm > login --username admin --role admin
Enter password:
{
  "error_code": 0,
  "data": {
    "username": "admin",
    "role": "admin"
  }
}

Use the cluster mtls register-trust-anchor 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 </path/mtls_ca_root_1.crt>

{
  "error_code": 0,
  "data": {
    "trust_anchor": {
      "certificate-reference": "0x01",
      "certificate": "<PEM Encoded Certificate>",
      "cluster-coverage": "full"
    }
  }
}

Note

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 length 4 with 2048-bit RSA key, certificate chain of length 3 with 3072-bit RSA key, certificate chain of length 3 with 4096-bit RSA key, and certificate chain of length 6 with EC key.

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": "<PEM Encoded Certificate>",
        "cluster-coverage": "full"
      }
    ]
  }
}

Note

The maximum number of trust anchors can be registered onto hsm2m.medium is two (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, and then use any of the Client SDK 5 configure tool to setup the private key path and client certificate chain path.

Create a private key and client certificate chain
Configure mTLS for Client SDK 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 encrypted with the AES-256 algorithm. To use this example, replace <ssl-client.key> with the name of the file where you want to store the key.


$ openssl genrsa -out <ssl-client.key> -aes256 4096

Generating RSA private key, 4096 bit long modulus
.....................................+++
.+++
e is 65537 (0x10001)
Enter pass phrase for ssl-client.key:
Verifying - Enter pass phrase for ssl-client.key:

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 <ssl-client.key> -out <ssl-client.csr>
Enter pass phrase for ssl-client.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 []:

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 and create a client certificate named ssl-client.crt. The certificate is valid for 5 years (1826 days).


$ openssl x509 -req -days 1826 -in <ssl-client.csr> -CA <mtls_ca_root_1.crt> -CAkey <mtls_ca_root_1.key> -CAcreateserial -out <ssl-client.crt>

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 and create a client certificate chain named ssl-client.pem, which will be used to configure in next step.


$ cat <ssl-client.crt> <mtls_ca_root_1.crt> > <ssl-client.pem>

Note

If you registered intermediate certificates in Create and register a trust anchor onto the HSM 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 Client SDK 5 configure tool .

PKCS #11 library