Added new manpages by Ivo.

6 files changed, 288 insertions, 93 deletions

diff --git a/doc/manpages/Makefile.am b/doc/manpages/Makefile.am
index c68c95fac8..199f63bf4b 100644
--- a/doc/manpages/Makefile.am
+++ b/doc/manpages/Makefile.am
@@ -1,3 +1,3 @@
-man_MANS = gnutls-cli.1 gnutls-cli-debug.1 gnutls-serv.1 gnutls-srpcrypt.1
-EXTRA_DIST = gnutls-cli.1 gnutls-cli-debug.1 gnutls-serv.1 gnutls-srpcrypt.1
+man_MANS = gnutls-cli.1 gnutls-cli-debug.1 gnutls-serv.1 gnutls-srpcrypt.1 certtool.1
+EXTRA_DIST = gnutls-cli.1 gnutls-cli-debug.1 gnutls-serv.1 gnutls-srpcrypt.1 certtool.1
 
diff --git a/doc/manpages/certtool.1 b/doc/manpages/certtool.1
new file mode 100644
index 0000000000..35a9de17ed
--- /dev/null
+++ b/doc/manpages/certtool.1
@@ -0,0 +1,127 @@
+.TH certtool 1 "December 1st 2003"
+.SH NAME
+certtool \- Manipulate certificates and keys.
+.SH SYNOPSIS
+certtool [\fIoptions\fR]
+.SH DESCRIPTION
+Generate X.509 certificates, certificate requests, and private keys.
+.SH OPTIONS
+.SS Program control options
+.IP "\-\-copyright"
+Shows the program's license
+.IP "\-d, \-\-debug LEVEL"
+Specify the debug level. Default is 1.
+.IP "\-h, \-\-help"
+Shows this help text
+.IP "\-v, \-\-version"
+Shows the program's version
+
+.SS Getting information
+.IP "\-i, \-\-certificate\-info"
+Print information on a certificate.
+.IP "\-k, \-\-key\-info"
+Print information on a private key.
+.IP "\-l, \-\-crl\-info"
+Print information on a CRL.
+.IP "\-\-p12\-info"
+Print information on a PKCS #12 structure.
+
+.SS Generating/verifying certificates/keys
+.IP "\-c, \-\-generate\-certificate"
+Generate a signed certificate.
+.IP "\-e, \-\-verify\-chain"
+Verify a PEM encoded certificate chain.  The last certificate in the chain must be a self signed one.
+.IP "\-\-generate\-dh\-params"
+Generate PKCS #3 encoded Diffie Hellman parameters.
+.IP "\-\-load\-ca\-certificate FILE"
+Certificate authority's certificate file to use.
+.IP "\-\-load\-ca\-privkey FILE"
+Certificate authority's private key file to use.
+.IP "\-\-load\-certificate FILE"
+Certificate file to use.
+.IP "\-\-load\-privkey FILE"
+Private key file to use.
+.IP "\-\-load\-request FILE"
+Certificate request file to use.
+.IP "\-p, \-\-generate\-privkey"
+Generate a private key.
+.IP "\-q, \-\-generate\-request"
+Generate a PKCS #10 certificate request.
+.IP "\-s, \-\-generate\-self\-signed"
+Generate a self-signed certificate.
+.IP "\-u, \-\-update\-certificate"
+Update a signed certificate.
+
+.SS Controlling output
+.IP "\-8, \-\-pkcs8"
+Use PKCS #8 format for private keys.
+.IP "\-\-bits BITS"
+Specify the number of bits for key generation.
+.IP "\-\-export\-ciphers"
+Use weak encryption algorithms.
+.IP "\-\-inder"
+Use DER format for input certificates and private keys.
+.IP "\-\-infile FILE"
+Output file.
+.IP "\-\-outder"
+Use DER format for output certificates and private keys.
+.IP "\-\-outfile FILE"
+Output file.
+.IP "\-\-password PASSWORD"
+Password to use.
+.IP "\-\-to\-p12"
+Generate a PKCS #12 structure.
+
+
+.SH EXAMPLES
+To create a private key, run:
+
+.RS
+.nf
+$ certtool \-\-generate\-privkey \-\-outfile key.pem
+.fi
+.RE
+
+To create a certificate request, run:
+
+.RS
+.nf
+$ certtool \-\-generate\-request \-\-load\-privkey key.pem \\
+   \-\-outfile request.pem
+.fi
+.RE
+
+To generate a certificate using the previous request, use the command:
+
+.RS
+.nf
+$ certtool \-\-generate\-certificate \-\-load\-request request.pem \\
+   \-\-outfile cert.pem \-\-load\-ca\-certificate ca\-cert.pem \\
+   \-\-load\-ca\-privkey ca\-key.pem
+.fi
+.RE
+
+To view the certificate information, use:
+
+.RS
+.nf
+$ certtool \-\-certificate\-info \-\-infile cert.pem
+.fi
+.RE
+
+To generate a PKCS #12 structure using the previous key and certificate, use the command:
+
+.RS
+.nf
+$ certtool \-\-load\-certificate cert.pem \-\-load\-privkey key.pem \\
+   \-\-to\-p12 \-\-outder \-\-outfile key.p12
+.fi
+.RE
+
+.SH AUTHOR
+.PP
+Nikos Mavroyanopoulos <nmav@gnutls.org> and others; see
+/usr/share/doc/gnutls\-bin/AUTHORS for a complete list.
+.PP
+This manual page was written by Ivo Timmermans <ivo@debian.org>, for
+the Debian GNU/Linux system (but may be used by others).
diff --git a/doc/manpages/gnutls-cli-debug.1 b/doc/manpages/gnutls-cli-debug.1
index c158fecb47..eec3972ae9 100644
--- a/doc/manpages/gnutls-cli-debug.1
+++ b/doc/manpages/gnutls-cli-debug.1
@@ -1,4 +1,4 @@
-.TH gnutls\-cli\-debug 1 "October 26th 2003"
+.TH gnutls\-cli\-debug 1 "December 1st 2003"
 .SH NAME
 gnutls\-cli\-debug \- GNU TLS test client, with verbose output
 .SH SYNOPSIS
