doc/invoke-tpmtool.texi

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