Manual pages for included programs are auto-generated using the autoopts definitions.

5 files changed, 63 insertions, 1113 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 9b7764b091..edf45a36d1 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -28,6 +28,44 @@ if ENABLE_GTK_DOC
 SUBDIRS += reference
 endif
 
+invoke-gnutls-cli.texi: ../src/cli-args.def
+	cd ../src/ && autogen -Tagtexi-cmd.tpl $<
+	mv ../src/$@ .
+
+invoke-gnutls-cli-debug.texi: ../src/cli-debug-args.def
+	cd ../src/ && autogen -Tagtexi-cmd.tpl $<
+	mv ../src/$@ .
+
+invoke-gnutls-serv.texi: ../src/serv-args.def
+	cd ../src/ && autogen -Tagtexi-cmd.tpl $<
+	mv ../src/$@ .
+
+invoke-certtool.texi: ../src/certtool-args.def
+	cd ../src/ && autogen -Tagtexi-cmd.tpl $<
+	mv ../src/$@ .
+
+invoke-srptool.texi: ../src/srptool-args.def
+	cd ../src/ && autogen -Tagtexi-cmd.tpl $<
+	mv ../src/$@ .
+	sed -i 's/@subsection/@subsubsection/' $@
+	sed -i 's/@section/@subsection/' $@
+
+invoke-ocsptool.texi: ../src/ocsptool-args.def
+	cd ../src/ && autogen -Tagtexi-cmd.tpl $<
+	mv ../src/$@ .
+
+invoke-psktool.texi: ../src/psk-args.def
+	cd ../src/ && autogen -Tagtexi-cmd.tpl $<
+	mv ../src/$@ .
+	sed -i 's/@subsection/@subsubsection/' $@
+	sed -i 's/@section/@subsection/' $@
+
+invoke-p11tool.texi: ../src/p11tool-args.def
+	cd ../src/ && autogen -Tagtexi-cmd.tpl $<
+	mv ../src/$@ .
+	sed -i 's/@subsection/@subsubsection/' $@
+	sed -i 's/@section/@subsection/' $@
+
 info_TEXINFOS = gnutls.texi gnutls-guile.texi
 gnutls_TEXINFOS = gnutls.texi fdl-1.3.texi				\
 	cha-bib.texi cha-cert-auth.texi	cha-cert-auth2.texi		\
@@ -37,6 +75,10 @@ gnutls_TEXINFOS = gnutls.texi fdl-1.3.texi				\
 	sec-tls-app.texi cha-errors.texi cha-support.texi		\
 	cha-shared-key.texi cha-gtls-examples.texi
 
+gnutls_TEXINFOS += invoke-gnutls-cli.texi invoke-gnutls-cli-debug.texi \
+	invoke-gnutls-serv.texi invoke-certtool.texi invoke-srptool.texi \
+	invoke-ocsptool.texi invoke-psktool.texi invoke-p11tool.texi
+
 # Examples.
 gnutls_TEXINFOS += examples/ex-client-anon.c				\
 	examples/ex-session-info.c examples/ex-verify.c			\
diff --git a/doc/cha-cert-auth2.texi b/doc/cha-cert-auth2.texi
index 251d73f231..9d246b04bb 100644
--- a/doc/cha-cert-auth2.texi
+++ b/doc/cha-cert-auth2.texi
@@ -12,8 +12,8 @@ structures, etc., are discussed in this chapter.
 * PKIX certificate revocation lists::
 * OCSP certificate status checking::
 * Managing encrypted keys::
-* The certtool application::
-* The ocsptool application::
+* certtool Invocation::            Invoking certtool
+* ocsptool Invocation::            Invoking ocsptool
 * Smart cards and HSMs::
 * Abstract key types::
 @end menu
@@ -351,565 +351,9 @@ of their usage is also shown.
 
 @verbatiminclude examples/ex-pkcs12.c
 
-@node The certtool application
-@section The certtool application
-@cindex certtool
+@include invoke-certtool.texi
 
