SSH-TPM-KEYGEN(1)

NAME
ssh-tpm-keygen - ssh-tpm-agent key creation utility

SYNOPSIS

ssh-tpm-keygen [OPTIONS]...

ssh-tpm-keygen --wrap PATH --wrap-with PATH

ssh-tpm-keygen --import PATH

ssh-tpm-keygen --print-pubkey PATH

ssh-tpm-keygen --supported

ssh-tpm-keygen -p [-f keyfile] [-P old passphrase] [-N new passphrase]

ssh-tpm-keygen -A [-f path prefix] [--hierarchy hierarchy]

DESCRIPTION

ssh-tpm-keygen is a program that allows the creation of TPM wrapped keys for ssh-tpm-agent.

OPTIONS

-A
    Generate host keys for all key types (rsa and ecdsa).

-b BITS
    Number of bits in the key to create.

        • rsa: 2048 (default)

        • ecdsa: 256 (default) | 384 | 521

-C COMMENT
    Provide a comment with the key.

-f PATH
    Output keyfile path.

-N PASSPHRASE
    Passphrase for the key.

-o, --owner-password PASSPHRASE
    Ask for the owner password.

-t [ecdsa | rsa]
    Specify the type of key to create. Defaults to ecdsa

-I, --import PATH
    Import existing key into ssh-tpm-agent.

--parent-handle HIERARCHY
    Parent for the TPM key. Can be a hierarchy or a persistent handle.

    Available hierarchies: - owner, o (default) - endorsement, e - null, n - platform, p

--print-pubkey PATH
    Print the public key given a TPM private key.

--supported
    List the supported key types of the TPM.

--hierarchy HIERARCHY
    Create a public key. Can only be used with -A.

    See Hierarchy Keys in ssh-tpm-agent(1) for usage.

    Available hierarchies:

        • owner, o

        • endorsement, e

        • null, n

        • platform, p

--wrap PATH
    A SSH key to wrap for import on remote machine.

--wrap-with PATH
    Parent key to wrap the SSH key with.

EXAMPLES

  Key creation

Create a key with ssh-tpm-keygen.

    $ 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's randomart image is the color of television, tuned to a dead channel.

    $ cat /home/user/.ssh/id_ecdsa.pub
    ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBOTOsMXyjTc1wiQSKhRiNhKFsHJNLzLk2r4foXPLQYKR0tuXIBMTQuMmc7OiTgNMvIjMrcb9adgGdT3s+GkNi1g=

  Import existing key

Useful if you want to back up the key to a remote secure storage while using the key day-to-day from the TPM.

Create a key, or use an existing one.

    $ 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's randomart image is:
    +---[ECDSA 256]---+
    |           .+=o..|
    |           o. oo.|
    |          o... .o|
    |       . + ..  ..|
    |        S .   . o|
    |       o * . oo=*|
    |        ..+.oo=+E|
    |        .++o...o=|
    |       .++++. .+ |
    +----[SHA256]-----+

Import the key using the --import switch.

    $ 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's randomart image is the color of television, tuned to a dead channel.

  Create and Wrap private key for client machine on remote srver

On the client side create one a primary key under an hierarchy. This example will use the owner hierarchy with an SRK.

The output file srk.pem needs to be transferred to the remote end which creates the key. This could be done as part of client provisioning.

    $ tpm2_createprimary -C o -G ecc -g sha256 -c prim.ctx -a 'restricted|decrypt|fixedtpm|fixedparent|sensitivedataorigin|userwithauth|noda' -f pem -o srk.pem

On the remote end we create a p256 ssh key, with no password, and wrap it with ssh-tpm-keygen with the srk.pem from the client side.

    $ ssh-keygen -t ecdsa -b 256 -N "" -f ./ecdsa.key

OR with openssl

    $ openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:prime256v1 -out ecdsa.key

Wrap with ssh-tpm-keygen

    $ ssh-tpm-keygen --wrap-with srk.pub --wrap ecdsa.key -f wrapped_id_ecdsa

On the client side we can unwrap wrapped_id_ecdsa to a loadable key.

    $ ssh-tpm-keygen --import ./wrapped_id_ecdsa.tpm --output id_ecdsa.tpm
    $ ssh-tpm-add id_ecdsa.tpm

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).

SEE ALSO

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

NOTES, STANDARDS AND OTHER