docs: clarify upgrade path for YubiHSM2 users (#48723)

* docs: clarify upgrade path for YubiHSM2 users * apply suggestions from code review Co-authored-by: Paul Gottschling <[email protected]> * link terms to yubihsm docs * rephrase * fix lint --------- Co-authored-by: Paul Gottschling <[email protected]>
gravitational · Nov 14, 2024 · 5560932 · 5560932
1 parent b8522ff
commit 5560932
Show file tree

Hide file tree

Showing 3 changed files with 81 additions and 13 deletions.
diff --git a/docs/cspell.json b/docs/cspell.json
@@ -344,7 +344,7 @@
     "certificatekey",
     "certificatesigningrequest",
     "certutil",
-    "cfhunter",
+    "cfpassword",
     "cfsdf",
     "cgroups",
     "cgroupv",

diff --git a/docs/pages/admin-guides/deploy-a-cluster/hsm.mdx b/docs/pages/admin-guides/deploy-a-cluster/hsm.mdx
@@ -189,33 +189,41 @@ to use.
    DEBU[0000] takeoff                                       TLS=false listen="localhost:12345" pid=73502
    ```
 
-1. Use `yubihsm-shell` to create a new authentication key to be used by
-   Teleport with the necessary capabilities.
+1. Use `yubihsm-shell` to create a new
+   [authentication key](https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-core-concepts.html#authentication-key)
+   to be used by Teleport with the necessary
+   [capabilities](https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-core-concepts.html#capability).
 
    YubiHSM2 comes with a factory default authentication key at slot 1 with password
-   `password`. You should replace and delete it as recommended by Yubico.
+   `password`. We recommend replacing this or changing the password as soon as
+   possible.
 
    When creating the authentication key to be used by Teleport, the password
-   must have at least 8 characters. The example `hunter22` is used here.
+   must have at least 8 characters.
 
    ```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
+   yubihsm> session open 1
+   Enter password:
    Created session 0
 
-   # Create an Authenticate Key for Teleport
-   yubihsm> put authkey 0 0 "Teleport Auth Key" 1 generate-asymmetric-key:sign-pkcs:sign-pss:sign-ecdsa:delete-asymmetric-key sign-pkcs:sign-pss:decrypt-pkcs:decrypt-oaep:sign-ecdsa hunter22
+   # Create an Authentication Key for Teleport
+   yubihsm> put authkey 0 0 "Teleport Auth Key" 1 generate-asymmetric-key:sign-pkcs:sign-pss:sign-ecdsa:delete-asymmetric-key sign-pkcs:sign-pss:decrypt-pkcs:decrypt-oaep:sign-ecdsa
+   Enter password:
    Stored Authentication key 0x85cf
 
    # Make sure you can open a session with the new authentication key and password
-   yubihsm> session open 0x85cf hunter22
+   yubihsm> session open 0x85cf
+   Enter password:
    Created session 1
 
-   # Delete the factory default authentication key
-   yubihsm> delete 0 1 authentication-key
+   # Change the password for the factory default authentication key.
+   # Remember to securely store this password somewhere.
+   yubihsm> change authkey 0 1 authentication-key
+   Enter password:
    ```
 
    Take note of the slot number of the new authentication key.
@@ -294,8 +302,8 @@ auth_service:
       # slot_number should always be set to 0 for YubiHSM2
       slot_number: 0
       # pin should be the (hex) slot number of your authentication key,
-      # concatenated with the password
-      pin: "85cfhunter22"
+      # concatenated with your chosen password
+      pin: "85cfpassword"
       # pin_path can optionally be used to read the pin from a file
       # pin_path: /path/to/pin_file
 ```

diff --git a/docs/pages/reference/signature-algorithms.mdx b/docs/pages/reference/signature-algorithms.mdx
@@ -215,3 +215,63 @@ The signature algorithm suites are designed to simplify the configuration burden
 We did not want to expose 100 configuration knobs to modify every single
 signature Teleport does, which could lead to thousands of possible combinations
 we'd have to support, and could create the possibility for insecure combinations.
+
+### What if my HSM doesn't support ECDSA keys?
+
+If you are using a PKCS#11 HSM that does not support ECDSA keys, we recommend
+you continue to use the `legacy` algorithm suite.
+
+If you have a strong need to have users and hosts use Ed25519 and/or ECDSA keys,
+you could switch to the `hsm-v1` suite, but whenever a new CA key is generated
+it may fail if the CA uses non-RSA keys.
+This may cause the Auth Service to terminate with an error after trying to
+generate the key.
+New CA keys may be generated the first time a new Auth Service starts, when a CA
+rotation is initiated, or during a version upgrade when a new CA has been added
+in the new version.
+For these reasons we recommend continuing to use the `legacy` algorithm suite.
+
+### My YubiHSM2 authentication key does not have capabilities for ECDSA keys, what do I do?
+
+Our [YubiHSM2 guide](../admin-guides/deploy-a-cluster/hsm.mdx) recommends
+creating an
+[authentication key](https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-core-concepts.html#authentication-key)
+to be used by the Teleport Auth Service to authenticate with the YubiHSM2.
+The example in the original version of that guide created an authentication key
+without the necessary
+[capabilities](https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-core-concepts.html#capability)
+to create and sign with ECDSA keys.
+Before upgrading to v17 and/or switching your algorithm suite, we recommend
+creating a new authentication key with the necessary capabilities and updating
+your Auth Service configuration to use the new key.
+The new authentication key will still be able to use your existing CA keys.
+
+To create a new authentication key with `yubihsm-shell`:
+```text
+$ yubihsm-shell
+Using default connector URL: http://localhost:12345
+yubihsm> connect
+Session keepalive set up to run every 15 seconds
+
+# Open a session with an admin authentication key that has capabilities to create
+# new authentication keys. The factory default authentication key has id:1 and
+# password:password. Use the appropriate ID and password if you have changed
+# these parameters.
+yubihsm> session open 1
+Enter password:
+Created session 0
+
+# Create a new authentication key for Teleport.
+yubihsm> put authkey 0 0 "New Teleport Auth Key" 1 generate-asymmetric-key:sign-pkcs:sign-pss:sign-ecdsa:delete-asymmetric-key sign-pkcs:sign-pss:decrypt-pkcs:decrypt-oaep:sign-ecdsa
+Enter password:
+Stored Authentication key 0x1a92
+
+# Make sure you can open a session with the new authentication key and password
+yubihsm> session open 0x1a92
+Enter password:
+Created session 1
+```
+
+Update `auth_service.ca_key_params.pkcs11.pin` or the file referenced by
+`auth_service.ca_key_params.pkcs11.pin_path` to use the ID of the new
+authentication key, then restart the Auth Service.