codekingpro/portable-devtools

1/*-------------------------------------------------------------------------2 *3 * sasl.h4 *	  Defines the SASL mechanism interface for the backend.5 *6 * Each SASL mechanism defines a frontend and a backend callback structure.7 *8 * See src/interfaces/libpq/fe-auth-sasl.h for the frontend counterpart.9 *10 * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group11 * Portions Copyright (c) 1994, Regents of the University of California12 *13 * src/include/libpq/sasl.h14 *15 *-------------------------------------------------------------------------16 */17 18#ifndef PG_SASL_H19#define PG_SASL_H20 21#include "lib/stringinfo.h"22#include "libpq/libpq-be.h"23 24/* Status codes for message exchange */25#define PG_SASL_EXCHANGE_CONTINUE		026#define PG_SASL_EXCHANGE_SUCCESS		127#define PG_SASL_EXCHANGE_FAILURE		228 29/*30 * Backend SASL mechanism callbacks.31 *32 * To implement a backend mechanism, declare a pg_be_sasl_mech struct with33 * appropriate callback implementations.  Then pass the mechanism to34 * CheckSASLAuth() during ClientAuthentication(), once the server has decided35 * which authentication method to use.36 */37typedef struct pg_be_sasl_mech38{39	/*---------40	 * get_mechanisms()41	 *42	 * Retrieves the list of SASL mechanism names supported by this43	 * implementation.44	 *45	 * Input parameters:46	 *47	 *	port: The client Port48	 *49	 * Output parameters:50	 *51	 *	buf:  A StringInfo buffer that the callback should populate with52	 *		  supported mechanism names.  The names are appended into this53	 *		  StringInfo, each one ending with '\0' bytes.54	 *---------55	 */56	void		(*get_mechanisms) (Port *port, StringInfo buf);57 58	/*---------59	 * init()60	 *61	 * Initializes mechanism-specific state for a connection. This callback62	 * must return a pointer to its allocated state, which will be passed63	 * as-is as the first argument to the other callbacks.64	 *65	 * Input parameters:66	 *67	 *	port:        The client Port.68	 *69	 *	mech:        The actual mechanism name in use by the client.70	 *71	 *	shadow_pass: The stored secret for the role being authenticated, or72	 *				 NULL if one does not exist.  Mechanisms that do not use73	 *				 shadow entries may ignore this parameter.  If a74	 *				 mechanism uses shadow entries but shadow_pass is NULL,75	 *				 the implementation must continue the exchange as if the76	 *				 user existed and the password did not match, to avoid77	 *				 disclosing valid user names.78	 *---------79	 */80	void	   *(*init) (Port *port, const char *mech, const char *shadow_pass);81 82	/*---------83	 * exchange()84	 *85	 * Produces a server challenge to be sent to the client.  The callback86	 * must return one of the PG_SASL_EXCHANGE_* values, depending on87	 * whether the exchange continues, has finished successfully, or has88	 * failed.89	 *90	 * Input parameters:91	 *92	 *	state:	  The opaque mechanism state returned by init()93	 *94	 *	input:	  The response data sent by the client, or NULL if the95	 *			  mechanism is client-first but the client did not send an96	 *			  initial response.  (This can only happen during the first97	 *			  message from the client.)  This is guaranteed to be98	 *			  null-terminated for safety, but SASL allows embedded99	 *			  nulls in responses, so mechanisms must be careful to100	 *            check inputlen.101	 *102	 *	inputlen: The length of the challenge data sent by the server, or103	 *			  -1 if the client did not send an initial response104	 *105	 * Output parameters, to be set by the callback function:106	 *107	 *	output:    A palloc'd buffer containing either the server's next108	 *			   challenge (if PG_SASL_EXCHANGE_CONTINUE is returned) or109	 *			   the server's outcome data (if PG_SASL_EXCHANGE_SUCCESS is110	 *			   returned and the mechanism requires data to be sent during111	 *			   a successful outcome).  The callback should set this to112	 *			   NULL if the exchange is over and no output should be sent,113	 *			   which should correspond to either PG_SASL_EXCHANGE_FAILURE114	 *			   or a PG_SASL_EXCHANGE_SUCCESS with no outcome data.115	 *116	 *  outputlen: The length of the challenge data.  Ignored if *output is117	 *			   NULL.118	 *119	 *	logdetail: Set to an optional DETAIL message to be printed to the120	 *			   server log, to disambiguate failure modes.  (The client121	 *			   will only ever see the same generic authentication122	 *			   failure message.) Ignored if the exchange is completed123	 *			   with PG_SASL_EXCHANGE_SUCCESS.124	 *---------125	 */126	int			(*exchange) (void *state,127							 const char *input, int inputlen,128							 char **output, int *outputlen,129							 const char **logdetail);130} pg_be_sasl_mech;131 132/* Common implementation for auth.c */133extern int	CheckSASLAuth(const pg_be_sasl_mech *mech, Port *port,134						  char *shadow_pass, const char **logdetail);135 136#endif							/* PG_SASL_H */137