1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
/*-------------------------------------------------------------------------
*
* 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 */
|
