Hardware Key Support

By default, tsh, Teleport Connect, and other Teleport clients store a user's key and certificates directly on their filesystem. If a user's filesystem is compromised, any of their active Teleport user keys and certificates would also be compromised.

You can configure per-session MFA to require a multi-factor authentication check when users start new sessions with Teleport services, such as the SSH Service, Kubernetes Service, Database Service, and so on. However, per-session MFA doesn't prevent compromised session credentials from taking other actions, such as running administrative commands with tctl.

To prevent these types of attacks, Teleport supports hardware-based private keys. Unlike disk-based private keys, hardware-based private keys are generated and stored directly on a hardware device and are impossible to export. With hardware-based private keys, a login session is only functional if there's also access to the hardware device where the key was generated and stored.

Additionally, you can configure this feature to require a touch for every Teleport request, including non-session requests like tctl edit. With touch required, hardware key support provides better security than per-session MFA.

Prerequisites

• A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial.

• The tctl admin tool and tsh client tool.

  Visit Installation for instructions on downloading tctl and tsh.

• A series 5+ YubiKey

• Install a smart card driver for you operating system. Teleport clients will connect to your YubiKey through the smart card driver to generate keys and perform cryptographic operations.
  • macOS and Windows both ship with smart card drivers.
    • If you run into problems on Windows, try the official YubiKey Smart Card Minidriver.
  • On Linux distributions, download the YubiKey Manager or Yubico PIV tool, which both include the Linux smart card driver as a dependency.
• To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. For example:

  tsh login --proxy=teleport.example.com --user=email@example.com
  tctl status
  Cluster  teleport.example.com
  Version  16.4.7
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

  If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/2. Enforce hardware key support

Hardware key support is not required by default.

There are three primary options for hardware key support:

• hardware_key: User keys are stored on their hardware key without touch/PIN protection. A separate MFA check is used for sessions and other MFA-reliant features, like moderated sessions.
• hardware_key_touch: User keys are stored on their hardware key with touch protection. On each request, users must touch their hardware key.
• hardware_key_touch_and_pin: User keys will be stored on their hardware key with touch and PIN protection. On each request, users must touch their hardware key and enter their PIV pin.
  • Users who have not set a PIV code are prompted to set it during login.

You can enforce hardware key support for specific roles, as shown here:

kind: role
metadata:
  name: admin
spec:
  options:
    require_session_mfa: hardware_key_touch

You can also enforce hardware key support cluster-wide by updating your Teleport configuration:

tctl edit cap

Set the value of spec.require_session_mfa to hardware_key_touch:

kind: cluster_auth_preference
metadata:
  ...
  name: cluster-auth-preference
spec:
  ...
  require_session_mfa: hardware_key_touch
  ...
version: v2

After you save and exit the editor, tctl updates the resource:

cluster auth preference has been updated

Step 2/2. Log in

After you configure a role or cluster to require a hardware key, all users signing in with that role or to that cluster must use their hardware key for all Teleport requests.

Affected users will be prompted to connect and touch their YubiKey to sign in. The first time users sign in with their hardware key they might be required to immediately sign in again.

tsh login --user=dev --proxy=proxy.example.com:3080
Enter password for Teleport user dev:
Unmet private key policy "hardware_key_touch".
Relogging in with hardware-backed private key.
Enter password for Teleport user dev:
Tap your YubiKey
> Profile URL:        https://example.com
Logged in as:       dev
Cluster:            example.com
...

tsh login --user=dev --proxy=proxy.example.com:3080
Enter password for Teleport user dev:
Unmet private key policy "hardware_key_touch".
Relogging in with hardware-backed private key.
Enter password for Teleport user dev:
Tap your YubiKey
> Profile URL:        https://example.com
Logged in as:       dev
Cluster:            example.com
...

tsh login --user=dev --proxy=proxy.example.com:3080
Enter password for Teleport user dev:
Unmet private key policy "hardware_key_touch".
Relogging in with hardware-backed private key.
Enter password for Teleport user dev:
Tap your YubiKey
> Profile URL:        https://example.com
Logged in as:       dev
Cluster:            example.com
...