@@ -11,12 +11,14 @@ it sets up a TLS connection and forwards data from the standard input
 to the socket.  Any information about the TLS control connection is
 printed to standard error.
 .SH OPTIONS
+.IP "\-d, \-\-debug \fIinteger\fR"
+Enable debugging.
 .IP "\-p, \-\-port \fIinteger\fR"
 The port to connect to.
-.IP "\-v, \-\-verbose"
-Even more verbose output.
 .IP "\-h, \-\-help"
 Prints a short reminder of the command line options.
+.IP "\-v, \-\-verbose"
+Even more verbose output.
 .SH "SEE ALSO"
 .BR gnutls\-cli (1),
 .BR gnutls\-serv (1)
diff --git a/doc/manpages/gnutls-cli.1 b/doc/manpages/gnutls-cli.1
index afa8d67533..3d50adaf67 100644
--- a/doc/manpages/gnutls-cli.1
+++ b/doc/manpages/gnutls-cli.1
@@ -1,67 +1,82 @@
-.TH gnutls\-cli 1 "October 26th 2003"
+.TH gnutls\-cli 1 "December 1st 2003"
 .SH NAME
 gnutls\-cli \- GNU TLS test client
 .SH SYNOPSIS
 gnutls\-cli [\fIoptions\fR] \fIhostname\fI
 .SH DESCRIPTION
 Simple client program to set up a TLS connection to some other
-computer.
+computer.  It sets up a TLS connection and forwards data from the
+standard input to the secured socket and vice versa.
 .SH OPTIONS
+.SS Program control options
+.IP "\-\-copyright"
+Prints the program's license.
+.IP "\-d, \-\-debug LEVEL"
+Specify the debug level. Default is 1.
+.IP "\-h, \-\-help"
+Prints a short reminder of the command line options.
+.IP "\-l, \-\-list"
+Print a list of the supported algorithms and modes.
 .IP "\-r, \-\-resume"
 Connect, establish a session.  Connect again and resume this session.
 .IP "\-s, \-\-starttls"
 Connect, establish a plain session and start TLS when EOF is sent from
 the keyboard.
+.IP "\-v, \-\-version"
+Prints the program's version number.
+
+.SS TLS/SSL control options
+.IP "\-\-ciphers \fIcipher1 cipher2...\fR"
+Ciphers to enable (use \fBgnutls\-cli \-\-list\fR to show the
+supported ciphers).
+.IP "\-\-comp \fIcomp1 comp2...\fR"
+Compression methods to enable (use \fBgnutls\-cli \-\-list\fR to show
+the supported compression methods).
 .IP "\-\-crlf"
 Send CR LF instead of LF.
