updated function listing.

17 files changed, 703 insertions, 413 deletions

diff --git a/doc/.gitignore b/doc/.gitignore
index 0ea0de13bf..915c30a332 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -26,3 +26,7 @@ guile.toc
 guile.tp
 guile.vr
 guile.vrs
+alerts.texi
+alert-printlist
+latex/alerts.tex
+latex/functions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index e54e5a337e..f3f91de486 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -148,12 +148,12 @@ extra-api.texi: $(srcdir)/../libextra/gnutls_extra.c
 
 # Generated texinfos.
 
-gnutls_TEXINFOS += error_codes.texi algorithms.texi
+gnutls_TEXINFOS += error_codes.texi algorithms.texi alerts.texi
 MAINTAINERCLEANFILES += error_codes.texi algorithms.texi
 
 AM_CPPFLAGS = -I$(top_srcdir)/lib/includes -I$(top_builddir)/lib/includes
 
-noinst_PROGRAMS = errcodes printlist
+noinst_PROGRAMS = errcodes printlist alert-printlist
 
 errcodes_SOURCES = errcodes.c
 errcodes_LDADD = ../lib/libgnutls.la ../gl/libgnu.la
@@ -161,16 +161,22 @@ errcodes_LDADD = ../lib/libgnutls.la ../gl/libgnu.la
 printlist_SOURCES = printlist.c
 printlist_LDADD = ../lib/libgnutls.la ../gl/libgnu.la
 
+alert_printlist_SOURCES = alert-printlist.c
+alert_printlist_LDADD = ../lib/libgnutls.la ../gl/libgnu.la
+
 error_codes.texi: $(top_srcdir)/lib/gnutls_errors.c $(srcdir)/errcodes.c
 	make $(builddir)/errcodes
 	$(builddir)/errcodes > $@-tmp
 	mv -f $@-tmp $@
 
-algorithms.texi: $(srcdir)/printlist.c
-	make $(builddir)/printlist
+algorithms.texi: printlist
 	$(builddir)/printlist > $@-tmp
 	mv -f $@-tmp $@
 
+alerts.texi: alert-printlist
+	$(builddir)/alert-printlist > $@-tmp
+	mv -f $@-tmp $@
+
 # Guile texinfos.
 
 guile_texi = core.c.texi extra.c.texi
