@node tpmtool Invocation

@subsection Invoking tpmtool

@pindex tpmtool

@ignore

#  -*- buffer-read-only: t -*- vi: set ro:

#

# DO NOT EDIT THIS FILE   (invoke-tpmtool.texi)

#

# It has been AutoGen-ed

# From the definitions    ../src/tpmtool-args.def

# and the template file   agtexi-cmd.tpl

@end ignore

Program that allows handling cryptographic data from the TPM chip.

This section was generated by @strong{AutoGen},

using the @code{agtexi-cmd} template and the option descriptions for the @code{tpmtool} program.

This software is released under the GNU General Public License, version 3 or later.

@anchor{tpmtool usage}

@subheading tpmtool help/usage (@option{--help})

@cindex tpmtool help

This is the automatically generated usage text for tpmtool.

The text printed is the same whether selected with the @code{help} option

(@option{--help}) or the @code{more-help} option (@option{--more-help}).  @code{more-help} will print

the usage text by passing it through a pager program.

@code{more-help} is disabled on platforms without a working

@code{fork(2)} function.  The @code{PAGER} environment variable is

used to select the program, defaulting to @file{more}.  Both will exit

with a status code of 0.

@exampleindent 0

@example

tpmtool - GnuTLS TPM tool

Usage:  tpmtool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]...

   -d, --debug=num            Enable debugging

                                - it must be in the range:

                                  0 to 9999

       --infile=file          Input file

                                - file must pre-exist

       --outfile=str          Output file

       --generate-rsa         Generate an RSA private-public key pair

       --register             Any generated key will be registered in the TPM

                                - requires the option 'generate-rsa'

       --signing              Any generated key will be a signing key

                                - requires the option 'generate-rsa'

                                -- and prohibits the option 'legacy'

       --legacy               Any generated key will be a legacy key

                                - requires the option 'generate-rsa'

                                -- and prohibits the option 'signing'

       --user                 Any registered key will be a user key

                                - requires the option 'register'

                                -- and prohibits the option 'system'

       --system               Any registered key will be a system key

                                - requires the option 'register'

                                -- and prohibits the option 'user'

       --pubkey=str           Prints the public key of the provided key

       --list                 Lists all stored keys in the TPM

       --delete=str           Delete the key identified by the given URL (UUID).

       --test-sign=str        Tests the signature operation of the provided object

       --sec-param=str        Specify the security level [low, legacy, medium, high, ultra].

       --bits=num             Specify the number of bits for key generate

       --inder                Use the DER format for keys.

                                - disabled as '--no-inder'

       --outder               Use DER format for output keys

                                - disabled as '--no-outder'

       --srk-well-known       SRK has well known password (20 bytes of zeros)

   -v, --version[=arg]        output version information and exit

   -h, --help                 display extended usage information and exit

   -!, --more-help            extended usage information passed thru pager

Options are specified by doubled hyphens and their name or by a single

hyphen and the flag character.

Program that allows handling cryptographic data from the TPM chip.

@end example

@exampleindent 4

@anchor{tpmtool debug}

@subheading debug option (-d)

This is the ``enable debugging'' option.

This option takes a number argument.

Specifies the debug level.

@anchor{tpmtool generate-rsa}

@subheading generate-rsa option

This is the ``generate an rsa private-public key pair'' option.

Generates an RSA private-public key pair in the TPM chip. 

The key may be stored in file system and protected by a PIN, or stored (registered)

in the TPM chip flash.

@anchor{tpmtool user}

@subheading user option

This is the ``any registered key will be a user key'' option.

@noindent

This option has some usage constraints.  It:

@itemize @bullet

@item

must appear in combination with the following options:

register.

@item

must not appear in combination with any of the following options:

system.

@end itemize

The generated key will be stored in a user specific persistent storage.

@anchor{tpmtool system}

@subheading system option

This is the ``any registered key will be a system key'' option.

@noindent

This option has some usage constraints.  It:

@itemize @bullet

@item

must appear in combination with the following options:

register.

@item

must not appear in combination with any of the following options:

user.

@end itemize

The generated key will be stored in system persistent storage.

@anchor{tpmtool test-sign}

@subheading test-sign option

This is the ``tests the signature operation of the provided object'' option.

This option takes a string argument @file{url}.

It can be used to test the correct operation of the signature operation.

This operation will sign and verify the signed data.

@anchor{tpmtool sec-param}

@subheading sec-param option

This is the ``specify the security level [low, legacy, medium, high, ultra].'' option.

This option takes a string argument @file{Security parameter}.

This is alternative to the bits option. Note however that the

values allowed by the TPM chip are quantized and given values may be rounded up.

@anchor{tpmtool inder}

@subheading inder option

This is the ``use the der format for keys.'' option.

@noindent

This option has some usage constraints.  It:

@itemize @bullet

@item

can be disabled with --no-inder.

@end itemize

The input files will be assumed to be in the portable

DER format of TPM. The default format is a custom format used by various

TPM tools

@anchor{tpmtool outder}

@subheading outder option

This is the ``use der format for output keys'' option.

@noindent

This option has some usage constraints.  It:

@itemize @bullet

@item

can be disabled with --no-outder.

@end itemize

The output will be in the TPM portable DER format.

@anchor{tpmtool srk-well-known}

@subheading srk-well-known option

This is the ``srk has well known password (20 bytes of zeros)'' option.

This option has no @samp{doc} documentation.

@anchor{tpmtool exit status}

@subheading tpmtool exit status

One of the following exit values will be returned:

@table @samp

@item 0 (EXIT_SUCCESS)

Successful program execution.

@item 1 (EXIT_FAILURE)

The operation failed or the command syntax was not valid.

@end table

@anchor{tpmtool See Also}

@subheading tpmtool See Also

    p11tool (1), certtool (1)

@anchor{tpmtool Examples}

@subheading tpmtool Examples

To generate a key that is to be stored in file system use:

@example

$ tpmtool --generate-rsa --bits 2048 --outfile tpmkey.pem

@end example

To generate a key that is to be stored in TPM's flash use:

@example

$ tpmtool --generate-rsa --bits 2048 --register --user

@end example

To get the public key of a TPM key use:

@example

$ tpmtool --pubkey tpmkey:uuid=58ad734b-bde6-45c7-89d8-756a55ad1891;storage=user \

          --outfile pubkey.pem

@end example

or if the key is stored in the file system:

@example

$ tpmtool --pubkey tpmkey:file=tmpkey.pem --outfile pubkey.pem

@end example

To list all keys stored in TPM use:

@example

$ tpmtool --list

@end example