132 lines
4.2 KiB
C
132 lines
4.2 KiB
C
/*-------------------------------------------------------------------------
|
|
*
|
|
* 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-2023, 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 (can be empty), or NULL if the exchange should
|
|
* be aborted. (*success should be set to false in the
|
|
* latter case.)
|
|
*
|
|
* outputlen: The length (0 or higher) of the client response buffer,
|
|
* ignored if output is NULL.
|
|
*
|
|
* 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 */
|