diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 800e68a19e0..498b8df9889 100644
--- 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 004b36084f1..cfc805f7853 100644
--- 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