diff --git a/doc/alert-printlist.c b/doc/alert-printlist.c
new file mode 100644
index 0000000000..5c38666ecc
--- /dev/null
+++ b/doc/alert-printlist.c
@@ -0,0 +1,140 @@
+/*
+ * Copyright (C) 2008, 2009, 2010 Free Software Foundation, Inc.
+ * Author: Nikos Mavrogiannopoulos
+ *
+ * This file is part of GnuTLS.
+ *
+ * GnuTLS is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * GnuTLS is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <config.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <gnutls/gnutls.h>
+#include <gnutls/x509.h>
+#include <gnutls/openpgp.h>
+
+static void main_texinfo (void);
+static void main_latex(void);
+
+int
+main (int argc, char *argv[])
+{
+  if (argc > 1)
+    main_latex();
+  else
+    main_texinfo();
+    
+  return 0;
+}
+
+static void main_texinfo (void)
+{
+  {
+    size_t i;
+    const char *name;
+    gnutls_kx_algorithm_t kx;
+    gnutls_cipher_algorithm_t cipher;
+    gnutls_mac_algorithm_t mac;
+    gnutls_protocol_t version;
+
+    printf ("Available alert messages:\n");
+    
+    printf ("@multitable @columnfractions .55 .10 .30\n@anchor{tab:alerts}\n");
+    for (i = 0; i<256;i++)
+      {
+        if (gnutls_alert_get_strname(i)==NULL) continue;
+        printf ("@item %s\n@tab %d\n@tab %s\n",
+                gnutls_alert_get_strname(i),
+                (unsigned int) i, gnutls_alert_get_name (i));
+      }
+    printf ("@end multitable\n");
+
+  }
+}
+
+static const char headers[] = "\\tablefirsthead{%\n"
+	"\\hline\n"
+	"Alert & ID & Description\\\\\n"
+	"\\hline}\n"
+	"\\tablehead{%\n"
+	"\\hline\n"
+	"\\multicolumn{3}{|l|}{\\small\\sl continued from previous page}\\\\\n"
+	"\\hline\n"
+	"Alert & ID & Description\\\\\n"
+	"\\hline}\n"
+	"\\tabletail{%\n"
+	"\\hline\n"
+	"\\multicolumn{3}{|r|}{\\small\\sl continued on next page}\\\\\n"
+	"\\hline}\n"
+	"\\tablelasttail{\\hline}\n"
+	"\\bottomcaption{The TLS alert table}\n\n";
+
+static char* escape_string( const char* str)
+{
+static char buffer[500];
+int i = 0, j = 0;
+
+
+while( str[i] != 0 && j < sizeof(buffer) - 1) {
+   if (str[i]=='_') {
+      buffer[j++] = '\\';
+      buffer[j++] = '_';
+   } else {
+      buffer[j++] = str[i];
+   }
+   i++;
+};
+
+buffer[j] = 0;
+
+return buffer;
+
+}
+
+static void main_latex(void)
+{
+int i, j;
+const char* desc;
+const char* _name;
+
+puts( headers);
+
+printf("\\begin{supertabular}{|l|p{1cm}|p{3.5cm}|}\n\\label{tab:alerts}\n");
+
+  {
+    size_t i;
+    const char *name;
+    gnutls_kx_algorithm_t kx;
+    gnutls_cipher_algorithm_t cipher;
+    gnutls_mac_algorithm_t mac;
+    gnutls_protocol_t version;
+
+    for (i = 0; i<256;i++)
+      {
+        if (gnutls_alert_get_strname(i)==NULL) continue;
+        printf ("{\\small{%s}} & \\code{%d} & %s",
+                escape_string(gnutls_alert_get_strname(i)),
+                (unsigned int) i, gnutls_alert_get_name (i));
+        printf( "\\\\\n");
+      }
+
+    printf("\\end{supertabular}\n\n");
+
+  }
+
+return;
+
+}
diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi
index 9f85e2ff10..4512416164 100644
--- a/doc/cha-auth.texi
+++ b/doc/cha-auth.texi
@@ -18,6 +18,14 @@ are:
 
 @end itemize
 
+The rule for each method is to allocate a credentials
+structure containing data required for authentication and
+associate that structure with the session using
+@funcref{gnutls_credentials_set}. In the next paragraphs
+we elaborate on supported authentication methods.
+
+@showfuncA{gnutls_credentials_set}
+
 @menu
 * Certificate authentication::
 * Anonymous authentication::
@@ -70,35 +78,37 @@ 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 @funcref{gnutls_certificate_server_set_retrieve_function}
+@showfuncE{gnutls_certificate_set_x509_key,gnutls_certificate_set_x509_key_mem,gnutls_certificate_set_openpgp_key,gnutls_certificate_set_openpgp_key_file,gnutls_certificate_set_openpgp_key_mem}
 
-@item @funcref{gnutls_certificate_client_set_retrieve_function}
+@showfuncdesc{gnutls_certificate_set_x509_key_file}
 
-@end itemize
+@showfuncdesc{gnutls_certificate_set_retrieve_function}
 
-Clients and servers that will select certificates using callback
-functions should select a certificate according the peer's signature
+As an alternative, a callback may be used so the server or the client
+specifies the certificate and the key at the handshake time
+using @funcref{gnutls_certificate_set_retrieve_function}. 
+In that case a certificate should be selected according the peer's signature
 algorithm preferences. To get those preferences use
 @funcref{gnutls_sign_algorithm_get_requested}.
 
+@showfuncA{gnutls_sign_algorithm_get_requested}
+
+
 Certificate verification is possible by loading the trusted
 authorities into the credentials structure by using
 @funcref{gnutls_certificate_set_x509_trust_file} or
 @funcref{gnutls_certificate_set_openpgp_keyring_file} for openpgp
 keys. Note however that the peer's certificate is not automatically
 verified, you should call @funcref{gnutls_certificate_verify_peers2},
-after a successful handshake, to verify the signatures of the
-certificate.  An alternative way, which reports a more detailed
+after a successful handshake or during if @funcref{nutls_certificate_set_verify_function}
+has been used, to verify the certificate's signature.
+An alternative way, which reports a more detailed
 verification output, is to use @funcref{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}.
 
+@showfuncdesc{gnutls_certificate_verify_peers2}
+
 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
@@ -112,6 +122,8 @@ and a different key for the plain RSA ciphersuites, which use
 encryption.  All the key exchange methods shown below are available in
 certificate authentication.
 
+@showfuncdesc{gnutls_certificate_set_verify_function}
+
 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.  See @ref{Selecting cryptographic key sizes}
@@ -250,6 +262,8 @@ Alternatively @funcref{gnutls_srp_set_client_credentials_function}
 may be used to specify a callback function.
 The callback will be called once during the @acronym{TLS} handshake.
 
+@showfuncB{gnutls_srp_set_client_credentials,gnutls_srp_set_client_credentials_function}
+
 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}
@@ -259,23 +273,19 @@ password file format is to be used, then
 @funcref{gnutls_srp_set_server_credentials_function} should be called,
 to set an appropriate callback.
 
-Some helper functions such as
-
-@itemize
+@showfuncdesc{gnutls_srp_set_server_credentials_file}
 
-@item @funcref{gnutls_srp_verifier}
+@showfuncdesc{gnutls_srp_set_server_credentials_function}
 
-@item @funcref{gnutls_srp_base64_encode}
-
-@item @funcref{gnutls_srp_base64_decode}
-
-@end itemize
-
-are included in @acronym{GnuTLS}, and can be used to generate and
+Helper functions 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.  See @ref{srptool}, for more information.
 
+@showfuncdesc{gnutls_srp_verifier}
+
+@showfuncB{gnutls_srp_base64_encode,gnutls_srp_base64_decode}
+
 
 @node Authentication using PSK
 @section Authentication using @acronym{PSK}
@@ -298,6 +308,10 @@ Authentication using the @acronym{PSK} protocol.
 Authentication using the @acronym{PSK} protocol and Diffie-Hellman key
 exchange.  This method offers perfect forward secrecy.
 
+@item ECDHE-PSK:
+Authentication using the @acronym{PSK} protocol and Elliptic curve Diffie-Hellman key
+exchange.  This method offers perfect forward secrecy.
+
 @end table
 
 Clients supporting @acronym{PSK} should supply the username and key
@@ -308,6 +322,8 @@ specify a callback function. This has the
 advantage that the callback will be called only if @acronym{PSK} has
 been negotiated.
 
+@showfuncB{gnutls_psk_set_client_credentials,gnutls_psk_set_client_credentials_function}
+
 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
@@ -324,18 +340,16 @@ A server, may specify the hint by calling
 the hint, for example in the callback function, using
 @funcref{gnutls_psk_client_get_hint}.
 
-Some helper functions such as:
-
-@itemize
+@showfuncdesc{gnutls_psk_set_server_credentials_file}
 
-@item @funcref{gnutls_hex_encode}
+@showfuncC{gnutls_psk_set_server_credentials_function,gnutls_psk_set_server_credentials_hint,gnutls_psk_client_get_hint}
 
-@item @funcref{gnutls_hex_decode}
+Helper functions are included in @acronym{GnuTLS}, and may be used to generate and
+maintain @acronym{PSK} keys.
 
-@end itemize
+@showfuncdesc{gnutls_hex_encode}
 
-are included in @acronym{GnuTLS}, and may be used to generate and
-maintain @acronym{PSK} keys.
+@showfuncdesc{gnutls_hex_decode}
 
 
 @node Authentication and credentials
diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index 26ca9fd2ae..6b4daf5211 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -136,7 +136,7 @@ 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}.
+@ref{ex:x509-info}.
 
 @node Verifying X.509 certificate paths
 @subsection Verifying @acronym{X.509} Certificate Paths
@@ -147,36 +147,13 @@ Verifying certificate paths is important in @acronym{X.509}
 authentication. For this purpose the following functions are
 provided.
 
-@table @code
-
-@item @funcref{gnutls_x509_trust_list_init}:
-A function to initialize a list that will hold trusted
-certificate authorities and certificate revocation lists.
-
-@item @funcref{gnutls_x509_trust_list_deinit}:
-Deinitializes the list.
-
-@item @funcref{gnutls_x509_trust_list_add_cas}:
-Adds certificate authorities to the list.
-
-@item @funcref{gnutls_x509_trust_list_add_named_crt}:
-Adds trusted certificates for an entity identified
-by a name.
-
-@item @funcref{gnutls_x509_trust_list_add_crls}:
-Adds certificate revocation lists.
-
-@item @funcref{gnutls_x509_trust_list_verify_crt}:
-Verifies a certificate chain using the previously setup trusted
-list. A callback can be specified that will provide information
-about the verification procedure (and detailed reasons of failure).
-
-@item @funcref{gnutls_x509_trust_list_verify_named_crt}:
-Does verification of the certificate by looking for a matching one
-in the named certificates. A callback can be specified that will provide information
-about the verification procedure (and detailed reasons of failure).
-
-@end table
+@showfuncdesc{gnutls_x509_trust_list_init}
+@showfuncdesc{gnutls_x509_trust_list_deinit}
+@showfuncdesc{gnutls_x509_trust_list_add_cas}
+@showfuncdesc{gnutls_x509_trust_list_add_named_crt}
+@showfuncdesc{gnutls_x509_trust_list_add_crls}
+@showfuncdesc{gnutls_x509_trust_list_verify_crt}
+@showfuncdesc{gnutls_x509_trust_list_verify_named_crt}
 
 The verification function will verify a given certificate chain against a list of certificate
 authorities and certificate revocation lists, and output
@@ -185,9 +162,7 @@ enumeration. It is also possible to have a set of certificates that
 are trusted for a particular server but not to authorize other certificates.
 This purpose is served by the functions @funcref{gnutls_x509_trust_list_add_named_crt} and @funcref{gnutls_x509_trust_list_verify_named_crt}.
 A detailed description of these elements can be found 
-in figure below. An example of these functions in use can be found
-in @ref{ex:verify2}.
-
+in @ref{tab:cert-verify}. An example of certificate verification is shown in @ref{ex:verify2}.
 
 When operating in the context of a TLS session, the trusted certificate
 authority list has been set via the
@@ -195,8 +170,7 @@ authority list has been set via the
 thus it is not required to setup a trusted list as above.
 Convenience functions such as @funcref{gnutls_certificate_verify_peers2} 
 are equivalent and will verify the peer's certificate chain
-in a TLS session. The certificate verification functions output
-codes as in @ref{tab:cert-verify}.
+in a TLS session. 
 
 @float Table,tab:cert-verify
 @multitable @columnfractions .55 .45
@@ -299,9 +273,12 @@ password. @acronym{GnuTLS} supports the requests defined in
 @acronym{PKCS} #10 @xcite{RFC2986}. Other certificate request's format
 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}.
+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.
+
+@anchor{ex:crq}
+@verbatiminclude examples/ex-crq.c
 
 @node PKCS 12 structures
 @subsection @acronym{PKCS} #12 Structures
@@ -319,7 +296,9 @@ 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}.
+below.
+
+@verbatiminclude examples/ex-pkcs12.c
 
 @node The OpenPGP trust model
 @section The @acronym{OpenPGP} Trust Model
@@ -367,7 +346,7 @@ 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
+GPGME@footnote{@url{http://www.gnupg.org/related_software/gpgme/}} is
 recommended.
 
 There is one verification function in @acronym{GnuTLS}, the
@@ -419,7 +398,7 @@ Moreover it can be used to allow all applications in the same operating system t
 shared cryptographic keys and certificates in a uniform way, as in @ref{fig:pkcs11-vision}.
 
 @float Figure,fig:pkcs11-vision
-@image{pkcs11-vision,8cm}
+@image{pkcs11-vision,9cm}
 @caption{PKCS #11 module usage.}
 @end float
 
@@ -428,28 +407,20 @@ To allow all the  @acronym{GnuTLS} applications to access @acronym{PKCS} #11 tok
 it is adviceable to use @code{/etc/pkcs11/modules/mymodule.conf}. This file has the following
 format:
 
-@verbatim
+@smallexample
 module: /usr/lib/opensc-pkcs11.so
-@end verbatim
+@end smallexample
 
 If you use this file, then there is no need for other initialization in
 @acronym{GnuTLS}, except for the PIN and token functions. Those allow retrieving a PIN
 when accessing a protected object, such as a private key, as well as probe
 the user to insert the token. All the initialization functions are below.
 
-@itemize
-
-@item @funcref{gnutls_pkcs11_init}: Global initialization
-
-@item @funcref{gnutls_pkcs11_deinit}: Global deinitialization
-
-@item @funcref{gnutls_pkcs11_set_token_function}: Sets the token insertion function
-
-@item @funcref{gnutls_pkcs11_set_pin_function}: Sets the PIN request function
-
-@item @funcref{gnutls_pkcs11_add_provider}: Adds an additional @acronym{PKCS} #11 provider
-
-@end itemize
+@showfuncdesc{gnutls_pkcs11_init}
+@showfuncdesc{gnutls_pkcs11_deinit}
+@showfuncdesc{gnutls_pkcs11_set_token_function}
+@showfuncdesc{gnutls_pkcs11_set_pin_function}
+@showfuncdesc{gnutls_pkcs11_add_provider}
 
 Note that due to limitations of @acronym{PKCS} #11 there are issues when multiple libraries 
 are sharing a module. To avoid this problem GnuTLS uses p11-kit@footnote{@url{http://p11-glue.freedesktop.org/}}
@@ -474,48 +445,31 @@ pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe
 @end example
 
 
-Objects can be accessed with the following functions
-@itemize
-
-@item @funcref{gnutls_pkcs11_obj_init}: Initializes an object
-
-@item @funcref{gnutls_pkcs11_obj_import_url}: To import an object from a url
-
-@item @funcref{gnutls_pkcs11_obj_export_url}: To export the URL of the object
-
-@item @funcref{gnutls_pkcs11_obj_deinit}: To deinitialize an object
-
-@item @funcref{gnutls_pkcs11_obj_export}: To export data associated with object
-
-@item @funcref{gnutls_pkcs11_obj_get_info}: To obtain information about an object
+@acronym{PKCS} #11 objects can be accessed with the functions shown below.
 
-@item @funcref{gnutls_pkcs11_obj_list_import_url}: To mass load of objects
+@showfuncB{gnutls_pkcs11_obj_init,gnutls_pkcs11_obj_deinit}
 
-@item @funcref{gnutls_x509_crt_import_pkcs11}: Import a certificate object
+@showfuncdesc{gnutls_pkcs11_obj_import_url}
 
-@item @funcref{gnutls_x509_crt_import_pkcs11_url}: Helper function to directly import a URL into a certificate
-
-@item @funcref{gnutls_x509_crt_list_import_pkcs11}: Mass import of certificates
-
-@end itemize
-
-
-Functions that relate to token handling are shown below
-@itemize
+@showfuncdesc{gnutls_pkcs11_obj_export_url}
 
-@item @funcref{gnutls_pkcs11_token_init}: Initializes a token
+@showfuncdesc{gnutls_pkcs11_obj_export}
 
-@item @funcref{gnutls_pkcs11_token_set_pin}: Sets the token user's PIN
+@showfuncdesc{gnutls_pkcs11_obj_get_info}
 
-@item @funcref{gnutls_pkcs11_token_get_url}: Returns the URL of a token
+@showfuncdesc{gnutls_pkcs11_obj_list_import_url}
 
-@item @funcref{gnutls_pkcs11_token_get_info}: Obtain information about a token
+@showfuncC{gnutls_x509_crt_import_pkcs11,gnutls_x509_crt_import_pkcs11_url,gnutls_x509_crt_list_import_pkcs11}
 
-@item @funcref{gnutls_pkcs11_token_get_flags}: Returns flags about a token (i.e. hardware or software)
+Functions that relate to token handling are shown below.
 
-@end itemize
+@showfuncdesc{gnutls_pkcs11_token_init}
+@showfuncdesc{gnutls_pkcs11_token_set_pin}
+@showfuncdesc{gnutls_pkcs11_token_get_url}
+@showfuncdesc{gnutls_pkcs11_token_get_info}
+@showfuncdesc{gnutls_pkcs11_token_get_flags}
 
-The following example will list all tokens.
+The following example will list all available PKCS #11 tokens in a system.
 @example
 int i;
 char* url;
@@ -538,8 +492,8 @@ gnutls_global_deinit();
 @end example
 
 
-The next one will list all certificates in a token, that have a corresponding
-private key:
+That example will only list all certificates in a token that have a corresponding
+private key.
 @verbatiminclude examples/ex-pkcs11-list.c
 
 @subsection Writing Objects
@@ -547,15 +501,9 @@ private key:
 With @acronym{GnuTLS} you can copy existing private keys and certificates
 to a token. This can be achieved with the following functions
 
-@itemize
-
-@item @funcref{gnutls_pkcs11_delete_url}: To delete an object
-
-@item @funcref{gnutls_pkcs11_copy_x509_privkey}: To copy a private key to a token
-
-@item @funcref{gnutls_pkcs11_copy_x509_crt}: To copy a certificate to a token
-
-@end itemize
+@showfuncdesc{gnutls_pkcs11_delete_url}
+@showfuncdesc{gnutls_pkcs11_copy_x509_privkey}
+@showfuncdesc{gnutls_pkcs11_copy_x509_crt}
 
 
 @subsection Using a @acronym{PKCS} #11 token with TLS
@@ -565,13 +513,7 @@ session, as shown in @ref{ex:pkcs11-client}. In addition
 the following functions can be used to load PKCS #11 key and
 certificates.
 
-@itemize
-
-@item @funcref{gnutls_certificate_set_x509_trust_file}: If given a PKCS #11 URL will load the trusted certificates from it.
-
-@item @funcref{gnutls_certificate_set_x509_key_file}: Will also load PKCS #11 URLs for keys and certificates.
-
-@end itemize
+@showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file}
 
 
 @node Abstract key types
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index c30d2be524..6c4f21e511 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -230,7 +230,7 @@ functions to verify a given certificate list.
 @verbatiminclude examples/ex-verify.c
 
 @node Client using a PKCS 11 token with TLS
-@subsection Using a @acronym{PKCS #11} token with TLS
+@subsection Using a @acronym{PKCS} #11 token with TLS
 @anchor{ex:pkcs11-client}
 
 This example will demonstrate how to load keys and certificates
@@ -333,8 +333,6 @@ used to serve the example client for anonymous authentication.
 @menu
 * Checking for an alert::
 * X.509 certificate parsing example::
-* Certificate request generation::
-* PKCS 12 structure generation::
 @end menu
 
 @node Checking for an alert
@@ -355,25 +353,6 @@ 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 Advanced and other topics
 @section Advanced and other topics
 
@@ -400,12 +379,14 @@ The parameters can be used in a session by calling
 @funcref{gnutls_certificate_set_dh_params} or
 @funcref{gnutls_anon_set_server_dh_params} for anonymous sessions.
 
+@showfuncD{gnutls_dh_params_generate2,gnutls_dh_params_import_pkcs3,gnutls_certificate_set_dh_params,gnutls_anon_set_server_dh_params}
+
 Due to the time-consuming calculations required for the generation
 of Diffie-Hellman parameters we suggest against performing generation
 of them within an application. The @code{certtool} tool can be used to 
 generate or export known safe values that can be stored in code
 or in a configuration file to provide the ability to replace. We also
-recommend the usage of @funcref{gnutls_sec_param_to_pk_bits} to determine
+recommend the usage of @funcref{gnutls_sec_param_to_pk_bits} (see @ref{Selecting cryptographic key sizes}) to determine
 the bit size of the parameters to be generated.
 
 The ciphersuites that involve the RSA-EXPORT key exchange require
@@ -416,17 +397,7 @@ requires 512-bit RSA keys to be generated. It is recommended those
 parameters to be refreshed (regenerated) in short intervals. The
 following functions can be used for these parameters.
 
-@itemize
-
-@item @funcref{gnutls_rsa_params_generate2}
-
-@item @funcref{gnutls_certificate_set_rsa_export_params}
-
-@item @funcref{gnutls_rsa_params_import_pkcs1}
-
-@item @funcref{gnutls_rsa_params_export_pkcs1}
-
-@end itemize
+@showfuncD{gnutls_rsa_params_generate2,gnutls_certificate_set_rsa_export_params,gnutls_rsa_params_import_pkcs1,gnutls_rsa_params_export_pkcs1}
 
 
 @node Keying Material Exporters
diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
index 8a2cf552f5..7c446e86d6 100644
--- a/doc/cha-intro-tls.texi
+++ b/doc/cha-intro-tls.texi
@@ -36,17 +36,17 @@ noted otherwise.
 @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
+@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
+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'
+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 @ref{fig:tls-layers}.
@@ -60,30 +60,28 @@ protocol.  The protocol layering in TLS is shown in @ref{fig:tls-layers}.
 @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
+@acronym{TLS} is not limited to any transport layer and can be used
+above any transport layer, as long as it is a reliable one.  @acronym{DTLS}
+can be used over reliable and unreliable transport layers.
+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 @funcref{gnutls_transport_set_push_function}
-@item @funcref{gnutls_transport_set_vec_push_function}
-@item @funcref{gnutls_transport_set_pull_timeout_function} (for @acronym{DTLS} only)
-@item @funcref{gnutls_transport_set_pull_function}
-@item @funcref{gnutls_transport_set_ptr}
-@item @funcref{gnutls_transport_set_errno}
-@end itemize
+@showfuncE{gnutls_transport_set_push_function,gnutls_transport_set_vec_push_function,gnutls_transport_set_pull_timeout_function,gnutls_transport_set_pull_function,gnutls_transport_set_ptr}
 
-These functions accept a callback function as a parameter.  The
+The function @funcref{gnutls_transport_set_pull_timeout_function} is only applicable
+to @acronym{DTLS} sessions.
+All those 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
+you, call @funcref{gnutls_transport_set_errno} with the intended errno
 value instead of setting @code{errno} directly.
 
+@showfuncA{gnutls_transport_set_errno}
+
 @acronym{GnuTLS} currently only interprets the EINTR and EAGAIN errno
 values and returns the corresponding @acronym{GnuTLS} error codes:
 @itemize
@@ -102,35 +100,21 @@ timers and waiting for peer's messages during the handshake process,
 blocking operation of @acronym{GnuTLS} during @acronym{DTLS} handshake
 can be changed using the appropriate flags in @funcref{gnutls_init}.
 
+@showfuncdesc{gnutls_init}
+
 By default, if the transport functions are not set, @acronym{GnuTLS}
-will use the Berkeley Sockets functions. 
+will use the Berkeley sockets. 
 
 @node The TLS record protocol
 @section The TLS Record Protocol
 @cindex Record protocol
 
-The Record protocol is the secure communications provider. Its purpose
+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 @funcref{gnutls_record_send}:
-To send a record packet with application data.
-
-@item @funcref{gnutls_record_recv}:
-To receive a record packet with application data.
 
-@item @funcref{gnutls_record_recv_seq}:
-To receive a record packet with application data as well
-as the sequence number of that. This is useful in @acronym{DTLS}
-where packets might be lost or received out of order.
+@showfuncdesc{gnutls_record_send}
 
-@item @funcref{gnutls_record_get_direction}:
-To get the direction of the last interrupted function call.
-@end table
-
-In @acronym{TLS} those functions can be called at any time after
+The record layer functions can be called at any time after
 the handshake process is finished, when there is need to receive
 or send data. In @acronym{DTLS} however, due to re-transmission
 timers used in the handshake out-of-order handshake data might
@@ -140,15 +124,20 @@ should call @funcref{gnutls_record_recv} or @funcref{gnutls_record_recv_seq}
 for every packet received by the peer, even if no data were
 expected. 
 
-As you may have already noticed, the functions which access the Record
+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.
+@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
+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.
 
+@showfuncdesc{gnutls_record_recv}
+@showfuncdesc{gnutls_record_recv_seq}
+@showfuncdesc{gnutls_record_check_pending}
+@c @showfuncdesc{gnutls_record_get_direction}
+
 @menu
 * Encryption algorithms used in the record layer::
 * Compression algorithms used in the record layer::
@@ -157,7 +146,7 @@ just after the handshake protocol has finished.
 @end menu
 
 @node Encryption algorithms used in the record layer
-@subsection 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
@@ -232,7 +221,7 @@ GCM, is in use.
 
 
 @node Compression algorithms used in the record layer
-@subsection 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
@@ -259,7 +248,7 @@ No compression.
 @node Weaknesses and countermeasures
 @subsection Weaknesses and Countermeasures
 
-Some weaknesses that may affect the security of the Record layer have
+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
 
@@ -288,8 +277,8 @@ see the archives of the TLS Working Group mailing list and @xcite{CBCATT}.
 @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 (see @xcite{RFC5246} section 6.2.3.2).  
+The TLS protocol allows for random padding of records, to prevent
+statistical analysis based on the length of exchanged messages (see @xcite{RFC5246} 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.
 
@@ -305,7 +294,7 @@ 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
 @funcref{gnutls_record_disable_padding}, or @funcref{gnutls_priority_set} with
-the @code{%COMPAT} priority string.
+the @code{%COMPAT} priority string (see @ref{Priority Strings}).
 
 If you implement an application that have a configuration file, we
 recommend that you make it possible for users or administrators to
@@ -314,17 +303,13 @@ application via @funcref{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 @command{gnutls-cli} client or the
-@command{gnutls-serv} server, for testing of other implementations, use
-the parameter: @option{--priority "NORMAL:%COMPAT"}.
-
 
 @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.
+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
@@ -332,75 +317,52 @@ protocol and the application protocol does not have to cope with them
 application protocol solely (e.g. @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.
+prevent future renegotiations using the current session ID. All alert
+messages are summarized in @ref{tab:alerts}.
+
 
 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.
+public log files etc. The available functions to control the alert
+protocol are shown below.
 
-@table @asis
-@item @funcref{gnutls_alert_send}:
-To send an alert signal.
+@showfuncdesc{gnutls_alert_get}
 
-@item @funcref{gnutls_error_to_alert}:
-To map a gnutls error number to an alert signal.
+@showfuncdesc{gnutls_alert_send}
 
-@item @funcref{gnutls_alert_get}:
-Returns the last received alert.
+@showfuncB{gnutls_error_to_alert,gnutls_alert_get_name}
 
-@item @funcref{gnutls_alert_get_name}:
-Returns the name, in a character array, of the given alert.
+@include alerts.texi
 
-@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 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:
+has to set up the required parameters. The main handshake function
+is @funcref{gnutls_handshake}. In the next paragraphs we elaborate on 
+controlling of the handshake protocol, i.e., the ciphersuite negotiation.
 
-@table @asis
-@item @funcref{gnutls_priority_init}:
-To initialize a priority set of ciphers.
-
-@item @funcref{gnutls_priority_deinit}:
-To deinitialize a priority set of ciphers.
-
-@item @funcref{gnutls_priority_set}:
-To associate a priority set with a @acronym{TLS} session.
-
-@item @funcref{gnutls_priority_set_direct}:
-To directly associate a session with a given priority string.
+@showfuncdesc{gnutls_handshake}
 
-@item @funcref{gnutls_credentials_set}:
-To set the appropriate credentials structures.
-
-@item @funcref{gnutls_certificate_server_set_request}:
-To set whether client certificate is required or not.
-
-@item @funcref{gnutls_handshake}:
-To initiate the handshake.
-@end table
 
 @menu
 * TLS Cipher Suites::           TLS session parameters.
 * Priority Strings::            Defining how parameters are negotiated.
 * Client Authentication::       Requesting a certificate from the client.
 * Resuming Sessions::           Reusing previously established keys.
-* Resuming Internals::          More information on reusing previously established keys.
 * Interoperability::            About interoperability with other implementations.
 @end menu
 
 @node TLS Cipher Suites
 @subsection TLS Cipher Suites
 
-The Handshake Protocol of @acronym{TLS} negotiates cipher suites of
+The handshake protocol of @acronym{TLS} negotiates cipher suites of
 a special form illustrated by the @code{TLS_DHE_RSA_WITH_3DES_CBC_SHA} cipher suite name.  A typical cipher
 suite contains these parameters:
 
@@ -418,21 +380,25 @@ suite contains these parameters:
 @end itemize
 
 The cipher suite negotiated in the handshake protocol will affect the
-Record Protocol, by enabling encryption and data authentication.  Note
+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.
 
-All the supported ciphersuites are shown in @ref{ciphersuites}.
+All the supported ciphersuites are listed in @ref{ciphersuites}.
 
 @node Priority Strings
 @subsection Priority Strings
 
-In order to specify cipher suite preferences, the
+In order to specify cipher suite preferences on client or server side, the
 previously shown priority functions accept a string
-that specifies the algorithms to be enabled in a TLS handshake.
+that specifies the enable for the handshake algorithms.
 That string may contain some high level keyword such as
-the keywords in @ref{tab:prio-keywords}.
+the keywords in @ref{tab:prio-keywords}
+or it might contain special keywords, to be explained
+later on.
+
+@showfuncD{gnutls_priority_set_direct,gnutls_priority_init,gnutls_priority_deinit,gnutls_priority_set}
 
 @float Table,tab:prio-keywords
 @multitable @columnfractions .30 .70
@@ -476,9 +442,6 @@ algorithms to be enabled.
 @caption{Supported priority string keywords.}
 @end float
 
-or it might contain special keywords, that will be explained
-later on.
-
 Unless the first keyword is "NONE" the defaults (in preference
 order) are for TLS protocols TLS 1.2, TLS1.1, TLS1.0, SSL3.0; for
 compression NULL; for certificate types X.509, OpenPGP.
@@ -488,26 +451,20 @@ protocols.  In all cases all the supported key exchange algorithms
  are enabled (except for the RSA-EXPORT which is only enabled in
 EXPORT level).
 
-The NONE keyword is followed by the algorithms to be enabled,
-and is used to provide the exact list of requested algorithms@footnote{
-To avoid collisions in order to specify a compression algorithm in
+The NONE keyword must followed by the algorithms to be enabled,
+and is used to provide the exact list of requested algorithms@footnote{To avoid collisions in order to specify a compression algorithm in
 this string you have to prefix it with "COMP-", protocol versions
 with "VERS-", signature algorithms with "SIGN-" and certificate types with "CTYPE-". All other
 algorithms don't need a prefix.}. The order with which every algorithm
 is specified is significant. Similar algorithms specified before others
 will take precedence. The individual algorithms are shown in @ref{tab:prio-algorithms}
 and special keywords are in @ref{tab:prio-special}.
-
-
-Keywords prepended to individual algorithms:
+The prefixes for individual algorithms are:
 @table @asis
-
 @item '!' or '-' 
 appended with an algorithm will remove this algorithm.
-
 @item "+" 
 appended with an algorithm will add this algorithm.
-
 @end table
 
 
@@ -609,21 +566,25 @@ will allow V1 CAs in chains.
 
 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
+may request a certificate from the client using the
 @funcref{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 @funcref{gnutls_certificate_set_x509_trust_file}
-@item @funcref{gnutls_certificate_set_x509_trust_mem}
-@end itemize
+by the server. That is the ones set using the following functions.
+
+@showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_trust_mem}
 
-Sending of the names of the certificate authorities can be controlled using the function
-@funcref{gnutls_certificate_send_x509_rdn_sequence}. The client, then, may
-send a certificate, signed by one of the server's acceptable signers.
+@showfuncdesc{gnutls_certificate_server_set_request}
+
+In cases where the server supports a large number of certificate authorities
+it makes sense not to advertize all of the names to save bandwidth. That can
+be controlled using the function @funcref{gnutls_certificate_send_x509_rdn_sequence}. 
+This however will have the side-effect of not restricting the client to certificates
+signed by server's acceptable signers.
+
+@showfuncdesc{gnutls_certificate_send_x509_rdn_sequence}
 
 @node Resuming Sessions
 @subsection Resuming Sessions
@@ -632,58 +593,48 @@ send a certificate, signed by one of the server's acceptable signers.
 
 The @funcref{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
+to the same server a client may use session resuming. 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
+the expensive calculations.  This is achieved by re-using the previously
 established keys. @acronym{GnuTLS} supports this feature, and the
 example in @ref{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
+Keep in mind that sessions might be expired after some time, 
+thus it may be normal for a server not to resume a session
+even if you requested that.  That is to prevent temporal session keys
+from becoming long-term keys. Also note that as a client you must enable, using the
 priority functions, at least the algorithms used in the last session.
 
-@node Resuming Internals
-@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. That is, copy and keep the
-necessary parameters. See the functions:
+necessary parameters. The relevant functions are listed below.
 
-@itemize
+@showfuncdesc{gnutls_session_get_data}
 
-@item @funcref{gnutls_session_get_data}
+@showfuncdesc{gnutls_session_get_id}
 
-@item @funcref{gnutls_session_get_id}
+@showfuncdesc{gnutls_session_set_data}
 
-@item @funcref{gnutls_session_set_data}
-
-@end itemize
-
-The server side is different. A server has to specify some callback
+Server side is different. A server needs to specify callback
 functions which store, retrieve and delete session data. These can be
-registered with:
+registered with the functions shown below.
 
-@itemize
+@showfuncdesc{gnutls_db_set_retrieve_function}
 
-@item @funcref{gnutls_db_set_remove_function}
+@showfuncdesc{gnutls_db_set_store_function}
 
-@item @funcref{gnutls_db_set_store_function}
-
-@item @funcref{gnutls_db_set_retrieve_function}
-
-@item @funcref{gnutls_db_set_ptr}
-
-@end itemize
+@showfuncB{gnutls_db_set_ptr,gnutls_db_set_remove_function}
 
 It might also be useful to be able to check for expired sessions in
 order to remove them, and save space. The function
 @funcref{gnutls_db_check_entry} is provided for that reason.
 
+@showfuncdesc{gnutls_db_check_entry}
+
 @node Interoperability
 @subsection Interoperability
 
@@ -709,7 +660,8 @@ NORMAL:-VERS-TLS-ALL:+VERS-TLS1.0:+VERS-SSL3.0:%COMPAT
 This priority string will only enable SSL 3.0 and TLS 1.0 as protocols and
 will disable, via the @code{%COMPAT} keyword, several @acronym{TLS} protocol
 options that are known to cause compatibility problems.
-We suggest however only to use this mode if compatibility issues occur.
+We suggest however only to use this mode if compatibility is preferred over
+security.
 
 @node TLS Extensions
 @section TLS Extensions
@@ -734,11 +686,12 @@ and they will be discussed in the subsections that follow.
 
 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 functions:
-@itemize
-@item @funcref{gnutls_record_set_max_size}
-@item @funcref{gnutls_record_get_max_size}
-@end itemize
+useful to clients with constrained capabilities. The functions shown
+below can be used to control this extension.
+
+@showfuncdesc{gnutls_record_get_max_size}
+
+@showfuncdesc{gnutls_record_set_max_size}
 
 @subsection Server Name Indication
 @anchor{serverind}
@@ -757,6 +710,10 @@ begins within the first handshake packet.  The functions
 used to enable this extension, or to retrieve the name sent by a
 client.
 
+@showfuncdesc{gnutls_server_name_set}
+
+@showfuncdesc{gnutls_server_name_get}
+
 @subsection Session Tickets
 @cindex TLS Extensions
 @cindex Session Tickets
@@ -775,6 +732,12 @@ Clients can enable support for TLS tickets with
 Clients resume sessions using the ticket using the normal session
 resume functions, @ref{resume}.
 
+@showfuncdesc{gnutls_session_ticket_key_generate}
+
+@showfuncdesc{gnutls_session_ticket_enable_server}
+
+@showfuncdesc{gnutls_session_ticket_enable_client}
+
 @subsection Safe Renegotiation
 @cindex renegotiation
 
@@ -889,7 +852,7 @@ appropriate key sizes as well as select parameters for Diffie-Hellman and SRP
 authentication.
 
 @float Table,tab:key-sizes
-@multitable @columnfractions .10 .15 .10 .20 .35
+@multitable @columnfractions .10 .12 .10 .20 .32
 
 @headitem Security bits @tab RSA, DH and SRP parameter size @tab ECC key size @tab Security parameter @tab Description
 
@@ -944,20 +907,17 @@ 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
+The NIST publication SP 800-57 @xcite{NISTSP80057} contains a similar
 table.
 
 When using @acronym{GnuTLS} and a decision on bit sizes for a public
 key algorithm is required, use of the following functions is  
 recommended:
-@itemize
 
-@item @funcref{gnutls_pk_bits_to_sec_param}
+@showfuncdesc{gnutls_sec_param_to_pk_bits}
 
-@item @funcref{gnutls_sec_param_to_pk_bits}
+@showfuncdesc{gnutls_pk_bits_to_sec_param}
 
-@end itemize
 Those functions will convert a human understandable security parameter
 of @code{gnutls_sec_param_t} type, to a number of bits suitable for a public 
 key algorithm.
diff --git a/doc/cha-library.texi b/doc/cha-library.texi
index 74865237fa..4568acb0c9 100644
--- a/doc/cha-library.texi
+++ b/doc/cha-library.texi
@@ -159,24 +159,27 @@ operating system provided locks (i.e. @code{pthreads} on GNU/Linux and
 the function @funcref{gnutls_global_set_mutex} before calling @funcref{gnutls_global_init}. 
 Setting manually mutexes is recommended
 only to applications that have full control of the underlying libraries. If this
-is not the case, the use of the operating system defaults is suggested.
+is not the case, the use of the operating system defaults is recommended. Examples
+are shown below.
 
 
-There are helper macros to help you properly initialize the libraries.
-Examples are shown in the following paragraphs.
-
-@subsection Native threads
 @example
 #include <gnutls.h>
 
+/* Native threads
+ */
+
 int main()
 @{
    gnutls_global_init();
 @}
 @end example
 
