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