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