PostgreSQL Source Code git master
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
libpq-be.h
Go to the documentation of this file.
1/*-------------------------------------------------------------------------
2 *
3 * libpq-be.h
4 * This file contains definitions for structures and externs used
5 * by the postmaster during client authentication.
6 *
7 * Note that this is backend-internal and is NOT exported to clients.
8 * Structs that need to be client-visible are in pqcomm.h.
9 *
10 *
11 * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
12 * Portions Copyright (c) 1994, Regents of the University of California
13 *
14 * src/include/libpq/libpq-be.h
15 *
16 *-------------------------------------------------------------------------
17 */
18#ifndef LIBPQ_BE_H
19#define LIBPQ_BE_H
20
21#include <sys/time.h>
22#ifdef USE_OPENSSL
23#include <openssl/ssl.h>
24#include <openssl/err.h>
25#endif
26#include <netinet/tcp.h>
27
28#ifdef ENABLE_GSS
29#if defined(HAVE_GSSAPI_H)
30#include <gssapi.h>
31#else
32#include <gssapi/gssapi.h>
33#endif /* HAVE_GSSAPI_H */
34#endif /* ENABLE_GSS */
35
36#ifdef ENABLE_SSPI
37#define SECURITY_WIN32
38#if defined(WIN32) && !defined(_MSC_VER)
39#include <ntsecapi.h>
40#endif
41#include <security.h>
42#undef SECURITY_WIN32
43
44#ifndef ENABLE_GSS
45/*
46 * Define a fake structure compatible with GSSAPI on Unix.
47 */
48typedef struct
49{
50 void *value;
51 int length;
52} gss_buffer_desc;
53#endif
54#endif /* ENABLE_SSPI */
55
56#include "datatype/timestamp.h"
57#include "libpq/hba.h"
58#include "libpq/pqcomm.h"
59
60
61/*
62 * GSSAPI specific state information
63 */
64#if defined(ENABLE_GSS) | defined(ENABLE_SSPI)
65typedef struct
66{
67 gss_buffer_desc outbuf; /* GSSAPI output token buffer */
68#ifdef ENABLE_GSS
69 gss_cred_id_t cred; /* GSSAPI connection cred's */
70 gss_ctx_id_t ctx; /* GSSAPI connection context */
71 gss_name_t name; /* GSSAPI client name */
72 char *princ; /* GSSAPI Principal used for auth, NULL if
73 * GSSAPI auth was not used */
74 bool auth; /* GSSAPI Authentication used */
75 bool enc; /* GSSAPI encryption in use */
76 bool delegated_creds; /* GSSAPI Delegated credentials */
77#endif
78} pg_gssinfo;
79#endif
80
81/*
82 * ClientConnectionInfo includes the fields describing the client connection
83 * that are copied over to parallel workers as nothing from Port does that.
84 * The same rules apply for allocations here as for Port (everything must be
85 * malloc'd or palloc'd in TopMemoryContext).
86 *
87 * If you add a struct member here, remember to also handle serialization in
88 * SerializeClientConnectionInfo() and co.
89 */
91{
92 /*
93 * Authenticated identity. The meaning of this identifier is dependent on
94 * auth_method; it is the identity (if any) that the user presented during
95 * the authentication cycle, before they were assigned a database role.
96 * (It is effectively the "SYSTEM-USERNAME" of a pg_ident usermap --
97 * though the exact string in use may be different, depending on pg_hba
98 * options.)
99 *
100 * authn_id is NULL if the user has not actually been authenticated, for
101 * example if the "trust" auth method is in use.
102 */
103 const char *authn_id;
104
105 /*
106 * The HBA method that determined the above authn_id. This only has
107 * meaning if authn_id is not NULL; otherwise it's undefined.
108 */
111
112/*
113 * The Port structure holds state information about a client connection in a
114 * backend process. It is available in the global variable MyProcPort. The
115 * struct and all the data it points are kept in TopMemoryContext.
116 *
117 * remote_hostname is set if we did a successful reverse lookup of the
118 * client's IP address during connection setup.
119 * remote_hostname_resolv tracks the state of hostname verification:
120 * +1 = remote_hostname is known to resolve to client's IP address
121 * -1 = remote_hostname is known NOT to resolve to client's IP address
122 * 0 = we have not done the forward DNS lookup yet
123 * -2 = there was an error in name resolution
124 * If reverse lookup of the client IP address fails, remote_hostname will be
125 * left NULL while remote_hostname_resolv is set to -2. If reverse lookup
126 * succeeds but forward lookup fails, remote_hostname_resolv is also set to -2
127 * (the case is distinguishable because remote_hostname isn't NULL). In
128 * either of the -2 cases, remote_hostname_errcode saves the lookup return
129 * code for possible later use with gai_strerror.
130 */
131
132typedef struct Port
133{
134 pgsocket sock; /* File descriptor */
135 bool noblock; /* is the socket in non-blocking mode? */
136 ProtocolVersion proto; /* FE/BE protocol version */
137 SockAddr laddr; /* local addr (postmaster) */
138 SockAddr raddr; /* remote addr (client) */
139 char *remote_host; /* name (or ip addr) of remote host */
140 char *remote_hostname; /* name (not ip addr) of remote host, if
141 * available */
142 int remote_hostname_resolv; /* see above */
143 int remote_hostname_errcode; /* see above */
144 char *remote_port; /* text rep of remote port */
145
146 /*
147 * Information that needs to be saved from the startup packet and passed
148 * into backend execution. "char *" fields are NULL if not set.
149 * guc_options points to a List of alternating option names and values.
150 */
155
156 /*
157 * The startup packet application name, only used here for the "connection
158 * authorized" log message. We shouldn't use this post-startup, instead
159 * the GUC should be used as application can change it afterward.
160 */
162
163 /*
164 * Information that needs to be held during the authentication cycle.
165 */
167
168 /*
169 * TCP keepalive and user timeout settings.
170 *
171 * default values are 0 if AF_UNIX or not yet known; current values are 0
172 * if AF_UNIX or using the default. Also, -1 in a default value means we
173 * were unable to find out the default (getsockopt failed).
174 */
183
184 /*
185 * GSSAPI structures.
186 */
187#if defined(ENABLE_GSS) || defined(ENABLE_SSPI)
188
189 /*
190 * If GSSAPI is supported and used on this connection, store GSSAPI
191 * information. Even when GSSAPI is not compiled in, store a NULL pointer
192 * to keep struct offsets the same (for extension ABI compatibility).
193 */
194 pg_gssinfo *gss;
195#else
196 void *gss;
197#endif
198
199 /*
200 * SSL structures.
201 */
203 char *peer_cn;
204 char *peer_dn;
208
209 /*
210 * OpenSSL structures. As with GSSAPI above, to keep struct offsets
211 * constant, NULL pointers are stored when SSL support is not enabled.
212 * (Although extensions should have no business accessing the raw_buf
213 * fields anyway.)
214 */
215#ifdef USE_OPENSSL
216 SSL *ssl;
217 X509 *peer;
218#else
219 void *ssl;
220 void *peer;
221#endif
222
223 /*
224 * This is a bit of a hack. raw_buf is data that was previously read and
225 * buffered in a higher layer but then "unread" and needs to be read again
226 * while establishing an SSL connection via the SSL library layer.
227 *
228 * There's no API to "unread", the upper layer just places the data in the
229 * Port structure in raw_buf and sets raw_buf_remaining to the amount of
230 * bytes unread and raw_buf_consumed to 0.
231 */
232 char *raw_buf;
236
237/*
238 * ClientSocket holds a socket for an accepted connection, along with the
239 * information about the remote endpoint. This is passed from postmaster to
240 * the backend process.
241 */
242typedef struct ClientSocket
243{
244 pgsocket sock; /* File descriptor */
245 SockAddr raddr; /* remote addr (client) */
247
248#ifdef USE_SSL
249/*
250 * Hardcoded DH parameters, used in ephemeral DH keying. (See also
251 * README.SSL for more details on EDH.)
252 *
253 * This is the 2048-bit DH parameter from RFC 3526. The generation of the
254 * prime is specified in RFC 2412 Appendix E, which also discusses the
255 * design choice of the generator. Note that when loaded with OpenSSL
256 * this causes DH_check() to fail on DH_NOT_SUITABLE_GENERATOR, where
257 * leaking a bit is preferred.
258 */
259#define FILE_DH2048 \
260"-----BEGIN DH PARAMETERS-----\n\
261MIIBCAKCAQEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n\
262IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n\
263awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n\
264mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n\
265fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n\
2665RXSJhiY+gUQFXKOWoqsqmj//////////wIBAg==\n\
267-----END DH PARAMETERS-----\n"
268
269/*
270 * These functions are implemented by the glue code specific to each
271 * SSL implementation (e.g. be-secure-openssl.c)
272 */
273
274/*
275 * Initialize global SSL context.
276 *
277 * If isServerStart is true, report any errors as FATAL (so we don't return).
278 * Otherwise, log errors at LOG level and return -1 to indicate trouble,
279 * preserving the old SSL state if any. Returns 0 if OK.
280 */
281extern int be_tls_init(bool isServerStart);
282
283/*
284 * Destroy global SSL context, if any.
285 */
286extern void be_tls_destroy(void);
287
288/*
289 * Attempt to negotiate SSL connection.
290 */
291extern int be_tls_open_server(Port *port);
292
293/*
294 * Close SSL connection.
295 */
296extern void be_tls_close(Port *port);
297
298/*
299 * Read data from a secure connection.
300 */
301extern ssize_t be_tls_read(Port *port, void *ptr, size_t len, int *waitfor);
302
303/*
304 * Write data to a secure connection.
305 */
306extern ssize_t be_tls_write(Port *port, void *ptr, size_t len, int *waitfor);
307
308/*
309 * Return information about the SSL connection.
310 */
311extern int be_tls_get_cipher_bits(Port *port);
312extern const char *be_tls_get_version(Port *port);
313extern const char *be_tls_get_cipher(Port *port);
314extern void be_tls_get_peer_subject_name(Port *port, char *ptr, size_t len);
315extern void be_tls_get_peer_issuer_name(Port *port, char *ptr, size_t len);
316extern void be_tls_get_peer_serial(Port *port, char *ptr, size_t len);
317
318/*
319 * Get the server certificate hash for SCRAM channel binding type
320 * tls-server-end-point.
321 *
322 * The result is a palloc'd hash of the server certificate with its
323 * size, and NULL if there is no certificate available.
324 */
325extern char *be_tls_get_certificate_hash(Port *port, size_t *len);
326
327/* init hook for SSL, the default sets the password callback if appropriate */
328#ifdef USE_OPENSSL
329typedef void (*openssl_tls_init_hook_typ) (SSL_CTX *context, bool isServerStart);
330extern PGDLLIMPORT openssl_tls_init_hook_typ openssl_tls_init_hook;
331#endif
332
333#endif /* USE_SSL */
334
335#ifdef ENABLE_GSS
336/*
337 * Return information about the GSSAPI authenticated connection
338 */
339extern bool be_gssapi_get_auth(Port *port);
340extern bool be_gssapi_get_enc(Port *port);
341extern const char *be_gssapi_get_princ(Port *port);
343
344/* Read and write to a GSSAPI-encrypted connection. */
345extern ssize_t be_gssapi_read(Port *port, void *ptr, size_t len);
346extern ssize_t be_gssapi_write(Port *port, void *ptr, size_t len);
347#endif /* ENABLE_GSS */
348
351
352/* TCP keepalives configuration. These are no-ops on an AF_UNIX socket. */
353
354extern int pq_getkeepalivesidle(Port *port);
356extern int pq_getkeepalivescount(Port *port);
357extern int pq_gettcpusertimeout(Port *port);
358
359extern int pq_setkeepalivesidle(int idle, Port *port);
361extern int pq_setkeepalivescount(int count, Port *port);
362extern int pq_settcpusertimeout(int timeout, Port *port);
363
364#endif /* LIBPQ_BE_H */
bool be_gssapi_get_auth(Port *port)
ssize_t be_gssapi_read(Port *port, void *ptr, size_t len)
ssize_t be_gssapi_write(Port *port, void *ptr, size_t len)
bool be_gssapi_get_enc(Port *port)
const char * be_gssapi_get_princ(Port *port)
bool be_gssapi_get_delegation(Port *port)
const char * be_tls_get_version(Port *port)
void be_tls_destroy(void)
int be_tls_init(bool isServerStart)
openssl_tls_init_hook_typ openssl_tls_init_hook
int be_tls_get_cipher_bits(Port *port)
int be_tls_open_server(Port *port)
char * be_tls_get_certificate_hash(Port *port, size_t *len)
const char * be_tls_get_cipher(Port *port)
void be_tls_get_peer_serial(Port *port, char *ptr, size_t len)
void be_tls_close(Port *port)
void be_tls_get_peer_issuer_name(Port *port, char *ptr, size_t len)
ssize_t be_tls_read(Port *port, void *ptr, size_t len, int *waitfor)
ssize_t be_tls_write(Port *port, void *ptr, size_t len, int *waitfor)
void be_tls_get_peer_subject_name(Port *port, char *ptr, size_t len)
#define PGDLLIMPORT
Definition: c.h:1274
enc
UserAuth
Definition: hba.h:26
static struct @161 value
int pq_setkeepalivesinterval(int interval, Port *port)
Definition: pqcomm.c:1750
PGDLLIMPORT ProtocolVersion FrontendProtocol
Definition: globals.c:29
int pq_getkeepalivescount(Port *port)
Definition: pqcomm.c:1799
int pq_getkeepalivesinterval(Port *port)
Definition: pqcomm.c:1715
int pq_settcpusertimeout(int timeout, Port *port)
Definition: pqcomm.c:1904
int pq_setkeepalivesidle(int idle, Port *port)
Definition: pqcomm.c:1665
int pq_getkeepalivesidle(Port *port)
Definition: pqcomm.c:1630
struct Port Port
struct ClientSocket ClientSocket
PGDLLIMPORT ClientConnectionInfo MyClientConnectionInfo
Definition: miscinit.c:1066
struct ClientConnectionInfo ClientConnectionInfo
int pq_gettcpusertimeout(Port *port)
Definition: pqcomm.c:1874
int pq_setkeepalivescount(int count, Port *port)
Definition: pqcomm.c:1829
const void size_t len
static int port
Definition: pg_regress.c:115
int pgsocket
Definition: port.h:29
uint32 ProtocolVersion
Definition: pqcomm.h:100
tree context
Definition: radixtree.h:1837
const char * authn_id
Definition: libpq-be.h:103
UserAuth auth_method
Definition: libpq-be.h:109
SockAddr raddr
Definition: libpq-be.h:245
pgsocket sock
Definition: libpq-be.h:244
Definition: hba.h:95
Definition: pg_list.h:54
Definition: libpq-be.h:133
bool ssl_in_use
Definition: libpq-be.h:202
char * user_name
Definition: libpq-be.h:152
ProtocolVersion proto
Definition: libpq-be.h:136
bool last_read_was_eof
Definition: libpq-be.h:207
char * raw_buf
Definition: libpq-be.h:232
char * remote_port
Definition: libpq-be.h:144
SockAddr laddr
Definition: libpq-be.h:137
char * remote_hostname
Definition: libpq-be.h:140
int remote_hostname_errcode
Definition: libpq-be.h:143
int default_keepalives_idle
Definition: libpq-be.h:175
int keepalives_idle
Definition: libpq-be.h:179
int keepalives_count
Definition: libpq-be.h:181
void * gss
Definition: libpq-be.h:196
int default_keepalives_interval
Definition: libpq-be.h:176
bool peer_cert_valid
Definition: libpq-be.h:205
char * database_name
Definition: libpq-be.h:151
void * peer
Definition: libpq-be.h:220
char * remote_host
Definition: libpq-be.h:139
bool alpn_used
Definition: libpq-be.h:206
pgsocket sock
Definition: libpq-be.h:134
void * ssl
Definition: libpq-be.h:219
HbaLine * hba
Definition: libpq-be.h:166
ssize_t raw_buf_remaining
Definition: libpq-be.h:234
char * peer_cn
Definition: libpq-be.h:203
int default_keepalives_count
Definition: libpq-be.h:177
char * cmdline_options
Definition: libpq-be.h:153
int keepalives_interval
Definition: libpq-be.h:180
SockAddr raddr
Definition: libpq-be.h:138
int remote_hostname_resolv
Definition: libpq-be.h:142
List * guc_options
Definition: libpq-be.h:154
char * peer_dn
Definition: libpq-be.h:204
bool noblock
Definition: libpq-be.h:135
char * application_name
Definition: libpq-be.h:161
int default_tcp_user_timeout
Definition: libpq-be.h:178
int tcp_user_timeout
Definition: libpq-be.h:182
ssize_t raw_buf_consumed
Definition: libpq-be.h:233
const char * name