doc: clarify SCRAM channel binding

Discussion: https://postgr.es/m/20180514231020[email protected]

Reviewed-by: Michael Paquier

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 800e68a19e086d3e152fe7102627118e9c9cd481..498b8df98898aec7dc6af882b989dd685adfe690 100644 (file)
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1242,14 +1242,18 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       scram_channel_binding
       
        
-        Specifies the channel binding type to use with SCRAM authentication.
-        The list of channel binding types supported by server are listed in
-        .  An empty value specifies that
-        the client will not use channel binding.  The default value is
-        tls-unique.
+        Specifies the channel binding type to use with SCRAM
+        authentication.  While SCRAM alone prevents
+        the replay of transmitted hashed passwords, channel binding also
+        prevents man-in-the-middle attacks.
        
 
        
+        The list of channel binding types supported by the server are
+        listed in .  An empty value
+        specifies that the client will not use channel binding.  If this
+        parameter is not specified, tls-unique 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.
        

diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 004b36084f19a925c958ee3e11de909585b5e267..cfc805f7853ea5c217c853333b29366cc8ee9c02 100644 (file)
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1584,6 +1584,33 @@ should use tls-unique if they can support it.
 that cannot support tls-unique for some reason.
   
 
+  
+   In SCRAM 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.
+  
+
+  
+   SCRAM 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 SCRAM with tls-unique
+   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.
+   SCRAM with tls-server-end-point
+   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.
+  
+
 
 Example