Affected users with existing sessions that aren't backed by a hardware key are prompted to sign in again on their next request. For example:

tsh clusters
Unmet private key policy "hardware_key_touch"
Relogging in with hardware-backed private key.
Enter password for Teleport user dev:
Tap your YubiKey
Cluster Name Status Cluster Type Labels Selected
----------- ------ ------------ ------ --------
example.com online root                *

Custom PIV setup

Custom PIV Slot

By default, Teleport clients use the following PIV slots for each option:

• hardware_key: slot 9a
• hardware_key_touch: slot 9c
• hardware_key_touch_and_pin: slot 9d
• hardware_key_pin: slot 9e

If you are using any other PIV applications, you might need to specify a different slot. For example, yubikey-agent uses slot 9a. To avoid overwriting the yubikey-agent key and certificate, a user with the hardware_key requirement would need to specify a different slot.

During login, users can specify a PIV slot using the --piv-slot command-line option or an environment variable. For example:

• tsh login --piv-slot=9c
• TELEPORT_PIV_SLOT=9c tsh login

The PIV slot can also be set cluster-wide with a configuration option:

kind: cluster_auth_preference
metadata:
  ...
  name: cluster-auth-preference
spec:
  ...
  require_session_mfa: hardware_key
  hardware_key:
    piv_slot: 9c
  ...
version: v2

Custom Key

Teleport clients generate keys in the slots specified using the default management key.

If your PIV key uses a different management key, you must generate the key yourself. This can be done with the YubiKey Manager CLI:

ykman piv keys generate -a ECCP256 [slot] --touch-policy=[never|cached|always] --pin-policy=[never|once|always] -

After running this command, you're prompted to enter your management key to complete the request. Make sure that the touch and PIN policy satisfy the hardware key requirement for your cluster and roles.

Troubleshooting

ERROR: private key policy not met

This error is returned by the Auth and Proxy services if a user does not meet the required private key policy. Both tsh and Teleport Connect automatically catch these errors and require the user to sign in again with a valid hardware-based private key.

ERROR: authenticating with management key: auth challenge: smart card error 6982: security status not satisfied

Smart card auth challenge errors can appear when the wrong management key is used.

Teleport clients expect a fresh PIV key with the default management key. You can reset this key, along with any existing PIV keys and certificates, with the YubiKey Manager CLI ykman piv reset.

If you want to use a different management key, follow the custom PIV setup instructions.

ERROR: ssh: handshake failed: command failed: transmitting request: an attempt was made to end a non-existent transaction

Sometimes, PIV interactions with your Yubikey can fail in unexpected ways.

For example, if you tap your Yubikey for MFA and then subsequently tap your Yubikey for Hardware Key support, you might get an error on rare occasions.

Why am I being asked to tap several times to login?

Depending on your settings, you might be asked to tap your Yubikey many times. Each tap is necessary to safely authenticate you.

For example, if you have second_factor: webauthn set in your cluster_auth_preference, and require_session_mfa: hardware_key_touch set on your role, you'll see the following output when you first sign in:

tsh login --user=dev --proxy=root.example.com:3080

First login as usual, as the unauthenticated client has no way of inferring
that "hardware_key_touch" is required by the user's role.

Enter password for Teleport user dev:Tap any security keyDetected security key tap
Login results in a "hardware_key_touch" error.

Unmet private key policy "hardware_key_touch".
At this point, `tsh` can infer from the error that the user's role requires
"hardware_key_touch", so it generates a private key directly on the hardware key
with a tap and re-initiates the sign in process.

Relogging in with hardware-backed private key.
This time, `tsh` uses the Yubikey-backed private key in the login request to
get certificates which pass the private key policy for the user's role.

Enter password for Teleport user dev:Tap any security keyDetected security key tapTap your YubiKey> Profile URL:        https://root.example.com:3080  Logged in as:       dev  Cluster:            root.example.com  ...