/*-------------------------------------------------------------------------
 *
 * 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-2025, 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"

/*
 * Possible states for the SASL exchange, see the comment on exchange for an
 * explanation of these.
 */
typedef enum
{
	SASL_COMPLETE = 0,
	SASL_FAILED,
	SASL_CONTINUE,
	SASL_ASYNC,
} SASLStatus;

/*
 * Frontend SASL mechanism callbacks.
 *
 * To implement a frontend mechanism, declare a pg_fe_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. Returns a SASLStatus indicating the
	 * state and status of the exchange.
	 *
	 * Input parameters:
	 *
	 *	state:	   The opaque mechanism state returned by init()
	 *
	 *	final:	   true if the server has sent a final exchange outcome
	 *
	 *	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 (can be empty), or NULL if the exchange should
	 *			   be aborted.  (The callback should return SASL_FAILED in the
	 *			   latter case.)
	 *
	 *	outputlen: The length (0 or higher) of the client response buffer,
	 *			   ignored if output is NULL.
	 *
	 * Return value:
	 *
	 *	SASL_CONTINUE:	The output buffer is filled with a client response.
	 *					Additional server challenge is expected
	 *	SASL_ASYNC:		Some asynchronous processing external to the
	 *					connection needs to be done before a response can be
	 *					generated. The mechanism is responsible for setting up
	 *					conn->async_auth/cleanup_async_auth appropriately
	 *					before returning.
	 *	SASL_COMPLETE:	The SASL exchange has completed successfully.
	 *	SASL_FAILED:	The exchange has failed and the connection should be
	 *					dropped.
	 *--------
	 */
	SASLStatus	(*exchange) (void *state, bool final,
							 char *input, int inputlen,
							 char **output, int *outputlen);

	/*--------
	 * 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 */