docs: update YubiHSM2 docs

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",

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:
   <TabItem label="YubiHSM2">
 1. Install the YubiHSM2 [SDK](https://developers.yubico.com/YubiHSM2/Releases/).
 
-2. Start `yubihsm-connector`
+   <Admonition type="warning">
+     The YubiHSM2 SDK version `2023.01` is currently unsupported.
+     The latest known supported version is `2022.06`.
+   </Admonition>
+
+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.
-   <Admonition type="note">
-   YubiHSM2 comes with a default authentication key at slot 1 with password
+   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
    must have at least 8 characters. The example `hunter22` is used here.
-   </Admonition>
 
    ```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 authentication 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 Authorities 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