PostgreSQL Source Code git master
fe-auth-sasl.h
Go to the documentation of this file.
1/*-------------------------------------------------------------------------
2 *
3 * fe-auth-sasl.h
4 * 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-2025, PostgreSQL Global Development Group
12 * Portions Copyright (c) 1994, Regents of the University of California
13 *
14 * src/interfaces/libpq/fe-auth-sasl.h
15 *
16 *-------------------------------------------------------------------------
17 */
18
19#ifndef FE_AUTH_SASL_H
20#define FE_AUTH_SASL_H
21
22#include "libpq-fe.h"
23
24/*
25 * Possible states for the SASL exchange, see the comment on exchange for an
26 * explanation of these.
27 */
28typedef enum
29{
35
36/*
37 * Frontend SASL mechanism callbacks.
38 *
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.
42 */
43typedef struct pg_fe_sasl_mech
44{
45 /*-------
46 * init()
47 *
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.
52 *
53 * If state allocation fails, the implementation should return NULL to
54 * fail the authentication exchange.
55 *
56 * Input parameters:
57 *
58 * conn: The connection to the server
59 *
60 * password: The user's supplied password for the current connection
61 *
62 * mech: The mechanism name in use, for implementations that may
63 * advertise more than one name (such as *-PLUS variants).
64 *-------
65 */
66 void *(*init) (PGconn *conn, const char *password, const char *mech);
67
68 /*--------
69 * exchange()
70 *
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.
76 *
77 * Input parameters:
78 *
79 * state: The opaque mechanism state returned by init()
80 *
81 * final: true if the server has sent a final exchange outcome
82 *
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.
89 *
90 * inputlen: The length of the challenge data sent by the server, or -1
91 * during client-first initial response generation.
92 *
93 * Output parameters, to be set by the callback function:
94 *
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
98 * latter case.)
99 *
100 * outputlen: The length (0 or higher) of the client response buffer,
101 * ignored if output is NULL.
102 *
103 * Return value:
104 *
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
111 * before returning.
112 * SASL_COMPLETE: The SASL exchange has completed successfully.
113 * SASL_FAILED: The exchange has failed and the connection should be
114 * dropped.
115 *--------
116 */
117 SASLStatus (*exchange) (void *state, bool final,
118 char *input, int inputlen,
119 char **output, int *outputlen);
120
121 /*--------
122 * channel_bound()
123 *
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.
127 *
128 * Mechanisms that do not implement channel binding may simply return
129 * false.
130 *
131 * Input parameters:
132 *
133 * state: The opaque mechanism state returned by init()
134 *--------
135 */
136 bool (*channel_bound) (void *state);
137
138 /*--------
139 * free()
140 *
141 * Frees the state allocated by init(). This is called when the connection
142 * is dropped, not when the exchange is completed.
143 *
144 * Input parameters:
145 *
146 * state: The opaque mechanism state returned by init()
147 *--------
148 */
149 void (*free) (void *state);
150
152
153#endif /* FE_AUTH_SASL_H */
SASLStatus
Definition: fe-auth-sasl.h:29
@ SASL_ASYNC
Definition: fe-auth-sasl.h:33
@ SASL_CONTINUE
Definition: fe-auth-sasl.h:32
@ SASL_COMPLETE
Definition: fe-auth-sasl.h:30
@ SASL_FAILED
Definition: fe-auth-sasl.h:31
struct pg_fe_sasl_mech pg_fe_sasl_mech
FILE * input
FILE * output
static char * password
Definition: streamutil.c:52
PGconn * conn
Definition: streamutil.c:53
void(* free)(void *state)
Definition: fe-auth-sasl.h:149
bool(* channel_bound)(void *state)
Definition: fe-auth-sasl.h:136
SASLStatus(* exchange)(void *state, bool final, char *input, int inputlen, char **output, int *outputlen)
Definition: fe-auth-sasl.h:117
Definition: regguts.h:323