Teleport
Teleport HSM Support
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
This guide will show you how to set up the Teleport Auth Service to use a hardware security module (HSM) to store and handle private keys.
Prerequisites
- Teleport v16.4.2 Enterprise (self-hosted).
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.4.2
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions. - An HSM reachable from your Teleport auth server.
- The PKCS#11 module for your HSM.
Teleport Cloud and Teleport Open Source do not currently support HSMs or Key Management Services.
While most PKCS#11 HSMs should be supported, the Teleport team tests with AWS CloudHSM, YubiHSM2, and SoftHSM2.
Step 1/5. Set up your HSM
You will need to set up your HSM and make sure that it is accessible from your Teleport Auth Server. You should create a unique HSM user or token for Teleport to use.
-
Create a CloudHSM cluster in the VPC where you will run your Teleport Auth Server. https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster.html
-
Wait for the newly created cluster to enter the "Uninitialized" state.
-
Add an HSM to the new cluster, using the AWS Console or the AWS CLI:
aws --region region cloudhsmv2 create-hsm --cluster-id cluster ID --availability-zone availability zone{ "Hsm": { "AvailabilityZone": "ca-central-1a", "ClusterId": "cluster-6uysmebmutd", "SubnetId": "subnet-0c535b67a117f7186", "HsmId": "hsm-ppzzfxbleki", "State": "CREATE_IN_PROGRESS" }} -
Optionally verify the identity and authenticity of your new HSM https://docs.aws.amazon.com/cloudhsm/latest/userguide/verify-hsm-identity.html
-
Wait for the state of the HSM to become
ACTIVE
:aws --region region cloudhsmv2 describe-clusters --filters clusterIds=cluster ID \ --query 'Clusters[].Hsms[].State' -
To initialize the cluster, you must download and sign a certificate signing request (CSR) that is generated by the cluster's first HSM. Download the CSR from the AWS Console or via the AWS CLI:
aws --region region cloudhsmv2 describe-clusters --filters clusterIds=cluster ID \ --query 'Clusters[].Certificates.ClusterCsr' --output text \ > ClusterCsr.csr -
Choose an appropriate RSA 2048 or RSA 4096 key and self-signed certificate to sign the HSM CSR. For a production cluster, AWS recommends a secured offsite and offline HSM. For a demonstration or test cluster, you can create a key and self-signed certificate with the following
openssl
commands:openssl genrsa -aes256 -out customerCA.key 2048openssl req -new -x509 -days 3652 -key customerCA.key -out customerCA.crt -
Sign the cluster CSR using the key and self-signed cert from the previous step. A demonstration
openssl
command to sign the CSR is:openssl x509 -req -days 3652 -in ClusterCsr.csr \ -CA customerCA.crt \ -CAkey customerCA.key \ -CAcreateserial \ -out CustomerHsmCertificate.crt -
Initialize the CloudHSM cluster by uploading the signed cert to the AWS Console or with the following AWS CLI command:
aws --region region cloudhsmv2 initialize-cluster --cluster-id cluster ID \ --signed-cert file://CustomerHsmCertificate.crt \ --trust-anchor file://customerCA.crt{ "State": "INITIALIZE_IN_PROGRESS", "StateMessage": "Cluster is initializing. State will change to INITIALIZED upon completion."} -
A security group with the same name as your CloudHSM cluster will have been automatically created when you created the cluster. Attach this security group to the EC2 instance where you will run your Teleport Auth Server to allow traffic between the Auth Server and your HSM.
-
On the Auth Server EC2 instance, install the CloudHSM CLI for the CloudHSM Client SDK 5. https://docs.aws.amazon.com/cloudhsm/latest/userguide/gs_cloudhsm_cli-install.html
Bootstrap the CLI by configuring the IP address of the new HSM:
sudo /opt/cloudhsm/bin/configure-cli -a HSM IP address -
Copy the self-signed certificate from step 6 (
customerCA.crt
) to the EC2 instance, save it at/opt/cloudhsm/etc/customerCA.crt
. -
Activate the CloudHSM cluster with the CloudHSM CLI by creating an admin user with a new password:
$ sudo /opt/cloudhsm/bin/cloudhsm-cli interactive aws-cloudhsm > cluster activate Enter password: Confirm password: { "error_code": 0, "data": "Cluster activation successful" }
-
Login to the CloudHSM CLI as the new admin user and create a Crypto User to be used by Teleport. Remember this new password because Teleport will use it later to authenticate to the PKCS#11 library.
aws-cloudhsm > login --username admin --role admin Enter password: { "error_code": 0, "data": { "username": "admin", "role": "admin" } } aws-cloudhsm > user create --username teleport --role crypto-user Enter password: Confirm password: { "error_code": 0, "data": { "username": "teleport", "role": "crypto-user" } } aws-cloudhsm > quit
-
Install the PKCS#11 library for the Client SDK 5 on the same Auth Server EC2 instance https://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-library-install.html
Bootstrap the PKCS#11 library by configuring the HSM IP address. If you only have one HSM in the cluster, you must include the
--disable-key-availability-check
flag.sudo /opt/cloudhsm/bin/configure-pkcs11 --disable-key-availability-check -a HSM IP address
-
Install the YubiHSM2 SDK.
-
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.yubihsm-connector -dDEBU[0000] preflight complete cert= config= key= pid=73502 seccomp=false serial= syslog=false timeout=0s version=3.0.3DEBU[0000] takeoff TLS=false listen="localhost:12345" pid=73502 -
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 must have at least 8 characters. The example
hunter22
is used here.$ 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 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 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. -
Create a
yubihsm_pkcs11.conf
file to configure the address and port thatyubihsm-connector
is listening on and enable debug logging:# /etc/yubihsm_pkcs11.conf connector = https://127.0.0.1:12345 debug
-
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.export YUBIHSM_PKCS11_CONF=/etc/yubihsm_pkcs11.conf
Step 2/5. Configure Teleport
To configure Teleport to use an HSM for all CA private key generation, storage,
and signing, include the ca_key_params
section in /etc/teleport.yaml
on the
auth server.
# /etc/teleport.yaml
teleport:
...
auth_service:
enabled: true
...
ca_key_params:
pkcs11:
# this is the default install location of the PKCS#11 module for the
# CloudHSM Client SDK 5
module_path: /opt/cloudhsm/lib/libcloudhsm_pkcs11.so
# token_label should always be "hsm1" for the CloudHSM SDK 5
# if you prefer to use SDK version 3, replace this with "cavium"
token_label: "hsm1"
# pin should be set to the username and password of the Crypto User
# created earlier in the guide
pin: "<CU_username>:<CU_password>"
# pin_path can optionally be used to read the pin from a file
# pin_path: /path/to/pin_file
# /etc/teleport.yaml
teleport:
...
auth_service:
enabled: true
...
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 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"
# pin_path can optionally be used to read the pin from a file
# pin_path: /path/to/pin_file
Step 3/5. (Re)start Teleport Auth
If this is a new Teleport Auth Service which has not been started yet, starting a brand new cluster with an empty backend, HSM keys will be automatically generated at startup and no further action is required, skip to step 5. Otherwise, continue reading.
If you are connecting an HSM to an existing Teleport cluster, restart the auth server for the configuration changes to take effect. New CA keys will automatically be generated in the HSM during the next CA rotation. Until a CA rotation is completed, the Auth Service will continue signing new certificates with the existing software keys.
Step 4/5. Certificate Rotation with HSM
When adding a new HSM to an existing Teleport cluster, or adding a new HSM-connected Auth Service to an HA Teleport cluster, you will need to rotate all Certificate Authorities in order for new certificates to be issued and trusted.
teleport start
will print a warning during startup if any CA needs to be rotated.
Any users allowed the update
verb for cert_authority
resources in any of
their Teleport roles will also see a cluster alert reminding them to rotate the
CAs.
CA rotation can be performed manually or semi-automatically, see our admin guide
on Certificate rotation.
All CAs listed in the output of tctl status
must be rotated.
Step 5/5. Confirm that Teleport is using your HSM
You are all set! Check the teleport logs for Creating new HSM key pair
to
confirm that the feature is working. You can also check that keys were created
in your HSM using your HSM's admin tool.