diff options
Diffstat (limited to 'doc/invoke-tpmtool.texi')
| -rw-r--r-- | doc/invoke-tpmtool.texi | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/doc/invoke-tpmtool.texi b/doc/invoke-tpmtool.texi new file mode 100644 index 0000000..053a2a1 --- /dev/null +++ b/doc/invoke-tpmtool.texi @@ -0,0 +1,203 @@ +@node tpmtool Invocation +@subsection Invoking tpmtool +@pindex tpmtool + +Program that allows handling cryptographic data from the TPM chip. + +@anchor{tpmtool usage} +@subsubheading tpmtool help/usage (@option{-?}) +@cindex tpmtool help + +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>] ]... + +None: + + -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 + - prohibits the option 'legacy' + - requires the option 'generate-rsa' + --legacy Any generated key will be a legacy key + - prohibits the option 'signing' + - requires the option 'generate-rsa' + --user Any registered key will be a user key + - prohibits the option 'system' + - requires the option 'register' + --system Any registered key will be a system key + - prohibits the option 'user' + - requires the option 'register' + --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 + --outder Use DER format for output keys + --srk-well-known SRK has well known password (20 bytes of zeros) + +Version, usage and configuration options: + + -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. + +Please send bug reports to: <bugs@@gnutls.org> + +@end example +@exampleindent 4 + +@subsubheading debug option (-d). +@anchor{tpmtool debug} + +This is the ``enable debugging'' option. +This option takes a ArgumentType.NUMBER argument. +Specifies the debug level. +@subsubheading generate-rsa option. +@anchor{tpmtool generate-rsa} + +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. +@subsubheading user option. +@anchor{tpmtool user} + +This is the ``any registered key will be a user key'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +system. +@item +must appear in combination with the following options: +register. +@end itemize + +The generated key will be stored in a user specific persistent storage. +@subsubheading system option. +@anchor{tpmtool system} + +This is the ``any registered key will be a system key'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +user. +@item +must appear in combination with the following options: +register. +@end itemize + +The generated key will be stored in system persistent storage. +@subsubheading test-sign option. +@anchor{tpmtool test-sign} + +This is the ``tests the signature operation of the provided object'' option. +This option takes a ArgumentType.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. +@subsubheading sec-param option. +@anchor{tpmtool sec-param} + +This is the ``specify the security level [low, legacy, medium, high, ultra]'' option. +This option takes a ArgumentType.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. +@subsubheading inder option. +@anchor{tpmtool inder} + +This is the ``use the der format for keys'' option. +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 +@subsubheading outder option. +@anchor{tpmtool outder} + +This is the ``use der format for output keys'' option. +The output will be in the TPM portable DER format. +@subsubheading version option (-v). +@anchor{tpmtool version} + +This is the ``output version information and exit'' option. +This option takes a ArgumentType.KEYWORD argument. +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +@subsubheading help option (-h). +@anchor{tpmtool help} + +This is the ``display extended usage information and exit'' option. +Display usage information and exit. +@subsubheading more-help option (-!). +@anchor{tpmtool more-help} + +This is the ``extended usage information passed thru pager'' option. +Pass the extended usage information through a pager. +@anchor{tpmtool exit status} +@subsubheading 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} +@subsubheading tpmtool See Also + p11tool (1), certtool (1) +@anchor{tpmtool Examples} +@subsubheading 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 |