Tools are discussed in the relevant chapters and sections.

1 files changed, 50 insertions, 561 deletions

diff --git a/doc/cha-programs.texi b/doc/cha-programs.texi
index 7bb39acfb9..fda5f376d1 100644
--- a/doc/cha-programs.texi
+++ b/doc/cha-programs.texi
@@ -1,362 +1,18 @@
-@node Included programs
-@chapter Included programs
+@node Other included programs
+@chapter Other included programs
 
 Included with @acronym{GnuTLS} are also a few command line tools that
 let you use the library for common tasks without writing an
 application.  The applications are discussed in this chapter.
 
 @menu
-* Invoking certtool::
-* Invoking gnutls-cli::
-* Invoking gnutls-cli-debug::
-* Invoking gnutls-serv::
-* Invoking psktool::
-* Invoking srptool::
-* Invoking p11tool::
+* The gnutls-cli tool::
+* The gnutls-serv tool::
+* The gnutls-cli-debug tool::
 @end menu
 
-@node Invoking certtool
-@section Invoking certtool
-@cindex certtool
-
-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.
-
-@subsection Diffie-Hellman parameter generation
-To generate parameters for Diffie-Hellman key exchange, use the command:
-@smallexample
-$ certtool --generate-dh-params --outfile dh.pem
-@end smallexample
-
-@subsection Self-signed certificate generation
-
-To create a self signed certificate, use the command:
-@smallexample
-$ certtool --generate-privkey --outfile ca-key.pem
-$ certtool --generate-self-signed --load-privkey ca-key.pem \
-   --outfile ca-cert.pem
-@end smallexample
-
-Note that a self-signed certificate usually belongs to a certificate
-authority, that signs other certificates.
-
-@subsection Private key generation
-To create a private key (RSA by default), run:
-
-@smallexample
-$ certtool --generate-privkey --outfile key.pem
-@end smallexample
-
-To create a DSA or elliptic curves (ECDSA) private key use the
-above command combined with @code{--dsa} or @code{--ecc} options.
-
-@subsection Certificate generation
-To generate a certificate using the private key, use the command:
-
-@smallexample
-$ certtool --generate-certificate --load-privkey key.pem \
-   --outfile cert.pem --load-ca-certificate ca-cert.pem \
-   --load-ca-privkey ca-key.pem
-@end smallexample
-
-Alternatively you may create a certificate request, which is needed
-when the certificate will be signed by a third party authority.
-
-@smallexample
-$ certtool --generate-request --load-privkey key.pem \
-  --outfile request.pem
-@end smallexample
-
-If the private key is stored in a smart card you can generate
-a request by specifying the private key object URL (see @ref{Invoking p11tool}
-on how to obtain the URL).
-
-@smallexample
-$ certtool --generate-request --load-privkey pkcs11:(PRIVKEY URL) \
-  --load-pubkey pkcs11:(PUBKEY URL) --outfile request.pem
-@end smallexample
-
-To generate a certificate using the previous request, use the command:
-
-@smallexample
-$ certtool --generate-certificate --load-request request.pem \
-   --outfile cert.pem \
-   --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
-@end smallexample
-
-@subsection Certificate information
-To view the certificate information, use:
-
-@smallexample
-$ certtool --certificate-info --infile cert.pem
-@end smallexample
-
-@subsection @acronym{PKCS} #12 structure generation
-To generate a @acronym{PKCS} #12 structure using the previous key and
-certificate, use the command:
-
-@smallexample
-$ certtool --load-certificate cert.pem --load-privkey key.pem \
-  --to-p12 --outder --outfile key.p12
-@end smallexample
-
-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:
-
-@smallexample
-$ certtool --load-ca-certificate ca.pem \
-  --load-certificate cert.pem --load-privkey key.pem \
-  --to-p12 --outder --outfile key.p12
-@end smallexample
-
-@subsection 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:
-
-@smallexample
-$ 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 smallexample
-
-@subsection Certificate revocation list generation
-To create an empty Certificate Revocation List (CRL) do:
-
-@smallexample
-$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
-           --load-ca-certificate x509-ca.pem
-@end smallexample
-
-To create a CRL that contains some revoked certificates, place the
-certificates in a file and use @code{--load-certificate} as follows:
-
-@smallexample
-$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
-  --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
-@end smallexample
-
-To verify a Certificate Revocation List (CRL) do:
-
-@smallexample
-$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
-@end smallexample
-
-
-
-@subsection 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:
-
-@smallexample
-$ 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 smallexample
-
-An example certtool template file:
-
-@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." "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"
-
-# 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
-@end example
-
-@node Invoking gnutls-cli
-@section Invoking gnutls-cli
+@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
@@ -450,54 +106,8 @@ By keeping the @code{--pskusername} parameter and removing the
 @code{--pskkey} parameter, it will query only for the password during
 the handshake.
 
