Install and Use the AWS CloudHSM Dynamic Engine for OpenSSL - AWS CloudHSM

Install and Use the AWS CloudHSM Dynamic Engine for OpenSSL

This topic provides OpenSSL Dynamic Engine installation instruction for Client SDK 5 and Client SDK 3. For more information about the Client SDK or OpenSSL Dynamic Engine, see Using the Client SDK and OpenSSL Dynamic Engine.

Client SDK 3 Install

Before you can use the AWS CloudHSM dynamic engine for OpenSSL, you need the AWS CloudHSM client.

The client is a daemon that establishes end-to-end encrypted communication with the HSMs in your cluster, and the OpenSSL engine communicates locally with the client. If you haven't installed and configured the AWS CloudHSM client package, do that now by following the steps at Install the Client (Linux). After you install and configure the client, use the following command to start it.

The AWS CloudHSM dynamic engine for OpenSSL is supported only on Linux and compatible operating systems.

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

Complete the following steps to install and configure the AWS CloudHSM dynamic engine for OpenSSL. It is supported only on Linux and compatible operating systems.

Note

For upgrading, see Client Upgrade.

To install and configure the OpenSSL engine

  1. Use the following commands to download and install the OpenSSL engine.

    Amazon Linux
    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-dyn-latest.el6.x86_64.rpm
    $ sudo yum install ./cloudhsm-client-dyn-latest.el6.x86_64.rpm
    Amazon Linux 2
    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-dyn-latest.el7.x86_64.rpm
    $ sudo yum install ./cloudhsm-client-dyn-latest.el7.x86_64.rpm
    CentOS 6
    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-dyn-latest.el6.x86_64.rpm
    $ sudo yum install ./cloudhsm-client-dyn-latest.el6.x86_64.rpm
    CentOS 7
    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-dyn-latest.el7.x86_64.rpm
    $ sudo yum install ./cloudhsm-client-dyn-latest.el7.x86_64.rpm
    RHEL 6
    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-dyn-latest.el6.x86_64.rpm
    $ sudo yum install ./cloudhsm-client-dyn-latest.el6.x86_64.rpm
    RHEL 7
    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-dyn-latest.el7.x86_64.rpm
    $ sudo yum install ./cloudhsm-client-dyn-latest.el7.x86_64.rpm
    Ubuntu 16.04 LTS
    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Xenial/cloudhsm-client-dyn_latest_amd64.deb
    $ sudo apt install ./cloudhsm-client-dyn_latest_amd64.deb
  2. After you complete the preceding step, you can find the OpenSSL engine at /opt/cloudhsm/lib/libcloudhsm_openssl.so.

  3. Use the following command to set an environment variable named n3fips_password that contains the credentials of a crypto user (CU).

    $ export n3fips_password=<HSM user name>:<password>

To use the AWS CloudHSM dynamic engine for OpenSSL from the OpenSSL command line, use the -engine option to specify the OpenSSL dynamic engine named cloudhsm. For example:

$ openssl s_server -cert server.crt -key server.key -engine cloudhsm

To use the AWS CloudHSM dynamic engine for OpenSSL from an OpenSSL-integrated application, ensure that your application uses the OpenSSL dynamic engine named cloudhsm. The shared library for the dynamic engine is located at /opt/cloudhsm/lib/libcloudhsm_openssl.so.

Client SDK 5 Install

With Client SDK 5, you are not required to install or run a client daemon.

To install and configure the OpenSSL Dynamic Engine

  1. Use the following commands to download and install the OpenSSL engine.

    CentOS 8
    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-dyn-latest.el8.x86_64.rpm
    $ sudo yum install ./cloudhsm-client-dyn-latest.el8.x86_64.rpm
    RHEL 8
    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-dyn-latest.el8.x86_64.rpm
    $ sudo yum install ./cloudhsm-client-dyn-latest.el8.x86_64.rpm
    Ubuntu 18.04 LTS
    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Bionic/cloudhsm-dyn_latest_u18.04_amd64.deb
    $ sudo apt install ./cloudhsm-dyn_latest_u18.04_amd64.deb
  2. Set an environment variable with the credentials of a crypto user (CU):

    $ export CLOUDHSM_PIN=<HSM user name>:<password>
    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.

  • You must bootstrap Client SDK 5. For more information about bootstrapping, see Bootstrapping the Client SDK.

  • You can find the OpenSSL engine here:

    /opt/cloudhsm/lib/libcloudhsm_openssl.so

Verify OpenSSL Dynamic Engine after you install and configure.

To verify the OpenSSL Dynamic Engine

  • Use the following command to verify your installation of OpenSSL Dynamic Engine.

    $ openssl engine -t cloudhsm

    This output from the previous command verifies your configuration:

    (cloudhsm) CloudHSM OpenSSL Engine [ available ]

If you can't verify your installation of OpenSSL Dynamic Engine, consider the following points: