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
132
133
134
135
136
|
/*-------------------------------------------------------------------------
*
* sasl.h
* Defines the SASL mechanism interface for the backend.
*
* Each SASL mechanism defines a frontend and a backend callback structure.
*
* See src/interfaces/libpq/fe-auth-sasl.h for the frontend counterpart.
*
* Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/include/libpq/sasl.h
*
*-------------------------------------------------------------------------
*/
#ifndef PG_SASL_H
#define PG_SASL_H
#include "lib/stringinfo.h"
#include "libpq/libpq-be.h"
/* Status codes for message exchange */
#define PG_SASL_EXCHANGE_CONTINUE 0
#define PG_SASL_EXCHANGE_SUCCESS 1
#define PG_SASL_EXCHANGE_FAILURE 2
/*
* Backend SASL mechanism callbacks.
*
* To implement a backend mechanism, declare a pg_be_sasl_mech struct with
* appropriate callback implementations. Then pass the mechanism to
* CheckSASLAuth() during ClientAuthentication(), once the server has decided
* which authentication method to use.
*/
typedef struct pg_be_sasl_mech
{
/*---------
* get_mechanisms()
*
* Retrieves the list of SASL mechanism names supported by this
* implementation.
*
* Input parameters:
*
* port: The client Port
*
* Output parameters:
*
* buf: A StringInfo buffer that the callback should populate with
* supported mechanism names. The names are appended into this
* StringInfo, each one ending with '\0' bytes.
*---------
*/
void (*get_mechanisms) (Port *port, StringInfo buf);
/*---------
* 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.
*
* Input parameters:
*
* port: The client Port.
*
* mech: The actual mechanism name in use by the client.
*
* shadow_pass: The stored secret for the role being authenticated, or
* NULL if one does not exist. Mechanisms that do not use
* shadow entries may ignore this parameter. If a
* mechanism uses shadow entries but shadow_pass is NULL,
* the implementation must continue the exchange as if the
* user existed and the password did not match, to avoid
* disclosing valid user names.
*---------
*/
void *(*init) (Port *port, const char *mech, const char *shadow_pass);
/*---------
* exchange()
*
* Produces a server challenge to be sent to the client. The callback
* must return one of the PG_SASL_EXCHANGE_* values, depending on
* whether the exchange continues, has finished successfully, or has
* failed.
*
* Input parameters:
*
* state: The opaque mechanism state returned by init()
*
* input: The response data sent by the client, or NULL if the
* mechanism is client-first but the client did not send an
* initial response. (This can only happen during the first
* message from the client.) This is guaranteed to be
* null-terminated for safety, but SASL allows embedded
* nulls in responses, so mechanisms must be careful to
* check inputlen.
*
* inputlen: The length of the challenge data sent by the server, or
* -1 if the client did not send an initial response
*
* Output parameters, to be set by the callback function:
*
* output: A palloc'd buffer containing either the server's next
* challenge (if PG_SASL_EXCHANGE_CONTINUE is returned) or
* the server's outcome data (if PG_SASL_EXCHANGE_SUCCESS is
* returned and the mechanism requires data to be sent during
* a successful outcome). The callback should set this to
* NULL if the exchange is over and no output should be sent,
* which should correspond to either PG_SASL_EXCHANGE_FAILURE
* or a PG_SASL_EXCHANGE_SUCCESS with no outcome data.
*
* outputlen: The length of the challenge data. Ignored if *output is
* NULL.
*
* logdetail: Set to an optional DETAIL message to be printed to the
* server log, to disambiguate failure modes. (The client
* will only ever see the same generic authentication
* failure message.) Ignored if the exchange is completed
* with PG_SASL_EXCHANGE_SUCCESS.
*---------
*/
int (*exchange) (void *state,
const char *input, int inputlen,
char **output, int *outputlen,
const char **logdetail);
} pg_be_sasl_mech;
/* Common implementation for auth.c */
extern int CheckSASLAuth(const pg_be_sasl_mech *mech, Port *port,
char *shadow_pass, const char **logdetail);
#endif /* PG_SASL_H */
|
