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       59296 : is_unixsock_path(const char *path)
      67             : {
      68       59296 :     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             :  * A client can send a cancel-current-operation request to the postmaster.
     109             :  * This is uglier than sending it directly to the client's backend, but it
     110             :  * avoids depending on out-of-band communication facilities.
     111             :  */
     112             : #define CANCEL_REQUEST_CODE     PG_PROTOCOL(1234,5678)
     113             : 
     114             : /*
     115             :  * A client can also start by sending a SSL or GSSAPI negotiation request to
     116             :  * get a secure channel.
     117             :  */
     118             : #define NEGOTIATE_SSL_CODE      PG_PROTOCOL(1234,5679)
     119             : #define NEGOTIATE_GSS_CODE      PG_PROTOCOL(1234,5680)
     120             : 
     121             : 
     122             : typedef uint32 ProtocolVersion; /* FE/BE protocol version number */
     123             : 
     124             : 
     125             : /*
     126             :  * Packet lengths are 4 bytes in network byte order.
     127             :  *
     128             :  * The initial length is omitted from the packet layouts appearing below.
     129             :  */
     130             : typedef uint32 PacketLen;
     131             : 
     132             : /*
     133             :  * In protocol 3.0 and later, the startup packet length is not fixed, but
     134             :  * we set an arbitrary limit on it anyway.  This is just to prevent simple
     135             :  * denial-of-service attacks via sending enough data to run the server
     136             :  * out of memory.
     137             :  */
     138             : #define MAX_STARTUP_PACKET_LENGTH 10000
     139             : 
     140             : 
     141             : typedef uint32 AuthRequest;     /* an AUTH_REQ_* code */
     142             : 
     143             : 
     144             : /*
     145             :  * The packet used with a CANCEL_REQUEST_CODE.
     146             :  *
     147             :  * Before PostgreSQL v18 and the protocol version bump from 3.0 to 3.2, the
     148             :  * cancel key was always 4 bytes.  With protocol version 3.2, it's variable
     149             :  * length.
     150             :  */
     151             : typedef struct CancelRequestPacket
     152             : {
     153             :     /* Note that each field is stored in network byte order! */
     154             :     ProtocolVersion cancelRequestCode;  /* code to identify a cancel request */
     155             :     uint32      backendPID;     /* PID of client's backend */
     156             :     uint8       cancelAuthCode[FLEXIBLE_ARRAY_MEMBER];  /* secret key to
     157             :                                                          * authorize cancel */
     158             : } CancelRequestPacket;
     159             : 
     160             : 
     161             : /*
     162             :  * Application-Layer Protocol Negotiation is required for direct connections
     163             :  * to avoid protocol confusion attacks (e.g https://alpaca-attack.com/).
     164             :  *
     165             :  * ALPN is specified in RFC 7301
     166             :  *
     167             :  * This string should be registered at:
     168             :  * https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids
     169             :  *
     170             :  * OpenSSL uses this wire-format for the list of alpn protocols even in the
     171             :  * API. Both server and client take the same format parameter but the client
     172             :  * actually sends it to the server as-is and the server it specifies the
     173             :  * preference order to use to choose the one selected to send back.
     174             :  *
     175             :  * c.f. https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_alpn_select_cb.html
     176             :  *
     177             :  * The #define can be used to initialize a char[] vector to use directly in the API
     178             :  */
     179             : #define PG_ALPN_PROTOCOL "postgresql"
     180             : #define PG_ALPN_PROTOCOL_VECTOR { 10, 'p','o','s','t','g','r','e','s','q','l' }
     181             : 
     182             : #endif                          /* PQCOMM_H */