-@subsection Other thread packages
 @example
+#include <gnutls.h>
+
+/* Other thread packages
+ */
 
 int main()
 @{
@@ -198,23 +201,12 @@ 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 @funcref{gnutls_transport_set_push_function}
-
-@item @funcref{gnutls_transport_set_pull_function}
-
-@end itemize
+@showfuncB{gnutls_transport_set_push_function,gnutls_transport_set_pull_function}
 
 Other callback functions may require more complicated input and data
 to be allocated. Such an example is 
 @funcref{gnutls_srp_set_server_credentials_function}.
 All callbacks should allocate and free memory using the functions shown below.
 
-@itemize
-
-@item @funcref{gnutls_malloc}
-
-@item @funcref{gnutls_free}
+@showfuncB{gnutls_malloc,gnutls_free}
 
-@end itemize
diff --git a/doc/gnutls.texi b/doc/gnutls.texi
index 66368dd1de..a534184c19 100644
--- a/doc/gnutls.texi
+++ b/doc/gnutls.texi
@@ -71,6 +71,63 @@ Documentation License''.
 @ref{\ref\}
 @end macro
 
+@macro showfuncA{ref}
+@itemize
+@item @ref{\ref\}
+@end itemize
+@end macro
+
+@macro showfuncB{ref1,ref2}
+@itemize
+@item @ref{\ref1\}
+@item @ref{\ref2\}
+@end itemize
+@end macro
+
+@macro showfuncC{ref1,ref2,ref3}
+@itemize
+@item @ref{\ref1\}
+@item @ref{\ref2\}
+@item @ref{\ref3\}
+@end itemize
+@end macro
+
+@macro showfuncD{ref1,ref2,ref3,ref4}
+@itemize
+@item @ref{\ref1\}
+@item @ref{\ref2\}
+@item @ref{\ref3\}
+@item @ref{\ref4\}
+@end itemize
+@end macro
+
+@macro showfuncE{ref1,ref2,ref3,ref4,ref5}
+@itemize
+@item @ref{\ref1\}
+@item @ref{\ref2\}
+@item @ref{\ref3\}
+@item @ref{\ref4\}
+@item @ref{\ref5\}
+@end itemize
+@end macro
+
+@macro showfuncF{ref1,ref2,ref3,ref4,ref5,ref6}
+@itemize
+@item @ref{\ref1\}
+@item @ref{\ref2\}
+@item @ref{\ref3\}
+@item @ref{\ref4\}
+@item @ref{\ref5\}
+@item @ref{\ref6\}
+@end itemize
+@end macro
+
+@macro showfuncdesc{ref}
+@itemize
+@item @ref{\ref\}
+@end itemize
+@end macro
+
 @contents
 
 @ifnottex
diff --git a/doc/latex/Makefile.am b/doc/latex/Makefile.am
index 1e86cf3817..2c01e887ed 100644
--- a/doc/latex/Makefile.am
+++ b/doc/latex/Makefile.am
@@ -3,7 +3,7 @@ TEX_OBJECTS = gnutls.tex macros.tex fdl.tex cover.tex gnutls.bib
 GEN_TEX_OBJECTS = cha-preface.tex cha-library.tex cha-intro-tls.tex cha-auth.tex \
   cha-cert-auth.tex cha-gtls-app.tex cha-tls-app.tex cha-programs.tex cha-support.tex \
   cha-functions.tex error_codes.tex cha-ciphersuites.tex algorithms.tex \
-  cha-errors.tex
+  cha-errors.tex alerts.tex
 
 cha-preface.tex: ../cha-preface.texi
 	../scripts/mytexi2latex $< > $@
@@ -45,10 +45,14 @@ error_codes.tex: $(top_srcdir)/lib/gnutls_errors.c $(srcdir)/../errcodes
 	$(builddir)/../errcodes --latex > $@-tmp
 	mv -f $@-tmp $@
 
-algorithms.tex: $(srcdir)/../printlist.c $(builddir)/../printlist
+algorithms.tex: ../printlist
 	$(builddir)/../printlist --latex > $@-tmp
 	mv -f $@-tmp $@
 
+alerts.tex: ../alert-printlist
+	$(builddir)/../alert-printlist --latex > $@-tmp
+	mv -f $@-tmp $@
+
 gnutls-api.tex: $(srcdir)/../../lib/*.c $(srcdir)/../../lib/ext/*.c $(srcdir)/../../lib/auth/*.c $(srcdir)/../../lib/algorithms/*.c
 	echo "" > $@-tmp
 	for i in $^; do \
@@ -57,6 +61,7 @@ gnutls-api.tex: $(srcdir)/../../lib/*.c $(srcdir)/../../lib/ext/*.c $(srcdir)/..
 		echo "ok"; \
 	done
 	$(srcdir)/../scripts/sort1.pl < $@-tmp > $@-tmp2
+	$(srcdir)/../scripts/split.pl functions < $@-tmp 
 	rm -f $@-tmp
 	mv -f $@-tmp2 $@
 
@@ -68,6 +73,7 @@ x509-api.tex: $(srcdir)/../../lib/x509/*.c
 		echo "ok"; \
 	done
 	$(srcdir)/../scripts/sort1.pl < $@-tmp > $@-tmp2
+	$(srcdir)/../scripts/split.pl functions < $@-tmp 
 	rm -f $@-tmp
 	mv -f $@-tmp2 $@
 
@@ -79,6 +85,7 @@ pgp-api.tex: $(srcdir)/../../lib/openpgp/*.c
 		echo "ok"; \
 	done
 	$(srcdir)/../scripts/sort1.pl < $@-tmp > $@-tmp2
+	$(srcdir)/../scripts/split.pl functions < $@-tmp 
 	rm -f $@-tmp
 	mv -f $@-tmp2 $@
 
@@ -90,6 +97,7 @@ extra-api.tex: $(srcdir)/../../libextra/gnutls_extra.c
 		echo "ok"; \
 	done
 	$(srcdir)/../scripts/sort1.pl < $@-tmp > $@-tmp2
+	$(srcdir)/../scripts/split.pl functions < $@-tmp 
 	rm -f $@-tmp
 	mv -f $@-tmp2 $@
 
@@ -103,3 +111,5 @@ gnutls.pdf: $(TEX_OBJECTS) $(GEN_TEX_OBJECTS) $(SOURCE_GEN_FILES)
 
 clean-am:
 	rm -f $(GEN_TEX_OBJECTS) $(SOURCE_GEN_FILES) gnutls.aux gnutls.bbl gnutls.blg gnutls.idx gnutls.ilg gnutls.ind gnutls.log gnutls.out gnutls.toc
+	rm -rf functions
+
diff --git a/doc/latex/gnutls.tex b/doc/latex/gnutls.tex
index 973eb546a3..44a008f7cf 100644
--- a/doc/latex/gnutls.tex
+++ b/doc/latex/gnutls.tex
@@ -1,17 +1,21 @@
-\documentclass{book}
+\documentclass[letterpaper,10pt]{book}
 \bibliographystyle{plain}
 
-\usepackage{html}
 \usepackage{fancyhdr}
 \usepackage{graphicx}
 \usepackage{makeidx}
 \usepackage{supertabular}
 \usepackage{color}
-\usepackage{colortbl}
 \usepackage{fancyvrb}
 \usepackage{eurosans}
 \usepackage{parskip}
 \usepackage{hyperref}
+\usepackage{framed}
+\usepackage{verbatim}
+\usepackage{listings}
+\usepackage{xcolor}
+\usepackage[greek,english]{babel}%for euro sign
+
 
 \hypersetup{
     colorlinks,%
diff --git a/doc/latex/macros.tex b/doc/latex/macros.tex
index 26df4799d4..f6ea4a38db 100644
--- a/doc/latex/macros.tex
+++ b/doc/latex/macros.tex
@@ -43,3 +43,145 @@
 	%\hyperref[#2]{#1()}%
 	\code{#1}%
 }
+
+\newcommand{\showfunc}[1]{%
+ \let\Oldfd\functionDescription
+ \let\Oldendfd\endfunctionDescription
+ \let\functionDescription=\comment
+ \let\endfunctionDescription=\endcomment 
+ \let\Oldfr\functionReturns
+ \let\Oldendfr\endfunctionReturns
+ \let\functionReturns=\comment
+ \let\endfunctionReturns=\endcomment 
+\texttt{
+ \input{functions/#1}
+}
+ \let\functionDescription=\Oldfd
+ \let\endfunctionDescription=\Oldendfd
+ \let\functionReturns=\Oldfr
+ \let\endfunctionReturns=\Oldendfr
+}
+
+\newcommand{\showfuncdesc}[1]{%
+%\fcolorbox{black}{light-gray}{
+ \begin{minipage}[l]{\linewidth}
+ \begin{framed}
+  \texttt{
+   \input{functions/#1}
+  }
+% }
+ \end{framed}
+ \vspace{0.15cm}
+ \end{minipage}
+}
+
+\newcommand{\showfuncA}[1]{%
+% \fcolorbox{black}{light-gray}{
+ \begin{samepage}
+ \begin{framed}
+  \texttt{
+   \showfunc{#1}
+  }
+% }
+ \end{framed}
+ \end{samepage}
+}
+
+\newcommand{\showfuncB}[2]{%
+% \fcolorbox{black}{light-gray}{
+ \begin{samepage}
+ \begin{framed}
+  \texttt{
+    \showfunc{#1}
+    \showfunc{#2}
+  }
+% }
+ \end{framed}
+ \end{samepage}
+}
+
+\newcommand{\showfuncC}[3]{%
+% \fcolorbox{black}{light-gray}{
+ \begin{samepage}
+ \begin{framed}
+  \texttt{
+  \showfunc{#1}
+  \showfunc{#2}
+  \showfunc{#3}
+  }
+% }
+ \end{framed}
+ \end{samepage}
+}
+
+\newcommand{\showfuncD}[4]{%
+% \fcolorbox{black}{light-gray}{
+ \begin{samepage}
+ \begin{framed}
+  \texttt{
+  \showfunc{#1}
+  \showfunc{#2}
+  \showfunc{#3}
+  \showfunc{#4}
+  }
+% }
+ \end{framed}
+ \end{samepage}
+}
+
+\newcommand{\showfuncE}[5]{%
+% \fcolorbox{black}{light-gray}{
+ \begin{samepage}
+ \begin{framed}
+  \texttt{
+  \showfunc{#1}
+  \showfunc{#2}
+  \showfunc{#3}
+  \showfunc{#4}
+  \showfunc{#5}
+  }
+% }
+ \end{framed}
+ \end{samepage}
+}
+
+\newcommand{\showfuncF}[6]{%
+% \fcolorbox{black}{light-gray}{
+ \begin{samepage}
+ \begin{framed}
+  \texttt{
+  \showfunc{#1}
+  \showfunc{#2}
+  \showfunc{#3}
+  \showfunc{#4}
+  \showfunc{#5}
+  \showfunc{#6}
+  }
+% }
+ \end{framed}
+ \end{samepage}
+}
+
+\newenvironment{function}%
+ {\begin{minipage}[l]{1\linewidth}}%
+ {\end{minipage}}
+
+\let\functionArguments=\comment
+\let\endfunctionArguments=\endcomment 
+
+\let\functionExamples=\comment
+\let\endfunctionExamples=\endcomment 
+
+\newenvironment{functionDescription}%
+{\vspace{0.5cm}{\bf Description:}\footnotesize}
+{}
+
+\newcommand{\functionTitle}[1]{}
+
+\newenvironment{functionReturns}%
+{\vspace{0.5cm}{\bf Returns:}\footnotesize}
+{}
+
+\let\functionSince=\comment
+\let\endfunctionSince=\endcomment 
+
diff --git a/doc/scripts/gdoc b/doc/scripts/gdoc
index afd0802968..49868dbd68 100755
--- a/doc/scripts/gdoc
+++ b/doc/scripts/gdoc
@@ -428,7 +428,8 @@ sub output_tex {
 
     $func =~ s/_/\\_/g;
 
-    print "\n\n\\subsection{". $func . "}\n\\label{" . $args{'function'} . "}\n";
+    print "\n\n\\begin{function}\n";
+    print "\\functionTitle{". $func . "}\n";
 
     $type = $args{'functiontype'};
     $type =~ s/_/\\_/g;
@@ -451,9 +452,8 @@ sub output_tex {
     }
     print ")\n";
 
-    print "\n{\\large{Arguments}}\n";
+    print "\n\\begin{functionArguments}\n";
 
-    print "\\begin{itemize}\n";
     $check=0;
     foreach $parameter (@{$args{'parameterlist'}}) {
         $param1 = $args{'parametertypes'}{$parameter};
@@ -462,11 +462,12 @@ sub output_tex {
 	$param2 =~ s/_/\\_/g;
 
 	$check = 1;
-	print "\\item {\\it ".$param1."} {\\bf ".$param2."}: \n";
+	print "\\functionArgument {\\it ".$param1."} {\\bf ".$param2."}: \n";
 #	print "\n";
 
 	$param3 = $args{'parameters'}{$parameter};
-	$param3 =~ s/#([a-zA-Z\_]+)/{\\it \1}/g;
+	$param3 =~ s/\#([a-zA-Z\_]+)/{\\it $1}/g;
+	$param3 =~ s/\%([a-zA-Z\_]+)/{\\bf $1}/g;
 
 	$out = just_highlight($param3);
 	$out =~ s/_/\\_/g;
@@ -475,29 +476,30 @@ sub output_tex {
     if ($check==0) {
 	print "\\item void\n";
     }
-    print "\\end{itemize}\n";
+    print "\\end{functionArguments}\n";
 
     foreach $section (@{$args{'sectionlist'}}) {
 	$sec = $section;
 	$sec =~ s/_/\\_/g;
 	$sec =~ s/#([a-zA-Z\_]+)/{\\it \1}/g;
 
-	print "\n{\\large{$sec}}\\\\\n";
-	print "\\begin{rmfamily}\n";
+	print "\n\\begin{function$sec}\n";
+	$out = $args{'sections'}{$section};
 
-	$sec = $args{'sections'}{$section};
-	$sec =~ s/\\:/:/g;
-	$sec =~ s/#([a-zA-Z\_]+)/{\\it \1}/g;
-	$sec =~ s/->/\$\\rightarrow\$/g;
-	$sec =~ s/([0-9]+)\^([0-9]+)/\$\{\1\}\^\{\2\}\$/g;
-
-	$out = just_highlight($sec);
+	$out =~ s/\#([a-zA-Z\_]+)/{\\it $1}/g;
+	$out =~ s/\%([a-zA-Z\_]+)/{\\bf $1}/g;
+	$out =~ s/\@([a-zA-Z\_]+)/{\\bf $1}/g;
 	$out =~ s/_/\\_/g;
+	$out =~ s/#/\\#/g;
+	$out =~ s/\n\n/\n/g;
+	$out =~ s/\\:/:/g;
+	$out =~ s/\-\>/\$\\rightarrow\$/g;
+	$out =~ s/([0-9]+)\^([0-9]+)/\$\{\1\}\^\{\2\}\$/g;
 
 	print $out;
-	print "\\end{rmfamily}\n";
+	print "\\end{function$sec}\n";
     }
-    print "\n";
+    print "\\end{function}\n\n";
 }
 
 
diff --git a/doc/scripts/mytexi2latex b/doc/scripts/mytexi2latex
index fe7ea2dd60..7d842dff56 100755
--- a/doc/scripts/mytexi2latex
+++ b/doc/scripts/mytexi2latex
@@ -27,11 +27,30 @@ sub funcref()
 my $prefix = $_[0];
 my $suffix=$_[0];
 	$suffix =~ s/\\//g;
+	$prefix =~ s/\\_/\\_\\-/g;
 	return "\\funcref\{$prefix\}\{$suffix\}";
 }
 
+sub showfunc()
+{
+my $prefix = $_[0];
+my $suffix = $_[1];
+	$suffix =~ s/\\//g;
+	$suffix =~ s/\,/\}\{/g;
+	return "\\showfunc$prefix\{$suffix\}";
+}
+
+sub showfuncdesc()
+{
+my $suffix = $_[0];
+	$suffix =~ s/\\//g;
+	return "\\showfuncdesc\{$suffix\}";
+}
+
 my $punescape = \&unescape;
 my $pfuncref = \&funcref;
+my $pshowfunc = \&showfunc;
+my $pshowfuncdesc = \&showfuncdesc;
 my $mode;
 my $num_args = $#ARGV + 1;
 
@@ -45,7 +64,7 @@ my $match = "[\\w\\d-\\.\\/\\@\\:\_\\\\\#]";
 my $spacematch = "[\\s\\w\\d-\\.\\/\\@\\#\\:]";
 my $mathmatch = "[\\s\\w\\d-\\.\\/\\:\\(\\)\\+\\/\\^\\'\\=\{\}\\\\\\,]";
 my $underscorematch = "[\\s\\w\\d-\\.\\/\\@\\_\\\\\:\\~]";
-my $codematch = "[\\s\\w\\d-\\.\\/\\@\\_\\\\\:\\-\\\"\+\\%]";
+my $codematch = "[\\s\\w\\d-\\.\\/\\@\\_\\\\\:\\-\\\"\+\\%\\,]";
 my ($line, $prev_mode);
 my ($verbatim, $label);
 my @stack = ();
@@ -292,7 +311,8 @@ multitable:
 		$line =~ s/\@cindex (.+)/\\index{$1}/g;
 		$line =~ s/\@url\{($underscorematch+)\}/\\url{$1}/g;
 		#$line =~ s/\@euro/\\euro/g;
-		$line =~ s/\@euro\{\}/euro/g;
+		$line =~ s/\s*\@euro\{\}/\~\\textgreek\{\\euro\}/g;
+		$line =~ s/\@page/\\newpage/g;
 		$line =~ s/\@file\{($spacematch+)\}/\\file{$1}/g;
 		$line =~ s/\@code\{($codematch+)\}/\\code{$1}/g;
 		$line =~ s/\@option\{($codematch+)\}/\\command{$1}/g;
@@ -301,6 +321,8 @@ multitable:
 		$line =~ s/\@emph\{($spacematch+)\}/\\emph{$1}/g;
 		$line =~ s/\@xref\{/\\myref\{/g;
 		$line =~ s/\@funcref\{($codematch+)\}/$pfuncref->($1)/ge;
+		$line =~ s/\@showfunc([A-Z])\{($codematch+)\}/$pshowfunc->($1,$2)/ge;
+		$line =~ s/\@showfuncdesc\{($codematch+)\}/$pshowfuncdesc->($1)/ge;
 		$line =~ s/\@pxref\{/\\myref\{/g;
 		$line =~ s/\@center (.*)/\\begin{center}\n$1\n\\end{center}/g;
 		if ($line =~ m/\@email/) {
diff --git a/doc/scripts/sort1.pl b/doc/scripts/sort1.pl
index 9d31ed4e81..504394d4cf 100755
--- a/doc/scripts/sort1.pl
+++ b/doc/scripts/sort1.pl
@@ -9,12 +9,12 @@ sub key_of_record {
   my ($i) = 1;
   my ($key) = $lines[$i]; 
 
-  while( !($key =~ m/^\\label(.*)/) && ($i < 5)) { $i=$i+1; $key = $lines[$i]; }
+  while( !($key =~ m/^\\functionTitle\{(.*)\}/) && ($i < 5)) { $i=$i+1; $key = $lines[$i]; }
 
   return $key;
 }
 
-$/="\n\n\n";          # Records are separated by blank lines.
+$/="\n\\end{function}";          # Records are separated by blank lines.
 @records = <>;  # Read in whole file, one record per array element.
 
 @records = sort { key_of_record($a) cmp key_of_record($b) } @records;
diff --git a/doc/scripts/split.pl b/doc/scripts/split.pl
new file mode 100755
index 0000000000..ca7d7855e0
--- /dev/null
+++ b/doc/scripts/split.pl
@@ -0,0 +1,39 @@
+#!/usr/bin/perl
+
+$dir = shift;
+
+sub key_of_record {
+  local($record) = @_;
+
+  # Split record into lines:
+  my @lines = split /\n/, $record;
+
+  my ($i) = 1;
+  my ($key) = $lines[$i]; 
+
+  while( !($key =~ m/^\\functionTitle\{(.*)\}/) && ($i < 5)) { $i=$i+1; $key = $lines[$i]; }
+
+  return $key;
+}
+
+$/="\n\\end{function}";          # Records are separated by blank lines.
+@records = <>;  # Read in whole file, one record per array element.
+
+mkdir $dir;
+
+@records = sort { key_of_record($a) cmp key_of_record($b) } @records;
+foreach (@records) {
+  $key = $_;
+  $key =~  m/\\functionTitle\{(.*)\}/;
+
+  $key = $1;
+  $key =~ s/\\_/_/g;
+
+  if (defined $key && $key ne "") {
+    open FILE, "> $dir/$key\n" or die $!;
+    print FILE $_ . "\n";
+    close FILE;
+  }
+} 
+
+#print @records;
diff --git a/lib/gnutls_x509.c b/lib/gnutls_x509.c
index 0c1d305eef..37ba539ab8 100644
--- a/lib/gnutls_x509.c
+++ b/lib/gnutls_x509.c
@@ -749,14 +749,8 @@ read_key_file (gnutls_certificate_credentials_t res,
  *
  * This function sets a certificate/private key pair in the
  * gnutls_certificate_credentials_t structure. This function may be called
- * more than once (in case multiple keys/certificates exist for the
- * server).
- *
- * Currently are supported: RSA PKCS-1 encoded private keys,
- * DSA private keys.
- *
- * DSA private keys are encoded the OpenSSL way, which is an ASN.1
- * DER sequence of 6 INTEGERs - version, p, q, g, pub, priv.
+ * more than once, in case multiple keys/certificates exist for the
+ * server.
  *
  * Note that the keyUsage (2.5.29.15) PKIX extension in X.509 certificates
  * is supported. This means that certificates intended for signing cannot
@@ -768,7 +762,7 @@ read_key_file (gnutls_certificate_credentials_t res,
  * The @key may be %NULL if you are using a sign callback, see
  * gnutls_sign_callback_set().
  *
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
  **/
 int
 gnutls_certificate_set_x509_key_mem (gnutls_certificate_credentials_t res,
@@ -854,14 +848,14 @@ certificate_credentials_append_pkey (gnutls_certificate_credentials_t res,
  *
  * This function sets a certificate/private key pair in the
  * gnutls_certificate_credentials_t structure.  This function may be
- * called more than once (in case multiple keys/certificates exist for
- * the server).  For clients that wants to send more than its own end
+ * called more than once, in case multiple keys/certificates exist for
+ * the server.  For clients that wants to send more than its own end
  * entity certificate (e.g., also an intermediate CA cert) then put
  * the certificate chain in @cert_list.
  *
  * 
  *
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
  *
  * Since: 2.4.0
  **/
@@ -944,18 +938,15 @@ gnutls_certificate_set_x509_key (gnutls_certificate_credentials_t res,
  *
  * This function sets a certificate/private key pair in the
  * gnutls_certificate_credentials_t structure.  This function may be
- * called more than once (in case multiple keys/certificates exist for
- * the server).  For clients that wants to send more than its own end
- * entity certificate (e.g., also an intermediate CA cert) then put
- * the certificate chain in @certfile.
+ * called more than once, in case multiple keys/certificates exist for
+ * the server.  For clients that need to send more than its own end
+ * entity certificate, e.g., also an intermediate CA cert, then the
+ * @certfile must contain the ordered certificate chain.
  *
- * Currently only PKCS-1 encoded RSA and DSA private keys are accepted by
- * this function.
+ * This function can also accept PKCS #11 URLs at @keyfile and @certfile. In that case it
+ * will import the private key and certificate indicated by the URLs.
  *
- * This function can also accept PKCS #11 URLs. In that case it
- * will import the private key and certificate indicated by the urls.
- *
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
  **/
 int
 gnutls_certificate_set_x509_key_file (gnutls_certificate_credentials_t res,
@@ -1235,7 +1226,7 @@ gnutls_certificate_set_x509_trust_mem (gnutls_certificate_credentials_t res,
  * a certificate request is sent. This can be disabled using
  * gnutls_certificate_send_x509_rdn_sequence().
  *
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
  *
  * Since: 2.4.0
  **/
@@ -1481,7 +1472,7 @@ gnutls_certificate_set_x509_crl_mem (gnutls_certificate_credentials_t res,
  * gnutls_certificate_verify_peers2().  This function may be called
  * multiple times.
  *
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
  *
  * Since: 2.4.0
  **/
@@ -1891,9 +1882,6 @@ done:
  * only password based security, and the same password for all
  * operations, are supported.
  *
- * The private keys may be RSA PKCS#1 or DSA private keys encoded in
- * the OpenSSL way.
- *
  * PKCS#12 file may contain many keys and/or certificates, and there
  * is no way to identify which key/certificate pair you want.  You
  * should make sure the PKCS#12 file only contain one key/certificate
@@ -1904,7 +1892,7 @@ done:
  * complexity that would make it harder to use this functionality at
  * all.
  *
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
  **/
 int
   gnutls_certificate_set_x509_simple_pkcs12_file
@@ -1948,9 +1936,6 @@ int
  * only password based security, and the same password for all
  * operations, are supported.
  *
- * The private keys may be RSA PKCS#1 or DSA private keys encoded in
- * the OpenSSL way.
- *
  * PKCS#12 file may contain many keys and/or certificates, and there
  * is no way to identify which key/certificate pair you want.  You
  * should make sure the PKCS#12 file only contain one key/certificate
@@ -1961,7 +1946,7 @@ int
  * complexity that would make it harder to use this functionality at
  * all.
  *
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
  *
  * Since: 2.8.0
  **/