PostgreSQL Source Code  git master
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
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-2024, 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  */
28 typedef enum
29 {
33 } SASLStatus;
34 
35 /*
36  * Frontend SASL mechanism callbacks.
37  *
38  * To implement a frontend mechanism, declare a pg_fe_sasl_mech struct with
39  * appropriate callback implementations, then hook it into conn->sasl during
40  * pg_SASL_init()'s mechanism negotiation.
41  */
42 typedef struct pg_fe_sasl_mech
43 {
44  /*-------
45  * init()
46  *
47  * Initializes mechanism-specific state for a connection. This
48  * callback must return a pointer to its allocated state, which will
49  * be passed as-is as the first argument to the other callbacks.
50  * the free() callback is called to release any state resources.
51  *
52  * If state allocation fails, the implementation should return NULL to
53  * fail the authentication exchange.
54  *
55  * Input parameters:
56  *
57  * conn: The connection to the server
58  *
59  * password: The user's supplied password for the current connection
60  *
61  * mech: The mechanism name in use, for implementations that may
62  * advertise more than one name (such as *-PLUS variants).
63  *-------
64  */
65  void *(*init) (PGconn *conn, const char *password, const char *mech);
66 
67  /*--------
68  * exchange()
69  *
70  * Produces a client response to a server challenge. As a special case
71  * for client-first SASL mechanisms, exchange() is called with a NULL
72  * server response once at the start of the authentication exchange to
73  * generate an initial response. Returns a SASLStatus indicating the
74  * state and status of the exchange.
75  *
76  * Input parameters:
77  *
78  * state: The opaque mechanism state returned by init()
79  *
80  * input: The challenge data sent by the server, or NULL when
81  * generating a client-first initial response (that is, when
82  * the server expects the client to send a message to start
83  * the exchange). This is guaranteed to be null-terminated
84  * for safety, but SASL allows embedded nulls in challenges,
85  * so mechanisms must be careful to check inputlen.
86  *
87  * inputlen: The length of the challenge data sent by the server, or -1
88  * during client-first initial response generation.
89  *
90  * Output parameters, to be set by the callback function:
91  *
92  * output: A malloc'd buffer containing the client's response to
93  * the server (can be empty), or NULL if the exchange should
94  * be aborted. (The callback should return SASL_FAILED in the
95  * latter case.)
96  *
97  * outputlen: The length (0 or higher) of the client response buffer,
98  * ignored if output is NULL.
99  *
100  * Return value:
101  *
102  * SASL_CONTINUE: The output buffer is filled with a client response.
103  * Additional server challenge is expected
104  * SASL_COMPLETE: The SASL exchange has completed successfully.
105  * SASL_FAILED: The exchange has failed and the connection should be
106  * dropped.
107  *--------
108  */
109  SASLStatus (*exchange) (void *state, char *input, int inputlen,
110  char **output, int *outputlen);
111 
112  /*--------
113  * channel_bound()
114  *
115  * Returns true if the connection has an established channel binding. A
116  * mechanism implementation must ensure that a SASL exchange has actually
117  * been completed, in addition to checking that channel binding is in use.
118  *
119  * Mechanisms that do not implement channel binding may simply return
120  * false.
121  *
122  * Input parameters:
123  *
124  * state: The opaque mechanism state returned by init()
125  *--------
126  */
128 
129  /*--------
130  * free()
131  *
132  * Frees the state allocated by init(). This is called when the connection
133  * is dropped, not when the exchange is completed.
134  *
135  * Input parameters:
136  *
137  * state: The opaque mechanism state returned by init()
138  *--------
139  */
140  void (*free) (void *state);
141 
143 
144 #endif /* FE_AUTH_SASL_H */
unsigned char bool
Definition: c.h:471
SASLStatus
Definition: fe-auth-sasl.h:29
@ 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:140
bool(* channel_bound)(void *state)
Definition: fe-auth-sasl.h:127
SASLStatus(* exchange)(void *state, char *input, int inputlen, char **output, int *outputlen)
Definition: fe-auth-sasl.h:109
Definition: regguts.h:323