SSH-TPM-AGENT(1) ssh-tpm-agent manual SSH-TPM-AGENT(1)

ssh-tpm-agent - ssh-agent for TPM 2.0 keys

ssh-tpm-agent [OPTIONS]

ssh-tpm-agent --print-socket

ssh-tpm-agent --install-user-units

ssh-tpm-agent is a program that created keys utilizing a Trusted Platform Module (TPM) to enable wrapped private keys for public key authentication.

-l PATH

Path of the UNIX socket to open

Defaults to $XDG_RUNTIME_DIR/ssh-tpm-agent.sock.

-A PATH

Fallback ssh-agent sockets for additional key lookup.

--print-socket

Prints the socket to STDIN.

--key-dir PATH

Path of the directory to look for TPM sealed keys in.

Defaults to ~/.ssh.

--no-load

Do not load TPM sealed keys from ~/.ssh by default.

-o, --owner-password

Ask for the owner password.

--no-cache

The agent will not cache key passwords.

--hierarchy HIERARCHY

Preload hierarchy keys into the agent.

See Hierarchy Keys for more information.

Available hierarchies:

•owner, o
•endorsement, e
•null, n
•platform, p

-d

Enable debug logging.

--install-user-units

Installs systemd system units and sshd configs for using ssh-tpm-agent as a hostkey agent.

--swtpm

Stores keys inside a swtpm instance instead of the actual TPM. This is not a security feature and your keys are not stored securely.

Can also be enabled with the environment variable SSH_TPM_AGENT_SWTPM.

ssh-tpm-agent can be used as a dropin replacement to ssh-agent and works the same way.

$ ssh-tpm-keygen
# Add ~/.ssh/id_ecdsa.pub to your Github accounts
$ ssh-tpm-agent &
$ export SSH_AUTH_SOCK=$(ssh-tpm-agent --print-socket)
$ ssh git@github.com

See ssh-tpm-keygen(1) for keygen usage.

ssh-tpm-agent supports fallback to different ssh-agent. Agents can be added with the -A switch. This will cause ssh-tpm-agent to fan-out to all available agents for keys.

This is practical if you have multiple keys from different agent implementations but want to rely on one socket.

# Start the usual ssh-agent
$ eval $(ssh-agent)
# Create a strong RSA key
$ ssh-keygen -t rsa -b 4096 -f id_rsa -C ssh-agent
...
The key fingerprint is:
SHA256:zLSeyU/6NKHGEvyZLA866S1jGqwdwdAxRFff8Z2N1i0 ssh-agent
$ ssh-add id_rsa
Identity added: id_rsa (ssh-agent)
# Print looonnggg key
$ ssh-add -L
ssh-rsa AAAAB3NzaC1yc[...]8TWynQ== ssh-agent
# Create key on the TPM
$ ssh-tpm-keygen -C ssh-tpm-agent
Generating a sealed public/private ecdsa key pair.
Enter file in which to save the key (/home/user/.ssh/id_ecdsa):
Enter passphrase (empty for no passphrase):
Confirm passphrase:
Your identification has been saved in /home/user/.ssh/id_ecdsa.tpm
Your public key has been saved in /home/user/.ssh/id_ecdsa.pub
The key fingerprint is:
SHA256:PoQyuzOpEBLqT+xtP0dnvyBVL6UQTiQeCWN/EXIxPOo
The key's randomart image is the color of television, tuned to a dead channel.
# Start ssh-tpm-agent with a proxy socket
$ ssh-tpm-agent -A "${SSH_AUTH_SOCK}" &
$ export SSH_AUTH_SOCK="$(ssh-tpm-agent --print-socket)"
# ssh-tpm-agent is proxying the keys from ssh-agent
$ ssh-add -L
ssh-rsa AAAAB3NzaC1yc[...]8TWynQ== ssh-agent
ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNo[...]q4whro= ssh-tpm-agent

ssh-tpm-agent can also be used to serve host keys for an ssh server. ssh-tpm-hostkeys has convenient flags to help install systemd configurations and services to the system. This will create a system socket for ssh-tpm-agent under /var/tmp/ssh-tpm-agent.sock.

$ sudo ssh-tpm-keygen -A
2023/09/03 17:03:08 INFO Generating new ECDSA host key
2023/09/03 17:03:08 INFO Wrote /etc/ssh/ssh_tpm_host_ecdsa_key.tpm
2023/09/03 17:03:08 INFO Generating new RSA host key
2023/09/03 17:03:15 INFO Wrote /etc/ssh/ssh_tpm_host_rsa_key.tpm
$ sudo ssh-tpm-hostkeys --install-system-units
Installed /usr/lib/systemd/system/ssh-tpm-agent.service
Installed /usr/lib/systemd/system/ssh-tpm-agent.socket
Installed /usr/lib/systemd/system/ssh-tpm-genkeys.service
Enable with: systemctl enable --now ssh-tpm-agent.socket
$ sudo ssh-tpm-hostkeys --install-sshd-config
Installed /etc/ssh/sshd_config.d/10-ssh-tpm-agent.conf
Restart sshd: systemd restart sshd
$ systemctl enable --now ssh-tpm-agent.socket
$ systemd restart sshd
$ sudo ssh-tpm-hostkeys
ecdsa-sha2-nistp256 AAAAE2V[...]YNwqWY0= root@localhost
ssh-rsa AAAAB3NzaC1ycA[...]N1Jg3fLQKSe7f root@localhost
$ ssh-keyscan -t ecdsa localhost
# localhost:22 SSH-2.0-OpenSSH_9.4
localhost ecdsa-sha2-nistp256 AAAAE2V[...]YNwqWY0=

