Document channel binding API.

3 files changed, 53 insertions, 1 deletions

diff --git a/NEWS b/NEWS
index 2134b80df1..997d201eb1 100644
--- a/NEWS
+++ b/NEWS
@@ -8,7 +8,8 @@ See the end for copying conditions.
 ** libgnutls: Add new API gnutls_session_channel_binding.
 The function is used to get the channel binding data.  Currently only
 the "tls-unique" (RFC 5929) channel binding type is supported, through
-the GNUTLS_CB_TLS_UNIQUE type.
+the GNUTLS_CB_TLS_UNIQUE type.  See new section "Channel Bindings" in
+the manual.
 
 ** doc: Added pkcs11.h header file to GTK-DOC manual.
 
diff --git a/doc/cha-bib.texi b/doc/cha-bib.texi
index 840af8795e..9664dd9d20 100644
--- a/doc/cha-bib.texi
+++ b/doc/cha-bib.texi
@@ -149,4 +149,12 @@ European Network of Excellence in Cryptology II, "ECRYPT II Yearly
 Report on Algorithms and Keysizes (2009-2010)", Available
 at @url{http://www.ecrypt.eu.org/documents/D.SPA.13.pdf}.
 
+@item @anchor{RFC5056}[RFC5056]
+N. Williams, "On the Use of Channel Bindings to Secure Channels",
+November 2007, available from @url{http://www.ietf.org/rfc/rfc5056}.
+
+@item @anchor{RFC5929}[RFC5929]
+J. Altman, N. Williams, L. Zhu, "Channel Bindings for TLS", July 2010,
+available from @url{http://www.ietf.org/rfc/rfc5929}.
+
 @end table
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 6512e3b667..2dfa871cf5 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -11,6 +11,7 @@
 * Miscellaneous examples::
 * Compatibility with the OpenSSL library::
 * Keying Material Exporters::
+* Channel Bindings::
 @end menu
 
 @node Preparation
@@ -450,3 +451,45 @@ rc = gnutls_prf (session, strlen (MYLABEL), MYLABEL, 0,
 
 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
+@cindex Channel Bindings
+
+In user authentication protocols (e.g., EAP or SASL mechanisms) it is
+useful to have a unique string that identifies the secure channel that
+is used, to bind together the user authentication with the secure
+channel.  This can protect against man-in-the-middle attacks in some
+situations.  The unique strings is a ``channel bindings''.  For
+background and more discussion see @xcite{RFC5056}.
+
+You can extract a channel bindings using the
+@ref{gnutls_session_channel_binding} function.  Currently only the
+@code{GNUTLS_CB_TLS_UNIQUE} type is supported, which corresponds to
+the @code{tls-unique} channel bindings for TLS defined in
+@xcite{RFC5929}.
+
+The following example describes how to print the channel binding data.
+Note that it must be run after a successful TLS handshake.
+
+@smallexample
+@{
+  gnutls_datum cb;
+  int rc;
+
+  rc = gnutls_session_channel_binding (session,
+                                       GNUTLS_CB_TLS_UNIQUE,
+                                       &cb);
+  if (rc)
+    fprintf (stderr, "Channel binding error: %s\n",
+             gnutls_strerror (rc));
+  else
+    @{
+      size_t i;
+      printf ("- Channel binding 'tls-unique': ");
+      for (i = 0; i < cb.size; i++)
+        printf ("%02x", cb.data[i]);
+      printf ("\n");
+    @}
+@}
+@end smallexample