From 185f4f84d5952e5692bd2712dd32288fcbb7fa71 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Mon, 14 May 2018 20:45:35 -0400
Subject: [PATCH] doc:  clarify SCRAM channel binding

Discussion: https://postgr.es/m/20180514231020.GB1600@paquier.xyz

Reviewed-by: Michael Paquier
---
 doc/src/sgml/libpq.sgml    | 14 +++++++++-----
 doc/src/sgml/protocol.sgml | 27 +++++++++++++++++++++++++++
 2 files changed, 36 insertions(+), 5 deletions(-)

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 800e68a19e..498b8df988 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1242,14 +1242,18 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>scram_channel_binding</literal></term>
       <listitem>
        <para>
-        Specifies the channel binding type to use with SCRAM authentication.
-        The list of channel binding types supported by server are listed in
-        <xref linkend="sasl-authentication"/>.  An empty value specifies that
-        the client will not use channel binding.  The default value is
-        <literal>tls-unique</literal>.
+        Specifies the channel binding type to use with SCRAM
+        authentication.  While <acronym>SCRAM</acronym> alone prevents
+        the replay of transmitted hashed passwords, channel binding also
+        prevents man-in-the-middle attacks.
        </para>
 
        <para>
+        The list of channel binding types supported by the server are
+        listed in <xref linkend="sasl-authentication"/>.  An empty value
+        specifies that the client will not use channel binding.  If this
+        parameter is not specified, <literal>tls-unique</literal> is used,
+        if supported by both server and client.
         Channel binding is only supported on SSL connections.  If the
         connection is not using SSL, then this setting is ignored.
        </para>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 004b36084f..cfc805f785 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1584,6 +1584,33 @@ should use <literal>tls-unique</literal> if they can support it.
 that cannot support <literal>tls-unique</literal> for some reason.
   </para>
 
+  <para>
+   In <acronym>SCRAM</acronym> without channel binding, the server chooses
+   a random number that is transmitted to the client to be mixed with the
+   user-supplied password in the transmitted password hash.  While this
+   prevents the password hash from being successfully retransmitted in
+   a later session, it does not prevent a fake server between the real
+   server and client from passing through the server's random value 
+   and successfully authenticating.
+  </para>
+
+  <para>
+   <acronym>SCRAM</acronym> with channel binding prevents such
+   man-in-the-middle attacks by mixing a value into the transmitted
+   password hash that cannot be retransmitted by a fake server.
+   In <acronym>SCRAM</acronym> with <literal>tls-unique</literal>
+   channel binding, the shared secret negotiated during the SSL session
+   is mixed into the user-supplied password hash.  The shared secret
+   is partly chosen by the server, but not directly transmitted, making
+   it impossible for a fake server to create an SSL connection with the
+   client that has the same shared secret it has with the real server.
+   <acronym>SCRAM</acronym> with <literal>tls-server-end-point</literal>
+   mixes a hash of the server's certificate into the user-supplied password
+   hash.  While a fake server can retransmit the real server's certificate,
+   it doesn't have access to the private key matching that certificate, and
+   therefore cannot prove it is the owner, causing SSL connection failure.
+  </para>
+
 <procedure>
 <title>Example</title>
   <step id="scram-begin">