1/*-------------------------------------------------------------------------
4 * Defines the SASL mechanism interface for libpq.
6 * Each SASL mechanism defines a frontend and a backend callback structure.
7 * This is not part of the public API for applications.
9 * See src/include/libpq/sasl.h for the backend counterpart.
11 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
12 * Portions Copyright (c) 1994, Regents of the University of California
14 * src/interfaces/libpq/fe-auth-sasl.h
16 *-------------------------------------------------------------------------
25 * Possible states for the SASL exchange, see the comment on exchange for an
26 * explanation of these.
37 * Frontend SASL mechanism callbacks.
39 * To implement a frontend mechanism, declare a pg_fe_sasl_mech struct with
40 * appropriate callback implementations, then hook it into conn->sasl during
41 * pg_SASL_init()'s mechanism negotiation.
48 * Initializes mechanism-specific state for a connection. This
49 * callback must return a pointer to its allocated state, which will
50 * be passed as-is as the first argument to the other callbacks.
51 * the free() callback is called to release any state resources.
53 * If state allocation fails, the implementation should return NULL to
54 * fail the authentication exchange.
58 * conn: The connection to the server
60 * password: The user's supplied password for the current connection
62 * mech: The mechanism name in use, for implementations that may
63 * advertise more than one name (such as *-PLUS variants).
71 * Produces a client response to a server challenge. As a special case
72 * for client-first SASL mechanisms, exchange() is called with a NULL
73 * server response once at the start of the authentication exchange to
74 * generate an initial response. Returns a SASLStatus indicating the
75 * state and status of the exchange.
79 * state: The opaque mechanism state returned by init()
81 * final: true if the server has sent a final exchange outcome
83 * input: The challenge data sent by the server, or NULL when
84 * generating a client-first initial response (that is, when
85 * the server expects the client to send a message to start
86 * the exchange). This is guaranteed to be null-terminated
87 * for safety, but SASL allows embedded nulls in challenges,
88 * so mechanisms must be careful to check inputlen.
90 * inputlen: The length of the challenge data sent by the server, or -1
91 * during client-first initial response generation.
93 * Output parameters, to be set by the callback function:
95 * output: A malloc'd buffer containing the client's response to
96 * the server (can be empty), or NULL if the exchange should
97 * be aborted. (The callback should return SASL_FAILED in the
100 * outputlen: The length (0 or higher) of the client response buffer,
101 * ignored if output is NULL.
105 * SASL_CONTINUE: The output buffer is filled with a client response.
106 * Additional server challenge is expected
107 * SASL_ASYNC: Some asynchronous processing external to the
108 * connection needs to be done before a response can be
109 * generated. The mechanism is responsible for setting up
110 * conn->async_auth/cleanup_async_auth appropriately
112 * SASL_COMPLETE: The SASL exchange has completed successfully.
113 * SASL_FAILED: The exchange has failed and the connection should be
118 char *
input,
int inputlen,
119 char **
output,
int *outputlen);
124 * Returns true if the connection has an established channel binding. A
125 * mechanism implementation must ensure that a SASL exchange has actually
126 * been completed, in addition to checking that channel binding is in use.
128 * Mechanisms that do not implement channel binding may simply return
133 * state: The opaque mechanism state returned by init()
141 * Frees the state allocated by init(). This is called when the connection
142 * is dropped, not when the exchange is completed.
146 * state: The opaque mechanism state returned by init()
153#endif /* FE_AUTH_SASL_H */
struct pg_fe_sasl_mech pg_fe_sasl_mech
void(* free)(void *state)
bool(* channel_bound)(void *state)
SASLStatus(* exchange)(void *state, bool final, char *input, int inputlen, char **output, int *outputlen)