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