# OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5 The AWS CloudHSM OpenSSL Dynamic Engine allows you to offload cryptographic operations to your CloudHSM cluster through the OpenSSL API. AWS CloudHSM provides an OpenSSL Dynamic Engine, which you can read about in [AWS CloudHSM SSL/TLS offload on Linux using Tomcat with JSSE](third-offload-linux-jsse.md) or [AWS CloudHSM SSL/TLS offload on Linux using NGINX or Apache with OpenSSL](third-offload-linux-openssl.md). For an example on using AWS CloudHSM with OpenSSL, refer to [this AWS security blog](https://aws.amazon.com/blogs/security/automate-the-deployment-of-an-nginx-web-service-using-amazon-ecs-with-tls-offload-in-cloudhsm/). For information about platform support for SDKs, see [AWS CloudHSM Client SDK 5 supported platforms](client-supported-platforms.md). For troubleshooting, see [Known issues for the OpenSSL Dynamic Engine for AWS CloudHSM](ki-openssl-sdk.md). Use the following sections to install and configure the AWS CloudHSM dynamic engine for OpenSSL, using Client SDK 5. For information on using Client SDK 3, see [Using previous SDK version to work with AWS CloudHSM](choose-client-sdk.md). **Topics** + [Install the OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5](openssl5-install.md) + [Supported key types for OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5](openssl-key-types.md) + [Supported mechanisms for OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5](openssl-mechanisms.md) + [Advanced configurations for OpenSSL for AWS CloudHSM](openssl-library-configs.md) # Install the OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5 Use the following sections to install the OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5. **Note** To run a single HSM cluster with Client SDK 5, you must first manage client key durability settings by setting `disable_key_availability_check` to `True`. For more information, see [Key Synchronization](manage-key-sync.md) and [Client SDK 5 Configure Tool](configure-sdk-5.md). **To install and configure the OpenSSL Dynamic Engine** 1. Use the following commands to download and install the OpenSSL engine. ------ #### [ Amazon Linux 2023 ] Install the OpenSSL Dynamic Engine for Amazon Linux 2023 on x86\$164 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-dyn-latest.amzn2023.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-dyn-latest.amzn2023.x86_64.rpm ``` Install the OpenSSL Dynamic Engine for Amazon Linux 2023 on ARM64 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-dyn-latest.amzn2023.aarch64.rpm ``` ``` $ sudo yum install ./cloudhsm-dyn-latest.amzn2023.aarch64.rpm ``` ------ #### [ Amazon Linux 2 ] Install the OpenSSL Dynamic Engine for Amazon Linux 2 on x86\$164 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-dyn-latest.el7.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-dyn-latest.el7.x86_64.rpm ``` Install the OpenSSL Dynamic Engine for Amazon Linux 2 on ARM64 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-dyn-latest.el7.aarch64.rpm ``` ``` $ sudo yum install ./cloudhsm-dyn-latest.el7.aarch64.rpm ``` ------ #### [ RHEL 9 (9.2\$1) ] Install the OpenSSL Dynamic Engine for RHEL 9 on x86\$164 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-dyn-latest.el9.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-dyn-latest.el9.x86_64.rpm ``` Install the OpenSSL Dynamic Engine for RHEL 9 on ARM64 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-dyn-latest.el9.aarch64.rpm ``` ``` $ sudo yum install ./cloudhsm-dyn-latest.el9.aarch64.rpm ``` ------ #### [ RHEL 8 (8.3\$1) ] Install the OpenSSL Dynamic Engine for RHEL 8 on x86\$164 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-dyn-latest.el8.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-dyn-latest.el8.x86_64.rpm ``` Install the OpenSSL Dynamic Engine for RHEL 8 on ARM64 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-dyn-latest.el8.aarch64.rpm ``` ``` $ sudo yum install ./cloudhsm-dyn-latest.el8.aarch64.rpm ``` ------ #### [ Ubuntu 24.04 LTS ] Install the OpenSSL Dynamic Engine for Ubuntu 24.04 LTS on x86\$164 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-dyn_latest_u24.04_amd64.deb ``` ``` $ sudo apt install ./cloudhsm-dyn_latest_u24.04_amd64.deb ``` Install the OpenSSL Dynamic Engine for Ubuntu 24.04 LTS on ARM64 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-dyn_latest_u24.04_arm64.deb ``` ``` $ sudo apt install ./cloudhsm-dyn_latest_u24.04_arm64.deb ``` ------ #### [ Ubuntu 22.04 LTS ] Install the OpenSSL Dynamic Engine for Ubuntu 22.04 LTS on x86\$164 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-dyn_latest_u22.04_amd64.deb ``` ``` $ sudo apt install ./cloudhsm-dyn_latest_u22.04_amd64.deb ``` Install the OpenSSL Dynamic Engine for Ubuntu 22.04 LTS on ARM64 architecture: ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-dyn_latest_u22.04_arm64.deb ``` ``` $ sudo apt install ./cloudhsm-dyn_latest_u22.04_arm64.deb ``` ------ You have installed the shared library for the dynamic engine at `/opt/cloudhsm/lib/libcloudhsm_openssl_engine.so`. 1. Bootstrap Client SDK 5. For more information about bootstrapping, see [Bootstrap the Client SDK](cluster-connect.md#connect-how-to). 1. Set an environment variable with the credentials of a crypto user (CU). For information about creating CUs, see [Create an AWS CloudHSM user with CloudHSM CLI](cloudhsm_cli-user-create.md). ``` $ export CLOUDHSM_PIN=: ``` **Note** Client SDK 5 introduces the `CLOUDHSM_PIN` environment variable for storing the credentials of the CU. In Client SDK 3 you store the CU credentials in the `n3fips_password` environment variable. Client SDK 5 supports both environment variables, but we recommend using `CLOUDHSM_PIN`. When setting `CLOUDHSM_PIN` environment variables, you must escape any special characters that may be interpreted by your shell. 1. Connect your installation of OpenSSL Dynamic Engine to the cluster. For more information, see [Connect to the Cluster](cluster-connect.md). 1. Bootstrap the Client SDK 5. For more information, see [Bootstrap the Client SDK](cluster-connect.md#connect-how-to). ## Verify the OpenSSL Dynamic Engine for Client SDK 5 Use the following command to verify your installation of OpenSSL Dynamic Engine. ``` $ openssl engine -t cloudhsm ``` The following output verifies your configuration: ``` (cloudhsm) CloudHSM OpenSSL Engine [ available ] ``` # Supported key types for OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5 The AWS CloudHSM OpenSSL Dynamic Engine supports the following key types with Client SDK 5. **** | Key Type | Description | | --- | --- | | EC | ECDSA sign/verify for P-256, P-384, and secp256k1 key types. To generate EC keys that are interoperable with the OpenSSL engine, see [Export an asymmetric key with CloudHSM CLI](cloudhsm_cli-key-generate-file.md). | | RSA | RSA key generation for 2048, 3072, and 4096-bit keys.RSA sign/verify. Verification is offloaded to OpenSSL software. | # Supported mechanisms for OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5 The AWS CloudHSM OpenSSL Dynamic Engine supports the following mechanisms for Sign and Verify functions with Client SDK 5. ## Sign and verify functions With Client SDK 5, the data is hashed locally in software. This means there is no limit on the size of the data that can be hashed. RSA Signature Types + SHA1withRSA + SHA224withRSA + SHA256withRSA + SHA384withRSA + SHA512withRSA ECDSA Signature Types + SHA1withECDSA + SHA224withECDSA + SHA256withECDSA + SHA384withECDSA + SHA512withECDSA # Advanced configurations for OpenSSL for AWS CloudHSM The AWS CloudHSM OpenSSL provider includes the following advanced configuration, which is not part of the general configurations most customers utilize. These configurations provide additional capabilities. + [Retry commands for OpenSSL](openssl-library-configs-retry.md) # Retry commands for OpenSSL for AWS CloudHSM AWS CloudHSM Client SDK 5.8.0 and later have a built-in automatic retry strategy which will retry HSM-throttled operations from the client side. When an HSM throttles operations because it is too busy performing previous operations and cannot take more requests, client SDKs will attempt to retry throttled operations up to 3 times while exponentially backing off. This automatic retry strategy can be set to one of two modes: **off** and **standard**. + **off**: The Client SDK will not perform any retry strategy for any throttled operations by the HSM. + **standard**: This is the default mode for Client SDK 5.8.0 and later. In this mode, client SDKs will automatically retry throttled operations by exponentially backing off. For more information, see [HSM throttling](troubleshoot-hsm-throttling.md). ## Set retry commands to off mode You can use the following command to set retry commands to **off** mode: ``` $ sudo /opt/cloudhsm/bin/configure-dyn --default-retry-mode off ```