Documentation updates. Separated big gnutls.texi to chapter to allow easier

maintainance.

17 files changed, 4005 insertions, 4282 deletions

diff --git a/NEWS b/NEWS
index 65b5832ee4..de08cd55fb 100644
--- a/NEWS
+++ b/NEWS
@@ -21,8 +21,12 @@ similar gnutls_certificate_set_server_retrieve_function() and
 gnutls_certificate_set_client_retrieve_function(). In addition it support
 PKCS #11 private keys.
 
+** libgnutls: Added  gnutls_pkcs11_copy_x509_crt(), gnutls_pkcs11_copy_x509_privkey(),
+and gnutls_pkcs11_delete_url() to allow copying and deleting data in tokens.
+
 ** certtool: Added new options: --pkcs11-list-tokens, --pkcs11-list-all
---pkcs11-list-all-certs, --pkcs11-list-trusted, --pkcs11-list-certs
+--pkcs11-list-all-certs, --pkcs11-list-trusted, --pkcs11-list-certs,
+--pkcs11-delete-url, --pkcs11-write
 
 ** gnutls-cli/gnutls-serv: --x509cafile, --x509certfile and --x509keyfile
 can now accept a PKCS #11 URL in addition to a file. This will allow for
@@ -45,7 +49,6 @@ gnutls_pkcs11_obj_init: ADDED
 gnutls_pkcs11_obj_import_url: ADDED
 gnutls_pkcs11_obj_export_url: ADDED
 gnutls_pkcs11_obj_deinit: ADDED
-gnutls_pkcs11_obj_list_deinit: ADDED
 gnutls_pkcs11_obj_export: ADDED
 gnutls_pkcs11_obj_list_import_url: ADDED
 gnutls_pkcs11_obj_export: ADDED
@@ -98,6 +101,9 @@ gnutls_pubkey_import_dsa_raw: ADDED
 gnutls_pubkey_import_rsa_raw: ADDED
 gnutls_x509_crt_set_pubkey: ADDED
 gnutls_x509_crq_set_pubkey: ADDED
+gnutls_pkcs11_copy_x509_crt: ADDED
+gnutls_pkcs11_copy_x509_privkey: ADDED
+gnutls_pkcs11_delete_url: ADDED
 
 
 * Version 2.9.10 (released 2010-04-22)
diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi
new file mode 100644
index 0000000000..39da7a5c9a
--- /dev/null
+++ b/doc/cha-auth.texi
@@ -0,0 +1,462 @@
+@node Authentication methods
+@chapter Authentication Methods
+
+The @acronym{TLS} protocol provides confidentiality and encryption,
+but also offers authentication, which is a prerequisite for a secure
+connection. The available authentication methods in @acronym{GnuTLS}
+are:
+
+@itemize
+
+@item Certificate authentication
+
+@item Anonymous authentication
+
+@item @acronym{SRP} authentication
+
+@item @acronym{PSK} authentication
+
+@end itemize
+
+@menu
+* Certificate authentication::
+* Anonymous authentication::
+* Authentication using SRP::
+* Authentication using PSK::
+* Authentication and credentials::
+* Parameters stored in credentials::
+@end menu
+
+@node Certificate authentication
+@section Certificate Authentication
+
+@subsection Authentication Using @acronym{X.509} Certificates
+@cindex @acronym{X.509} certificates
+
+@acronym{X.509} certificates contain the public parameters, of a
+public key algorithm, and an authority's signature, which proves the
+authenticity of the parameters.  @xref{The X.509 trust model}, for
+more information on @acronym{X.509} protocols.
+
+@subsection Authentication Using @acronym{OpenPGP} Keys
+@cindex @acronym{OpenPGP} Keys
+
+@acronym{OpenPGP} keys also contain public parameters of a public key
+algorithm, and signatures from several other parties. Depending on
+whether a signer is trusted the key is considered trusted or not.
+@acronym{GnuTLS}'s @acronym{OpenPGP} authentication implementation is
+based on the @xcite{TLSPGP} proposal.
+
+@xref{The OpenPGP trust model}, for more information about the
+@acronym{OpenPGP} trust model.  For a more detailed introduction to
+@acronym{OpenPGP} and @acronym{GnuPG} see @xcite{GPGH}.
+
+@subsection Using Certificate Authentication
+
+In @acronym{GnuTLS} both the @acronym{OpenPGP} and @acronym{X.509}
+certificates are part of the certificate authentication and thus are
+handled using a common API.
+
+When using certificates the server is required to have at least one
+certificate and private key pair. A client may or may not have such a
+pair. The certificate and key pair should be loaded, before any
+@acronym{TLS} session is initialized, in a certificate credentials
+structure. This should be done by using
+@ref{gnutls_certificate_set_x509_key_file} or
+@ref{gnutls_certificate_set_openpgp_key_file} depending on the
+certificate type.  In the @acronym{X.509} case, the functions will
+also accept and use a certificate list that leads to a trusted
+authority. The certificate list must be ordered in such way that every
+certificate certifies the one before it. The trusted authority's
+certificate need not to be included, since the peer should possess it
+already.
+
+As an alternative, a callback may be used so the server or the client
+specify the certificate and the key at the handshake time.  That
+callback can be set using the functions:
+
+@itemize
+
+@item @ref{gnutls_certificate_server_set_retrieve_function}
+
+@item @ref{gnutls_certificate_client_set_retrieve_function}
+
+@end itemize
+
+Clients and servers that will select certificates using callback
+functions should select a certificate according the peer's signature
+algorithm preferences. To get those preferences use
+@ref{gnutls_sign_algorithm_get_requested}.
+
+Certificate verification is possible by loading the trusted
+authorities into the credentials structure by using
+@ref{gnutls_certificate_set_x509_trust_file} or
+@ref{gnutls_certificate_set_openpgp_keyring_file} for openpgp
+keys. Note however that the peer's certificate is not automatically
+verified, you should call @ref{gnutls_certificate_verify_peers2},
+after a successful handshake, to verify the signatures of the
+certificate.  An alternative way, which reports a more detailed
+verification output, is to use @ref{gnutls_certificate_get_peers} to
+obtain the raw certificate of the peer and verify it using the
+functions discussed in @ref{The X.509 trust model}.
+
+In a handshake, the negotiated cipher suite depends on the
+certificate's parameters, so not all key exchange methods will be
+available with some certificates. @acronym{GnuTLS} will disable
+ciphersuites that are not compatible with the key, or the enabled
+authentication methods.  For example keys marked as sign-only, will
+not be able to access the plain RSA ciphersuites, but only the
+@code{DHE_RSA} ones. It is recommended not to use RSA keys for both
+signing and encryption. If possible use the same key for the
+@code{DHE_RSA} and @code{RSA_EXPORT} ciphersuites, which use signing,
+and a different key for the plain RSA ciphersuites, which use
+encryption.  All the key exchange methods shown below are available in
+certificate authentication.
+
+Note that the DHE key exchange methods are generally
+slower@footnote{It really depends on the group used.  Primes with
+lesser bits are always faster, but also easier to break.  Values less
+than 768 should not be used today} than plain RSA and require Diffie
+Hellman parameters to be generated and associated with a credentials
+structure, by the server.  The @code{RSA-EXPORT} method also requires
+512 bit RSA parameters, that should also be generated and associated
+with the credentials structure.  See the functions:
+
+@itemize
+
+@item @ref{gnutls_dh_params_generate2}
+
+@item @ref{gnutls_certificate_set_dh_params}
+
+@item @ref{gnutls_rsa_params_generate2}
+
+@item @ref{gnutls_certificate_set_rsa_export_params}
+
+@end itemize
+
+Sometimes in order to avoid bottlenecks in programs it is usefull to
+store and read parameters from formats that can be generated by
+external programs such as @code{certtool}. This is possible with
+@acronym{GnuTLS} by using the following functions:
+
+@itemize
+
+@item @ref{gnutls_dh_params_import_pkcs3}
+
+@item @ref{gnutls_rsa_params_import_pkcs1}
+
+@item @ref{gnutls_dh_params_export_pkcs3}
+
+@item @ref{gnutls_rsa_params_export_pkcs1}
+
+@end itemize
+
+Key exchange algorithms for @acronym{OpenPGP} and @acronym{X.509}
+certificates:
+
+@table @code
+
+@item RSA:
+The RSA algorithm is used to encrypt a key and send it to the peer.
+The certificate must allow the key to be used for encryption.
+
+@item RSA_EXPORT:
+The RSA algorithm is used to encrypt a key and send it to the peer.
+In the EXPORT algorithm, the server signs temporary RSA parameters of
+512 bits --- which are considered weak --- and sends them to the
+client.
+
+@item DHE_RSA:
+The RSA algorithm is used to sign Ephemeral Diffie-Hellman parameters
+which are sent to the peer. The key in the certificate must allow the
+key to be used for signing. Note that key exchange algorithms which
+use Ephemeral Diffie-Hellman parameters, offer perfect forward
+secrecy. That means that even if the private key used for signing is
+compromised, it cannot be used to reveal past session data.
+
+@item DHE_DSS:
+The DSS algorithm is used to sign Ephemeral Diffie-Hellman parameters
+which are sent to the peer. The certificate must contain DSA
+parameters to use this key exchange algorithm. DSS stands for Digital
+Signature Standard.
+
+@end table
+
+@node Anonymous authentication
+@section Anonymous Authentication
+@cindex Anonymous authentication
+
+The anonymous key exchange performs encryption but there is no
+indication of the identity of the peer.  This kind of authentication
+is vulnerable to a man in the middle attack, but this protocol can be
+used even if there is no prior communication and trusted parties with
+the peer, or when full anonymity is required.  Unless really required,
+do not use anonymous authentication.  Available key exchange methods
+are shown below.
+
+Note that the key exchange methods for anonymous authentication
+require Diffie-Hellman parameters to be generated by the server and
+associated with an anonymous credentials structure.
+
+Supported anonymous key exchange algorithms:
+
+@table @code
+
+@item ANON_DH:
+This algorithm exchanges Diffie-Hellman parameters.
+
+@end table
+
+@node Authentication using SRP
+@section Authentication using @acronym{SRP}
+@cindex @acronym{SRP} authentication
+
+Authentication via the Secure Remote Password protocol,
+@acronym{SRP}@footnote{@acronym{SRP} is described in @xcite{RFC2945}},
+is supported.  The @acronym{SRP} key exchange is an extension to the
+@acronym{TLS} protocol, and it is a password based authentication
+(unlike @acronym{X.509} or @acronym{OpenPGP} that use certificates).
+The two peers can be identified using a single password, or there can
+be combinations where the client is authenticated using @acronym{SRP}
+and the server using a certificate.
+
+The advantage of @acronym{SRP} authentication, over other proposed
+secure password authentication schemes, is that @acronym{SRP} does not
+require the server to hold the user's password.  This kind of
+protection is similar to the one used traditionally in the @emph{UNIX}
+@file{/etc/passwd} file, where the contents of this file did not cause
+harm to the system security if they were revealed.  The @acronym{SRP}
+needs instead of the plain password something called a verifier, which
+is calculated using the user's password, and if stolen cannot be used
+to impersonate the user. Check @xcite{TOMSRP} for a detailed
+description of the @acronym{SRP} protocol and the Stanford
+@acronym{SRP} libraries, which includes a PAM module that synchronizes
+the system's users passwords with the @acronym{SRP} password
+files. That way @acronym{SRP} authentication could be used for all the
+system's users.
+
+The implementation in @acronym{GnuTLS} is based on paper
+@xcite{TLSSRP}.  The supported @acronym{SRP} key exchange methods are:
+
+@table @code
+
+@item SRP:
+Authentication using the @acronym{SRP} protocol.
+
+@item SRP_DSS:
+Client authentication using the @acronym{SRP} protocol. Server is
+authenticated using a certificate with DSA parameters.
+
+@item SRP_RSA:
+Client authentication using the @acronym{SRP} protocol. Server is
+authenticated using a certificate with RSA parameters.
+
+@end table
+
+If clients supporting @acronym{SRP} know the username and password
+before the connection, should initialize the client credentials and
+call the function @ref{gnutls_srp_set_client_credentials}.
+Alternatively they could specify a callback function by using the
+function @ref{gnutls_srp_set_client_credentials_function}.  This has
+the advantage that allows probing the server for @acronym{SRP}
+support.  In that case the callback function will be called twice per
+handshake.  The first time is before the ciphersuite is negotiated,
+and if the callback returns a negative error code, the callback will
+be called again if @acronym{SRP} has been negotiated.  This uses a
+special @acronym{TLS}-@acronym{SRP} handshake idiom in order to avoid,
+in interactive applications, to ask the user for @acronym{SRP}
+password and username if the server does not negotiate an
+@acronym{SRP} ciphersuite.
+
+In server side the default behaviour of @acronym{GnuTLS} is to read
+the usernames and @acronym{SRP} verifiers from password files. These
+password files are the ones used by the @emph{Stanford srp libraries}
+and can be specified using the
+@ref{gnutls_srp_set_server_credentials_file}.  If a different
+password file format is to be used, then the function
+@ref{gnutls_srp_set_server_credentials_function}, should be called,
+in order to set an appropriate callback.
+
+Some helper functions such as
+
+@itemize
+
+@item @ref{gnutls_srp_verifier}
+
+@item @ref{gnutls_srp_base64_encode}
+
+@item @ref{gnutls_srp_base64_decode}
+
+@end itemize
+
+are included in @acronym{GnuTLS}, and can be 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.  @xref{srptool}, for more information.
+
+
+@node Authentication using PSK
+@section Authentication using @acronym{PSK}
+@cindex @acronym{PSK} authentication
+
+Authentication using Pre-shared keys is a method to authenticate using
+usernames and binary keys. This protocol avoids making use of public
+key infrastructure and expensive calculations, thus it is suitable for
+constraint clients.
+
+The implementation in @acronym{GnuTLS} is based on paper
+@xcite{TLSPSK}.  The supported @acronym{PSK} key exchange methods are:
+
+@table @code
+
+@item PSK:
+Authentication using the @acronym{PSK} protocol.
+
+@item DHE-PSK:
+Authentication using the @acronym{PSK} protocol and Diffie-Hellman key
+exchange.  This method offers perfect forward secrecy.
+
+@end table
+
+Clients supporting @acronym{PSK} should supply the username and key
+before the connection to the client credentials by calling the
+function @ref{gnutls_psk_set_client_credentials}.  Alternatively they
+could specify a callback function by using the function
+@ref{gnutls_psk_set_client_credentials_function}.  This has the
+advantage that the callback will be called only if @acronym{PSK} has
+been negotiated.
+
+In server side the default behaviour of @acronym{GnuTLS} is to read
+the usernames and @acronym{PSK} keys from a password file. The
+password file should contain usernames and keys in hexadecimal
+format. The name of the password file can be stored to the credentials
+structure by calling @ref{gnutls_psk_set_server_credentials_file}.  If
+a different password file format is to be used, then the function
+@ref{gnutls_psk_set_server_credentials_function}, should be used
+instead.
+
+The server can help the client chose a suitable username and password,
+by sending a hint.  In the server, specify the hint by calling
+@ref{gnutls_psk_set_server_credentials_hint}.  The client can retrieve
+the hint, for example in the callback function, using
+@ref{gnutls_psk_client_get_hint}.
+
+There is no standard mechanism to derive a PSK key from a password
+specified by the TLS PSK document.  However, GnuTLS provides
+@ref{gnutls_psk_netconf_derive_key} which follows the algorithm
+specified in @file{draft-ietf-netconf-tls-02.txt}.
+
+Some helper functions such as:
+
+@itemize
+
+@item @ref{gnutls_hex_encode}
+
+@item @ref{gnutls_hex_decode}
+
+@end itemize
+
+are included in @acronym{GnuTLS}, and may be used to generate and
+maintain @acronym{PSK} keys.
+
+
+@node Authentication and credentials
+@section Authentication and Credentials
+
+In @acronym{GnuTLS} every key exchange method is associated with a
+credentials type. So in order to enable to enable a specific method,
+the corresponding credentials type should be initialized and set using
+@ref{gnutls_credentials_set}.  A mapping is shown below.
+
+Key exchange algorithms and the corresponding credential types:
+
+@multitable @columnfractions .3 .3 .3
+
+@headitem Key exchange @tab Client credentials @tab Server credentials
+
+@item @code{KX_RSA}
+@item @code{KX_DHE_RSA}
+@item @code{KX_DHE_DSS}
+@item @code{KX_RSA_EXPORT}
+@tab @code{CRD_CERTIFICATE}
+@tab @code{CRD_CERTIFICATE}
+
+@item @code{KX_SRP_RSA}
+@tab @code{CRD_SRP}
+@tab @code{CRD_SRP}
+@item @code{KX_SRP_DSS}
+@tab
+@tab @code{CRD_CERTIFICATE}
+
+@item @code{KX_SRP}
+@tab @code{CRD_SRP}
+@tab @code{CRD_SRP}
+
+@item @code{KX_ANON_DH}
+@tab @code{CRD_ANON}
+@tab @code{CRD_ANON}
+
+@item @code{KX_PSK}
+@tab @code{CRD_PSK}
+@tab @code{CRD_PSK}
+
+@end multitable
+
+@node Parameters stored in credentials
+@section Parameters Stored in Credentials
+
+Several parameters such as the ones used for Diffie-Hellman
+authentication are stored within the credentials structures, so all
+sessions can access them. Those parameters are stored in structures
+such as @code{gnutls_dh_params_t} and @code{gnutls_rsa_params_t}, and
+functions like @ref{gnutls_certificate_set_dh_params} and
+@ref{gnutls_certificate_set_rsa_export_params} can be used to
+associate those parameters with the given credentials structure.
+
+Since those parameters need to be renewed from time to time and a
+global structure such as the credentials, may not be easy to modify
+since it is accessible by all sessions, an alternative interface is
+available using a callback function.  This can be set using the
+@ref{gnutls_certificate_set_params_function}.  An example is shown
+below.
+
+@example
+#include <gnutls.h>
+
+gnutls_rsa_params_t rsa_params;
+gnutls_dh_params_t dh_params;
+
+/* This function will be called once a session requests DH
+ * or RSA parameters. The parameters returned (if any) will
+ * be used for the first handshake only.
+ */
+static int get_params( gnutls_session_t session,
+        gnutls_params_type_t type,
+        gnutls_params_st *st)
+@{
+   if (type == GNUTLS_PARAMS_RSA_EXPORT)
+      st->params.rsa_export = rsa_params;
+   else if (type == GNUTLS_PARAMS_DH)
+      st->params.dh = dh_params;
+   else return -1;
+
+   st->type = type;
+   /* do not deinitialize those parameters.
+    */
+   st->deinit = 0;
+
+   return 0;
+@}
+
+int main()
+@{
+   gnutls_certificate_credentials_t cert_cred;
+
+   initialize_params();
+
+   /* ...
+    */
+
+   gnutls_certificate_set_params_function( cert_cred, get_params);
+@}
+@end example
diff --git a/doc/cha-bib.texi b/doc/cha-bib.texi
new file mode 100644
index 0000000000..d52744e867
--- /dev/null
+++ b/doc/cha-bib.texi
@@ -0,0 +1,143 @@
+@node Bibliography
+@unnumbered Bibliography
+
+@table @asis
+
+@item @anchor{CBCATT}[CBCATT]
+Bodo Moeller, "Security of CBC Ciphersuites in SSL/TLS: Problems and
+Countermeasures", 2002, available from
+@url{http://www.openssl.org/~bodo/tls-cbc.txt}.
+
+@item @anchor{GPGH}[GPGH]
+Mike Ashley, "The GNU Privacy Handbook", 2002, available from
+@url{http://www.gnupg.org/gph/en/manual.pdf}.
+
+@item @anchor{GUTPKI}[GUTPKI]
+Peter Gutmann, "Everything you never wanted to know about PKI but were
+forced to find out", Available from
+@url{http://www.cs.auckland.ac.nz/~pgut001/}.
+
+@item @anchor{NISTSP80057}[NISTSP80057]
+NIST Special Publication 800-57, "Recommendation for Key Management -
+Part 1: General (Revised)", March 2007, available from
+@url{http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf}.
+
+@item @anchor{RFC2246}[RFC2246]
+Tim Dierks and Christopher Allen, "The TLS Protocol Version 1.0",
+January 1999, Available from
+@url{http://www.ietf.org/rfc/rfc2246.txt}.
+
+@item @anchor{RFC4346}[RFC4346]
+Tim Dierks and Eric Rescorla, "The TLS Protocol Version 1.1", Match
+2006, Available from @url{http://www.ietf.org/rfc/rfc4346.txt}.
+
+@item @anchor{RFC2440}[RFC2440]
+Jon Callas, Lutz Donnerhacke, Hal Finney and Rodney Thayer, "OpenPGP
+Message Format", November 1998, Available from
+@url{http://www.ietf.org/rfc/rfc2440.txt}.
+
+@item @anchor{RFC4880}[RFC4880]
+Jon Callas, Lutz Donnerhacke, Hal Finney, David Shaw and Rodney
+Thayer, "OpenPGP Message Format", November 2007, Available from
+@url{http://www.ietf.org/rfc/rfc4880.txt}.
+
+@item @anchor{RFC4211}[RFC4211]
+J. Schaad, "Internet X.509 Public Key Infrastructure Certificate
+Request Message Format (CRMF)", September 2005, Available from
+@url{http://www.ietf.org/rfc/rfc4211.txt}.
+
+@item @anchor{RFC2817}[RFC2817]
+Rohit Khare and Scott Lawrence, "Upgrading to TLS Within HTTP/1.1",
+May 2000, Available from @url{http://www.ietf.org/rfc/rfc2817.txt}
+
+@item @anchor{RFC2818}[RFC2818]
+Eric Rescorla, "HTTP Over TLS", May 2000, Available from
+@url{http://www.ietf/rfc/rfc2818.txt}.
+
+@item @anchor{RFC2945}[RFC2945]
+Tom Wu, "The SRP Authentication and Key Exchange System", September
+2000, Available from @url{http://www.ietf.org/rfc/rfc2945.txt}.
+
+@item @anchor{RFC2986}[RFC2986]
+Magnus Nystrom and Burt Kaliski, "PKCS 10 v1.7: Certification Request
+Syntax Specification", November 2000, Available from
+@url{http://www.ietf.org/rfc/rfc2986.txt}.
+
+@item @anchor{PKIX}[PKIX]
+D. Cooper, S. Santesson, S. Farrel, S. Boeyen, R. Housley, W. Polk,
+"Internet X.509 Public Key Infrastructure Certificate and Certificate
+Revocation List (CRL) Profile", May 2008, available from
+@url{http://www.ietf.org/rfc/rfc5280.txt}.
+
+@item @anchor{RFC3749}[RFC3749]
+Scott Hollenbeck, "Transport Layer Security Protocol Compression
+Methods", May 2004, available from
+@url{http://www.ietf.org/rfc/rfc3749.txt}.
+
+@item @anchor{RFC3820}[RFC3820]
+Steven Tuecke, Von Welch, Doug Engert, Laura Pearlman, and Mary
+Thompson, "Internet X.509 Public Key Infrastructure (PKI) Proxy
+Certificate Profile", June 2004, available from
+@url{http://www.ietf.org/rfc/rfc3820}.
+
+@item @anchor{RFC5746}[RFC5746]
+E. Rescorla, M. Ray, S. Dispensa, and N. Oskov, "Transport Layer
+Security (TLS) Renegotiation Indication Extension", February 2010,
+available from @url{http://www.ietf.org/rfc/rfc5746}.
+
+@item @anchor{TLSTKT}[TLSTKT]
+Joseph Salowey, Hao Zhou, Pasi Eronen, Hannes Tschofenig, "Transport
+Layer Security (TLS) Session Resumption without Server-Side State",
+January 2008, available from @url{http://www.ietf.org/rfc/rfc5077}.
+
+@item @anchor{PKCS12}[PKCS12]
+RSA Laboratories, "PKCS 12 v1.0: Personal Information Exchange
+Syntax", June 1999, Available from @url{http://www.rsa.com}.
+
+@item @anchor{RESCORLA}[RESCORLA]
+Eric Rescorla, "SSL and TLS: Designing and Building Secure Systems",
+2001
+
+@item @anchor{SELKEY}[SELKEY]
+Arjen Lenstra and Eric Verheul, "Selecting Cryptographic Key Sizes",
+2003, available from @url{http://www.win.tue.nl/~klenstra/key.pdf}.
+
+@item @anchor{SSL3}[SSL3]
+Alan Freier, Philip Karlton and Paul Kocher, "The SSL Protocol Version
+3.0", November 1996, Available from
+@url{http://wp.netscape.com/eng/ssl3/draft302.txt}.
+
+@item @anchor{STEVENS}[STEVENS]
+Richard Stevens, "UNIX Network Programming, Volume 1", Prentice Hall
+PTR, January 1998
+
+@item @anchor{TLSEXT}[TLSEXT]
+Simon Blake-Wilson, Magnus Nystrom, David Hopwood, Jan Mikkelsen and
+Tim Wright, "Transport Layer Security (TLS) Extensions", June 2003,
+Available from @url{http://www.ietf.org/rfc/rfc3546.txt}.
+
+@item @anchor{TLSPGP}[TLSPGP]
+Nikos Mavrogiannopoulos, "Using OpenPGP keys for TLS authentication",
+April 2004, November 2007. Available from
+@url{http://www.ietf.org/rfc/rfc5081.txt}.
+
+@item @anchor{TLSSRP}[TLSSRP]
+David Taylor, Trevor Perrin, Tom Wu and Nikos Mavrogiannopoulos,
+"Using SRP for TLS Authentication", November 2007. Available from
+@url{http://www.ietf.org/rfc/rfc5054.txt}.
+
+@item @anchor{TLSPSK}[TLSPSK]
+Pasi Eronen and Hannes Tschofenig, "Pre-shared key Ciphersuites for
+TLS", December 2005, Available from
+@url{http://www.ietf.org/rfc/rfc4279.txt}.
+
+@item @anchor{TOMSRP}[TOMSRP]
+Tom Wu, "The Stanford SRP Authentication Project", Available at
+@url{http://srp.stanford.edu/}.
+
+@item @anchor{WEGER}[WEGER]
+Arjen Lenstra and Xiaoyun Wang and Benne de Weger, "Colliding X.509
+Certificates", Cryptology ePrint Archive, Report 2005/067, Available
+at @url{http://eprint.iacr.org/}.
+
+@end table
diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
new file mode 100644
index 0000000000..7b76857eff
--- /dev/null
+++ b/doc/cha-cert-auth.texi
@@ -0,0 +1,626 @@
+@node More on certificate authentication
+@chapter More on Certificate Authentication
+@anchor{Certificate Authentication}
+@cindex Certificate authentication
+
+@menu
+* The X.509 trust model::
+* The OpenPGP trust model::
+* Digital signatures::
+* PKCS #11 tokens::
+@end menu
+
+@node The X.509 trust model
+@section The @acronym{X.509} Trust Model
+@cindex @acronym{X.509} certificates
+
+The @acronym{X.509} protocols rely on a hierarchical trust model. In
+this trust model Certification Authorities (CAs) are used to certify
+entities.  Usually more than one certification authorities exist, and
+certification authorities may certify other authorities to issue
+certificates as well, following a hierarchical model.
+
+@image{gnutls-x509,7cm,9.5cm}
+
+One needs to trust one or more CAs for his secure communications. In
+that case only the certificates issued by the trusted authorities are
+acceptable.  See the figure above for a typical example.  The API for
+handling @acronym{X.509} certificates is described at section
+@ref{sec:x509api}.  Some examples are listed below.
+
+@menu
+* X.509 certificates::
+* Verifying X.509 certificate paths::
+* PKCS #10 certificate requests::
+* PKCS #12 structures::
+@end menu
+
+@node X.509 certificates
+@subsection @acronym{X.509} Certificates
+
+An @acronym{X.509} certificate usually contains information about the
+certificate holder, the signer, a unique serial number, expiration
+dates and some other fields @xcite{PKIX} as shown in the table below.
+
+@table @code
+
+@item version:
+The field that indicates the version of the certificate.
+
+@item serialNumber:
+This field holds a unique serial number per certificate.
+
+@item issuer:
+Holds the issuer's distinguished name.
+
+@item validity:
+The activation and expiration dates.
+
+@item subject:
+The subject's distinguished name of the certificate.
+
+@item extensions:
+The extensions are fields only present in version 3 certificates.
+
+@end table
+
+The certificate's @emph{subject or issuer name} is not just a single
+string.  It is a Distinguished name and in the @acronym{ASN.1}
+notation is a sequence of several object IDs with their corresponding
+values. Some of available OIDs to be used in an @acronym{X.509}
+distinguished name are defined in @file{gnutls/x509.h}.
+
+The @emph{Version} field in a certificate has values either 1 or 3 for
+version 3 certificates.  Version 1 certificates do not support the
+extensions field so it is not possible to distinguish a CA from a
+person, thus their usage should be avoided.
+
+The @emph{validity} dates are there to indicate the date that the
+specific certificate was activated and the date the certificate's key
+would be considered invalid.
+
+Certificate @emph{extensions} are there to include information about
+the certificate's subject that did not fit in the typical certificate
+fields. Those may be e-mail addresses, flags that indicate whether the
+belongs to a CA etc.  All the supported @acronym{X.509} version 3
+extensions are shown in the table below.
+
+@table @code
+
+@item subject key id (2.5.29.14):
+An identifier of the key of the subject.
+
+@item authority key id (2.5.29.35):
+An identifier of the authority's key used to sign the certificate.
+
+@item subject alternative name (2.5.29.17):
+Alternative names to subject's distinguished name.
+
+@item key usage (2.5.29.15):
+Constraints the key's usage of the certificate.
+
+@item extended key usage (2.5.29.37):
+Constraints the purpose of the certificate.
+
+@item basic constraints (2.5.29.19):
+Indicates whether this is a CA certificate or not, and specify the
+maximum path lengths of certificate chains.
+
+@item CRL distribution points (2.5.29.31):
+This extension is set by the CA, in order to inform about the issued
+CRLs.
+
+@item Proxy Certification Information (1.3.6.1.5.5.7.1.14):
+Proxy Certificates includes this extension that contains the OID of
+the proxy policy language used, and can specify limits on the maximum
+lengths of proxy chains.  Proxy Certificates are specified in
+@xcite{RFC3820}.
+
+@end table
+
+In @acronym{GnuTLS} the @acronym{X.509} certificate structures are
+handled using the @code{gnutls_x509_crt_t} type and the corresponding
+private keys with the @code{gnutls_x509_privkey_t} type.  All the
+available functions for @acronym{X.509} certificate handling have
+their prototypes in @file{gnutls/x509.h}. An example program to
+demonstrate the @acronym{X.509} parsing capabilities can be found at
+section @ref{ex:x509-info}.
+
+@node Verifying X.509 certificate paths
+@subsection Verifying @acronym{X.509} Certificate Paths
+@cindex Verifying certificate paths
+
+Verifying certificate paths is important in @acronym{X.509}
+authentication. For this purpose the function
+@ref{gnutls_x509_crt_verify} is provided. The output of this function
+is the bitwise OR of the elements of the
+@code{gnutls_certificate_status_t} enumeration.  A detailed
+description of these elements can be found in figure below.  The
+function @ref{gnutls_certificate_verify_peers2} is equivalent to the
+previous one, and will verify the peer's certificate in a TLS session.
+
+@table @code
+
+@item GNUTLS_CERT_INVALID:
+The certificate is not signed by one of the known authorities, or
+the signature is invalid.
+
+@item GNUTLS_CERT_REVOKED:
+The certificate has been revoked by its CA.
+
+@item GNUTLS_CERT_SIGNER_NOT_FOUND:
+The certificate's issuer is not known. This is the case when the
+issuer is not in the trusted certificates list.
+
+@item GNUTLS_CERT_SIGNER_NOT_CA:
+The certificate's signer was not a CA. This may happen if
+this was a version 1 certificate, which is common with some CAs, or
+a version 3 certificate without the basic constrains extension.
+
+@anchor{GNUTLS_CERT_INSECURE_ALGORITHM}
+@item GNUTLS_CERT_INSECURE_ALGORITHM:
+The certificate was signed using an insecure algorithm such as MD2 or
+MD5.  These algorithms have been broken and should not be trusted.
+
+@end table
+
+There is also to possibility to pass some input to the verification
+functions in the form of flags. For @ref{gnutls_x509_crt_verify} the
+flags are passed straightforward, but
+@ref{gnutls_certificate_verify_peers2} depends on the flags set by
+calling @ref{gnutls_certificate_set_verify_flags}.  All the available
+flags are part of the enumeration
+@ref{gnutls_certificate_verify_flags} and are explained in the table
+below.
+
+@anchor{gnutls_certificate_verify_flags}
+@tindex gnutls_certificate_verify_flags
+@table @code
+@item GNUTLS_VERIFY_DISABLE_CA_SIGN:
+If set a signer does not have to be a certificate authority. This
+flag should normaly be disabled, unless you know what this means.
+
+@item GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT:
+Allow only trusted CA certificates that have version 1.  This is
+safer than GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT, and should be
+used instead. That way only signers in your trusted list will be
+allowed to have certificates of version 1.
+
+@item GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT:
+Allow CA certificates that have version 1 (both root and
+intermediate). This is dangerous since those haven't the
+basicConstraints extension. Must be used in combination with
+GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT.
+
+@item GNUTLS_VERIFY_DO_NOT_ALLOW_SAME:
+If a certificate is not signed by anyone trusted but exists in
+the trusted CA list do not treat it as trusted.
+
+@item GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2:
+Allow certificates to be signed using the old MD2 algorithm.
+
+@item GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5:
+Allow certificates to be signed using the broken MD5 algorithm.
+@end table
+
+Although the verification of a certificate path indicates that the
+certificate is signed by trusted authority, does not reveal anything
+about the peer's identity. It is required to verify if the
+certificate's owner is the one you expect. For more information
+consult @xcite{RFC2818} and section @ref{ex:verify} for an example.
+
+@node PKCS #10 certificate requests
+@subsection @acronym{PKCS} #10 Certificate Requests
+@cindex Certificate requests
+@cindex @acronym{PKCS} #10
+
+A certificate request is a structure, which contain information about
+an applicant of a certificate service.  It usually contains a private
+key, a distinguished name and secondary data such as a challenge
+password. @acronym{GnuTLS} supports the requests defined in
+@acronym{PKCS} #10 @xcite{RFC2986}. Other certificate request's format
+such as PKIX's @xcite{RFC4211} are not currently supported.
+
+In @acronym{GnuTLS} the @acronym{PKCS} #10 structures are handled
+using the @code{gnutls_x509_crq_t} type.  An example of a certificate
+request generation can be found at section @ref{ex:crq}.
+
+@node PKCS #12 structures
+@subsection @acronym{PKCS} #12 Structures
+@cindex @acronym{PKCS} #12
+
+A @acronym{PKCS} #12 structure @xcite{PKCS12} usually contains a user's
+private keys and certificates. It is commonly used in browsers to
+export and import the user's identities.
+
+In @acronym{GnuTLS} the @acronym{PKCS} #12 structures are handled
+using the @code{gnutls_pkcs12_t} type. This is an abstract type that
+may hold several @code{gnutls_pkcs12_bag_t} types.  The Bag types are
+the holders of the actual data, which may be certificates, private
+keys or encrypted data.  An Bag of type encrypted should be decrypted
+in order for its data to be accessed.
+
+An example of a @acronym{PKCS} #12 structure generation can be found
+at section @ref{ex:pkcs12}.
+
+@node The OpenPGP trust model
+@section The @acronym{OpenPGP} Trust Model
+@cindex @acronym{OpenPGP} Keys
+
+The @acronym{OpenPGP} key authentication relies on a distributed trust
+model, called the ``web of trust''. The ``web of trust'' uses a
+decentralized system of trusted introducers, which are the same as a
+CA. @acronym{OpenPGP} allows anyone to sign anyone's else public
+key. When Alice signs Bob's key, she is introducing Bob's key to
+anyone who trusts Alice. If someone trusts Alice to introduce keys,
+then Alice is a trusted introducer in the mind of that observer.
+
+@image{gnutls-pgp,11cm,9cm}
+
+For example: If David trusts Alice to be an introducer, and Alice
+signed Bob's key, Dave also trusts Bob's key to be the real one.
+
+There are some key points that are important in that model. In the
+example Alice has to sign Bob's key, only if she is sure that the key
+belongs to Bob. Otherwise she may also make Dave falsely believe that
+this is Bob's key. Dave has also the responsibility to know who to
+trust.  This model is similar to real life relations.
+
+Just see how Charlie behaves in the previous example. Although he has
+signed Bob's key - because he knows, somehow, that it belongs to Bob -
+he does not trust Bob to be an introducer. Charlie decided to trust
+only Kevin, for some reason. A reason could be that Bob is lazy
+enough, and signs other people's keys without being sure that they
+belong to the actual owner.
+
+@subsection @acronym{OpenPGP} Keys
+
+In @acronym{GnuTLS} the @acronym{OpenPGP} key structures
+@xcite{RFC2440} are handled using the @code{gnutls_openpgp_crt_t} type
+and the corresponding private keys with the
+@code{gnutls_openpgp_privkey_t} type. All the prototypes for the key
+handling functions can be found at @file{gnutls/openpgp.h}.
+
+@subsection Verifying an @acronym{OpenPGP} Key
+
+The verification functions of @acronym{OpenPGP} keys, included in
+@acronym{GnuTLS}, are simple ones, and do not use the features of the
+``web of trust''.  For that reason, if the verification needs are
+complex, the assistance of external tools like @acronym{GnuPG} and
+GPGME (@url{http://www.gnupg.org/related_software/gpgme/}) is
+recommended.
+
+There is one verification function in @acronym{GnuTLS}, the
+@ref{gnutls_openpgp_crt_verify_ring}.  This checks an
+@acronym{OpenPGP} key against a given set of public keys (keyring) and
+returns the key status. The key verification status is the same as in
+@acronym{X.509} certificates, although the meaning and interpretation
+are different. For example an @acronym{OpenPGP} key may be valid, if
+the self signature is ok, even if no signers were found.  The meaning
+of verification status is shown in the figure below.
+
+@table @code
+
+@item CERT_INVALID:
+A signature on the key is invalid. That means that the key was
+modified by somebody, or corrupted during transport.
+
+@item CERT_REVOKED:
+The key has been revoked by its owner.
+
+@item CERT_SIGNER_NOT_FOUND:
+The key was not signed by a known signer.
+
+@item GNUTLS_CERT_INSECURE_ALGORITHM:
+The certificate was signed using an insecure algorithm such as MD2 or
+MD5.  These algorithms have been broken and should not be trusted.
+
+@end table
+
+@node Digital signatures
+@section Digital Signatures
+@cindex Digital signatures
+
+In this section we will provide some information about digital
+signatures, how they work, and give the rationale for disabling some
+of the algorithms used.
+
+Digital signatures work by using somebody's secret key to sign some
+arbitrary data.  Then anybody else could use the public key of that
+person to verify the signature.  Since the data may be arbitrary it is
+not suitable input to a cryptographic digital signature algorithm. For
+this reason and also for performance cryptographic hash algorithms are
+used to preprocess the input to the signature algorithm. This works as
+long as it is difficult enough to generate two different messages with
+the same hash algorithm output. In that case the same signature could
+be used as a proof for both messages. Nobody wants to sign an innocent
+message of donating 1 @euro{} to Greenpeace and find out that he
+donated 1.000.000 @euro{} to Bad Inc.
+
+For a hash algorithm to be called cryptographic the following three
+requirements must hold:
+
+@enumerate
+@item Preimage resistance.
+That means the algorithm must be one way and given the output of the
+hash function @math{H(x)}, it is impossible to calculate @math{x}.
+
+@item 2nd preimage resistance.
+That means that given a pair @math{x,y} with @math{y=H(x)} it is
+impossible to calculate an @math{x'} such that @math{y=H(x')}.
+
+@item Collision resistance.
+That means that it is impossible to calculate random @math{x} and
+@math{x'} such @math{H(x')=H(x)}.
+@end enumerate
+
+The last two requirements in the list are the most important in
+digital signatures. These protect against somebody who would like to
+generate two messages with the same hash output. When an algorithm is
+considered broken usually it means that the Collision resistance of
+the algorithm is less than brute force. Using the birthday paradox the
+brute force attack takes
+@iftex
+@math{2^{(\rm{hash\ size}) / 2}}
+@end iftex
+@ifnottex
+@math{2^{((hash size) / 2)}}
+@end ifnottex
+operations. Today colliding certificates using the MD5 hash algorithm
+have been generated as shown in @xcite{WEGER}.
+
+There has been cryptographic results for the SHA-1 hash algorithms as
+well, although they are not yet critical.  Before 2004, MD5 had a
+presumed collision strength of @math{2^{64}}, but it has been showed
+to have a collision strength well under @math{2^{50}}.  As of November
+2005, it is believed that SHA-1's collision strength is around
+@math{2^{63}}.  We consider this sufficiently hard so that we still
+support SHA-1.  We anticipate that SHA-256/386/512 will be used in
+publicly-distributed certificates in the future.  When @math{2^{63}}
+can be considered too weak compared to the computer power available
+sometime in the future, SHA-1 will be disabled as well.  The collision
+attacks on SHA-1 may also get better, given the new interest in tools
+for creating them.
+
+@subsection Trading Security for Interoperability
+
+If you connect to a server and use GnuTLS' functions to verify the
+certificate chain, and get a @ref{GNUTLS_CERT_INSECURE_ALGORITHM}
+validation error (@pxref{Verifying X.509 certificate paths}), it means
+that somewhere in the certificate chain there is a certificate signed
+using @code{RSA-MD2} or @code{RSA-MD5}.  These two digital signature
+algorithms are considered broken, so GnuTLS fail when attempting to
+verify the certificate.  In some situations, it may be useful to be
+able to verify the certificate chain anyway, assuming an attacker did
+not utilize the fact that these signatures algorithms are broken.
+This section will give help on how to achieve that.
+
+First, it is important to know that you do not have to enable any of
+the flags discussed here to be able to use trusted root CA
+certificates signed using @code{RSA-MD2} or @code{RSA-MD5}.  The only
+attack today is that it is possible to generate certificates with
+colliding signatures (collision resistance); you cannot generate a
+certificate that has the same signature as an already existing
+signature (2nd preimage resistance).
+
+If you are using @ref{gnutls_certificate_verify_peers2} to verify the
+certificate chain, you can call
+@ref{gnutls_certificate_set_verify_flags} with the
+@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2} or
+@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} flag, as in:
+
+@example
+  gnutls_certificate_set_verify_flags (x509cred,
+                                       GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5);
+@end example
+
+This will tell the verifier algorithm to enable @code{RSA-MD5} when
+verifying the certificates.
+
+If you are using @ref{gnutls_x509_crt_verify} or
+@ref{gnutls_x509_crt_list_verify}, you can pass the
+@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} parameter directly in the
+@code{flags} parameter.
+
+If you are using these flags, it may also be a good idea to warn the
+user when verification failure occur for this reason.  The simplest is
+to not use the flags by default, and only fall back to using them
+after warning the user.  If you wish to inspect the certificate chain
+yourself, you can use @ref{gnutls_certificate_get_peers} to extract
+the raw server's certificate chain, then use
+@ref{gnutls_x509_crt_import} to parse each of the certificates, and
+then use @ref{gnutls_x509_crt_get_signature_algorithm} to find out the
+signing algorithm used for each certificate.  If any of the
+intermediary certificates are using @code{GNUTLS_SIGN_RSA_MD2} or
+@code{GNUTLS_SIGN_RSA_MD5}, you could present a warning.
+
+
+@node PKCS #11 tokens
+@section @acronym{PKCS #11} tokens
+@anchor{sec:pkcs11}
+@cindex @acronym{PKCS #11} tokens
+
+@subsection Introduction
+This section copes with the @acronym{PKCS #11} support in @acronym{GnuTLS}.
+@acronym{PKCS #11} is plugin API allowing applications to access cryptographic
+operations on a token, as well as to objects residing on the token. A token can 
+be a real hardware token such as a smart card, or it can be a software component
+such as @acronym{Gnome Keyring}. The objects residing on such token can be
+certificates, public keys, private keys or even plain data or  secret keys. Of those
+certificates and public/private key pairs can be used with @acronym{GnuTLS}. It's
+main advantage is that it allows operations on private key objects such as decryption
+and signing without accessing the key itself.
+
+@subsection Initialization
+To allow all the  @acronym{GnuTLS} applications to access @acronym{PKCS #11} tokens
+it is adviceable to use @code{/etc/gnutls/pkcs11.conf}. This file has the following
+format:
+
+@verbatim
+load=/usr/lib/opensc-pkcs11.so
+load=/usr/lib/gnome-keyring/gnome-keyring-pkcs11.so
+@end verbatim
+
+If you use this file, then there is no need for other initialization in
+@acronym{GnuTLS}, except for the PIN and token functions, to allow retrieving a PIN
+when accessing a protected object, such as a private key, or allowing probing
+the user to insert the token. All the initialization functions are below.
+
+@itemize
+
+@item @ref{gnutls_pkcs11_init}: Global initialization
+
+@item @ref{gnutls_pkcs11_deinit}: Global deinitialization
+
+@item @ref{gnutls_pkcs11_set_token_function}: Sets the token insertion function
+
+@item @ref{gnutls_pkcs11_set_pin_function}: Sets the PIN request function
+
+@item @ref{gnutls_pkcs11_add_provider}: Adds an additional @acronym{PKCS #11} provider
+
+@end itemize
+
+@subsection Reading Objects
+
+All @acronym{PKCS #11} objects are referenced by @acronym{GnuTLS} functions by
+URLs as described in @code{draft-pechanec-pkcs11uri-01}. For example a public
+key on a smart card may be referenced as:
+
+@example
+pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe;\
+object=test1;objecttype=public;\
+id=32:f1:53:f3:e3:79:90:b0:86:24:14:10:77:ca:5d:ec:2d:15:fa:ed
+@end example
+
+while the smart card itself can be referenced as:
+@example
+pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe
+@end example
+
+
+Objects can be accessed with the following functions
+@itemize
+
+@item @ref{gnutls_pkcs11_obj_init}: Initializes an object
+
+@item @ref{gnutls_pkcs11_obj_import_url}: To import an object from a url
+
+@item @ref{gnutls_pkcs11_obj_export_url}: To export the URL of the object
+
+@item @ref{gnutls_pkcs11_obj_deinit}: To deinitialize an object
+
+@item @ref{gnutls_pkcs11_obj_export}: To export data associated with object
+
+@item @ref{gnutls_pkcs11_obj_get_info}: To obtain information about an object
+
+@item @ref{gnutls_pkcs11_obj_list_import_url}: To mass load of objects
+
+@item @ref{gnutls_x509_crt_import_pkcs11}: Import a certificate object
+
+@item @ref{gnutls_x509_crt_import_pkcs11_url}: Helper function to directly import a URL into a certificate
+
+@item @ref{gnutls_x509_crt_list_import_pkcs11}: Mass import of certificates
+
+@end itemize
+
+
+Functions that relate to token handling are shown below
+@itemize
+
+@item @ref{gnutls_pkcs11_token_get_url}: Returns the URL of a token
+
+@item @ref{gnutls_pkcs11_token_get_info}: Obtain information about a token
+
+@item @ref{gnutls_pkcs11_token_get_flags}: Returns flags about a token (i.e. hardware or software)
+
+@end itemize
+
+The following example will list all tokens.
+@verbatim
+int i;
+char* url;
+
+	gnutls_global_init();
+
+	for (i=0;;i++) {
+		ret = gnutls_pkcs11_token_get_url(i, &url);
+		if (ret == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE)
+			break;
+
+		if (ret < 0)
+			exit(1);
+		
+		fprintf(stdout, "Token[%d]: URL: %s\n", i, url);
+	}
+	gnutls_global_deinit();
+@end verbatim
+
+
+The next one will list all objects in a token:
+@verbatim
+gnutls_pkcs11_obj_t *obj_list;
+unsigned int obj_list_size = 0;
+gnutls_datum_t cinfo;
+int i;
+
+	crt_list_size = 0;
+	ret = gnutls_pkcs11_obj_list_import_url( crt_list, NULL, url, \
+				GNUTLS_PKCS11_OBJ_ATTR_CRT_WITH_PRIVKEY);
+	if (ret < 0 && ret != GNUTLS_E_SHORT_MEMORY_BUFFER)
+		exit(1);
+
+	crt_list = malloc(sizeof(*crt_list)*crt_list_size);
+	if (crt_list == NULL)
+		exit(1);
+
+	ret = gnutls_pkcs11_obj_list_import_url( crt_list, &crt_list_size, url, flags);
+	if (ret < 0)
+		exit(1);
+
+	/* now all certificates are in crt_list */
+
+	for (i=0;i<crt_list_size;i++) {
+
+		ret = gnutls_x509_crt_init(&xcrt);
+		if (ret < 0)
+			exit(1);
+		
+		ret = gnutls_x509_crt_import_pkcs11(xcrt, crt_list[i]);
+		if (ret < 0)
+			exit(1);
+		
+		ret = gnutls_x509_crt_print (xcrt, GNUTLS_CRT_PRINT_FULL, &cinfo);
+		if (ret < 0)
+			exit(1);
+
+		fprintf(stdout, "cert[%d]:\n %s\n\n", cinfo.data);
+
+		gnutls_free(cinfo.data);
+		gnutls_x509_crt_deinit(&xcrt);
+	}
+@end verbatim
+
+
+@subsection Writing Objects
+
+With @acronym{GnuTLS} you can copy existing private keys and certificates
+to a token. This can be achieved with the following functions
+
+@itemize
+
+@item @ref{gnutls_pkcs11_delete_url}: To delete an object
+
+@item @ref{gnutls_pkcs11_copy_x509_privkey}: To copy a private key to a token
+
+@item @ref{gnutls_pkcs11_copy_x509_crt}: To copy a certificate to a token
+
+@end itemize
+
+
+@subsection Using a @acronym{PKCS #11} token with TLS
+
+This example will demonstrate how to load keys and certificates
+from a @acronym{PKCS} #11 token, and use it with a TLS connection.
+
+@verbatiminclude examples/ex-cert-select-pkcs11.c
+
diff --git a/doc/cha-ciphersuites.texi b/doc/cha-ciphersuites.texi
new file mode 100644
index 0000000000..e0fad2218f
--- /dev/null
+++ b/doc/cha-ciphersuites.texi
@@ -0,0 +1,44 @@
+@node All the supported ciphersuites in GnuTLS
+@chapter All the Supported Ciphersuites in @acronym{GnuTLS}
+@anchor{ciphersuites}
+@cindex Ciphersuites
+
+@include algorithms.texi
+
+Some additional information regarding some of the algorithms:
+
+@table @code
+@item RSA
+RSA is public key cryptosystem designed by Ronald Rivest, Adi Shamir
+and Leonard Adleman.  It can be used with any hash functions.
+
+@item DSA
+DSA is the USA's Digital Signature Standard.  It uses only the SHA-1
+hash algorithm.
+
+@item MD2
+MD2 is a cryptographic hash algorithm designed by Ron Rivest.  It is
+optimized for 8-bit processors. Outputs 128 bits of data.  There are
+no known weaknesses of this algorithm but since this algorithm is
+rarely used and not really studied it should not be used today.
+
+@item MD5
+MD5 is a cryptographic hash algorithm designed by Ron Rivest. Outputs
+128 bits of data.  It is considered to be broken.
+
+@item SHA-1
+SHA is a cryptographic hash algorithm designed by NSA. Outputs 160
+bits of data.  It is also considered to be broken, though no practical
+attacks have been found.
+
+@item RMD160
+RIPEMD is a cryptographic hash algorithm developed in the framework of
+the EU project RIPE.  Outputs 160 bits of data.
+
+@end table
+
+@c
+@c Guile Bindings
+@c
+
+@include guile.texi
diff --git a/doc/cha-copying.texi b/doc/cha-copying.texi
new file mode 100644
index 0000000000..d35dd92e55
--- /dev/null
+++ b/doc/cha-copying.texi
@@ -0,0 +1,29 @@
+@node Copying Information
+@appendix Copying Information
+
+@menu
+* GNU Free Documentation License::   License for copying this manual.
+* GNU LGPL::                     License for copying the core GnuTLS library.
+* GNU GPL::                      License for copying GnuTLS-extra and tools.
+@end menu
+
+@node GNU Free Documentation License
+@appendixsec GNU Free Documentation License
+
+@cindex FDL, GNU Free Documentation License
+
+@include fdl-1.3.texi
+
+@node GNU LGPL
+@appendixsec GNU Lesser General Public License
+@cindex LGPL, GNU Lesser General Public License
+@cindex License, GNU LGPL
+
+@include lgpl-2.1.texi
+
+@node GNU GPL
+@appendixsec GNU General Public License
+@cindex GPL, GNU General Public License
+@cindex License, GNU GPL
+
+@include gpl-3.0.texi
diff --git a/doc/cha-functions.texi b/doc/cha-functions.texi
new file mode 100644
index 0000000000..f73bc571e9
--- /dev/null
+++ b/doc/cha-functions.texi
@@ -0,0 +1,120 @@
+@node Function reference
+@chapter Function Reference
+@cindex Function reference
+
+@menu
+* Core functions::
+* X.509 certificate functions::
+* GnuTLS-extra functions::
+* OpenPGP functions::
+* TLS Inner Application (TLS/IA) functions::
+* Error codes and descriptions::
+@end menu
+
+@node Core functions
+@section Core Functions
+
+The prototypes for the following functions lie in
+@file{gnutls/gnutls.h}.
+
+@include gnutls-api.texi
+
+@node X.509 certificate functions
+@section @acronym{X.509} Certificate Functions
+@anchor{sec:x509api}
+@cindex @acronym{X.509} Functions
+
+The following functions are to be used for @acronym{X.509} certificate handling.
+Their prototypes lie in @file{gnutls/x509.h}.
+
+@include x509-api.texi
+
+@node GnuTLS-extra functions
+@section @acronym{GnuTLS-extra} Functions
+@cindex @acronym{GnuTLS-extra} functions
+
+These functions are only available in the GPLv3+ version of the
+library called @code{gnutls-extra}. The prototypes for this library
+lie in @file{gnutls/extra.h}.
+
+@include extra-api.texi
+
+@node OpenPGP functions
+@section @acronym{OpenPGP} Functions
+@cindex @acronym{OpenPGP} functions
+@anchor{sec:openpgpapi}
+
+The following functions are to be used for @acronym{OpenPGP}
+certificate handling.  Their prototypes lie in
+@file{gnutls/openpgp.h}.
+
+@include pgp-api.texi
+
+@node TLS Inner Application (TLS/IA) functions
+@section @acronym{TLS} Inner Application (@acronym{TLS/IA}) Functions
+@cindex @acronym{TLS} Inner Application (@acronym{TLS/IA}) functions
+@cindex Inner Application (@acronym{TLS/IA}) functions
+
+The following functions are used for @acronym{TLS} Inner Application
+(@acronym{TLS/IA}).  Their prototypes lie in @file{gnutls/extra.h}.
+You need to link with @file{libgnutls-extra} to be able to use these
+functions (@pxref{GnuTLS-extra functions}).
+
+The typical control flow in an TLS/IA client (that would not require
+an Application Phase for resumed sessions) would be similar to the
+following:
+
+@example
+int client_avp (gnuls_session_t *session, void *ptr,
+                const char *last, size_t lastlen,
+		char **new, size_t *newlen)
+@{
+...
+@}
+...
+int main ()
+@{
+  gnutls_ia_client_credentials_t iacred;
+...
+  gnutls_init (&session, GNUTLS_CLIENT);
+...
+  /* Enable TLS/IA. */
+  gnutls_ia_allocate_client_credentials(&iacred);
+  gnutls_ia_set_client_avp_function(iacred, client_avp);
+  gnutls_credentials_set (session, GNUTLS_CRD_IA, iacred);
+...
+  ret = gnutls_handshake (session);
+  // Error handling...
+...
+  if (gnutls_ia_handshake_p (session))
+    @{
+      ret = gnutls_ia_handshake (session);
+      // Error handling...
+...
+@end example
+
+See below for detailed descriptions of all the functions used above.
+
+The function @code{client_avp} would have to be implemented by your
+application.  The function is responsible for handling the AVP data.
+See @code{gnutls_ia_set_client_avp_function} below for more
+information on how that function should be implemented.
+
+The control flow in a typical server is similar to the above, use
+@code{gnutls_ia_server_credentials_t} instead of
+@code{gnutls_ia_client_credentials_t}, and replace the call to the
+client functions with the corresponding server functions.
+
+@include ia-api.texi
+
+@node Error codes and descriptions
+@section Error Codes and Descriptions
+@anchor{Error Codes}
+@cindex Error codes
+
+The error codes used throughout the library are described below.  The
+return code @code{GNUTLS_E_SUCCESS} indicate successful operation, and
+is guaranteed to have the value 0, so you can use it in logical
+expressions.
+
+@include error_codes.texi
diff --git a/doc/cha-internals.texi b/doc/cha-internals.texi
new file mode 100644
index 0000000000..fda6221699
--- /dev/null
+++ b/doc/cha-internals.texi
@@ -0,0 +1,336 @@
+@node Internal architecture of GnuTLS
+@chapter Internal Architecture of GnuTLS
+@cindex Internal architecture
+
+This chapter is to give a brief description of the
+way @acronym{GnuTLS} works. The focus is to give an idea
+to potential developers and those who want to know what
+happens inside the black box.
+
+@menu
+* The TLS Protocol::
+* TLS Handshake Protocol::
+* TLS Authentication Methods::
+* TLS Extension Handling::
+* Certificate Handling::
+* Cryptographic Backend::
+@end menu
+
+@node The TLS Protocol
+@section The TLS Protocol
+The main needs for the TLS protocol to be used are
+shown in the image below.
+
+@image{gnutls-client-server-use-case,9cm}
+
+This is being accomplished by the following object diagram.
+Note that since @acronym{GnuTLS} is being developed in C
+object are just structures with attributes. The operations listed
+are functions that require the first parameter to be that object.
+@image{gnutls-objects,15cm}
+
+@node TLS Handshake Protocol
+@section TLS Handshake Protocol
+The @acronym{GnuTLS} handshake protocol is implemented as a state
+machine that waits for input or returns immediately when the non-blocking
+transport layer functions are used. The main idea is shown in the following
+figure.
+
+@image{gnutls-handshake-state,9cm}
+
+Also the way the input is processed varies per ciphersuite. Several 
+implementations of the internal handlers are available and 
+@ref{gnutls_handshake} only multiplexes the input to the appropriate 
+handler. For example a @acronym{PSK} ciphersuite has a different 
+implementation of the @code{process_client_key_exchange} than a
+certificate ciphersuite.
+
+@image{gnutls-handshake-sequence,12cm}
+
+@node TLS Authentication Methods
+@section TLS Authentication Methods
+In @acronym{GnuTLS} authentication methods can be implemented quite
+easily.  Since the required changes to add a new authentication method
+affect only the handshake protocol, a simple interface is used. An
+authentication method needs only to implement the functions as seen in
+the figure below.
+
+@image{gnutls-mod_auth_st,12cm}
+
+The functions that need to be implemented are the ones responsible for
+interpreting the handshake protocol messages. It is common for such
+functions to read data from one or more @code{credentials_t}
+structures@footnote{such as the
+@code{gnutls_certificate_credentials_t} structures} and write data,
+such as certificates, usernames etc. to @code{auth_info_t} structures.
+
+Simple examples of existing authentication methods can be seen in
+@code{auth_psk.c} for PSK ciphersuites and @code{auth_srp.c} for SRP
+ciphersuites. After implementing these functions the structure holding
+its pointers has to be registered in @code{gnutls_algorithms.c} in the
+@code{_gnutls_kx_algorithms} structure.
+
+@node TLS Extension Handling
+@section TLS Extension Handling
+As with authentication methods, the TLS extensions handlers can be
+implemented using the following interface.
+
+@image{gnutls-extensions_st,12cm}
+
+Here there are two functions, one for receiving the extension data
+and one for sending. These functions have to check internally whether
+they operate in client or server side. 
+
+A simple example of an extension handler can be seen in
+@code{ext_srp.c} After implementing these functions, together with the
+extension number they handle, they have to be registered in
+@code{gnutls_extensions.c} in the @code{_gnutls_extensions} structure.
+
+@subsection Adding a New TLS Extension
+
+Adding support for a new TLS extension is done from time to time, and
+the process to do so is not difficult.  Here are the steps you need to
+follow if you wish to do this yourself.  For sake of discussion, let's
+consider adding support for the hypothetical TLS extension
+@code{foobar}.
+
+@enumerate
+
+@item Add @code{configure} option like @code{--enable-foobar} or @code{--disable-foobar}.
+
+Which to chose depends on whether you intend to make the extension be
+enabled by default.  Look at existing checks (i.e., SRP, authz) for
+how to model the code.  For example:
+
+@example
+AC_MSG_CHECKING([whether to disable foobar support])
+AC_ARG_ENABLE(foobar,
+	AS_HELP_STRING([--disable-foobar],
+		[disable foobar support]),
+	ac_enable_foobar=no)
+if test x$ac_enable_foobar != xno; then
+ AC_MSG_RESULT(no)
+ AC_DEFINE(ENABLE_FOOBAR, 1, [enable foobar])
+else
+ ac_full=0
+ AC_MSG_RESULT(yes)
+fi
+AM_CONDITIONAL(ENABLE_FOOBAR, test "$ac_enable_foobar" != "no")
+@end example
+
+These lines should go in @code{lib/m4/hooks.m4}.
+
+@item Add IANA extension value to @code{extensions_t} in @code{gnutls_int.h}.
+
+A good name for the value would be GNUTLS_EXTENSION_FOOBAR.  Check
+with @url{http://www.iana.org/assignments/tls-extensiontype-values}
+for allocated values.  For experiments, you could pick a number but
+remember that some consider it a bad idea to deploy such modified
+version since it will lead to interoperability problems in the future
+when the IANA allocates that number to someone else, or when the
+foobar protocol is allocated another number.
+
+@item Add an entry to @code{_gnutls_extensions} in @code{gnutls_extensions.c}.
+
+A typical entry would be:
+
+@example
+  int ret;
+
+  /* ...
+   */
+
+#if ENABLE_FOOBAR
+  ret = gnutls_ext_register (GNUTLS_EXTENSION_FOOBAR,
+                             "FOOBAR",
+                             GNUTLS_EXT_TLS,
+                             _gnutls_foobar_recv_params,
+                             _gnutls_foobar_send_params);
+  if (ret != GNUTLS_E_SUCCESS)
+    return ret;
+#endif
+@end example
+
+The GNUTLS_EXTENSION_FOOBAR is the integer value you added to
+@code{gnutls_int.h} earlier.  The two functions are new functions that
+you will need to implement, most likely you'll need to add an
+@code{#include "ext_foobar.h"} as well.
+
+@item Add new files @code{ext_foobar.c} and @code{ext_foobar.h} that implements the extension.
+
+The functions you are responsible to add are those mentioned in the
+previous step.  As a starter, you could add this:
+
+@example
+int
+_gnutls_foobar_recv_params (gnutls_session_t session,
+                            const opaque * data,
+                            size_t data_size)
+@{
+  return 0;
+@}
+
+int
+_gnutls_foobar_send_params (gnutls_session_t session,
+                            opaque * data,
+                            size_t _data_size)
+@{
+  return 0;
+@}
+@end example
+
+The @code{_gnutls_foobar_recv_params} function is responsible for
+parsing incoming extension data (both in the client and server).
+
+The @code{_gnutls_foobar_send_params} function is responsible for
+sending extension data (both in the client and server).
+
+If you receive length fields that doesn't match, return
+@code{GNUTLS_E_UNEXPECTED_PACKET_LENGTH}.  If you receive invalid
+data, return @code{GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER}.  You can use
+other error codes too.  Return 0 on success.
+
+The function typically store some information in the @code{session}
+variable for later usage.  If you need to add new fields there, check
+@code{tls_ext_st} in @code{gnutls_int.h} and compare with existing TLS
+extension specific variables.
+
+Recall that both the client and server both send and receives
+parameters, and your code most likely will need to do different things
+depending on which mode it is in.  It may be useful to make this
+distinction explicit in the code.  Thus, for example, a better
+template than above would be:
+
+@example
+int
+_gnutls_foobar_recv_params (gnutls_session_t session,
+                            const opaque * data,
+                            size_t data_size)
+@{
+  if (session->security_parameters.entity == GNUTLS_CLIENT)
+    return foobar_recv_client (session, data, data_size);
+  else
+    return foobar_recv_server (session, data, data_size);
+@}
+
+int
+_gnutls_foobar_send_params (gnutls_session_t session,
+                            opaque * data,
+                            size_t data_size)
+@{
+  if (session->security_parameters.entity == GNUTLS_CLIENT)
+    return foobar_send_client (session, data, data_size);
+  else
+    return foobar_send_server (session, data, data_size);
+@}
+@end example
+
+The functions used would be declared as @code{static} functions, of
+the appropriate prototype, in the same file.
+
+When adding the files, you'll need to add them to @code{Makefile.am}
+as well, for example:
+
+@example
+if ENABLE_FOOBAR
+COBJECTS += ext_foobar.c
+HFILES += ext_foobar.h
+endif
+@end example
+
+@item Add API functions to enable/disable the extension.
+
+Normally the client will have one API to request use of the extension,
+and setting some extension specific data.  The server will have one
+API to let the library know that it is willing to accept the
+extension, often this is implemented through a callback but it doesn't
+have to.
+
+The APIs need to be added to @code{includes/gnutls/gnutls.h} or
+@code{includes/gnutls/extra.h} as appropriate.  It is recommended that
+if you don't have a requirement to use the LGPLv2.1+ license for your
+extension, that you place your work under the GPLv3+ license and thus
+in the libgnutls-extra library.
+
+You can implement the API function in the @code{ext_foobar.c} file, or
+if that file ends up becoming rather larger, add a
+@code{gnutls_foobar.c} file.
+
+To make the API available in the shared library you need to add the
+symbol in @code{lib/libgnutls.map} or
+@code{libextra/libgnutls-extra.map} as appropriate, so that the symbol
+is exported properly.
+
+When writing GTK-DOC style documentation for your new APIs, don't
+forget to add @code{Since:} tags to indicate the GnuTLS version the
+API was introduced in.
+
+@end enumerate
+
+@node Certificate Handling
+@section Certificate Handling
+What is provided by the certificate handling functions
+is summarized in the following diagram.
+
+@image{gnutls-certificate-user-use-case,12cm}
+
+@node Cryptographic Backend
+@section Cryptographic Backend
+Several new systems provide hardware assisted cryptographic algorithm
+implementations that offer implementations some orders of magnitude
+faster than the software. For this reason GnuTLS supports by default
+the /dev/crypto device usually found in FreeBSD and OpenBSD system, to
+take advantage of installed hardware. 
+
+In addition it is possible to override parts of the crypto backend or the
+whole. It is possible to override them both at runtime and compile
+time, however here we will discuss the runtime possibility. The API
+available for this functionality is in @code{gnutls/crypto.h} header
+file.
+
+@subsection Override specific algorithms
+When an optimized implementation of a single algorithm is available,
+say a hardware assisted version of @acronym{AES-CBC} then the
+following functions can be used to register those algorithms.
+
+@itemize
+
+@item @ref{gnutls_crypto_single_cipher_register2}
+To register a cipher algorithm.
+
+@ref{gnutls_crypto_single_digest_register2}
+To register a hash (digest) or MAC algorithm.
+
+@end itemize
+
+Those registration functions will only replace the specified algorithm
+and leave the rest of subsystem intact.
+
+@subsection Override parts of the backend
+In some systems, such as embedded ones, it might be desirable to
+override big parts of the cryptographic backend, or even all of
+them. For this reason the following functions are provided.
+
+@itemize
+
+@item @ref{gnutls_crypto_cipher_register2}
+To override the cryptographic algorithms backend.
+
+@item @ref{gnutls_crypto_digest_register2}
+To override the digest algorithms backend.
+
+@item @ref{gnutls_crypto_rnd_register2}
+To override the random number generator backend.
+
+@item @ref{gnutls_crypto_bigint_register2}
+To override the big number number operations backend.
+
+@item @ref{gnutls_crypto_pk_register2}
+To override the public key encryption backend. This is tight to the
+big number operations so either both of them should be updated or care
+must be taken to use the same format.
+
+@end itemize
+
+If all of them are used then GnuTLS will no longer use libgcrypt.
+
diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
new file mode 100644
index 0000000000..f7b88d07a1
--- /dev/null
+++ b/doc/cha-intro-tls.texi
@@ -0,0 +1,783 @@
+@node Introduction to TLS
+@chapter Introduction to @acronym{TLS}
+
+@acronym{TLS} stands for ``Transport Layer Security'' and is the
+successor of SSL, the Secure Sockets Layer protocol @xcite{SSL3}
+designed by Netscape.  @acronym{TLS} is an Internet protocol, defined
+by @acronym{IETF}@footnote{IETF, or Internet Engineering Task Force,
+is a large open international community of network designers,
+operators, vendors, and researchers concerned with the evolution of
+the Internet architecture and the smooth operation of the Internet.
+It is open to any interested individual.}, described in @acronym{RFC}
+4346 and also in @xcite{RESCORLA}.  The protocol provides
+confidentiality, and authentication layers over any reliable transport
+layer.  The description, below, refers to @acronym{TLS} 1.0 but also
+applies to @acronym{TLS} 1.1 @xcite{RFC4346} and @acronym{SSL} 3.0,
+since the differences of these protocols are minor.  Older protocols
+such as @acronym{SSL} 2.0 are not discussed nor implemented in
+@acronym{GnuTLS} since they are not considered secure today.  GnuTLS
+also supports @acronym{X.509} and @acronym{OpenPGP} @xcite{RFC4880}.
+
+@menu
+* TLS layers::
+* The transport layer::
+* The TLS record protocol::
+* The TLS Alert Protocol::
+* The TLS Handshake Protocol::
+* TLS Extensions::
+* Selecting cryptographic key sizes::
+* On SSL 2 and older protocols::
+* On Record Padding::
+* Safe Renegotiation::
+@end menu
+
+@node TLS layers
+@section TLS Layers
+@cindex TLS Layers
+
+@acronym{TLS} is a layered protocol, and consists of the Record
+Protocol, the Handshake Protocol and the Alert Protocol. The Record
+Protocol is to serve all other protocols and is above the transport
+layer.  The Record protocol offers symmetric encryption, data
+authenticity, and optionally compression.
+
+The Alert protocol offers some signaling to the other protocols. It
+can help informing the peer for the cause of failures and other error
+conditions.  @xref{The Alert Protocol}, for more information.  The
+alert protocol is above the record protocol.
+
+The Handshake protocol is responsible for the security parameters'
+negotiation, the initial key exchange and authentication.  @xref{The
+Handshake Protocol}, for more information about the handshake
+protocol.  The protocol layering in TLS is shown in the figure below.
+
+@image{gnutls-layers,12cm,8cm}
+
+@node The transport layer
+@section The Transport Layer
+@cindex Transport protocol
+
+@acronym{TLS} is not limited to one transport layer, it can be used
+above any transport layer, as long as it is a reliable one.  A set of
+functions is provided and their purpose is to load to @acronym{GnuTLS} the
+required callbacks to access the transport layer.
+
+@itemize
+@item @ref{gnutls_transport_set_push_function}
+@item @ref{gnutls_transport_set_pull_function}
+@item @ref{gnutls_transport_set_ptr}
+@item @ref{gnutls_transport_set_lowat}
+@item @ref{gnutls_transport_set_errno}
+@end itemize
+
+These functions accept a callback function as a parameter.  The
+callback functions should return the number of bytes written, or -1 on
+error and should set @code{errno} appropriately.
+
+In some environments, setting @code{errno} is unreliable, for example
+Windows have several errno variables in different CRTs, or it may be
+that errno is not a thread-local variable.  If this is a concern to
+you, call @code{gnutls_transport_set_errno} with the intended errno
+value instead of setting @code{errno} directly.
+
+@acronym{GnuTLS} currently only interprets the EINTR and EAGAIN errno
+values and returns the corresponding @acronym{GnuTLS} error codes
+@code{GNUTLS_E_INTERRUPTED} and @code{GNUTLS_E_AGAIN}.  These values
+are usually returned by interrupted system calls, or when non blocking
+IO is used.  All @acronym{GnuTLS} functions can be resumed (called
+again), if any of these error codes is returned.  The error codes
+above refer to the system call, not the @acronym{GnuTLS} function,
+since signals do not interrupt @acronym{GnuTLS}' functions.
+
+For non blocking sockets or other custom made pull/push functions
+the @ref{gnutls_transport_set_lowat} must be called, with a zero
+low water mark value.
+
+By default, if the transport functions are not set, @acronym{GnuTLS}
+will use the Berkeley Sockets functions.  In this case
+@acronym{GnuTLS} will use some hacks in order for @code{select} to
+work, thus making it easy to add @acronym{TLS} support to existing
+TCP/IP servers.
+
+@node The TLS record protocol
+@section The TLS Record Protocol
+@cindex Record protocol
+
+The Record protocol is the secure communications provider. Its purpose
+is to encrypt, authenticate and ---optionally--- compress packets.
+The following functions are available:
+
+@table @asis
+
+@item @ref{gnutls_record_send}:
+To send a record packet (with application data).
+
+@item @ref{gnutls_record_recv}:
+To receive a record packet (with application data).
+
+@item @ref{gnutls_record_get_direction}:
+To get the direction of the last interrupted function call.
+@end table
+
+As you may have already noticed, the functions which access the Record
+protocol, are quite limited, given the importance of this protocol in
+@acronym{TLS}.  This is because the Record protocol's parameters are
+all set by the Handshake protocol.
+
+The Record protocol initially starts with NULL parameters, which means
+no encryption, and no MAC is used. Encryption and authentication begin
+just after the handshake protocol has finished.
+
+@menu
+* Encryption algorithms used in the record layer::
+* Compression algorithms used in the record layer::
+* Weaknesses and countermeasures::
+@end menu
+
+@node Encryption algorithms used in the record layer
+@subsection Encryption Algorithms Used in the Record Layer
+@cindex Symmetric encryption algorithms
+
+Confidentiality in the record layer is achieved by using symmetric
+block encryption algorithms like @code{3DES}, @code{AES}@footnote{AES,
+or Advanced Encryption Standard, is actually the RIJNDAEL algorithm.
+This is the algorithm that replaced DES.}, or stream algorithms like
+@code{ARCFOUR_128}@footnote{@code{ARCFOUR_128} is a compatible
+algorithm with RSA's RC4 algorithm, which is considered to be a trade
+secret.}. Ciphers are encryption algorithms that use a single, secret,
+key to encrypt and decrypt data. Block algorithms in TLS also provide
+protection against statistical analysis of the data.  Thus, if you're
+using the @acronym{TLS} protocol, a random number of blocks will be
+appended to data, to prevent eavesdroppers from guessing the actual
+data size.
+
+Supported cipher algorithms:
+
+@table @code
+@item 3DES_CBC
+@code{3DES_CBC} is the DES block cipher algorithm used with triple
+encryption (EDE). Has 64 bits block size and is used in CBC mode.
+
+@item ARCFOUR_128
+ARCFOUR is a fast stream cipher.
+
+@item ARCFOUR_40
+This is the ARCFOUR cipher that is fed with a 40 bit key,
+which is considered weak.
+
+@item AES_CBC
+AES or RIJNDAEL is the block cipher algorithm that replaces the old
+DES algorithm.  Has 128 bits block size and is used in CBC mode. This
+is not officially supported in TLS.
+@end table
+
+Supported MAC algorithms:
+
+@table @code
+@item MAC_MD5
+MD5 is a cryptographic hash algorithm designed by Ron Rivest. Outputs
+128 bits of data.
+
+@item MAC_SHA
+SHA is a cryptographic hash algorithm designed by NSA. Outputs 160
+bits of data.
+
+@end table
+
+@node Compression algorithms used in the record layer
+@subsection Compression Algorithms Used in the Record Layer
+@cindex Compression algorithms
+
+The TLS record layer also supports compression.  The algorithms
+implemented in @acronym{GnuTLS} can be found in the table below.
+All the algorithms except for DEFLATE which is
+referenced in @xcite{RFC3749}, should be considered as
+@acronym{GnuTLS}' extensions@footnote{You should use
+@ref{gnutls_handshake_set_private_extensions} to enable private
+extensions.}, and should be advertised only when the peer is known to
+have a compliant client, to avoid interoperability problems.
+
+The included algorithms perform really good when text, or other
+compressible data are to be transfered, but offer nothing on already
+compressed data, such as compressed images, zipped archives etc.
+These compression algorithms, may be useful in high bandwidth TLS
+tunnels, and in cases where network usage has to be minimized. As a
+drawback, compression increases latency.
+
+The record layer compression in @acronym{GnuTLS} is implemented based
+on the proposal @xcite{RFC3749}.
+The supported compression algorithms are:
+
+@table @code
+@item DEFLATE
+Zlib compression, using the deflate algorithm.
+
+@item LZO
+LZO is a very fast compression algorithm.  This algorithm is only
+available if the @acronym{GnuTLS-extra} library has been initialized
+and the private extensions are enabled, and if GnuTLS was built with
+LZO support.
+
+@end table
+
+@node Weaknesses and countermeasures
+@subsection Weaknesses and Countermeasures
+
+Some weaknesses that may affect the security of the Record layer have
+been found in @acronym{TLS} 1.0 protocol. These weaknesses can be
+exploited by active attackers, and exploit the facts that
+
+@enumerate
+
+@item
+@acronym{TLS} has separate alerts for ``decryption_failed'' and
+``bad_record_mac''
+
+@item
+The decryption failure reason can be detected by timing the response
+time.
+
+@item
+The IV for CBC encrypted packets is the last block of the previous
+encrypted packet.
+
+@end enumerate
+
+Those weaknesses were solved in @acronym{TLS} 1.1 @xcite{RFC4346}
+which is implemented in @acronym{GnuTLS}. For a detailed discussion
+see the archives of the TLS Working Group mailing list and the paper
+@xcite{CBCATT}.
+
+@node The TLS Alert Protocol
+@section The TLS Alert Protocol
+@anchor{The Alert Protocol}
+@cindex Alert protocol
+
+The Alert protocol is there to allow signals to be sent between peers.
+These signals are mostly used to inform the peer about the cause of a
+protocol failure. Some of these signals are used internally by the
+protocol and the application protocol does not have to cope with them
+(see @code{GNUTLS_A_CLOSE_NOTIFY}), and others refer to the
+application protocol solely (see @code{GNUTLS_A_USER_CANCELLED}).  An
+alert signal includes a level indication which may be either fatal or
+warning. Fatal alerts always terminate the current connection, and
+prevent future renegotiations using the current session ID.
+
+The alert messages are protected by the record protocol, thus the
+information that is included does not leak. You must take extreme care
+for the alert information not to leak to a possible attacker, via
+public log files etc.
+
+@table @asis
+@item @ref{gnutls_alert_send}:
+To send an alert signal.
+
+@item @ref{gnutls_error_to_alert}:
+To map a gnutls error number to an alert signal.
+
+@item @ref{gnutls_alert_get}:
+Returns the last received alert.
+
+@item @ref{gnutls_alert_get_name}:
+Returns the name, in a character array, of the given alert.
+
+@end table
+
+@node The TLS Handshake Protocol
+@section The TLS Handshake Protocol
+@anchor{The Handshake Protocol}
+@cindex Handshake protocol
+
+The Handshake protocol is responsible for the ciphersuite negotiation,
+the initial key exchange, and the authentication of the two peers.
+This is fully controlled by the application layer, thus your program
+has to set up the required parameters. Available functions to control
+the handshake protocol include:
+
+@table @asis
+@item @ref{gnutls_priority_init}:
+To initialize a priority set of ciphers.
+
+@item @ref{gnutls_priority_deinit}:
+To deinitialize a priority set of ciphers.
+
+@item @ref{gnutls_priority_set}:
+To associate a priority set with a @acronym{TLS} session.
+
+@item @ref{gnutls_priority_set_direct}:
+To directly associate a session with a given priority string.
+
+@item @ref{gnutls_credentials_set}:
+To set the appropriate credentials structures.
+
+@item @ref{gnutls_certificate_server_set_request}:
+To set whether client certificate is required or not.
+
+@item @ref{gnutls_handshake}:
+To initiate the handshake.
+@end table
+
+@subsection TLS Cipher Suites
+
+The Handshake Protocol of @acronym{TLS} negotiates cipher suites of
+the form @code{TLS_DHE_RSA_WITH_3DES_CBC_SHA}.  The usual cipher
+suites contain these parameters:
+
+@itemize
+
+@item The key exchange algorithm.
+@code{DHE_RSA} in the example.
+
+@item The Symmetric encryption algorithm and mode
+@code{3DES_CBC} in this example.
+
+@item The MAC@footnote{MAC stands for Message Authentication Code. It can be described as a keyed hash algorithm. See RFC2104.} algorithm used for authentication.
+@code{MAC_SHA} is used in the above example.
+
+@end itemize
+
+The cipher suite negotiated in the handshake protocol will affect the
+Record Protocol, by enabling encryption and data authentication.  Note
+that you should not over rely on @acronym{TLS} to negotiate the
+strongest available cipher suite. Do not enable ciphers and algorithms
+that you consider weak.
+
+The priority functions, dicussed above, allow the application layer to
+enable and set priorities on the individual ciphers. It may imply that
+all combinations of ciphersuites are allowed, but this is not
+true. For several reasons, not discussed here, some combinations were
+not defined in the @acronym{TLS} protocol.  The supported ciphersuites
+are shown in @ref{ciphersuites}.
+
+@subsection Client Authentication
+@cindex Client Certificate authentication
+
+In the case of ciphersuites that use certificate authentication, the
+authentication of the client is optional in @acronym{TLS}.  A server
+may request a certificate from the client --- using the
+@ref{gnutls_certificate_server_set_request} function. If a certificate
+is to be requested from the client during the handshake, the server
+will send a certificate request message that contains a list of
+acceptable certificate signers. In @acronym{GnuTLS} the certificate
+signers list is constructed using the trusted Certificate Authorities
+by the server. That is the ones set using
+@itemize
+@item @ref{gnutls_certificate_set_x509_trust_file}
+@item @ref{gnutls_certificate_set_x509_trust_mem}
+@end itemize
+
+Sending of the names of the CAs can be controlled using
+@ref{gnutls_certificate_send_x509_rdn_sequence}. The client, then, may
+send a certificate, signed by one of the server's acceptable signers.
+
+@subsection Resuming Sessions
+@anchor{resume}
+@cindex Resuming sessions
+
+The @ref{gnutls_handshake} function, is expensive since a lot of
+calculations are performed. In order to support many fast connections
+to the same server a client may use session resuming. @strong{Session
+resuming} is a feature of the @acronym{TLS} protocol which allows a
+client to connect to a server, after a successful handshake, without
+the expensive calculations.  This is achieved by using the previously
+established keys. @acronym{GnuTLS} supports this feature, and the
+example (@pxref{ex:resume-client}) illustrates a typical use of it.
+
+Keep in mind that sessions are expired after some time, for security
+reasons, thus it may be normal for a server not to resume a session
+even if you requested that.  Also note that you must enable, using the
+priority functions, at least the algorithms used in the last session.
+
+@subsection Resuming Internals
+
+The resuming capability, mostly in the server side, is one of the
+problems of a thread-safe TLS implementations. The problem is that all
+threads must share information in order to be able to resume
+sessions. The gnutls approach is, in case of a client, to leave all
+the burden of resuming to the client. I.e., copy and keep the
+necessary parameters. See the functions:
+
+@itemize
+
+@item @ref{gnutls_session_get_data}
+
+@item @ref{gnutls_session_get_id}
+
+@item @ref{gnutls_session_set_data}
+
+@end itemize
+
+The server side is different. A server has to specify some callback
+functions which store, retrieve and delete session data. These can be
+registered with:
+
+@itemize
+
+@item @ref{gnutls_db_set_remove_function}
+
+@item @ref{gnutls_db_set_store_function}
+
+@item @ref{gnutls_db_set_retrieve_function}
+
+@item @ref{gnutls_db_set_ptr}
+
+@end itemize
+
+It might also be useful to be able to check for expired sessions in
+order to remove them, and save space. The function
+@ref{gnutls_db_check_entry} is provided for that reason.
+
+@node TLS Extensions
+@section TLS Extensions
+@cindex TLS Extensions
+
+A number of extensions to the @acronym{TLS} protocol have been
+proposed mainly in @xcite{TLSEXT}. The extensions supported
+in @acronym{GnuTLS} are:
+
+@itemize
+@item Maximum fragment length negotiation
+@item Server name indication
+@item Session tickets
+@end itemize
+
+and they will be discussed in the subsections that follow.
+
+@subsection Maximum Fragment Length Negotiation
+@cindex TLS Extensions
+@cindex Maximum fragment length
+
+This extension allows a @acronym{TLS} implementation to negotiate a
+smaller value for record packet maximum length. This extension may be
+useful to clients with constrained capabilities. See the
+@ref{gnutls_record_set_max_size} and the
+@ref{gnutls_record_get_max_size} functions.
+
+@subsection Server Name Indication
+@anchor{serverind}
+@cindex TLS Extensions
+@cindex Server name indication
+
+A common problem in @acronym{HTTPS} servers is the fact that the
+@acronym{TLS} protocol is not aware of the hostname that a client
+connects to, when the handshake procedure begins. For that reason the
+@acronym{TLS} server has no way to know which certificate to send.
+
+This extension solves that problem within the @acronym{TLS} protocol,
+and allows a client to send the HTTP hostname before the handshake
+begins within the first handshake packet.  The functions
+@ref{gnutls_server_name_set} and @ref{gnutls_server_name_get} can be
+used to enable this extension, or to retrieve the name sent by a
+client.
+
+@subsection Session Tickets
+@cindex TLS Extensions
+@cindex Session Tickets
+@cindex Ticket
+
+To resume a TLS session the server normally store some state.  This
+complicates deployment, and typical situations the client can cache
+information and send it to the server instead.  The Session Ticket
+extension implements this idea, and it is documented in
+RFC 5077 @xcite{TLSTKT}.
+
+Clients can enable support for TLS tickets with
+@ref{gnutls_session_ticket_enable_client} and servers use
+@ref{gnutls_session_ticket_key_generate} to generate a key and
+@ref{gnutls_session_ticket_enable_server} to enable the extension.
+Clients resume sessions using the ticket using the normal session
+resume functions, @ref{resume}.
+
+@node Selecting cryptographic key sizes
+@section Selecting Cryptographic Key Sizes
+@cindex key sizes
+
+In TLS, since a lot of algorithms are involved, it is not easy to set
+a consistent security level.  For this reason this section will
+present some correspondance between key sizes of symmetric algorithms
+and public key algorithms based on the most conservative values of
+@xcite{SELKEY}.  Those can be used to generate certificates with
+appropriate key sizes as well as parameters for Diffie-Hellman and SRP
+authentication.
+
+@multitable @columnfractions .15 .20 .20 .20
+
+@item Year
+@tab Symmetric key size
+@tab RSA key size, DH and SRP prime size
+@tab ECC key size
+
+@item 1982
+@tab 56
+@tab 417
+@tab 105
+
+@item 1988
+@tab 61
+@tab 566
+@tab 114
+
+@item 2002
+@tab 72
+@tab 1028
+@tab 139
+
+@item 2015
+@tab 82
+@tab 1613
+@tab 173
+
+@item 2028
+@tab 92
+@tab 2362
+@tab 210
+
+@item 2040
+@tab 101
+@tab 3214
+@tab 244
+
+@item 2050
+@tab 109
+@tab 4047
+@tab 272
+
+@end multitable
+
+The first column provides an estimation of the year until these
+parameters are considered safe and the rest of the columns list the
+parameters for the various algorithms.
+
+Note however that the values suggested here are nothing more than an
+educated guess that is valid today. There are no guarrantees that an
+algorithm will remain unbreakable or that these values will remain
+constant in time. There could be scientific breakthroughs that cannot
+be predicted or total failure of the current public key systems by
+quantum computers. On the other hand though the cryptosystems used in
+TLS are selected in a conservative way and such catastrophic
+breakthroughs or failures are believed to be unlikely.
+
+NIST publication SP 800-57 @xcite{NISTSP80057} contains a similar
+table that extends beyond the key sizes given above.
+
+@multitable @columnfractions .15 .20 .20 .20
+
+@item Bits of security
+@tab Symmetric key algorithms
+@tab RSA key size, DSA, DH and SRP prime size
+@tab ECC key size
+
+@item 80
+@tab 2TDEA
+@tab 1024
+@tab 160-223
+
+@item 112
+@tab 3DES
+@tab 2048
+@tab 224-255
+
+@item 128
+@tab AES-128
+@tab 3072
+@tab 256-383
+
+@item 192
+@tab AES-192
+@tab 7680
+@tab 384-511
+
+@item 256
+@tab AES-256
+@tab 15360
+@tab 512+
+
+@end multitable
+
+The recommendations are fairly consistent.
+
+@node On SSL 2 and older protocols
+@section On SSL 2 and Older Protocols
+@cindex SSL 2
+
+One of the initial decisions in the @acronym{GnuTLS} development was
+to implement the known security protocols for the transport layer.
+Initially @acronym{TLS} 1.0 was implemented since it was the latest at
+that time, and was considered to be the most advanced in security
+properties.  Later the @acronym{SSL} 3.0 protocol was implemented
+since it is still the only protocol supported by several servers and
+there are no serious security vulnerabilities known.
+
+One question that may arise is why we didn't implement @acronym{SSL}
+2.0 in the library.  There are several reasons, most important being
+that it has serious security flaws, unacceptable for a modern security
+library.  Other than that, this protocol is barely used by anyone
+these days since it has been deprecated since 1996.  The security
+problems in @acronym{SSL} 2.0 include:
+
+@itemize
+
+@item Message integrity compromised.
+The @acronym{SSLv2} message authentication uses the MD5 function, and
+is insecure.
+
+@item Man-in-the-middle attack.
+There is no protection of the handshake in @acronym{SSLv2}, which
+permits a man-in-the-middle attack.
+
+@item Truncation attack.
+@acronym{SSLv2} relies on TCP FIN to close the session, so the
+attacker can forge a TCP FIN, and the peer cannot tell if it was a
+legitimate end of data or not.
+
+@item Weak message integrity for export ciphers.
+The cryptographic keys in @acronym{SSLv2} are used for both message
+authentication and encryption, so if weak encryption schemes are
+negotiated (say 40-bit keys) the message authentication code use the
+same weak key, which isn't necessary.
+
+@end itemize
+
+@cindex PCT
+Other protocols such as Microsoft's @acronym{PCT} 1 and @acronym{PCT}
+2 were not implemented because they were also abandoned and deprecated
+by @acronym{SSL} 3.0 and later @acronym{TLS} 1.0.
+
+@node On Record Padding
+@section On Record Padding
+@cindex Record padding
+@cindex Bad record MAC
+
+The TLS protocol allows for random padding of records, to make it more
+difficult to perform analysis on the length of exchanged messages.
+(In RFC 4346 this is specified in section 6.2.3.2.)  GnuTLS appears to
+be one of few implementation that take advantage of this text, and pad
+records by a random length.
+
+The TLS implementation in the Symbian operating system, frequently
+used by Nokia and Sony-Ericsson mobile phones, cannot handle
+non-minimal record padding.  What happens when one of these clients
+handshake with a GnuTLS server is that the client will fail to compute
+the correct MAC for the record.  The client sends a TLS alert
+(@code{bad_record_mac}) and disconnects.  Typically this will result
+in error messages such as 'A TLS fatal alert has been received', 'Bad
+record MAC', or both, on the GnuTLS server side.
+
+GnuTLS implements a work around for this problem.  However, it has to
+be enabled specifically.  It can be enabled by using
+@ref{gnutls_record_disable_padding}, or @ref{gnutls_priority_set} with
+the @code{%COMPAT} priority string.
+
+If you implement an application that have a configuration file, we
+recommend that you make it possible for users or administrators to
+specify a GnuTLS protocol priority string, which is used by your
+application via @ref{gnutls_priority_set}.  To allow the best
+flexibility, make it possible to have a different priority string for
+different incoming IP addresses.
+
+To enable the workaround in the @code{gnutls-cli} client or the
+@code{gnutls-serv} server, for testing of other implementations, use
+the following parameter: @code{--priority "%COMPAT"}.
+
+This problem has been discussed on mailing lists and in bug reports.
+This section tries to collect all pieces of information that we know
+about the problem.  If you wish to go back to the old discussions,
+here are some links:
+
+@url{http://bugs.debian.org/390712}
+
+@url{http://bugs.debian.org/402861}
+
+@url{http://bugs.debian.org/438137}
+
+@url{http://thread.gmane.org/gmane.ietf.tls/3079}
+
+@node Safe Renegotiation
+@section Safe Renegotiation
+@cindex renegotiation
+
+Some application protocols and implementations uses the TLS
+renegotiation feature in a manner that enables attackers to insert
+content of his choice in the beginning of a TLS session.
+
+One easy to understand vulnerability is HTTPS when servers request
+client certificates optionally for certain parts of a web site.  The
+attack works by having the attacker simulate a client and connect to a
+server, with server-only authentication, and send some data intended
+to cause harm.  When the proper client attempts to contact the server,
+the attacker hijacks that connection and uses the TLS renegotiation
+feature with the server and splices in the client connection to the
+already established connection between the attacker and server.  The
+attacker will not be able to read the data exchanged between the
+client and the server.  However, the server will (incorrectly) assume
+that the data sent by the attacker was sent by the now authenticated
+client.  The result is a prefix plain-text injection attack.
+
+The above is just one example.  Other vulnerabilities exists that do
+not rely on the TLS renegotiation to change the client's authenticated
+status (either TLS or application layer).
+
+While fixing these application protocols and implementations would be
+one natural reaction, an extension to TLS has been designed that
+cryptographically binds together any renegotiated handshakes with the
+initial negotiation.  When the extension is used, the attack is
+detected and the session can be terminated.  The extension is
+specified in @xcite{RFC5746}.
+
+GnuTLS supports the safe renegotiation extension.  The default
+behavior is as follows.  Clients will attempt to negotiate the safe
+renegotiation extension when talking to servers.  Servers will accept
+the extension when presented by clients.  Clients and servers will
+permit an initial handshake to complete even when the other side does
+not support the safe renegotiation extension.  Clients and servers
+will refuse renegotiation attempts when the extension has not been
+negotiated.
+
+Note that permitting clients to connect to servers even when the safe
+renegotiation extension is not negotiated open up for some attacks.
+Changing this default behaviour would prevent interoperability against
+the majority of deployed servers out there.  We will reconsider this
+default behaviour in the future when more servers have been upgraded.
+Note that it is easy to configure clients to always require the safe
+renegotiation extension from servers (see below on the
+%SAFE_RENEGOTIATION priority string).
+
+
+To modify the default behaviour, we have introduced some new priority
+strings.  The priority strings can be used by applications
+(@pxref{gnutls_priority_set}) and end users (e.g., @code{--priority}
+parameter to @code{gnutls-cli} and @code{gnutls-serv}).
+
+The @code{%UNSAFE_RENEGOTIATION} priority string permits
+(re-)handshakes even when the safe renegotiation extension was not
+negotiated.  The @code{%SAFE_RENEGOTIATION} priority string makes
+client require the extension for every handshake and servers will refuse
+renegotiation without it.
+
+To enforce your clients to upgrade to a version that supports safe
+renegotiation the %INITIAL_SAFE_RENEGOTIATION priority string should
+be used at server side.  This will deny any (re-)handshakes unless the
+client supports the extension.  This however will prevent all clients
+that do not support the extension from connecting to server, even if
+they do not use renegotiation.
+
+It is possible to disable use of the extension completely, in both
+clients and servers, by using the @code{%DISABLE_SAFE_RENEGOTIATION}
+priority string however we strongly recommend you to only do this for
+debugging and test purposes.
+
+The default values if the flags above are not specified are:
+@table @code
+
+@item Server:
+%SAFE_RENEGOTIATION
+
+@item Client:
+%UNSAFE_RENEGOTIATION
+
+@end table
+
+For applications we have introduced a new API related to safe
+renegotiation.  The @ref{gnutls_safe_renegotiation_status} function is
+used to check if the extension has been negotiated on a session, and
+can be used both by clients and servers.
diff --git a/doc/cha-library.texi b/doc/cha-library.texi
new file mode 100644
index 0000000000..9213ea69d7
--- /dev/null
+++ b/doc/cha-library.texi
@@ -0,0 +1,188 @@
+@node The Library
+@chapter The Library
+
+In brief @acronym{GnuTLS} can be described as a library which offers an API
+to access secure communication protocols. These protocols provide
+privacy over insecure lines, and were designed to prevent
+eavesdropping, tampering, or message forgery.
+
+Technically @acronym{GnuTLS} is a portable ANSI C based library which
+implements the TLS 1.1 and SSL 3.0 protocols (@xref{Introduction to
+TLS}, for a more detailed description of the protocols), accompanied
+with the required framework for authentication and public key
+infrastructure.  Important features of the @acronym{GnuTLS} library
+include:
+
+@itemize
+
+@item Support for TLS 1.0, TLS 1.1, and SSL 3.0 protocols.
+
+@item Support for both @acronym{X.509} and @acronym{OpenPGP} certificates.
+
+@item Support for handling and verification of certificates.
+
+@item Support for @acronym{SRP} for TLS authentication.
+
+@item Support for @acronym{PSK} for TLS authentication.
+
+@item Support for TLS Extension mechanism.
+
+@item Support for TLS Compression Methods.
+
+@end itemize
+
+Additionally @acronym{GnuTLS} provides a limited emulation API for the
+widely used OpenSSL@footnote{@url{http://www.openssl.org/}} library,
+to ease integration with existing applications.
+
+@acronym{GnuTLS} consists of three independent parts, namely the ``TLS
+protocol part'', the ``Certificate part'', and the ``Cryptographic
+backend'' part.  The `TLS protocol part' is the actual protocol
+implementation, and is entirely implemented within the
+@acronym{GnuTLS} library.  The `Certificate part' consists of the
+certificate parsing, and verification functions which is partially
+implemented in the @acronym{GnuTLS} library.  The
+@acronym{Libtasn1}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/libtasn1/}},
+a library which offers @acronym{ASN.1} parsing capabilities, is used
+for the @acronym{X.509} certificate parsing functions.  A smaller
+version of
+@acronym{OpenCDK}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/opencdk/}}
+is used for the @acronym{OpenPGP} key support in @acronym{GnuTLS}.
+The ``Cryptographic backend'' is provided by the
+@acronym{Libgcrypt}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/}}
+library@footnote{On current versions of GnuTLS it is possible to
+override the default crypto backend. Check @pxref{Cryptographic
+Backend} for details}.
+
+In order to ease integration in embedded systems, parts of the
+@acronym{GnuTLS} library can be disabled at compile time. That way a
+small library, with the required features, can be generated.
+
+@menu
+* General Idea::
+* Error handling::
+* Memory handling::
+* Callback functions::
+@end menu
+
+@node General Idea
+@section General Idea
+
+A brief description of how @acronym{GnuTLS} works internally is shown
+at the figure below. This section may be easier to understand after
+having seen the examples (@pxref{examples}).
+
+@image{gnutls-internals,12cm,8cm}
+
+As shown in the figure, there is a read-only global state that is
+initialized once by the global initialization function.  This global
+structure, among others, contains the memory allocation functions
+used, and some structures needed for the @acronym{ASN.1} parser.  This
+structure is never modified by any @acronym{GnuTLS} function, except
+for the deinitialization function which frees all memory allocated in
+the global structure and is called after the program has permanently
+finished using @acronym{GnuTLS}.
+
+The credentials structure is used by some authentication methods, such
+as certificate authentication (@pxref{Certificate Authentication}).  A
+credentials structure may contain certificates, private keys,
+temporary parameters for Diffie-Hellman or RSA key exchange, and other
+stuff that may be shared between several TLS sessions.
+
+This structure should be initialized using the appropriate
+initialization functions. For example an application which uses
+certificate authentication would probably initialize the credentials,
+using the appropriate functions, and put its trusted certificates in
+this structure. The next step is to associate the credentials
+structure with each @acronym{TLS} session.
+
+A @acronym{GnuTLS} session contains all the required stuff for a
+session to handle one secure connection. This session calls directly
+to the transport layer functions, in order to communicate with the
+peer.  Every session has a unique session ID shared with the peer.
+
+Since TLS sessions can be resumed, servers would probably need a
+database backend to hold the session's parameters.  Every
+@acronym{GnuTLS} session after a successful handshake calls the
+appropriate backend function (@xref{resume}, for information on
+initialization) to store the newly negotiated session. The session
+database is examined by the server just after having received the
+client hello@footnote{The first message in a @acronym{TLS} handshake},
+and if the session ID sent by the client, matches a stored session,
+the stored session will be retrieved, and the new session will be a
+resumed one, and will share the same session ID with the previous one.
+
+@node Error handling
+@section Error Handling
+
+In @acronym{GnuTLS} most functions return an integer type as a result.
+In almost all cases a zero or a positive number means success, and a
+negative number indicates failure, or a situation that some action has
+to be taken. Thus negative error codes may be fatal or not.
+
+Fatal errors terminate the connection immediately and further sends
+and receives will be disallowed. An example of a fatal error code is
+@code{GNUTLS_E_DECRYPTION_FAILED}. Non-fatal errors may warn about
+something, i.e., a warning alert was received, or indicate the some
+action has to be taken. This is the case with the error code
+@code{GNUTLS_E_REHANDSHAKE} returned by @ref{gnutls_record_recv}.
+This error code indicates that the server requests a re-handshake. The
+client may ignore this request, or may reply with an alert.  You can
+test if an error code is a fatal one by using the
+@ref{gnutls_error_is_fatal}.
+
+If any non fatal errors, that require an action, are to be returned by
+a function, these error codes will be documented in the function's
+reference.  @xref{Error Codes}, for all the error codes.
+
+@node Memory handling
+@section Memory Handling
+
+@acronym{GnuTLS} internally handles heap allocated objects
+differently, depending on the sensitivity of the data they
+contain. However for performance reasons, the default memory functions
+do not overwrite sensitive data from memory, nor protect such objects
+from being written to the swap.  In order to change the default
+behavior the @ref{gnutls_global_set_mem_functions} function is
+available which can be used to set other memory handlers than the
+defaults.
+
+The @acronym{Libgcrypt} library on which @acronym{GnuTLS} depends, has
+such secure memory allocation functions available. These should be
+used in cases where even the system's swap memory is not considered
+secure. See the documentation of @acronym{Libgcrypt} for more
+information.
+
+@node Callback functions
+@section Callback Functions
+@cindex Callback functions
+
+There are several cases where @acronym{GnuTLS} may need some out of
+band input from your program. This is now implemented using some
+callback functions, which your program is expected to register.
+
+An example of this type of functions are the push and pull callbacks
+which are used to specify the functions that will retrieve and send
+data to the transport layer.
+
+@itemize
+
+@item @ref{gnutls_transport_set_push_function}
+
+@item @ref{gnutls_transport_set_pull_function}
+
+@end itemize
+
+Other callback functions such as the one set by
+@ref{gnutls_srp_set_server_credentials_function}, may require more
+complicated input, including data to be allocated.  These callbacks
+should allocate and free memory using the functions shown below.
+
+@itemize
+
+@item @ref{gnutls_malloc}
+
+@item @ref{gnutls_free}
+
+@end itemize
+
diff --git a/doc/cha-preface.texi b/doc/cha-preface.texi
new file mode 100644
index 0000000000..1c4058bf45
--- /dev/null
+++ b/doc/cha-preface.texi
@@ -0,0 +1,257 @@
+@node Preface
+@chapter Preface
+
+This document tries to demonstrate and explain the @acronym{GnuTLS}
+library API.  A brief introduction to the protocols and the technology
+involved, is also included so that an application programmer can
+better understand the @acronym{GnuTLS} purpose and actual offerings.
+Even if @acronym{GnuTLS} is a typical library software, it operates
+over several security and cryptographic protocols, which require the
+programmer to make careful and correct usage of them, otherwise he
+risks to offer just a false sense of security. Security and the
+network security terms are very general terms even for computer
+software thus cannot be easily restricted to a single cryptographic
+library.  For that reason, do not consider a program secure just
+because it uses @acronym{GnuTLS}; there are several ways to compromise
+a program or a communication line and @acronym{GnuTLS} only helps with
+some of them.
+
+Although this document tries to be self contained, basic network
+programming and PKI knowlegde is assumed in most of it. A good
+introduction to networking can be found in @xcite{STEVENS} and for
+Public Key Infrastructure in @xcite{GUTPKI}.
+
+@anchor{Availability}
+
+Updated versions of the @acronym{GnuTLS} software and this document
+will be available from @url{http://www.gnutls.org/} and
+@url{http://www.gnu.org/software/gnutls/}.
+
+@menu
+* Getting help::
+* Commercial Support::
+* Downloading and Installing::
+* Bug Reports::
+* Contributing::
+@end menu
+
+@node Getting help
+@section Getting Help
+
+A mailing list where users may help each other exists, and you can
+reach it by sending e-mail to @email{help-gnutls@@gnu.org}.  Archives
+of the mailing list discussions, and an interface to manage
+subscriptions, is available through the World Wide Web at
+@url{http://lists.gnu.org/mailman/listinfo/help-gnutls}.
+
+A mailing list for developers are also available, see
+@url{http://www.gnu.org/software/gnutls/lists.html}.
+
+Bug reports should be sent to @email{bug-gnutls@@gnu.org}, see
+@xref{Bug Reports}.
+
+@node Commercial Support
+@section Commercial Support
+
+Commercial support is available for users of GnuTLS.  The kind of
+support that can be purchased may include:
+
+@itemize
+
+@item Implement new features.
+Such as a new TLS extension.
+
+@item Port GnuTLS to new platforms.
+This could include porting to an embedded platforms that may need
+memory or size optimization.
+
+@item Integrating TLS as a security environment in your existing project.
+
+@item System design of components related to TLS.
+
+@end itemize
+
+If you are interested, please write to:
+
+@verbatim
+Simon Josefsson Datakonsult
+Hagagatan 24
+113 47 Stockholm
+Sweden
+
+E-mail: simon@josefsson.org
+@end verbatim
+
+If your company provides support related to GnuTLS and would like to
+be mentioned here, contact the author (@pxref{Bug Reports}).
+
+@node Downloading and Installing
+@section Downloading and Installing
+@cindex Installation
+@cindex Download
+
+GnuTLS is available for download from the following URL:
+
+@url{http://www.gnutls.org/download.html}
+
+The latest version is stored in a file, e.g.,
+@samp{gnutls-@value{VERSION}.tar.gz} where the @samp{@value{VERSION}}
+value is the highest version number in the directory.
+
+GnuTLS uses a Linux-like development cycle: even minor version numbers
+indicate a stable release and a odd minor version number indicates a
+development release.  For example, GnuTLS 1.6.3 denote a stable
+release since 6 is even, and GnuTLS 1.7.11 denote a development
+release since 7 is odd.
+
+GnuTLS depends on Libgcrypt,
+and you will need to install Libgcrypt
+before installing GnuTLS.  Libgcrypt is available from
+@url{ftp://ftp.gnupg.org/gcrypt/libgcrypt}.  Libgcrypt needs another
+library, libgpg-error, and you need to install libgpg-error before
+installing Libgcrypt.  Libgpg-error is available from
+@url{ftp://ftp.gnupg.org/gcrypt/libgpg-error}.
+
+Don't forget to verify the cryptographic signature after downloading
+source code packages.
+
+The package is then extracted, configured and built like many other
+packages that use Autoconf.  For detailed information on configuring
+and building it, refer to the @file{INSTALL} file that is part of the
+distribution archive.  Typically you invoke @code{./configure} and
+then @code{make check install}.  There are a number of compile-time
+parameters, as discussed below.
+
+The compression libraries (libz and lzo) are optional dependencies.
+You can get libz from @url{http://www.zlib.net/}.  You can get lzo
+from @url{http://www.oberhumer.com/opensource/lzo/}.
+
+The X.509 part of GnuTLS needs ASN.1 functionality, from a library
+called libtasn1.  A copy of libtasn1 is included in GnuTLS.  If you
+want to install it separately (e.g., to make it possibly to use
+libtasn1 in other programs), you can get it from
+@url{http://www.gnu.org/software/gnutls/download.html}.
+
+The OpenPGP part of GnuTLS uses a stripped down version of OpenCDK for
+parsing OpenPGP packets.  It is included GnuTLS.  Use parameter
+@code{--disable-openpgp-authentication} to disable the OpenPGP
+functionality in GnuTLS.  Unfortunately, we didn't have resources to
+maintain the code in a separate library.
+
+Regarding the Guile bindings, there are additional installation
+considerations, see @xref{Guile Preparations}.
+
+A few @code{configure} options may be relevant, summarized in the
+table.
+
+@table @code
+
+@item --disable-srp-authentication
+@itemx --disable-psk-authentication
+@itemx --disable-anon-authentication
+@itemx --disable-extra-pki
+@itemx --disable-openpgp-authentication
+@itemx --disable-openssl-compatibility
+Disable or enable particular features.  Generally not recommended.
+
+@end table
+
+For the complete list, refer to the output from @code{configure
+--help}.
+
+@node Bug Reports
+@section Bug Reports
+@cindex Reporting Bugs
+
+If you think you have found a bug in GnuTLS, please investigate it and
+report it.
+
+@itemize @bullet
+
+@item Please make sure that the bug is really in GnuTLS, and
+preferably also check that it hasn't already been fixed in the latest
+version.
+
+@item You have to send us a test case that makes it possible for us to
+reproduce the bug.
+
+@item You also have to explain what is wrong; if you get a crash, or
+if the results printed are not good and in that case, in what way.
+Make sure that the bug report includes all information you would need
+to fix this kind of bug for someone else.
+
+@end itemize
+
+Please make an effort to produce a self-contained report, with
+something definite that can be tested or debugged.  Vague queries or
+piecemeal messages are difficult to act on and don't help the
+development effort.
+
+If your bug report is good, we will do our best to help you to get a
+corrected version of the software; if the bug report is poor, we won't
+do anything about it (apart from asking you to send better bug
+reports).
+
+If you think something in this manual is unclear, or downright
+incorrect, or if the language needs to be improved, please also send a
+note.
+
+Send your bug report to:
+
+@center @samp{bug-gnutls@@gnu.org}
+
+@node Contributing
+@section Contributing
+@cindex Contributing
+@cindex Hacking
+
+If you want to submit a patch for inclusion -- from solve a typo you
+discovered, up to adding support for a new feature -- you should
+submit it as a bug report (@pxref{Bug Reports}).  There are some
+things that you can do to increase the chances for it to be included
+in the official package.
+
+Unless your patch is very small (say, under 10 lines) we require that
+you assign the copyright of your work to the Free Software Foundation.
+This is to protect the freedom of the project.  If you have not
+already signed papers, we will send you the necessary information when
+you submit your contribution.
+
+For contributions that doesn't consist of actual programming code, the
+only guidelines are common sense.  Use it.
+
+For code contributions, a number of style guides will help you:
+
+@itemize @bullet
+
+@item Coding Style.
+Follow the GNU Standards document (@pxref{top, GNU Coding Standards,,
+standards}).
+
+If you normally code using another coding standard, there is no
+problem, but you should use @samp{indent} to reformat the code
+(@pxref{top, GNU Indent,, indent}) before submitting your work.
+
+@item Use the unified diff format @samp{diff -u}.
+
+@item Return errors.
+No reason whatsoever should abort the execution of the library.  Even
+memory allocation errors, e.g. when malloc return NULL, should work
+although result in an error code.
+
+@item Design with thread safety in mind.
+Don't use global variables.  Don't even write to per-handle global
+variables unless the documented behaviour of the function you write is
+to write to the per-handle global variable.
+
+@item Avoid using the C math library.
+It causes problems for embedded implementations, and in most
+situations it is very easy to avoid using it.
+
+@item Document your functions.
+Use comments before each function headers, that, if properly
+formatted, are extracted into Texinfo manuals and GTK-DOC web pages.
+
+@item Supply a ChangeLog and NEWS entries, where appropriate.
+
+@end itemize
diff --git a/doc/cha-programs.texi b/doc/cha-programs.texi
new file mode 100644
index 0000000000..c1b940ca13
--- /dev/null
+++ b/doc/cha-programs.texi
@@ -0,0 +1,853 @@
+@node Included programs
+@chapter 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::
+@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.
+
+@verbatim
+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-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-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.
+     -l, --crl-info           Print information on a CRL.
+     --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.
+     --fix-key                Regenerate the parameters in a private
+                              key.
+     --to-p12                 Generate a PKCS #12 structure.
+     -8, --pkcs8              Use PKCS #8 format for private keys.
+     --dsa                    Use DSA keys.
+     --hash STR               Hash algorithm to use for signing
+                              (MD5,SHA1,RMD160).
+     --export-ciphers         Use weak encryption algorithms.
+     --inder                  Use DER format for input certificates
+                              and private keys.
+     --outder                 Use DER format for output certificates
+                              and private keys.
+     --bits BITS              specify the number of bits for key
+                              generation.
+     --outfile FILE           Output file.
+     --infile FILE            Input file.
+     --template FILE          Template file to use for non
+                              interactive operation.
+     -d, --debug LEVEL        specify the debug level. Default is 1.
+     -h, --help               shows this help text
+     -v, --version            shows the program's version
+@end verbatim
+
+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.
+
+How to use certtool interactively:
+
+@itemize
+@item
+To generate parameters for Diffie-Hellman key exchange, use the command:
+@example
+$ certtool --generate-dh-params --outfile dh.pem
+@end example
+
+@item
+To generate parameters for the RSA-EXPORT key exchange, use the command:
+@example
+$ certtool --generate-privkey --bits 512 --outfile rsa.pem
+@end example
+
+@end itemize
+
+@itemize
+
+@item
+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.
+
+@item
+To create a private key (RSA by default), run:
+
+@example
+$ certtool --generate-privkey --outfile key.pem
+@end example
+
+To create a DSA private key, run:
+
+@example
+$ certtool --dsa --generate-privkey --outfile key-dsa.pem
+@end example
+
+@item
+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
+
+@item
+To create a certificate request (needed when the certificate is issued by
+another party), run:
+
+@example
+$ certtool --generate-request --load-privkey key.pem \
+  --outfile request.pem
+@end example
+
+@item
+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
+
+@item
+To view the certificate information, use:
+
+@example
+$ certtool --certificate-info --infile cert.pem
+@end example
+
+@item
+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
+@samp{--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
+
+@item
+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
+
+@item
+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
+
+@item
+To verify a Certificate Revocation List (CRL) do:
+
+@example
+$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
+@end example
+
+@end itemize
+
+Certtool's template file format:
+
+@itemize
+
+@item
+Firstly create a file named 'cert.cfg' that contains the information
+about the certificate. An example file is listed below.
+
+@item
+Then execute:
+
+@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
+
+@end itemize
+
+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
+@end example
+
+@node Invoking gnutls-cli
+@section Invoking gnutls-cli
+@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.
+
+@verbatim
+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 verbatim
+
+To connect to a server using PSK authentication, you may use something
+like:
+
+@smallexample
+$ gnutls-cli -p 5556 test.gnutls.org --pskusername jas --pskkey 9e32cf7786321a828ef7668f09fb35db --priority NORMAL:+PSK:-RSA:-DHE-RSA -d 4711
+@end smallexample
+
+@menu
+* Example client PSK connection::
+@end menu
+
+@node Example client PSK connection
+@subsection Example client PSK connection
+@cindex PSK client
+
+If your server only supports the PSK ciphersuite, connecting to it
+should be as simple as connecting to the server:
+
+@smallexample
+$ ./gnutls-cli -p 5556 localhost
+Resolving 'localhost'...
+Connecting to '127.0.0.1:5556'...
+- PSK client callback. PSK hint 'psk_identity_hint'
+Enter PSK identity: psk_identity
+Enter password: 
+- PSK authentication. PSK hint 'psk_identity_hint'
+- Version: TLS1.1
+- Key Exchange: PSK
+- Cipher: AES-128-CBC
+- MAC: SHA1
+- Compression: NULL
+- Handshake was completed
+
+- Simple Client Mode:
+@end smallexample
+
+If the server supports several cipher suites, you may need to force it
+to chose PSK by using a cipher priority parameter such as
+@code{--priority NORMAL:+PSK:-RSA:-DHE-RSA:-DHE-PSK}.
+
+@cindex Netconf
+Instead of using the Netconf-way to derive the PSK key from a
+password, you can also give the PSK username and key directly on the
+command line:
+
+@smallexample
+$ ./gnutls-cli -p 5556 localhost --pskusername psk_identity --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 
+Resolving 'localhost'...
+Connecting to '127.0.0.1:5556'...
+- PSK authentication. PSK hint 'psk_identity_hint'
+- Version: TLS1.1
+- Key Exchange: PSK
+- Cipher: AES-128-CBC
+- MAC: SHA1
+- Compression: NULL
+- Handshake was completed
+
+- Simple Client Mode:
+@end smallexample
+
+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 a more checks will be performed. An example output is:
+
+@smallexample
+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 whether the server can accept a bogus TLS record version in the client hello... 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 LZO compression support (GnuTLS 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 smallexample
+
+@node Invoking gnutls-serv
+@section Invoking gnutls-serv
+@cindex gnutls-serv
+
+Simple server program that listens to incoming TLS connections.
+
+@verbatim
+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 verbatim
+
+@subsection 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.
+
+@example
+srptool --create-conf srp-tpasswd.conf
+srptool --passwd-conf srp-tpasswd.conf --username jas --passwd srp-passwd.txt
+Enter password: [TYPE "foo"]
+@end example
+
+Start the server with SRP support:
+
+@example
+gnutls-serv --http \
+            --srppasswdconf srp-tpasswd.conf \
+            --srppasswd srp-passwd.txt
+@end example
+
+Let's also add support for PSK.
+
+@example
+$ psktool --passwd psk-passwd.txt
+@end example
+
+Start the server with PSK support:
+
+@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
+
+@menu
+* Example server PSK connection::
+@end menu
+
+@node Example server PSK connection
+@subsection Example server PSK connection
+@cindex PSK server
+
+To set up a PSK server with @code{gnutls-serv} you need to create PSK
+password file (@pxref{Invoking psktool}).  In the example below, I
+type @code{password} at the prompt.
+
+@smallexample
+$ ./psktool -u psk_identity -p psks.txt -n psk_identity_hint
+Enter password:
+Key stored to psks.txt
+$ cat psks.txt
+psk_identity:88f3824b3e5659f52d00e959bacab954b6540344
+$
+@end smallexample
+
+After this, start the server pointing to the password file.  We
+disable DHE-PSK.
+
+@smallexample
+$ ./gnutls-serv --pskpasswd psks.txt  --pskhint psk_identity_hint --priority NORMAL:-DHE-PSK
+Set static Diffie-Hellman parameters, consider --dhparams.
+Echo Server ready. Listening to port '5556'.
+@end smallexample
+
+You can now connect to the server using a PSK client (@pxref{Example
+client PSK connection}).
+
+@node Invoking psktool
+@section Invoking psktool
+@cindex psktool
+
+This is a program to manage @acronym{PSK} username and keys.
+
+@verbatim
+PSKtool help
+Usage : psktool [options]
+     -u, --username username
+                              specify username.
+     -p, --passwd FILE        specify a password file.
+     -n, --netconf-hint HINT
+                              derive key from Netconf password, using 
+                              HINT as the psk_identity_hint.
+     -s, --keysize SIZE       specify the key size in bytes.
+     -v, --version            prints the program's version number
+     -h, --help               shows this help text
+@end verbatim
+
+Normally the file will generate random keys for the indicate username.
+You may also derive PSK keys from passwords, using the algorithm
+specified in @file{draft-ietf-netconf-tls-02.txt}.  The algorithm
+needs a PSK identity hint, which you specify using
+@code{--netconf-hint}.  To derive a PSK key from a password with an
+empty PSK identity hint, using @code{--netconf-hint ""}.
+
+@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}, 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.
+
+How to use srptool:
+
+@itemize
+
+@item
+To create tpasswd.conf which holds the g and n values for
+@acronym{SRP} protocol (generator and a large prime), run:
+
+@example
+$ srptool --create-conf /etc/tpasswd.conf
+@end example
+
+@item
+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.
+
+@example
+$ srptool --passwd /etc/tpasswd \
+    --passwd-conf /etc/tpasswd.conf -u test
+@end example
+
+@item
+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
+
+@end itemize
diff --git a/doc/cha-tls-app.texi b/doc/cha-tls-app.texi
new file mode 100644
index 0000000000..a34d891a93
--- /dev/null
+++ b/doc/cha-tls-app.texi
@@ -0,0 +1,130 @@
+@node How to use TLS in application protocols
+@chapter How To Use @acronym{TLS} in Application Protocols
+
+This chapter is intended to provide some hints on how to use the
+@acronym{TLS} over simple custom made application protocols.  The
+discussion below mainly refers to the @emph{TCP/IP} transport layer
+but may be extended to other ones too.
+
+@menu
+* Separate ports::
+* Upward negotiation::
+@end menu
+
+@node Separate ports
+@section Separate Ports
+
+Traditionally @acronym{SSL} was used in application protocols by
+assigning a new port number for the secure services. That way two
+separate ports were assigned, one for the non secure sessions, and one
+for the secured ones. This has the benefit that if a user requests a
+secure session then the client will try to connect to the secure port
+and fail otherwise. The only possible attack with this method is a
+denial of service one. The most famous example of this method is the
+famous ``HTTP over TLS'' or @acronym{HTTPS} protocol @xcite{RFC2818}.
+
+Despite its wide use, this method is not as good as it seems.  This
+approach starts the @acronym{TLS} Handshake procedure just after the
+client connects on the ---so called--- secure port.  That way the
+@acronym{TLS} protocol does not know anything about the client, and
+popular methods like the host advertising in HTTP do not
+work@footnote{See also the Server Name Indication extension on
+@ref{serverind}.}.  There is no way for the client to say ``I
+connected to YYY server'' before the Handshake starts, so the server
+cannot possibly know which certificate to use.
+
+Other than that it requires two separate ports to run a single
+service, which is unnecessary complication. Due to the fact that there
+is a limitation on the available privileged ports, this approach was
+soon obsoleted.
+
+@node Upward negotiation
+@section Upward Negotiation
+
+Other application protocols@footnote{See LDAP, IMAP etc.}  use a
+different approach to enable the secure layer.  They use something
+called the ``TLS upgrade'' method. This method is quite tricky but it
+is more flexible. The idea is to extend the application protocol to
+have a ``STARTTLS'' request, whose purpose it to start the TLS
+protocols just after the client requests it.  This is a really neat
+idea and does not require an extra port.
+
+This method is used by almost all modern protocols and there is even
+the @xcite{RFC2817} paper which proposes extensions to HTTP to support
+it.
+
+The tricky part, in this method, is that the ``STARTTLS'' request is
+sent in the clear, thus is vulnerable to modifications.  A typical
+attack is to modify the messages in a way that the client is fooled
+and thinks that the server does not have the ``STARTTLS'' capability.
+See a typical conversation of a hypothetical protocol:
+
+@quotation
+(client connects to the server)
+
+CLIENT: HELLO I'M MR. XXX
+
+SERVER: NICE TO MEET YOU XXX
+
+CLIENT: PLEASE START TLS
+
+SERVER: OK
+
+*** TLS STARTS
+
+CLIENT: HERE ARE SOME CONFIDENTIAL DATA
+@end quotation
+
+And see an example of a conversation where someone is acting
+in between:
+
+@quotation
+(client connects to the server)
+
+CLIENT: HELLO I'M MR. XXX
+
+SERVER: NICE TO MEET YOU XXX
+
+CLIENT: PLEASE START TLS
+
+(here someone inserts this message)
+
+SERVER: SORRY I DON'T HAVE THIS CAPABILITY
+
+CLIENT: HERE ARE SOME CONFIDENTIAL DATA
+@end quotation
+
+As you can see above the client was fooled, and was dummy enough to
+send the confidential data in the clear.
+
+How to avoid the above attack? As you may have already thought this
+one is easy to avoid. The client has to ask the user before it
+connects whether the user requests @acronym{TLS} or not. If the user
+answered that he certainly wants the secure layer the last
+conversation should be:
+
+@quotation
+(client connects to the server)
+
+CLIENT: HELLO I'M MR. XXX
+
+SERVER: NICE TO MEET YOU XXX
+
+CLIENT: PLEASE START TLS
+
+(here someone inserts this message)
+
+SERVER: SORRY I DON'T HAVE THIS CAPABILITY
+
+CLIENT: BYE
+
+(the client notifies the user that the secure connection was not possible)
+@end quotation
+
+This method, if implemented properly, is far better than the
+traditional method, and the security properties remain the same, since
+only denial of service is possible. The benefit is that the server may
+request additional data before the @acronym{TLS} Handshake protocol
+starts, in order to send the correct certificate, use the correct
+password file@footnote{in @acronym{SRP} authentication}, or anything
+else!
diff --git a/doc/gnutls.texi b/doc/gnutls.texi
index 84cc674447..bbecd1f8bf 100644
--- a/doc/gnutls.texi
+++ b/doc/gnutls.texi
@@ -90,4286 +90,29 @@ Documentation License''.
 * Bibliography::
 @end menu
 
+@include cha-preface.texi
 
-@node Preface
-@chapter Preface
+@include cha-library.texi
 
-This document tries to demonstrate and explain the @acronym{GnuTLS}
-library API.  A brief introduction to the protocols and the technology
-involved, is also included so that an application programmer can
-better understand the @acronym{GnuTLS} purpose and actual offerings.
-Even if @acronym{GnuTLS} is a typical library software, it operates
-over several security and cryptographic protocols, which require the
-programmer to make careful and correct usage of them, otherwise he
-risks to offer just a false sense of security. Security and the
-network security terms are very general terms even for computer
-software thus cannot be easily restricted to a single cryptographic
-library.  For that reason, do not consider a program secure just
-because it uses @acronym{GnuTLS}; there are several ways to compromise
-a program or a communication line and @acronym{GnuTLS} only helps with
-some of them.
+@include cha-intro-tls.texi
 
-Although this document tries to be self contained, basic network
-programming and PKI knowlegde is assumed in most of it. A good
-introduction to networking can be found in @xcite{STEVENS} and for
-Public Key Infrastructure in @xcite{GUTPKI}.
+@include cha-auth.texi
 
-@anchor{Availability}
+@include cha-cert-auth.texi
 
-Updated versions of the @acronym{GnuTLS} software and this document
-will be available from @url{http://www.gnutls.org/} and
-@url{http://www.gnu.org/software/gnutls/}.
+@include cha-tls-app.texi
 
-@menu
-* Getting help::
-* Commercial Support::
-* Downloading and Installing::
-* Bug Reports::
-* Contributing::
-@end menu
-
-@node Getting help
-@section Getting Help
-
-A mailing list where users may help each other exists, and you can
-reach it by sending e-mail to @email{help-gnutls@@gnu.org}.  Archives
-of the mailing list discussions, and an interface to manage
-subscriptions, is available through the World Wide Web at
-@url{http://lists.gnu.org/mailman/listinfo/help-gnutls}.
-
-A mailing list for developers are also available, see
-@url{http://www.gnu.org/software/gnutls/lists.html}.
-
-Bug reports should be sent to @email{bug-gnutls@@gnu.org}, see
-@xref{Bug Reports}.
-
-@node Commercial Support
-@section Commercial Support
-
-Commercial support is available for users of GnuTLS.  The kind of
-support that can be purchased may include:
-
-@itemize
-
-@item Implement new features.
-Such as a new TLS extension.
-
-@item Port GnuTLS to new platforms.
-This could include porting to an embedded platforms that may need
-memory or size optimization.
-
-@item Integrating TLS as a security environment in your existing project.
-
-@item System design of components related to TLS.
-
-@end itemize
-
-If you are interested, please write to:
-
-@verbatim
-Simon Josefsson Datakonsult
-Hagagatan 24
-113 47 Stockholm
-Sweden
-
-E-mail: simon@josefsson.org
-@end verbatim
-
-If your company provides support related to GnuTLS and would like to
-be mentioned here, contact the author (@pxref{Bug Reports}).
-
-@node Downloading and Installing
-@section Downloading and Installing
-@cindex Installation
-@cindex Download
-
-GnuTLS is available for download from the following URL:
-
-@url{http://www.gnutls.org/download.html}
-
-The latest version is stored in a file, e.g.,
-@samp{gnutls-@value{VERSION}.tar.gz} where the @samp{@value{VERSION}}
-value is the highest version number in the directory.
-
-GnuTLS uses a Linux-like development cycle: even minor version numbers
-indicate a stable release and a odd minor version number indicates a
-development release.  For example, GnuTLS 1.6.3 denote a stable
-release since 6 is even, and GnuTLS 1.7.11 denote a development
-release since 7 is odd.
-
-GnuTLS depends on Libgcrypt,
-and you will need to install Libgcrypt
-before installing GnuTLS.  Libgcrypt is available from
-@url{ftp://ftp.gnupg.org/gcrypt/libgcrypt}.  Libgcrypt needs another
-library, libgpg-error, and you need to install libgpg-error before
-installing Libgcrypt.  Libgpg-error is available from
-@url{ftp://ftp.gnupg.org/gcrypt/libgpg-error}.
-
-Don't forget to verify the cryptographic signature after downloading
-source code packages.
-
-The package is then extracted, configured and built like many other
-packages that use Autoconf.  For detailed information on configuring
-and building it, refer to the @file{INSTALL} file that is part of the
-distribution archive.  Typically you invoke @code{./configure} and
-then @code{make check install}.  There are a number of compile-time
-parameters, as discussed below.
-
-The compression libraries (libz and lzo) are optional dependencies.
-You can get libz from @url{http://www.zlib.net/}.  You can get lzo
-from @url{http://www.oberhumer.com/opensource/lzo/}.
-
-The X.509 part of GnuTLS needs ASN.1 functionality, from a library
-called libtasn1.  A copy of libtasn1 is included in GnuTLS.  If you
-want to install it separately (e.g., to make it possibly to use
-libtasn1 in other programs), you can get it from
-@url{http://www.gnu.org/software/gnutls/download.html}.
-
-The OpenPGP part of GnuTLS uses a stripped down version of OpenCDK for
-parsing OpenPGP packets.  It is included GnuTLS.  Use parameter
-@code{--disable-openpgp-authentication} to disable the OpenPGP
-functionality in GnuTLS.  Unfortunately, we didn't have resources to
-maintain the code in a separate library.
-
-Regarding the Guile bindings, there are additional installation
-considerations, see @xref{Guile Preparations}.
-
-A few @code{configure} options may be relevant, summarized in the
-table.
-
-@table @code
-
-@item --disable-srp-authentication
-@itemx --disable-psk-authentication
-@itemx --disable-anon-authentication
-@itemx --disable-extra-pki
-@itemx --disable-openpgp-authentication
-@itemx --disable-openssl-compatibility
-Disable or enable particular features.  Generally not recommended.
-
-@end table
-
-For the complete list, refer to the output from @code{configure
---help}.
-
-@node Bug Reports
-@section Bug Reports
-@cindex Reporting Bugs
-
-If you think you have found a bug in GnuTLS, please investigate it and
-report it.
-
-@itemize @bullet
-
-@item Please make sure that the bug is really in GnuTLS, and
-preferably also check that it hasn't already been fixed in the latest
-version.
-
-@item You have to send us a test case that makes it possible for us to
-reproduce the bug.
-
-@item You also have to explain what is wrong; if you get a crash, or
-if the results printed are not good and in that case, in what way.
-Make sure that the bug report includes all information you would need
-to fix this kind of bug for someone else.
-
-@end itemize
-
-Please make an effort to produce a self-contained report, with
-something definite that can be tested or debugged.  Vague queries or
-piecemeal messages are difficult to act on and don't help the
-development effort.
-
-If your bug report is good, we will do our best to help you to get a
-corrected version of the software; if the bug report is poor, we won't
-do anything about it (apart from asking you to send better bug
-reports).
-
-If you think something in this manual is unclear, or downright
-incorrect, or if the language needs to be improved, please also send a
-note.
-
-Send your bug report to:
-
-@center @samp{bug-gnutls@@gnu.org}
-
-@node Contributing
-@section Contributing
-@cindex Contributing
-@cindex Hacking
-
-If you want to submit a patch for inclusion -- from solve a typo you
-discovered, up to adding support for a new feature -- you should
-submit it as a bug report (@pxref{Bug Reports}).  There are some
-things that you can do to increase the chances for it to be included
-in the official package.
-
-Unless your patch is very small (say, under 10 lines) we require that
-you assign the copyright of your work to the Free Software Foundation.
-This is to protect the freedom of the project.  If you have not
-already signed papers, we will send you the necessary information when
-you submit your contribution.
-
-For contributions that doesn't consist of actual programming code, the
-only guidelines are common sense.  Use it.
-
-For code contributions, a number of style guides will help you:
-
-@itemize @bullet
-
-@item Coding Style.
-Follow the GNU Standards document (@pxref{top, GNU Coding Standards,,
-standards}).
-
-If you normally code using another coding standard, there is no
-problem, but you should use @samp{indent} to reformat the code
-(@pxref{top, GNU Indent,, indent}) before submitting your work.
-
-@item Use the unified diff format @samp{diff -u}.
-
-@item Return errors.
-No reason whatsoever should abort the execution of the library.  Even
-memory allocation errors, e.g. when malloc return NULL, should work
-although result in an error code.
-
-@item Design with thread safety in mind.
-Don't use global variables.  Don't even write to per-handle global
-variables unless the documented behaviour of the function you write is
-to write to the per-handle global variable.
-
-@item Avoid using the C math library.
-It causes problems for embedded implementations, and in most
-situations it is very easy to avoid using it.
-
-@item Document your functions.
-Use comments before each function headers, that, if properly
-formatted, are extracted into Texinfo manuals and GTK-DOC web pages.
-
-@item Supply a ChangeLog and NEWS entries, where appropriate.
-
-@end itemize
-@node The Library
-@chapter The Library
-
-In brief @acronym{GnuTLS} can be described as a library which offers an API
-to access secure communication protocols. These protocols provide
-privacy over insecure lines, and were designed to prevent
-eavesdropping, tampering, or message forgery.
-
-Technically @acronym{GnuTLS} is a portable ANSI C based library which
-implements the TLS 1.1 and SSL 3.0 protocols (@xref{Introduction to
-TLS}, for a more detailed description of the protocols), accompanied
-with the required framework for authentication and public key
-infrastructure.  Important features of the @acronym{GnuTLS} library
-include:
-
-@itemize
-
-@item Support for TLS 1.0, TLS 1.1, and SSL 3.0 protocols.
-
-@item Support for both @acronym{X.509} and @acronym{OpenPGP} certificates.
-
-@item Support for handling and verification of certificates.
-
-@item Support for @acronym{SRP} for TLS authentication.
-
-@item Support for @acronym{PSK} for TLS authentication.
-
-@item Support for TLS Extension mechanism.
-
-@item Support for TLS Compression Methods.
-
-@end itemize
-
-Additionally @acronym{GnuTLS} provides a limited emulation API for the
-widely used OpenSSL@footnote{@url{http://www.openssl.org/}} library,
-to ease integration with existing applications.
-
-@acronym{GnuTLS} consists of three independent parts, namely the ``TLS
-protocol part'', the ``Certificate part'', and the ``Cryptographic
-backend'' part.  The `TLS protocol part' is the actual protocol
-implementation, and is entirely implemented within the
-@acronym{GnuTLS} library.  The `Certificate part' consists of the
-certificate parsing, and verification functions which is partially
-implemented in the @acronym{GnuTLS} library.  The
-@acronym{Libtasn1}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/libtasn1/}},
-a library which offers @acronym{ASN.1} parsing capabilities, is used
-for the @acronym{X.509} certificate parsing functions.  A smaller
-version of
-@acronym{OpenCDK}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/opencdk/}}
-is used for the @acronym{OpenPGP} key support in @acronym{GnuTLS}.
-The ``Cryptographic backend'' is provided by the
-@acronym{Libgcrypt}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/}}
-library@footnote{On current versions of GnuTLS it is possible to
-override the default crypto backend. Check @pxref{Cryptographic
-Backend} for details}.
-
-In order to ease integration in embedded systems, parts of the
-@acronym{GnuTLS} library can be disabled at compile time. That way a
-small library, with the required features, can be generated.
-
-@menu
-* General Idea::
-* Error handling::
-* Memory handling::
-* Callback functions::
-@end menu
-
-@node General Idea
-@section General Idea
-
-A brief description of how @acronym{GnuTLS} works internally is shown
-at the figure below. This section may be easier to understand after
-having seen the examples (@pxref{examples}).
-
-@image{gnutls-internals,12cm,8cm}
-
-As shown in the figure, there is a read-only global state that is
-initialized once by the global initialization function.  This global
-structure, among others, contains the memory allocation functions
-used, and some structures needed for the @acronym{ASN.1} parser.  This
-structure is never modified by any @acronym{GnuTLS} function, except
-for the deinitialization function which frees all memory allocated in
-the global structure and is called after the program has permanently
-finished using @acronym{GnuTLS}.
-
-The credentials structure is used by some authentication methods, such
-as certificate authentication (@pxref{Certificate Authentication}).  A
-credentials structure may contain certificates, private keys,
-temporary parameters for Diffie-Hellman or RSA key exchange, and other
-stuff that may be shared between several TLS sessions.
-
-This structure should be initialized using the appropriate
-initialization functions. For example an application which uses
-certificate authentication would probably initialize the credentials,
-using the appropriate functions, and put its trusted certificates in
-this structure. The next step is to associate the credentials
-structure with each @acronym{TLS} session.
-
-A @acronym{GnuTLS} session contains all the required stuff for a
-session to handle one secure connection. This session calls directly
-to the transport layer functions, in order to communicate with the
-peer.  Every session has a unique session ID shared with the peer.
-
-Since TLS sessions can be resumed, servers would probably need a
-database backend to hold the session's parameters.  Every
-@acronym{GnuTLS} session after a successful handshake calls the
-appropriate backend function (@xref{resume}, for information on
-initialization) to store the newly negotiated session. The session
-database is examined by the server just after having received the
-client hello@footnote{The first message in a @acronym{TLS} handshake},
-and if the session ID sent by the client, matches a stored session,
-the stored session will be retrieved, and the new session will be a
-resumed one, and will share the same session ID with the previous one.
-
-@node Error handling
-@section Error Handling
-
-In @acronym{GnuTLS} most functions return an integer type as a result.
-In almost all cases a zero or a positive number means success, and a
-negative number indicates failure, or a situation that some action has
-to be taken. Thus negative error codes may be fatal or not.
-
-Fatal errors terminate the connection immediately and further sends
-and receives will be disallowed. An example of a fatal error code is
-@code{GNUTLS_E_DECRYPTION_FAILED}. Non-fatal errors may warn about
-something, i.e., a warning alert was received, or indicate the some
-action has to be taken. This is the case with the error code
-@code{GNUTLS_E_REHANDSHAKE} returned by @ref{gnutls_record_recv}.
-This error code indicates that the server requests a re-handshake. The
-client may ignore this request, or may reply with an alert.  You can
-test if an error code is a fatal one by using the
-@ref{gnutls_error_is_fatal}.
-
-If any non fatal errors, that require an action, are to be returned by
-a function, these error codes will be documented in the function's
-reference.  @xref{Error Codes}, for all the error codes.
-
-@node Memory handling
-@section Memory Handling
-
-@acronym{GnuTLS} internally handles heap allocated objects
-differently, depending on the sensitivity of the data they
-contain. However for performance reasons, the default memory functions
-do not overwrite sensitive data from memory, nor protect such objects
-from being written to the swap.  In order to change the default
-behavior the @ref{gnutls_global_set_mem_functions} function is
-available which can be used to set other memory handlers than the
-defaults.
-
-The @acronym{Libgcrypt} library on which @acronym{GnuTLS} depends, has
-such secure memory allocation functions available. These should be
-used in cases where even the system's swap memory is not considered
-secure. See the documentation of @acronym{Libgcrypt} for more
-information.
-
-@node Callback functions
-@section Callback Functions
-@cindex Callback functions
-
-There are several cases where @acronym{GnuTLS} may need some out of
-band input from your program. This is now implemented using some
-callback functions, which your program is expected to register.
-
-An example of this type of functions are the push and pull callbacks
-which are used to specify the functions that will retrieve and send
-data to the transport layer.
-
-@itemize
-
-@item @ref{gnutls_transport_set_push_function}
-
-@item @ref{gnutls_transport_set_pull_function}
-
-@end itemize
-
-Other callback functions such as the one set by
-@ref{gnutls_srp_set_server_credentials_function}, may require more
-complicated input, including data to be allocated.  These callbacks
-should allocate and free memory using the functions shown below.
-
-@itemize
-
-@item @ref{gnutls_malloc}
-
-@item @ref{gnutls_free}
-
-@end itemize
-
-@node Introduction to TLS
-@chapter Introduction to @acronym{TLS}
-
-@acronym{TLS} stands for ``Transport Layer Security'' and is the
-successor of SSL, the Secure Sockets Layer protocol @xcite{SSL3}
-designed by Netscape.  @acronym{TLS} is an Internet protocol, defined
-by @acronym{IETF}@footnote{IETF, or Internet Engineering Task Force,
-is a large open international community of network designers,
-operators, vendors, and researchers concerned with the evolution of
-the Internet architecture and the smooth operation of the Internet.
-It is open to any interested individual.}, described in @acronym{RFC}
-4346 and also in @xcite{RESCORLA}.  The protocol provides
-confidentiality, and authentication layers over any reliable transport
-layer.  The description, below, refers to @acronym{TLS} 1.0 but also
-applies to @acronym{TLS} 1.1 @xcite{RFC4346} and @acronym{SSL} 3.0,
-since the differences of these protocols are minor.  Older protocols
-such as @acronym{SSL} 2.0 are not discussed nor implemented in
-@acronym{GnuTLS} since they are not considered secure today.  GnuTLS
-also supports @acronym{X.509} and @acronym{OpenPGP} @xcite{RFC4880}.
-
-@menu
-* TLS layers::
-* The transport layer::
-* The TLS record protocol::
-* The TLS Alert Protocol::
-* The TLS Handshake Protocol::
-* TLS Extensions::
-* Selecting cryptographic key sizes::
-* On SSL 2 and older protocols::
-* On Record Padding::
-* Safe Renegotiation::
-@end menu
-
-@node TLS layers
-@section TLS Layers
-@cindex TLS Layers
-
-@acronym{TLS} is a layered protocol, and consists of the Record
-Protocol, the Handshake Protocol and the Alert Protocol. The Record
-Protocol is to serve all other protocols and is above the transport
-layer.  The Record protocol offers symmetric encryption, data
-authenticity, and optionally compression.
-
-The Alert protocol offers some signaling to the other protocols. It
-can help informing the peer for the cause of failures and other error
-conditions.  @xref{The Alert Protocol}, for more information.  The
-alert protocol is above the record protocol.
-
-The Handshake protocol is responsible for the security parameters'
-negotiation, the initial key exchange and authentication.  @xref{The
-Handshake Protocol}, for more information about the handshake
-protocol.  The protocol layering in TLS is shown in the figure below.
-
-@image{gnutls-layers,12cm,8cm}
-
-@node The transport layer
-@section The Transport Layer
-@cindex Transport protocol
-
-@acronym{TLS} is not limited to one transport layer, it can be used
-above any transport layer, as long as it is a reliable one.  A set of
-functions is provided and their purpose is to load to @acronym{GnuTLS} the
-required callbacks to access the transport layer.
-
-@itemize
-@item @ref{gnutls_transport_set_push_function}
-@item @ref{gnutls_transport_set_pull_function}
-@item @ref{gnutls_transport_set_ptr}
-@item @ref{gnutls_transport_set_lowat}
-@item @ref{gnutls_transport_set_errno}
-@end itemize
-
-These functions accept a callback function as a parameter.  The
-callback functions should return the number of bytes written, or -1 on
-error and should set @code{errno} appropriately.
-
-In some environments, setting @code{errno} is unreliable, for example
-Windows have several errno variables in different CRTs, or it may be
-that errno is not a thread-local variable.  If this is a concern to
-you, call @code{gnutls_transport_set_errno} with the intended errno
-value instead of setting @code{errno} directly.
-
-@acronym{GnuTLS} currently only interprets the EINTR and EAGAIN errno
-values and returns the corresponding @acronym{GnuTLS} error codes
-@code{GNUTLS_E_INTERRUPTED} and @code{GNUTLS_E_AGAIN}.  These values
-are usually returned by interrupted system calls, or when non blocking
-IO is used.  All @acronym{GnuTLS} functions can be resumed (called
-again), if any of these error codes is returned.  The error codes
-above refer to the system call, not the @acronym{GnuTLS} function,
-since signals do not interrupt @acronym{GnuTLS}' functions.
-
-For non blocking sockets or other custom made pull/push functions
-the @ref{gnutls_transport_set_lowat} must be called, with a zero
-low water mark value.
-
-By default, if the transport functions are not set, @acronym{GnuTLS}
-will use the Berkeley Sockets functions.  In this case
-@acronym{GnuTLS} will use some hacks in order for @code{select} to
-work, thus making it easy to add @acronym{TLS} support to existing
-TCP/IP servers.
-
-@node The TLS record protocol
-@section The TLS Record Protocol
-@cindex Record protocol
-
-The Record protocol is the secure communications provider. Its purpose
-is to encrypt, authenticate and ---optionally--- compress packets.
-The following functions are available:
-
-@table @asis
-
-@item @ref{gnutls_record_send}:
-To send a record packet (with application data).
-
-@item @ref{gnutls_record_recv}:
-To receive a record packet (with application data).
-
-@item @ref{gnutls_record_get_direction}:
-To get the direction of the last interrupted function call.
-@end table
-
-As you may have already noticed, the functions which access the Record
-protocol, are quite limited, given the importance of this protocol in
-@acronym{TLS}.  This is because the Record protocol's parameters are
-all set by the Handshake protocol.
-
-The Record protocol initially starts with NULL parameters, which means
-no encryption, and no MAC is used. Encryption and authentication begin
-just after the handshake protocol has finished.
-
-@menu
-* Encryption algorithms used in the record layer::
-* Compression algorithms used in the record layer::
-* Weaknesses and countermeasures::
-@end menu
-
-@node Encryption algorithms used in the record layer
-@subsection Encryption Algorithms Used in the Record Layer
-@cindex Symmetric encryption algorithms
-
-Confidentiality in the record layer is achieved by using symmetric
-block encryption algorithms like @code{3DES}, @code{AES}@footnote{AES,
-or Advanced Encryption Standard, is actually the RIJNDAEL algorithm.
-This is the algorithm that replaced DES.}, or stream algorithms like
-@code{ARCFOUR_128}@footnote{@code{ARCFOUR_128} is a compatible
-algorithm with RSA's RC4 algorithm, which is considered to be a trade
-secret.}. Ciphers are encryption algorithms that use a single, secret,
-key to encrypt and decrypt data. Block algorithms in TLS also provide
-protection against statistical analysis of the data.  Thus, if you're
-using the @acronym{TLS} protocol, a random number of blocks will be
-appended to data, to prevent eavesdroppers from guessing the actual
-data size.
-
-Supported cipher algorithms:
-
-@table @code
-@item 3DES_CBC
-@code{3DES_CBC} is the DES block cipher algorithm used with triple
-encryption (EDE). Has 64 bits block size and is used in CBC mode.
-
-@item ARCFOUR_128
-ARCFOUR is a fast stream cipher.
-
-@item ARCFOUR_40
-This is the ARCFOUR cipher that is fed with a 40 bit key,
-which is considered weak.
-
-@item AES_CBC
-AES or RIJNDAEL is the block cipher algorithm that replaces the old
-DES algorithm.  Has 128 bits block size and is used in CBC mode. This
-is not officially supported in TLS.
-@end table
-
-Supported MAC algorithms:
-
-@table @code
-@item MAC_MD5
-MD5 is a cryptographic hash algorithm designed by Ron Rivest. Outputs
-128 bits of data.
-
-@item MAC_SHA
-SHA is a cryptographic hash algorithm designed by NSA. Outputs 160
-bits of data.
-
-@end table
-
-@node Compression algorithms used in the record layer
-@subsection Compression Algorithms Used in the Record Layer
-@cindex Compression algorithms
-
-The TLS record layer also supports compression.  The algorithms
-implemented in @acronym{GnuTLS} can be found in the table below.
-All the algorithms except for DEFLATE which is
-referenced in @xcite{RFC3749}, should be considered as
-@acronym{GnuTLS}' extensions@footnote{You should use
-@ref{gnutls_handshake_set_private_extensions} to enable private
-extensions.}, and should be advertised only when the peer is known to
-have a compliant client, to avoid interoperability problems.
-
-The included algorithms perform really good when text, or other
-compressible data are to be transfered, but offer nothing on already
-compressed data, such as compressed images, zipped archives etc.
-These compression algorithms, may be useful in high bandwidth TLS
-tunnels, and in cases where network usage has to be minimized. As a
-drawback, compression increases latency.
-
-The record layer compression in @acronym{GnuTLS} is implemented based
-on the proposal @xcite{RFC3749}.
-The supported compression algorithms are:
-
-@table @code
-@item DEFLATE
-Zlib compression, using the deflate algorithm.
-
-@item LZO
-LZO is a very fast compression algorithm.  This algorithm is only
-available if the @acronym{GnuTLS-extra} library has been initialized
-and the private extensions are enabled, and if GnuTLS was built with
-LZO support.
-
-@end table
-
-@node Weaknesses and countermeasures
-@subsection Weaknesses and Countermeasures
-
-Some weaknesses that may affect the security of the Record layer have
-been found in @acronym{TLS} 1.0 protocol. These weaknesses can be
-exploited by active attackers, and exploit the facts that
-
-@enumerate
-
-@item
-@acronym{TLS} has separate alerts for ``decryption_failed'' and
-``bad_record_mac''
-
-@item
-The decryption failure reason can be detected by timing the response
-time.
-
-@item
-The IV for CBC encrypted packets is the last block of the previous
-encrypted packet.
-
-@end enumerate
-
-Those weaknesses were solved in @acronym{TLS} 1.1 @xcite{RFC4346}
-which is implemented in @acronym{GnuTLS}. For a detailed discussion
-see the archives of the TLS Working Group mailing list and the paper
-@xcite{CBCATT}.
-
-@node The TLS Alert Protocol
-@section The TLS Alert Protocol
-@anchor{The Alert Protocol}
-@cindex Alert protocol
-
-The Alert protocol is there to allow signals to be sent between peers.
-These signals are mostly used to inform the peer about the cause of a
-protocol failure. Some of these signals are used internally by the
-protocol and the application protocol does not have to cope with them
-(see @code{GNUTLS_A_CLOSE_NOTIFY}), and others refer to the
-application protocol solely (see @code{GNUTLS_A_USER_CANCELLED}).  An
-alert signal includes a level indication which may be either fatal or
-warning. Fatal alerts always terminate the current connection, and
-prevent future renegotiations using the current session ID.
-
-The alert messages are protected by the record protocol, thus the
-information that is included does not leak. You must take extreme care
-for the alert information not to leak to a possible attacker, via
-public log files etc.
-
-@table @asis
-@item @ref{gnutls_alert_send}:
-To send an alert signal.
-
-@item @ref{gnutls_error_to_alert}:
-To map a gnutls error number to an alert signal.
-
-@item @ref{gnutls_alert_get}:
-Returns the last received alert.
-
-@item @ref{gnutls_alert_get_name}:
-Returns the name, in a character array, of the given alert.
-
-@end table
-
-@node The TLS Handshake Protocol
-@section The TLS Handshake Protocol
-@anchor{The Handshake Protocol}
-@cindex Handshake protocol
-
-The Handshake protocol is responsible for the ciphersuite negotiation,
-the initial key exchange, and the authentication of the two peers.
-This is fully controlled by the application layer, thus your program
-has to set up the required parameters. Available functions to control
-the handshake protocol include:
-
-@table @asis
-@item @ref{gnutls_priority_init}:
-To initialize a priority set of ciphers.
-
-@item @ref{gnutls_priority_deinit}:
-To deinitialize a priority set of ciphers.
-
-@item @ref{gnutls_priority_set}:
-To associate a priority set with a @acronym{TLS} session.
-
-@item @ref{gnutls_priority_set_direct}:
-To directly associate a session with a given priority string.
-
-@item @ref{gnutls_credentials_set}:
-To set the appropriate credentials structures.
-
-@item @ref{gnutls_certificate_server_set_request}:
-To set whether client certificate is required or not.
-
-@item @ref{gnutls_handshake}:
-To initiate the handshake.
-@end table
-
-@subsection TLS Cipher Suites
-
-The Handshake Protocol of @acronym{TLS} negotiates cipher suites of
-the form @code{TLS_DHE_RSA_WITH_3DES_CBC_SHA}.  The usual cipher
-suites contain these parameters:
-
-@itemize
-
-@item The key exchange algorithm.
-@code{DHE_RSA} in the example.
-
-@item The Symmetric encryption algorithm and mode
-@code{3DES_CBC} in this example.
-
-@item The MAC@footnote{MAC stands for Message Authentication Code. It can be described as a keyed hash algorithm. See RFC2104.} algorithm used for authentication.
-@code{MAC_SHA} is used in the above example.
-
-@end itemize
-
-The cipher suite negotiated in the handshake protocol will affect the
-Record Protocol, by enabling encryption and data authentication.  Note
-that you should not over rely on @acronym{TLS} to negotiate the
-strongest available cipher suite. Do not enable ciphers and algorithms
-that you consider weak.
-
-The priority functions, dicussed above, allow the application layer to
-enable and set priorities on the individual ciphers. It may imply that
-all combinations of ciphersuites are allowed, but this is not
-true. For several reasons, not discussed here, some combinations were
-not defined in the @acronym{TLS} protocol.  The supported ciphersuites
-are shown in @ref{ciphersuites}.
-
-@subsection Client Authentication
-@cindex Client Certificate authentication
-
-In the case of ciphersuites that use certificate authentication, the
-authentication of the client is optional in @acronym{TLS}.  A server
-may request a certificate from the client --- using the
-@ref{gnutls_certificate_server_set_request} function. If a certificate
-is to be requested from the client during the handshake, the server
-will send a certificate request message that contains a list of
-acceptable certificate signers. In @acronym{GnuTLS} the certificate
-signers list is constructed using the trusted Certificate Authorities
-by the server. That is the ones set using
-@itemize
-@item @ref{gnutls_certificate_set_x509_trust_file}
-@item @ref{gnutls_certificate_set_x509_trust_mem}
-@end itemize
-
-Sending of the names of the CAs can be controlled using
-@ref{gnutls_certificate_send_x509_rdn_sequence}. The client, then, may
-send a certificate, signed by one of the server's acceptable signers.
-
-@subsection Resuming Sessions
-@anchor{resume}
-@cindex Resuming sessions
-
-The @ref{gnutls_handshake} function, is expensive since a lot of
-calculations are performed. In order to support many fast connections
-to the same server a client may use session resuming. @strong{Session
-resuming} is a feature of the @acronym{TLS} protocol which allows a
-client to connect to a server, after a successful handshake, without
-the expensive calculations.  This is achieved by using the previously
-established keys. @acronym{GnuTLS} supports this feature, and the
-example (@pxref{ex:resume-client}) illustrates a typical use of it.
-
-Keep in mind that sessions are expired after some time, for security
-reasons, thus it may be normal for a server not to resume a session
-even if you requested that.  Also note that you must enable, using the
-priority functions, at least the algorithms used in the last session.
-
-@subsection Resuming Internals
-
-The resuming capability, mostly in the server side, is one of the
-problems of a thread-safe TLS implementations. The problem is that all
-threads must share information in order to be able to resume
-sessions. The gnutls approach is, in case of a client, to leave all
-the burden of resuming to the client. I.e., copy and keep the
-necessary parameters. See the functions:
-
-@itemize
-
-@item @ref{gnutls_session_get_data}
-
-@item @ref{gnutls_session_get_id}
-
-@item @ref{gnutls_session_set_data}
-
-@end itemize
-
-The server side is different. A server has to specify some callback
-functions which store, retrieve and delete session data. These can be
-registered with:
-
-@itemize
-
-@item @ref{gnutls_db_set_remove_function}
-
-@item @ref{gnutls_db_set_store_function}
-
-@item @ref{gnutls_db_set_retrieve_function}
-
-@item @ref{gnutls_db_set_ptr}
-
-@end itemize
-
-It might also be useful to be able to check for expired sessions in
-order to remove them, and save space. The function
-@ref{gnutls_db_check_entry} is provided for that reason.
-
-@node TLS Extensions
-@section TLS Extensions
-@cindex TLS Extensions
-
-A number of extensions to the @acronym{TLS} protocol have been
-proposed mainly in @xcite{TLSEXT}. The extensions supported
-in @acronym{GnuTLS} are:
-
-@itemize
-@item Maximum fragment length negotiation
-@item Server name indication
-@item Session tickets
-@end itemize
-
-and they will be discussed in the subsections that follow.
-
-@subsection Maximum Fragment Length Negotiation
-@cindex TLS Extensions
-@cindex Maximum fragment length
-
-This extension allows a @acronym{TLS} implementation to negotiate a
-smaller value for record packet maximum length. This extension may be
-useful to clients with constrained capabilities. See the
-@ref{gnutls_record_set_max_size} and the
-@ref{gnutls_record_get_max_size} functions.
-
-@subsection Server Name Indication
-@anchor{serverind}
-@cindex TLS Extensions
-@cindex Server name indication
-
-A common problem in @acronym{HTTPS} servers is the fact that the
-@acronym{TLS} protocol is not aware of the hostname that a client
-connects to, when the handshake procedure begins. For that reason the
-@acronym{TLS} server has no way to know which certificate to send.
-
-This extension solves that problem within the @acronym{TLS} protocol,
-and allows a client to send the HTTP hostname before the handshake
-begins within the first handshake packet.  The functions
-@ref{gnutls_server_name_set} and @ref{gnutls_server_name_get} can be
-used to enable this extension, or to retrieve the name sent by a
-client.
-
-@subsection Session Tickets
-@cindex TLS Extensions
-@cindex Session Tickets
-@cindex Ticket
-
-To resume a TLS session the server normally store some state.  This
-complicates deployment, and typical situations the client can cache
-information and send it to the server instead.  The Session Ticket
-extension implements this idea, and it is documented in
-RFC 5077 @xcite{TLSTKT}.
-
-Clients can enable support for TLS tickets with
-@ref{gnutls_session_ticket_enable_client} and servers use
-@ref{gnutls_session_ticket_key_generate} to generate a key and
-@ref{gnutls_session_ticket_enable_server} to enable the extension.
-Clients resume sessions using the ticket using the normal session
-resume functions, @ref{resume}.
-
-@node Selecting cryptographic key sizes
-@section Selecting Cryptographic Key Sizes
-@cindex key sizes
-
-In TLS, since a lot of algorithms are involved, it is not easy to set
-a consistent security level.  For this reason this section will
-present some correspondance between key sizes of symmetric algorithms
-and public key algorithms based on the most conservative values of
-@xcite{SELKEY}.  Those can be used to generate certificates with
-appropriate key sizes as well as parameters for Diffie-Hellman and SRP
-authentication.
-
-@multitable @columnfractions .15 .20 .20 .20
-
-@item Year
-@tab Symmetric key size
-@tab RSA key size, DH and SRP prime size
-@tab ECC key size
-
-@item 1982
-@tab 56
-@tab 417
-@tab 105
-
-@item 1988
-@tab 61
-@tab 566
-@tab 114
-
-@item 2002
-@tab 72
-@tab 1028
-@tab 139
-
-@item 2015
-@tab 82
-@tab 1613
-@tab 173
-
-@item 2028
-@tab 92
-@tab 2362
-@tab 210
-
-@item 2040
-@tab 101
-@tab 3214
-@tab 244
-
-@item 2050
-@tab 109
-@tab 4047
-@tab 272
-
-@end multitable
-
-The first column provides an estimation of the year until these
-parameters are considered safe and the rest of the columns list the
-parameters for the various algorithms.
-
-Note however that the values suggested here are nothing more than an
-educated guess that is valid today. There are no guarrantees that an
-algorithm will remain unbreakable or that these values will remain
-constant in time. There could be scientific breakthroughs that cannot
-be predicted or total failure of the current public key systems by
-quantum computers. On the other hand though the cryptosystems used in
-TLS are selected in a conservative way and such catastrophic
-breakthroughs or failures are believed to be unlikely.
-
-NIST publication SP 800-57 @xcite{NISTSP80057} contains a similar
-table that extends beyond the key sizes given above.
-
-@multitable @columnfractions .15 .20 .20 .20
-
-@item Bits of security
-@tab Symmetric key algorithms
-@tab RSA key size, DSA, DH and SRP prime size
-@tab ECC key size
-
-@item 80
-@tab 2TDEA
-@tab 1024
-@tab 160-223
-
-@item 112
-@tab 3DES
-@tab 2048
-@tab 224-255
-
-@item 128
-@tab AES-128
-@tab 3072
-@tab 256-383
-
-@item 192
-@tab AES-192
-@tab 7680
-@tab 384-511
-
-@item 256
-@tab AES-256
-@tab 15360
-@tab 512+
-
-@end multitable
-
-The recommendations are fairly consistent.
-
-@node On SSL 2 and older protocols
-@section On SSL 2 and Older Protocols
-@cindex SSL 2
-
-One of the initial decisions in the @acronym{GnuTLS} development was
-to implement the known security protocols for the transport layer.
-Initially @acronym{TLS} 1.0 was implemented since it was the latest at
-that time, and was considered to be the most advanced in security
-properties.  Later the @acronym{SSL} 3.0 protocol was implemented
-since it is still the only protocol supported by several servers and
-there are no serious security vulnerabilities known.
-
-One question that may arise is why we didn't implement @acronym{SSL}
-2.0 in the library.  There are several reasons, most important being
-that it has serious security flaws, unacceptable for a modern security
-library.  Other than that, this protocol is barely used by anyone
-these days since it has been deprecated since 1996.  The security
-problems in @acronym{SSL} 2.0 include:
-
-@itemize
-
-@item Message integrity compromised.
-The @acronym{SSLv2} message authentication uses the MD5 function, and
-is insecure.
-
-@item Man-in-the-middle attack.
-There is no protection of the handshake in @acronym{SSLv2}, which
-permits a man-in-the-middle attack.
-
-@item Truncation attack.
-@acronym{SSLv2} relies on TCP FIN to close the session, so the
-attacker can forge a TCP FIN, and the peer cannot tell if it was a
-legitimate end of data or not.
-
-@item Weak message integrity for export ciphers.
-The cryptographic keys in @acronym{SSLv2} are used for both message
-authentication and encryption, so if weak encryption schemes are
-negotiated (say 40-bit keys) the message authentication code use the
-same weak key, which isn't necessary.
-
-@end itemize
-
-@cindex PCT
-Other protocols such as Microsoft's @acronym{PCT} 1 and @acronym{PCT}
-2 were not implemented because they were also abandoned and deprecated
-by @acronym{SSL} 3.0 and later @acronym{TLS} 1.0.
-
-@node On Record Padding
-@section On Record Padding
-@cindex Record padding
-@cindex Bad record MAC
-
-The TLS protocol allows for random padding of records, to make it more
-difficult to perform analysis on the length of exchanged messages.
-(In RFC 4346 this is specified in section 6.2.3.2.)  GnuTLS appears to
-be one of few implementation that take advantage of this text, and pad
-records by a random length.
-
-The TLS implementation in the Symbian operating system, frequently
-used by Nokia and Sony-Ericsson mobile phones, cannot handle
-non-minimal record padding.  What happens when one of these clients
-handshake with a GnuTLS server is that the client will fail to compute
-the correct MAC for the record.  The client sends a TLS alert
-(@code{bad_record_mac}) and disconnects.  Typically this will result
-in error messages such as 'A TLS fatal alert has been received', 'Bad
-record MAC', or both, on the GnuTLS server side.
-
-GnuTLS implements a work around for this problem.  However, it has to
-be enabled specifically.  It can be enabled by using
-@ref{gnutls_record_disable_padding}, or @ref{gnutls_priority_set} with
-the @code{%COMPAT} priority string.
-
-If you implement an application that have a configuration file, we
-recommend that you make it possible for users or administrators to
-specify a GnuTLS protocol priority string, which is used by your
-application via @ref{gnutls_priority_set}.  To allow the best
-flexibility, make it possible to have a different priority string for
-different incoming IP addresses.
-
-To enable the workaround in the @code{gnutls-cli} client or the
-@code{gnutls-serv} server, for testing of other implementations, use
-the following parameter: @code{--priority "%COMPAT"}.
-
-This problem has been discussed on mailing lists and in bug reports.
-This section tries to collect all pieces of information that we know
-about the problem.  If you wish to go back to the old discussions,
-here are some links:
-
-@url{http://bugs.debian.org/390712}
-
-@url{http://bugs.debian.org/402861}
-
-@url{http://bugs.debian.org/438137}
-
-@url{http://thread.gmane.org/gmane.ietf.tls/3079}
-
-@node Safe Renegotiation
-@section Safe Renegotiation
-@cindex renegotiation
-
-Some application protocols and implementations uses the TLS
-renegotiation feature in a manner that enables attackers to insert
-content of his choice in the beginning of a TLS session.
-
-One easy to understand vulnerability is HTTPS when servers request
-client certificates optionally for certain parts of a web site.  The
-attack works by having the attacker simulate a client and connect to a
-server, with server-only authentication, and send some data intended
-to cause harm.  When the proper client attempts to contact the server,
-the attacker hijacks that connection and uses the TLS renegotiation
-feature with the server and splices in the client connection to the
-already established connection between the attacker and server.  The
-attacker will not be able to read the data exchanged between the
-client and the server.  However, the server will (incorrectly) assume
-that the data sent by the attacker was sent by the now authenticated
-client.  The result is a prefix plain-text injection attack.
-
-The above is just one example.  Other vulnerabilities exists that do
-not rely on the TLS renegotiation to change the client's authenticated
-status (either TLS or application layer).
-
-While fixing these application protocols and implementations would be
-one natural reaction, an extension to TLS has been designed that
-cryptographically binds together any renegotiated handshakes with the
-initial negotiation.  When the extension is used, the attack is
-detected and the session can be terminated.  The extension is
-specified in @xcite{RFC5746}.
-
-GnuTLS supports the safe renegotiation extension.  The default
-behavior is as follows.  Clients will attempt to negotiate the safe
-renegotiation extension when talking to servers.  Servers will accept
-the extension when presented by clients.  Clients and servers will
-permit an initial handshake to complete even when the other side does
-not support the safe renegotiation extension.  Clients and servers
-will refuse renegotiation attempts when the extension has not been
-negotiated.
-
-Note that permitting clients to connect to servers even when the safe
-renegotiation extension is not negotiated open up for some attacks.
-Changing this default behaviour would prevent interoperability against
-the majority of deployed servers out there.  We will reconsider this
-default behaviour in the future when more servers have been upgraded.
-Note that it is easy to configure clients to always require the safe
-renegotiation extension from servers (see below on the
-%SAFE_RENEGOTIATION priority string).
-
-To modify the default behaviour, we have introduced some new priority
-strings.  The priority strings can be used by applications
-(@pxref{gnutls_priority_set}) and end users (e.g., @code{--priority}
-parameter to @code{gnutls-cli} and @code{gnutls-serv}).
-
-The @code{%UNSAFE_RENEGOTIATION} priority string permits
-(re-)handshakes even when the safe renegotiation extension was not
-negotiated. The default behavior is @code{%PARTIAL_RENEGOTIATION} that will
-prevent renegotiation with clients and servers not supporting the
-extension. This is secure for servers but leaves clients vulnerable
-to some attacks, but this is a tradeoff between security and compatibility
-with old servers. The @code{%SAFE_RENEGOTIATION} priority string makes
-clients and servers require the extension for every handshake. The latter
-is the most secure option for clients, at the cost of not being able
-to connect to legacy servers. Servers will also deny clients that
-do not support the extension from connecting.
-
-It is possible to disable use of the extension completely, in both
-clients and servers, by using the @code{%DISABLE_SAFE_RENEGOTIATION}
-priority string however we strongly recommend you to only do this for
-debugging and test purposes.
-
-The default values if the flags above are not specified are:
-@table @code
-
-@item Server:
-%PARTIAL_RENEGOTIATION
-
-@item Client:
-%PARTIAL_RENEGOTIATION
-
-@end table
-
-For applications we have introduced a new API related to safe
-renegotiation.  The @ref{gnutls_safe_renegotiation_status} function is
-used to check if the extension has been negotiated on a session, and
-can be used both by clients and servers.
-
-@node Authentication methods
-@chapter Authentication Methods
-
-The @acronym{TLS} protocol provides confidentiality and encryption,
-but also offers authentication, which is a prerequisite for a secure
-connection. The available authentication methods in @acronym{GnuTLS}
-are:
-
-@itemize
-
-@item Certificate authentication
-
-@item Anonymous authentication
-
-@item @acronym{SRP} authentication
-
-@item @acronym{PSK} authentication
-
-@end itemize
-
-@menu
-* Certificate authentication::
-* Anonymous authentication::
-* Authentication using SRP::
-* Authentication using PSK::
-* Authentication and credentials::
-* Parameters stored in credentials::
-@end menu
-
-@node Certificate authentication
-@section Certificate Authentication
-
-@subsection Authentication Using @acronym{X.509} Certificates
-@cindex @acronym{X.509} certificates
-
-@acronym{X.509} certificates contain the public parameters, of a
-public key algorithm, and an authority's signature, which proves the
-authenticity of the parameters.  @xref{The X.509 trust model}, for
-more information on @acronym{X.509} protocols.
-
-@subsection Authentication Using @acronym{OpenPGP} Keys
-@cindex @acronym{OpenPGP} Keys
-
-@acronym{OpenPGP} keys also contain public parameters of a public key
-algorithm, and signatures from several other parties. Depending on
-whether a signer is trusted the key is considered trusted or not.
-@acronym{GnuTLS}'s @acronym{OpenPGP} authentication implementation is
-based on the @xcite{TLSPGP} proposal.
-
-@xref{The OpenPGP trust model}, for more information about the
-@acronym{OpenPGP} trust model.  For a more detailed introduction to
-@acronym{OpenPGP} and @acronym{GnuPG} see @xcite{GPGH}.
-
-@subsection Using Certificate Authentication
-
-In @acronym{GnuTLS} both the @acronym{OpenPGP} and @acronym{X.509}
-certificates are part of the certificate authentication and thus are
-handled using a common API.
-
-When using certificates the server is required to have at least one
-certificate and private key pair. A client may or may not have such a
-pair. The certificate and key pair should be loaded, before any
-@acronym{TLS} session is initialized, in a certificate credentials
-structure. This should be done by using
-@ref{gnutls_certificate_set_x509_key_file} or
-@ref{gnutls_certificate_set_openpgp_key_file} depending on the
-certificate type.  In the @acronym{X.509} case, the functions will
-also accept and use a certificate list that leads to a trusted
-authority. The certificate list must be ordered in such way that every
-certificate certifies the one before it. The trusted authority's
-certificate need not to be included, since the peer should possess it
-already.
-
-As an alternative, a callback may be used so the server or the client
-specify the certificate and the key at the handshake time.  That
-callback can be set using the functions:
-
-@itemize
-
-@item @ref{gnutls_certificate_server_set_retrieve_function}
-
-@item @ref{gnutls_certificate_client_set_retrieve_function}
-
-@end itemize
-
-Clients and servers that will select certificates using callback
-functions should select a certificate according the peer's signature
-algorithm preferences. To get those preferences use
-@ref{gnutls_sign_algorithm_get_requested}.
-
-Certificate verification is possible by loading the trusted
-authorities into the credentials structure by using
-@ref{gnutls_certificate_set_x509_trust_file} or
-@ref{gnutls_certificate_set_openpgp_keyring_file} for openpgp
-keys. Note however that the peer's certificate is not automatically
-verified, you should call @ref{gnutls_certificate_verify_peers2},
-after a successful handshake, to verify the signatures of the
-certificate.  An alternative way, which reports a more detailed
-verification output, is to use @ref{gnutls_certificate_get_peers} to
-obtain the raw certificate of the peer and verify it using the
-functions discussed in @ref{The X.509 trust model}.
-
-In a handshake, the negotiated cipher suite depends on the
-certificate's parameters, so not all key exchange methods will be
-available with some certificates. @acronym{GnuTLS} will disable
-ciphersuites that are not compatible with the key, or the enabled
-authentication methods.  For example keys marked as sign-only, will
-not be able to access the plain RSA ciphersuites, but only the
-@code{DHE_RSA} ones. It is recommended not to use RSA keys for both
-signing and encryption. If possible use the same key for the
-@code{DHE_RSA} and @code{RSA_EXPORT} ciphersuites, which use signing,
-and a different key for the plain RSA ciphersuites, which use
-encryption.  All the key exchange methods shown below are available in
-certificate authentication.
-
-Note that the DHE key exchange methods are generally
-slower@footnote{It really depends on the group used.  Primes with
-lesser bits are always faster, but also easier to break.  Values less
-than 768 should not be used today} than plain RSA and require Diffie
-Hellman parameters to be generated and associated with a credentials
-structure, by the server.  The @code{RSA-EXPORT} method also requires
-512 bit RSA parameters, that should also be generated and associated
-with the credentials structure.  See the functions:
-
-@itemize
-
-@item @ref{gnutls_dh_params_generate2}
-
-@item @ref{gnutls_certificate_set_dh_params}
-
-@item @ref{gnutls_rsa_params_generate2}
-
-@item @ref{gnutls_certificate_set_rsa_export_params}
-
-@end itemize
-
-Sometimes in order to avoid bottlenecks in programs it is usefull to
-store and read parameters from formats that can be generated by
-external programs such as @code{certtool}. This is possible with
-@acronym{GnuTLS} by using the following functions:
-
-@itemize
-
-@item @ref{gnutls_dh_params_import_pkcs3}
-
-@item @ref{gnutls_rsa_params_import_pkcs1}
-
-@item @ref{gnutls_dh_params_export_pkcs3}
-
-@item @ref{gnutls_rsa_params_export_pkcs1}
-
-@end itemize
-
-Key exchange algorithms for @acronym{OpenPGP} and @acronym{X.509}
-certificates:
-
-@table @code
-
-@item RSA:
-The RSA algorithm is used to encrypt a key and send it to the peer.
-The certificate must allow the key to be used for encryption.
-
-@item RSA_EXPORT:
-The RSA algorithm is used to encrypt a key and send it to the peer.
-In the EXPORT algorithm, the server signs temporary RSA parameters of
-512 bits --- which are considered weak --- and sends them to the
-client.
-
-@item DHE_RSA:
-The RSA algorithm is used to sign Ephemeral Diffie-Hellman parameters
-which are sent to the peer. The key in the certificate must allow the
-key to be used for signing. Note that key exchange algorithms which
-use Ephemeral Diffie-Hellman parameters, offer perfect forward
-secrecy. That means that even if the private key used for signing is
-compromised, it cannot be used to reveal past session data.
-
-@item DHE_DSS:
-The DSS algorithm is used to sign Ephemeral Diffie-Hellman parameters
-which are sent to the peer. The certificate must contain DSA
-parameters to use this key exchange algorithm. DSS stands for Digital
-Signature Standard.
-
-@end table
-
-@node Anonymous authentication
-@section Anonymous Authentication
-@cindex Anonymous authentication
-
-The anonymous key exchange performs encryption but there is no
-indication of the identity of the peer.  This kind of authentication
-is vulnerable to a man in the middle attack, but this protocol can be
-used even if there is no prior communication and trusted parties with
-the peer, or when full anonymity is required.  Unless really required,
-do not use anonymous authentication.  Available key exchange methods
-are shown below.
-
-Note that the key exchange methods for anonymous authentication
-require Diffie-Hellman parameters to be generated by the server and
-associated with an anonymous credentials structure.
-
-Supported anonymous key exchange algorithms:
-
-@table @code
-
-@item ANON_DH:
-This algorithm exchanges Diffie-Hellman parameters.
-
-@end table
-
-@node Authentication using SRP
-@section Authentication using @acronym{SRP}
-@cindex @acronym{SRP} authentication
-
-Authentication via the Secure Remote Password protocol,
-@acronym{SRP}@footnote{@acronym{SRP} is described in @xcite{RFC2945}},
-is supported.  The @acronym{SRP} key exchange is an extension to the
-@acronym{TLS} protocol, and it is a password based authentication
-(unlike @acronym{X.509} or @acronym{OpenPGP} that use certificates).
-The two peers can be identified using a single password, or there can
-be combinations where the client is authenticated using @acronym{SRP}
-and the server using a certificate.
-
-The advantage of @acronym{SRP} authentication, over other proposed
-secure password authentication schemes, is that @acronym{SRP} does not
-require the server to hold the user's password.  This kind of
-protection is similar to the one used traditionally in the @emph{UNIX}
-@file{/etc/passwd} file, where the contents of this file did not cause
-harm to the system security if they were revealed.  The @acronym{SRP}
-needs instead of the plain password something called a verifier, which
-is calculated using the user's password, and if stolen cannot be used
-to impersonate the user. Check @xcite{TOMSRP} for a detailed
-description of the @acronym{SRP} protocol and the Stanford
-@acronym{SRP} libraries, which includes a PAM module that synchronizes
-the system's users passwords with the @acronym{SRP} password
-files. That way @acronym{SRP} authentication could be used for all the
-system's users.
-
-The implementation in @acronym{GnuTLS} is based on paper
-@xcite{TLSSRP}.  The supported @acronym{SRP} key exchange methods are:
-
-@table @code
-
-@item SRP:
-Authentication using the @acronym{SRP} protocol.
-
-@item SRP_DSS:
-Client authentication using the @acronym{SRP} protocol. Server is
-authenticated using a certificate with DSA parameters.
-
-@item SRP_RSA:
-Client authentication using the @acronym{SRP} protocol. Server is
-authenticated using a certificate with RSA parameters.
-
-@end table
-
-If clients supporting @acronym{SRP} know the username and password
-before the connection, should initialize the client credentials and
-call the function @ref{gnutls_srp_set_client_credentials}.
-Alternatively they could specify a callback function by using the
-function @ref{gnutls_srp_set_client_credentials_function}.  This has
-the advantage that allows probing the server for @acronym{SRP}
-support.  In that case the callback function will be called twice per
-handshake.  The first time is before the ciphersuite is negotiated,
-and if the callback returns a negative error code, the callback will
-be called again if @acronym{SRP} has been negotiated.  This uses a
-special @acronym{TLS}-@acronym{SRP} handshake idiom in order to avoid,
-in interactive applications, to ask the user for @acronym{SRP}
-password and username if the server does not negotiate an
-@acronym{SRP} ciphersuite.
-
-In server side the default behaviour of @acronym{GnuTLS} is to read
-the usernames and @acronym{SRP} verifiers from password files. These
-password files are the ones used by the @emph{Stanford srp libraries}
-and can be specified using the
-@ref{gnutls_srp_set_server_credentials_file}.  If a different
-password file format is to be used, then the function
-@ref{gnutls_srp_set_server_credentials_function}, should be called,
-in order to set an appropriate callback.
-
-Some helper functions such as
-
-@itemize
-
-@item @ref{gnutls_srp_verifier}
-
-@item @ref{gnutls_srp_base64_encode}
-
-@item @ref{gnutls_srp_base64_decode}
-
-@end itemize
-
-are included in @acronym{GnuTLS}, and can be 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.  @xref{srptool}, for more information.
-
-
-@node Authentication using PSK
-@section Authentication using @acronym{PSK}
-@cindex @acronym{PSK} authentication
-
-Authentication using Pre-shared keys is a method to authenticate using
-usernames and binary keys. This protocol avoids making use of public
-key infrastructure and expensive calculations, thus it is suitable for
-constraint clients.
-
-The implementation in @acronym{GnuTLS} is based on paper
-@xcite{TLSPSK}.  The supported @acronym{PSK} key exchange methods are:
-
-@table @code
-
-@item PSK:
-Authentication using the @acronym{PSK} protocol.
-
-@item DHE-PSK:
-Authentication using the @acronym{PSK} protocol and Diffie-Hellman key
-exchange.  This method offers perfect forward secrecy.
-
-@end table
-
-Clients supporting @acronym{PSK} should supply the username and key
-before the connection to the client credentials by calling the
-function @ref{gnutls_psk_set_client_credentials}.  Alternatively they
-could specify a callback function by using the function
-@ref{gnutls_psk_set_client_credentials_function}.  This has the
-advantage that the callback will be called only if @acronym{PSK} has
-been negotiated.
-
-In server side the default behaviour of @acronym{GnuTLS} is to read
-the usernames and @acronym{PSK} keys from a password file. The
-password file should contain usernames and keys in hexadecimal
-format. The name of the password file can be stored to the credentials
-structure by calling @ref{gnutls_psk_set_server_credentials_file}.  If
-a different password file format is to be used, then the function
-@ref{gnutls_psk_set_server_credentials_function}, should be used
-instead.
-
-The server can help the client chose a suitable username and password,
-by sending a hint.  In the server, specify the hint by calling
-@ref{gnutls_psk_set_server_credentials_hint}.  The client can retrieve
-the hint, for example in the callback function, using
-@ref{gnutls_psk_client_get_hint}.
-
-There is no standard mechanism to derive a PSK key from a password
-specified by the TLS PSK document.  However, GnuTLS provides
-@ref{gnutls_psk_netconf_derive_key} which follows the algorithm
-specified in @file{draft-ietf-netconf-tls-02.txt}.
-
-Some helper functions such as:
-
-@itemize
-
-@item @ref{gnutls_hex_encode}
-
-@item @ref{gnutls_hex_decode}
-
-@end itemize
-
-are included in @acronym{GnuTLS}, and may be used to generate and
-maintain @acronym{PSK} keys.
-
-
-@node Authentication and credentials
-@section Authentication and Credentials
-
-In @acronym{GnuTLS} every key exchange method is associated with a
-credentials type. So in order to enable to enable a specific method,
-the corresponding credentials type should be initialized and set using
-@ref{gnutls_credentials_set}.  A mapping is shown below.
-
-Key exchange algorithms and the corresponding credential types:
-
-@multitable @columnfractions .3 .3 .3
-
-@headitem Key exchange @tab Client credentials @tab Server credentials
-
-@item @code{KX_RSA}
-@item @code{KX_DHE_RSA}
-@item @code{KX_DHE_DSS}
-@item @code{KX_RSA_EXPORT}
-@tab @code{CRD_CERTIFICATE}
-@tab @code{CRD_CERTIFICATE}
-
-@item @code{KX_SRP_RSA}
-@tab @code{CRD_SRP}
-@tab @code{CRD_SRP}
-@item @code{KX_SRP_DSS}
-@tab
-@tab @code{CRD_CERTIFICATE}
-
-@item @code{KX_SRP}
-@tab @code{CRD_SRP}
-@tab @code{CRD_SRP}
-
-@item @code{KX_ANON_DH}
-@tab @code{CRD_ANON}
-@tab @code{CRD_ANON}
-
-@item @code{KX_PSK}
-@tab @code{CRD_PSK}
-@tab @code{CRD_PSK}
-
-@end multitable
-
-@node Parameters stored in credentials
-@section Parameters Stored in Credentials
-
-Several parameters such as the ones used for Diffie-Hellman
-authentication are stored within the credentials structures, so all
-sessions can access them. Those parameters are stored in structures
-such as @code{gnutls_dh_params_t} and @code{gnutls_rsa_params_t}, and
-functions like @ref{gnutls_certificate_set_dh_params} and
-@ref{gnutls_certificate_set_rsa_export_params} can be used to
-associate those parameters with the given credentials structure.
-
-Since those parameters need to be renewed from time to time and a
-global structure such as the credentials, may not be easy to modify
-since it is accessible by all sessions, an alternative interface is
-available using a callback function.  This can be set using the
-@ref{gnutls_certificate_set_params_function}.  An example is shown
-below.
-
-@example
-#include <gnutls.h>
-
-gnutls_rsa_params_t rsa_params;
-gnutls_dh_params_t dh_params;
-
-/* This function will be called once a session requests DH
- * or RSA parameters. The parameters returned (if any) will
- * be used for the first handshake only.
- */
-static int get_params( gnutls_session_t session,
-        gnutls_params_type_t type,
-        gnutls_params_st *st)
-@{
-   if (type == GNUTLS_PARAMS_RSA_EXPORT)
-      st->params.rsa_export = rsa_params;
-   else if (type == GNUTLS_PARAMS_DH)
-      st->params.dh = dh_params;
-   else return -1;
-
-   st->type = type;
-   /* do not deinitialize those parameters.
-    */
-   st->deinit = 0;
-
-   return 0;
-@}
-
-int main()
-@{
-   gnutls_certificate_credentials_t cert_cred;
-
-   initialize_params();
-
-   /* ...
-    */
-
-   gnutls_certificate_set_params_function( cert_cred, get_params);
-@}
-@end example
-
-@node More on certificate authentication
-@chapter More on Certificate Authentication
-@anchor{Certificate Authentication}
-@cindex Certificate authentication
-
-@menu
-* The X.509 trust model::
-* The OpenPGP trust model::
-* Digital signatures::
-@end menu
-
-@node The X.509 trust model
-@section The @acronym{X.509} Trust Model
-@cindex @acronym{X.509} certificates
-
-The @acronym{X.509} protocols rely on a hierarchical trust model. In
-this trust model Certification Authorities (CAs) are used to certify
-entities.  Usually more than one certification authorities exist, and
-certification authorities may certify other authorities to issue
-certificates as well, following a hierarchical model.
-
-@image{gnutls-x509,7cm,9.5cm}
-
-One needs to trust one or more CAs for his secure communications. In
-that case only the certificates issued by the trusted authorities are
-acceptable.  See the figure above for a typical example.  The API for
-handling @acronym{X.509} certificates is described at section
-@ref{sec:x509api}.  Some examples are listed below.
-
-@menu
-* X.509 certificates::
-* Verifying X.509 certificate paths::
-* PKCS #10 certificate requests::
-* PKCS #12 structures::
-@end menu
-
-@node X.509 certificates
-@subsection @acronym{X.509} Certificates
-
-An @acronym{X.509} certificate usually contains information about the
-certificate holder, the signer, a unique serial number, expiration
-dates and some other fields @xcite{PKIX} as shown in the table below.
-
-@table @code
-
-@item version:
-The field that indicates the version of the certificate.
-
-@item serialNumber:
-This field holds a unique serial number per certificate.
-
-@item issuer:
-Holds the issuer's distinguished name.
-
-@item validity:
-The activation and expiration dates.
-
-@item subject:
-The subject's distinguished name of the certificate.
-
-@item extensions:
-The extensions are fields only present in version 3 certificates.
-
-@end table
-
-The certificate's @emph{subject or issuer name} is not just a single
-string.  It is a Distinguished name and in the @acronym{ASN.1}
-notation is a sequence of several object IDs with their corresponding
-values. Some of available OIDs to be used in an @acronym{X.509}
-distinguished name are defined in @file{gnutls/x509.h}.
-
-The @emph{Version} field in a certificate has values either 1 or 3 for
-version 3 certificates.  Version 1 certificates do not support the
-extensions field so it is not possible to distinguish a CA from a
-person, thus their usage should be avoided.
-
-The @emph{validity} dates are there to indicate the date that the
-specific certificate was activated and the date the certificate's key
-would be considered invalid.
-
-Certificate @emph{extensions} are there to include information about
-the certificate's subject that did not fit in the typical certificate
-fields. Those may be e-mail addresses, flags that indicate whether the
-belongs to a CA etc.  All the supported @acronym{X.509} version 3
-extensions are shown in the table below.
-
-@table @code
-
-@item subject key id (2.5.29.14):
-An identifier of the key of the subject.
-
-@item authority key id (2.5.29.35):
-An identifier of the authority's key used to sign the certificate.
-
-@item subject alternative name (2.5.29.17):
-Alternative names to subject's distinguished name.
-
-@item key usage (2.5.29.15):
-Constraints the key's usage of the certificate.
-
-@item extended key usage (2.5.29.37):
-Constraints the purpose of the certificate.
-
-@item basic constraints (2.5.29.19):
-Indicates whether this is a CA certificate or not, and specify the
-maximum path lengths of certificate chains.
-
-@item CRL distribution points (2.5.29.31):
-This extension is set by the CA, in order to inform about the issued
-CRLs.
-
-@item Proxy Certification Information (1.3.6.1.5.5.7.1.14):
-Proxy Certificates includes this extension that contains the OID of
-the proxy policy language used, and can specify limits on the maximum
-lengths of proxy chains.  Proxy Certificates are specified in
-@xcite{RFC3820}.
-
-@end table
-
-In @acronym{GnuTLS} the @acronym{X.509} certificate structures are
-handled using the @code{gnutls_x509_crt_t} type and the corresponding
-private keys with the @code{gnutls_x509_privkey_t} type.  All the
-available functions for @acronym{X.509} certificate handling have
-their prototypes in @file{gnutls/x509.h}. An example program to
-demonstrate the @acronym{X.509} parsing capabilities can be found at
-section @ref{ex:x509-info}.
-
-@node Verifying X.509 certificate paths
-@subsection Verifying @acronym{X.509} Certificate Paths
-@cindex Verifying certificate paths
-
-Verifying certificate paths is important in @acronym{X.509}
-authentication. For this purpose the function
-@ref{gnutls_x509_crt_verify} is provided. The output of this function
-is the bitwise OR of the elements of the
-@code{gnutls_certificate_status_t} enumeration.  A detailed
-description of these elements can be found in figure below.  The
-function @ref{gnutls_certificate_verify_peers2} is equivalent to the
-previous one, and will verify the peer's certificate in a TLS session.
-
-@table @code
-
-@item GNUTLS_CERT_INVALID:
-The certificate is not signed by one of the known authorities, or
-the signature is invalid.
-
-@item GNUTLS_CERT_REVOKED:
-The certificate has been revoked by its CA.
-
-@item GNUTLS_CERT_SIGNER_NOT_FOUND:
-The certificate's issuer is not known. This is the case when the
-issuer is not in the trusted certificates list.
-
-@item GNUTLS_CERT_SIGNER_NOT_CA:
-The certificate's signer was not a CA. This may happen if
-this was a version 1 certificate, which is common with some CAs, or
-a version 3 certificate without the basic constrains extension.
-
-@anchor{GNUTLS_CERT_INSECURE_ALGORITHM}
-@item GNUTLS_CERT_INSECURE_ALGORITHM:
-The certificate was signed using an insecure algorithm such as MD2 or
-MD5.  These algorithms have been broken and should not be trusted.
-
-@end table
-
-There is also to possibility to pass some input to the verification
-functions in the form of flags. For @ref{gnutls_x509_crt_verify} the
-flags are passed straightforward, but
-@ref{gnutls_certificate_verify_peers2} depends on the flags set by
-calling @ref{gnutls_certificate_set_verify_flags}.  All the available
-flags are part of the enumeration
-@ref{gnutls_certificate_verify_flags} and are explained in the table
-below.
-
-@anchor{gnutls_certificate_verify_flags}
-@tindex gnutls_certificate_verify_flags
-@table @code
-@item GNUTLS_VERIFY_DISABLE_CA_SIGN:
-If set a signer does not have to be a certificate authority. This
-flag should normaly be disabled, unless you know what this means.
-
-@item GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT:
-Allow only trusted CA certificates that have version 1.  This is
-safer than GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT, and should be
-used instead. That way only signers in your trusted list will be
-allowed to have certificates of version 1.
-
-@item GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT:
-Allow CA certificates that have version 1 (both root and
-intermediate). This is dangerous since those haven't the
-basicConstraints extension. Must be used in combination with
-GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT.
-
-@item GNUTLS_VERIFY_DO_NOT_ALLOW_SAME:
-If a certificate is not signed by anyone trusted but exists in
-the trusted CA list do not treat it as trusted.
-
-@item GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2:
-Allow certificates to be signed using the old MD2 algorithm.
-
-@item GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5:
-Allow certificates to be signed using the broken MD5 algorithm.
-@end table
-
-Although the verification of a certificate path indicates that the
-certificate is signed by trusted authority, does not reveal anything
-about the peer's identity. It is required to verify if the
-certificate's owner is the one you expect. For more information
-consult @xcite{RFC2818} and section @ref{ex:verify} for an example.
-
-@node PKCS #10 certificate requests
-@subsection @acronym{PKCS} #10 Certificate Requests
-@cindex Certificate requests
-@cindex @acronym{PKCS} #10
-
-A certificate request is a structure, which contain information about
-an applicant of a certificate service.  It usually contains a private
-key, a distinguished name and secondary data such as a challenge
-password. @acronym{GnuTLS} supports the requests defined in
-@acronym{PKCS} #10 @xcite{RFC2986}. Other certificate request's format
-such as PKIX's @xcite{RFC4211} are not currently supported.
-
-In @acronym{GnuTLS} the @acronym{PKCS} #10 structures are handled
-using the @code{gnutls_x509_crq_t} type.  An example of a certificate
-request generation can be found at section @ref{ex:crq}.
-
-@node PKCS #12 structures
-@subsection @acronym{PKCS} #12 Structures
-@cindex @acronym{PKCS} #12
-
-A @acronym{PKCS} #12 structure @xcite{PKCS12} usually contains a user's
-private keys and certificates. It is commonly used in browsers to
-export and import the user's identities.
-
-In @acronym{GnuTLS} the @acronym{PKCS} #12 structures are handled
-using the @code{gnutls_pkcs12_t} type. This is an abstract type that
-may hold several @code{gnutls_pkcs12_bag_t} types.  The Bag types are
-the holders of the actual data, which may be certificates, private
-keys or encrypted data.  An Bag of type encrypted should be decrypted
-in order for its data to be accessed.
-
-An example of a @acronym{PKCS} #12 structure generation can be found
-at section @ref{ex:pkcs12}.
-
-@node The OpenPGP trust model
-@section The @acronym{OpenPGP} Trust Model
-@cindex @acronym{OpenPGP} Keys
-
-The @acronym{OpenPGP} key authentication relies on a distributed trust
-model, called the ``web of trust''. The ``web of trust'' uses a
-decentralized system of trusted introducers, which are the same as a
-CA. @acronym{OpenPGP} allows anyone to sign anyone's else public
-key. When Alice signs Bob's key, she is introducing Bob's key to
-anyone who trusts Alice. If someone trusts Alice to introduce keys,
-then Alice is a trusted introducer in the mind of that observer.
-
-@image{gnutls-pgp,11cm,9cm}
-
-For example: If David trusts Alice to be an introducer, and Alice
-signed Bob's key, Dave also trusts Bob's key to be the real one.
-
-There are some key points that are important in that model. In the
-example Alice has to sign Bob's key, only if she is sure that the key
-belongs to Bob. Otherwise she may also make Dave falsely believe that
-this is Bob's key. Dave has also the responsibility to know who to
-trust.  This model is similar to real life relations.
-
-Just see how Charlie behaves in the previous example. Although he has
-signed Bob's key - because he knows, somehow, that it belongs to Bob -
-he does not trust Bob to be an introducer. Charlie decided to trust
-only Kevin, for some reason. A reason could be that Bob is lazy
-enough, and signs other people's keys without being sure that they
-belong to the actual owner.
-
-@subsection @acronym{OpenPGP} Keys
-
-In @acronym{GnuTLS} the @acronym{OpenPGP} key structures
-@xcite{RFC2440} are handled using the @code{gnutls_openpgp_crt_t} type
-and the corresponding private keys with the
-@code{gnutls_openpgp_privkey_t} type. All the prototypes for the key
-handling functions can be found at @file{gnutls/openpgp.h}.
-
-@subsection Verifying an @acronym{OpenPGP} Key
-
-The verification functions of @acronym{OpenPGP} keys, included in
-@acronym{GnuTLS}, are simple ones, and do not use the features of the
-``web of trust''.  For that reason, if the verification needs are
-complex, the assistance of external tools like @acronym{GnuPG} and
-GPGME (@url{http://www.gnupg.org/related_software/gpgme/}) is
-recommended.
-
-There is one verification function in @acronym{GnuTLS}, the
-@ref{gnutls_openpgp_crt_verify_ring}.  This checks an
-@acronym{OpenPGP} key against a given set of public keys (keyring) and
-returns the key status. The key verification status is the same as in
-@acronym{X.509} certificates, although the meaning and interpretation
-are different. For example an @acronym{OpenPGP} key may be valid, if
-the self signature is ok, even if no signers were found.  The meaning
-of verification status is shown in the figure below.
-
-@table @code
-
-@item CERT_INVALID:
-A signature on the key is invalid. That means that the key was
-modified by somebody, or corrupted during transport.
-
-@item CERT_REVOKED:
-The key has been revoked by its owner.
-
-@item CERT_SIGNER_NOT_FOUND:
-The key was not signed by a known signer.
-
-@item GNUTLS_CERT_INSECURE_ALGORITHM:
-The certificate was signed using an insecure algorithm such as MD2 or
-MD5.  These algorithms have been broken and should not be trusted.
-
-@end table
-
-@node Digital signatures
-@section Digital Signatures
-@cindex Digital signatures
-
-In this section we will provide some information about digital
-signatures, how they work, and give the rationale for disabling some
-of the algorithms used.
-
-Digital signatures work by using somebody's secret key to sign some
-arbitrary data.  Then anybody else could use the public key of that
-person to verify the signature.  Since the data may be arbitrary it is
-not suitable input to a cryptographic digital signature algorithm. For
-this reason and also for performance cryptographic hash algorithms are
-used to preprocess the input to the signature algorithm. This works as
-long as it is difficult enough to generate two different messages with
-the same hash algorithm output. In that case the same signature could
-be used as a proof for both messages. Nobody wants to sign an innocent
-message of donating 1 @euro{} to Greenpeace and find out that he
-donated 1.000.000 @euro{} to Bad Inc.
-
-For a hash algorithm to be called cryptographic the following three
-requirements must hold:
-
-@enumerate
-@item Preimage resistance.
-That means the algorithm must be one way and given the output of the
-hash function @math{H(x)}, it is impossible to calculate @math{x}.
-
-@item 2nd preimage resistance.
-That means that given a pair @math{x,y} with @math{y=H(x)} it is
-impossible to calculate an @math{x'} such that @math{y=H(x')}.
-
-@item Collision resistance.
-That means that it is impossible to calculate random @math{x} and
-@math{x'} such @math{H(x')=H(x)}.
-@end enumerate
-
-The last two requirements in the list are the most important in
-digital signatures. These protect against somebody who would like to
-generate two messages with the same hash output. When an algorithm is
-considered broken usually it means that the Collision resistance of
-the algorithm is less than brute force. Using the birthday paradox the
-brute force attack takes
-@iftex
-@math{2^{(\rm{hash\ size}) / 2}}
-@end iftex
-@ifnottex
-@math{2^{((hash size) / 2)}}
-@end ifnottex
-operations. Today colliding certificates using the MD5 hash algorithm
-have been generated as shown in @xcite{WEGER}.
-
-There has been cryptographic results for the SHA-1 hash algorithms as
-well, although they are not yet critical.  Before 2004, MD5 had a
-presumed collision strength of @math{2^{64}}, but it has been showed
-to have a collision strength well under @math{2^{50}}.  As of November
-2005, it is believed that SHA-1's collision strength is around
-@math{2^{63}}.  We consider this sufficiently hard so that we still
-support SHA-1.  We anticipate that SHA-256/386/512 will be used in
-publicly-distributed certificates in the future.  When @math{2^{63}}
-can be considered too weak compared to the computer power available
-sometime in the future, SHA-1 will be disabled as well.  The collision
-attacks on SHA-1 may also get better, given the new interest in tools
-for creating them.
-
-@subsection Trading Security for Interoperability
-
-If you connect to a server and use GnuTLS' functions to verify the
-certificate chain, and get a @ref{GNUTLS_CERT_INSECURE_ALGORITHM}
-validation error (@pxref{Verifying X.509 certificate paths}), it means
-that somewhere in the certificate chain there is a certificate signed
-using @code{RSA-MD2} or @code{RSA-MD5}.  These two digital signature
-algorithms are considered broken, so GnuTLS fail when attempting to
-verify the certificate.  In some situations, it may be useful to be
-able to verify the certificate chain anyway, assuming an attacker did
-not utilize the fact that these signatures algorithms are broken.
-This section will give help on how to achieve that.
-
-First, it is important to know that you do not have to enable any of
-the flags discussed here to be able to use trusted root CA
-certificates signed using @code{RSA-MD2} or @code{RSA-MD5}.  The only
-attack today is that it is possible to generate certificates with
-colliding signatures (collision resistance); you cannot generate a
-certificate that has the same signature as an already existing
-signature (2nd preimage resistance).
-
-If you are using @ref{gnutls_certificate_verify_peers2} to verify the
-certificate chain, you can call
-@ref{gnutls_certificate_set_verify_flags} with the
-@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2} or
-@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} flag, as in:
-
-@example
-  gnutls_certificate_set_verify_flags (x509cred,
-                                       GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5);
-@end example
-
-This will tell the verifier algorithm to enable @code{RSA-MD5} when
-verifying the certificates.
-
-If you are using @ref{gnutls_x509_crt_verify} or
-@ref{gnutls_x509_crt_list_verify}, you can pass the
-@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} parameter directly in the
-@code{flags} parameter.
-
-If you are using these flags, it may also be a good idea to warn the
-user when verification failure occur for this reason.  The simplest is
-to not use the flags by default, and only fall back to using them
-after warning the user.  If you wish to inspect the certificate chain
-yourself, you can use @ref{gnutls_certificate_get_peers} to extract
-the raw server's certificate chain, then use
-@ref{gnutls_x509_crt_import} to parse each of the certificates, and
-then use @ref{gnutls_x509_crt_get_signature_algorithm} to find out the
-signing algorithm used for each certificate.  If any of the
-intermediary certificates are using @code{GNUTLS_SIGN_RSA_MD2} or
-@code{GNUTLS_SIGN_RSA_MD5}, you could present a warning.
-
-
-
-@node How to use TLS in application protocols
-@chapter How To Use @acronym{TLS} in Application Protocols
-
-This chapter is intended to provide some hints on how to use the
-@acronym{TLS} over simple custom made application protocols.  The
-discussion below mainly refers to the @emph{TCP/IP} transport layer
-but may be extended to other ones too.
-
-@menu
-* Separate ports::
-* Upward negotiation::
-@end menu
-
-@node Separate ports
-@section Separate Ports
-
-Traditionally @acronym{SSL} was used in application protocols by
-assigning a new port number for the secure services. That way two
-separate ports were assigned, one for the non secure sessions, and one
-for the secured ones. This has the benefit that if a user requests a
-secure session then the client will try to connect to the secure port
-and fail otherwise. The only possible attack with this method is a
-denial of service one. The most famous example of this method is the
-famous ``HTTP over TLS'' or @acronym{HTTPS} protocol @xcite{RFC2818}.
-
-Despite its wide use, this method is not as good as it seems.  This
-approach starts the @acronym{TLS} Handshake procedure just after the
-client connects on the ---so called--- secure port.  That way the
-@acronym{TLS} protocol does not know anything about the client, and
-popular methods like the host advertising in HTTP do not
-work@footnote{See also the Server Name Indication extension on
-@ref{serverind}.}.  There is no way for the client to say ``I
-connected to YYY server'' before the Handshake starts, so the server
-cannot possibly know which certificate to use.
-
-Other than that it requires two separate ports to run a single
-service, which is unnecessary complication. Due to the fact that there
-is a limitation on the available privileged ports, this approach was
-soon obsoleted.
-
-@node Upward negotiation
-@section Upward Negotiation
-
-Other application protocols@footnote{See LDAP, IMAP etc.}  use a
-different approach to enable the secure layer.  They use something
-called the ``TLS upgrade'' method. This method is quite tricky but it
-is more flexible. The idea is to extend the application protocol to
-have a ``STARTTLS'' request, whose purpose it to start the TLS
-protocols just after the client requests it.  This is a really neat
-idea and does not require an extra port.
-
-This method is used by almost all modern protocols and there is even
-the @xcite{RFC2817} paper which proposes extensions to HTTP to support
-it.
-
-The tricky part, in this method, is that the ``STARTTLS'' request is
-sent in the clear, thus is vulnerable to modifications.  A typical
-attack is to modify the messages in a way that the client is fooled
-and thinks that the server does not have the ``STARTTLS'' capability.
-See a typical conversation of a hypothetical protocol:
-
-@quotation
-(client connects to the server)
-
-CLIENT: HELLO I'M MR. XXX
-
-SERVER: NICE TO MEET YOU XXX
-
-CLIENT: PLEASE START TLS
-
-SERVER: OK
-
-*** TLS STARTS
-
-CLIENT: HERE ARE SOME CONFIDENTIAL DATA
-@end quotation
-
-And see an example of a conversation where someone is acting
-in between:
-
-@quotation
-(client connects to the server)
-
-CLIENT: HELLO I'M MR. XXX
-
-SERVER: NICE TO MEET YOU XXX
-
-CLIENT: PLEASE START TLS
-
-(here someone inserts this message)
-
-SERVER: SORRY I DON'T HAVE THIS CAPABILITY
-
-CLIENT: HERE ARE SOME CONFIDENTIAL DATA
-@end quotation
-
-As you can see above the client was fooled, and was dummy enough to
-send the confidential data in the clear.
-
-How to avoid the above attack? As you may have already thought this
-one is easy to avoid. The client has to ask the user before it
-connects whether the user requests @acronym{TLS} or not. If the user
-answered that he certainly wants the secure layer the last
-conversation should be:
-
-@quotation
-(client connects to the server)
-
-CLIENT: HELLO I'M MR. XXX
-
-SERVER: NICE TO MEET YOU XXX
-
-CLIENT: PLEASE START TLS
-
-(here someone inserts this message)
-
-SERVER: SORRY I DON'T HAVE THIS CAPABILITY
-
-CLIENT: BYE
-
-(the client notifies the user that the secure connection was not possible)
-@end quotation
-
-This method, if implemented properly, is far better than the
-traditional method, and the security properties remain the same, since
-only denial of service is possible. The benefit is that the server may
-request additional data before the @acronym{TLS} Handshake protocol
-starts, in order to send the correct certificate, use the correct
-password file@footnote{in @acronym{SRP} authentication}, or anything
-else!
-
-@node How to use GnuTLS in applications
-@chapter How To Use @acronym{GnuTLS} in Applications
-@anchor{examples}
-@cindex Example programs
-
-@menu
-* Preparation::
-* Multi-threaded applications::
-* Client examples::
-* Server examples::
-* Miscellaneous examples::
-* Compatibility with the OpenSSL library::
-* Opaque PRF Input TLS Extension::
-* Keying Material Exporters::
-@end menu
-
-@node Preparation
-@section Preparation
-
-To use @acronym{GnuTLS}, you have to perform some changes to your
-sources and your build system. The necessary changes are explained in
-the following subsections.
-
-@menu
-* Headers::
-* Initialization::
-* Version check::
-* Debugging::
-* Building the source::
-@end menu
-
-@node Headers
-@subsection Headers
-
-All the data types and functions of the @acronym{GnuTLS} library are
-defined in the header file @file{gnutls/gnutls.h}.  This must be
-included in all programs that make use of the @acronym{GnuTLS}
-library.
-
-The extra functionality of the @acronym{GnuTLS-extra} library is
-available by including the header file @file{gnutls/extra.h} in your
-programs.
-
-@node Initialization
-@subsection Initialization
-
-GnuTLS must be initialized before it can be used.  The library is
-initialized by calling @ref{gnutls_global_init}.  The resources
-allocated by the initialization process can be released if the
-application no longer has a need to call GnuTLS functions, this is
-done by calling @ref{gnutls_global_deinit}.
-
-The extra functionality of the @acronym{GnuTLS-extra} library is
-available after calling @ref{gnutls_global_init_extra}.
-
-In order to take advantage of the internationalisation features in
-GnuTLS, such as translated error messages, the application must set
-the current locale using @code{setlocale} before initializing GnuTLS.
-
-@node Version check
-@subsection Version Check
-
-It is often desirable to check that the version of `gnutls' used is
-indeed one which fits all requirements.  Even with binary
-compatibility new features may have been introduced but due to problem
-with the dynamic linker an old version is actually used.  So you may
-want to check that the version is okay right after program startup.
-See the function @ref{gnutls_check_version}.
-
-@node Debugging
-@subsection Debugging
-
-In many cases things may not go as expected and further information,
-to assist debugging, from @acronym{GnuTLS} is desired. Those are the
-case where the @ref{gnutls_global_set_log_level} and
-@ref{gnutls_global_set_log_function} are to be used. Those will print
-verbose information on the @acronym{GnuTLS} functions internal flow.
-
-@node Building the source
-@subsection Building the Source
-
-If you want to compile a source file including the
-@file{gnutls/gnutls.h} header file, you must make sure that the
-compiler can find it in the directory hierarchy.  This is accomplished
-by adding the path to the directory in which the header file is
-located to the compilers include file search path (via the @option{-I}
-option).
-
-However, the path to the include file is determined at the time the
-source is configured.  To solve this problem, the library uses the
-external package @command{pkg-config} that knows the path to the
-include file and other configuration options.  The options that need
-to be added to the compiler invocation at compile time are output by
-the @option{--cflags} option to @command{pkg-config gnutls}.  The
-following example shows how it can be used at the command line:
-
-@example
-gcc -c foo.c `pkg-config gnutls --cflags`
-@end example
-
-Adding the output of @samp{pkg-config gnutls --cflags} to the
-compilers command line will ensure that the compiler can find the
-@file{gnutls/gnutls.h} header file.
-
-A similar problem occurs when linking the program with the library.
-Again, the compiler has to find the library files.  For this to work,
-the path to the library files has to be added to the library search
-path (via the @option{-L} option).  For this, the option
-@option{--libs} to @command{pkg-config gnutls} can be used.  For
-convenience, this option also outputs all other options that are
-required to link the program with the libarary (for instance, the
-@samp{-ltasn1} option).  The example shows how to link @file{foo.o}
-with the library to a program @command{foo}.
-
-@example
-gcc -o foo foo.o `pkg-config gnutls --libs`
-@end example
-
-Of course you can also combine both examples to a single command by
-specifying both options to @command{pkg-config}:
-
-@example
-gcc -o foo foo.c `pkg-config gnutls --cflags --libs`
-@end example
-
-@node Multi-threaded applications
-@section Multi-Threaded Applications
-
-Although the @acronym{GnuTLS} library is thread safe by design, some
-parts of Libgcrypt, such as the random generator, are not.
-Applications have to register callback functions to ensure proper
-locking in the sensitive parts of @emph{libgcrypt}.
-
-There are helper macros to help you properly initialize the libraries.
-Examples are shown below.
-
-@itemize
-
-@item POSIX threads
-@example
-#include <gnutls.h>
-#include <gcrypt.h>
-#include <errno.h>
-#include <pthread.h>
-GCRY_THREAD_OPTION_PTHREAD_IMPL;
-
-int main() 
-@{
-   /* The order matters.
-    */
-   gcry_control (GCRYCTL_SET_THREAD_CBS, &gcry_threads_pthread);
-   gnutls_global_init();
-@}
-@end example
-
-@item GNU PTH threads
-@example
-#include <gnutls.h>
-#include <gcrypt.h>
-#include <errno.h>
-#include <pth.h>
-GCRY_THREAD_OPTION_PTH_IMPL;
-
-int main() 
-@{
-   gcry_control (GCRYCTL_SET_THREAD_CBS, &gcry_threads_pth);
-   gnutls_global_init();
-@}
-@end example
-
-@item Other thread packages
-@example
-/* The gcry_thread_cbs structure must have been
- * initialized.
- */
-static struct gcry_thread_cbs gcry_threads_other = @{ ... @};
-
-int main()
-@{
-   gcry_control (GCRYCTL_SET_THREAD_CBS, &gcry_threads_other);
-@}
-@end example
-@end itemize
-
-@node Client examples
-@section Client Examples
-
-This section contains examples of @acronym{TLS} and @acronym{SSL}
-clients, using @acronym{GnuTLS}.  Note that these examples contain
-little or no error checking.  Some of the examples require functions
-implemented by another example.
-
-@menu
-* Simple client example with anonymous authentication::
-* Simple client example with X.509 certificate support::
-* Obtaining session information::
-* Verifying peer's certificate::
-* Using a callback to select the certificate to use::
-* Client with Resume capability example::
-* Simple client example with SRP authentication::
-* Simple client example with TLS/IA support::
-* Simple client example in C++::
-* Helper function for TCP connections::
-@end menu
-
-@node Simple client example with anonymous authentication
-@subsection Simple Client Example with Anonymous Authentication
-
-The simplest client using TLS is the one that doesn't do any
-authentication.  This means no external certificates or passwords are
-needed to set up the connection.  As could be expected, the connection
-is vulnerable to man-in-the-middle (active or redirection) attacks.
-However, the data is integrity and privacy protected.
-
-@verbatiminclude examples/ex-client1.c
-
-@node Simple client example with X.509 certificate support
-@subsection Simple Client Example with @acronym{X.509} Certificate Support
-
-Let's assume now that we want to create a TCP client which
-communicates with servers that use @acronym{X.509} or
-@acronym{OpenPGP} certificate authentication. The following client is
-a very simple @acronym{TLS} client, it does not support session
-resuming, not even certificate verification. The TCP functions defined
-in this example are used in most of the other examples below, without
-redefining them.
-
-@verbatiminclude examples/ex-client2.c
-
-@node Obtaining session information
-@subsection Obtaining Session Information
-
-Most of the times it is desirable to know the security properties of
-the current established session.  This includes the underlying ciphers
-and the protocols involved.  That is the purpose of the following
-function.  Note that this function will print meaningful values only
-if called after a successful @ref{gnutls_handshake}.
-
-@verbatiminclude examples/ex-session-info.c
-
-@node Verifying peer's certificate
-@subsection Verifying Peer's Certificate
-@anchor{ex:verify}
-
-A @acronym{TLS} session is not secure just after the handshake
-procedure has finished.  It must be considered secure, only after the
-peer's certificate and identity have been verified. That is, you have
-to verify the signature in peer's certificate, the hostname in the
-certificate, and expiration dates.  Just after this step you should
-treat the connection as being a secure one.
-
-@verbatiminclude examples/ex-rfc2818.c
-
-An other example is listed below which provides a more detailed
-verification output.
-
-@verbatiminclude examples/ex-verify.c
-
-@node Using a callback to select the certificate to use
-@subsection Using a Callback to Select the Certificate to Use
-
-There are cases where a client holds several certificate and key
-pairs, and may not want to load all of them in the credentials
-structure.  The following example demonstrates the use of the
-certificate selection callback.
-
-@verbatiminclude examples/ex-cert-select.c
-
-@subsection Using a Callback to Select a @acronym{PKCS} #11 Certificate
-
-This example will demonstrate how to load keys and certificates
-from a @acronym{PKCS} #11 module, which is typically used
-for keys and certificates stored in smart cards.
-
-@verbatiminclude examples/ex-cert-select-pkcs11.c
-
-@node Client with Resume capability example
-@subsection Client with Resume Capability Example
-@anchor{ex:resume-client}
-
-This is a modification of the simple client example. Here we
-demonstrate the use of session resumption. The client tries to connect
-once using @acronym{TLS}, close the connection and then try to
-establish a new connection using the previously negotiated data.
-
-@verbatiminclude examples/ex-client-resume.c
-
-@node Simple client example with SRP authentication
-@subsection Simple Client Example with @acronym{SRP} Authentication
-
-The following client is a very simple @acronym{SRP} @acronym{TLS}
-client which connects to a server and authenticates using a
-@emph{username} and a @emph{password}. The server may authenticate
-itself using a certificate, and in that case it has to be verified.
-
-@verbatiminclude examples/ex-client-srp.c
-
-@node Simple client example with TLS/IA support
-@subsection Simple Client Example with @acronym{TLS/IA} Support
-
-The following client is a simple client which uses the
-@acronym{TLS/IA} extension to authenticate with the server.
-
-@verbatiminclude examples/ex-client-tlsia.c
-
-@node Simple client example in C++
-@subsection Simple Client Example using the C++ API
-
-The following client is a simple example of a client client utilizing
-the GnuTLS C++ API.
-
-@verbatiminclude examples/ex-cxx.cpp
-
-@node Helper function for TCP connections
-@subsection Helper Function for TCP Connections
-
-This helper function abstracts away TCP connection handling from the
-other examples.  It is required to build some examples.
-
-@verbatiminclude examples/tcp.c
-
-@node Server examples
-@section Server Examples
-
-This section contains examples of @acronym{TLS} and @acronym{SSL}
-servers, using @acronym{GnuTLS}.
-
-@menu
-* Echo Server with X.509 authentication::
-* Echo Server with X.509 authentication II::
-* Echo Server with OpenPGP authentication::
-* Echo Server with SRP authentication::
-* Echo Server with anonymous authentication::
-@end menu
-
-@node Echo Server with X.509 authentication
-@subsection Echo Server with @acronym{X.509} Authentication
-
-This example is a very simple echo server which supports
-@acronym{X.509} authentication, using the RSA ciphersuites.
-
-@verbatiminclude examples/ex-serv1.c
-
-@node Echo Server with X.509 authentication II
-@subsection Echo Server with @acronym{X.509} Authentication II
-
-The following example is a server which supports @acronym{X.509}
-authentication.  This server supports the export-grade cipher suites,
-the DHE ciphersuites and session resuming.
-
-@verbatiminclude examples/ex-serv-export.c
-
-@node Echo Server with OpenPGP authentication
-@subsection Echo Server with @acronym{OpenPGP} Authentication
-@cindex @acronym{OpenPGP} Server
-
-The following example is an echo server which supports
-@acronym{@acronym{OpenPGP}} key authentication. You can easily combine
-this functionality ---that is have a server that supports both
-@acronym{X.509} and @acronym{OpenPGP} certificates--- but we separated
-them to keep these examples as simple as possible.
-
-@verbatiminclude examples/ex-serv-pgp.c
-
-@node Echo Server with SRP authentication
-@subsection Echo Server with @acronym{SRP} Authentication
-
-This is a server which supports @acronym{SRP} authentication. It is
-also possible to combine this functionality with a certificate
-server. Here it is separate for simplicity.
-
-@verbatiminclude examples/ex-serv-srp.c
-
-@node Echo Server with anonymous authentication
-@subsection Echo Server with Anonymous Authentication
-
-This example server support anonymous authentication, and could be
-used to serve the example client for anonymous authentication.
-
-@verbatiminclude examples/ex-serv-anon.c
-
-@node Miscellaneous examples
-@section Miscellaneous Examples
-
-@menu
-* Checking for an alert::
-* X.509 certificate parsing example::
-* Certificate request generation::
-* PKCS #12 structure generation::
-@end menu
-
-@node Checking for an alert
-@subsection Checking for an Alert
-
-This is a function that checks if an alert has been received in the
-current session.
-
-@verbatiminclude examples/ex-alert.c
-
-@node X.509 certificate parsing example
-@subsection @acronym{X.509} Certificate Parsing Example
-@anchor{ex:x509-info}
-
-To demonstrate the @acronym{X.509} parsing capabilities an example program is
-listed below.  That program reads the peer's certificate, and prints
-information about it.
-
-@verbatiminclude examples/ex-x509-info.c
-
-@node Certificate request generation
-@subsection Certificate Request Generation
-@anchor{ex:crq}
-
-The following example is about generating a certificate request, and a
-private key. A certificate request can be later be processed by a CA,
-which should return a signed certificate.
-
-@verbatiminclude examples/ex-crq.c
-
-@node PKCS #12 structure generation
-@subsection @acronym{PKCS} #12 Structure Generation
-@anchor{ex:pkcs12}
-
-The following example is about generating a @acronym{PKCS} #12
-structure.
-
-@verbatiminclude examples/ex-pkcs12.c
-
-@node Compatibility with the OpenSSL library
-@section Compatibility with the OpenSSL Library
-@cindex OpenSSL
-
-To ease @acronym{GnuTLS}' integration with existing applications, a
-compatibility layer with the widely used OpenSSL library is included
-in the @code{gnutls-openssl} library. This compatibility layer is not
-complete and it is not intended to completely reimplement the OpenSSL
-API with @acronym{GnuTLS}.  It only provides source-level
-compatibility. There is currently no attempt to make it
-binary-compatible with OpenSSL.
-
-The prototypes for the compatibility functions are in the
-@file{gnutls/openssl.h} header file.
-
-Current limitations imposed by the compatibility layer include:
-
-@itemize
-
-@item Error handling is not thread safe.
-
-@end itemize
-
-@node Opaque PRF Input TLS Extension
-@section Opaque PRF Input TLS Extension
-@cindex Opaque PRF Input
-
-GnuTLS supports the Opaque PRF Input TLS extension
-(@code{draft-rescorla-tls-opaque-prf-input-00.txt}).  The API consists
-of one API for use in the client, @ref{gnutls_oprfi_enable_client},
-and one API for use in the server, @ref{gnutls_oprfi_enable_server}.
-You must invoke both functions before calling @ref{gnutls_handshake}.
-The server utilizes a callback function into the application.  The
-callback can look at the random string provided by the client, and
-also set the server string.  The string lengths must be equal
-according to the protocol.
-
-@node Keying Material Exporters
-@section Keying Material Exporters
-@cindex Keying Material Exporters
-@cindex Exporting Keying Material
-
-The TLS PRF can be used by other protocols to derive data.  The API to
-use is @ref{gnutls_prf}.  The function needs to be provided with the
-label in the parameter @code{label}, and the extra data to mix in the
-@code{extra} parameter.  Depending on whether you want to mix in the
-client or server random data first, you can set the
-@code{server_random_first} parameter.
-
-For example, after establishing a TLS session using
-@ref{gnutls_handshake}, you can invoke the TLS PRF with this call:
-
-@smallexample
-#define MYLABEL "EXPORTER-FOO"
-#define MYCONTEXT "some context data"
-char out[32];
-rc = gnutls_prf (session, strlen (MYLABEL), MYLABEL, 0,
-                 strlen (MYCONTEXT), MYCONTEXT, 32, out);
-@end smallexample
-
-If you don't want to mix in the client/server random, there is a more
-low-level TLS PRF interface called @ref{gnutls_prf_raw}.
-
-@node Included programs
-@chapter 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::
-@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.
-
-@verbatim
-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-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-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.
-     -l, --crl-info           Print information on a CRL.
-     --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.
-     --fix-key                Regenerate the parameters in a private
-                              key.
-     --to-p12                 Generate a PKCS #12 structure.
-     -8, --pkcs8              Use PKCS #8 format for private keys.
-     --dsa                    Use DSA keys.
-     --hash STR               Hash algorithm to use for signing
-                              (MD5,SHA1,RMD160).
-     --export-ciphers         Use weak encryption algorithms.
-     --inder                  Use DER format for input certificates
-                              and private keys.
-     --outder                 Use DER format for output certificates
-                              and private keys.
-     --bits BITS              specify the number of bits for key
-                              generation.
-     --outfile FILE           Output file.
-     --infile FILE            Input file.
-     --template FILE          Template file to use for non
-                              interactive operation.
-     -d, --debug LEVEL        specify the debug level. Default is 1.
-     -h, --help               shows this help text
-     -v, --version            shows the program's version
-@end verbatim
-
-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.
-
-How to use certtool interactively:
-
-@itemize
-@item
-To generate parameters for Diffie-Hellman key exchange, use the command:
-@example
-$ certtool --generate-dh-params --outfile dh.pem
-@end example
-
-@item
-To generate parameters for the RSA-EXPORT key exchange, use the command:
-@example
-$ certtool --generate-privkey --bits 512 --outfile rsa.pem
-@end example
-
-@end itemize
-
-@itemize
-
-@item
-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.
-
-@item
-To create a private key (RSA by default), run:
-
-@example
-$ certtool --generate-privkey --outfile key.pem
-@end example
-
-To create a DSA private key, run:
-
-@example
-$ certtool --dsa --generate-privkey --outfile key-dsa.pem
-@end example
-
-@item
-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
-
-@item
-To create a certificate request (needed when the certificate is issued by
-another party), run:
-
-@example
-$ certtool --generate-request --load-privkey key.pem \
-  --outfile request.pem
-@end example
-
-@item
-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
-
-@item
-To view the certificate information, use:
-
-@example
-$ certtool --certificate-info --infile cert.pem
-@end example
-
-@item
-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
-@samp{--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
-
-@item
-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
-
-@item
-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
-
-@item
-To verify a Certificate Revocation List (CRL) do:
-
-@example
-$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
-@end example
-
-@end itemize
-
-Certtool's template file format:
-
-@itemize
-
-@item
-Firstly create a file named 'cert.cfg' that contains the information
-about the certificate. An example file is listed below.
-
-@item
-Then execute:
-
-@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
-
-@end itemize
-
-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
-@end example
-
-@node Invoking gnutls-cli
-@section Invoking gnutls-cli
-@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.
-
-@verbatim
-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 verbatim
-
-To connect to a server using PSK authentication, you may use something
-like:
-
-@smallexample
-$ gnutls-cli -p 5556 test.gnutls.org --pskusername jas --pskkey 9e32cf7786321a828ef7668f09fb35db --priority NORMAL:+PSK:-RSA:-DHE-RSA -d 4711
-@end smallexample
-
-@menu
-* Example client PSK connection::
-@end menu
-
-@node Example client PSK connection
-@subsection Example client PSK connection
-@cindex PSK client
-
-If your server only supports the PSK ciphersuite, connecting to it
-should be as simple as connecting to the server:
-
-@smallexample
-$ ./gnutls-cli -p 5556 localhost
-Resolving 'localhost'...
-Connecting to '127.0.0.1:5556'...
-- PSK client callback. PSK hint 'psk_identity_hint'
-Enter PSK identity: psk_identity
-Enter password: 
-- PSK authentication. PSK hint 'psk_identity_hint'
-- Version: TLS1.1
-- Key Exchange: PSK
-- Cipher: AES-128-CBC
-- MAC: SHA1
-- Compression: NULL
-- Handshake was completed
-
-- Simple Client Mode:
-@end smallexample
-
-If the server supports several cipher suites, you may need to force it
-to chose PSK by using a cipher priority parameter such as
-@code{--priority NORMAL:+PSK:-RSA:-DHE-RSA:-DHE-PSK}.
-
-@cindex Netconf
-Instead of using the Netconf-way to derive the PSK key from a
-password, you can also give the PSK username and key directly on the
-command line:
-
-@smallexample
-$ ./gnutls-cli -p 5556 localhost --pskusername psk_identity --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 
-Resolving 'localhost'...
-Connecting to '127.0.0.1:5556'...
-- PSK authentication. PSK hint 'psk_identity_hint'
-- Version: TLS1.1
-- Key Exchange: PSK
-- Cipher: AES-128-CBC
-- MAC: SHA1
-- Compression: NULL
-- Handshake was completed
-
-- Simple Client Mode:
-@end smallexample
-
-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 a more checks will be performed. An example output is:
-
-@smallexample
-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 whether the server can accept a bogus TLS record version in the client hello... 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 LZO compression support (GnuTLS 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 smallexample
-
-@node Invoking gnutls-serv
-@section Invoking gnutls-serv
-@cindex gnutls-serv
-
-Simple server program that listens to incoming TLS connections.
-
-@verbatim
-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 verbatim
-
-@subsection 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.
-
-@example
-srptool --create-conf srp-tpasswd.conf
-srptool --passwd-conf srp-tpasswd.conf --username jas --passwd srp-passwd.txt
-Enter password: [TYPE "foo"]
-@end example
-
-Start the server with SRP support:
-
-@example
-gnutls-serv --http \
-            --srppasswdconf srp-tpasswd.conf \
-            --srppasswd srp-passwd.txt
-@end example
-
-Let's also add support for PSK.
-
-@example
-$ psktool --passwd psk-passwd.txt
-@end example
-
-Start the server with PSK support:
-
-@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
-
-@menu
-* Example server PSK connection::
-@end menu
-
-@node Example server PSK connection
-@subsection Example server PSK connection
-@cindex PSK server
-
-To set up a PSK server with @code{gnutls-serv} you need to create PSK
-password file (@pxref{Invoking psktool}).  In the example below, I
-type @code{password} at the prompt.
-
-@smallexample
-$ ./psktool -u psk_identity -p psks.txt -n psk_identity_hint
-Enter password:
-Key stored to psks.txt
-$ cat psks.txt
-psk_identity:88f3824b3e5659f52d00e959bacab954b6540344
-$
-@end smallexample
-
-After this, start the server pointing to the password file.  We
-disable DHE-PSK.
-
-@smallexample
-$ ./gnutls-serv --pskpasswd psks.txt  --pskhint psk_identity_hint --priority NORMAL:-DHE-PSK
-Set static Diffie-Hellman parameters, consider --dhparams.
-Echo Server ready. Listening to port '5556'.
-@end smallexample
-
-You can now connect to the server using a PSK client (@pxref{Example
-client PSK connection}).
-
-@node Invoking psktool
-@section Invoking psktool
-@cindex psktool
-
-This is a program to manage @acronym{PSK} username and keys.
-
-@verbatim
-PSKtool help
-Usage : psktool [options]
-     -u, --username username
-                              specify username.
-     -p, --passwd FILE        specify a password file.
-     -n, --netconf-hint HINT
-                              derive key from Netconf password, using 
-                              HINT as the psk_identity_hint.
-     -s, --keysize SIZE       specify the key size in bytes.
-     -v, --version            prints the program's version number
-     -h, --help               shows this help text
-@end verbatim
-
-Normally the file will generate random keys for the indicate username.
-You may also derive PSK keys from passwords, using the algorithm
-specified in @file{draft-ietf-netconf-tls-02.txt}.  The algorithm
-needs a PSK identity hint, which you specify using
-@code{--netconf-hint}.  To derive a PSK key from a password with an
-empty PSK identity hint, using @code{--netconf-hint ""}.
-
-@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}, 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.
-
-How to use srptool:
-
-@itemize
-
-@item
-To create tpasswd.conf which holds the g and n values for
-@acronym{SRP} protocol (generator and a large prime), run:
-
-@example
-$ srptool --create-conf /etc/tpasswd.conf
-@end example
-
-@item
-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.
-
-@example
-$ srptool --passwd /etc/tpasswd \
-    --passwd-conf /etc/tpasswd.conf -u test
-@end example
-
-@item
-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
-
-@end itemize
-
-@node Function reference
-@chapter Function Reference
-@cindex Function reference
-
-@menu
-* Core functions::
-* X.509 certificate functions::
-* GnuTLS-extra functions::
-* OpenPGP functions::
-* TLS Inner Application (TLS/IA) functions::
-* Error codes and descriptions::
-@end menu
-
-@node Core functions
-@section Core Functions
-
-The prototypes for the following functions lie in
-@file{gnutls/gnutls.h}.
-
-@include gnutls-api.texi
-
-@node X.509 certificate functions
-@section @acronym{X.509} Certificate Functions
-@anchor{sec:x509api}
-@cindex @acronym{X.509} Functions
-
-The following functions are to be used for @acronym{X.509} certificate handling.
-Their prototypes lie in @file{gnutls/x509.h}.
-
-@include x509-api.texi
-
-@node GnuTLS-extra functions
-@section @acronym{GnuTLS-extra} Functions
-@cindex @acronym{GnuTLS-extra} functions
-
-These functions are only available in the GPLv3+ version of the
-library called @code{gnutls-extra}. The prototypes for this library
-lie in @file{gnutls/extra.h}.
-
-@include extra-api.texi
-
-@node OpenPGP functions
-@section @acronym{OpenPGP} Functions
-@cindex @acronym{OpenPGP} functions
-@anchor{sec:openpgpapi}
-
-The following functions are to be used for @acronym{OpenPGP}
-certificate handling.  Their prototypes lie in
-@file{gnutls/openpgp.h}.
-
-@include pgp-api.texi
-
-@node TLS Inner Application (TLS/IA) functions
-@section @acronym{TLS} Inner Application (@acronym{TLS/IA}) Functions
-@cindex @acronym{TLS} Inner Application (@acronym{TLS/IA}) functions
-@cindex Inner Application (@acronym{TLS/IA}) functions
-
-The following functions are used for @acronym{TLS} Inner Application
-(@acronym{TLS/IA}).  Their prototypes lie in @file{gnutls/extra.h}.
-You need to link with @file{libgnutls-extra} to be able to use these
-functions (@pxref{GnuTLS-extra functions}).
-
-The typical control flow in an TLS/IA client (that would not require
-an Application Phase for resumed sessions) would be similar to the
-following:
-
-@example
-int client_avp (gnuls_session_t *session, void *ptr,
-                const char *last, size_t lastlen,
-		char **new, size_t *newlen)
-@{
-...
-@}
-...
-int main ()
-@{
-  gnutls_ia_client_credentials_t iacred;
-...
-  gnutls_init (&session, GNUTLS_CLIENT);
-...
-  /* Enable TLS/IA. */
-  gnutls_ia_allocate_client_credentials(&iacred);
-  gnutls_ia_set_client_avp_function(iacred, client_avp);
-  gnutls_credentials_set (session, GNUTLS_CRD_IA, iacred);
-...
-  ret = gnutls_handshake (session);
-  // Error handling...
-...
-  if (gnutls_ia_handshake_p (session))
-    @{
-      ret = gnutls_ia_handshake (session);
-      // Error handling...
-...
-@end example
-
-See below for detailed descriptions of all the functions used above.
-
-The function @code{client_avp} would have to be implemented by your
-application.  The function is responsible for handling the AVP data.
-See @code{gnutls_ia_set_client_avp_function} below for more
-information on how that function should be implemented.
-
-The control flow in a typical server is similar to the above, use
-@code{gnutls_ia_server_credentials_t} instead of
-@code{gnutls_ia_client_credentials_t}, and replace the call to the
-client functions with the corresponding server functions.
-
-@include ia-api.texi
-
-@node Error codes and descriptions
-@section Error Codes and Descriptions
-@anchor{Error Codes}
-@cindex Error codes
-
-The error codes used throughout the library are described below.  The
-return code @code{GNUTLS_E_SUCCESS} indicate successful operation, and
-is guaranteed to have the value 0, so you can use it in logical
-expressions.
-
-@include error_codes.texi
-
-@node All the supported ciphersuites in GnuTLS
-@chapter All the Supported Ciphersuites in @acronym{GnuTLS}
-@anchor{ciphersuites}
-@cindex Ciphersuites
-
-@include algorithms.texi
-
-Some additional information regarding some of the algorithms:
-
-@table @code
-@item RSA
-RSA is public key cryptosystem designed by Ronald Rivest, Adi Shamir
-and Leonard Adleman.  It can be used with any hash functions.
-
-@item DSA
-DSA is the USA's Digital Signature Standard.  It uses only the SHA-1
-hash algorithm.
-
-@item MD2
-MD2 is a cryptographic hash algorithm designed by Ron Rivest.  It is
-optimized for 8-bit processors. Outputs 128 bits of data.  There are
-no known weaknesses of this algorithm but since this algorithm is
-rarely used and not really studied it should not be used today.
-
-@item MD5
-MD5 is a cryptographic hash algorithm designed by Ron Rivest. Outputs
-128 bits of data.  It is considered to be broken.
-
-@item SHA-1
-SHA is a cryptographic hash algorithm designed by NSA. Outputs 160
-bits of data.  It is also considered to be broken, though no practical
-attacks have been found.
-
-@item RMD160
-RIPEMD is a cryptographic hash algorithm developed in the framework of
-the EU project RIPE.  Outputs 160 bits of data.
-
-@end table
-
-@c
-@c Guile Bindings
-@c
-
-@include guile.texi
-
-
-@node Internal architecture of GnuTLS
-@chapter Internal Architecture of GnuTLS
-@cindex Internal architecture
-
-This chapter is to give a brief description of the
-way @acronym{GnuTLS} works. The focus is to give an idea
-to potential developers and those who want to know what
-happens inside the black box.
-
-@menu
-* The TLS Protocol::
-* TLS Handshake Protocol::
-* TLS Authentication Methods::
-* TLS Extension Handling::
-* Certificate Handling::
-* Cryptographic Backend::
-@end menu
-
-@node The TLS Protocol
-@section The TLS Protocol
-The main needs for the TLS protocol to be used are
-shown in the image below.
-
-@image{gnutls-client-server-use-case,9cm}
-
-This is being accomplished by the following object diagram.
-Note that since @acronym{GnuTLS} is being developed in C
-object are just structures with attributes. The operations listed
-are functions that require the first parameter to be that object.
-@image{gnutls-objects,15cm}
-
-@node TLS Handshake Protocol
-@section TLS Handshake Protocol
-The @acronym{GnuTLS} handshake protocol is implemented as a state
-machine that waits for input or returns immediately when the non-blocking
-transport layer functions are used. The main idea is shown in the following
-figure.
-
-@image{gnutls-handshake-state,9cm}
-
-Also the way the input is processed varies per ciphersuite. Several 
-implementations of the internal handlers are available and 
-@ref{gnutls_handshake} only multiplexes the input to the appropriate 
-handler. For example a @acronym{PSK} ciphersuite has a different 
-implementation of the @code{process_client_key_exchange} than a
-certificate ciphersuite.
-
-@image{gnutls-handshake-sequence,12cm}
-
-@node TLS Authentication Methods
-@section TLS Authentication Methods
-In @acronym{GnuTLS} authentication methods can be implemented quite
-easily.  Since the required changes to add a new authentication method
-affect only the handshake protocol, a simple interface is used. An
-authentication method needs only to implement the functions as seen in
-the figure below.
-
-@image{gnutls-mod_auth_st,12cm}
-
-The functions that need to be implemented are the ones responsible for
-interpreting the handshake protocol messages. It is common for such
-functions to read data from one or more @code{credentials_t}
-structures@footnote{such as the
-@code{gnutls_certificate_credentials_t} structures} and write data,
-such as certificates, usernames etc. to @code{auth_info_t} structures.
-
-Simple examples of existing authentication methods can be seen in
-@code{auth_psk.c} for PSK ciphersuites and @code{auth_srp.c} for SRP
-ciphersuites. After implementing these functions the structure holding
-its pointers has to be registered in @code{gnutls_algorithms.c} in the
-@code{_gnutls_kx_algorithms} structure.
-
-@node TLS Extension Handling
-@section TLS Extension Handling
-As with authentication methods, the TLS extensions handlers can be
-implemented using the following interface.
-
-@image{gnutls-extensions_st,12cm}
-
-Here there are two functions, one for receiving the extension data
-and one for sending. These functions have to check internally whether
-they operate in client or server side. 
-
-A simple example of an extension handler can be seen in
-@code{ext_srp.c} After implementing these functions, together with the
-extension number they handle, they have to be registered in
-@code{gnutls_extensions.c} in the @code{_gnutls_extensions} structure.
-
-@subsection Adding a New TLS Extension
-
-Adding support for a new TLS extension is done from time to time, and
-the process to do so is not difficult.  Here are the steps you need to
-follow if you wish to do this yourself.  For sake of discussion, let's
-consider adding support for the hypothetical TLS extension
-@code{foobar}.
-
-@enumerate
-
-@item Add @code{configure} option like @code{--enable-foobar} or @code{--disable-foobar}.
-
-Which to chose depends on whether you intend to make the extension be
-enabled by default.  Look at existing checks (i.e., SRP, authz) for
-how to model the code.  For example:
-
-@example
-AC_MSG_CHECKING([whether to disable foobar support])
-AC_ARG_ENABLE(foobar,
-	AS_HELP_STRING([--disable-foobar],
-		[disable foobar support]),
-	ac_enable_foobar=no)
-if test x$ac_enable_foobar != xno; then
- AC_MSG_RESULT(no)
- AC_DEFINE(ENABLE_FOOBAR, 1, [enable foobar])
-else
- ac_full=0
- AC_MSG_RESULT(yes)
-fi
-AM_CONDITIONAL(ENABLE_FOOBAR, test "$ac_enable_foobar" != "no")
-@end example
-
-These lines should go in @code{lib/m4/hooks.m4}.
-
-@item Add IANA extension value to @code{extensions_t} in @code{gnutls_int.h}.
-
-A good name for the value would be GNUTLS_EXTENSION_FOOBAR.  Check
-with @url{http://www.iana.org/assignments/tls-extensiontype-values}
-for allocated values.  For experiments, you could pick a number but
-remember that some consider it a bad idea to deploy such modified
-version since it will lead to interoperability problems in the future
-when the IANA allocates that number to someone else, or when the
-foobar protocol is allocated another number.
-
-@item Add an entry to @code{_gnutls_extensions} in @code{gnutls_extensions.c}.
-
-A typical entry would be:
-
-@example
-  int ret;
-
-  /* ...
-   */
-
-#if ENABLE_FOOBAR
-  ret = gnutls_ext_register (GNUTLS_EXTENSION_FOOBAR,
-                             "FOOBAR",
-                             GNUTLS_EXT_TLS,
-                             _gnutls_foobar_recv_params,
-                             _gnutls_foobar_send_params);
-  if (ret != GNUTLS_E_SUCCESS)
-    return ret;
-#endif
-@end example
-
-The GNUTLS_EXTENSION_FOOBAR is the integer value you added to
-@code{gnutls_int.h} earlier.  The two functions are new functions that
-you will need to implement, most likely you'll need to add an
-@code{#include "ext_foobar.h"} as well.
-
-@item Add new files @code{ext_foobar.c} and @code{ext_foobar.h} that implements the extension.
-
-The functions you are responsible to add are those mentioned in the
-previous step.  As a starter, you could add this:
-
-@example
-int
-_gnutls_foobar_recv_params (gnutls_session_t session,
-                            const opaque * data,
-                            size_t data_size)
-@{
-  return 0;
-@}
-
-int
-_gnutls_foobar_send_params (gnutls_session_t session,
-                            opaque * data,
-                            size_t _data_size)
-@{
-  return 0;
-@}
-@end example
-
-The @code{_gnutls_foobar_recv_params} function is responsible for
-parsing incoming extension data (both in the client and server).
-
-The @code{_gnutls_foobar_send_params} function is responsible for
-sending extension data (both in the client and server).
-
-If you receive length fields that doesn't match, return
-@code{GNUTLS_E_UNEXPECTED_PACKET_LENGTH}.  If you receive invalid
-data, return @code{GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER}.  You can use
-other error codes too.  Return 0 on success.
-
-The function typically store some information in the @code{session}
-variable for later usage.  If you need to add new fields there, check
-@code{tls_ext_st} in @code{gnutls_int.h} and compare with existing TLS
-extension specific variables.
-
-Recall that both the client and server both send and receives
-parameters, and your code most likely will need to do different things
-depending on which mode it is in.  It may be useful to make this
-distinction explicit in the code.  Thus, for example, a better
-template than above would be:
-
-@example
-int
-_gnutls_foobar_recv_params (gnutls_session_t session,
-                            const opaque * data,
-                            size_t data_size)
-@{
-  if (session->security_parameters.entity == GNUTLS_CLIENT)
-    return foobar_recv_client (session, data, data_size);
-  else
-    return foobar_recv_server (session, data, data_size);
-@}
-
-int
-_gnutls_foobar_send_params (gnutls_session_t session,
-                            opaque * data,
-                            size_t data_size)
-@{
-  if (session->security_parameters.entity == GNUTLS_CLIENT)
-    return foobar_send_client (session, data, data_size);
-  else
-    return foobar_send_server (session, data, data_size);
-@}
-@end example
-
-The functions used would be declared as @code{static} functions, of
-the appropriate prototype, in the same file.
-
-When adding the files, you'll need to add them to @code{Makefile.am}
-as well, for example:
-
-@example
-if ENABLE_FOOBAR
-COBJECTS += ext_foobar.c
-HFILES += ext_foobar.h
-endif
-@end example
-
-@item Add API functions to enable/disable the extension.
-
-Normally the client will have one API to request use of the extension,
-and setting some extension specific data.  The server will have one
-API to let the library know that it is willing to accept the
-extension, often this is implemented through a callback but it doesn't
-have to.
-
-The APIs need to be added to @code{includes/gnutls/gnutls.h} or
-@code{includes/gnutls/extra.h} as appropriate.  It is recommended that
-if you don't have a requirement to use the LGPLv2.1+ license for your
-extension, that you place your work under the GPLv3+ license and thus
-in the libgnutls-extra library.
-
-You can implement the API function in the @code{ext_foobar.c} file, or
-if that file ends up becoming rather larger, add a
-@code{gnutls_foobar.c} file.
-
-To make the API available in the shared library you need to add the
-symbol in @code{lib/libgnutls.map} or
-@code{libextra/libgnutls-extra.map} as appropriate, so that the symbol
-is exported properly.
-
-When writing GTK-DOC style documentation for your new APIs, don't
-forget to add @code{Since:} tags to indicate the GnuTLS version the
-API was introduced in.
-
-@end enumerate
-
-@node Certificate Handling
-@section Certificate Handling
-What is provided by the certificate handling functions
-is summarized in the following diagram.
-
-@image{gnutls-certificate-user-use-case,12cm}
-
-@node Cryptographic Backend
-@section Cryptographic Backend
-Several new systems provide hardware assisted cryptographic algorithm
-implementations that offer implementations some orders of magnitude
-faster than the software. For this reason GnuTLS supports by default
-the /dev/crypto device usually found in FreeBSD and OpenBSD system, to
-take advantage of installed hardware. 
-
-In addition it is possible to override parts of the crypto backend or the
-whole. It is possible to override them both at runtime and compile
-time, however here we will discuss the runtime possibility. The API
-available for this functionality is in @code{gnutls/crypto.h} header
-file.
-
-@subsection Override specific algorithms
-When an optimized implementation of a single algorithm is available,
-say a hardware assisted version of @acronym{AES-CBC} then the
-following functions can be used to register those algorithms.
-
-@itemize
-
-@item @ref{gnutls_crypto_single_cipher_register2}
-To register a cipher algorithm.
-
-@ref{gnutls_crypto_single_digest_register2}
-To register a hash (digest) or MAC algorithm.
-
-@end itemize
-
-Those registration functions will only replace the specified algorithm
-and leave the rest of subsystem intact.
-
-@subsection Override parts of the backend
-In some systems, such as embedded ones, it might be desirable to
-override big parts of the cryptographic backend, or even all of
-them. For this reason the following functions are provided.
-
-@itemize
-
-@item @ref{gnutls_crypto_cipher_register2}
-To override the cryptographic algorithms backend.
-
-@item @ref{gnutls_crypto_digest_register2}
-To override the digest algorithms backend.
-
-@item @ref{gnutls_crypto_rnd_register2}
-To override the random number generator backend.
-
-@item @ref{gnutls_crypto_bigint_register2}
-To override the big number number operations backend.
-
-@item @ref{gnutls_crypto_pk_register2}
-To override the public key encryption backend. This is tight to the
-big number operations so either both of them should be updated or care
-must be taken to use the same format.
-
-@end itemize
-
-If all of them are used then GnuTLS will no longer use libgcrypt.
-
-@node Copying Information
-@appendix Copying Information
-
-@menu
-* GNU Free Documentation License::   License for copying this manual.
-* GNU LGPL::                     License for copying the core GnuTLS library.
-* GNU GPL::                      License for copying GnuTLS-extra and tools.
-@end menu
-
-@node GNU Free Documentation License
-@appendixsec GNU Free Documentation License
-
-@cindex FDL, GNU Free Documentation License
-
-@include fdl-1.3.texi
-
-@node GNU LGPL
-@appendixsec GNU Lesser General Public License
-@cindex LGPL, GNU Lesser General Public License
-@cindex License, GNU LGPL
-
-@include lgpl-2.1.texi
-
-@node GNU GPL
-@appendixsec GNU General Public License
-@cindex GPL, GNU General Public License
-@cindex License, GNU GPL
-
-@include gpl-3.0.texi
-
-@node Bibliography
-@unnumbered Bibliography
-
-@table @asis
-
-@item @anchor{CBCATT}[CBCATT]
-Bodo Moeller, "Security of CBC Ciphersuites in SSL/TLS: Problems and
-Countermeasures", 2002, available from
-@url{http://www.openssl.org/~bodo/tls-cbc.txt}.
-
-@item @anchor{GPGH}[GPGH]
-Mike Ashley, "The GNU Privacy Handbook", 2002, available from
-@url{http://www.gnupg.org/gph/en/manual.pdf}.
-
-@item @anchor{GUTPKI}[GUTPKI]
-Peter Gutmann, "Everything you never wanted to know about PKI but were
-forced to find out", Available from
-@url{http://www.cs.auckland.ac.nz/~pgut001/}.
-
-@item @anchor{NISTSP80057}[NISTSP80057]
-NIST Special Publication 800-57, "Recommendation for Key Management -
-Part 1: General (Revised)", March 2007, available from
-@url{http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf}.
-
-@item @anchor{RFC2246}[RFC2246]
-Tim Dierks and Christopher Allen, "The TLS Protocol Version 1.0",
-January 1999, Available from
-@url{http://www.ietf.org/rfc/rfc2246.txt}.
-
-@item @anchor{RFC4346}[RFC4346]
-Tim Dierks and Eric Rescorla, "The TLS Protocol Version 1.1", Match
-2006, Available from @url{http://www.ietf.org/rfc/rfc4346.txt}.
-
-@item @anchor{RFC2440}[RFC2440]
-Jon Callas, Lutz Donnerhacke, Hal Finney and Rodney Thayer, "OpenPGP
-Message Format", November 1998, Available from
-@url{http://www.ietf.org/rfc/rfc2440.txt}.
-
-@item @anchor{RFC4880}[RFC4880]
-Jon Callas, Lutz Donnerhacke, Hal Finney, David Shaw and Rodney
-Thayer, "OpenPGP Message Format", November 2007, Available from
-@url{http://www.ietf.org/rfc/rfc4880.txt}.
-
-@item @anchor{RFC4211}[RFC4211]
-J. Schaad, "Internet X.509 Public Key Infrastructure Certificate
-Request Message Format (CRMF)", September 2005, Available from
-@url{http://www.ietf.org/rfc/rfc4211.txt}.
-
-@item @anchor{RFC2817}[RFC2817]
-Rohit Khare and Scott Lawrence, "Upgrading to TLS Within HTTP/1.1",
-May 2000, Available from @url{http://www.ietf.org/rfc/rfc2817.txt}
-
-@item @anchor{RFC2818}[RFC2818]
-Eric Rescorla, "HTTP Over TLS", May 2000, Available from
-@url{http://www.ietf/rfc/rfc2818.txt}.
-
-@item @anchor{RFC2945}[RFC2945]
-Tom Wu, "The SRP Authentication and Key Exchange System", September
-2000, Available from @url{http://www.ietf.org/rfc/rfc2945.txt}.
-
-@item @anchor{RFC2986}[RFC2986]
-Magnus Nystrom and Burt Kaliski, "PKCS 10 v1.7: Certification Request
-Syntax Specification", November 2000, Available from
-@url{http://www.ietf.org/rfc/rfc2986.txt}.
-
-@item @anchor{PKIX}[PKIX]
-D. Cooper, S. Santesson, S. Farrel, S. Boeyen, R. Housley, W. Polk,
-"Internet X.509 Public Key Infrastructure Certificate and Certificate
-Revocation List (CRL) Profile", May 2008, available from
-@url{http://www.ietf.org/rfc/rfc5280.txt}.
-
-@item @anchor{RFC3749}[RFC3749]
-Scott Hollenbeck, "Transport Layer Security Protocol Compression
-Methods", May 2004, available from
-@url{http://www.ietf.org/rfc/rfc3749.txt}.
-
-@item @anchor{RFC3820}[RFC3820]
-Steven Tuecke, Von Welch, Doug Engert, Laura Pearlman, and Mary
-Thompson, "Internet X.509 Public Key Infrastructure (PKI) Proxy
-Certificate Profile", June 2004, available from
-@url{http://www.ietf.org/rfc/rfc3820}.
-
-@item @anchor{RFC5746}[RFC5746]
-E. Rescorla, M. Ray, S. Dispensa, and N. Oskov, "Transport Layer
-Security (TLS) Renegotiation Indication Extension", February 2010,
-available from @url{http://www.ietf.org/rfc/rfc5746}.
-
-@item @anchor{TLSTKT}[TLSTKT]
-Joseph Salowey, Hao Zhou, Pasi Eronen, Hannes Tschofenig, "Transport
-Layer Security (TLS) Session Resumption without Server-Side State",
-January 2008, available from @url{http://www.ietf.org/rfc/rfc5077}.
-
-@item @anchor{PKCS12}[PKCS12]
-RSA Laboratories, "PKCS 12 v1.0: Personal Information Exchange
-Syntax", June 1999, Available from @url{http://www.rsa.com}.
-
-@item @anchor{RESCORLA}[RESCORLA]
-Eric Rescorla, "SSL and TLS: Designing and Building Secure Systems",
-2001
-
-@item @anchor{SELKEY}[SELKEY]
-Arjen Lenstra and Eric Verheul, "Selecting Cryptographic Key Sizes",
-2003, available from @url{http://www.win.tue.nl/~klenstra/key.pdf}.
-
-@item @anchor{SSL3}[SSL3]
-Alan Freier, Philip Karlton and Paul Kocher, "The SSL Protocol Version
-3.0", November 1996, Available from
-@url{http://wp.netscape.com/eng/ssl3/draft302.txt}.
-
-@item @anchor{STEVENS}[STEVENS]
-Richard Stevens, "UNIX Network Programming, Volume 1", Prentice Hall
-PTR, January 1998
-
-@item @anchor{TLSEXT}[TLSEXT]
-Simon Blake-Wilson, Magnus Nystrom, David Hopwood, Jan Mikkelsen and
-Tim Wright, "Transport Layer Security (TLS) Extensions", June 2003,
-Available from @url{http://www.ietf.org/rfc/rfc3546.txt}.
-
-@item @anchor{TLSPGP}[TLSPGP]
-Nikos Mavrogiannopoulos, "Using OpenPGP keys for TLS authentication",
-April 2004, November 2007. Available from
-@url{http://www.ietf.org/rfc/rfc5081.txt}.
+@include cha-programs.texi
 
-@item @anchor{TLSSRP}[TLSSRP]
-David Taylor, Trevor Perrin, Tom Wu and Nikos Mavrogiannopoulos,
-"Using SRP for TLS Authentication", November 2007. Available from
-@url{http://www.ietf.org/rfc/rfc5054.txt}.
+@include cha-functions.texi
 
-@item @anchor{TLSPSK}[TLSPSK]
-Pasi Eronen and Hannes Tschofenig, "Pre-shared key Ciphersuites for
-TLS", December 2005, Available from
-@url{http://www.ietf.org/rfc/rfc4279.txt}.
+@include cha-ciphersuites.texi
 
-@item @anchor{TOMSRP}[TOMSRP]
-Tom Wu, "The Stanford SRP Authentication Project", Available at
-@url{http://srp.stanford.edu/}.
+@include cha-internals.texi
 
-@item @anchor{WEGER}[WEGER]
-Arjen Lenstra and Xiaoyun Wang and Benne de Weger, "Colliding X.509
-Certificates", Cryptology ePrint Archive, Report 2005/067, Available
-at @url{http://eprint.iacr.org/}.
+@include cha-copying.texi
 
-@end table
+@include cha-bib.texi
 
 @node Function and Data Index
 @unnumbered Function and Data Index
diff --git a/lib/includes/gnutls/pkcs11.h b/lib/includes/gnutls/pkcs11.h
index 1064c5e2cc..40bda70771 100644
--- a/lib/includes/gnutls/pkcs11.h
+++ b/lib/includes/gnutls/pkcs11.h
@@ -147,14 +147,6 @@ int gnutls_pkcs11_copy_x509_privkey(const char* token_url,
 	gnutls_x509_privkey_t crt, const char* label, unsigned int key_usage /*GNUTLS_KEY_* */);
 int gnutls_pkcs11_delete_url(const char* object_url);
 
-/**
- * @brief Release array of certificate references.
- * @param certificates	Array to free.
- * @param ncertificates	Array size.
- * @return gnutls status.
- */
-int gnutls_pkcs11_obj_list_deinit (gnutls_pkcs11_obj_t * , const unsigned int nobjs);
-
 typedef enum {
 	GNUTLS_PKCS11_OBJ_ID_HEX=1,
 	GNUTLS_PKCS11_OBJ_LABEL,
diff --git a/lib/libgnutls.map b/lib/libgnutls.map
index 950ac59590..2acda43b54 100644
--- a/lib/libgnutls.map
+++ b/lib/libgnutls.map
@@ -615,7 +615,6 @@ GNUTLS_2_11
         gnutls_pkcs11_obj_import_url;
         gnutls_pkcs11_obj_export_url;
         gnutls_pkcs11_obj_deinit;
-        gnutls_pkcs11_obj_list_deinit;
         gnutls_pkcs11_obj_list_import_url;
         gnutls_x509_crt_import_pkcs11;
         gnutls_pkcs11_obj_get_type;
diff --git a/lib/pkcs11.c b/lib/pkcs11.c
index 6b658b9b4f..e35dcc1cec 100644
--- a/lib/pkcs11.c
+++ b/lib/pkcs11.c
@@ -2140,8 +2140,20 @@ int gnutls_x509_crt_import_pkcs11( gnutls_x509_crt_t crt, gnutls_pkcs11_obj_t pk
     return gnutls_x509_crt_import(crt, &pkcs11_crt->raw, GNUTLS_X509_FMT_DER);
 }
 
+/**
+ * gnutls_x509_crt_list_import_pkcs11:
+ * @cert: A list of certificates of type #gnutls_x509_crt_t
+ * @cert_max: The maximum size of the list
+ * @objs: A list of PKCS 11 objects
+ *
+ * This function will import a PKCS 11 certificate list to a list of 
+ * #gnutls_x509_crt_t structure. These must not be initialized.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int gnutls_x509_crt_list_import_pkcs11 (gnutls_x509_crt_t * certs,
-    unsigned int cert_max, gnutls_pkcs11_obj_t * const pkcs11_certs,
+    unsigned int cert_max, gnutls_pkcs11_obj_t * const objs,
     unsigned int flags)
 {
     int i, j;
@@ -2154,7 +2166,7 @@ int gnutls_x509_crt_list_import_pkcs11 (gnutls_x509_crt_t * certs,
             goto cleanup;
         }
         
-        ret = gnutls_x509_crt_import_pkcs11( certs[i], pkcs11_certs[i]);
+        ret = gnutls_x509_crt_import_pkcs11( certs[i], objs[i]);
         if (ret < 0) {
             gnutls_assert();
             goto cleanup;