[v13] docs: update CloudHSM docs

.github/ISSUE_TEMPLATE/testplan.md

@@ -708,7 +708,7 @@ Set `auth_service.authentication.require_session_mfa: hardware_key_touch` in you
   - [ ] Migrating a software cluster to YubiHSM2 works
   - [ ] CA rotation works
 - [ ] AWS CloudHSM Support
-  - [ ] Make sure docs/links are up to date (they currently aren't https://github.com/gravitational/teleport/issues/24503)
+  - [ ] Make sure docs/links are up to date
   - [ ] New cluster with CloudHSM CA works
   - [ ] Migrating a software cluster to CloudHSM works
   - [ ] CA rotation works

docs/cspell.json

@@ -27,6 +27,7 @@
     "BSFD",
     "BUCKETNAME",
     "Binm",
+    "CAcreateserial",
     "CCDC",
     "CHANGEID",
     "CHANGEME",
@@ -72,6 +73,7 @@
     "Grafana's",
     "Gtczk",
     "hostdb",
+    "hsm-ppzzfxbleki",
     "HSTS",
     "Hqlo",
     "IAMR",
@@ -281,9 +283,11 @@
     "clientid",
     "clis",
     "cloudbuild",
+    "cloudhsmv2",
     "cloudkms",
     "cloudsql",
     "clusers",
+    "cluster-6uysmebmutd",
     "clusteradmin",
     "clustername",
     "clusterolebinding",

docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx

@@ -36,32 +36,149 @@ to use.
 
 <Tabs>
   <TabItem label="AWS CloudHSM">
-Before getting started, you should create and activate a CloudHSM cluster in
-the VPC where you will run your Teleport Auth Server. Create a Crypto User (CU)
-to be used by Teleport. See the AWS CloudHSM
-[User Guide](https://docs.aws.amazon.com/cloudhsm/latest/userguide/getting-started.html)
-for help.
+1. Create a CloudHSM cluster in the VPC where you will run your Teleport Auth Server.
+   https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster.html
 
-On the EC2 instance where you will run your Teleport Auth Server:
+2. Wait for the newly created cluster to enter the "Uninitialized" state.
 
-1. Add the security group with the same name as your CloudHSM cluster to your
-   EC2 instance to allow incoming traffic from CloudHSM on ports 2223–2225.
+3. Add an HSM to the new cluster, using the AWS Console or the AWS CLI:
 
-2. Install and configure the CloudHSM client by following
-   https://docs.aws.amazon.com/cloudhsm/latest/userguide/install-and-configure-client-linux.html.
+   ```code
+   $ aws cloudhsmv2 create-hsm --cluster-id <Var name="cluster ID"/> --availability-zone <Var name="availability zone"/>
+   {
+       "Hsm": {
+           "AvailabilityZone": "ca-central-1a",
+           "ClusterId": "cluster-6uysmebmutd",
+           "SubnetId": "subnet-0c535b67a117f7186",
+           "HsmId": "hsm-ppzzfxbleki",
+           "State": "CREATE_IN_PROGRESS"
+       }
+   }
+   ```
+
+4. Optionally verify the identity and authenticity of your new HSM
+   https://docs.aws.amazon.com/cloudhsm/latest/userguide/verify-hsm-identity.html
+
+5. To initialize the cluster, you must download and sign a certificate signing
+   request (CSR) that is generated by the cluster's first HSM.
+   Download the CSR from the AWS Console or via the AWS CLI:
 
-3. Start the CloudHSM client.
    ```code
-   $ sudo systemctl start cloudhsm-client
+   $ aws cloudhsmv2 describe-clusters --filters clusterIds=<Var name="cluster ID"/> \
+         --output text \
+         --query 'Clusters[].Certificates.ClusterCsr' \
+         > ClusterCsr.csr
    ```
 
-4. Install the AWS CloudHSM Client SDK 3 by following
-   https://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-library-install.html.
+6. Choose an appropriate RSA 2048 or RSA 4096 key and self-signed certificate to
+   sign the HSM CSR.
+   For a production cluster, AWS recommends a secured offsite and offline HSM.
+   For a demonstration or test cluster, you can create a key and self-signed
+   certificate with the following `openssl` commands:
 
-   This step installs the PKCS#11 module at `/opt/cloudhsm/lib/libcloudhsm_pkcs11.so`
-  </TabItem>
+   ```code
+   $ openssl genrsa -aes256 -out customerCA.key 2048
+   $ openssl req -new -x509 -days 3652 -key customerCA.key -out customerCA.crt
+   ```
+
+7. Sign the cluster CSR using the key and self-signed cert from the previous
+   step.
+   A demonstration `openssl` command to sign the CSR is:
 
+   ```code
+   $ openssl x509 -req -days 3652 -in ClusterCsr.csr \
+         -CA customerCA.crt \
+         -CAkey customerCA.key \
+         -CAcreateserial \
+         -out CustomerHsmCertificate.crt
+   ```
+
+8. Initialize the CloudHSM cluster by uploading the signed cert to the AWS
+   Console or with the following AWS CLI command:
+
+   ```code
+   $ aws cloudhsmv2 initialize-cluster --cluster-id <Var name="cluster ID"/> \
+         --signed-cert file://CustomerHsmCertificate.crt \
+         --trust-anchor file://customerCA.crt
+   {
+       "State": "INITIALIZE_IN_PROGRESS",
+       "StateMessage": "Cluster is initializing. State will change to INITIALIZED upon completion."
+   }
+   ```
+
+9. A security group with the same name as your CloudHSM cluster will have been
+   automatically created when you created the cluster.
+   Attach this security group to the EC2 instance where you will run your
+   Teleport Auth Server to allow traffic between the Auth Server and your HSM.
+
+10. On the Auth Server EC2 instance, install the CloudHSM CLI for the CloudHSM
+    Client SDK 5.
+    https://docs.aws.amazon.com/cloudhsm/latest/userguide/gs_cloudhsm_cli-install.html
+
+    Bootstrap the CLI by configuring the IP address of the new HSM:
+
+    ```code
+    $ sudo /opt/cloudhsm/bin/configure-cli -a <Var name="HSM IP address"/>
+    ```
+
+11. Copy the self-signed certificate from step 6 (`customerCA.crt`) to the EC2
+    instance, save it at `/opt/cloudhsm/etc/customerCA.crt`.
+
+12. Activate the CloudHSM cluster with the CloudHSM CLI by creating an admin user
+    with a new password:
+
+    ```text
+    $ sudo /opt/cloudhsm/bin/cloudhsm-cli interactive
+    aws-cloudhsm > cluster activate
+    Enter password:
+    Confirm password:
+    {
+      "error_code": 0,
+      "data": "Cluster activation successful"
+    }
+    ```
+
+13. Login to the CloudHSM CLI as the new admin user and create a Crypto User to
+    be used by Teleport.
+    Remember this new password because Teleport will use it later to authenticate
+    to the PKCS#11 library.
+
+    ```text
+    aws-cloudhsm > login --username admin --role admin
+    Enter password:
+    {
+      "error_code": 0,
+      "data": {
+        "username": "admin",
+        "role": "admin"
+      }
+    }
+    aws-cloudhsm > user create --username teleport --role crypto-user
+    Enter password:
+    Confirm password:
+    {
+      "error_code": 0,
+      "data": {
+        "username": "teleport",
+        "role": "crypto-user"
+      }
+    }
+    aws-cloudhsm > quit
+    ```
+
+14. Install the PKCS#11 library for the Client SDK 5 on the same Auth Server EC2 instance
+    https://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-library-install.html
+
+    Bootstrap the PKCS#11 library by configuring the HSM IP address.
+    If you only have one HSM in the cluster, you must include the
+    `--disable-key-availability-check` flag.
+
+    ```code
+    $ sudo /opt/cloudhsm/bin/configure-pkcs11 --disable-key-availability-check -a <Var name="HSM IP address"/>
+
+  </TabItem>
   <TabItem label="YubiHSM2">
+
 1. Install the YubiHSM2 [SDK](https://developers.yubico.com/YubiHSM2/Releases/).
 
    <Admonition type="warning">
@@ -150,9 +267,16 @@ auth_service:
 
   ca_key_params:
     pkcs11:
+      # this is the default install location of the PKCS#11 module for the
+      # CloudHSM Client SDK 5
       module_path: /opt/cloudhsm/lib/libcloudhsm_pkcs11.so
-      # token_label should always be "cavium" for CloudHSM
-      token_label: "cavium"
+
+      # token_label should always be "hsm1" for the CloudHSM SDK 5
+      # if you prefer to use SDK version 3, replace this with "cavium"
+      token_label: "hsm1"
+
+      # pin should be set to the username and password of the Crypto User
+      # created earlier in the guide
       pin: "<CU_username>:<CU_password>"
       # pin_path can optionally be used to read the pin from a file
       # pin_path: /path/to/pin_file