updated documentation.

2 files changed, 87 insertions, 58 deletions

diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index 72b9919e0d..eeb1f7334f 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -442,6 +442,13 @@ to verify the signatures in the certificate sent by the peer.
 @section Advanced certificate verification
 @cindex Certificate verification
 
+The verification of X.509 certificates in the HTTPS and other Internet protocols is typically 
+done by loading a trusted list of commercial Certificate Authorities
+(see @funcref{gnutls_certificate_set_x509_system_trust}), and using them as trusted anchors.
+However, there are several examples (eg. the Diginotar incident) where one of these
+authorities was compromised. This risk can be mitigated by using in addition to CA certificate verification,
+other verification methods. In this section we list the available in GnuTLS methods.
+
 @menu
 * Verifying a certificate using trust on first use authentication::
 * Verifying a certificate using DANE (DNSSEC)::
@@ -453,7 +460,6 @@ to verify the signatures in the certificate sent by the peer.
 @cindex SSH-style authentication
 @cindex Trust on first use
 @cindex Key pinning
-@tindex gnutls_certificate_verify_flags
 
 It is possible to use a trust on first use (TOFU) authentication 
 method in GnuTLS. That is the concept used by the SSH programs, where the 
@@ -468,76 +474,25 @@ the trust on first use method.
 Such a hybrid system with X.509 and trust on first use authentication is 
 shown in @ref{Simple client example with SSH-style certificate verification}.
 
-@showfuncdesc{gnutls_verify_stored_pubkey}
-@showfuncdesc{gnutls_store_pubkey}
-
-In addition to the above the @funcref{gnutls_store_commitment} can be 
-used to implement a key-pinning architecture as in @xcite{KEYPIN}. 
-This provides a way for web server to commit on a public key that is
-not yet active.
-
-@showfuncdesc{gnutls_store_commitment}
-
-The storage and verification functions may be used with the default
-text file based back-end, or another back-end may be specified. That
-should contain storage and retrieval functions and specified as below.
-
-@showfuncE{gnutls_tdb_init,gnutls_tdb_deinit,gnutls_tdb_set_verify_func,gnutls_tdb_set_store_func,gnutls_tdb_set_store_commitment_func}
+See @ref{Certificate verification} on how to use the available functionality.
 
 @node Verifying a certificate using DANE (DNSSEC)
 @subsection Verifying a certificate using DANE (DNSSEC)
 @cindex verifying certificate paths
 @cindex DANE
 @cindex DNSSEC
-@tindex gnutls_certificate_verify_flags
 
 The DANE protocol is a protocol that can be used to verify TLS certificates
 using the DNS (or better DNSSEC) protocols. The DNS security extensions (DNSSEC)
 provide an alternative public key infrastructure to the commercial CAs that
 are typically used to sign TLS certificates. The DANE protocol takes advantage
 of the DNSSEC infrastructure to verify TLS certificates. This can be 
-in addition to the verification by commercial CA infrastructure or 
+in addition to the verification by CA infrastructure or 
 could even replace it where DNSSEC is deployed.
 
 The DANE functionality is provided by the @code{libgnutls-dane} library that is shipped
 with GnuTLS and the function prototypes are in @code{gnutls/dane.h}. 
-
-@subsubheading Using the DANE library
-Since the DANE library is not included in GnuTLS it requires programs
-to be linked against it. This can be achieved with the following commands.
-
-@example
-gcc -o foo foo.c `pkg-config gnutls-dane --cflags --libs`
-@end example
-
-When a program uses the GNU autoconf system, then the following
-line or similar can be used to detect the presence of the library.
-
-@example
-PKG_CHECK_MODULES([LIBDANE], [gnutls-dane >= 3.0.0])
-
-AC_SUBST([LIBDANE_CFLAGS])
-AC_SUBST([LIBDANE_LIBS])
-@end example
-
-@subsubheading DANE library functionality
-
-The library provides high level verification functions which are shown below.
-
-@showfuncdesc{dane_verify_crt}
-
-@showfuncB{dane_verify_session_crt,dane_strerror}
-
-Note that the @code{dane_state_t} structure that is accepted by both
-verification functions is optional. It is required when many queries
-are performed to facilitate caching.
-The following flags are returned by the verify functions to
-indicate the status of the verification.
-
-@showenumdesc{dane_verify_status_t,The DANE verification status flags.}
-
-In order to generate a DANE TLSA entry to use in a DNS server 
-you may use danetool (see @ref{danetool Invocation}).
+See @ref{Certificate verification} for information on how to use the library.
 
 @node Digital signatures
 @section Digital signatures
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 7b5150b3bf..baa316af91 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -11,7 +11,7 @@
 * Data transfer and termination::
 * Handling alerts::
 * Priority Strings::