Alternatively one can omit the embedded install flags and just include a drop-in configuration for sshd under /etc/ssh/sshd_config.d with the following content.

HostKeyAgent /var/tmp/ssh-tpm-agent.sock
HostKey /etc/ssh/ssh_tpm_host_ecdsa_key.pub
HostKey /etc/ssh/ssh_tpm_host_rsa_key.pub

TPMs are capable of creating static keys utilizing the top-level hierarchies. This enables the user to create keys that are available for the lifetime of the device, for the current owner of the device, or the current session of the device. These keys do not leave the TPM, like other keys created by ssh-tpm-keygen, and can always be recreated.

These keys can be preloaded into ssh-tpm-agent.

$ ssh-tpm-agent --hierarchy owner &
$ export SSH_AUTH_SOCK="$(ssh-tpm-agent --print-socket)"
$ ssh-add -l
2048 SHA256:yt7A20tcRnzgaD2ATgAXSNWy9sP6wznysp3SkoK3Gj8 Owner hierarchy key (RSA)
256 SHA256:PmEsMeh/DwFP04iUaWLNeX4maMR6r1vfqw1BbbdFjIg Owner hierarchy key (ECDSA)

For usage with sshd the public part of these keys can be created by combining -A with --hierarchy.

$ ssh-tpm-keygen -A --hierarchy owner
2025/03/10 21:57:08 INFO Generating new hierarcy host key algorithm=RSA hierarchy=owner
2025/03/10 21:57:10 INFO Wrote public key filename=/etc/ssh/ssh_tpm_host_rsa_key.pub
2025/03/10 21:57:10 INFO Generating new hierarcy host key algorithm=ECDSA hierarchy=owner
2025/03/10 21:57:10 INFO Wrote public key filename=/etc/ssh/ssh_tpm_host_ecdsa_key.pub

These files can be used with HostKey as normal in ssh_config.

The different key hierarchies have different properties and lifetimes.

endorsement hierarchy stores keys created for the lifetime of the device. This hierarchy should not change during the lifetime of the device.

owner hierarchy stores keys created for the device owner. These keys will be rotated when tpm2_clear(1) is issued on the platform, which should be done when the device gets a new owner.

null hierarchy stores keys created for the current session. The session should be a power cycle of the devices.

Note: This feature is experimental. ssh-tpm-agent keeps the TPM objects loaded while running. Some TPM devices run out of memory if you attempt to use the hierarchy keys with the usual keys created by ssh-tpm-keygen.

SSH_TPM_AUTH_SOCK

Identifies the path of a unix-domain socket for communication with the agent.

Default to /var/tmp/ssh-tpm-agent.sock.

SSH_ASKPASS

If ssh-tpm-agent, and other binaries, needs to read a password it will default to using the terminal if it can. If there is no terminal available it will fall back to calling the binary SSH_ASKPASS point at.

See ssh(1) under ENVIRONMENT for more information.

SSH_ASKPASS_REQUIRE

Allows control of the use of the askpass program. Valid values are:
•never ensures ssh will never try to use the askpass program.
•prefer will prefer to use the askpass program.
•force will ensure all passphrase inputs will be using the askpass program.

See ssh(1) under ENVIRONMENT for more information.

SSH_TPM_AGENT_SWTPM

Specify if ssh-tpm-agent should use the swtpm backend or not. Accepts any non-empty value as true.

SSH_TPM_LANDLOCK

If set then ssh-tpm-agent, and the other binaries, will enforce the landlock sandbox where applicable.

Disabled by default.

See landlock(7) for more information.

~/ssh/id_rsa.tpm, ~/ssh/id_ecdsa.tpm

Contains the ssh private keys used by ssh-tpm-agent. They are TPM 2.0 TSS key files and securely wrapped by the TPM. They can be shared publicly as they can only be used by the TPM they where created on. However it is probably better to not do that.

~/ssh/id_rsa.pub, ~/ssh/id_ecdsa.pub

Contains the ssh public keys. These can be shared publicly, and is the same format as the ones created by ssh-keygen(1).

/run/user/$UID/ssh-tpm-agent.sock

The default user ssh-tpm-agent UNIX socket path. Used by induvidual users.

/var/tmp/ssh-tpm-agent.sock

The default system ssh-tpm-agent UNIX socket path. Used for host keys and the system.

ssh-agent(1), ssh(1), ssh-tpm-keygen(1), ssh-keygen(1)

ASN.1 Specification for TPM 2.0 Key Files https://www.hansenpartnership.com/draft-bottomley-tpm2-keys.html

Store ssh keys inside the TPM: ssh-tpm-agent https://linderud.dev/blog/store-ssh-keys-inside-the-tpm-ssh-tpm-agent/

2025-03-27 ssh-tpm-agent