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 29508 : is_unixsock_path(const char *path)
67 : {
68 29508 : 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 */
|
