updated documentation. The function descriptions were converted to floats.

9 files changed, 80 insertions, 107 deletions

diff --git a/NEWS b/NEWS
index c506b75b9f..45234ec08b 100644
--- a/NEWS
+++ b/NEWS
@@ -4,6 +4,9 @@ See the end for copying conditions.
 
 * Version 3.0.3 (unreleased)
 
+** libgnutls: All functions related to RSA-EXPORT were deprecated.
+Support for RSA-EXPORT ciphersuites will be ceased in future versions.
+
 ** libgnutls: Memory leak fixes in ECC ciphersuites.
 
 ** libgnutls: Do not send an empty extension structure in server 
diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi
index 873db91d7b..a42854a531 100644
--- a/doc/cha-auth.texi
+++ b/doc/cha-auth.texi
@@ -130,11 +130,12 @@ 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
+slower@footnote{It depends on the group used.  Primes with
 lesser bits are always faster, but also easier to break.  See @ref{Selecting cryptographic key sizes}
-for the acceptable security levels.} 
-and require Diffie-Hellman parameters to be generated and associated with a credentials
-structure, by the server (see @ref{Parameter generation}).
+for the acceptable security levels.} than the elliptic curves counterpart
+(ECDHE). Moreover the plain Diffie-Hellman key exchange
+requires parameters to be generated and associated with a credentials
+structure by the server (see @ref{Parameter generation}). 
 
 @float Table,tab:key-exchange
 @multitable @columnfractions .2 .7
@@ -363,12 +364,10 @@ the hint, for example in the callback function, using
 
 @showfuncC{gnutls_psk_set_server_credentials_function,gnutls_psk_set_server_credentials_hint,gnutls_psk_client_get_hint}
 
-Helper functions are included in @acronym{GnuTLS}, and may be used to generate and
-maintain @acronym{PSK} keys.
+Helper functions to generate and maintain @acronym{PSK} keys are also included
+in @acronym{GnuTLS}.
 
-@showfuncdesc{gnutls_hex_encode}
-
-@showfuncdesc{gnutls_hex_decode}
+@showfuncC{gnutls_key_generate,gnutls_hex_encode,gnutls_hex_decode}
 
 
 @node Authentication and credentials
diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index 6ee340d75d..dfbb51ecf0 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -225,9 +225,9 @@ possession of the private key.
 @showfuncdesc{gnutls_x509_crq_set_key_purpose_oid}
 @showfuncdesc{gnutls_x509_crq_set_basic_constraints}
 
-The following two functions associate the request with
-a private key and sign it. If a request is to be signed
-with a key residing in a token it is recommended to use
+The @funcref{gnutls_x509_crq_set_key} and @funcref{gnutls_x509_crq_sign2} 
+functions associate the request with a private key and sign it. If a 
+request is to be signed with a key residing in a PKCS #11 token it is recommended to use
 the signing functions shown in @ref{Abstract key types}.
 
 @showfuncdesc{gnutls_x509_crq_set_key}
@@ -265,11 +265,10 @@ structure.
 @showfuncdesc{gnutls_pkcs12_verify_mac}
 @showfuncdesc{gnutls_pkcs12_bag_decrypt}
 
-@showfuncB{gnutls_pkcs12_bag_init,gnutls_pkcs12_bag_deinit}
+@showfuncF{gnutls_pkcs12_bag_init,gnutls_pkcs12_bag_deinit,gnutls_pkcs12_bag_get_count,gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name}
 
-@showfuncD{gnutls_pkcs12_bag_get_count,gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name}
-
-To generate a structure the functions below may be used.
+The functions below are used to generate a PKCS #12 structure. An example
+of their usage is also shown.
 
 @showfuncdesc{gnutls_pkcs12_set_bag}
 @showfuncdesc{gnutls_pkcs12_bag_encrypt}
@@ -277,9 +276,6 @@ To generate a structure the functions below may be used.
 @showfuncdesc{gnutls_pkcs12_export}
 @showfuncE{gnutls_pkcs12_bag_set_data,gnutls_pkcs12_bag_set_crl,gnutls_pkcs12_bag_set_crt,gnutls_pkcs12_bag_set_key_id,gnutls_pkcs12_bag_set_friendly_name}
 
-An example of a @acronym{PKCS} #12 structure generation can be found
-below.
-
 @verbatiminclude examples/ex-pkcs12.c
 
 @node OpenPGP certificates
@@ -338,30 +334,13 @@ 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.
+of verification status flags is the same as in the @acronym{X.509} certificates
+(see @ref{gnutls_certificate_verify_flags}).
 
 @showfuncdesc{gnutls_openpgp_crt_verify_ring}
 
 @showfuncdesc{gnutls_openpgp_crt_verify_self}
 
