diff --git a/.github/ISSUE_TEMPLATE/testplan.md b/.github/ISSUE_TEMPLATE/testplan.md index 2f2dafb517f54..149d10ef0a76d 100644 --- a/.github/ISSUE_TEMPLATE/testplan.md +++ b/.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 diff --git a/docs/cspell.json b/docs/cspell.json index e8d3dea14ea8f..703859e7d0c04 100644 --- a/docs/cspell.json +++ b/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", diff --git a/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx b/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx index 7c640f81dfb54..8f6971e5d0576 100644 --- a/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx +++ b/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx @@ -36,32 +36,149 @@ to use. -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 --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= \ + --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` - + ```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 \ + --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 + ``` + +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 + + + 1. Install the YubiHSM2 [SDK](https://developers.yubico.com/YubiHSM2/Releases/). @@ -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: ":" # pin_path can optionally be used to read the pin from a file # pin_path: /path/to/pin_file