SSH-TPM-AGENT(1) ssh-tpm-agent manual SSH-TPM-AGENT(1) NAME ssh-tpm-agent - ssh-agent for TPM 2.0 keys SYNOPSIS ssh-tpm-agent [OPTIONS] ssh-tpm-agent --print-socket ssh-tpm-agent --install-user-units DESCRIPTION ssh-tpm-agent is a program that created keys utilizing a Trusted Platform Module (TPM) to enable wrapped private keys for public key authentication. OPTIONS -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: o owner, o o endorsement, e o null, n o 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. EXAMPLES Normal agent usage 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. Agent fallback support 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 Hostkeys usage 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 Hierarchy keys 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. ENVIRONMENT 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: o never ensures ssh will never try to use the askpass program. o prefer will prefer to use the askpass program. o 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. FILES ~/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. SEE ALSO ssh-agent(1), ssh(1), ssh-tpm-keygen(1), ssh-keygen(1) NOTES, STANDARDS AND OTHER ASN.1 Specification for TPM 2.0 Key Files Store ssh keys inside the TPM: ssh-tpm-agent ssh-tpm-agent 2025-03-27 SSH-TPM-AGENT(1)