-.IP "\-\-x509fmtder"
-Use DER format for certificates
+.IP "\-\-ctypes \fIcertType1 certType2...\fR"
+Certificate types to enable (use \fBgnutls\-cli \-\-list\fR to show
+the supported certificate types).
 .IP "\-f, \-\-fingerprint"
 Send the openpgp fingerprint, instead of the key.
-.IP "\-\-xml"
-Print the certificate information in XML format.
+.IP "\-\-kx \fIkx1 kx2...\fR"
+Key exchange methods to enable (use \fBgnutls\-cli \-\-list\fR to show
+the supported key exchange methods).
+.IP "\-\-macs \fImac1 mac2...\fR"
+MACs (Message Authentication Codes) to enable (use \fBgnutls\-cli
+\-\-list\fR to show the supported MACs).
 .IP "\-p, \-\-port \fIinteger\fR"
 The port to connect to.
+.IP "\-\-protocols \fIprotocol1 protocol2...\fR"
+Protocols to enable (use \fBgnutls\-cli \-\-list\fR to show the
+supported protocols).
 .IP "\-\-recordsize \fIinteger\fR"
 The maximum record size to advertize.
-.IP "\-\-ciphers \fIcipher1 cipher2...\fR"
-Ciphers to enable.
-.IP "\-\-protocols \fIprotocol1 protocol2...\fR"
-Protocols to enable.
-.IP "\-\-comp \fIcomp1 comp2...\fR"
-Compression methods to enable.
-.IP "\-\-macs \fImac1 mac2...\fR"
-MACs to enable.
-.IP "\-\-kx \fIkx1 kx2...\fR"
-Key exchange methods to enable.
-.IP "\-\-ctypes \fIcertType1 certType2...\fR"
-Certificate types to enable.
-.IP "\-\-x509cafile \fIFILE\fR"
-Certificate file to use.
+
+.SS Certificate options
+.IP "\-\-pgpcertfile \fIFILE\fR"
+PGP Public Key (certificate) file to use.
 .IP "\-\-pgpkeyfile \fIFILE\fR"
 PGP Key file to use.
 .IP "\-\-pgpkeyring \fIFILE\fR"
 PGP Key ring file to use.
 .IP "\-\-pgptrustdb \fIFILE\fR"
 PGP trustdb file to use.
-.IP "\-\-pgpcertfile \fIFILE\fR"
-PGP Public Key (certificate) file to use.
-.IP "\-\-x509keyfile \fIFILE\fR"
-X.509 key file to use.
-.IP "\-\-x509certfile \fIFILE\fR"
-X.509 Certificate file to use.
-.IP "\-\-srpusername \fINAME\fR"
-SRP username to use.
 .IP "\-\-srppasswd \fIPASSWD\fR"
 SRP password to use.
-.IP "\-l, \-\-list"
-Print a list of the supported algorithms and modes.
-.IP "\-h, \-\-help"
-Prints a short reminder of the command line options.
-.IP "\-v, \-\-version"
-Prints the program's version number.
-.IP "\-\-copyright"
-Prints the program's license.
+.IP "\-\-srpusername \fINAME\fR"
+SRP username to use.
+.IP "\-\-x509cafile \fIFILE\fR"
+Certificate file to use.
+.IP "\-\-x509certfile \fIFILE\fR"
+X.509 Certificate file to use.
+.IP "\-\-x509fmtder"
+Use DER format for certificates
+.IP "\-\-x509keyfile \fIFILE\fR"
+X.509 key file to use.
+.IP "\-\-xml"
+Print the certificate information in XML format.
+
 .SH "SEE ALSO"
 .BR gnutls\-cli\-debug (1),
 .BR gnutls\-serv (1)
diff --git a/doc/manpages/gnutls-serv.1 b/doc/manpages/gnutls-serv.1
index 8cc9108e71..b2cc143aa4 100644
--- a/doc/manpages/gnutls-serv.1
+++ b/doc/manpages/gnutls-serv.1
@@ -1,4 +1,4 @@
-.TH gnutls\-serv 1 "October 26th 2003"
+.TH gnutls\-serv 1 "December 1st 2003"
 .SH NAME
 gnutls\-serv \- GNU TLS test server
 .SH SYNOPSIS