-* Advanced and other topics::
+* Advanced topics::
 * Using the cryptographic library::
 * Selecting cryptographic key sizes::
 @end menu
@@ -1067,11 +1067,12 @@ except TLS 1.2:
     "SECURE128:+SECURE192:-VERS-TLS-ALL:+VERS-TLS1.2"
 @end example
 
-@node Advanced and other topics
-@section Advanced and other topics
+@node Advanced topics
+@section Advanced topics
 
 @menu
 * Session resumption::
+* Certificate verification::
 * Parameter generation::
 * Keying Material Exporters::
 * Channel Bindings::
@@ -1130,6 +1131,77 @@ Those keys should be associated with the GnuTLS session using
 A server enabling both session tickets and a storage for session data
 would use session tickets when clients support it and the storage otherwise.
 
+@node Certificate verification
+@subsection Certificate verification
+@cindex DANE
+@cindex DNSSEC
+@cindex SSH-style authentication
+@cindex Trust on first use
+@cindex Key pinning
+@tindex gnutls_certificate_verify_flags
+
+In this section the functionality for additional certificate verification methods is listed. 
+These methods are intended to be used in addition to normal PKI verification, in order to reduce 
+the risk of a compromised CA being undetected.
+
+@subsubsection Trust on first use
+
+The GnuTLS library includes functionlity to use an SSH-like trust on first use authentication.
+The available functions to store and verify public keys are listed below.
+
+@showfuncdesc{gnutls_verify_stored_pubkey}
+@showfuncdesc{gnutls_store_pubkey}
+
+In addition to the above the @funcref{gnutls_store_commitment} can be 
+used to implement a key-pinning architecture as in @xcite{KEYPIN}. 
+This provides a way for web server to commit on a public key that is
+not yet active.
+
+@showfuncdesc{gnutls_store_commitment}
+
+The storage and verification functions may be used with the default
+text file based back-end, or another back-end may be specified. That
+should contain storage and retrieval functions and specified as below.
+
+@showfuncE{gnutls_tdb_init,gnutls_tdb_deinit,gnutls_tdb_set_verify_func,gnutls_tdb_set_store_func,gnutls_tdb_set_store_commitment_func}
+
+@subsubsection DANE verification
+Since the DANE library is not included in GnuTLS it requires programs
+to be linked against it. This can be achieved with the following commands.
+
+@example
+gcc -o foo foo.c `pkg-config gnutls-dane --cflags --libs`
+@end example
+
+When a program uses the GNU autoconf system, then the following
+line or similar can be used to detect the presence of the library.
+
+@example
+PKG_CHECK_MODULES([LIBDANE], [gnutls-dane >= 3.0.0])
+
+AC_SUBST([LIBDANE_CFLAGS])
+AC_SUBST([LIBDANE_LIBS])
+@end example
+
+The high level functionality provided by the DANE library is shown below.
+
+@showfuncdesc{dane_verify_crt}
+
+@showfuncB{dane_verify_session_crt,dane_strerror}
+
+Note that the @code{dane_state_t} structure that is accepted by both
+verification functions is optional. It is required when many queries
+are performed to facilitate caching.
+The following flags are returned by the verify functions to
+indicate the status of the verification.
+
+@showenumdesc{dane_verify_status_t,The DANE verification status flags.}
+
+In order to generate a DANE TLSA entry to use in a DNS server 
+you may use danetool (see @ref{danetool Invocation}).
+
+
+
 @node Parameter generation
 @subsection Parameter generation
 @cindex parameter generation
@@ -1283,6 +1355,8 @@ that only allows the stream cipher ARCFOUR is below.
 NORMAL:-VERS-TLS-ALL:+VERS-TLS1.0:+VERS-SSL3.0:-CIPHER-ALL:+ARCFOUR-128:%COMPAT
 @end verbatim
 
+
+
 @node Compatibility with the OpenSSL library
 @subsection Compatibility with the OpenSSL library
 @cindex OpenSSL