-@node Invoking gnutls-cli-debug
-@section Invoking gnutls-cli-debug
-@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
-
-@node Invoking gnutls-serv
-@section Invoking gnutls-serv
+@node The gnutls-serv tool
+@section The gnutls-serv tool
 @cindex gnutls-serv
 
 Simple server program that listens to incoming TLS connections.
@@ -723,171 +333,50 @@ gnutls-serv --http \
             --pskpasswd psk-passwd.txt
 @end smallexample
 
-@node Invoking psktool
-@section 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.
-
-@smallexample
-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 smallexample
-
-The generation of a PSK password file is illustrated in the example below. 
-The password is provided in the prompt.
-
-@smallexample
-$ ./psktool -u psk_identity -p psks.txt
-Enter password:
-Key stored to psks.txt
-$ cat psks.txt
-psk_identity:88f3824b3e5659f52d00e959bacab954b6540344
-$
-@end smallexample
-
-@node Invoking srptool
-@section 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 is intended for use in places
-where you don't expect @acronym{SRP} authentication to be the used for
-system users.
-
-Traditionally @emph{libsrp} used two files. One called @code{tpasswd}
-which holds usernames and verifiers, and @code{tpasswd.conf} which
-holds generators and primes.
-
-@subsection How to use srptool
-
-To create tpasswd.conf which holds the g and n values for
-@acronym{SRP} protocol (generator and a large prime), run:
-
-@smallexample
-$ srptool --create-conf /etc/tpasswd.conf
-@end smallexample
-
-This command will create /etc/tpasswd and will add user 'test' (you
-will also be prompted for a password).  Verifiers are stored by
-default in the way libsrp expects.
-
-@smallexample
-$ srptool --passwd /etc/tpasswd \
-    --passwd-conf /etc/tpasswd.conf -u test
-@end smallexample
-
-This command will check against a password.  If the password matches
-the one in /etc/tpasswd you will get an ok.
-
-@smallexample
-$ srptool --passwd /etc/tpasswd \
-    --passwd-conf /etc/tpasswd.conf --verify -u test
-@end smallexample
 
-@node Invoking p11tool
-@section Invoking p11tool
-@anchor{p11tool}
-@cindex p11tool
+@node The gnutls-cli-debug tool
+@section The gnutls-cli-debug tool
+@cindex gnutls-cli-debug
 
-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{Hardware tokens}.
+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
-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
+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
 
-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.
-
-@subsection List all tokens
-@smallexample
-$ p11tool --list-tokens
-@end smallexample
-
-@subsection List all objects
-The following command will list all objects in a token. The @code{--login}
-is required to show objects marked as private.
-@smallexample
-$ p11tool --login --list-all
-@end smallexample
-
-@subsection 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.
-@smallexample 
-$ p11tool --login --export pkcs11:(OBJECT URL)
-@end smallexample
-
-@subsection Copy an object to a token
-To copy an object, such as a certificate or private key to a token
-use the following command.
-@smallexample 
-$ p11tool --login --write pkcs11:(TOKEN URL) \
-  --load-certificate cert.pem --label "my_cert"
-@end smallexample
-