Trusted Platform Module/SSH

From Gentoo Wiki
Jump to:navigation Jump to:search

A TPM can be used to store SSH private keys, making them harder to steal. This mechanism is much more secure than using filesystem permissions, and is comparable in security to encrypting the keyfile, with different considerations.

SSH can be configured to read PKCS 11 keys from the TPM using libtpm_pkcs11.


USE Flags

USE flags for net-misc/openssh Port of OpenBSD's free SSH release

audit Enable support for Linux audit subsystem using sys-process/audit
debug Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see
kerberos Add kerberos support
ldns Use LDNS for DNSSEC/SSHFP validation.
libedit Use the libedit library (replacement for readline)
livecd Enable root password logins for live-cd environment.
pam Add support for PAM (Pluggable Authentication Modules) - DANGEROUS to arbitrarily flip
pie Build programs as Position Independent Executables (a security hardening technique)
security-key Include builtin U2F/FIDO support
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
ssl Enable additional crypto algorithms via OpenSSL
static !!do not set this during bootstrap!! Causes binaries to be statically linked instead of dynamically
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
verify-sig Verify upstream signatures on distfiles
xmss Enable XMSS post-quantum authentication algorithm

USE flags for app-crypt/tpm2-pkcs11 A PKCS#11 interface for TPM2 hardware

fapi Enable feature API backend
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)

USE flags for app-crypt/tpm2-tss TCG Trusted Platform Module 2.0 Software Stack

doc Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
fapi Enable feature API (requires openssl as crypto backend)
mbedtls Use net-libs/mbedtls as crypto engine
openssl Use dev-libs/openssl as crypto engine
policy Enable policy library (requires openssl as crypto backend)
static-libs Build static versions of dynamic libraries as well
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)


root #emerge --ask app-crypt/tpm2-pkcs11
root #emerge --ask app-crypt/tpm2-tss
root #emerge --ask net-misc/openssh
root #emerge --ask sys-apps/dbus




Add dbus and tpm2-abrmd to the default runlevel on OpenRC systems:

root #rc-update add dbus default
root #rc-update add tpm2-abrmd default
root #rc-service dbus start
root #rc-service tpm2-abrmd start

User groups

Users must be added to the tss group to use the TPM's stored keys:

root #gpasswd -a larry tss

Key Creation

Then, as the user, create a new primary, token & private key. There is debate about whether it is better to create the private key in software and import it (easier to audit and trust the creation). Or create the private key on the TPM so it never touches the disk. For this example, create the private key via the TPM.

user $tpm2_ptool init
user $tpm2_ptool addtoken --pid=1 --label=ssh --userpin=PasswordRequiredToUsekey --sopin=AdminPasswordForUncommonModifications
user $tpm2_ptool addkey --label=ssh --userpin=PasswordrequiredToUseKey --algorithm=ecc256

RSA and different key sizes are available. Find a complete list in the source.

--userpin can be set to an empty string to mimic the behavior of an SSH key that doesn't have password protection. But leaving it empty means the physical theft of the computer can allow an attacker to use the SSH private key through possession of the TPM alone. Setting a password achieves two factors of authentication, something you have (TPM) and something you know (password).


Using the TPM by default

To configure SSH to try to use TPM keys by default:

FILE ~/.ssh/config
PKCS11Provider /usr/lib64/pkcs11/

This directive could also be added to specific hosts like:

FILE ~/.ssh/config
Host ExampleHost
    PKCS11Provider /usr/lib64/pkcs11/


Reading public keys

To retrieve the public key from the TPM, run:

user $ssh-keygen -D /usr/lib64/pkcs11/

These key fingerprints can be copied to the ~/.ssh/authorized_keys file like with other SSH keys.

At this time, ssh-copy-id does not work with

Using keys

To use the TPM key for a single SSH connection:

user $ssh -I /usr/lib64/pkcs11/

SSH agent

To load the key into the SSH agent:

user $ssh-add -s /usr/lib64/pkcs11/
This command is necessary every time the system reboots or the ssh-agent session expires, if configured to expire.

See Also

  • SSH — the ubiquitous tool for logging into and working on remote machines securely.
  • YubiKey/SSH — YubiKeys can be configured to authenticate SSH connections