src/include/libpq/pqcomm.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * pqcomm.h
   4  *              Definitions common to frontends and backends.
   5  *
   6  * NOTE: for historical reasons, this does not correspond to pqcomm.c.
   7  * pqcomm.c's routines are declared in libpq.h.
   8  *
   9  * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
  10  * Portions Copyright (c) 1994, Regents of the University of California
  11  *
  12  * src/include/libpq/pqcomm.h
  13  *
  14  *-------------------------------------------------------------------------
  15  */
  16 #ifndef PQCOMM_H
  17 #define PQCOMM_H
  18
  19 #include <sys/socket.h>
  20 #include <sys/un.h>
  21 #include <netdb.h>
  22 #include <netinet/in.h>
  23
  24 /*
  25  * The definitions for the request/response codes are kept in a separate file
  26  * for ease of use in third party programs.
  27  */
  28 #include "libpq/protocol.h"
  29
  30 typedef struct
  31 {
  32         struct sockaddr_storage addr;
  33         socklen_t       salen;
  34 } SockAddr;
  35
  36 typedef struct
  37 {
  38         int                     family;
  39         SockAddr        addr;
  40 } AddrInfo;
  41
  42 /* Configure the UNIX socket location for the well known port. */
  43
  44 #define UNIXSOCK_PATH(path, port, sockdir) \
  45            (AssertMacro(sockdir), \
  46                 AssertMacro(*(sockdir) != '\0'), \
  47                 snprintf(path, sizeof(path), "%s/.s.PGSQL.%d", \
  48                                  (sockdir), (port)))
  49
  50 /*
  51  * The maximum workable length of a socket path is what will fit into
  52  * struct sockaddr_un.  This is usually only 100 or so bytes :-(.
  53  *
  54  * For consistency, always pass a MAXPGPATH-sized buffer to UNIXSOCK_PATH(),
  55  * then complain if the resulting string is >= UNIXSOCK_PATH_BUFLEN bytes.
  56  * (Because the standard API for getaddrinfo doesn't allow it to complain in
  57  * a useful way when the socket pathname is too long, we have to test for
  58  * this explicitly, instead of just letting the subroutine return an error.)
  59  */
  60 #define UNIXSOCK_PATH_BUFLEN sizeof(((struct sockaddr_un *) NULL)->sun_path)
  61
  62 /*
  63  * A host that looks either like an absolute path or starts with @ is
  64  * interpreted as a Unix-domain socket address.
  65  */
  66 static inline bool
  67 is_unixsock_path(const char *path)
  68 {
  69         return is_absolute_path(path) || path[0] == '@';
  70 }
  71
  72 /*
  73  * These manipulate the frontend/backend protocol version number.
  74  *
  75  * The major number should be incremented for incompatible changes.  The minor
  76  * number should be incremented for compatible changes (eg. additional
  77  * functionality).
  78  *
  79  * If a backend supports version m.n of the protocol it must actually support
  80  * versions m.[0..n].  Backend support for version m-1 can be dropped after a
  81  * `reasonable' length of time.
  82  *
  83  * A frontend isn't required to support anything other than the current
  84  * version.
  85  */
  86
  87 #define PG_PROTOCOL_MAJOR(v)    ((v) >> 16)
  88 #define PG_PROTOCOL_MINOR(v)    ((v) & 0x0000ffff)
  89 #define PG_PROTOCOL_FULL(v)     (PG_PROTOCOL_MAJOR(v) * 10000 + PG_PROTOCOL_MINOR(v))
  90 #define PG_PROTOCOL(m,n)        (((m) << 16) | (n))
  91
  92 /*
  93  * The earliest and latest frontend/backend protocol version supported.
  94  * (Only protocol version 3 is currently supported)
  95  */
  96
  97 #define PG_PROTOCOL_EARLIEST    PG_PROTOCOL(3,0)
  98 #define PG_PROTOCOL_LATEST              PG_PROTOCOL(3,0)
  99
 100 typedef uint32 ProtocolVersion; /* FE/BE protocol version number */
 101
 102 typedef ProtocolVersion MsgType;
 103
 104
 105 /*
 106  * Packet lengths are 4 bytes in network byte order.
 107  *
 108  * The initial length is omitted from the packet layouts appearing below.
 109  */
 110
 111 typedef uint32 PacketLen;
 112
 113 /*
 114  * In protocol 3.0 and later, the startup packet length is not fixed, but
 115  * we set an arbitrary limit on it anyway.  This is just to prevent simple
 116  * denial-of-service attacks via sending enough data to run the server
 117  * out of memory.
 118  */
 119 #define MAX_STARTUP_PACKET_LENGTH 10000
 120
 121
 122 typedef uint32 AuthRequest;
 123
 124
 125 /*
 126  * A client can also send a cancel-current-operation request to the postmaster.
 127  * This is uglier than sending it directly to the client's backend, but it
 128  * avoids depending on out-of-band communication facilities.
 129  *
 130  * The cancel request code must not match any protocol version number
 131  * we're ever likely to use.  This random choice should do.
 132  */
 133 #define CANCEL_REQUEST_CODE PG_PROTOCOL(1234,5678)
 134
 135 typedef struct CancelRequestPacket
 136 {
 137         /* Note that each field is stored in network byte order! */
 138         MsgType         cancelRequestCode;      /* code to identify a cancel request */
 139         uint32          backendPID;             /* PID of client's backend */
 140         uint32          cancelAuthCode; /* secret key to authorize cancel */
 141 } CancelRequestPacket;
 142
 143 /* Application-Layer Protocol Negotiation is required for direct connections
 144  * to avoid protocol confusion attacks (e.g https://alpaca-attack.com/).
 145  *
 146  * ALPN is specified in RFC 7301
 147  *
 148  * This string should be registered at:
 149  * https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids
 150  *
 151  * OpenSSL uses this wire-format for the list of alpn protocols even in the
 152  * API. Both server and client take the same format parameter but the client
 153  * actually sends it to the server as-is and the server it specifies the
 154  * preference order to use to choose the one selected to send back.
 155  *
 156  * c.f. https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_alpn_select_cb.html
 157  *
 158  * The #define can be used to initialize a char[] vector to use directly in the API
 159  */
 160 #define PG_ALPN_PROTOCOL "postgresql"
 161 #define PG_ALPN_PROTOCOL_VECTOR { 10, 'p','o','s','t','g','r','e','s','q','l' }
 162
 163 /*
 164  * A client can also start by sending a SSL or GSSAPI negotiation request to
 165  * get a secure channel.
 166  */
 167 #define NEGOTIATE_SSL_CODE PG_PROTOCOL(1234,5679)
 168 #define NEGOTIATE_GSS_CODE PG_PROTOCOL(1234,5680)
 169
 170 #endif                                                  /* PQCOMM_H */