reorganization and added section on parameter generation.

4 files changed, 88 insertions, 59 deletions

diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi
index b359af9b18..9336ab5834 100644
--- a/doc/cha-auth.texi
+++ b/doc/cha-auth.texi
@@ -116,40 +116,10 @@ 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
+than 1024 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 useful 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
+structure, by the server. For more information check the @ref{Parameter generation}
+section.
 
 Key exchange algorithms for @acronym{OpenPGP} and @acronym{X.509}
 certificates:
@@ -209,7 +179,8 @@ 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.
+associated with an anonymous credentials structure. Check
+@ref{Parameter generation} for more information.
 
 Supported anonymous key exchange algorithms:
 
@@ -389,6 +360,8 @@ Key exchange algorithms and the corresponding credential types:
 @item @code{KX_RSA}
 @item @code{KX_DHE_RSA}
 @item @code{KX_DHE_DSS}
+@item @code{KX_ECDHE_RSA}
+@item @code{KX_ECDHE_ECDSA}
 @item @code{KX_RSA_EXPORT}
 @tab @code{CRD_CERTIFICATE}
 @tab @code{CRD_CERTIFICATE}
@@ -405,10 +378,12 @@ Key exchange algorithms and the corresponding credential types:
 @tab @code{CRD_SRP}
 
 @item @code{KX_ANON_DH}
+@item @code{KX_ANON_ECDH}
 @tab @code{CRD_ANON}
 @tab @code{CRD_ANON}
 
 @item @code{KX_PSK}
+@item @code{KX_DHE_PSK}
 @tab @code{CRD_PSK}
 @tab @code{CRD_PSK}
 
diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index 69e10b87b6..c64e61bcdd 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -7,7 +7,7 @@
 * The X.509 trust model::
 * The OpenPGP trust model::
 * PKCS #11 tokens::
-* Abstract data types::
+* Abstract key types::
 * Digital signatures::
 @end menu
 
@@ -555,8 +555,8 @@ certificates.
 @end itemize
 
 
-@node Abstract data types
-@section Abstract data types
+@node Abstract key types
+@section Abstract key types
 @anchor{sec:abstract}
 @cindex Abstract types
 
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 935ea40d3b..c61d3f5c9f 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -8,9 +8,7 @@
 * Client examples::
 * Server examples::
 * Miscellaneous examples::
-* Compatibility with the OpenSSL library::
-* Keying Material Exporters::
-* Channel Bindings::
+* Advanced and other topics::
 @end menu
 
 @node Preparation
@@ -375,31 +373,63 @@ structure.
 
 @verbatiminclude examples/ex-pkcs12.c
 
-@node Compatibility with the OpenSSL library
-@section Compatibility with the OpenSSL Library
-@cindex OpenSSL
+@node Advanced and other topics
+@section Advanced and other topics
 
-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.
+@menu
+* Parameter generation::
+* Keying Material Exporters::
+* Channel Bindings::
+* Compatibility with the OpenSSL library::
+@end menu
 
-The prototypes for the compatibility functions are in the
-@file{gnutls/openssl.h} header file.
 
-Current limitations imposed by the compatibility layer include:
+@node Parameter generation
+@subsection Parameter generation
+@cindex parameter generation
+@cindex generating parameters
+
+Several TLS ciphersuites require additional parameters that
+need to be generated or provided by the application. The
+Diffie-Hellman based ciphersuites (ANON-DH or DHE), require
+the group information to be provided. This information can be either
+be generated on the fly using @ref{gnutls_dh_params_generate2}
+or imported from some pregenerated value using @ref{gnutls_dh_params_import_pkcs3}.
+The parameters can be used in a session by calling
+@ref{gnutls_certificate_set_dh_params} or
+@ref{gnutls_anon_set_server_dh_params} for anonymous sessions.
+
+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 @ref{gnutls_sec_param_to_pk_bits} to determine
+the bit size of the parameters to be generated.
+
+The ciphersuites that involve the RSA-EXPORT key exchange require
+additional parameters. Those ciphersuites are rarely used today
+because they are by design insecure, thus if you have no requirement
+for them, this section should be skipped. The RSA-EXPORT key exchange
+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 Error handling is not thread safe.
+@item @ref{gnutls_rsa_params_generate2}
+
+@item @ref{gnutls_certificate_set_rsa_export_params}
+
+@item @ref{gnutls_rsa_params_import_pkcs1}
+
+@item @ref{gnutls_rsa_params_export_pkcs1}
 
 @end itemize
 
+
 @node Keying Material Exporters
-@section Keying Material Exporters
+@subsection Keying Material Exporters
 @cindex Keying Material Exporters
 @cindex Exporting Keying Material
 
@@ -425,7 +455,7 @@ 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 Channel Bindings
-@section Channel Bindings
+@subsection Channel Bindings
 @cindex Channel Bindings
 
 In user authentication protocols (e.g., EAP or SASL mechanisms) it is
@@ -465,3 +495,27 @@ Note that it must be run after a successful TLS handshake.
     @}
 @}
 @end smallexample
+
+@node Compatibility with the OpenSSL library
+@subsection 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 limited 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
+
diff --git a/doc/gnutls.texi b/doc/gnutls.texi
index eb8c1c73dc..f0d7ed2b02 100644
--- a/doc/gnutls.texi
+++ b/doc/gnutls.texi
@@ -76,8 +76,8 @@ Documentation License''.
 * Introduction to TLS::
 * Authentication methods::
 * More on certificate authentication::
-* How to use TLS in application protocols::
 * How to use GnuTLS in applications::
+* How to use TLS in application protocols::
 * Included programs::
 * Function reference::
 * All the supported ciphersuites in GnuTLS::
@@ -100,10 +100,10 @@ Documentation License''.
 
 @include cha-cert-auth.texi
 
-@include cha-tls-app.texi
-
 @include cha-gtls-app.texi
 
+@include cha-tls-app.texi
+
 @include cha-programs.texi
 
 @include cha-functions.texi