-@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
-
 @subsection Verifying a certificate in the context of a TLS session
 
 Similarly with X.509 certificates, one needs to specify
@@ -468,13 +447,13 @@ are shown below.
 Properties of the physical token can also be accessed and altered with @acronym{GnuTLS}.
 For example data in a token can be erased (initialized), PIN can be altered, etc.
 
-@showfuncdesc{gnutls_pkcs11_token_init}
+@showfuncD{gnutls_pkcs11_token_init,gnutls_pkcs11_token_get_url,gnutls_pkcs11_token_get_info,gnutls_pkcs11_token_get_flags}
 @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 available PKCS #11 tokens in a system.
+The following examples demonstrate the usage of the API. The first example
+will list all available PKCS #11 tokens in a system and the latter will
+list all certificates in a token that have a corresponding private key.
+
 @example
 int i;
 char* url;
@@ -496,9 +475,6 @@ for (i=0;;i++)
 gnutls_global_deinit();
 @end example
 
-
-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
@@ -534,8 +510,9 @@ Since there are many forms of a public or private keys supported by @acronym{Gnu
 @acronym{X.509}, @acronym{OpenPGP}, or @acronym{PKCS} #11 it is desirable to allow common operations
 on them. For these reasons the abstract @code{gnutls_privkey_t} and @code{gnutls_pubkey_t} were
 introduced in @code{gnutls/abstract.h} header. Those types are initialized using a specific type of 
-key and then can be used to perform operations in an abstract way. For example in order for someone 
-to sign an X.509 certificate with a key that resides in a smart he has to follow the steps below:
+key and then can be used to perform operations in an abstract way. For example in order
+to sign an X.509 certificate with a key that resides in a token the following steps must be
+used.
 
 @example
 #inlude <gnutls/abstract.h>
@@ -602,12 +579,7 @@ are not extractable.
 
 @showfuncdesc{gnutls_privkey_import_x509}
 
-@showfuncdesc{gnutls_privkey_import_openpgp}
-@showfuncdesc{gnutls_privkey_import_pkcs11}
-
-Other information on the private key can be accessed using
-the following functions.
-
+@showfuncB{gnutls_privkey_import_openpgp,gnutls_privkey_import_pkcs11}
 @showfuncdesc{gnutls_privkey_get_pk_algorithm}
 @showfuncdesc{gnutls_privkey_get_type}
 
@@ -616,7 +588,6 @@ The abstract key types can be used to access signing and
 signature verification operations with the underlying keys.
 
 @showfuncdesc{gnutls_pubkey_verify_data2}
-
 @showfuncdesc{gnutls_pubkey_verify_hash}
 @showfuncdesc{gnutls_privkey_sign_data}
 @showfuncdesc{gnutls_privkey_sign_hash}
@@ -627,11 +598,8 @@ keys with structures is also possible using the
 key abstractions.
 
 @showfuncdesc{gnutls_x509_crq_set_pubkey}
-
 @showfuncdesc{gnutls_x509_crt_set_pubkey}
-@showfuncdesc{gnutls_x509_crt_privkey_sign}
-@showfuncdesc{gnutls_x509_crl_privkey_sign}
-@showfuncdesc{gnutls_x509_crq_privkey_sign}
+@showfuncC{gnutls_x509_crt_privkey_sign,gnutls_x509_crl_privkey_sign,gnutls_x509_crq_privkey_sign}
 
 @node Digital signatures
 @section Digital signatures
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 64fbdc6ec9..6c28b839fe 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -179,7 +179,7 @@ In the case of DTLS it is also desirable to override the generic
 transport functions with functions that emulate the operation
 of @code{recvfrom} and @code{sendto}. In addition
 @acronym{DTLS} requires timers during the receive of a handshake
-message. This requires the following function to be used.
+message. This requires the @funcref{gnutls_transport_set_pull_timeout_function} function to be used.
 
 @showfuncdesc{gnutls_transport_set_pull_timeout_function}
 
@@ -196,7 +196,7 @@ The handshake process doesn't ensure the verification
 of the peer's identity. When certificates are in use,
 this can be done, either after the handshake is complete, or during 
 the handshake if @funcref{gnutls_certificate_set_verify_function}
-has been used. In both cases the following function can be
+has been used. In both cases the @funcref{gnutls_certificate_verify_peers2} function can be
 used to verify the peer's certificate (see @ref{Certificate authentication}
 for more information).
 
@@ -231,11 +231,9 @@ recommended to use @funcref{gnutls_bye} to terminate the
 session. That way the peer is notified securely about the
 intention of termination, which allows distinguishing it
 from a malicious connection termination.
+A session can be deinitialized with the @funcref{gnutls_deinit} function.
 
 @showfuncdesc{gnutls_bye}
