PostgreSQL Source Code  git master
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  */
48 typedef 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)
65 typedef 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  */
90 typedef struct ClientConnectionInfo
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 
132 typedef 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  */
152  char *user_name;
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;
206  bool alpn_used;
207 
208  /*
209  * OpenSSL structures. (Keep these last so that the locations of other
210  * fields are the same whether or not you build with SSL enabled.)
211  */
212 #ifdef USE_OPENSSL
213  SSL *ssl;
214  X509 *peer;
215 #endif
216 
217  /*
218  * This is a bit of a hack. raw_buf is data that was previously read and
219  * buffered in a higher layer but then "unread" and needs to be read again
220  * while establishing an SSL connection via the SSL library layer.
221  *
222  * There's no API to "unread", the upper layer just places the data in the
223  * Port structure in raw_buf and sets raw_buf_remaining to the amount of
224  * bytes unread and raw_buf_consumed to 0.
225  */
226  char *raw_buf;
230 
231 /*
232  * ClientSocket holds a socket for an accepted connection, along with the
233  * information about the remote endpoint. This is passed from postmaster to
234  * the backend process.
235  */
236 typedef struct ClientSocket
237 {
238  pgsocket sock; /* File descriptor */
239  SockAddr raddr; /* remote addr (client) */
241 
242 #ifdef USE_SSL
243 /*
244  * Hardcoded DH parameters, used in ephemeral DH keying. (See also
245  * README.SSL for more details on EDH.)
246  *
247  * This is the 2048-bit DH parameter from RFC 3526. The generation of the
248  * prime is specified in RFC 2412 Appendix E, which also discusses the
249  * design choice of the generator. Note that when loaded with OpenSSL
250  * this causes DH_check() to fail on DH_NOT_SUITABLE_GENERATOR, where
251  * leaking a bit is preferred.
252  */
253 #define FILE_DH2048 \
254 "-----BEGIN DH PARAMETERS-----\n\
255 MIIBCAKCAQEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n\
256 IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n\
257 awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n\
258 mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n\
259 fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n\
260 5RXSJhiY+gUQFXKOWoqsqmj//////////wIBAg==\n\
261 -----END DH PARAMETERS-----\n"
262 
263 /*
264  * These functions are implemented by the glue code specific to each
265  * SSL implementation (e.g. be-secure-openssl.c)
266  */
267 
268 /*
269  * Initialize global SSL context.
270  *
271  * If isServerStart is true, report any errors as FATAL (so we don't return).
272  * Otherwise, log errors at LOG level and return -1 to indicate trouble,
273  * preserving the old SSL state if any. Returns 0 if OK.
274  */
275 extern int be_tls_init(bool isServerStart);
276 
277 /*
278  * Destroy global SSL context, if any.
279  */
280 extern void be_tls_destroy(void);
281 
282 /*
283  * Attempt to negotiate SSL connection.
284  */
285 extern int be_tls_open_server(Port *port);
286 
287 /*
288  * Close SSL connection.
289  */
290 extern void be_tls_close(Port *port);
291 
292 /*
293  * Read data from a secure connection.
294  */
295 extern ssize_t be_tls_read(Port *port, void *ptr, size_t len, int *waitfor);
296 
297 /*
298  * Write data to a secure connection.
299  */
300 extern ssize_t be_tls_write(Port *port, void *ptr, size_t len, int *waitfor);
301 
302 /*
303  * Return information about the SSL connection.
304  */
305 extern int be_tls_get_cipher_bits(Port *port);
306 extern const char *be_tls_get_version(Port *port);
307 extern const char *be_tls_get_cipher(Port *port);
308 extern void be_tls_get_peer_subject_name(Port *port, char *ptr, size_t len);
309 extern void be_tls_get_peer_issuer_name(Port *port, char *ptr, size_t len);
310 extern void be_tls_get_peer_serial(Port *port, char *ptr, size_t len);
311 
312 /*
313  * Get the server certificate hash for SCRAM channel binding type
314  * tls-server-end-point.
315  *
316  * The result is a palloc'd hash of the server certificate with its
317  * size, and NULL if there is no certificate available.
318  */
319 extern char *be_tls_get_certificate_hash(Port *port, size_t *len);
320 
321 /* init hook for SSL, the default sets the password callback if appropriate */
322 #ifdef USE_OPENSSL
323 typedef void (*openssl_tls_init_hook_typ) (SSL_CTX *context, bool isServerStart);
324 extern PGDLLIMPORT openssl_tls_init_hook_typ openssl_tls_init_hook;
325 #endif
326 
327 #endif /* USE_SSL */
328 
329 #ifdef ENABLE_GSS
330 /*
331  * Return information about the GSSAPI authenticated connection
332  */
333 extern bool be_gssapi_get_auth(Port *port);
334 extern bool be_gssapi_get_enc(Port *port);
335 extern const char *be_gssapi_get_princ(Port *port);
336 extern bool be_gssapi_get_delegation(Port *port);
337 
338 /* Read and write to a GSSAPI-encrypted connection. */
339 extern ssize_t be_gssapi_read(Port *port, void *ptr, size_t len);
340 extern ssize_t be_gssapi_write(Port *port, void *ptr, size_t len);
341 #endif /* ENABLE_GSS */
342 
345 
346 /* TCP keepalives configuration. These are no-ops on an AF_UNIX socket. */
347 
348 extern int pq_getkeepalivesidle(Port *port);
349 extern int pq_getkeepalivesinterval(Port *port);
350 extern int pq_getkeepalivescount(Port *port);
351 extern int pq_gettcpusertimeout(Port *port);
352 
353 extern int pq_setkeepalivesidle(int idle, Port *port);
354 extern int pq_setkeepalivesinterval(int interval, Port *port);
355 extern int pq_setkeepalivescount(int count, Port *port);
356 extern int pq_settcpusertimeout(int timeout, Port *port);
357 
358 #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)
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)
const char * be_tls_get_cipher(Port *port)
void be_tls_get_peer_subject_name(Port *port, char *ptr, size_t len)
#define PGDLLIMPORT
Definition: c.h:1316
enc
UserAuth
Definition: hba.h:26
static struct @155 value
int pq_setkeepalivesinterval(int interval, Port *port)
Definition: pqcomm.c:1749
PGDLLIMPORT ProtocolVersion FrontendProtocol
Definition: globals.c:28
int pq_getkeepalivescount(Port *port)
Definition: pqcomm.c:1798
int pq_getkeepalivesinterval(Port *port)
Definition: pqcomm.c:1714
int pq_settcpusertimeout(int timeout, Port *port)
Definition: pqcomm.c:1903
int pq_setkeepalivesidle(int idle, Port *port)
Definition: pqcomm.c:1664
int pq_getkeepalivesidle(Port *port)
Definition: pqcomm.c:1629
struct Port Port
struct ClientSocket ClientSocket
PGDLLIMPORT ClientConnectionInfo MyClientConnectionInfo
Definition: miscinit.c:1010
struct ClientConnectionInfo ClientConnectionInfo
int pq_gettcpusertimeout(Port *port)
Definition: pqcomm.c:1873
int pq_setkeepalivescount(int count, Port *port)
Definition: pqcomm.c:1828
const void size_t len
static int port
Definition: pg_regress.c:116
int pgsocket
Definition: port.h:29
uint32 ProtocolVersion
Definition: pqcomm.h:99
tree context
Definition: radixtree.h:1829
const char * authn_id
Definition: libpq-be.h:103
UserAuth auth_method
Definition: libpq-be.h:109
SockAddr raddr
Definition: libpq-be.h:239
pgsocket sock
Definition: libpq-be.h:238
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
char * raw_buf
Definition: libpq-be.h:226
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
char * remote_host
Definition: libpq-be.h:139
bool alpn_used
Definition: libpq-be.h:206
pgsocket sock
Definition: libpq-be.h:134
HbaLine * hba
Definition: libpq-be.h:166
ssize_t raw_buf_remaining
Definition: libpq-be.h:228
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:227
const char * name