doc/invoke-p11tool.texi

   1 @node p11tool Invocation
   2 @subsection Invoking p11tool
   3 @pindex p11tool
   4 @ignore
   5 #  -*- buffer-read-only: t -*- vi: set ro:
   6 #
   7 # DO NOT EDIT THIS FILE   (invoke-p11tool.texi)
   8 #
   9 # It has been AutoGen-ed  June 26, 2014 at 08:12:19 PM by AutoGen 5.18.2
  10 # From the definitions    ../src/p11tool-args.def
  11 # and the template file   agtexi-cmd.tpl
  12 @end ignore
  13
  14
  15 Program that allows operations on PKCS #11 smart cards
  16 and security modules.
  17
  18 To use PKCS #11 tokens with GnuTLS the p11-kit configuration files need to be setup.
  19 That is create a .module file in /etc/pkcs11/modules with the contents 'module: /path/to/pkcs11.so'.
  20 Alternatively the configuration file /etc/gnutls/pkcs11.conf has to exist and contain a number
  21 of lines of the form 'load=/usr/lib/opensc-pkcs11.so'.
  22
  23 You can provide the PIN to be used for the PKCS #11 operations with the environment variable
  24 GNUTLS_PIN.
  25
  26
  27 This section was generated by @strong{AutoGen},
  28 using the @code{agtexi-cmd} template and the option descriptions for the @code{p11tool} program.
  29 This software is released under the GNU General Public License, version 3 or later.
  30
  31
  32 @anchor{p11tool usage}
  33 @subsubheading p11tool help/usage (@option{--help})
  34 @cindex p11tool help
  35
  36 This is the automatically generated usage text for p11tool.
  37
  38 The text printed is the same whether selected with the @code{help} option
  39 (@option{--help}) or the @code{more-help} option (@option{--more-help}).  @code{more-help} will print
  40 the usage text by passing it through a pager program.
  41 @code{more-help} is disabled on platforms without a working
  42 @code{fork(2)} function.  The @code{PAGER} environment variable is
  43 used to select the program, defaulting to @file{more}.  Both will exit
  44 with a status code of 0.
  45
  46 @exampleindent 0
  47 @example
  48 p11tool - GnuTLS PKCS #11 tool
  49 Usage:  p11tool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [url]
  50
  51    -d, --debug=num            Enable debugging
  52                                 - it must be in the range:
  53                                   0 to 9999
  54        --outfile=str          Output file
  55        --list-tokens          List all available tokens
  56        --export               Export the object specified by the URL
  57        --export-chain         Export the certificate specified by the URL and its chain of trust
  58        --list-mechanisms      List all available mechanisms in a token
  59        --list-all             List all available objects in a token
  60        --list-all-certs       List all available certificates in a token
  61        --list-certs           List all certificates that have an associated private key
  62        --list-all-privkeys    List all available private keys in a token
  63        --list-privkeys        an alias for the 'list-all-privkeys' option
  64        --list-keys            an alias for the 'list-all-privkeys' option
  65        --list-all-trusted     List all available certificates marked as trusted
  66        --initialize           Initializes a PKCS #11 token
  67        --write                Writes the loaded objects to a PKCS #11 token
  68        --delete               Deletes the objects matching the PKCS #11 URL
  69        --generate-random=num  Generate random data
  70        --generate-rsa         Generate an RSA private-public key pair
  71        --generate-dsa         Generate an RSA private-public key pair
  72        --generate-ecc         Generate an RSA private-public key pair
  73        --label=str            Sets a label for the write operation
  74        --trusted              Marks the object to be written as trusted
  75                                 - disabled as '--no-trusted'
  76        --private              Marks the object to be written as private
  77                                 - disabled as '--no-private'
  78                                 - enabled by default
  79        --login                Force (user) login to token
  80                                 - disabled as '--no-login'
  81        --so-login             Force security officer login to token
  82                                 - disabled as '--no-so-login'
  83        --admin-login          an alias for the 'so-login' option
  84        --detailed-url         Print detailed URLs
  85                                 - disabled as '--no-detailed-url'
  86        --secret-key=str       Provide a hex encoded secret key
  87        --load-privkey=file    Private key file to use
  88                                 - file must pre-exist
  89        --load-pubkey=file     Public key file to use
  90                                 - file must pre-exist
  91        --load-certificate=file Certificate file to use
  92                                 - file must pre-exist
  93    -8, --pkcs8                Use PKCS #8 format for private keys
  94        --bits=num             Specify the number of bits for key generate
  95        --sec-param=str        Specify the security level
  96        --inder                Use DER/RAW format for input
  97                                 - disabled as '--no-inder'
  98        --inraw                an alias for the 'inder' option
  99        --outder               Use DER format for output certificates, private keys, and DH parameters
 100                                 - disabled as '--no-outder'
 101        --outraw               an alias for the 'outder' option
 102        --provider=file        Specify the PKCS #11 provider library
 103                                 - file must pre-exist
 104    -v, --version[=arg]        output version information and exit
 105    -h, --help                 display extended usage information and exit
 106    -!, --more-help            extended usage information passed thru pager
 107
 108 Options are specified by doubled hyphens and their name or by a single
 109 hyphen and the flag character.
 110 Operands and options may be intermixed.  They will be reordered.
 111
 112 Program that allows handling data from PKCS #11 smart cards and security
 113 modules.
 114
 115 To use PKCS #11 tokens with gnutls the configuration file
 116 /etc/gnutls/pkcs11.conf has to exist and contain a number of lines of the
 117 form 'load=/usr/lib/opensc-pkcs11.so'.  Alternatively the p11-kit
 118 configuration files have to be setup.
 119
 120 To provide the PIN for all the operations below use the environment
 121 variable GNUTLS_PIN.
 122
 123 @end example
 124 @exampleindent 4
 125
 126 @anchor{p11tool debug}
 127 @subsubheading debug option (-d)
 128
 129 This is the ``enable debugging'' option.
 130 This option takes a number argument.
 131 Specifies the debug level.
 132 @anchor{p11tool export-chain}
 133 @subsubheading export-chain option
 134
 135 This is the ``export the certificate specified by the url and its chain of trust'' option.
 136 Exports the certificate specified by the URL and generates its chain of trust based on the stored certificates in the module.
 137 @anchor{p11tool list-all-privkeys}
 138 @subsubheading list-all-privkeys option
 139
 140 This is the ``list all available private keys in a token'' option.
 141 Lists all the private keys in a token that match the specified URL.
 142 @anchor{p11tool list-privkeys}
 143 @subsubheading list-privkeys option
 144
 145 This is an alias for the @code{list-all-privkeys} option,
 146 @pxref{p11tool list-all-privkeys, the list-all-privkeys option documentation}.
 147
 148 @anchor{p11tool list-keys}
 149 @subsubheading list-keys option
 150
 151 This is an alias for the @code{list-all-privkeys} option,
 152 @pxref{p11tool list-all-privkeys, the list-all-privkeys option documentation}.
 153
 154 @anchor{p11tool write}
 155 @subsubheading write option
 156
 157 This is the ``writes the loaded objects to a pkcs #11 token'' option.
 158 It can be used to write private keys, certificates or secret keys to a token.
 159 @anchor{p11tool generate-random}
 160 @subsubheading generate-random option
 161
 162 This is the ``generate random data'' option.
 163 This option takes a number argument.
 164 Asks the token to generate a number of bytes of random bytes.
 165 @anchor{p11tool generate-rsa}
 166 @subsubheading generate-rsa option
 167
 168 This is the ``generate an rsa private-public key pair'' option.
 169 Generates an RSA private-public key pair on the specified token.
 170 @anchor{p11tool generate-dsa}
 171 @subsubheading generate-dsa option
 172
 173 This is the ``generate an rsa private-public key pair'' option.
 174 Generates an RSA private-public key pair on the specified token.
 175 @anchor{p11tool generate-ecc}
 176 @subsubheading generate-ecc option
 177
 178 This is the ``generate an rsa private-public key pair'' option.
 179 Generates an RSA private-public key pair on the specified token.
 180 @anchor{p11tool private}
 181 @subsubheading private option
 182
 183 This is the ``marks the object to be written as private'' option.
 184
 185 @noindent
 186 This option has some usage constraints.  It:
 187 @itemize @bullet
 188 @item
 189 can be disabled with --no-private.
 190 @item
 191 It is enabled by default.
 192 @end itemize
 193
 194 The written object will require a PIN to be used.
 195 @anchor{p11tool so-login}
 196 @subsubheading so-login option
 197
 198 This is the ``force security officer login to token'' option.
 199
 200 @noindent
 201 This option has some usage constraints.  It:
 202 @itemize @bullet
 203 @item
 204 can be disabled with --no-so-login.
 205 @end itemize
 206
 207 Forces login to the token as security officer (admin).
 208 @anchor{p11tool admin-login}
 209 @subsubheading admin-login option
 210
 211 This is an alias for the @code{so-login} option,
 212 @pxref{p11tool so-login, the so-login option documentation}.
 213
 214 @anchor{p11tool sec-param}
 215 @subsubheading sec-param option
 216
 217 This is the ``specify the security level'' option.
 218 This option takes a string argument @file{Security parameter}.
 219 This is alternative to the bits option. Available options are [low, legacy, medium, high, ultra].
 220 @anchor{p11tool inder}
 221 @subsubheading inder option
 222
 223 This is the ``use der/raw format for input'' option.
 224
 225 @noindent
 226 This option has some usage constraints.  It:
 227 @itemize @bullet
 228 @item
 229 can be disabled with --no-inder.
 230 @end itemize
 231
 232 Use DER/RAW format for input certificates and private keys.
 233 @anchor{p11tool inraw}
 234 @subsubheading inraw option
 235
 236 This is an alias for the @code{inder} option,
 237 @pxref{p11tool inder, the inder option documentation}.
 238
 239 @anchor{p11tool outder}
 240 @subsubheading outder option
 241
 242 This is the ``use der format for output certificates, private keys, and dh parameters'' option.
 243
 244 @noindent
 245 This option has some usage constraints.  It:
 246 @itemize @bullet
 247 @item
 248 can be disabled with --no-outder.
 249 @end itemize
 250
 251 The output will be in DER or RAW format.
 252 @anchor{p11tool outraw}
 253 @subsubheading outraw option
 254
 255 This is an alias for the @code{outder} option,
 256 @pxref{p11tool outder, the outder option documentation}.
 257
 258 @anchor{p11tool provider}
 259 @subsubheading provider option
 260
 261 This is the ``specify the pkcs #11 provider library'' option.
 262 This option takes a file argument.
 263 This will override the default options in /etc/gnutls/pkcs11.conf
 264 @anchor{p11tool exit status}
 265 @subsubheading p11tool exit status
 266
 267 One of the following exit values will be returned:
 268 @table @samp
 269 @item 0 (EXIT_SUCCESS)
 270 Successful program execution.
 271 @item 1 (EXIT_FAILURE)
 272 The operation failed or the command syntax was not valid.
 273 @end table
 274 @anchor{p11tool See Also}
 275 @subsubheading p11tool See Also
 276     certtool (1)
 277 @anchor{p11tool Examples}
 278 @subsubheading p11tool Examples
 279 To view all tokens in your system use:
 280 @example
 281 $ p11tool --list-tokens
 282 @end example
 283
 284 To view all objects in a token use:
 285 @example
 286 $ p11tool --login --list-all "pkcs11:TOKEN-URL"
 287 @end example
 288
 289 To store a private key and a certificate in a token run:
 290 @example
 291 $ p11tool --login --write "pkcs11:URL" --load-privkey key.pem \
 292           --label "Mykey"
 293 $ p11tool --login --write "pkcs11:URL" --load-certificate cert.pem \
 294           --label "Mykey"
 295 @end example
 296 Note that some tokens require the same label to be used for the certificate
 297 and its corresponding private key.
 298
 299 To generate an RSA private key inside the token use:
 300 @example
 301 $ p11tool --login --generate-rsa --bits 1024 --label "MyNewKey" \
 302           --outfile MyNewKey.pub "pkcs11:TOKEN-URL"
 303 @end example
 304 The bits parameter in the above example is explicitly set because some
 305 tokens only support limited choices in the bit length. The output file is the
 306 corresponding public key. This key can be used to general a certificate
 307 request with certtool.
 308 @example
 309 certtool --generate-request --load-privkey "pkcs11:KEY-URL" \
 310    --load-pubkey MyNewKey.pub --outfile request.pem
 311 @end example