Add support for SCRAM-SHA-256 authentication.

SCRAM-SHA-256 authentication was introduced in PostgreSQL 10 as a better way
for handling password based authentication.

This implementation follows the guidance provided in the documentation, i.e.

https://www.postgresql.org/docs/current/sasl-authentication.html#SASL-SCRAM-SHA-256

Author: jkatz

asyncpg/protocol/coreproto.pxd

@@ -5,6 +5,9 @@
 # the Apache 2.0 License: http://www.apache.org/licenses/LICENSE-2.0
 
 
+include "scram.pxd"
+
+
 cdef enum ConnectionStatus:
     CONNECTION_OK = 1
     CONNECTION_BAD = 2
@@ -43,13 +46,17 @@ cdef enum AuthenticationMessage:
     AUTH_REQUIRED_GSS = 7
     AUTH_REQUIRED_GSS_CONTINUE = 8
     AUTH_REQUIRED_SSPI = 9
+    AUTH_REQUIRED_SASL = 10
+    AUTH_SASL_CONTINUE = 11
+    AUTH_SASL_FINAL = 12
 
 
 AUTH_METHOD_NAME = {
     AUTH_REQUIRED_KERBEROS: 'kerberosv5',
     AUTH_REQUIRED_PASSWORD: 'password',
     AUTH_REQUIRED_PASSWORDMD5: 'md5',
     AUTH_REQUIRED_GSS: 'gss',
+    AUTH_REQUIRED_SASL: 'scram-sha-256',
     AUTH_REQUIRED_SSPI: 'sspi',
 }
 
@@ -91,6 +98,8 @@ cdef class CoreProtocol:
 
         # Instance of _ConnectionParameters
         object con_params
+        # Instance of SCRAMAuthentication
+        SCRAMAuthentication scram
 
         readonly int32_t backend_pid
         readonly int32_t backend_secret
@@ -133,6 +142,8 @@ cdef class CoreProtocol:
 
     cdef _auth_password_message_cleartext(self)
     cdef _auth_password_message_md5(self, bytes salt)
+    cdef _auth_password_message_sasl_initial(self, list sasl_auth_methods)
+    cdef _auth_password_message_sasl_continue(self, bytes server_response)
 
     cdef _write(self, buf)
 

asyncpg/protocol/coreproto.pyx

@@ -8,6 +8,9 @@
 from hashlib import md5 as hashlib_md5  # for MD5 authentication
 
 
+include "scram.pyx"
+
+
 cdef class CoreProtocol:
 
     def __init__(self, con_params):
@@ -21,6 +24,8 @@ cdef class CoreProtocol:
         self.state = PROTOCOL_IDLE
         self.xact_status = PQTRANS_IDLE
         self.encoding = 'utf-8'
+        # type of `scram` is `SCRAMAuthentcation`
+        self.scram = None
 
         # executemany support data
         self._execute_iter = None
@@ -528,6 +533,8 @@ cdef class CoreProtocol:
         cdef:
             int32_t status
             bytes md5_salt
+            list sasl_auth_methods
+            list unsupported_sasl_auth_methods
 
         status = self.buffer.read_int32()
 
@@ -546,6 +553,58 @@ cdef class CoreProtocol:
             md5_salt = self.buffer.read_bytes(4)
             self.auth_msg = self._auth_password_message_md5(md5_salt)
 
