From: Nikos Mavrogiannopoulos <nmav@gnutls.org>
Date: Tue, 8 Feb 2011 22:06:14 +0000 (+0100)
Subject: Added documentation on p11tool.
X-Git-Tag: gnutls_2_99_0~290
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=cef63066036659bc39ccf76206a13d6afc10f520;p=thirdparty%2Fgnutls.git

Added documentation on p11tool.
---

diff --git a/doc/cha-programs.texi b/doc/cha-programs.texi
index 60b3514c77..53a71954ea 100644
--- a/doc/cha-programs.texi
+++ b/doc/cha-programs.texi
@@ -12,6 +12,7 @@ application.  The applications are discussed in this chapter.
 * Invoking gnutls-serv::
 * Invoking psktool::
 * Invoking srptool::
+* Invoking p11tool::
 @end menu
 
 @node Invoking certtool
@@ -846,3 +847,92 @@ $ srptool --passwd /etc/tpasswd \
 @end example
 
 @end itemize
+
+@node Invoking p11tool
+@section Invoking p11tool
+@anchor{p11tool}
+@cindex p11tool
+
+The @file{p11tool} is a program that helps with accessing tokens
+and security modules that support the PKCS #11 API. It requires
+the individual PKCS #11 modules to be loaded either with the
+@code{--provider} option, or by setting up the GnuTLS configuration
+file for PKCS #11 as in @ref{sec:pkcs11}.
+
+@verbatim
+p11tool help
+Usage: p11tool [options]
+
+     --export URL             Export an object specified by a pkcs11 
+                              URL
+     --list-tokens            List all available tokens
+     --list-mechanisms URL    List all available mechanisms in token.
+     --list-all               List all objects specified by a PKCS#11 
+                              URL
+     --list-all-certs         List all certificates specified by a 
+                              PKCS#11 URL
+     --list-certs             List certificates that have a private 
+                              key specified by a PKCS#11 URL
+     --list-privkeys          List private keys specified by a 
+                              PKCS#11 URL
+     --list-trusted           List certificates marked as trusted, 
+                              specified by a PKCS#11 URL
+     --initialize URL         Initializes a PKCS11 token.
+     --write URL              Writes loaded certificates, private or 
+                              secret keys to a PKCS11 token.
+     --delete URL             Deletes objects matching the URL.
+     --label label            Sets a label for the write operation.
+     --trusted                Marks the certificate to be imported as 
+                              trusted.
+     --login                  Force login to token
+     --detailed-url           Export detailed URLs.
+     --no-detailed-url        Export less detailed URLs.
+     --secret-key HEX_KEY     Provide a hex encoded secret key.
+     --load-privkey FILE      Private key file to use.
+     --load-pubkey FILE       Private key file to use.
+     --load-certificate FILE  
+                              Certificate file to use.
+     -8, --pkcs8              Use PKCS #8 format for private keys.
+     --inder                  Use DER format for input certificates 
+                              and private keys.
+     --inraw                  Use RAW/DER format for input 
+                              certificates and private keys.
+     --provider Library       Specify the pkcs11 provider library
+     --outfile FILE           Output file.
+     -d, --debug LEVEL        specify the debug level. Default is 1.
+     -h, --help               shows this help text
+@end verbatim
+
+After being provided the available PKCS #11 modules, it can list all tokens 
+available in your system, the objects on the tokens, and perform operations
+on them.
+
+Some examples on how to use p11tool:
+
+@itemize
+
+@item List all tokens
+@example
+$ p11tool --list-tokens
+@end example
+
+@item List all objects
+@example
+$ p11tool --login --list-all
+@end example
+
+@item To export an object
+@example 
+$ p11tool --login --export pkcs11:(OBJECT URL)
+@end example
+
+@item To copy an object to a token
+@example 
+$ p11tool --login --write pkcs11:(TOKEN URL) --load-certificate (certificate file) --label "my_cert"
+@end example
+
+@end itemize
+
+Note that typically PKCS #11 private key objects are not allowed
+to be extracted from the token.
+