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