diff options
Diffstat (limited to 'doc/invoke-p11tool.texi')
| -rw-r--r-- | doc/invoke-p11tool.texi | 303 |
1 files changed, 137 insertions, 166 deletions
diff --git a/doc/invoke-p11tool.texi b/doc/invoke-p11tool.texi index 688461a46b..278e1aa302 100644 --- a/doc/invoke-p11tool.texi +++ b/doc/invoke-p11tool.texi @@ -6,11 +6,12 @@ # # DO NOT EDIT THIS FILE (invoke-p11tool.texi) # -# It has been AutoGen-ed December 29, 2012 at 01:00:45 PM by AutoGen 5.12 +# It has been AutoGen-ed January 1, 2013 at 09:07:59 PM by AutoGen 5.16 # From the definitions ../src/p11tool-args.def # and the template file agtexi-cmd.tpl @end ignore + Program that allows handling data from PKCS #11 smart cards and security modules. @@ -20,176 +21,122 @@ To use PKCS #11 tokens with gnutls the configuration file This section was generated by @strong{AutoGen}, using the @code{agtexi-cmd} template and the option descriptions for the @code{p11tool} program. - -This software is released under the GNU General Public License. +This software is released under the GNU General Public License, version 3 or later. @anchor{p11tool usage} -@subsubheading p11tool usage help (-?) +@subsubheading p11tool help/usage (-h) +@cindex p11tool help -This is the automatically generated usage text for p11tool: +This is the automatically generated usage text for p11tool. +The text printed is the same whether for the @code{help} option (-h) or the @code{more-help} option (-!). @code{more-help} will print +the usage text by passing it through a pager program. +@code{more-help} is disabled on platforms without a working +@code{fork(2)} function. The @code{PAGER} environment variable is +used to select the program, defaulting to @file{more}. Both will exit +with a status code of 0. @exampleindent 0 @example -p11tool is unavailable - no --help +p11tool - GnuTLS PKCS #11 tool - Ver. @@VERSION@@ +USAGE: p11tool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [url] + + -d, --debug=num Enable debugging. + - It must be in the range: + 0 to 9999 + --outfile=str Output file + --list-tokens List all available tokens + --export Export the object specified by the URL + --list-mechanisms List all available mechanisms in a token + --list-all List all available objects in a token + --list-all-certs List all available certificates in a token + --list-certs List all certificates that have an associated private key + --list-all-privkeys List all available private keys in a token + --list-all-trusted List all available certificates marked as trusted + --initialize Initializes a PKCS #11 token + --write Writes the loaded objects to a PKCS #11 token + --delete Deletes the objects matching the PKCS #11 URL + --generate-rsa Generate an RSA private-public key pair + --generate-dsa Generate an RSA private-public key pair + --generate-ecc Generate an RSA private-public key pair + --label=str Sets a label for the write operation + --trusted Marks the object to be written as trusted + - disabled as --no-trusted + --private Marks the object to be written as private + - disabled as --no-private + - enabled by default + --login Force login to token + - disabled as --no-login + --detailed-url Print detailed URLs + - disabled as --no-detailed-url + --secret-key=str Provide a hex encoded secret key + --load-privkey=file Private key file to use + - file must pre-exist + --load-pubkey=file Public key file to use + - file must pre-exist + --load-certificate=file Certificate file to use + - file must pre-exist + -8, --pkcs8 Use PKCS #8 format for private keys + --bits=num Specify the number of bits for key generate + --sec-param=str Specify the security level + --inder Use DER/RAW format for input + - disabled as --no-inder + --inraw This is an alias for 'inder' + --provider=file Specify the PKCS #11 provider library + - file must pre-exist + -v, --version[=arg] Output version information and exit + -h, --help Display extended usage information and exit + -!, --more-help Extended usage information passed thru pager + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. +Operands and options may be intermixed. They will be reordered. + + + +Program that allows handling data from PKCS #11 smart cards and security +modules. + +To use PKCS #11 tokens with gnutls the configuration file +/etc/gnutls/pkcs11.conf has to exist and contain a number of lines of the +form 'load=/usr/lib/opensc-pkcs11.so'. + +please send bug reports to: bug-gnutls@@gnu.org @end example @exampleindent 4 -@anchor{p11tool bits} -@subsubheading bits option - -This is the ``specify the number of bits for key generate'' option. - - @anchor{p11tool debug} @subsubheading debug option (-d) This is the ``enable debugging.'' option. +This option takes an argument number. Specifies the debug level. +@anchor{p11tool write} +@subsubheading write option -@anchor{p11tool delete} -@subsubheading delete option - -This is the ``deletes the objects matching the pkcs #11 url'' option. - - -@anchor{p11tool detailed-url} -@subsubheading detailed-url option - -This is the ``print detailed urls'' option. - - -@anchor{p11tool export} -@subsubheading export option - -This is the ``export the object specified by the url'' option. - +This is the ``writes the loaded objects to a pkcs #11 token'' option. +It can be used to write private keys, certificates or secret keys to a token. +@anchor{p11tool generate-rsa} +@subsubheading generate-rsa option +This is the ``generate an rsa private-public key pair'' option. +Generates an RSA private-public key pair on the specified token. @anchor{p11tool generate-dsa} @subsubheading generate-dsa option This is the ``generate an rsa private-public key pair'' option. Generates an RSA private-public key pair on the specified token. - @anchor{p11tool generate-ecc} @subsubheading generate-ecc option This is the ``generate an rsa private-public key pair'' option. Generates an RSA private-public key pair on the specified token. - -@anchor{p11tool generate-rsa} -@subsubheading generate-rsa option - -This is the ``generate an rsa private-public key pair'' option. -Generates an RSA private-public key pair on the specified token. - -@anchor{p11tool inder} -@subsubheading inder option - -This is the ``use der/raw format for input'' option. -Use DER/RAW format for input certificates and private keys. - -@anchor{p11tool initialize} -@subsubheading initialize option - -This is the ``initializes a pkcs #11 token'' option. - - -@anchor{p11tool inraw} -@subsubheading inraw option - -This is the ``'' option. -This option has no @samp{doc} documentation. - -@anchor{p11tool label} -@subsubheading label option - -This is the ``sets a label for the write operation'' option. - - -@anchor{p11tool list-all} -@subsubheading list-all option - -This is the ``list all available objects in a token'' option. - - -@anchor{p11tool list-all-certs} -@subsubheading list-all-certs option - -This is the ``list all available certificates in a token'' option. - - -@anchor{p11tool list-all-privkeys} -@subsubheading list-all-privkeys option - -This is the ``list all available private keys in a token'' option. - - -@anchor{p11tool list-all-trusted} -@subsubheading list-all-trusted option - -This is the ``list all available certificates marked as trusted'' option. - - -@anchor{p11tool list-certs} -@subsubheading list-certs option - -This is the ``list all certificates that have an associated private key'' option. - - -@anchor{p11tool list-mechanisms} -@subsubheading list-mechanisms option - -This is the ``list all available mechanisms in a token'' option. - - -@anchor{p11tool list-tokens} -@subsubheading list-tokens option - -This is the ``list all available tokens'' option. - - -@anchor{p11tool load-certificate} -@subsubheading load-certificate option - -This is the ``certificate file to use'' option. - - -@anchor{p11tool load-privkey} -@subsubheading load-privkey option - -This is the ``private key file to use'' option. - - -@anchor{p11tool load-pubkey} -@subsubheading load-pubkey option - -This is the ``public key file to use'' option. - - -@anchor{p11tool login} -@subsubheading login option - -This is the ``force login to token'' option. - - -@anchor{p11tool outfile} -@subsubheading outfile option - -This is the ``output file'' option. - - -@anchor{p11tool pkcs8} -@subsubheading pkcs8 option (-8) - -This is the ``use pkcs #8 format for private keys'' option. - - @anchor{p11tool private} @subsubheading private option This is the ``marks the object to be written as private'' option. +@noindent This option has some usage constraints. It: @itemize @bullet @item @@ -197,53 +144,77 @@ is enabled by default. @end itemize The written object will require a PIN to be used. - -@anchor{p11tool provider} -@subsubheading provider option - -This is the ``specify the pkcs #11 provider library'' option. -This will override the default options in /etc/gnutls/pkcs11.conf - @anchor{p11tool sec-param} @subsubheading sec-param option This is the ``specify the security level'' option. +This option takes an argument string @file{Security parameter}. This is alternative to the bits option. Available options are [low, legacy, normal, high, ultra]. +@anchor{p11tool inder} +@subsubheading inder option -@anchor{p11tool secret-key} -@subsubheading secret-key option - -This is the ``provide a hex encoded secret key'' option. - - -@anchor{p11tool trusted} -@subsubheading trusted option - -This is the ``marks the object to be written as trusted'' option. - +This is the ``use der/raw format for input'' option. +Use DER/RAW format for input certificates and private keys. +@anchor{p11tool inraw} +@subsubheading inraw option -@anchor{p11tool write} -@subsubheading write option +This is an alias for the inder option, +@pxref{p11tool inder, the inder option documentation}. -This is the ``writes the loaded objects to a pkcs #11 token'' option. -It can be used to write private keys, certificates or secret keys to a token. +@anchor{p11tool provider} +@subsubheading provider option +This is the ``specify the pkcs #11 provider library'' option. +This option takes an argument file. +This will override the default options in /etc/gnutls/pkcs11.conf @anchor{p11tool exit status} @subsubheading p11tool exit status One of the following exit values will be returned: @table @samp -@item 0 +@item 0 (EXIT_SUCCESS) Successful program execution. -@item 1 +@item 1 (EXIT_FAILURE) The operation failed or the command syntax was not valid. @end table - - @anchor{p11tool See Also} @subsubheading p11tool See Also - + certtool (1) @anchor{p11tool Examples} @subsubheading p11tool Examples +To view all tokens in your system use: +@example +$ p11tool --list-tokens +@end example + +To view all objects in a token use: +@example +$ p11tool --login --list-all "pkcs11:TOKEN-URL" +@end example + +To store a private key and a certificate in a token run: +@example +$ p11tool --login --write "pkcs11:URL" --load-privkey key.pem \ + --label "Mykey" +$ p11tool --login --write "pkcs11:URL" --load-certificate cert.pem \ + --label "Mykey" +@end example +Note that some tokens require the same label to be used for the certificate +and its corresponding private key. + +To generate an RSA private key inside the token use: +@example +$ p11tool --login --generate-rsa --bits 1024 --label "MyNewKey" \ + --outfile MyNewKey.pub "pkcs11:TOKEN-URL" +@end example +The bits parameter in the above example is explicitly set because some +tokens only support a limited number of bits. The output file is the +corresponding public key. This key can be used to general a certificate +request with certtool. +@example +certtool --generate-request --load-privkey "pkcs11:KEY-URL" \ + --load-pubkey MyNewKey.pub --outfile request.pem +@end example + |