From d9676713d4eb703cbd16acac3d62cc48dfc9d15d Mon Sep 17 00:00:00 2001 From: Nic Klaassen Date: Thu, 27 Apr 2023 19:45:17 -0700 Subject: [PATCH] docs: update CloudHSM docs Some edits I made to the CloudHSM docs while going through the v13 test plan. The biggest change is an update to use the Client SDK 5, instead of version 3. This has many benefits, you are not required to run a client daemon, and it works with the kernel in FIPS mode (v3 doesn't). I also added much more detail to the guide and added code samples where I could, you should be able to go through this mostly without reading the AWS docs, I link there for downloads or extra/optional information. The AWS docs are very hard to follow. --- .github/ISSUE_TEMPLATE/testplan.md | 2 +- docs/cspell.json | 4 + .../teleport-enterprise/hsm.mdx | 160 ++++++++++++++++-- 3 files changed, 147 insertions(+), 19 deletions(-) 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