PostgreSQL Source Code  git master
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-2021, 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  * Backend SASL mechanism callbacks.
31  *
32  * To implement a backend mechanism, declare a pg_be_sasl_mech struct with
33  * appropriate callback implementations. Then pass the mechanism to
34  * CheckSASLAuth() during ClientAuthentication(), once the server has decided
35  * which authentication method to use.
36  */
37 typedef struct pg_be_sasl_mech
38 {
39  /*---------
40  * get_mechanisms()
41  *
42  * Retrieves the list of SASL mechanism names supported by this
43  * implementation.
44  *
45  * Input parameters:
46  *
47  * port: The client Port
48  *
49  * Output parameters:
50  *
51  * buf: A StringInfo buffer that the callback should populate with
52  * supported mechanism names. The names are appended into this
53  * StringInfo, each one ending with '\0' bytes.
54  *---------
55  */
57 
58  /*---------
59  * init()
60  *
61  * Initializes mechanism-specific state for a connection. This callback
62  * must return a pointer to its allocated state, which will be passed
63  * as-is as the first argument to the other callbacks.
64  *
65  * Input paramters:
66  *
67  * port: The client Port.
68  *
69  * mech: The actual mechanism name in use by the client.
70  *
71  * shadow_pass: The stored secret for the role being authenticated, or
72  * NULL if one does not exist. Mechanisms that do not use
73  * shadow entries may ignore this parameter. If a
74  * mechanism uses shadow entries but shadow_pass is NULL,
75  * the implementation must continue the exchange as if the
76  * user existed and the password did not match, to avoid
77  * disclosing valid user names.
78  *---------
79  */
80  void *(*init) (Port *port, const char *mech, const char *shadow_pass);
81 
82  /*---------
83  * exchange()
84  *
85  * Produces a server challenge to be sent to the client. The callback
86  * must return one of the PG_SASL_EXCHANGE_* values, depending on
87  * whether the exchange continues, has finished successfully, or has
88  * failed.
89  *
90  * Input parameters:
91  *
92  * state: The opaque mechanism state returned by init()
93  *
94  * input: The response data sent by the client, or NULL if the
95  * mechanism is client-first but the client did not send an
96  * initial response. (This can only happen during the first
97  * message from the client.) This is guaranteed to be
98  * null-terminated for safety, but SASL allows embedded
99  * nulls in responses, so mechanisms must be careful to
100  * check inputlen.
101  *
102  * inputlen: The length of the challenge data sent by the server, or
103  * -1 if the client did not send an initial response
104  *
105  * Output parameters, to be set by the callback function:
106  *
107  * output: A palloc'd buffer containing either the server's next
108  * challenge (if PG_SASL_EXCHANGE_CONTINUE is returned) or
109  * the server's outcome data (if PG_SASL_EXCHANGE_SUCCESS is
110  * returned and the mechanism requires data to be sent during
111  * a successful outcome). The callback should set this to
112  * NULL if the exchange is over and no output should be sent,
113  * which should correspond to either PG_SASL_EXCHANGE_FAILURE
114  * or a PG_SASL_EXCHANGE_SUCCESS with no outcome data.
115  *
116  * outputlen: The length of the challenge data. Ignored if *output is
117  * NULL.
118  *
119  * logdetail: Set to an optional DETAIL message to be printed to the
120  * server log, to disambiguate failure modes. (The client
121  * will only ever see the same generic authentication
122  * failure message.) Ignored if the exchange is completed
123  * with PG_SASL_EXCHANGE_SUCCESS.
124  *---------
125  */
126  int (*exchange) (void *state,
127  const char *input, int inputlen,
128  char **output, int *outputlen,
129  char **logdetail);
131 
132 /* Common implementation for auth.c */
133 extern int CheckSASLAuth(const pg_be_sasl_mech *mech, Port *port,
134  char *shadow_pass, char **logdetail);
135 
136 #endif /* PG_SASL_H */
static void output(uint64 loop_count)
Definition: libpq-be.h:125
int(* exchange)(void *state, const char *input, int inputlen, char **output, int *outputlen, char **logdetail)
Definition: sasl.h:126
static char * buf
Definition: pg_test_fsync.c:68
struct pg_be_sasl_mech pg_be_sasl_mech
static int port
Definition: pg_regress.c:92
int CheckSASLAuth(const pg_be_sasl_mech *mech, Port *port, char *shadow_pass, char **logdetail)
Definition: auth-sasl.c:52
Definition: regguts.h:317
void(* get_mechanisms)(Port *port, StringInfo buf)
Definition: sasl.h:56