doc/invoke-tpmtool.texi

   1 @node tpmtool Invocation
   2 @subsection Invoking tpmtool
   3 @pindex tpmtool
   4 @ignore
   5 #  -*- buffer-read-only: t -*- vi: set ro:
   6 #
   7 # DO NOT EDIT THIS FILE   (invoke-tpmtool.texi)
   8 #
   9 # It has been AutoGen-ed  November  8, 2012 at 11:40:19 PM by AutoGen 5.16
  10 # From the definitions    ../src/tpmtool-args.def
  11 # and the template file   agtexi-cmd.tpl
  12 @end ignore
  13
  14
  15 Program that allows handling cryptographic data from the TPM chip.
  16
  17 This section was generated by @strong{AutoGen},
  18 using the @code{agtexi-cmd} template and the option descriptions for the @code{tpmtool} program.
  19 This software is released under the GNU General Public License, version 3 or later.
  20
  21
  22 @anchor{tpmtool usage}
  23 @subsubheading tpmtool help/usage (-h)
  24 @cindex tpmtool help
  25
  26 This is the automatically generated usage text for tpmtool.
  27 The text printed is the same whether for the @code{help} option (-h) or the @code{more-help} option (-!).  @code{more-help} will print
  28 the usage text by passing it through a pager program.
  29 @code{more-help} is disabled on platforms without a working
  30 @code{fork(2)} function.  The @code{PAGER} environment variable is
  31 used to select the program, defaulting to @file{more}.  Both will exit
  32 with a status code of 0.
  33
  34 @exampleindent 0
  35 @example
  36 tpmtool - GnuTLS TPM tool - Ver. @@VERSION@@
  37 USAGE:  tpmtool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]...
  38
  39    -d, --debug=num            Enable debugging.
  40                                 - It must be in the range:
  41                                   0 to 9999
  42        --infile=file          Input file
  43                                 - file must pre-exist
  44        --outfile=str          Output file
  45        --generate-rsa         Generate an RSA private-public key pair
  46        --register             Any generated key will be registered in the TPM
  47                                 - requires these options:
  48                                 generate-rsa
  49        --signing              Any generated key will be a signing key
  50                                 - requires these options:
  51                                 generate-rsa
  52                                 -- and prohibits these options:
  53                                 legacy
  54        --legacy               Any generated key will be a legacy key
  55                                 - requires these options:
  56                                 generate-rsa
  57                                 -- and prohibits these options:
  58                                 signing
  59        --user                 Any registered key will be a user key
  60                                 - requires these options:
  61                                 register
  62                                 -- and prohibits these options:
  63                                 system
  64        --system               Any registred key will be a system key
  65                                 - requires these options:
  66                                 register
  67                                 -- and prohibits these options:
  68                                 user
  69        --pubkey=str           Prints the public key of the provided key
  70        --list                 Lists all stored keys in the TPM
  71        --delete=str           Delete the key identified by the given URL (UUID).
  72        --sec-param=str        Specify the security level [low, legacy, normal, high, ultra].
  73        --bits=num             Specify the number of bits for key generate
  74        --inder                Use the DER format for keys.
  75                                 - disabled as --no-inder
  76        --outder               Use DER format for output keys
  77                                 - disabled as --no-outder
  78    -v, --version[=arg]        Output version information and exit
  79    -h, --help                 Display extended usage information and exit
  80    -!, --more-help            Extended usage information passed thru pager
  81
  82 Options are specified by doubled hyphens and their name or by a single
  83 hyphen and the flag character.
  84
  85
  86
  87 Program that allows handling cryptographic data from the TPM chip.
  88
  89 please send bug reports to:  bug-gnutls@@gnu.org
  90 @end example
  91 @exampleindent 4
  92
  93 @anchor{tpmtool debug}
  94 @subsubheading debug option (-d)
  95
  96 This is the ``enable debugging.'' option.
  97 This option takes an argument number.
  98 Specifies the debug level.
  99 @anchor{tpmtool generate-rsa}
 100 @subsubheading generate-rsa option
 101
 102 This is the ``generate an rsa private-public key pair'' option.
 103 Generates an RSA private-public key pair in the TPM chip.
 104 The key may be stored in filesystem and protected by a PIN, or stored (registered)
 105 in the TPM chip flash.
 106 @anchor{tpmtool user}
 107 @subsubheading user option
 108
 109 This is the ``any registered key will be a user key'' option.
 110
 111 @noindent
 112 This option has some usage constraints.  It:
 113 @itemize @bullet
 114 @item
 115 must appear in combination with the following options:
 116 register.
 117 @item
 118 must not appear in combination with any of the following options:
 119 system.
 120 @end itemize
 121
 122 The generated key will be stored in a user specific persistent storage.
 123 @anchor{tpmtool system}
 124 @subsubheading system option
 125
 126 This is the ``any registred key will be a system key'' option.
 127
 128 @noindent
 129 This option has some usage constraints.  It:
 130 @itemize @bullet
 131 @item
 132 must appear in combination with the following options:
 133 register.
 134 @item
 135 must not appear in combination with any of the following options:
 136 user.
 137 @end itemize
 138
 139 The generated key will be stored in system persistent storage.
 140 @anchor{tpmtool sec-param}
 141 @subsubheading sec-param option
 142
 143 This is the ``specify the security level [low, legacy, normal, high, ultra].'' option.
 144 This option takes an argument string @file{Security parameter}.
 145 This is alternative to the bits option. Note however that the
 146 values allowed by the TPM chip are quantized and given values may be rounded up.
 147 @anchor{tpmtool inder}
 148 @subsubheading inder option
 149
 150 This is the ``use the der format for keys.'' option.
 151 The input files will be assumed to be in the portable
 152 DER format of TPM. The default format is a custom format used by various
 153 TPM tools
 154 @anchor{tpmtool outder}
 155 @subsubheading outder option
 156
 157 This is the ``use der format for output keys'' option.
 158 The output will be in the TPM portable DER format.
 159 @anchor{tpmtool exit status}
 160 @subsubheading tpmtool exit status
 161
 162 One of the following exit values will be returned:
 163 @table @samp
 164 @item 0 (EXIT_SUCCESS)
 165 Successful program execution.
 166 @item 1 (EXIT_FAILURE)
 167 The operation failed or the command syntax was not valid.
 168 @end table
 169 @anchor{tpmtool See Also}
 170 @subsubheading tpmtool See Also
 171     p11tool (1), certtool (1)
 172
 173 @anchor{tpmtool Examples}
 174 @subsubheading tpmtool Examples
 175 To generate a key that is to be stored in filesystem use:
 176 @example
 177 $ tpmtool --generate-rsa --bits 2048 --outfile tpmkey.pem
 178 @end example
 179
 180 To generate a key that is to be stored in TPM's flash use:
 181 @example
 182 $ tpmtool --generate-rsa --bits 2048 --register --user
 183 @end example
 184
 185 To get the public key of a TPM key use:
 186 @example
 187 $ tpmtool --pubkey tpmkey:uuid=58ad734b-bde6-45c7-89d8-756a55ad1891;storage=user \
 188           --outfile pubkey.pem
 189 @end example
 190
 191 or if the key is stored in the filesystem:
 192 @example
 193 $ tpmtool --pubkey tpmkey:file=tmpkey.pem --outfile pubkey.pem
 194 @end example
 195
 196 To list all keys stored in TPM use:
 197 @example
 198 $ tpmtool --list
 199 @end example
 200