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-2022, 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 #ifdef HAVE_NETINET_TCP_H
27 #include <netinet/tcp.h>
28 #endif
29 
30 #ifdef ENABLE_GSS
31 #if defined(HAVE_GSSAPI_H)
32 #include <gssapi.h>
33 #else
34 #include <gssapi/gssapi.h>
35 #endif /* HAVE_GSSAPI_H */
36 /*
37  * GSSAPI brings in headers that set a lot of things in the global namespace on win32,
38  * that doesn't match the msvc build. It gives a bunch of compiler warnings that we ignore,
39  * but also defines a symbol that simply does not exist. Undefine it again.
40  */
41 #ifdef _MSC_VER
42 #undef HAVE_GETADDRINFO
43 #endif
44 #endif /* ENABLE_GSS */
45 
46 #ifdef ENABLE_SSPI
47 #define SECURITY_WIN32
48 #if defined(WIN32) && !defined(_MSC_VER)
49 #include <ntsecapi.h>
50 #endif
51 #include <security.h>
52 #undef SECURITY_WIN32
53 
54 #ifndef ENABLE_GSS
55 /*
56  * Define a fake structure compatible with GSSAPI on Unix.
57  */
58 typedef struct
59 {
60  void *value;
61  int length;
62 } gss_buffer_desc;
63 #endif
64 #endif /* ENABLE_SSPI */
65 
66 #include "datatype/timestamp.h"
67 #include "libpq/hba.h"
68 #include "libpq/pqcomm.h"
69 
70 
71 typedef enum CAC_state
72 {
80 
81 
82 /*
83  * GSSAPI specific state information
84  */
85 #if defined(ENABLE_GSS) | defined(ENABLE_SSPI)
86 typedef struct
87 {
88  gss_buffer_desc outbuf; /* GSSAPI output token buffer */
89 #ifdef ENABLE_GSS
90  gss_cred_id_t cred; /* GSSAPI connection cred's */
91  gss_ctx_id_t ctx; /* GSSAPI connection context */
92  gss_name_t name; /* GSSAPI client name */
93  char *princ; /* GSSAPI Principal used for auth, NULL if
94  * GSSAPI auth was not used */
95  bool auth; /* GSSAPI Authentication used */
96  bool enc; /* GSSAPI encryption in use */
97 #endif
98 } pg_gssinfo;
99 #endif
100 
101 /*
102  * This is used by the postmaster in its communication with frontends. It
103  * contains all state information needed during this communication before the
104  * backend is run. The Port structure is kept in malloc'd memory and is
105  * still available when a backend is running (see MyProcPort). The data
106  * it points to must also be malloc'd, or else palloc'd in TopMemoryContext,
107  * so that it survives into PostgresMain execution!
108  *
109  * remote_hostname is set if we did a successful reverse lookup of the
110  * client's IP address during connection setup.
111  * remote_hostname_resolv tracks the state of hostname verification:
112  * +1 = remote_hostname is known to resolve to client's IP address
113  * -1 = remote_hostname is known NOT to resolve to client's IP address
114  * 0 = we have not done the forward DNS lookup yet
115  * -2 = there was an error in name resolution
116  * If reverse lookup of the client IP address fails, remote_hostname will be
117  * left NULL while remote_hostname_resolv is set to -2. If reverse lookup
118  * succeeds but forward lookup fails, remote_hostname_resolv is also set to -2
119  * (the case is distinguishable because remote_hostname isn't NULL). In
120  * either of the -2 cases, remote_hostname_errcode saves the lookup return
121  * code for possible later use with gai_strerror.
122  */
123 
124 typedef struct Port
125 {
126  pgsocket sock; /* File descriptor */
127  bool noblock; /* is the socket in non-blocking mode? */
128  ProtocolVersion proto; /* FE/BE protocol version */
129  SockAddr laddr; /* local addr (postmaster) */
130  SockAddr raddr; /* remote addr (client) */
131  char *remote_host; /* name (or ip addr) of remote host */
132  char *remote_hostname; /* name (not ip addr) of remote host, if
133  * available */
134  int remote_hostname_resolv; /* see above */
135  int remote_hostname_errcode; /* see above */
136  char *remote_port; /* text rep of remote port */
137  CAC_state canAcceptConnections; /* postmaster connection status */
138 
139  /*
140  * Information that needs to be saved from the startup packet and passed
141  * into backend execution. "char *" fields are NULL if not set.
142  * guc_options points to a List of alternating option names and values.
143  */
145  char *user_name;
148 
149  /*
150  * The startup packet application name, only used here for the "connection
151  * authorized" log message. We shouldn't use this post-startup, instead
152  * the GUC should be used as application can change it afterward.
153  */
155 
156  /*
157  * Information that needs to be held during the authentication cycle.
158  */
160 
161  /*
162  * Authenticated identity. The meaning of this identifier is dependent on
163  * hba->auth_method; it is the identity (if any) that the user presented
164  * during the authentication cycle, before they were assigned a database
165  * role. (It is effectively the "SYSTEM-USERNAME" of a pg_ident usermap
166  * -- though the exact string in use may be different, depending on pg_hba
167  * options.)
168  *
169  * authn_id is NULL if the user has not actually been authenticated, for
170  * example if the "trust" auth method is in use.
171  */
172  const char *authn_id;
173 
174  /*
175  * TCP keepalive and user timeout settings.
176  *
177  * default values are 0 if AF_UNIX or not yet known; current values are 0
178  * if AF_UNIX or using the default. Also, -1 in a default value means we
179  * were unable to find out the default (getsockopt failed).
180  */
189 
190  /*
191  * GSSAPI structures.
192  */
193 #if defined(ENABLE_GSS) || defined(ENABLE_SSPI)
194 
195  /*
196  * If GSSAPI is supported and used on this connection, store GSSAPI
197  * information. Even when GSSAPI is not compiled in, store a NULL pointer
198  * to keep struct offsets the same (for extension ABI compatibility).
199  */
200  pg_gssinfo *gss;
201 #else
202  void *gss;
203 #endif
204 
205  /*
206  * SSL structures.
207  */
209  char *peer_cn;
210  char *peer_dn;
212 
213  /*
214  * OpenSSL structures. (Keep these last so that the locations of other
215  * fields are the same whether or not you build with SSL enabled.)
216  */
217 #ifdef USE_OPENSSL
218  SSL *ssl;
219  X509 *peer;
220 #endif
222 
223 #ifdef USE_SSL
224 /*
225  * Hardcoded DH parameters, used in ephemeral DH keying. (See also
226  * README.SSL for more details on EDH.)
227  *
228  * This is the 2048-bit DH parameter from RFC 3526. The generation of the
229  * prime is specified in RFC 2412 Appendix E, which also discusses the
230  * design choice of the generator. Note that when loaded with OpenSSL
231  * this causes DH_check() to fail on DH_NOT_SUITABLE_GENERATOR, where
232  * leaking a bit is preferred.
233  */
234 #define FILE_DH2048 \
235 "-----BEGIN DH PARAMETERS-----\n\
236 MIIBCAKCAQEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n\
237 IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n\
238 awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n\
239 mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n\
240 fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n\
241 5RXSJhiY+gUQFXKOWoqsqmj//////////wIBAg==\n\
242 -----END DH PARAMETERS-----\n"
243 
244 /*
245  * These functions are implemented by the glue code specific to each
246  * SSL implementation (e.g. be-secure-openssl.c)
247  */
248 
249 /*
250  * Initialize global SSL context.
251  *
252  * If isServerStart is true, report any errors as FATAL (so we don't return).
253  * Otherwise, log errors at LOG level and return -1 to indicate trouble,
254  * preserving the old SSL state if any. Returns 0 if OK.
255  */
256 extern int be_tls_init(bool isServerStart);
257 
258 /*
259  * Destroy global SSL context, if any.
260  */
261 extern void be_tls_destroy(void);
262 
263 /*
264  * Attempt to negotiate SSL connection.
265  */
266 extern int be_tls_open_server(Port *port);
267 
268 /*
269  * Close SSL connection.
270  */
271 extern void be_tls_close(Port *port);
272 
273 /*
274  * Read data from a secure connection.
275  */
276 extern ssize_t be_tls_read(Port *port, void *ptr, size_t len, int *waitfor);
277 
278 /*
279  * Write data to a secure connection.
280  */
281 extern ssize_t be_tls_write(Port *port, void *ptr, size_t len, int *waitfor);
282 
283 /*
284  * Return information about the SSL connection.
285  */
286 extern int be_tls_get_cipher_bits(Port *port);
287 extern const char *be_tls_get_version(Port *port);
288 extern const char *be_tls_get_cipher(Port *port);
289 extern void be_tls_get_peer_subject_name(Port *port, char *ptr, size_t len);
290 extern void be_tls_get_peer_issuer_name(Port *port, char *ptr, size_t len);
291 extern void be_tls_get_peer_serial(Port *port, char *ptr, size_t len);
292 
293 /*
294  * Get the server certificate hash for SCRAM channel binding type
295  * tls-server-end-point.
296  *
297  * The result is a palloc'd hash of the server certificate with its
298  * size, and NULL if there is no certificate available.
299  *
300  * This is not supported with old versions of OpenSSL that don't have
301  * the X509_get_signature_nid() function.
302  */
303 #if defined(USE_OPENSSL) && defined(HAVE_X509_GET_SIGNATURE_NID)
304 #define HAVE_BE_TLS_GET_CERTIFICATE_HASH
305 extern char *be_tls_get_certificate_hash(Port *port, size_t *len);
306 #endif
307 
308 /* init hook for SSL, the default sets the password callback if appropriate */
309 #ifdef USE_OPENSSL
310 typedef void (*openssl_tls_init_hook_typ) (SSL_CTX *context, bool isServerStart);
311 extern PGDLLIMPORT openssl_tls_init_hook_typ openssl_tls_init_hook;
312 #endif
313 
314 #endif /* USE_SSL */
315 
316 #ifdef ENABLE_GSS
317 /*
318  * Return information about the GSSAPI authenticated connection
319  */
320 extern bool be_gssapi_get_auth(Port *port);
321 extern bool be_gssapi_get_enc(Port *port);
322 extern const char *be_gssapi_get_princ(Port *port);
323 
324 /* Read and write to a GSSAPI-encrypted connection. */
325 extern ssize_t be_gssapi_read(Port *port, void *ptr, size_t len);
326 extern ssize_t be_gssapi_write(Port *port, void *ptr, size_t len);
327 #endif /* ENABLE_GSS */
328 
330 
331 /* TCP keepalives configuration. These are no-ops on an AF_UNIX socket. */
332 
333 extern int pq_getkeepalivesidle(Port *port);
334 extern int pq_getkeepalivesinterval(Port *port);
335 extern int pq_getkeepalivescount(Port *port);
336 extern int pq_gettcpusertimeout(Port *port);
337 
338 extern int pq_setkeepalivesidle(int idle, Port *port);
339 extern int pq_setkeepalivesinterval(int interval, Port *port);
340 extern int pq_setkeepalivescount(int count, Port *port);
341 extern int pq_settcpusertimeout(int timeout, Port *port);
342 
343 #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)
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)
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:1331
const char * name
Definition: encode.c:561
struct pg_encoding enc
Definition: encode.c:562
static struct @151 value
int pq_setkeepalivesinterval(int interval, Port *port)
Definition: pqcomm.c:1743
PGDLLIMPORT ProtocolVersion FrontendProtocol
Definition: globals.c:28
int pq_getkeepalivescount(Port *port)
Definition: pqcomm.c:1792
int pq_getkeepalivesinterval(Port *port)
Definition: pqcomm.c:1708
int pq_settcpusertimeout(int timeout, Port *port)
Definition: pqcomm.c:1897
CAC_state
Definition: libpq-be.h:72
@ CAC_TOOMANY
Definition: libpq-be.h:78
@ CAC_OK
Definition: libpq-be.h:73
@ CAC_RECOVERY
Definition: libpq-be.h:76
@ CAC_NOTCONSISTENT
Definition: libpq-be.h:77
@ CAC_STARTUP
Definition: libpq-be.h:74
@ CAC_SHUTDOWN
Definition: libpq-be.h:75
int pq_setkeepalivesidle(int idle, Port *port)
Definition: pqcomm.c:1658
int pq_getkeepalivesidle(Port *port)
Definition: pqcomm.c:1623
struct Port Port
int pq_gettcpusertimeout(Port *port)
Definition: pqcomm.c:1867
int pq_setkeepalivescount(int count, Port *port)
Definition: pqcomm.c:1822
const void size_t len
static int port
Definition: pg_regress.c:92
int pgsocket
Definition: port.h:29
uint32 ProtocolVersion
Definition: pqcomm.h:125
Definition: hba.h:81
Definition: pg_list.h:51
Definition: libpq-be.h:125
bool ssl_in_use
Definition: libpq-be.h:208
char * user_name
Definition: libpq-be.h:145
ProtocolVersion proto
Definition: libpq-be.h:128
char * remote_port
Definition: libpq-be.h:136
SockAddr laddr
Definition: libpq-be.h:129
const char * authn_id
Definition: libpq-be.h:172
char * remote_hostname
Definition: libpq-be.h:132
int remote_hostname_errcode
Definition: libpq-be.h:135
int default_keepalives_idle
Definition: libpq-be.h:181
int keepalives_idle
Definition: libpq-be.h:185
int keepalives_count
Definition: libpq-be.h:187
void * gss
Definition: libpq-be.h:202
int default_keepalives_interval
Definition: libpq-be.h:182
bool peer_cert_valid
Definition: libpq-be.h:211
char * database_name
Definition: libpq-be.h:144
char * remote_host
Definition: libpq-be.h:131
pgsocket sock
Definition: libpq-be.h:126
HbaLine * hba
Definition: libpq-be.h:159
char * peer_cn
Definition: libpq-be.h:209
int default_keepalives_count
Definition: libpq-be.h:183
char * cmdline_options
Definition: libpq-be.h:146
int keepalives_interval
Definition: libpq-be.h:186
SockAddr raddr
Definition: libpq-be.h:130
int remote_hostname_resolv
Definition: libpq-be.h:134
List * guc_options
Definition: libpq-be.h:147
char * peer_dn
Definition: libpq-be.h:210
bool noblock
Definition: libpq-be.h:127
char * application_name
Definition: libpq-be.h:154
int default_tcp_user_timeout
Definition: libpq-be.h:184
CAC_state canAcceptConnections
Definition: libpq-be.h:137
int tcp_user_timeout
Definition: libpq-be.h:188