Support channel binding 'tls-unique' in SCRAM

This is the basic feature set using OpenSSL to support the feature.  In
order to allow the frontend and the backend to fetch the sent and
expected TLS Finished messages, a PG-like API is added to be able to
make the interface pluggable for other SSL implementations.

This commit also adds a infrastructure to facilitate the addition of
future channel binding types as well as libpq parameters to control the
SASL mechanism names and channel binding names.  Those will be added by
upcoming commits.

Some tests are added to the SSL test suite to test SCRAM authentication
with channel binding.

Author: Michael Paquier <michael@paquier.xyz>
Reviewed-by: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>

1 files changed, 21 insertions, 10 deletions

diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 6d4dcf83ac9..4d3b6446c41 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1461,10 +1461,11 @@ SELCT 1/0;
 
 <para>
 <firstterm>SASL</firstterm> is a framework for authentication in connection-oriented
-protocols. At the moment, <productname>PostgreSQL</productname> implements only one SASL
-authentication mechanism, SCRAM-SHA-256, but more might be added in the
-future. The below steps illustrate how SASL authentication is performed in
-general, while the next subsection gives more details on SCRAM-SHA-256.
+protocols. At the moment, <productname>PostgreSQL</productname> implements two SASL
+authentication mechanisms, SCRAM-SHA-256 and SCRAM-SHA-256-PLUS. More
+might be added in the future. The below steps illustrate how SASL
+authentication is performed in general, while the next subsection gives
+more details on SCRAM-SHA-256 and SCRAM-SHA-256-PLUS.
 </para>
 
 <procedure>
@@ -1518,9 +1519,10 @@ ErrorMessage.
   <title>SCRAM-SHA-256 authentication</title>
 
   <para>
-    <firstterm>SCRAM-SHA-256</firstterm> (called just <firstterm>SCRAM</firstterm> from now on) is
-    the only implemented SASL mechanism, at the moment. It is described in detail
-    in RFC 7677 and RFC 5802.
+   The implemented SASL mechanisms at the moment
+   are <literal>SCRAM-SHA-256</literal> and its variant with channel
+   binding <literal>SCRAM-SHA-256-PLUS</literal>. They are described in
+   detail in RFC 7677 and RFC 5802.
   </para>
 
   <para>
@@ -1547,7 +1549,10 @@ the password is in.
   </para>
 
   <para>
-<firstterm>Channel binding</firstterm> has not been implemented yet.
+<firstterm>Channel binding</firstterm> is supported in PostgreSQL builds with
+SSL support. The SASL mechanism name for SCRAM with channel binding
+is <literal>SCRAM-SHA-256-PLUS</literal>.  The only channel binding type
+supported at the moment is <literal>tls-unique</literal>, defined in RFC 5929.
   </para>
 
 <procedure>
@@ -1556,13 +1561,19 @@ the password is in.
 <para>
   The server sends an AuthenticationSASL message. It includes a list of
   SASL authentication mechanisms that the server can accept.
+  This will be <literal>SCRAM-SHA-256-PLUS</literal>
+  and <literal>SCRAM-SHA-256</literal> if the server is built with SSL
+  support, or else just the latter.
 </para>
 </step>
 <step id="scram-client-first">
 <para>
   The client responds by sending a SASLInitialResponse message, which
-  indicates the chosen mechanism, <literal>SCRAM-SHA-256</literal>. In the Initial
-  Client response field, the message contains the SCRAM
+  indicates the chosen mechanism, <literal>SCRAM-SHA-256</literal> or
+  <literal>SCRAM-SHA-256-PLUS</literal>. (A client is free to choose either
+  mechanism, but for better security it should choose the channel-binding
+  variant if it can support it.) In the Initial Client response field,
+  the message contains the SCRAM
   <structname>client-first-message</structname>.
 </para>
 </step>