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-2025, 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 */
45typedef 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 */
144extern 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:135
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