@@ -6,58 +6,75 @@ gnutls\-serv [\fIoptions\fR]
 .SH DESCRIPTION
 Simple server program that listens to incoming TLS connections.
 .SH OPTIONS
-.IP "\-g, \-\-generate"
-Generate Diffie Hellman Parameters.
-.IP "\-p, \-\-port \fIinteger\fR"
-The port to connect to.
+.SS Program control options
+.IP "\-\-copyright"
+prints the program's license
+.IP "\-d, \-\-debug LEVEL"
+Specify the debug level. Default is 1.
+.IP "\-h, \-\-help"
+prints this help
+.IP "\-l, \-\-list"
+Print a list of the supported algorithms and modes.
 .IP "\-q, \-\-quiet"
 Suppress some messages.
+.IP "\-v, \-\-version"
+prints the program's version number
+
+.SS Server options
+.IP "\-p, \-\-port \fIinteger\fR"
+The port to listen on.
 .IP "\-\-nodb"
 Does not use the resume database.
 .IP "\-\-http"
 Act as an HTTP Server.
 .IP "\-\-echo"
 Act as an Echo Server.
-.IP "\-\-x509fmtder"
-Use DER format for certificates
-.IP "\-\-x509cafile \fIFILE\fR"
-Certificate file to use.
+
+.SS TLS/SSL control options
+.IP "\-\-ciphers \fIcipher1 cipher2...\fR"
+Ciphers to enable (use \fBgnutls\-cli \-\-list\fR to show the
+supported ciphers).
+.IP "\-\-comp \fIcomp1 comp2...\fR"
+Compression methods to enable (use \fBgnutls\-cli \-\-list\fR to show
+the supported compression methods).
+.IP "\-\-ctypes \fIcertType1 certType2...\fR"
+Certificate types to enable.
+.IP "\-g, \-\-generate"
+Generate Diffie Hellman Parameters.
+.IP "\-\-kx \fIkx1 kx2...\fR"
+Key exchange methods to enable (use \fBgnutls\-cli \-\-list\fR to show
+the supported key exchange methods).
+.IP "\-\-macs \fImac1 mac2...\fR"
+MACs (Message Authentication Codes) to enable (use \fBgnutls\-cli
+\-\-list\fR to show the supported MACs).
+.IP "\-p, \-\-port \fIinteger\fR"
+The port to connect to.
+.IP "\-\-protocols \fIprotocol1 protocol2...\fR"
+Protocols to enable (use \fBgnutls\-cli \-\-list\fR to show the
+supported protocols).
+
+.SS Certificate options
+.IP "\-\-pgpcertfile \fIFILE\fR"
+PGP Public Key (certificate) file to use.
+.IP "\-\-pgpkeyfile \fIFILE\fR"
+PGP Key file to use.
 .IP "\-\-pgpkeyring \fIFILE\fR"
 PGP Key ring file to use.
 .IP "\-\-pgptrustdb \fIFILE\fR"
 PGP trustdb file to use.
-.IP "\-\-pgpkeyfile \fIFILE\fR"
-PGP Key file to use.
-.IP "\-\-pgpcertfile \fIFILE\fR"
-PGP Public Key (certificate) file to use.
-.IP "\-\-x509keyfile \fIFILE\fR"
-X.509 key file to use.
-.IP "\-\-x509certfile \fIFILE\fR"
-X.509 Certificate file to use.
 .IP "\-\-srppasswd \fIFILE\fR"
 SRP password file to use.
 .IP "\-\-srppasswdconf \fIFILE\fR"
 SRP password configuration file to use.
