codekingpro/portable-devtools

1/*-------------------------------------------------------------------------2 *3 * fe-auth-sasl.h4 *	  Defines the SASL mechanism interface for libpq.5 *6 * Each SASL mechanism defines a frontend and a backend callback structure.7 * This is not part of the public API for applications.8 *9 * See src/include/libpq/sasl.h for the backend counterpart.10 *11 * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group12 * Portions Copyright (c) 1994, Regents of the University of California13 *14 * src/interfaces/libpq/fe-auth-sasl.h15 *16 *-------------------------------------------------------------------------17 */18 19#ifndef FE_AUTH_SASL_H20#define FE_AUTH_SASL_H21 22#include "libpq-fe.h"23 24/*25 * Frontend SASL mechanism callbacks.26 *27 * To implement a frontend mechanism, declare a pg_be_sasl_mech struct with28 * appropriate callback implementations, then hook it into conn->sasl during29 * pg_SASL_init()'s mechanism negotiation.30 */31typedef struct pg_fe_sasl_mech32{33	/*-------34	 * init()35	 *36	 * Initializes mechanism-specific state for a connection.  This37	 * callback must return a pointer to its allocated state, which will38	 * be passed as-is as the first argument to the other callbacks.39	 * the free() callback is called to release any state resources.40	 *41	 * If state allocation fails, the implementation should return NULL to42	 * fail the authentication exchange.43	 *44	 * Input parameters:45	 *46	 *   conn:     The connection to the server47	 *48	 *   password: The user's supplied password for the current connection49	 *50	 *   mech:     The mechanism name in use, for implementations that may51	 *			   advertise more than one name (such as *-PLUS variants).52	 *-------53	 */54	void	   *(*init) (PGconn *conn, const char *password, const char *mech);55 56	/*--------57	 * exchange()58	 *59	 * Produces a client response to a server challenge.  As a special case60	 * for client-first SASL mechanisms, exchange() is called with a NULL61	 * server response once at the start of the authentication exchange to62	 * generate an initial response.63	 *64	 * Input parameters:65	 *66	 *	state:	   The opaque mechanism state returned by init()67	 *68	 *	input:	   The challenge data sent by the server, or NULL when69	 *			   generating a client-first initial response (that is, when70	 *			   the server expects the client to send a message to start71	 *			   the exchange).  This is guaranteed to be null-terminated72	 *			   for safety, but SASL allows embedded nulls in challenges,73	 *			   so mechanisms must be careful to check inputlen.74	 *75	 *	inputlen:  The length of the challenge data sent by the server, or -176	 *             during client-first initial response generation.77	 *78	 * Output parameters, to be set by the callback function:79	 *80	 *	output:	   A malloc'd buffer containing the client's response to81	 *			   the server (can be empty), or NULL if the exchange should82	 *			   be aborted.  (*success should be set to false in the83	 *			   latter case.)84	 *85	 *	outputlen: The length (0 or higher) of the client response buffer,86	 *			   ignored if output is NULL.87	 *88	 *	done:      Set to true if the SASL exchange should not continue,89	 *			   because the exchange is either complete or failed90	 *91	 *	success:   Set to true if the SASL exchange completed successfully.92	 *			   Ignored if *done is false.93	 *--------94	 */95	void		(*exchange) (void *state, char *input, int inputlen,96							 char **output, int *outputlen,97							 bool *done, bool *success);98 99	/*--------100	 * channel_bound()101	 *102	 * Returns true if the connection has an established channel binding.  A103	 * mechanism implementation must ensure that a SASL exchange has actually104	 * been completed, in addition to checking that channel binding is in use.105	 *106	 * Mechanisms that do not implement channel binding may simply return107	 * false.108	 *109	 * Input parameters:110	 *111	 *	state:    The opaque mechanism state returned by init()112	 *--------113	 */114	bool		(*channel_bound) (void *state);115 116	/*--------117	 * free()118	 *119	 * Frees the state allocated by init(). This is called when the connection120	 * is dropped, not when the exchange is completed.121	 *122	 * Input parameters:123	 *124	 *   state:    The opaque mechanism state returned by init()125	 *--------126	 */127	void		(*free) (void *state);128 129} pg_fe_sasl_mech;130 131#endif							/* FE_AUTH_SASL_H */132