From: Nikos Mavrogiannopoulos <nmav@gnutls.org>
Date: Wed, 15 Feb 2012 22:16:20 +0000 (+0100)
Subject: doc updates
X-Git-Tag: gnutls_3_0_13~25
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=784f5810c8b9cb2de2f12627b2fc7e048fcc3e79;p=thirdparty%2Fgnutls.git

doc updates
---

diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index 2068f5c05a..4b40b50dbc 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -286,28 +286,31 @@ consult @xcite{RFC2818} and section @ref{ex:verify} for an example.
 @tindex gnutls_certificate_verify_flags
 
 It is possible to use a trust on first use (similar to SSH) authentication 
-method in GnuTLS. That means that having seen and associated a public key 
-with a host is enough to trust it on the subsequent connections. Such
-a system in combination with the normal CA verification, and OCSP verification,
+method in GnuTLS. That is the concept used by the SSH programs, where the 
+public key of the peer is not verified, or verified in an out-of-bound way,
+but subsequent connections to the same peer require the public key to 
+remain the same.  Such a system in combination with the typical CA 
+verification of a certificate, and OCSP revocation checks,
 can help to provide multiple factor verification, where a single point of
 failure is not enough to compromise the system. For example a server compromise
 may be detected using OCSP, and a CA compromise can be detected using
 the trust on first use method.
-Such a hybrid system with X.509 and SSH authentication is 
+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}
-@showfuncdesc{gnutls_store_commitment}
 
-The @funcref{gnutls_store_commitment} may be used to implement a
-key-pinning architecture as in @xcite{KEYPIN}.
-http://tools.ietf.org/html/draft-ietf-websec-key-pinning-01
+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 backend, or another backend may be specified. Such
-backend should contain a storage and a retrieval function. The format
-of those functions is shown below.
+text file based back-end, or another back-end may be specified. That
+should contain storage and retrieval functions as shown below.
 @example
   typedef int (*gnutls_trust_db_store_func) (const char* db_name, 
                                              const char* host,
diff --git a/doc/cha-internals.texi b/doc/cha-internals.texi
index bb8b420f3b..0f05935897 100644
--- a/doc/cha-internals.texi
+++ b/doc/cha-internals.texi
@@ -372,7 +372,7 @@ instructions set, using the kernel interface will introduce an
 unneeded layer. For this reason GnuTLS includes such optimizations
 found in popular processors such as the AES-NI or VIA PADLOCK instruction sets.
 This is achieved using a mechanism that detects CPU capabilities and
-overrides parts of crypto backend at runtime.
+overrides parts of crypto back-end at runtime.
 The next section discusses the registration of a detected algorithm
 optimization. For more information please consult the @acronym{GnuTLS}
 source code in @code{lib/accelerated/}.
@@ -398,25 +398,25 @@ and leave the rest of subsystem intact.
 
 @subsubheading Overriding the cryptographic library
 In some systems, that might contain a broad acceleration engine, it 
-might be desirable to override big parts of the cryptographic backend, 
+might be desirable to override big parts of the cryptographic back-end, 
 or even all of them. The following functions are provided for this reason.
 
 @itemize
 
 @item @code{gnutls_crypto_cipher_register}:
-To override the cryptographic algorithms backend.
+To override the cryptographic algorithms back-end.
 
 @item @code{gnutls_crypto_digest_register}:
-To override the digest algorithms backend.
+To override the digest algorithms back-end.
 
 @item @code{gnutls_crypto_rnd_register}:
-To override the random number generator backend.
+To override the random number generator back-end.
 
 @item @code{gnutls_crypto_bigint_register}:
-To override the big number number operations backend.
+To override the big number number operations back-end.
 
 @item @code{gnutls_crypto_pk_register}:
-To override the public key encryption backend. This is tied to the
+To override the public key encryption back-end. This is tied to the
 big number operations so either none or both of them should be overriden.
 
 @end itemize