-
-A session can be deinitialized using the following function.
-
 @showfuncdesc{gnutls_deinit}
 
 @subsection Asynchronous operation
@@ -279,14 +277,7 @@ should verify the initial message sent by client using @funcref{gnutls_dtls_cook
 If successful a the session should be initialization and associated with
 the cookie using @funcref{gnutls_dtls_prestate_set}.
 
-@showfuncdesc{gnutls_key_generate}
-
-@showfuncdesc{gnutls_dtls_cookie_send}
-
-@showfuncdesc{gnutls_dtls_cookie_verify}
-
-@showfuncdesc{gnutls_dtls_prestate_set}
-
+@showfuncD{gnutls_key_generate,gnutls_dtls_cookie_send,gnutls_dtls_cookie_verify,gnutls_dtls_prestate_set}
 
 Note that the above apply to server side only and they are not mandatory to be
 used. Not using them, however, allows denial of service attacks.
@@ -299,10 +290,7 @@ of DTLS messages and prevent messages from being silently discarded by the
 transport layer. The ``correct'' maximum transfer unit can be obtained through
 a path MTU discovery mechanism @xcite{RFC4821}.
 
-@showfuncdesc{gnutls_dtls_set_mtu}
-
-@showfuncdesc{gnutls_dtls_get_mtu}
-@showfuncdesc{gnutls_dtls_get_data_mtu}
+@showfuncC{gnutls_dtls_set_mtu,gnutls_dtls_get_mtu,gnutls_dtls_get_data_mtu}
 
 @node Priority Strings
 @section Priority strings
diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
index 8380c6cf75..7ede5156ad 100644
--- a/doc/cha-intro-tls.texi
+++ b/doc/cha-intro-tls.texi
@@ -75,9 +75,6 @@ by providing callbacks for @acronym{GnuTLS} to access the transport layer
 
 The record protocol is the secure communications provider. Its purpose
 is to encrypt, authenticate and ---optionally--- compress packets.
-
-@showfuncA{gnutls_record_send}
-
 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
@@ -92,12 +89,12 @@ 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.
 
-@showfuncD{gnutls_record_recv,gnutls_record_recv_seq,gnutls_record_check_pending,gnutls_record_get_direction}
+@showfuncC{gnutls_record_send,gnutls_record_recv,gnutls_record_recv_seq}
+@showfuncB{gnutls_record_check_pending,gnutls_record_get_direction}
 
 @menu
 * Encryption algorithms used in the record layer::
@@ -195,16 +192,10 @@ tunnels, and in cases where network usage has to be minimized. It
 should be noted however that compression increases latency.
 
 The record layer compression in @acronym{GnuTLS} is implemented based
-on the proposal @xcite{RFC3749}. The supported algorithms are:
+on the proposal @xcite{RFC3749}. The supported algorithms are shown in
+@ref{gnutls_compression_method_t}.
 
-@table @code
-@item DEFLATE:
-Zlib compression, using the deflate algorithm.
-
-@item NULL:
-No compression.
-
-@end table
+@showenumdesc{gnutls_compression_method_t,Supported compression algorithms}
 
 @node Weaknesses and countermeasures
 @subsection Weaknesses and countermeasures
diff --git a/doc/latex/gnutls.tex b/doc/latex/gnutls.tex
index ba4a9d3be4..edb1e988fa 100644
--- a/doc/latex/gnutls.tex
+++ b/doc/latex/gnutls.tex
@@ -15,8 +15,15 @@
 \usepackage{verbatim}
 \usepackage{listings}
 \usepackage{xcolor}
+\usepackage{afterpage}
+\usepackage{float}
+\usepackage{morefloats}
 \usepackage[greek,english]{babel}%for euro sign
 
+\renewcommand{\textfraction}{0.00}
+\renewcommand{\floatpagefraction}{0.8}
+\renewcommand{\dblfloatpagefraction}{0.8}
+
 \hypersetup{
     colorlinks,%
     citecolor=blue,%
diff --git a/doc/latex/macros.tex b/doc/latex/macros.tex
index 1b48459ba7..8907c52ce2 100644
--- a/doc/latex/macros.tex
+++ b/doc/latex/macros.tex
@@ -44,6 +44,8 @@
 	\code{#1}%
 }
 
+\definecolor{light-gray}{gray}{0.95}
+
 \newcommand{\showfunc}[1]{%
  \let\Oldfd\functionDescription
  \let\Oldendfd\endfunctionDescription
@@ -63,15 +65,15 @@
 }
 
 \newcommand{\showfuncdesc}[1]{%
+ \begin{figure}[htbp]
  \begin{minipage}[l]{\linewidth}
  \begin{framed}
   \texttt{
    \input{functions/#1}
   }
  \end{framed}
- \vspace{0.10cm}
  \end{minipage}
- \par
+ \end{figure}
 }
 
 \newcommand{\showenumdesc}[2]{%
@@ -90,78 +92,93 @@
 }
 
 \newcommand{\showfuncA}[1]{%
-% \fcolorbox{black}{light-gray}{
+ \begin{figure}[H]
  \begin{samepage}
  \begin{framed}
    \showfunc{#1}
-% }
  \end{framed}
  \end{samepage}
+ \end{figure}
 }
 
 \newcommand{\showfuncB}[2]{%
-% \fcolorbox{black}{light-gray}{
+ \begin{figure}[H]
  \begin{samepage}
  \begin{framed}
     \showfunc{#1}
+ \vspace{0.2cm}
     \showfunc{#2}
-% }
  \end{framed}
  \end{samepage}
+ \end{figure}
 }
 
 \newcommand{\showfuncC}[3]{%
-% \fcolorbox{black}{light-gray}{
+ \begin{figure}[H]
  \begin{samepage}
  \begin{framed}
   \showfunc{#1}
+ \vspace{0.2cm}
   \showfunc{#2}
+ \vspace{0.2cm}
   \showfunc{#3}
-% }
  \end{framed}
  \end{samepage}
+ \end{figure}
 }
 
 \newcommand{\showfuncD}[4]{%
-% \fcolorbox{black}{light-gray}{
+ \begin{figure}[H]
  \begin{samepage}
  \begin{framed}
   \showfunc{#1}
+ \vspace{0.2cm}
   \showfunc{#2}
+ \vspace{0.2cm}
   \showfunc{#3}
+ \vspace{0.2cm}
   \showfunc{#4}
-% }
  \end{framed}
  \end{samepage}
+ \end{figure}
 }
 
 \newcommand{\showfuncE}[5]{%
-% \fcolorbox{black}{light-gray}{
+ \begin{figure}[H]
  \begin{samepage}
  \begin{framed}
   \showfunc{#1}
+ \vspace{0.2cm}
   \showfunc{#2}
+ \vspace{0.2cm}
   \showfunc{#3}
+ \vspace{0.2cm}
   \showfunc{#4}
+ \vspace{0.2cm}
   \showfunc{#5}
-% }
  \end{framed}
  \end{samepage}
+ \end{figure}
 }
 
 \newcommand{\showfuncF}[6]{%
-% \fcolorbox{black}{light-gray}{
+ \begin{figure}[H]
  \begin{samepage}
  \begin{framed}
   \showfunc{#1}
+ \vspace{0.2cm}
   \showfunc{#2}
+ \vspace{0.2cm}
   \showfunc{#3}
+ \vspace{0.2cm}
   \showfunc{#4}
+ \vspace{0.2cm}
   \showfunc{#5}
+ \vspace{0.2cm}
   \showfunc{#6}
-% }
  \end{framed}
  \end{samepage}
+ \end{figure}
 }
 
 \newenvironment{function}%
diff --git a/doc/scripts/mytexi2latex b/doc/scripts/mytexi2latex
index 70fdcca167..9fb1cb30b4 100755
--- a/doc/scripts/mytexi2latex
+++ b/doc/scripts/mytexi2latex
@@ -262,7 +262,7 @@ multitable:
                         push(@stack, NORMAL);
                         $mode = FLOAT;
                 }
-                if ($line =~ s/\@float Table\,(.*)/\\begin{table}[htp]\n\\centering/g) {
+                if ($line =~ s/\@float Table\,(.*)/\\begin{table}[thp]\n\\centering/g) {
 			$label = $1;
                         push(@stack, NORMAL);
                         $mode = FLOAT_TABLE;
diff --git a/lib/includes/gnutls/gnutls.h.in b/lib/includes/gnutls/gnutls.h.in
index dea88db02d..5034d80650 100644
--- a/lib/includes/gnutls/gnutls.h.in
+++ b/lib/includes/gnutls/gnutls.h.in
@@ -270,8 +270,8 @@ extern "C"
 /**
  * gnutls_compression_method_t:
  * @GNUTLS_COMP_UNKNOWN: Unknown compression method.
- * @GNUTLS_COMP_NULL: The NULL compression method (uncompressed).
- * @GNUTLS_COMP_DEFLATE: The deflate/zlib compression method.
+ * @GNUTLS_COMP_NULL: The NULL compression method (no compression).
+ * @GNUTLS_COMP_DEFLATE: The DEFLATE compression method from zlib.
  * @GNUTLS_COMP_ZLIB: Same as %GNUTLS_COMP_DEFLATE.
  *
  * Enumeration of different TLS compression methods.