Step 2: Generate or Import a Private Key and SSL/TLS Certificate - AWS CloudHSM

Step 2: Generate or Import a Private Key and SSL/TLS Certificate

To enable HTTPS, your web server application (NGINX or Apache) needs a private key and a corresponding SSL/TLS certificate. To use web server SSL/TLS offload with AWS CloudHSM, you must store the private key in an HSM in your AWS CloudHSM cluster. You can accomplish this in one of the following ways:

  • If you don't yet have a private key and a corresponding certificate, you generate a private key in a HSM. You use the private key to create a certificate signing request (CSR), which you use to create the SSL/TLS certificate.

  • If you already have a private key and corresponding certificate, you import the private key into a HSM.

Regardless of which of the preceding methods you choose, you export a fake PEM private key from the HSM and save it to a file. This file contains a reference to the private key stored on the HSM (it's not the actual private key). Your web server uses the fake PEM private key to offload SSL/TLS processing to the HSM.

Generate a Private Key and Certificate

If you don't have a private key and a corresponding SSL/TLS certificate to use for HTTPS, you can generate a private key on an HSM. You can then you use the private key to create a certificate signing request (CSR). Sign the CSR to create the certificate.

To generate a private key on an HSM

  1. Connect to your client instance.

  2. Set an environment variable that contains the credentials of the cryptographic user (CU):

    Amazon Linux
    export n3fips_password=<CU user name>:<password>

    Replace <CU user name> and <password> with the CU credentials.

    Amazon Linux 2
    export n3fips_password=<CU user name>:<password>

    Replace <CU user name> and <password> with the CU credentials.

    CentOS 7
    export n3fips_password=<CU user name>:<password>

    Replace <CU user name> and <password> with the CU credentials.

    CentOS 8
    export CLOUDHSM_PIN=<CU user name>:<password>

    Replace <CU user name> and <password> with the CU credentials.

    Note

    Client SDK 5 introduces the CLOUDHSM_PIN environment variable for storing the credentials of the CU. In Client SDK 3 you stored the CU credentials in the n3fips_password environment variable. Client SDK 5 supports both environment variables, but we recommend using CLOUDHSM_PIN.

    Red Hat 7
    export n3fips_password=<CU user name>:<password>

    Replace <CU user name> and <password> with the CU credentials.

    Red Hat 8
    export CLOUDHSM_PIN=<CU user name>:<password>

    Replace <CU user name> and <password> with the CU credentials.

    Note

    Client SDK 5 introduces the CLOUDHSM_PIN environment variable for storing the credentials of the CU. In Client SDK 3 you stored the CU credentials in the n3fips_password environment variable. Client SDK 5 supports both environment variables, but we recommend using CLOUDHSM_PIN.

    Ubuntu 16.04 LTS
    export n3fips_password=<CU user name>:<password>

    Replace <CU user name> and <password> with the CU credentials.

    Ubuntu 18.04 LTS
    export CLOUDHSM_PIN=<CU user name>:<password>

    Replace <CU user name> and <password> with the CU credentials.

    Note

    Client SDK 5 introduces the CLOUDHSM_PIN environment variable for storing the credentials of the CU. In Client SDK 3 you stored the CU credentials in the n3fips_password environment variable. Client SDK 5 supports both environment variables, but we recommend using CLOUDHSM_PIN.

  3. Run the following command to use the AWS CloudHSM dynamic engine for OpenSSL to generate a private key on an HSM. This command also exports the fake PEM private key and saves it in a file. Replace <web_server_fake_PEM.key> with the file name you want to use for the exported fake PEM private key.

    openssl genrsa -engine cloudhsm -out <web_server_fake_PEM.key> 2048

To create a CSR

Run the following command to use the AWS CloudHSM dynamic engine for OpenSSL to create a certificate signing request (CSR). Replace <web_server_fake_PEM.key> with the name of the file that contains your fake PEM private key. Replace <web_server.csr> with the name of the file that contains your CSR.

The req command is interactive. Respond to each field. The field information is copied into your SSL/TLS certificate.

openssl req -engine cloudhsm -new -key <web_server_fake_PEM.key> -out <web_server.csr>

In a production environment, you typically use a certificate authority (CA) to create a certificate from a CSR. A CA is not necessary for a test environment. If you do use a CA, send the CSR file (<web_server.csr>) to it and use the CA create a signed SSL/TLS certificate. Your web server uses the signed certificate for HTTPS.

As an alternative to using a CA, you can use the AWS CloudHSM dynamic engine for OpenSSL to create a self-signed certificate. Self-signed certificates are not trusted by browsers and should not be used in production environments. They can be used in test environments.

Warning

Self-signed certificates should be used in a test environment only. For a production environment, use a more secure method such as a certificate authority to create a certificate.

To create a self-signed certificate

Run the following command to use the AWS CloudHSM dynamic engine for OpenSSL to sign your CSR with your private key on your HSM. This creates a self-signed certificate. Replace the following values in the command with your own.

  • <web_server.csr> – Name of the file that contains the CSR.

  • <web_server_fake_PEM.key> – Name of the file that contains the fake PEM private key.

  • <web_server.crt> – Name of the file that will contain your web server certificate.

openssl x509 -engine cloudhsm -req -days 365 -in <web_server.csr> -signkey <web_server_fake_PEM.key> -out <web_server.crt>

After you complete these steps, go to Step 3: Configure the Web Server.

Import an Existing Private Key with Client SDK 3

You might already have a private key and a corresponding SSL/TLS certificate that you use for HTTPS on your web server. If so, you can import that key into an HSM by following the steps in this section.

Note

Some notes on private key imports and Client SDK compatibility:

  • Importing an existing private key requires Client SDK 3.

  • You can use private keys from Client SDK 3 with Client SDK 5.

  • OpenSSL Dynamic Engine for Client SDK 3 does not support the latest Linux platforms, but the implementation of OpenSSL Dynamic Engine for Client SDK 5 does. You can import an existing private key using the key management tool provided with Client SDK 3, then use that private key and the implementation of OpenSSL Dynamic Engine with Client SDK 5 to support SSL/TLS offload on the latest Linux platforms such as, Red Hat 8, CentOS 8, and Ubuntu 18.04 LTS.

To import an existing private key into an HSM with Client SDK 3

  1. Connect to your Amazon EC2 client instance. If necessary, copy your existing private key and certificate to the instance.

  2. Run the following command to start the AWS CloudHSM client.

    Amazon Linux
    $ sudo start cloudhsm-client
    Amazon Linux 2
    $ sudo service cloudhsm-client start
    CentOS 7
    $ sudo service cloudhsm-client start
    CentOS 8
    $ sudo service cloudhsm-client start
    RHEL 7
    $ sudo service cloudhsm-client start
    RHEL 8
    $ sudo service cloudhsm-client start
    Ubuntu 16.04 LTS
    $ sudo service cloudhsm-client start
    Ubuntu 18.04 LTS
    $ sudo service cloudhsm-client start
  3. Run the following command to start the key_mgmt_util command line tool.

    /opt/cloudhsm/bin/key_mgmt_util
  4. Run the following command to log in to the HSM. Replace <user name> and <password> with the user name and password of the cryptographic user (CU).

    loginHSM -u CU -s <user name> -p <password>
  5. Run the following commands to import your private key into an HSM.

    1. Run the following command to create a symmetric wrapping key that is valid for the current session only. The command and output are shown.

      genSymKey -t 31 -s 16 -sess -l wrapping_key_for_import Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS Symmetric Key Created. Key Handle: 6 Cluster Error Status Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
    2. Run the following command to import your existing private key into an HSM. The command and output are shown. Replace the following values with your own:

      • <web_server_existing.key> – Name of the file that contains your private key.

      • <web_server_imported_key> – Label for your imported private key.

      • <wrapping_key_handle> – Wrapping key handle generated by the preceding command. In the previous example, the wrapping key handle is 6.

      importPrivateKey -f <web_server_existing.key> -l <web_server_imported_key> -w <wrapping_key_handle> BER encoded key length is 1219 Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS Private Key Unwrapped. Key Handle: 8 Cluster Error Status Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
  6. Run the following command to export the private key in fake PEM format and save it to a file. Replace the following values with your own.

    • <private_key_handle> – Handle of the imported private key. This handle was generated by the second command in the preceding step. In the preceding example, the handle of the private key is 8.

    • <web_server_fake_PEM.key> – Name of the file that contains your exported fake PEM private key.

    getCaviumPrivKey -k <private_key_handle> -out <web_server_fake_PEM.key>
  7. Run the following command to stop key_mgmt_util.

    exit

After you complete these steps, go to Step 3: Configure the Web Server.