PostgreSQL Source Code  git master
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
sasl.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * sasl.h
4  * Defines the SASL mechanism interface for the backend.
5  *
6  * Each SASL mechanism defines a frontend and a backend callback structure.
7  *
8  * See src/interfaces/libpq/fe-auth-sasl.h for the frontend counterpart.
9  *
10  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
11  * Portions Copyright (c) 1994, Regents of the University of California
12  *
13  * src/include/libpq/sasl.h
14  *
15  *-------------------------------------------------------------------------
16  */
17 
18 #ifndef PG_SASL_H
19 #define PG_SASL_H
20 
21 #include "lib/stringinfo.h"
22 #include "libpq/libpq-be.h"
23 
24 /* Status codes for message exchange */
25 #define PG_SASL_EXCHANGE_CONTINUE 0
26 #define PG_SASL_EXCHANGE_SUCCESS 1
27 #define PG_SASL_EXCHANGE_FAILURE 2
28 
29 /*
30  * Maximum accepted size of SASL messages.
31  *
32  * The messages that the server or libpq generate are much smaller than this,
33  * but have some headroom.
34  */
35 #define PG_MAX_SASL_MESSAGE_LENGTH 1024
36 
37 /*
38  * Backend SASL mechanism callbacks and metadata.
39  *
40  * To implement a backend mechanism, declare a pg_be_sasl_mech struct with
41  * appropriate callback implementations. Then pass the mechanism to
42  * CheckSASLAuth() during ClientAuthentication(), once the server has decided
43  * which authentication method to use.
44  */
45 typedef struct pg_be_sasl_mech
46 {
47  /*---------
48  * get_mechanisms()
49  *
50  * Retrieves the list of SASL mechanism names supported by this
51  * implementation.
52  *
53  * Input parameters:
54  *
55  * port: The client Port
56  *
57  * Output parameters:
58  *
59  * buf: A StringInfo buffer that the callback should populate with
60  * supported mechanism names. The names are appended into this
61  * StringInfo, each one ending with '\0' bytes.
62  *---------
63  */
65 
66  /*---------
67  * init()
68  *
69  * Initializes mechanism-specific state for a connection. This callback
70  * must return a pointer to its allocated state, which will be passed
71  * as-is as the first argument to the other callbacks.
72  *
73  * Input parameters:
74  *
75  * port: The client Port.
76  *
77  * mech: The actual mechanism name in use by the client.
78  *
79  * shadow_pass: The stored secret for the role being authenticated, or
80  * NULL if one does not exist. Mechanisms that do not use
81  * shadow entries may ignore this parameter. If a
82  * mechanism uses shadow entries but shadow_pass is NULL,
83  * the implementation must continue the exchange as if the
84  * user existed and the password did not match, to avoid
85  * disclosing valid user names.
86  *---------
87  */
88  void *(*init) (Port *port, const char *mech, const char *shadow_pass);
89 
90  /*---------
91  * exchange()
92  *
93  * Produces a server challenge to be sent to the client. The callback
94  * must return one of the PG_SASL_EXCHANGE_* values, depending on
95  * whether the exchange continues, has finished successfully, or has
96  * failed.
97  *
98  * Input parameters:
99  *
100  * state: The opaque mechanism state returned by init()
101  *
102  * input: The response data sent by the client, or NULL if the
103  * mechanism is client-first but the client did not send an
104  * initial response. (This can only happen during the first
105  * message from the client.) This is guaranteed to be
106  * null-terminated for safety, but SASL allows embedded
107  * nulls in responses, so mechanisms must be careful to
108  * check inputlen.
109  *
110  * inputlen: The length of the challenge data sent by the server, or
111  * -1 if the client did not send an initial response
112  *
113  * Output parameters, to be set by the callback function:
114  *
115  * output: A palloc'd buffer containing either the server's next
116  * challenge (if PG_SASL_EXCHANGE_CONTINUE is returned) or
117  * the server's outcome data (if PG_SASL_EXCHANGE_SUCCESS is
118  * returned and the mechanism requires data to be sent during
119  * a successful outcome). The callback should set this to
120  * NULL if the exchange is over and no output should be sent,
121  * which should correspond to either PG_SASL_EXCHANGE_FAILURE
122  * or a PG_SASL_EXCHANGE_SUCCESS with no outcome data.
123  *
124  * outputlen: The length of the challenge data. Ignored if *output is
125  * NULL.
126  *
127  * logdetail: Set to an optional DETAIL message to be printed to the
128  * server log, to disambiguate failure modes. (The client
129  * will only ever see the same generic authentication
130  * failure message.) Ignored if the exchange is completed
131  * with PG_SASL_EXCHANGE_SUCCESS.
132  *---------
133  */
134  int (*exchange) (void *state,
135  const char *input, int inputlen,
136  char **output, int *outputlen,
137  const char **logdetail);
138 
139  /* The maximum size allowed for client SASLResponses. */
142 
143 /* Common implementation for auth.c */
144 extern int CheckSASLAuth(const pg_be_sasl_mech *mech, Port *port,
145  char *shadow_pass, const char **logdetail);
146 
147 #endif /* PG_SASL_H */
FILE * input
FILE * output
static int port
Definition: pg_regress.c:115
static char * buf
Definition: pg_test_fsync.c:72
struct pg_be_sasl_mech pg_be_sasl_mech
int CheckSASLAuth(const pg_be_sasl_mech *mech, Port *port, char *shadow_pass, const char **logdetail)
Definition: auth-sasl.c:44
Definition: libpq-be.h:133
int(* exchange)(void *state, const char *input, int inputlen, char **output, int *outputlen, const char **logdetail)
Definition: sasl.h:134
void(* get_mechanisms)(Port *port, StringInfo buf)
Definition: sasl.h:64
int max_message_length
Definition: sasl.h:140
Definition: regguts.h:323