AWS cloudhsm documentation change
Summary
Updated installation commands to remove redundant 'sudo' and 'update' steps. Added detailed instructions for configuring OpenSSL Provider without modifying system default openssl.cnf. Improved security practices by recommending separate configuration files and environment variable setup. Fixed command examples and clarified HAProxy/NGINX setup steps.
Security assessment
The changes emphasize security best practices like avoiding system-wide openssl.cnf modification to prevent unintended cryptographic operations, but there's no evidence of addressing a specific vulnerability. Documentation additions focus on secure configuration of HSM-backed operations.
Diff
diff --git a/cloudhsm/latest/userguide/third-offload-linux-openssl-provider.md b/cloudhsm/latest/userguide/third-offload-linux-openssl-provider.md index b92e9dd7e..7a4ec5f9d 100644 --- a//cloudhsm/latest/userguide/third-offload-linux-openssl-provider.md +++ b//cloudhsm/latest/userguide/third-offload-linux-openssl-provider.md @@ -69,0 +70,4 @@ You can use a single HSM cluster, but you must first disable client key durabili +###### Note + +Many of the commands in this procedure require elevated privileges. You may need to run commands with `sudo` or as the root user depending on your system configuration. + @@ -79,2 +83 @@ Amazon Linux 2023 - $ sudo yum update -y - $ sudo yum install -y nginx + $ yum install nginx @@ -84,2 +87 @@ Amazon Linux 2023 - $ sudo yum update -y - $ sudo yum install -y haproxy + $ yum install haproxy @@ -92,2 +94 @@ RHEL 9 (9.2+) - $ sudo yum update -y - $ sudo yum install -y nginx + $ yum install nginx @@ -97,2 +98 @@ RHEL 9 (9.2+) - $ sudo yum update -y - $ sudo yum install -y haproxy + $ yum install haproxy @@ -105,2 +105 @@ RHEL 10 (10.0+) - $ sudo yum update -y - $ sudo yum install -y nginx + $ yum install nginx @@ -110,2 +109 @@ RHEL 10 (10.0+) - $ sudo yum update -y - $ sudo yum install -y haproxy + $ yum install haproxy @@ -118,2 +116 @@ Ubuntu 24.04 - $ sudo apt update - $ sudo apt install -y nginx + $ apt install nginx @@ -123,2 +120 @@ Ubuntu 24.04 - $ sudo apt update - $ sudo apt install -y haproxy + $ apt install haproxy @@ -168 +164 @@ This section shows you how to generate a keypair using the [CloudHSM CLI](./clou - Command: login --username <user name> --role crypto-user + aws-cloudhsm>login --username <user name> --role crypto-user @@ -185 +181 @@ Use the [key generate-asymmetric-pair rsa](./cloudhsm_cli-key-generate-asymmetri - --private-label tls_rsa_private + --private-label tls_rsa_private \ @@ -284 +280 @@ Use the [key generate-asymmetric-pair ec](./cloudhsm_cli-key-generate-asymmetric - --private-label tls_ec_private + --private-label tls_ec_private \ @@ -487 +483 @@ Use this section to configure NGINX with the OpenSSL Provider. - $ sudo mkdir -p /etc/pki/nginx/private + $ mkdir -p /etc/pki/nginx/private @@ -491 +487 @@ Use this section to configure NGINX with the OpenSSL Provider. - $ sudo cp <web_server.crt> /etc/pki/nginx/server.crt + $ cp <web_server.crt> /etc/pki/nginx/server.crt @@ -495 +491 @@ Use this section to configure NGINX with the OpenSSL Provider. - $ sudo cp <web_server_fake_pem.key> /etc/pki/nginx/private/server.key + $ cp <web_server_fake_pem.key> /etc/pki/nginx/private/server.key @@ -499 +495,49 @@ Use this section to configure NGINX with the OpenSSL Provider. - $ sudo chown nginx /etc/pki/nginx/server.crt /etc/pki/nginx/private/server.key + $ chown nginx /etc/pki/nginx/server.crt /etc/pki/nginx/private/server.key + + 6. Configure OpenSSL to use the AWS CloudHSM provider. For more information about configuring the OpenSSL Provider, see [AWS CloudHSM OpenSSL Provider for Client SDK 5](./openssl-provider-install.html). + + 1. Locate your OpenSSL configuration file: + + $ openssl version -d + +You should see output similar to: + + OPENSSLDIR: "/etc/pki/tls" + +The configuration file is `openssl.cnf` in this directory. + + 2. ###### Note + +Do not modify your system's default openssl.cnf file directly. This prevents system-wide OpenSSL operations (SSH, TLS connections, and other services) from unintentionally routing through the CloudHSM provider. + +Using a separate configuration file allows you to scope CloudHSM Provider usage to only specific applications that require HSM-backed cryptographic operations. + +Create a new OpenSSL configuration file with the following contents: + + $ cat > <example-cloudhsm-openssl.cnf> << 'EOF' + ## NOTE: This should point to the system default openssl config file. + # Replace /etc/pki/tls with the path to your OpenSSL configuration directory + .include </etc/pki/tls>/openssl.cnf + + # Override the existing provider_section to include AWS CloudHSM OpenSSL Provider as a 3rd party OpenSSL provider + [provider_sect] + default = default_sect + # Include AWS CloudHSM CloudHSM OpenSSL provider + cloudhsm = cloudhsm_sect + + [default_sect] + activate = 1 + + [cloudhsm_sect] + activate = 1 + EOF + + 3. Ensure that the `CLOUDHSM_PIN` environment variable is set with your crypto user (CU) credentials: + + $ export CLOUDHSM_PIN=<username>:<password> + + 4. Set the `OPENSSL_CONF` environment variable to point to your updated configuration file and verify the provider is loaded: + + $ OPENSSL_CONF=/path/to/example-cloudhsm-openssl.cnf openssl list -providers + +You should see both the default provider and the CloudHSM provider listed: @@ -501 +545,10 @@ Use this section to configure NGINX with the OpenSSL Provider. - 6. Configure OpenSSL to use the AWS CloudHSM provider. For more information about configuring the OpenSSL Provider, see [AWS CloudHSM OpenSSL Provider for Client SDK 5](./openssl-provider-install.html). Edit `/etc/ssl/openssl.cnf` and add the following sections: + OPENSSL_CONF=/path/to/example-cloudhsm-openssl.cnf openssl list -providers + Providers: + default + name: OpenSSL Default Provider + version: 3.2.2 + status: active + cloudhsm + name: AWS CloudHSM OpenSSL Provider + version: 5.17.0 + status: active @@ -505 +558 @@ Use this section to configure NGINX with the OpenSSL Provider. - $ sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.backup + $ cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.backup @@ -664 +717 @@ Then add the following to the TLS section of the file: - # It is *strongly* recommended to generate unique DH parameters for DHE ciphers for DHE ciphers + # It is *strongly* recommended to generate unique DH parameters for DHE ciphers @@ -666 +719 @@ Then add the following to the TLS section of the file: - ssl_dhparam "/etc/ssl/certs/dhparams.pem"; + # ssl_dhparam "/etc/ssl/certs/dhparams.pem"; @@ -696 +749 @@ Amazon Linux 2023 - 1. Back up the `nginx.service` file. + 1. Back up the `nginx.service` file: @@ -698 +751 @@ Amazon Linux 2023 - $ sudo cp /lib/systemd/system/nginx.service /lib/systemd/system/nginx.service.backup + $ cp /lib/systemd/system/nginx.service /lib/systemd/system/nginx.service.backup @@ -707 +760 @@ RHEL 9 (9.2+) - 1. Back up the `nginx.service` file. + 1. Back up the `nginx.service` file: @@ -709 +762 @@ RHEL 9 (9.2+) - $ sudo cp /lib/systemd/system/nginx.service /lib/systemd/system/nginx.service.backup + $ cp /lib/systemd/system/nginx.service /lib/systemd/system/nginx.service.backup @@ -711 +764 @@ RHEL 9 (9.2+) - 2. Open the `/lib/systemd/system/nginx.service` file in a text editor, and then under the [Service] section, add the following path: + 2. Open `/lib/systemd/system/nginx.service` in a text editor. Under the [Service] section, add: @@ -718 +771 @@ RHEL 10 (10.0+) - 1. Back up the `nginx.service` file. + 1. Back up the `nginx.service` file: @@ -720 +773 @@ RHEL 10 (10.0+) - $ sudo cp /lib/systemd/system/nginx.service /lib/systemd/system/nginx.service.backup + $ cp /lib/systemd/system/nginx.service /lib/systemd/system/nginx.service.backup @@ -722 +775 @@ RHEL 10 (10.0+) - 2. Open the `/lib/systemd/system/nginx.service` file in a text editor, and then under the [Service] section, add the following path: + 2. Open `/lib/systemd/system/nginx.service` in a text editor. Under the [Service] section, add: @@ -729 +782 @@ Ubuntu 24.04 - 1. Back up the `nginx.service` file. + 1. Back up the `nginx.service` file: @@ -731 +784 @@ Ubuntu 24.04 - $ sudo cp /lib/systemd/system/nginx.service /lib/systemd/system/nginx.service.backup + $ cp /lib/systemd/system/nginx.service /lib/systemd/system/nginx.service.backup @@ -733 +786 @@ Ubuntu 24.04 - 2. Open the `/lib/systemd/system/nginx.service` file in a text editor, and then under the [Service] section, add the following path: + 2. Open `/lib/systemd/system/nginx.service` in a text editor. Under the [Service] section, add: @@ -741 +794 @@ Ubuntu 24.04 - $ sudo cp /etc/sysconfig/nginx /etc/sysconfig/nginx.backup + $ cp /etc/sysconfig/nginx /etc/sysconfig/nginx.backup @@ -752 +805 @@ As the Linux root user, open `/etc/sysconfig/nginx` file in a text editor. For e - sudo vi /etc/sysconfig/nginx + vi /etc/sysconfig/nginx @@ -757 +810 @@ Add the Cryptography User (CU) credentials and the path to your OpenSSL configur - OPENSSL_CONF=<path to my-openssl.cnf> + OPENSSL_CONF=<path to example-cloudhsm-openssl.cnf> @@ -759 +812 @@ Add the Cryptography User (CU) credentials and the path to your OpenSSL configur -Replace `<CU user name>` and `<password>` with the CU credentials. Replace `<path to my-openssl.cnf>` with the full path to the configuration file you created in [Configure OpenSSL to use the provider](./openssl-provider-install.html#openssl-provider-configure-openssl). +Replace `<CU user name>` and `<password>` with the CU credentials. Replace `<path to example-cloudhsm-openssl.cnf>` with the full path to the configuration file you created in To configure NGINX for OpenSSL Provider. @@ -769 +822 @@ Open the `/etc/sysconfig/nginx` file in a text editor. This may require Linux ro - OPENSSL_CONF=<path to my-openssl.cnf> + OPENSSL_CONF=<path to example-cloudhsm-openssl.cnf> @@ -771 +824 @@ Open the `/etc/sysconfig/nginx` file in a text editor. This may require Linux ro -Replace `<CU user name>` and `<password>` with the CU credentials. Replace `<path to my-openssl.cnf>` with the full path to the configuration file you created in [Configure OpenSSL to use the provider](./openssl-provider-install.html#openssl-provider-configure-openssl). +Replace `<CU user name>` and `<password>` with the CU credentials. Replace `<path to example-cloudhsm-openssl.cnf>` with the full path to the configuration file you created in To configure NGINX for OpenSSL Provider. @@ -781 +834 @@ Open the `/etc/sysconfig/nginx` file in a text editor. This may require Linux ro - OPENSSL_CONF=<path to my-openssl.cnf> + OPENSSL_CONF=<path to example-cloudhsm-openssl.cnf> @@ -783 +836 @@ Open the `/etc/sysconfig/nginx` file in a text editor. This may require Linux ro -Replace `<CU user name>` and `<password>` with the CU credentials. Replace `<path to my-openssl.cnf>` with the full path to the configuration file you created in [Configure OpenSSL to use the provider](./openssl-provider-install.html#openssl-provider-configure-openssl). +Replace `<CU user name>` and `<password>` with the CU credentials. Replace `<path to example-cloudhsm-openssl.cnf>` with the full path to the configuration file you created in To configure NGINX for OpenSSL Provider. @@ -793 +846 @@ Open the `/etc/sysconfig/nginx` file in a text editor. This may require Linux ro - OPENSSL_CONF=<path to my-openssl.cnf> + OPENSSL_CONF=<path to example-cloudhsm-openssl.cnf> @@ -795 +848 @@ Open the `/etc/sysconfig/nginx` file in a text editor. This may require Linux ro -Replace `<CU user name>` and `<password>` with the CU credentials. Replace `<path to my-openssl.cnf>` with the full path to the configuration file you created in [Configure OpenSSL to use the provider](./openssl-provider-install.html#openssl-provider-configure-openssl). +Replace `<CU user name>` and `<password>` with the CU credentials. Replace `<path to example-cloudhsm-openssl.cnf>` with the full path to the configuration file you created in To configure NGINX for OpenSSL Provider. @@ -806 +859 @@ Stop all NGINX processes - $ sudo systemctl stop nginx + $ systemctl stop nginx @@ -810 +863 @@ Reload the `systemd` configuration to pick up the latest changes - $ sudo systemctl daemon-reload + $ systemctl daemon-reload