Line data    Source code

       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-2026, 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             : #define UNIXSOCK_PATH(path, port, sockdir) \
      44             :        (AssertMacro(sockdir), \
      45             :         AssertMacro(*(sockdir) != '\0'), \
      46             :         snprintf(path, sizeof(path), "%s/.s.PGSQL.%d", \
      47             :                  (sockdir), (port)))
      48             : 
      49             : /*
      50             :  * The maximum workable length of a socket path is what will fit into
      51             :  * struct sockaddr_un.  This is usually only 100 or so bytes :-(.
      52             :  *
      53             :  * For consistency, always pass a MAXPGPATH-sized buffer to UNIXSOCK_PATH(),
      54             :  * then complain if the resulting string is >= UNIXSOCK_PATH_BUFLEN bytes.
      55             :  * (Because the standard API for getaddrinfo doesn't allow it to complain in
      56             :  * a useful way when the socket pathname is too long, we have to test for
      57             :  * this explicitly, instead of just letting the subroutine return an error.)
      58             :  */
      59             : #define UNIXSOCK_PATH_BUFLEN sizeof(((struct sockaddr_un *) NULL)->sun_path)
      60             : 
      61             : /*
      62             :  * A host that looks either like an absolute path or starts with @ is
      63             :  * interpreted as a Unix-domain socket address.
      64             :  */
      65             : static inline bool
      66       59952 : is_unixsock_path(const char *path)
      67             : {
      68       59952 :     return is_absolute_path(path) || path[0] == '@';
      69             : }
      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             : #define PG_PROTOCOL_MAJOR(v)    ((v) >> 16)
      87             : #define PG_PROTOCOL_MINOR(v)    ((v) & 0x0000ffff)
      88             : #define PG_PROTOCOL_FULL(v) (PG_PROTOCOL_MAJOR(v) * 10000 + PG_PROTOCOL_MINOR(v))
      89             : #define PG_PROTOCOL(m,n)    (((m) << 16) | (n))
      90             : 
      91             : /*
      92             :  * The earliest and latest frontend/backend protocol version supported.
      93             :  */
      94             : #define PG_PROTOCOL_EARLIEST    PG_PROTOCOL(3,0)
      95             : #define PG_PROTOCOL_LATEST      PG_PROTOCOL(3,2)
      96             : 
      97             : /*
      98             :  * Reserved protocol numbers, which have special semantics:
      99             :  */
     100             : 
     101             : /*
     102             :  * 3.1 would have collided with old pgbouncer deployments, and was skipped. We
     103             :  * neither emit it nor accept it on the wire.
     104             :  */
     105             : #define PG_PROTOCOL_RESERVED_31     PG_PROTOCOL(3,1)
     106             : 
     107             : /*
     108             :  * PG_PROTOCOL_GREASE is an intentionally unsupported protocol version used
     109             :  * for "greasing" (the practice of sending valid, but extraneous or otherwise
     110             :  * unusual, messages to keep peer implementations honest). This helps ensure
     111             :  * that servers properly implement protocol version negotiation. Version 3.9999
     112             :  * was chosen since it is safely within the valid range, it is representable
     113             :  * via PQfullProtocolVersion, and it is unlikely to ever be needed in practice.
     114             :  */
     115             : #define PG_PROTOCOL_GREASE      PG_PROTOCOL(3,9999)
     116             : 
     117             : /*
     118             :  * A client can send a cancel-current-operation request to the postmaster.
     119             :  * This is uglier than sending it directly to the client's backend, but it
     120             :  * avoids depending on out-of-band communication facilities.
     121             :  */
     122             : #define CANCEL_REQUEST_CODE     PG_PROTOCOL(1234,5678)
     123             : 
     124             : /*
     125             :  * A client can also start by sending a SSL or GSSAPI negotiation request to
     126             :  * get a secure channel.
     127             :  */
     128             : #define NEGOTIATE_SSL_CODE      PG_PROTOCOL(1234,5679)
     129             : #define NEGOTIATE_GSS_CODE      PG_PROTOCOL(1234,5680)
     130             : 
     131             : 
     132             : typedef uint32 ProtocolVersion; /* FE/BE protocol version number */
     133             : 
     134             : 
     135             : /*
     136             :  * Packet lengths are 4 bytes in network byte order.
     137             :  *
     138             :  * The initial length is omitted from the packet layouts appearing below.
     139             :  */
     140             : typedef uint32 PacketLen;
     141             : 
     142             : /*
     143             :  * In protocol 3.0 and later, the startup packet length is not fixed, but
     144             :  * we set an arbitrary limit on it anyway.  This is just to prevent simple
     145             :  * denial-of-service attacks via sending enough data to run the server
     146             :  * out of memory.
     147             :  */
     148             : #define MAX_STARTUP_PACKET_LENGTH 10000
     149             : 
     150             : 
     151             : typedef uint32 AuthRequest;     /* an AUTH_REQ_* code */
     152             : 
     153             : 
     154             : /*
     155             :  * The packet used with a CANCEL_REQUEST_CODE.
     156             :  *
     157             :  * Before PostgreSQL v18 and the protocol version bump from 3.0 to 3.2, the
     158             :  * cancel key was always 4 bytes.  With protocol version 3.2, it's variable
     159             :  * length.
     160             :  */
     161             : typedef struct CancelRequestPacket
     162             : {
     163             :     /* Note that each field is stored in network byte order! */
     164             :     ProtocolVersion cancelRequestCode;  /* code to identify a cancel request */
     165             :     uint32      backendPID;     /* PID of client's backend */
     166             :     uint8       cancelAuthCode[FLEXIBLE_ARRAY_MEMBER];  /* secret key to
     167             :                                                          * authorize cancel */
     168             : } CancelRequestPacket;
     169             : 
     170             : 
     171             : /*
     172             :  * Application-Layer Protocol Negotiation is required for direct connections
     173             :  * to avoid protocol confusion attacks (e.g https://alpaca-attack.com/).
     174             :  *
     175             :  * ALPN is specified in RFC 7301
     176             :  *
     177             :  * This string should be registered at:
     178             :  * https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids
     179             :  *
     180             :  * OpenSSL uses this wire-format for the list of alpn protocols even in the
     181             :  * API. Both server and client take the same format parameter but the client
     182             :  * actually sends it to the server as-is and the server it specifies the
     183             :  * preference order to use to choose the one selected to send back.
     184             :  *
     185             :  * c.f. https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_alpn_select_cb.html
     186             :  *
     187             :  * The #define can be used to initialize a char[] vector to use directly in the API
     188             :  */
     189             : #define PG_ALPN_PROTOCOL "postgresql"
     190             : #define PG_ALPN_PROTOCOL_VECTOR { 10, 'p','o','s','t','g','r','e','s','q','l' }
     191             : 
     192             : #endif                          /* PQCOMM_H */