-.IP "\-\-ciphers \fIcipher1 cipher2...\fR"
-Ciphers to enable.
-.IP "\-\-protocols \fIprotocol1 protocol2...\fR"
-Protocols to enable.
-.IP "\-\-comp \fIcomp1 comp2...\fR"
-Compression methods to enable.
-.IP "\-\-macs \fImac1 mac2...\fR"
-MACs to enable.
-.IP "\-\-kx \fIkx1 kx2...\fR"
-Key exchange methods to enable.
-.IP "\-\-ctypes \fIcertType1 certType2...\fR"
-Certificate types to enable.
-.IP "\-l, \-\-list"
-Print a list of the supported algorithms and modes.
-.IP "\-h, \-\-help"
-prints this help
-.IP "\-v, \-\-version"
-prints the program's version number
-.IP "\-\-copyright"
-prints the program's license
+.IP "\-\-x509cafile \fIFILE\fR"
+Certificate file to use.
+.IP "\-\-x509certfile \fIFILE\fR"
+X.509 Certificate file to use.
+.IP "\-\-x509fmtder"
+Use DER format for certificates
+.IP "\-\-x509keyfile \fIFILE\fR"
+X.509 key file to use.
+
 .SH "SEE ALSO"
 .BR gnutls\-cli (1),
 .BR gnutls\-cli\-debug (1)
diff --git a/doc/manpages/gnutls-srpcrypt.1 b/doc/manpages/gnutls-srpcrypt.1
index ab4a5b5c63..4fb47da56f 100644
--- a/doc/manpages/gnutls-srpcrypt.1
+++ b/doc/manpages/gnutls-srpcrypt.1
@@ -1,30 +1,64 @@
-.TH gnutls\-srpcrypt 1 "October 26th 2003"
+.TH gnutls\-srpcrypt 1 "December 1st 2003"
 .SH NAME
 gnutls\-srpcrypt \- Simple SRP password tool
 .SH SYNOPSIS
 gnutls\-srpcrypt [\fIoptions\fR]
 .SH DESCRIPTION
-SRP (Secure Remote Password) utility using GNU TLS.
+Very simple program that emulates the programs in the Stanford SRP
+(Secure Remote Password) libraries using GNU TLS.
+It is intended for use in places where you don't expect SRP
+authentication to be the used for system users.
 .SH OPTIONS
-.IP "\-u, \-\-username \fIusername\fR"
-Specify username.
-.IP "\-p, \-\-passwd \fIFILE\fR"
-Specify a password file.
+.IP "\-\-bits \fIBITS\fR"
+specify the number of bits for prime numbers (used only when the
+\fB\-\-create\-conf\fR option is used).
+.IP "\-\-create\-conf \fIFILE\fR"
+Generate a tpasswd.conf file.
+.IP "\-h, \-\-help"
+Prints a short reminder of the command line options.
 .IP "\-i, \-\-index \fIINDEX\fR"
 Specify the index of the parameters in tpasswd.conf to use.
+.IP "\-p, \-\-passwd \fIFILE\fR"
+Specify a password file.
+.IP "\-\-passwd\-conf \fIFILE\fR"
+Specify a password configuration file.
 .IP "\-s, \-\-salt \fISALT\fR"
 Specify salt/cost size for crypt algorithm.
+.IP "\-u, \-\-username \fIusername\fR"
+Specify username.
 .IP "\-\-verify"
 Just verify password.
-.IP "\-\-passwd\-conf \fIFILE\fR"
-Specify a password configuration file.
-.IP "\-\-create\-conf \fIFILE\fR"
-Generate a tpasswd.conf file.
-.IP "\-\-bits \fIBITS\fR"
-specify the number of bits for prime numbers (used only when the
-\fB\-\-create\-conf\fR option is used).
-.IP "\-h, \-\-help"
-Prints a short reminder of the command line options.
+.SH EXAMPLES
+To create tpasswd.conf which holds the g and n values for SRP protocol
+(generator and a large prime), run:
+
+.RS
+.nf
+$ gnutls\-srpcrypt \-\-create\-conf /etc/tpasswd.conf
+.fi
+.RE
+
+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.
+
+.RS
+.nf
+$ gnutls\-srpcrypt \-\-passwd /etc/tpasswd \\
+    \-\-passwd\-conf /etc/tpasswd.conf \-u test
+.fi
+.RE
+
+This command will check against a password. If the password matches
+the one in /etc/tpasswd you will get an ok.
+
+.RS
+.nf
+$ gnutls\-srpcrypt \-\-passwd /etc/tpasswd \\
+    \-\-passwd\-conf /etc/tpasswd.conf \-\-verify \-u test
+.fi
+.RE
+
 .SH AUTHOR
 .PP
 Nikos Mavroyanopoulos <nmav@gnutls.org> and others; see