doc/invoke-p11tool.texi

   1 @node p11tool Invocation
   2 @subsection Invoking p11tool
   3 @pindex p11tool
   4 @cindex GnuTLS PKCS #11 tool
   5 @ignore
   6 #  -*- buffer-read-only: t -*- vi: set ro:
   7 #
   8 # DO NOT EDIT THIS FILE   (invoke-p11tool.texi)
   9 #
  10 # It has been AutoGen-ed  May  9, 2012 at 08:06:14 PM by AutoGen 5.16
  11 # From the definitions    ../src/p11tool-args.def
  12 # and the template file   agtexi-cmd.tpl
  13 @end ignore
  14
  15
  16 Program that allows handling data from PKCS #11 smart cards
  17 and security modules.
  18
  19 To use PKCS #11 tokens with gnutls the configuration file
  20 /etc/gnutls/pkcs11.conf has to exist and contain a number of lines of the form 'load=/usr/lib/opensc-pkcs11.so'.
  21
  22
  23 This section was generated by @strong{AutoGen},
  24 using the @code{agtexi-cmd} template and the option descriptions for the @code{p11tool} program.
  25 This software is released under the GNU General Public License, version 3 or later.
  26
  27
  28 @anchor{p11tool usage}
  29 @subsubheading p11tool help/usage (-h)
  30 @cindex p11tool help
  31
  32 This is the automatically generated usage text for p11tool.
  33 The text printed is the same whether for the @code{help} option (-h) or the @code{more-help} option (-!).  @code{more-help} will print
  34 the usage text by passing it through a pager program.
  35 @code{more-help} is disabled on platforms without a working
  36 @code{fork(2)} function.  The @code{PAGER} environment variable is
  37 used to select the program, defaulting to @file{more}.  Both will exit
  38 with a status code of 0.
  39
  40 @exampleindent 0
  41 @example
  42 p11tool - GnuTLS PKCS #11 tool - Ver. @@VERSION@@
  43 USAGE:  p11tool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [url]
  44
  45    -d, --debug=num            Enable debugging.
  46                                 - It must be in the range:
  47                                   0 to 9999
  48        --outfile=str          Output file
  49        --list-tokens          List all available tokens
  50        --export               Export the object specified by the URL
  51        --list-mechanisms      List all available mechanisms in a token
  52        --list-all             List all available objects in a token
  53        --list-all-certs       List all available certificates in a token
  54        --list-certs           List all certificates that have an associated private key
  55        --list-all-privkeys    List all available private keys in a token
  56        --list-all-trusted     List all available certificates marked as trusted
  57        --initialize           Initializes a PKCS #11 token
  58        --write                Writes the loaded objects to a PKCS #11 token
  59        --delete               Deletes the objects matching the PKCS #11 URL
  60        --generate-rsa         Generate an RSA private-public key pair
  61        --generate-dsa         Generate an RSA private-public key pair
  62        --generate-ecc         Generate an RSA private-public key pair
  63        --label=str            Sets a label for the write operation
  64        --trusted              Marks the object to be written as trusted
  65                                 - disabled as --no-trusted
  66        --private              Marks the object to be written as private
  67                                 - disabled as --no-private
  68                                 - enabled by default
  69        --login                Force login to token
  70                                 - disabled as --no-login
  71        --detailed-url         Print detailed URLs
  72                                 - disabled as --no-detailed-url
  73        --secret-key=str       Provide a hex encoded secret key
  74        --load-privkey=file    Private key file to use
  75                                 - file must pre-exist
  76        --load-pubkey=file     Public key file to use
  77                                 - file must pre-exist
  78        --load-certificate=file Certificate file to use
  79                                 - file must pre-exist
  80    -8, --pkcs8                Use PKCS #8 format for private keys
  81        --bits=num             Specify the number of bits for key generate
  82        --sec-param=str        Specify the security level
  83        --inder                Use DER/RAW format for input
  84                                 - disabled as --no-inder
  85        --inraw                This is an alias for 'inder'
  86        --provider=file        Specify the PKCS #11 provider library
  87                                 - file must pre-exist
  88    -v, --version[=arg]        Output version information and exit
  89    -h, --help                 Display extended usage information and exit
  90    -!, --more-help            Extended usage information passed thru pager
  91
  92 Options are specified by doubled hyphens and their name or by a single
  93 hyphen and the flag character.
  94 Operands and options may be intermixed.  They will be reordered.
  95
  96
  97
  98 Program that allows handling data from PKCS #11 smart cards and security
  99 modules.
 100
 101 To use PKCS #11 tokens with gnutls the configuration file
 102 /etc/gnutls/pkcs11.conf has to exist and contain a number of lines of the
 103 form 'load=/usr/lib/opensc-pkcs11.so'.
 104
 105 please send bug reports to:  bug-gnutls@@gnu.org
 106 @end example
 107 @exampleindent 4
 108
 109 @anchor{p11tool debug}
 110 @subsubheading debug option (-d)
 111 @cindex p11tool-debug
 112
 113 This is the ``enable debugging.'' option.
 114 This option takes an argument number.
 115 Specifies the debug level.
 116 @anchor{p11tool write}
 117 @subsubheading write option
 118 @cindex p11tool-write
 119
 120 This is the ``writes the loaded objects to a pkcs #11 token'' option.
 121 It can be used to write private keys, certificates or secret keys to a token.
 122 @anchor{p11tool generate-rsa}
 123 @subsubheading generate-rsa option
 124 @cindex p11tool-generate-rsa
 125
 126 This is the ``generate an rsa private-public key pair'' option.
 127 Generates an RSA private-public key pair on the specified token.
 128 @anchor{p11tool generate-dsa}
 129 @subsubheading generate-dsa option
 130 @cindex p11tool-generate-dsa
 131
 132 This is the ``generate an rsa private-public key pair'' option.
 133 Generates an RSA private-public key pair on the specified token.
 134 @anchor{p11tool generate-ecc}
 135 @subsubheading generate-ecc option
 136 @cindex p11tool-generate-ecc
 137
 138 This is the ``generate an rsa private-public key pair'' option.
 139 Generates an RSA private-public key pair on the specified token.
 140 @anchor{p11tool private}
 141 @subsubheading private option
 142 @cindex p11tool-private
 143
 144 This is the ``marks the object to be written as private'' option.
 145
 146 @noindent
 147 This option has some usage constraints.  It:
 148 @itemize @bullet
 149 @item
 150 is enabled by default.
 151 @end itemize
 152
 153 The written object will require a PIN to be used.
 154 @anchor{p11tool sec-param}
 155 @subsubheading sec-param option
 156 @cindex p11tool-sec-param
 157
 158 This is the ``specify the security level'' option.
 159 This option takes an argument string @file{Security parameter}.
 160 This is alternative to the bits option. Available options are [low, legacy, normal, high, ultra].
 161 @anchor{p11tool inder}
 162 @subsubheading inder option
 163 @cindex p11tool-inder
 164
 165 This is the ``use der/raw format for input'' option.
 166 Use DER/RAW format for input certificates and private keys.
 167 @anchor{p11tool inraw}
 168 @subsubheading inraw option
 169 @cindex p11tool-inraw
 170
 171 This is an alias for the inder option,
 172 @pxref{p11tool inder, the inder option documentation}.
 173
 174 @anchor{p11tool provider}
 175 @subsubheading provider option
 176 @cindex p11tool-provider
 177
 178 This is the ``specify the pkcs #11 provider library'' option.
 179 This option takes an argument file.
 180 This will override the default options in /etc/gnutls/pkcs11.conf
 181 @anchor{p11tool exit status}
 182 @subsubheading p11tool exit status
 183
 184 One of the following exit values will be returned:
 185 @table @samp
 186 @item 0 (EXIT_SUCCESS)
 187 Successful program execution.
 188 @item 1 (EXIT_FAILURE)
 189 The operation failed or the command syntax was not valid.
 190 @end table
 191 @anchor{p11tool See Also}
 192 @subsubheading p11tool See Also
 193     certtool (1)
 194
 195 @anchor{p11tool Examples}
 196 @subsubheading p11tool Examples
 197 To view all tokens in your system use:
 198 @example
 199 $ p11tool --list-tokens
 200 @end example
 201
 202 To view all objects in a token use:
 203 @example
 204 $ p11tool --login --list-all "pkcs11:TOKEN-URL"
 205 @end example
 206
 207 To store a private key and a certificate in a token run:
 208 @example
 209 $ p11tool --login --write "pkcs11:URL" --load-privkey key.pem \
 210           --label "Mykey"
 211 $ p11tool --login --write "pkcs11:URL" --load-certificate cert.pem \
 212           --label "Mykey"
 213 @end example
 214 Note that some tokens require the same label to be used for the certificate
 215 and its corresponding private key.
 216