Refactor SASL code with a generic interface for its mechanisms

The code of SCRAM and SASL have been tightly linked together since SCRAM
exists in the core code, making hard to apprehend the addition of new
SASL mechanisms, but these are by design different facilities, with
SCRAM being an option for SASL.  This refactors the code related to both
so as the backend and the frontend use a set of callbacks for SASL
mechanisms, documenting while on it what is expected by anybody adding a
new SASL mechanism.

The separation between both layers is neat, using two sets of callbacks
for the frontend and the backend to mark the frontier between both
facilities.  The shape of the callbacks is now directly inspired from
the routines used by SCRAM, so the code change is straight-forward, and
the SASL code is moved into its own set of files.  These will likely
change depending on how and if new SASL mechanisms get added in the
future.

Author: Jacob Champion
Reviewed-by: Michael Paquier
Discussion: https://postgr.es/m/3d2a6f5d50e741117d6baf83eb67ebf1a8a35a11.camel@vmware.com

1 files changed, 130 insertions, 0 deletions

diff --git a/src/interfaces/libpq/fe-auth-sasl.h b/src/interfaces/libpq/fe-auth-sasl.h
new file mode 100644
index 00000000000..0aec588a9eb
--- /dev/null
+++ b/src/interfaces/libpq/fe-auth-sasl.h
@@ -0,0 +1,130 @@
+/*-------------------------------------------------------------------------
+ *
+ * fe-auth-sasl.h
+ *	  Defines the SASL mechanism interface for libpq.
+ *
+ * Each SASL mechanism defines a frontend and a backend callback structure.
+ * This is not part of the public API for applications.
+ *
+ * See src/include/libpq/sasl.h for the backend counterpart.
+ *
+ * Portions Copyright (c) 1996-2021, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1994, Regents of the University of California
+ *
+ * src/interfaces/libpq/fe-auth-sasl.h
+ *
+ *-------------------------------------------------------------------------
+ */
+
+#ifndef FE_AUTH_SASL_H
+#define FE_AUTH_SASL_H
+
+#include "libpq-fe.h"
+
+/*
+ * Frontend SASL mechanism callbacks.
+ *
+ * To implement a frontend mechanism, declare a pg_be_sasl_mech struct with
+ * appropriate callback implementations, then hook it into conn->sasl during
+ * pg_SASL_init()'s mechanism negotiation.
+ */
+typedef struct pg_fe_sasl_mech
+{
+	/*-------
+	 * init()
+	 *
+	 * Initializes mechanism-specific state for a connection.  This
+	 * callback must return a pointer to its allocated state, which will
+	 * be passed as-is as the first argument to the other callbacks.
+	 * the free() callback is called to release any state resources.
+	 *
+	 * If state allocation fails, the implementation should return NULL to
+	 * fail the authentication exchange.
+	 *
+	 * Input parameters:
+	 *
+	 *   conn:     The connection to the server
+	 *
+	 *   password: The user's supplied password for the current connection
+	 *
+	 *   mech:     The mechanism name in use, for implementations that may
+	 *			   advertise more than one name (such as *-PLUS variants).
+	 *-------
+	 */
+	void	   *(*init) (PGconn *conn, const char *password, const char *mech);
+
+	/*--------
+	 * exchange()
+	 *
+	 * Produces a client response to a server challenge.  As a special case
+	 * for client-first SASL mechanisms, exchange() is called with a NULL
+	 * server response once at the start of the authentication exchange to
+	 * generate an initial response.
+	 *
+	 * Input parameters:
+	 *
+	 *	state:	   The opaque mechanism state returned by init()
+	 *
+	 *	input:	   The challenge data sent by the server, or NULL when
+	 *			   generating a client-first initial response (that is, when
+	 *			   the server expects the client to send a message to start
+	 *			   the exchange).  This is guaranteed to be null-terminated
+	 *			   for safety, but SASL allows embedded nulls in challenges,
+	 *			   so mechanisms must be careful to check inputlen.
+	 *
+	 *	inputlen:  The length of the challenge data sent by the server, or -1
+	 *             during client-first initial response generation.
+	 *
+	 * Output parameters, to be set by the callback function:
+	 *
+	 *	output:	   A malloc'd buffer containing the client's response to
+	 *			   the server, or NULL if the exchange should be aborted.
+	 *			   (*success should be set to false in the latter case.)
+	 *
+	 *	outputlen: The length of the client response buffer, or zero if no
+	 *			   data should be sent due to an exchange failure
+	 *
+	 *	done:      Set to true if the SASL exchange should not continue,
+	 *			   because the exchange is either complete or failed
+	 *
+	 *	success:   Set to true if the SASL exchange completed successfully.
+	 *			   Ignored if *done is false.
+	 *--------
+	 */
+	void		(*exchange) (void *state, char *input, int inputlen,
+							 char **output, int *outputlen,
+							 bool *done, bool *success);
+
+	/*--------
+	 * channel_bound()
+	 *
+	 * Returns true if the connection has an established channel binding.  A
+	 * mechanism implementation must ensure that a SASL exchange has actually
+	 * been completed, in addition to checking that channel binding is in use.
+	 *
+	 * Mechanisms that do not implement channel binding may simply return
+	 * false.
+	 *
+	 * Input parameters:
+	 *
+	 *	state:    The opaque mechanism state returned by init()
+	 *--------
+	 */
+	bool		(*channel_bound) (void *state);
+
+	/*--------
+	 * free()
+	 *
+	 * Frees the state allocated by init(). This is called when the connection
+	 * is dropped, not when the exchange is completed.
+	 *
+	 * Input parameters:
+	 *
+	 *   state:    The opaque mechanism state returned by init()
+	 *--------
+	 */
+	void		(*free) (void *state);
+
+} pg_fe_sasl_mech;
+
+#endif							/* FE_AUTH_SASL_H */