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-2023, 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  * Frontend SASL mechanism callbacks.
26  *
27  * To implement a frontend mechanism, declare a pg_be_sasl_mech struct with
28  * appropriate callback implementations, then hook it into conn->sasl during
29  * pg_SASL_init()'s mechanism negotiation.
30  */
31 typedef struct pg_fe_sasl_mech
32 {
33  /*-------
34  * init()
35  *
36  * Initializes mechanism-specific state for a connection. This
37  * callback must return a pointer to its allocated state, which will
38  * 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 to
42  * fail the authentication exchange.
43  *
44  * Input parameters:
45  *
46  * conn: The connection to the server
47  *
48  * password: The user's supplied password for the current connection
49  *
50  * mech: The mechanism name in use, for implementations that may
51  * 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 case
60  * for client-first SASL mechanisms, exchange() is called with a NULL
61  * server response once at the start of the authentication exchange to
62  * 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 when
69  * generating a client-first initial response (that is, when
70  * the server expects the client to send a message to start
71  * the exchange). This is guaranteed to be null-terminated
72  * 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 -1
76  * 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 to
81  * the server (can be empty), or NULL if the exchange should
82  * be aborted. (*success should be set to false in the
83  * 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 failed
90  *
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. A
103  * mechanism implementation must ensure that a SASL exchange has actually
104  * been completed, in addition to checking that channel binding is in use.
105  *
106  * Mechanisms that do not implement channel binding may simply return
107  * false.
108  *
109  * Input parameters:
110  *
111  * state: The opaque mechanism state returned by init()
112  *--------
113  */
115 
116  /*--------
117  * free()
118  *
119  * Frees the state allocated by init(). This is called when the connection
120  * 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 
130 
131 #endif /* FE_AUTH_SASL_H */
unsigned char bool
Definition: c.h:440
struct pg_fe_sasl_mech pg_fe_sasl_mech
FILE * input
FILE * output
static bool success
Definition: initdb.c:187
static char * password
Definition: streamutil.c:53
PGconn * conn
Definition: streamutil.c:54
void(* free)(void *state)
Definition: fe-auth-sasl.h:127
bool(* channel_bound)(void *state)
Definition: fe-auth-sasl.h:114
void(* exchange)(void *state, char *input, int inputlen, char **output, int *outputlen, bool *done, bool *success)
Definition: fe-auth-sasl.h:95
Definition: regguts.h:323