'\" t
.\"     Title: ssh-tpm-keygen
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.23
.\"      Date: 2025-03-27
.\"    Manual: ssh-tpm-keygen manual
.\"    Source: ssh-tpm-agent
.\"  Language: English
.\"
.TH "SSH\-TPM\-KEYGEN" "1" "2025-03-27" "ssh\-tpm\-agent" "ssh\-tpm\-keygen manual"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
ssh-tpm-keygen \- ssh\-tpm\-agent key creation utility
.SH "SYNOPSIS"
.sp
\fBssh\-tpm\-keygen\fP [\fIOPTIONS\fP]...
.sp
\fBssh\-tpm\-keygen\fP \fB\-\-wrap\fP \fIPATH\fP \fB\-\-wrap\-with\fP \fIPATH\fP
.sp
\fBssh\-tpm\-keygen\fP \fB\-\-import\fP \fIPATH\fP
.sp
\fBssh\-tpm\-keygen\fP \fB\-\-print\-pubkey\fP \fIPATH\fP
.sp
\fBssh\-tpm\-keygen\fP \fB\-\-supported\fP
.sp
\fBssh\-tpm\-keygen\fP \fB\-p\fP [\fB\-f\fP \fIkeyfile\fP] [\fB\-P\fP \fIold passphrase\fP] [\fB\-N\fP \fInew passphrase\fP]
.sp
\fBssh\-tpm\-keygen\fP \fB\-A\fP [\fB\-f\fP \fIpath prefix\fP] [\fB\-\-hierarchy\fP \fIhierarchy\fP]
.SH "DESCRIPTION"
.sp
\fBssh\-tpm\-keygen\fP is a program that allows the creation of TPM wrapped keys for \fBssh\-tpm\-agent\fP.
.SH "OPTIONS"
.sp
\fB\-A\fP
.RS 4
Generate host keys for all key types (rsa and ecdsa).
.RE
.sp
\fB\-b\fP \fIBITS\fP
.RS 4
Number of bits in the key to create.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
rsa: 2048 (default)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
ecdsa: 256 (default) | 384 | 521
.RE
.RE
.sp
\fB\-C\fP \fICOMMENT\fP
.RS 4
Provide a comment with the key.
.RE
.sp
\fB\-f\fP \fIPATH\fP
.RS 4
Output keyfile path.
.RE
.sp
\fB\-N\fP \fIPASSPHRASE\fP
.RS 4
Passphrase for the key.
.RE
.sp
\fB\-o\fP, \fB\-\-owner\-password\fP \fIPASSPHRASE\fP
.RS 4
Ask for the owner password.
.RE
.sp
\fB\-t\fP [\fIecdsa\fP | \fIrsa\fP]
.RS 4
Specify the type of key to create. Defaults to ecdsa
.RE
.sp
\fB\-I\fP, \fB\-\-import\fP \fIPATH\fP
.RS 4
Import existing key into ssh\-tpm\-agent.
.RE
.sp
\fB\-\-parent\-handle\fP \fIHIERARCHY\fP
.RS 4
Parent for the TPM key. Can be a hierarchy or a persistent handle.
.sp
Available hierarchies:
\- owner, o (default)
\- endorsement, e
\- null, n
\- platform, p
.RE
.sp
\fB\-\-print\-pubkey\fP \fIPATH\fP
.RS 4
Print the public key given a TPM private key.
.RE
.sp
\fB\-\-supported\fP
.RS 4
List the supported key types of the TPM.
.RE
.sp
\fB\-\-hierarchy\fP \fIHIERARCHY\fP
.RS 4
Create a public key. Can only be used with \fB\-A\fP.
.sp
See \fBHierarchy Keys\fP in \fBssh\-tpm\-agent\fP(1) for usage.
.sp
Available hierarchies:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
owner, o
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
endorsement, e
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
null, n
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
platform, p
.RE
.RE
.sp
\fB\-\-wrap\fP \fIPATH\fP
.RS 4
A SSH key to wrap for import on remote machine.
.RE
.sp
\fB\-\-wrap\-with\fP \fIPATH\fP
.RS 4
Parent key to wrap the SSH key with.
.RE
.SH "EXAMPLES"
.SS "Key creation"
.sp
Create a key with \fBssh\-tpm\-keygen\fP.
.sp
.if n .RS 4
.nf
.fam C
$ ssh\-tpm\-keygen
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):
Enter same passphrase again:
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:NCMJJ2La+q5tGcngQUQvEOJP3gPH8bMP98wJOEMV564
The key\*(Aqs randomart image is the color of television, tuned to a dead channel.
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
$ cat /home/user/.ssh/id_ecdsa.pub
ecdsa\-sha2\-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBOTOsMXyjTc1wiQSKhRiNhKFsHJNLzLk2r4foXPLQYKR0tuXIBMTQuMmc7OiTgNMvIjMrcb9adgGdT3s+GkNi1g=
.fam
.fi
.if n .RE
.SS "Import existing key"
.sp
Useful if you want to back up the key to a remote secure storage while using the key day\-to\-day from the TPM.
.sp
Create a key, or use an existing one.
.sp
.if n .RS 4
.nf
.fam C
$ ssh\-keygen \-t ecdsa \-f id_ecdsa
Generating public/private ecdsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in id_ecdsa
Your public key has been saved in id_ecdsa.pub
The key fingerprint is:
SHA256:bDn2EpX6XRX5ADXQSuTq+uUyia/eV3Z6MW+UtxjnXvU user@localhost
The key\*(Aqs randomart image is:
+\-\-\-[ECDSA 256]\-\-\-+
|\&           .+=o..|
|\&           o. oo.|
|\&          o... .o|
|\&       . + ..\&  ..|
|\&        S .\&   . o|
|\&       o * . oo=*|
|\&        ..+.oo=+E|
|\&        .++o...o=|
|\&       .++++. .+ |
+\-\-\-\-[SHA256]\-\-\-\-\-+
.fam
.fi
.if n .RE
.sp
Import the key using the \f(CR\-\-import\fP switch.
.sp
.if n .RS 4
.nf
.fam C
$ ssh\-tpm\-keygen \-\-import id_ecdsa
Sealing an existing public/private ecdsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in id_ecdsa.tpm
The key fingerprint is:
SHA256:bDn2EpX6XRX5ADXQSuTq+uUyia/eV3Z6MW+UtxjnXvU
The key\*(Aqs randomart image is the color of television, tuned to a dead channel.
.fam
.fi
.if n .RE
.SS "Create and Wrap private key for client machine on remote srver"
.sp
On the client side create one a primary key under an hierarchy. This example
will use the owner hierarchy with an SRK.
.sp
The output file \f(CRsrk.pem\fP needs to be transferred to the remote end which
creates the key. This could be done as part of client provisioning.
.sp
.if n .RS 4
.nf
.fam C
$ tpm2_createprimary \-C o \-G ecc \-g sha256 \-c prim.ctx \-a \*(Aqrestricted|decrypt|fixedtpm|fixedparent|sensitivedataorigin|userwithauth|noda\*(Aq \-f pem \-o srk.pem
.fam
.fi
.if n .RE
.sp
On the remote end we create a p256 ssh key, with no password, and wrap it with
\f(CRssh\-tpm\-keygen\fP with the \f(CRsrk.pem\fP from the client side.
.sp
.if n .RS 4
.nf
.fam C
$ ssh\-keygen \-t ecdsa \-b 256 \-N "" \-f ./ecdsa.key
.fam
.fi
.if n .RE
.sp
OR with openssl
.sp
.if n .RS 4
.nf
.fam C
$ openssl genpkey \-algorithm EC \-pkeyopt ec_paramgen_curve:prime256v1 \-out ecdsa.key
.fam
.fi
.if n .RE
.sp
Wrap with ssh\-tpm\-keygen
.sp
.if n .RS 4
.nf
.fam C
$ ssh\-tpm\-keygen \-\-wrap\-with srk.pub \-\-wrap ecdsa.key \-f wrapped_id_ecdsa
.fam
.fi
.if n .RE
.sp
On the client side we can unwrap \f(CRwrapped_id_ecdsa\fP to a loadable key.
.sp
.if n .RS 4
.nf
.fam C
$ ssh\-tpm\-keygen \-\-import ./wrapped_id_ecdsa.tpm \-\-output id_ecdsa.tpm
$ ssh\-tpm\-add id_ecdsa.tpm
.fam
.fi
.if n .RE
.SH "FILES"
.sp
\fI~/ssh/id_rsa.tpm\fP, \fI~/ssh/id_ecdsa.tpm\fP
.RS 4
Contains the ssh private keys used by \fBssh\-tpm\-agent\fP. 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.
.RE
.sp
\fI~/ssh/id_rsa.pub\fP, \fI~/ssh/id_ecdsa.pub\fP
.RS 4
Contains the ssh public keys. These can be shared publicly, and is the same format as the ones created by \fBssh\-keygen\fP(1).
.RE
.SH "SEE ALSO"
.sp
\fBssh\-agent\fP(1), \fBssh\fP(1), \fBssh\-tpm\-keygen\fP(1), \fBssh\-keygen\fP(1)
.SH "NOTES, STANDARDS AND OTHER"
.sp
.URL "https://www.hansenpartnership.com/draft\-bottomley\-tpm2\-keys.html" "ASN.1 Specification for TPM 2.0 Key Files" ""