Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[v14] docs: clarify upgrade path for YubiHSM2 users #49025

Merged
merged 1 commit into from
Nov 15, 2024
Merged

[v14] docs: clarify upgrade path for YubiHSM2 users #49025

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/cspell.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -317,7 +317,7 @@
"certificatekey",
"certificatesigningrequest",
"certutil",
"cfhunter",
"cfpassword",
"cfsdf",
"cgroups",
"cgroupv",
Expand Down
32 changes: 20 additions & 12 deletions docs/pages/admin-guides/deploy-a-cluster/hsm.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,33 +186,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.
Expand Down Expand Up @@ -291,8 +299,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
```
Expand Down
Loading