-This is a program to generate @acronym{X.509} certificates, certificate
-requests, CRLs and private keys.
-
-@example
-Certtool help
-Usage: certtool [options]
-     -s, --generate-self-signed 
-                              Generate a self-signed certificate.
-     -c, --generate-certificate 
-                              Generate a signed certificate.
-     --generate-proxy         Generate a proxy certificate.
-     --generate-crl           Generate a CRL.
-     -u, --update-certificate 
-                              Update a signed certificate.
-     -p, --generate-privkey   Generate a private key.
-     -q, --generate-request   Generate a PKCS #10 certificate 
-                              request.
-     -e, --verify-chain       Verify a PEM encoded certificate chain. 
-                              The last certificate in the chain must 
-                              be a self signed one.
-     --verify                 Verify a PEM encoded certificate chain. 
-                              CA certificates must be loaded with 
-                              --load-ca-certificate.
-     --verify-crl             Verify a CRL.
-     --generate-dh-params     Generate PKCS #3 encoded Diffie-Hellman 
-                              parameters.
-     --get-dh-params          Get the included PKCS #3 encoded 
-                              Diffie-Hellman parameters.
-     --load-privkey FILE      Private key file to use.
-     --load-pubkey FILE       Public key file to use.
-     --load-request FILE      Certificate request file to use.
-     --load-certificate FILE  
-                              Certificate file to use.
-     --load-ca-privkey FILE   Certificate authority's private key 
-                              file to use.
-     --load-ca-certificate FILE  
-                              Certificate authority's certificate 
-                              file to use.
-     --password PASSWORD      Password to use.
-     -i, --certificate-info   Print information on a certificate.
-     --certificate-pubkey     Print certificate public key.
-     --pgp-certificate-info   Print information on a OpenPGP 
-                              certificate.
-     --pgp-ring-info          Print information on a keyring 
-                              structure.
-     -l, --crl-info           Print information on a CRL.
-     --crq-info               Print information on a Certificate 
-                              Request.
-     --no-crq-extensions      Do not use extensions in certificate 
-                              requests.
-     --p12-info               Print information on a PKCS #12 
-                              structure.
-     --p7-info                Print information on a PKCS #7 
-                              structure.
-     --smime-to-p7            Convert S/MIME to PKCS #7 structure.
-     -k, --key-info           Print information on a private key.
-     --pgp-key-info           Print information on a OpenPGP private 
-                              key.
-     --pubkey-info            Print information on a public key.
-     --fix-key                Regenerate the parameters in a private 
-                              key.
-     --v1                     Generate an X.509 version 1 certificate 
-                              (no extensions).
-     --to-p12                 Generate a PKCS #12 structure.
-     --to-p8                  Generate a PKCS #8 key structure.
-     -8, --pkcs8              Use PKCS #8 format for private keys.
-     --dsa                    Use DSA keys.
-     --ecc                    Use ECC (ECDSA) keys.
-     --hash STR               Hash algorithm to use for signing 
-                              (MD5,SHA1,RMD160,SHA256,SHA384,SHA512).
-     --export-ciphers         Use weak encryption algorithms.
-     --inder                  Use DER format for input certificates 
-                              and private keys.
-     --inraw                  Use RAW/DER format for input 
-                              certificates and private keys.
-     --outder                 Use DER format for output certificates 
-                              and private keys.
-     --outraw                 Use RAW/DER format for output 
-                              certificates and private keys.
-     --bits BITS              specify the number of bits for key 
-                              generation.
-     --sec-param PARAM        specify the security level 
-                              [low|normal|high|ultra].
-     --disable-quick-random   Use /dev/random for key generationg, 
-                              thus increasing the quality of 
-                              randomness used.
-     --outfile FILE           Output file.
-     --infile FILE            Input file.
-     --template FILE          Template file to use for non 
-                              interactive operation.
-     --pkcs-cipher CIPHER     Cipher to use for pkcs operations 
-                              (3des,3des-pkcs12,aes-128,aes-192,aes-25
-                              6,rc2-40,arcfour).
-     -d, --debug LEVEL        specify the debug level. Default is 1.
-     -h, --help               shows this help text
-     -v, --version            shows the program's version
-@end example
-
-The program can be used interactively or non interactively by
-specifying the @code{--template} command line option. See below for an
-example of a template file.
-
-@subheading Diffie-Hellman parameter generation
-To generate parameters for Diffie-Hellman key exchange, use the command:
-@example
-$ certtool --generate-dh-params --outfile dh.pem --sec-param normal
-@end example
-
-@subheading Self-signed certificate generation
-
-To create a self signed certificate, use the command:
-@example
-$ certtool --generate-privkey --outfile ca-key.pem
-$ certtool --generate-self-signed --load-privkey ca-key.pem \
-   --outfile ca-cert.pem
-@end example
-
-Note that a self-signed certificate usually belongs to a certificate
-authority, that signs other certificates.
-
-@subheading Private key generation
-To create a private key (RSA by default), run:
-
-@example
-$ certtool --generate-privkey --outfile key.pem
-@end example
-
-To create a DSA or elliptic curves (ECDSA) private key use the
-above command combined with @code{--dsa} or @code{--ecc} options.
-
-@subheading Certificate generation
-To generate a certificate using the private key, use the command:
-
-@example
-$ certtool --generate-certificate --load-privkey key.pem \
-   --outfile cert.pem --load-ca-certificate ca-cert.pem \
-   --load-ca-privkey ca-key.pem
-@end example
-
-Alternatively you may create a certificate request, which is needed
-when the certificate will be signed by a third party authority.
-
-@example
-$ certtool --generate-request --load-privkey key.pem \
-  --outfile request.pem
-@end example
-
-If the private key is stored in a smart card you can generate
-a request by specifying the private key object URL (see @ref{The p11tool application}
-on how to obtain the URL).
-
-@example
-$ certtool --generate-request --load-privkey pkcs11:(PRIVKEY URL) \
-  --load-pubkey pkcs11:(PUBKEY URL) --outfile request.pem
-@end example
-
-To generate a certificate using the previous request, use the command:
-
-@example
-$ certtool --generate-certificate --load-request request.pem \
-   --outfile cert.pem \
-   --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
-@end example
-
-@subheading Certificate information
-To view the certificate information, use:
-
-@example
-$ certtool --certificate-info --infile cert.pem
-@end example
-
-@subheading @acronym{PKCS} #12 structure generation
-To generate a @acronym{PKCS} #12 structure using the previous key and
-certificate, use the command:
-
-@example
-$ certtool --load-certificate cert.pem --load-privkey key.pem \
-  --to-p12 --outder --outfile key.p12
-@end example
-
-Some tools (reportedly web browsers) have problems with that file
-because it does not contain the CA certificate for the certificate.
-To work around that problem in the tool, you can use the
---load-ca-certificate parameter as follows:
-
-@example
-$ certtool --load-ca-certificate ca.pem \
-  --load-certificate cert.pem --load-privkey key.pem \
-  --to-p12 --outder --outfile key.p12
-@end example
-
-@subheading Proxy certificate generation
-Proxy certificate can be used to delegate your credential to a
-temporary, typically short-lived, certificate.  To create one from the
-previously created certificate, first create a temporary key and then
-generate a proxy certificate for it, using the commands:
-
-@example
-$ certtool --generate-privkey > proxy-key.pem
-$ certtool --generate-proxy --load-ca-privkey key.pem \
-  --load-privkey proxy-key.pem --load-certificate cert.pem \
-  --outfile proxy-cert.pem
-@end example
-
-@subheading Certificate revocation list generation
-To create an empty Certificate Revocation List (CRL) do:
-
-@example
-$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
-           --load-ca-certificate x509-ca.pem
-@end example
-
-To create a CRL that contains some revoked certificates, place the
-certificates in a file and use @code{--load-certificate} as follows:
-
-@example
-$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
-  --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
-@end example
-
-To verify a Certificate Revocation List (CRL) do:
-
-@example
-$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
-@end example
-
-
-
-@subheading Certtool's template file format:
-A template file can be used to avoid the interactive questions of
-certtool. Initially create a file named 'cert.cfg' that contains the information
-about the certificate. The template can be used as below:
-
-@example
-$ certtool --generate-certificate cert.pem --load-privkey key.pem  \
-   --template cert.cfg \
-   --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
-@end example
-
-An example certtool template file that can be used to generate a certificate
-request or a self signed certificate follows.
-
-@example
-# X.509 Certificate options
-#
-# DN options
-
-# The organization of the subject.
-organization = "Koko inc."
-
-# The organizational unit of the subject.
-unit = "sleeping dept."
-
-# The locality of the subject.
-# locality =
-
-# The state of the certificate owner.
-state = "Attiki"
-
-# The country of the subject. Two letter code.
-country = GR
-
-# The common name of the certificate owner.
-cn = "Cindy Lauper"
-
-# A user id of the certificate owner.
-#uid = "clauper"
-
-# If the supported DN OIDs are not adequate you can set
-# any OID here.
-# For example set the X.520 Title and the X.520 Pseudonym
-# by using OID and string pairs.
-#dn_oid = 2.5.4.12 Dr. 
-#dn_oid = 2.5.4.65 jackal
-
-# This is deprecated and should not be used in new
-# certificates.
-# pkcs9_email = "none@@none.org"
-
-# The serial number of the certificate
-serial = 007
-
-# In how many days, counting from today, this certificate will expire.
-expiration_days = 700
-
-# X.509 v3 extensions
-
-# A dnsname in case of a WWW server.
-#dns_name = "www.none.org"
-#dns_name = "www.morethanone.org"
-
-# An IP address in case of a server.
-#ip_address = "192.168.1.1"
-
-# An email in case of a person
-email = "none@@none.org"
-
-# Challenge password used in certificate requests
-challenge_passwd = 123456
-
-# key_purpose_oid = 1.2.3.4.5.6.7
-# key_purpose_oid = 1.2.3.4.5.6.7.9
-
-# An URL that has CRLs (certificate revocation lists)
-# available. Needed in CA certificates.
-#crl_dist_points = "http://www.getcrl.crl/getcrl/"
-
-# Whether this is a CA certificate or not
-#ca
-
-# Whether this certificate will be used for a TLS client
-#tls_www_client
-
-# Whether this certificate will be used for a TLS server
-#tls_www_server
-
-# Whether this certificate will be used to sign data (needed
-# in TLS DHE ciphersuites).
-signing_key
-
-# Whether this certificate will be used to encrypt data (needed
-# in TLS RSA ciphersuites). Note that it is preferred to use different
-# keys for encryption and signing.
-#encryption_key
-
-# Whether this key will be used to sign other certificates.
-#cert_signing_key
-
-# Whether this key will be used to sign CRLs.
-#crl_signing_key
-
-# Whether this key will be used to sign code.
-#code_signing_key
-
-# Whether this key will be used to sign OCSP data.
-#ocsp_signing_key
-
-# Whether this key will be used for time stamping.
-#time_stamping_key
-
-# Whether this key will be used for IPsec IKE operations.
-#ipsec_ike_key
-
-# When generating a certificate from a certificate
-# request, then honor the extensions stored in the request
-# and store them in the real certificate.
-#honor_crq_extensions
-
-# Path length contraint. Sets the maximum number of
-# certificates that can be used to certify this certificate.
-# (i.e. the certificate chain length)
-#path_len = -1
-#path_len = 2
-
-# Options for proxy certificates
-# proxy_policy_language = 1.3.6.1.5.5.7.21.1
-
-# Options for generating a CRL
-
-# next CRL update will be in 43 days (wow)
-#crl_next_update = 43
-
-# this is the 5th CRL by this CA
-#crl_number = 5
-
-@end example
-
-@node The ocsptool application
-@section The ocsptool application
-@cindex ocsptool
-
-This is a program that can parse and print information about
-@acronym{OCSP} requests/responses, generate requests and verify
-responses.
-
-@example
-Ocsptool help
-Usage : ocsptool [options]
-     -e, --verify-response    Verify response.
-     -i, --request-info       Print information on a OCSP request.
-     -j, --response-info      Print information on a OCSP response.
-     -q, --generate-request   Generate a OCSP request.
-     --no-nonce               don't add nonce to OCSP request.
-     --load-issuer FILE       read issuer certificate from FILE.
-     --load-cert FILE         read certificate to check from FILE.
-     --load-trust FILE        read trust anchors from FILE.
-     --inder                  Use DER format for input certificates.
-     -Q, --load-request FILE
-                              read DER encoded OCSP request from
-                              FILE.
-     -S, --load-response FILE
-                              read DER encoded OCSP response from
-                              FILE.
-     --outfile FILE           Output file.
-     --infile FILE            Input file.
-     -V, --verbose            More verbose output.
-     -d, --debug integer      Enable debugging
-     -v, --version            prints the program's version number
-     -h, --help               shows this help text
-@end example
-
-@subheading Print information about an OCSP request
-
-To parse an OCSP request and print information about the content, the
-@code{-i} or @code{--request-info} parameter may be used as follows.
-The @code{-Q} parameter specify the name of the file containing the
-OCSP request, and it should contain the OCSP request in binary DER
-format.
-
-@example
-$ ocsptool -i -Q ocsp-request.der
-@end example
-
-The input file may also be sent to standard input like this:
-
-@example
-$ cat ocsp-request.der | ocsptool --request-info
-@end example
-
-@subheading Print information about an OCSP response
-
-Similar to parsing OCSP requests, OCSP responses can be parsed using
-the @code{-j} or @code{--response-info} as follows.
-
-@example
-$ ocsptool -j -Q ocsp-response.der
-$ cat ocsp-response.der | ocsptool --response-info
-@end example
-
-@subheading Generate an OCSP request
-
-The @code{-q} or @code{--generate-request} parameters are used to
-generate an OCSP request.  By default the OCSP request is written to
-standard output in binary DER format, but can be stored in a file
-using @code{--outfile}.  To generate an OCSP request the issuer of the
-certificate to check needs to be specified with @code{--load-issuer}
-and the certificate to check with @code{--load-cert}.  By default PEM
-format is used for these files, although @code{--inder} can be used to
-specify that the input files are in DER format.
-
-@example
-$ ocsptool -q --load-issuer issuer.pem --load-cert client.pem --outfile ocsp-request.der
-@end example
-
-When generating OCSP requests, the tool will add an OCSP extension
-containing a nonce.  This behaviour can be disabled by specifying
-@code{--no-nonce}.
-
-@subheading Verify signature in OCSP response
-
-To verify the signature in an OCSP response the @code{-e} or
-@code{--verify-response} parameter is used.  The tool will read an
-OCSP response in DER format from standard input, or from the file
-specified by @code{--load-response}.  The OCSP response is verified
-against a set of trust anchors, which are specified using
-@code{--load-trust}.  The trust anchors are concatenated certificates
-in PEM format.  The certificate that signed the OCSP response needs to
-be in the set of trust anchors, or the issuer of the signer
-certificate needs to be in the set of trust anchors and the OCSP
-Extended Key Usage bit has to be asserted in the signer certificate.
-
-@example
-$ ocsptool -e --load-trust issuer.pem --load-response ocsp-response.der
-@end example
-
-The tool will print status of verification.
-
-@subheading Verify signature in OCSP response against given certificate
-
-It is possible to override the normal trust logic if you know that a
-certain certificate is supposed to have signed the OCSP response, and
-you want to use it to check the signature.  This is achieved using
-@code{--load-signer} instead of @code{--load-trust}.  This will load
-one certificate and it will be used to verify the signature in the
-OCSP response.  It will not check the Extended Key Usage bit.
-
-@example
-$ ocsptool -e --load-signer ocsp-signer.pem --load-response ocsp-response.der
-@end example
-
-This approach is normally only relevant in two situations.  The first
-is when the OCSP response does not contain a copy of the signer
-certificate, so the @code{--load-trust} code would fail.  The second
-is if you want to avoid the indirect mode where the OCSP response
-signer certificate is signed by a trust anchor.
-
-@subheading Real-world example
-
-Here is an example of how to generate an OCSP request for a
-certificate and to verify the response.  For illustration we'll use
-the @code{blog.josefsson.org} host, which (as of writing) uses a
-certificate from CACert.  First we'll use @code{gnutls-cli} to get a
-copy of the server certificate chain.  The server is not required to
-send this information, but this particular one is configured to do so.
-
-@example
-$ echo | gnutls-cli -p 443 blog.josefsson.org --print-cert > chain.pem
-@end example
-
-Use a text editor on @code{chain.pem} to create three files for each
-separate certificates, called @code{cert.pem} for the first
-certificate for the domain itself, secondly @code{issuer.pem} for the
-intermediate certificate and @code{root.pem} for the final root
-certificate.
-
-The domain certificate normally contains a pointer to where the OCSP
-responder is located, in the Authority Information Access Information
-extension.  For example, from @code{certtool -i < cert.pem} there is
-this information:
-
-@example
-		Authority Information Access Information (not critical):
-			Access Method: 1.3.6.1.5.5.7.48.1 (id-ad-ocsp)
-			Access Location URI: http://ocsp.CAcert.org/
-@end example
-
-This means the CA support OCSP queries over HTTP.  We are now ready to
-create a OCSP request for the certificate.
-
-@example
-$ ocsptool --generate-request --load-issuer issuer.pem  --load-cert cert.pem --outfile ocsp-request.der
-@end example
-
-The request is sent base64 encoded via HTTP to the address indicated
-by the id-ad-ocsp extension, as follows.
-
-@example
-$ wget -O ocsp-response.der http://ocsp.CAcert.org/$(base64 -w0 ocsp-request.der)
-@end example
-
-The OCSP response is now in the file @code{ocsp-response.der} and you
-can view it using @code{ocsptool -j < ocsp-response.der}.  To verify
-the signature you need to load the issuer as the trust anchor.
-
-@example
-$ ocsptool --verify-response --load-trust issuer.pem --load-response ocsp-response.der
-Verifying OCSP Response: Success.
-$
-@end example
-
-This particular OCSP responder includes its signer certificate in the
-OCSP respnose, so you may extract it and use it together with
-@code{--load-signer} for verifying the signature directly against the
-certificate.
-
-@example
-$ ocsptool -j < ocsp-response.der > signer.pem
-$ ocsptool --verify-response --load-signer signer.pem --load-response ocsp-response.der
-Verifying OCSP Response: Success.
-$
-@end example
-
-You may experiment passing different certificates to
-@code{--load-trust} and @code{--load-signer} to find common error
-conditions for OCSP response verification failures.
+@include invoke-ocsptool.texi
 
 @node Smart cards and HSMs
 @section Smart cards and HSMs
@@ -954,7 +398,7 @@ system, being the @acronym{Gnome Keyring}.
 * Reading objects::
 * Writing objects::
 * Using a PKCS11 token with TLS::
-* The p11tool application::
+* p11tool Invocation::             Invoking p11tool
 @end menu
 
 @node PKCS11 Initialization
@@ -1078,102 +522,7 @@ certificates by specifying a PKCS #11 URL instead of a filename.
 
 @showfuncC{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file,gnutls_certificate_set_x509_simple_pkcs12_file}
 
-@node The p11tool application
-@subsection The p11tool application
-@anchor{p11tool}
-@cindex p11tool
-
-p11tool is a program that is used to access tokens
-and security modules that support the PKCS #11 API. It requires
-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{Smart cards and HSMs}.
-
-@example
-p11tool help
-Usage: p11tool [options]
-Usage: p11tool --list-tokens
-Usage: p11tool --list-all
-Usage: p11tool --export 'pkcs11:...'
-
-     --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 written as 
-                              trusted.
-     --private                Marks the object to be written as 
-                              private (requires PIN).
-     --no-private             Marks the object to be written as not 
-                              private.
-     --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 example
-
-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 are illustrated in the following  paragraphs.
-
-@subsubheading List all tokens
-@example
-$ p11tool --list-tokens
-@end example
-
-@subsubheading List all objects
-The following command will list all objects in a token. The @code{--login}
-is required to show objects marked as private.
-@example
-$ p11tool --login --list-all
-@end example
-
-@subsubheading Exporting an object
-To retrieve an object stored in the card use the following command.
-Note however that objects marked as sensitive (typically PKCS #11 private keys) 
-are not allowed to be extracted from the token.
-@example 
-$ p11tool --login --export [OBJECT URL]
-@end example
-
-@subsubheading Copy an object to a token
-To copy an object, such as a certificate or private key to a token
-use the following command.
-@example 
-$ p11tool --login --write [TOKEN URL] \
-  --load-certificate cert.pem --label "my_cert"
-@end example
-
+@include invoke-p11tool.texi
 
 @node Abstract key types
 @section Abstract key types
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index f716bb8a03..9207c26a8b 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -935,7 +935,7 @@ will allow V1 CAs in chains.
 @end float
 
 Finally the ciphersuites enabled by any priority string can be
-listed using the @code{gnutls-cli} application (see @ref{The gnutls-cli tool}), 
+listed using the @code{gnutls-cli} application (see @ref{gnutls-cli Invocation}), 
 or by using the priority functions as in @ref{Listing the ciphersuites in a priority string}.
 
 Example priority strings are:
diff --git a/doc/cha-programs.texi b/doc/cha-programs.texi
index bf08d29038..4526747e30 100644
--- a/doc/cha-programs.texi
+++ b/doc/cha-programs.texi
@@ -6,393 +6,14 @@ let you use the library for common tasks without writing an
 application.  The applications are discussed in this chapter.
 
 @menu
-* The gnutls-cli tool::
-* The gnutls-serv tool::
-* The gnutls-cli-debug tool::
+* gnutls-cli Invocation::          Invoking gnutls-cli
+* gnutls-serv Invocation::         Invoking gnutls-serv
+* gnutls-cli-debug Invocation::    Invoking gnutls-cli-debug
 @end menu
+@c @include invoke-gnutls-cli.menu
+@c @include invoke-gnutls-serv.menu
+@c @include invoke-gnutls-cli-debug.menu
 
-@node The gnutls-cli tool
-@section The gnutls-cli tool
-@cindex gnutls-cli
-
-Simple client program to set up a TLS connection to some other
-computer.  It sets up a TLS connection and forwards data from the
-standard input to the secured socket and vice versa.
-
-@example
-GnuTLS test client
-Usage:  gnutls-cli [options] hostname
-
-     -d, --debug integer      Enable debugging
-     -r, --resume             Connect, establish a session. Connect
-                              again and resume this session.
-     -s, --starttls           Connect, establish a plain session and
-                              start TLS when EOF or a SIGALRM is
-                              received.
-     --crlf                   Send CR LF instead of LF.
-     --x509fmtder             Use DER format for certificates to read
-                              from.
-     -f, --fingerprint        Send the openpgp fingerprint, instead
-                              of the key.
-     --disable-extensions     Disable all the TLS extensions.
-     --print-cert             Print the certificate in PEM format.
-     --recordsize integer     The maximum record size to advertize.
-     -V, --verbose            More verbose output.
-     --ciphers cipher1 cipher2...
-                              Ciphers to enable.
-     --protocols protocol1 protocol2...
-                              Protocols to enable.
-     --comp comp1 comp2...    Compression methods to enable.
-     --macs mac1 mac2...      MACs to enable.
-     --kx kx1 kx2...          Key exchange methods to enable.
-     --ctypes certType1 certType2...
-                              Certificate types to enable.
-     --priority PRIORITY STRING
-                              Priorities string.
-     --x509cafile FILE        Certificate file to use.
-     --x509crlfile FILE       CRL file to use.
-     --pgpkeyfile FILE        PGP Key file to use.
-     --pgpkeyring FILE        PGP Key ring file to use.
-     --pgpcertfile FILE       PGP Public Key (certificate) file to
-                              use.
-     --pgpsubkey HEX|auto     PGP subkey to use.
-     --x509keyfile FILE       X.509 key file to use.
-     --x509certfile FILE      X.509 Certificate file to use.
-     --srpusername NAME       SRP username to use.
-     --srppasswd PASSWD       SRP password to use.
-     --pskusername NAME       PSK username to use.
-     --pskkey KEY             PSK key (in hex) to use.
-     --opaque-prf-input DATA
-                              Use Opaque PRF Input DATA.
-     -p, --port PORT          The port to connect to.
-     --insecure               Don't abort program if server
-                              certificate can't be validated.
-     -l, --list               Print a list of the supported
-                              algorithms and modes.
-     -h, --help               prints this help
-     -v, --version            prints the program's version number
-@end example
-
-@subheading Example client PSK connection
-@cindex PSK client
-
-To connect to a server using PSK authentication, you need to enable
-the choice of PSK by using a cipher priority parameter such as in the
-example below.
-
-@example
-$ ./gnutls-cli -p 5556 localhost --pskusername psk_identity \
-  --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 \
-  --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
-Resolving 'localhost'...
-Connecting to '127.0.0.1:5556'...
-- PSK authentication.
-- Version: TLS1.1
-- Key Exchange: PSK
-- Cipher: AES-128-CBC
-- MAC: SHA1
-- Compression: NULL
-- Handshake was completed
-
-- Simple Client Mode:
-@end example
-
-By keeping the @code{--pskusername} parameter and removing the
-@code{--pskkey} parameter, it will query only for the password during
-the handshake.
-
-@subheading Listing the ciphersuites in a priority string
-@cindex Priority strings
-
-@example
-$ ./gnutls-cli --priority SECURE192 -l
-Cipher suites for SECURE192
-TLS_ECDHE_ECDSA_AES_256_CBC_SHA384                0xc0, 0x24	TLS1.2
-TLS_ECDHE_ECDSA_AES_256_GCM_SHA384                0xc0, 0x2e	TLS1.2
-TLS_ECDHE_RSA_AES_256_GCM_SHA384                  0xc0, 0x30	TLS1.2
-TLS_DHE_RSA_AES_256_CBC_SHA256                    0x00, 0x6b	TLS1.2
-TLS_DHE_DSS_AES_256_CBC_SHA256                    0x00, 0x6a	TLS1.2
-TLS_RSA_AES_256_CBC_SHA256                        0x00, 0x3d	TLS1.2
-
-Certificate types: CTYPE-X.509
-Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
-Compression: COMP-NULL
-Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
-PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
-@end example
-
-
-@node The gnutls-serv tool
-@section The gnutls-serv tool
-@cindex gnutls-serv
-
-Simple server program that listens to incoming TLS connections.
-
-@example
-GnuTLS test server
-Usage: gnutls-serv [options]
-
-     -d, --debug integer      Enable debugging
-     -g, --generate           Generate Diffie-Hellman Parameters.
-     -p, --port integer       The port to connect to.
-     -q, --quiet              Suppress some messages.
-     --nodb                   Does not use the resume database.
-     --http                   Act as an HTTP Server.
-     --echo                   Act as an Echo Server.
-     --dhparams FILE          DH params file to use.
-     --x509fmtder             Use DER format for certificates
-     --x509cafile FILE        Certificate file to use.
-     --x509crlfile FILE       CRL file to use.
-     --pgpkeyring FILE        PGP Key ring file to use.
-     --pgpkeyfile FILE        PGP Key file to use.
-     --pgpcertfile FILE       PGP Public Key (certificate) file to
-                              use.
-     --pgpsubkey HEX|auto     PGP subkey to use.
-     --x509keyfile FILE       X.509 key file to use.
-     --x509certfile FILE      X.509 Certificate file to use.
-     --x509dsakeyfile FILE    Alternative X.509 key file to use.
-     --x509dsacertfile FILE   Alternative X.509 certificate file to
-                              use.
-     -r, --require-cert       Require a valid certificate.
-     -a, --disable-client-cert
-                              Disable request for a client
-                              certificate.
-     --pskpasswd FILE         PSK password file to use.
-     --pskhint HINT           PSK identity hint to use.
-     --srppasswd FILE         SRP password file to use.
-     --srppasswdconf FILE     SRP password conf file to use.
-     --opaque-prf-input DATA
-                              Use Opaque PRF Input DATA.
-     --ciphers cipher1 cipher2...
-                              Ciphers to enable.
-     --protocols protocol1 protocol2...
-                              Protocols to enable.
-     --comp comp1 comp2...    Compression methods to enable.
-     --macs mac1 mac2...      MACs to enable.
-     --kx kx1 kx2...          Key exchange methods to enable.
-     --ctypes certType1 certType2...
-                              Certificate types to enable.
-     --priority PRIORITY STRING
-                              Priorities string.
-     -l, --list               Print a list of the supported
-                              algorithms  and modes.
-     -h, --help               prints this help
-     -v, --version            prints the program's version number
-@end example
-
-@subheading Setting up a test HTTPS server
-@cindex HTTPS server
-@cindex debug server
-
-Running your own TLS server based on GnuTLS can be useful when
-debugging clients and/or GnuTLS itself.  This section describes how to
-use @code{gnutls-serv} as a simple HTTPS server.
-
-The most basic server can be started as:
-
-@example
-gnutls-serv --http
-@end example
-
-It will only support anonymous ciphersuites, which many TLS clients
-refuse to use.
-
-The next step is to add support for X.509.  First we generate a CA:
-
-@example
-$ certtool --generate-privkey > x509-ca-key.pem
-$ echo 'cn = GnuTLS test CA' > ca.tmpl
-$ echo 'ca' >> ca.tmpl
-$ echo 'cert_signing_key' >> ca.tmpl
-$ certtool --generate-self-signed --load-privkey x509-ca-key.pem \
-  --template ca.tmpl --outfile x509-ca.pem
-...
-@end example
-
-Then generate a server certificate.  Remember to change the dns_name
-value to the name of your server host, or skip that command to avoid
-the field.
-
-@example
-$ certtool --generate-privkey > x509-server-key.pem
-$ echo 'organization = GnuTLS test server' > server.tmpl
-$ echo 'cn = test.gnutls.org' >> server.tmpl
-$ echo 'tls_www_server' >> server.tmpl
-$ echo 'encryption_key' >> server.tmpl
-$ echo 'signing_key' >> server.tmpl
-$ echo 'dns_name = test.gnutls.org' >> server.tmpl
-$ certtool --generate-certificate --load-privkey x509-server-key.pem \
-  --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
-  --template server.tmpl --outfile x509-server.pem
-...
-@end example
-
-For use in the client, you may want to generate a client certificate
-as well.
-
-@example
-$ certtool --generate-privkey > x509-client-key.pem
-$ echo 'cn = GnuTLS test client' > client.tmpl
-$ echo 'tls_www_client' >> client.tmpl
-$ echo 'encryption_key' >> client.tmpl
-$ echo 'signing_key' >> client.tmpl
-$ certtool --generate-certificate --load-privkey x509-client-key.pem \
-  --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
-  --template client.tmpl --outfile x509-client.pem
-...
-@end example
-
-To be able to import the client key/certificate into some
-applications, you will need to convert them into a PKCS#12 structure.
-This also encrypts the security sensitive key with a password.
-
-@example
-$ certtool --to-p12 --load-ca-certificate x509-ca.pem \
-  --load-privkey x509-client-key.pem --load-certificate x509-client.pem \
-  --outder --outfile x509-client.p12
-@end example
-
-For icing, we'll create a proxy certificate for the client too.
-
-@example
-$ certtool --generate-privkey > x509-proxy-key.pem
-$ echo 'cn = GnuTLS test client proxy' > proxy.tmpl
-$ certtool --generate-proxy --load-privkey x509-proxy-key.pem \
-  --load-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem \
-  --load-certificate x509-client.pem --template proxy.tmpl \
-  --outfile x509-proxy.pem
-...
-@end example
-
-Then start the server again:
-
-@example
-$ gnutls-serv --http \
-            --x509cafile x509-ca.pem \
-            --x509keyfile x509-server-key.pem \
-            --x509certfile x509-server.pem
-@end example
-
-Try connecting to the server using your web browser.  Note that the
-server listens to port 5556 by default.
-
-While you are at it, to allow connections using DSA, you can also
-create a DSA key and certificate for the server.  These credentials
-will be used in the final example below.
-
-@example
-$ certtool --generate-privkey --dsa > x509-server-key-dsa.pem
-$ certtool --generate-certificate --load-privkey x509-server-key-dsa.pem \
-  --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
-  --template server.tmpl --outfile x509-server-dsa.pem
-...
-@end example
-
-The next step is to create OpenPGP credentials for the server.
-
-@example
-gpg --gen-key
-...enter whatever details you want, use 'test.gnutls.org' as name...
-@end example
-
-Make a note of the OpenPGP key identifier of the newly generated key,
-here it was @code{5D1D14D8}.  You will need to export the key for
-GnuTLS to be able to use it.
-
-@example
-gpg -a --export 5D1D14D8 > openpgp-server.txt
-gpg --export 5D1D14D8 > openpgp-server.bin
-gpg --export-secret-keys 5D1D14D8 > openpgp-server-key.bin
-gpg -a --export-secret-keys 5D1D14D8 > openpgp-server-key.txt
-@end example
-
-Let's start the server with support for OpenPGP credentials:
-
-@example
-gnutls-serv --http \
-            --pgpkeyfile openpgp-server-key.txt \
-            --pgpcertfile openpgp-server.txt
-@end example
-
-The next step is to add support for SRP authentication. This requires
-an SRP password file (see @ref{Invoking srptool}).
-To start the server with SRP support:
-
-@example
-gnutls-serv --http \
-            --srppasswdconf srp-tpasswd.conf \
-            --srppasswd srp-passwd.txt
-@end example
-
-Let's also start a server with support for PSK. This would require
-a password file created with @code{psktool} (see @ref{Invoking psktool}).
-
-@example
-gnutls-serv --http \
-            --pskpasswd psk-passwd.txt
-@end example
-
-Finally, we start the server with all the earlier parameters and you
-get this command:
-
-@example
-gnutls-serv --http \
-            --x509cafile x509-ca.pem \
-            --x509keyfile x509-server-key.pem \
-            --x509certfile x509-server.pem \
-            --x509dsakeyfile x509-server-key-dsa.pem \
-            --x509dsacertfile x509-server-dsa.pem \
-            --pgpkeyfile openpgp-server-key.txt \
-            --pgpcertfile openpgp-server.txt \
-            --srppasswdconf srp-tpasswd.conf \
-            --srppasswd srp-passwd.txt \
-            --pskpasswd psk-passwd.txt
-@end example
-
-
-@node The gnutls-cli-debug tool
-@section The gnutls-cli-debug tool
-@cindex gnutls-cli-debug
-
-This program was created to assist in debugging @acronym{GnuTLS}, but
-it might be useful to extract a @acronym{TLS} server's capabilities.
-It's purpose is to connect onto a @acronym{TLS} server, perform some
-tests and print the server's capabilities. If called with the `-v'
-parameter more checks will be performed. An example output is:
-
-@example
-crystal:/cvs/gnutls/src$ ./gnutls-cli-debug localhost -p 5556
-Resolving 'localhost'...
-Connecting to '127.0.0.1:5556'...
-Checking for TLS 1.1 support... yes
-Checking fallback from TLS 1.1 to... N/A
-Checking for TLS 1.0 support... yes
-Checking for SSL 3.0 support... yes
-Checking for version rollback bug in RSA PMS... no
-Checking for version rollback bug in Client Hello... no
-Checking whether we need to disable TLS 1.0... N/A
-Checking whether the server ignores the RSA PMS version... no
-Checking whether the server can accept Hello Extensions... yes
-Checking whether the server can accept cipher suites not in SSL 3.0 spec... yes
-Checking for certificate information... N/A
-Checking for trusted CAs... N/A
-Checking whether the server understands TLS closure alerts... yes
-Checking whether the server supports session resumption... yes
-Checking for export-grade ciphersuite support... no
-Checking RSA-export ciphersuite info... N/A
-Checking for anonymous authentication support... no
-Checking anonymous Diffie-Hellman group info... N/A
-Checking for ephemeral Diffie-Hellman support... no
-Checking ephemeral Diffie-Hellman group info... N/A
-Checking for AES cipher support (TLS extension)... yes
-Checking for 3DES cipher support... yes
-Checking for ARCFOUR 128 cipher support... yes
-Checking for ARCFOUR 40 cipher support... no
-Checking for MD5 MAC support... yes
-Checking for SHA1 MAC support... yes
-Checking for ZLIB compression support (TLS extension)... yes
-Checking for max record size (TLS extension)... yes
-Checking for SRP authentication support (TLS extension)... yes
-Checking for OpenPGP authentication support (TLS extension)... no
-@end example
-
+@include invoke-gnutls-cli.texi
+@include invoke-gnutls-serv.texi
+@include invoke-gnutls-cli-debug.texi
diff --git a/doc/cha-shared-key.texi b/doc/cha-shared-key.texi
index 28405aa110..a8730f41d9 100644
--- a/doc/cha-shared-key.texi
+++ b/doc/cha-shared-key.texi
@@ -16,7 +16,7 @@ The rest of this chapter discusses details of these methods.
 
 @menu
 * Authentication using SRP::
-* Invoking srptool::
+* srptool Invocation::             Invoking srptool
 @end menu
 
 @node Authentication using SRP
@@ -67,53 +67,20 @@ authenticated using a certificate with RSA parameters.
 Helper functions are included in @acronym{GnuTLS}, used to generate and
 maintain @acronym{SRP} verifiers and password files.  A program to
 manipulate the required parameters for @acronym{SRP} authentication is
-also included.  See @ref{srptool}, for more information.
+also included.  See @ref{srptool Invocation}, for more information.
 
 @showfuncdesc{gnutls_srp_verifier}
 
 @showfuncB{gnutls_srp_base64_encode,gnutls_srp_base64_decode}
 
-@node Invoking srptool
-@subsection Invoking srptool
-@anchor{srptool}
-@cindex srptool
-
-The @file{srptool} is a very simple program that emulates the programs
-in the @emph{Stanford SRP libraries}@footnote{See
-@url{http://srp.stanford.edu/}.}. It requires two files,
-one called @code{tpasswd} which holds usernames and verifiers, 
-and @code{tpasswd.conf} which holds generators and primes.
-
-To create tpasswd.conf which holds the generator and prime values for
-the @acronym{SRP} protocol, run:
-
-@example
-$ srptool --create-conf /etc/tpasswd.conf
-@end example
-
-This command will create /etc/tpasswd and will add user 'test' (you
-will also be prompted for a password).  Verifiers are stored in a way that
-is compatible with libsrp.
-
-@example
-$ srptool --passwd /etc/tpasswd \
-    --passwd-conf /etc/tpasswd.conf -u test
-@end example
-
-This command will check against a password.  If the password matches
-the one in /etc/tpasswd you will get an ok.
-
-@example
-$ srptool --passwd /etc/tpasswd \
-    --passwd-conf /etc/tpasswd.conf --verify -u test
-@end example
+@include invoke-srptool.texi
 
 @node PSK authentication
 @section PSK authentication
 
 @menu
 * Authentication using PSK::
-* Invoking psktool::
+* psktool Invocation::             Invoking psktool
 @end menu
 
 @node Authentication using PSK
@@ -149,36 +116,7 @@ in @acronym{GnuTLS}.
 
 @showfuncC{gnutls_key_generate,gnutls_hex_encode,gnutls_hex_decode}
 
-@node Invoking psktool
-@subsection Invoking psktool
-@cindex psktool
-
-This is a program to manage @acronym{PSK} username and keys.
-It will generate random keys for the indicated username, 
-using a simple password file format.
-
-@example
-PSKtool help
-Usage : psktool [options]
-     -u, --username username
-                              specify username.
-     -p, --passwd FILE        specify a password file.
-     -s, --keysize SIZE       specify the key size in bytes.
-     -v, --version            prints the program's version number
-     -h, --help               shows this help text
-@end example
-
-The generation of a PSK password file is illustrated in the example below. 
-The password is provided in the prompt.
-
-@example
-$ ./psktool -u psk_identity -p psks.txt
-Generating a random key for user 'psk_identity'
-Key stored to psks.txt
-$ cat psks.txt
-psk_identity:88f3824b3e5659f52d00e959bacab954b6540344
-$
-@end example
+@include invoke-psktool.texi
 
 @node Anonymous authentication
 @section Anonymous authentication