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

1 files changed, 6 insertions, 657 deletions

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