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