From a4c1e083a3be3cafddbafc7b36898838d804fb60 Mon Sep 17 00:00:00 2001 From: Nic Klaassen Date: Fri, 21 Apr 2023 17:48:13 -0700 Subject: [PATCH 1/4] docs: update YubiHSM2 docs Some edits I made to the YubiHSM2 docs while going through the test plan. Mostly just adding some extra context and trying to improve readability. Important changes: - added a warning that the YubiHSM2 SDK v 2023.01 is unsupported, due to https://github.com/gravitational/teleport/issues/25017 - the CA rotation example was out of date because you cannot rotate all CAs at once anymore. Removed the example and I'm just linking to the CA rotation guide now. --- .../teleport-enterprise/hsm.mdx | 107 +++++++++++------- 1 file changed, 66 insertions(+), 41 deletions(-) diff --git a/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx b/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx index 9877d1c51a3cf..f909edd99e6ed 100644 --- a/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx +++ b/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx @@ -64,41 +64,67 @@ On the EC2 instance where you will run your Teleport Auth Server: 1. Install the YubiHSM2 [SDK](https://developers.yubico.com/YubiHSM2/Releases/). -2. Start `yubihsm-connector` + + The YubiHSM2 SDK version `2023.01` is currently unsupported. + The latest known supported version is `2022.06`. + + +2. Start `yubihsm-connector` with debug logging enabled. This is a background + process that you will need to keep running to facilitate connections to your + YubiHSM2. ```code - $ yubihsm-connector + $ yubihsm-connector -d + DEBU[0000] preflight complete cert= config= key= pid=73502 seccomp=false serial= syslog=false timeout=0s version=3.0.3 + DEBU[0000] takeoff TLS=false listen="localhost:12345" pid=73502 ``` -3. Use `yubihsm-shell` to create a new authentication key to be used by - Teleport with the below capabilities. - - YubiHSM2 comes with a default authentication key at slot 1 with password +3. Use `yubihsm-shell` to create a new Authentication Key to be used by + Teleport with the necessary capabilities. + + YubiHSM2 comes with a factory default Authentication Key at slot 1 with password `password`. You should replace and delete it as recommended by Yubico. - When creating the authentication key to be used by Teleport, the password + When creating the Authentication Key to be used by Teleport, the password must have at least 8 characters. The example `hunter22` is used here. - ```text $ yubihsm-shell + Using default connector URL: http://localhost:12345 yubihsm> connect + Session keepalive set up to run every 15 seconds yubihsm> session open 1 password + Created session 0 + + # Create an Authenticate Key for Teleport yubihsm> put authkey 0 0 "Teleport Auth Key" 1 generate-asymmetric-key:sign-pkcs:delete-asymmetric-key sign-pkcs:sign-pss:decrypt-pkcs:decrypt-oaep hunter22 - Stored Authentication key 0x53bf + Stored Authentication key 0x85cf + + # Make sure you can open a session with the new Authenication Key and password + yubihsm> session open 0x85cf hunter22 + Created session 1 + + # Delete the factory default Authentication Key + yubihsm> delete 0 1 authentication-key ``` - Take note of the hex slot number output above. It will be used when configuring Teleport. + Take note of the slot number of the new Authentication Key. + In the above example this is the hex value `0x85cf`. + This will need to be included in your Teleport configuration file in a later + step. -4. Create a `yubihsm_pkcs11.conf` file pointing to your connector +4. Create a `yubihsm_pkcs11.conf` file to configure the address and port that + `yubihsm-connector` is listening on and enable debug logging. ```text # /etc/yubishm_pkcs11.conf connector = https://127.0.0.1:12345 + debug ``` 5. Set the environment variable `YUBIHSM_PKCS11_CONF` to the path of your - configuration file. This will be read by the PKCS#11 module and needs to be - set in the Teleport auth server's environment. + configuration file. + This will be read by the PKCS#11 module and needs to be set in the Teleport + auth server's environment. ```code $ export YUBIHSM_PKCS11_CONF=/etc/yubihsm_pkcs11.conf ``` @@ -145,12 +171,13 @@ auth_service: ca_key_params: pkcs11: + # this is the default installation path for Yubico's PKCS#11 module module_path: /usr/local/lib/pkcs11/yubihsm_pkcs11.dylib - # slot_number should be set to 0 for YubiHSM2 + # slot_number should always be set to 0 for YubiHSM2 slot_number: 0 - # pin should be the (hex) slot of your authentication key, + # pin should be the (hex) slot number of your Authentication Key, # concatenated with the password - pin: "53bfhunter22" + pin: "85cfhunter22" # pin_path can optionally be used to read the pin from a file # pin_path: /path/to/pin_file ``` @@ -176,36 +203,34 @@ route any traffic to the auth server where the HSM is currently being added. ## Step 4/5. Certificate Rotation with HSM When adding a new HSM to an existing Teleport cluster, or adding a new -HSM-connected Auth server to an HA Teleport cluster, CA rotation needs to be -performed in order for the cluster to trust the new HSM certificates. `teleport` -will print a warning during startup if this needs to be completed, and will not -sign any certificates (except the `Admin` certificate used by `tctl` which will -be signed by a temporary HSM key). A warning will also be printed in `tctl -status` if this is required for any Auth server in the cluster. - -CA rotation can be performed manually or semi-automatically, see our admin guide -on [Certificate rotation](../../management/operations/ca-rotation.mdx). To rotate the -CAs manually you can run: +HSM-connected Auth server to an HA Teleport cluster, you will need to rotate all +Certificate Authoritities in order for new certificates to by issued and +trusted. +`tctl status` will print a warning if CA rotation is required: ```code $ tctl status -WARNING: One or more auth servers has a newly added or removed HSM... -$ tctl auth rotate --manual --phase init -# all auth servers will generate new HSM keys, wait for logs to stabilize -$ tctl auth rotate --manual --phase update_clients -# wait for all teleport servers and clients to reload and receive new certs, up -# to ~10 minutes if all clients are connected -$ tctl auth rotate --manual --phase update_servers -# wait for all teleport servers to reload, up to ~10 minutes -$ tctl auth rotate --manual --phase standby -# rotation is complete -$ tctl status -# no warning should be printed +WARNING: One or more auth servers has a newly added or removed HSM or KMS configured. You should not route traffic to that server until a CA rotation has been completed. +Cluster cluster-one +Version 13.0.0-alpha.1 +host CA never updated +user CA never updated +db CA never updated +openssh CA never updated +jwt CA never updated +saml_idp CA never updated +CA pin sha256:29afff5a1c1231375525b8a9b98ea7a44a760b7e65de3ca2e04d72db39b1672b +CA pin sha256:e758c8f0f6cd95116d5da8171e0ff4adfa99dab3b1f171bfe854070884955524 ``` -If you are updating a live cluster, make sure to wait for all nodes which may -intermittently lose connection to connect and receive new certs or they may lose -access to the cluster and have to re-join. +`teleport start` will also print a warning during startup if any CA needs to be rotated. +Until rotation is completed, the auth server will not sign any new certificates +(except the `Admin` certificate used by `tctl` which will be signed by a +temporary HSM key). + +CA rotation can be performed manually or semi-automatically, see our admin guide +on [Certificate rotation](../../management/operations/ca-rotation.mdx). +All CAs listed in the output of `tctl status` must be rotated. ## Step 5/5. Confirm that Teleport is using your HSM From b8a5b05728770f89fe0233d75568238280c28710 Mon Sep 17 00:00:00 2001 From: Nic Klaassen Date: Tue, 25 Apr 2023 10:11:36 -0700 Subject: [PATCH 2/4] punctuation Co-authored-by: Alex Fornuto --- docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx b/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx index f909edd99e6ed..cc398791c0a80 100644 --- a/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx +++ b/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx @@ -113,7 +113,7 @@ On the EC2 instance where you will run your Teleport Auth Server: step. 4. Create a `yubihsm_pkcs11.conf` file to configure the address and port that - `yubihsm-connector` is listening on and enable debug logging. + `yubihsm-connector` is listening on and enable debug logging: ```text # /etc/yubishm_pkcs11.conf From a6b83d10038a8971a5b51e43ee3c6a70053eb29b Mon Sep 17 00:00:00 2001 From: Nic Klaassen Date: Wed, 26 Apr 2023 09:25:53 -0700 Subject: [PATCH 3/4] s/Authentication Key/authentication key/ --- .../choose-an-edition/teleport-enterprise/hsm.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx b/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx index cc398791c0a80..6a5f2d82316c2 100644 --- a/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx +++ b/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx @@ -78,13 +78,13 @@ On the EC2 instance where you will run your Teleport Auth Server: DEBU[0000] preflight complete cert= config= key= pid=73502 seccomp=false serial= syslog=false timeout=0s version=3.0.3 DEBU[0000] takeoff TLS=false listen="localhost:12345" pid=73502 ``` -3. Use `yubihsm-shell` to create a new Authentication Key to be used by +3. Use `yubihsm-shell` to create a new authentication key to be used by Teleport with the necessary capabilities. - YubiHSM2 comes with a factory default Authentication Key at slot 1 with password + YubiHSM2 comes with a factory default authentication key at slot 1 with password `password`. You should replace and delete it as recommended by Yubico. - When creating the Authentication Key to be used by Teleport, the password + When creating the authentication key to be used by Teleport, the password must have at least 8 characters. The example `hunter22` is used here. ```text @@ -103,11 +103,11 @@ On the EC2 instance where you will run your Teleport Auth Server: yubihsm> session open 0x85cf hunter22 Created session 1 - # Delete the factory default Authentication Key + # Delete the factory default authentication key yubihsm> delete 0 1 authentication-key ``` - Take note of the slot number of the new Authentication Key. + Take note of the slot number of the new authentication key. In the above example this is the hex value `0x85cf`. This will need to be included in your Teleport configuration file in a later step. @@ -175,7 +175,7 @@ auth_service: module_path: /usr/local/lib/pkcs11/yubihsm_pkcs11.dylib # slot_number should always be set to 0 for YubiHSM2 slot_number: 0 - # pin should be the (hex) slot number of your Authentication Key, + # pin should be the (hex) slot number of your authentication key, # concatenated with the password pin: "85cfhunter22" # pin_path can optionally be used to read the pin from a file From c50cfd91265f30d2615f427dbef3ab1778cad836 Mon Sep 17 00:00:00 2001 From: Nic Klaassen Date: Wed, 26 Apr 2023 11:40:46 -0700 Subject: [PATCH 4/4] fix spelling --- docs/cspell.json | 2 ++ docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/cspell.json b/docs/cspell.json index 3e93bdc6d35f7..a610a0f7d3d85 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -271,6 +271,7 @@ "certificatekey", "certutil", "cfsdf", + "cfhunter", "cgroupv", "chacha", "cicd", @@ -599,6 +600,7 @@ "sampleconnector", "sandboxbd", "scrollback", + "seccomp", "secretname", "selectnongalleryapp", "selectsaml", diff --git a/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx b/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx index 6a5f2d82316c2..7c640f81dfb54 100644 --- a/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx +++ b/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx @@ -99,7 +99,7 @@ On the EC2 instance where you will run your Teleport Auth Server: yubihsm> put authkey 0 0 "Teleport Auth Key" 1 generate-asymmetric-key:sign-pkcs:delete-asymmetric-key sign-pkcs:sign-pss:decrypt-pkcs:decrypt-oaep hunter22 Stored Authentication key 0x85cf - # Make sure you can open a session with the new Authenication Key and password + # Make sure you can open a session with the new authentication key and password yubihsm> session open 0x85cf hunter22 Created session 1 @@ -204,7 +204,7 @@ route any traffic to the auth server where the HSM is currently being added. When adding a new HSM to an existing Teleport cluster, or adding a new HSM-connected Auth server to an HA Teleport cluster, you will need to rotate all -Certificate Authoritities in order for new certificates to by issued and +Certificate Authorities in order for new certificates to by issued and trusted. `tctl status` will print a warning if CA rotation is required: