src/include/libpq/libpq-be.h

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