+        elif status == AUTH_REQUIRED_SASL:
+            # AuthenticationSASL
+            # This requires making additional requests to the server in order
+            # to follow the SCRAM protocol defined in RFC 5802.
+            # get the SASL authentication methods that the server is providing
+            sasl_auth_methods = []
+            unsupported_sasl_auth_methods = []
+            # determine if the advertised authentication methods are supported,
+            # and if so, add them to the list
+            auth_method = self.buffer.read_null_str()
+            while auth_method:
+                if auth_method in SCRAMAuthentication.AUTHENTICATION_METHODS:
+                    sasl_auth_methods.append(auth_method)
+                else:
+                    unsupported_sasl_auth_methods.append(auth_method)
+                auth_method = self.buffer.read_null_str()
+
+            # if none of the advertised authentication methods are supported,
+            # raise an error
+            # otherwise, initialize the SASL authentication exchange
+            if not sasl_auth_methods:
+                unsupported_sasl_auth_methods = [m.decode("ascii")
+                    for m in unsupported_sasl_auth_methods]
+                self.result_type = RESULT_FAILED
+                self.result = apg_exc.InterfaceError(
+                    'unsupported SASL Authentication methods requested by the '
+                    'server: {!r}'.format(
+                        ", ".join(unsupported_sasl_auth_methods)))
+            else:
+                self.auth_msg = self._auth_password_message_sasl_initial(
+                    sasl_auth_methods)
+
+        elif status == AUTH_SASL_CONTINUE:
+            # AUTH_SASL_CONTINUE
+            # this requeires sending the second part of the SASL exchange, where
+            # the client parses information back from the server and determines
+            # if this is valid.
+            # The client builds a challenge response to the server
+            server_response = self.buffer.consume_message()
+            self.auth_msg = self._auth_password_message_sasl_continue(
+                server_response)
+
+        elif status == AUTH_SASL_FINAL:
+            # AUTH_SASL_FINAL
+            server_response = self.buffer.consume_message()
+            if not self.scram.verify_server_final_message(server_response):
+                self.result_type = RESULT_FAILED
+                self.result = apg_exc.InterfaceError(
+                    'could not verify server signature for '
+                    'SCRAM authentciation: scram-sha-256',
+                )
+
         elif status in (AUTH_REQUIRED_KERBEROS, AUTH_REQUIRED_SCMCRED,
                         AUTH_REQUIRED_GSS, AUTH_REQUIRED_GSS_CONTINUE,
                         AUTH_REQUIRED_SSPI):
@@ -560,7 +619,8 @@ cdef class CoreProtocol:
                 'unsupported authentication method requested by the '
                 'server: {}'.format(status))
 
-        self.buffer.discard_message()
+        if status not in [AUTH_SASL_CONTINUE, AUTH_SASL_FINAL]:
+            self.buffer.discard_message()
 
     cdef _auth_password_message_cleartext(self):
         cdef:
@@ -588,6 +648,34 @@ cdef class CoreProtocol:
 
         return msg
 
+    cdef _auth_password_message_sasl_initial(self, list sasl_auth_methods):
+        cdef:
+            WriteBuffer msg
+
+        # use the first supported advertized mechanism
+        self.scram = SCRAMAuthentication(sasl_auth_methods[0])
+        # this involves a call and response with the server
+        msg = WriteBuffer.new_message(b'p')
+        msg.write_bytes(self.scram.create_client_first_message(self.user or ''))
+        msg.end_message()
+
+        return msg
+
+    cdef _auth_password_message_sasl_continue(self, bytes server_response):
+        cdef:
+            WriteBuffer msg
+
+        # determine if there is a valid server response
+        self.scram.parse_server_first_message(server_response)
+        # this involves a call and response with the server
+        msg = WriteBuffer.new_message(b'p')
+        client_final_message = self.scram.create_client_final_message(
+            self.password or '')
+        msg.write_bytes(client_final_message)
+        msg.end_message()
+
+        return msg
+
     cdef _parse_msg_ready_for_query(self):
         cdef char status = self.buffer.read_byte()
 

asyncpg/protocol/scram.pxd

@@ -0,0 +1,31 @@
+# Copyright (C) 2016-present the asyncpg authors and contributors
+# <see AUTHORS file>
+#
+# This module is part of asyncpg and is released under
+# the Apache 2.0 License: http://www.apache.org/licenses/LICENSE-2.0
+
+
+cdef class SCRAMAuthentication:
+    cdef:
+        readonly bytes authentication_method
+        readonly bytes authorization_message
+        readonly bytes client_channel_binding
+        readonly bytes client_first_message_bare
+        readonly bytes client_nonce
+        readonly bytes client_proof
+        readonly bytes password_salt
+        readonly int   password_iterations
+        readonly bytes server_first_message
+        # server_key is an instance of hmac.HAMC
+        readonly object server_key
+        readonly bytes server_nonce
+
+    cdef create_client_first_message(self, str username)
+    cdef create_client_final_message(self, str password)
+    cdef parse_server_first_message(self, bytes server_response)
+    cdef verify_server_final_message(self, bytes server_final_message)
+    cdef _bytes_xor(self, bytes a, bytes b)
+    cdef _generate_client_nonce(self, int num_bytes)
+    cdef _generate_client_proof(self, str password)
+    cdef _generate_salted_password(self, str password, bytes salt, int iterations)
+    cdef _normalize_password(self, str original_password)