MySQL 8.0.30
Source Code Documentation
network_provider.h
Go to the documentation of this file.
1/* Copyright (c) 2015, 2022, Oracle and/or its affiliates.
2
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6
7 This program is also distributed with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have included with MySQL.
13
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License, version 2.0, for more details.
18
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22
23#ifndef NETWORK_PROVIDER_H
24#define NETWORK_PROVIDER_H
25
26#ifndef XCOM_WITHOUT_OPENSSL
27#ifdef _WIN32
28/* In OpenSSL before 1.1.0, we need this first. */
29#include <winsock2.h>
30#endif
31#include <openssl/ssl.h>
32#endif
33
34#include <atomic>
35#include <memory>
36#include <string>
37#include <vector>
38
39/**
40 * @brief Enum that describes the available XCom Communication Stacks
41 */
46};
47
48/*
49 Possible operation modes as explained further down. If you
50 want to add a new mode, do it before the LAST_SSL_MODE.
51*/
60};
61
62/*
63 Possible operation fips modes as explained further down. If you
64 want to add a new ssl fips mode, do it before the LAST_SSL_FIPS_MODE.
65*/
72};
73
74/**
75 * @brief This class is a helper to translate a Communication Stack to a
76 string
77 *
78 */
80 public:
81 static const char *to_string(enum_transport_protocol protocol) {
82 static std::vector<const char *> m_running_protocol_to_string = {"XCom",
83 "MySQL"};
84
85 return protocol > INVALID_PROTOCOL && protocol <= MYSQL_PROTOCOL
86 ? m_running_protocol_to_string[protocol]
87 : "Invalid Protocol";
88 }
89};
90
91/**
92 * @brief Security credentials to establish a connection
93 */
95 std::string user;
96 std::string pass;
97 bool use_ssl;
98};
99
100/*
101 Set the necessary SSL parameters before initialization.
102
103 server_key_file - Path of file that contains the server's X509 key in PEM
104 format.
105 server_cert_file - Path of file that contains the server's X509 certificate
106 in PEM format.
107 client_key_file - Path of file that contains the client's X509 key in PEM
108 format.
109 client_cert_file - Path of file that contains the client's X509 certificate
110 in PEM format.
111 ca_file - Path of file that contains list of trusted SSL CAs.
112 ca_path - Path of directory that contains trusted SSL CA
113 certificates in PEM format.
114 crl_file - Path of file that contains certificate revocation lists.
115 crl_path - Path of directory that contains certificate revocation
116 list files.
117 cipher - List of permitted ciphers to use for connection
118 encryption.
119 tls_version - Protocols permitted for secure connections.
120 tls_ciphersuites - List of permitted ciphersuites to use for TLS 1.3
121 connection encryption.
122
123 Note that only the server_key_file/server_cert_file and the client_key_file/
124 client_cert_file are required and the rest of the pointers can be NULL.
125 If the key is provided along with the certificate, either the key file or
126 the other can be ommited.
127
128 The caller can free the parameters after the SSL is started
129 if this is necessary.
130*/
133 const char *server_key_file;
134 const char *server_cert_file;
135 const char *client_key_file;
136 const char *client_cert_file;
137 const char *ca_file;
138 const char *ca_path;
139 const char *crl_file;
140 const char *crl_path;
141 const char *cipher;
142};
144 const char *tls_version;
145 const char *tls_ciphersuites;
146};
147
148/**
149 * @brief Possible configuration parameters
150 */
152 unsigned short port;
153
156};
157
158/**
159 * @brief Represents an open connection.
160 */
162 Network_connection(int parameter_fd)
163 : fd(parameter_fd)
164#ifndef XCOM_WITHOUT_OPENSSL
165 ,
167#endif
168 ,
169 has_error(false) {
170 }
171
172 Network_connection(int parameter_fd
173#ifndef XCOM_WITHOUT_OPENSSL
174 ,
175 SSL *parameter_ssl_fd
176#endif
177 )
178 : fd(parameter_fd)
179#ifndef XCOM_WITHOUT_OPENSSL
180 ,
181 ssl_fd(parameter_ssl_fd)
182#endif
183 ,
184 has_error(false) {
185 }
186
187 Network_connection(int parameter_fd
188#ifndef XCOM_WITHOUT_OPENSSL
189 ,
190 SSL *parameter_ssl_fd
191#endif
192 ,
193 bool parameter_has_error)
194 : fd(parameter_fd)
195#ifndef XCOM_WITHOUT_OPENSSL
196 ,
197 ssl_fd(parameter_ssl_fd)
198#endif
199 ,
200 has_error(parameter_has_error) {
201 }
202
203 int fd;
204#ifndef XCOM_WITHOUT_OPENSSL
205 SSL *ssl_fd;
206#endif
208};
209
210/**
211 * @brief Class that provides Network Namespace services
212 */
214 public:
216
217 /**
218 Method to get the network namespace configured for a channel
219
220 @param[out] net_ns The network namespace to extract
221
222 @return the operation status
223 @retval false OK
224 @retval true Error, channel not found
225*/
226 virtual int channel_get_network_namespace(std::string &net_ns) = 0;
227
228 /**
229 Set active network namespace specified by a name.
230
231 @param network_namespace the name of a network namespace to be set active
232
233 @return false on success, true on error
234 @note all opened descriptors used during function run are closed on error
235 */
236 virtual bool set_network_namespace(const std::string &network_namespace) = 0;
237
238 /**
239 Restore original network namespace used to be active before a new network
240 namespace has been set.
241
242 @return false on success, true on failure
243 */
245};
246
247/**
248 * @brief Base class for External Network Providers
249 *
250 * This virtual class will serve as base class for any external entity that
251 * whishes to provide network connections to XCom.
252 *
253 * It will have to implement the following methods:
254 * - start();
255 * - stop();
256 * - get_─ęd();
257 * - configure();
258 * - open_connection();
259 * - close_connection();
260 *
261 * If provides a lock free implementation of (set)\‍(get)_connection() for
262 * multithreaded usage.
263 *
264 *
265 */
267 public:
269 m_shared_connection.store(nullptr);
270 }
273
276
277 virtual ~Network_provider() {}
278
279 /**
280 * @brief Starts the network provider.
281 *
282 * Each implementation will place here any code that it needs to start a
283 * network provider.
284 *
285 * start() is synchronous. After start() succeeded, it is assumed that XCom
286 * is ready to receive new connections.
287 *
288 * @return a pair of <bool,int>
289 * bool indicates the success of the operation. false means success.
290 * int returns an error code.
291 */
292 virtual std::pair<bool, int> start() = 0;
293
294 /**
295 * @brief Stops the network provider.
296 *
297 * Each implementation will place here any code that it needs to stop a
298 * network provider.
299 *
300 * stop() is synchronous. After stop() succeeded, it is assumed that XCom
301 * shall not receive any new connection.
302 *
303 * @return a pair of <bool,int>
304 * bool indicates the success of the operation. false means success.
305 * int returns an error code.
306 */
307 virtual std::pair<bool, int> stop() = 0;
308
309 /**
310 * @brief Get the communcation stack implmeneted by this provider
311 *
312 * Return a valid value withint the range of RunningProtocol enum.
313 *
314 * @return RunningProtocol valid value
315 */
317
318 /**
319 * @brief Configures a network provider
320 *
321 * @param params a sensible list of possibly configurable network parameters
322 *
323 * @return true in case of a successful configuration.
324 * @return false in case of a unsuccessful configuration.
325 */
326 virtual bool configure(const Network_configuration_parameters &params) = 0;
327
328 /**
329 * @brief Configures the active provider with all things needed to establish
330 * SSL connections
331 *
332 * @param params configuration parameters for SSL.
333 *
334 * @return true In case of success.
335 * @return false In case of failure.
336 */
338 const Network_configuration_parameters &params) = 0;
339
341
343
344 /**
345 * @brief Opens a new connection to another XCom endpoint served by the same
346 * Network provider.
347 *
348 * @param address address of the remote endpoint
349 * @param port port of the remote endpoint
350 * @param security_credentials security credentials to connect to the remote
351 * endpoint
352 * @param connection_timeout
353 * @return std::unique_ptr<Network_connection> an established connection.
354 * nullptr in case of failure.
355 */
356 virtual std::unique_ptr<Network_connection> open_connection(
357 const std::string &address, const unsigned short port,
358 const Network_security_credentials &security_credentials,
359 int connection_timeout = default_connection_timeout()) = 0;
360
361 /**
362 * @brief Closes an open connection to another XCom endpoint served by the
363 * same Network provider.
364 *
365 * @param connection an open and valid connection
366 * @return int an error code in case of error. 0, otherwise.
367 */
368 virtual int close_connection(const Network_connection &connection) = 0;
369
370 /**
371 * @brief Lock-free Set connection
372 *
373 * Sets a new connection received by this provider. It will be consumed
374 * internally by get_new_connection().
375 *
376 * @param connection a newly created connection.
377 */
379 Network_connection *null_desired_value;
380 do {
381 null_desired_value = nullptr;
382 } while (!m_shared_connection.compare_exchange_weak(null_desired_value,
383 connection));
384 }
385
386 /**
387 * @brief Get the new connection object
388 *
389 * @return Network_connection* a new connection coming from this network
390 * provider
391 */
394
396
397 if (new_connection != nullptr) m_shared_connection.store(nullptr);
398
399 return new_connection;
400 }
401
404
405 if (to_purge) {
406 close_connection(*to_purge);
407 }
408
409 delete to_purge;
410 }
411
412 static constexpr int default_connection_timeout() { return 3000; }
413
414 private:
415 std::atomic<Network_connection *> m_shared_connection;
416};
417
418#endif // NETWORK_PROVIDER_H
This class is a helper to translate a Communication Stack to a string.
Definition: network_provider.h:79
static const char * to_string(enum_transport_protocol protocol)
Definition: network_provider.h:81
Class that provides Network Namespace services.
Definition: network_provider.h:213
virtual bool set_network_namespace(const std::string &network_namespace)=0
Set active network namespace specified by a name.
virtual ~Network_namespace_manager()
Definition: network_provider.h:215
virtual bool restore_original_network_namespace()=0
Restore original network namespace used to be active before a new network namespace has been set.
virtual int channel_get_network_namespace(std::string &net_ns)=0
Method to get the network namespace configured for a channel.
Base class for External Network Providers.
Definition: network_provider.h:266
void reset_new_connection()
Definition: network_provider.h:402
virtual int close_connection(const Network_connection &connection)=0
Closes an open connection to another XCom endpoint served by the same Network provider.
virtual bool finalize_secure_connections_context()=0
Network_connection * get_new_connection()
Get the new connection object.
Definition: network_provider.h:392
virtual std::pair< bool, int > start()=0
Starts the network provider.
virtual std::unique_ptr< Network_connection > open_connection(const std::string &address, const unsigned short port, const Network_security_credentials &security_credentials, int connection_timeout=default_connection_timeout())=0
Opens a new connection to another XCom endpoint served by the same Network provider.
virtual std::pair< bool, int > stop()=0
Stops the network provider.
static constexpr int default_connection_timeout()
Definition: network_provider.h:412
Network_provider()
Definition: network_provider.h:268
virtual bool configure_secure_connections(const Network_configuration_parameters &params)=0
Configures the active provider with all things needed to establish SSL connections.
std::atomic< Network_connection * > m_shared_connection
Definition: network_provider.h:415
virtual bool cleanup_secure_connections_context()=0
virtual ~Network_provider()
Definition: network_provider.h:277
Network_provider & operator=(Network_provider &param)=delete
virtual enum_transport_protocol get_communication_stack() const =0
Get the communcation stack implmeneted by this provider.
virtual bool configure(const Network_configuration_parameters &params)=0
Configures a network provider.
void set_new_connection(Network_connection *connection)
Lock-free Set connection.
Definition: network_provider.h:378
Network_provider(Network_provider &&param)
Definition: network_provider.h:271
Network_provider(Network_provider &param)=delete
Fido Client Authentication nullptr
Definition: fido_client_plugin.cc:221
bool load(THD *, const dd::String_type &fname, dd::String_type *buf)
Read an sdi file from disk and store in a buffer.
Definition: sdi_file.cc:307
ssl_enum_fips_mode_options
Definition: network_provider.h:66
@ INVALID_SSL_FIPS_MODE
Definition: network_provider.h:67
@ FIPS_MODE_ON
Definition: network_provider.h:69
@ FIPS_MODE_OFF
Definition: network_provider.h:68
@ FIPS_MODE_STRICT
Definition: network_provider.h:70
@ LAST_SSL_FIPS_MODE
Definition: network_provider.h:71
enum_transport_protocol
Enum that describes the available XCom Communication Stacks.
Definition: network_provider.h:42
@ INVALID_PROTOCOL
Definition: network_provider.h:43
@ MYSQL_PROTOCOL
Definition: network_provider.h:45
@ XCOM_PROTOCOL
Definition: network_provider.h:44
ssl_enum_mode_options
Definition: network_provider.h:52
@ LAST_SSL_MODE
Definition: network_provider.h:59
@ SSL_VERIFY_CA
Definition: network_provider.h:57
@ SSL_VERIFY_IDENTITY
Definition: network_provider.h:58
@ SSL_REQUIRED
Definition: network_provider.h:56
@ SSL_PREFERRED
Definition: network_provider.h:55
@ INVALID_SSL_MODE
Definition: network_provider.h:53
@ SSL_DISABLED
Definition: network_provider.h:54
static connection_descriptor * new_connection(int fd, SSL *ssl_fd)
Definition: node_connection.h:60
required string network_namespace
Definition: replication_asynchronous_connection_failover.proto:33
required uint64 port
Definition: replication_asynchronous_connection_failover.proto:32
Possible configuration parameters.
Definition: network_provider.h:151
struct ssl_parameters ssl_params
Definition: network_provider.h:154
struct tls_parameters tls_params
Definition: network_provider.h:155
unsigned short port
Definition: network_provider.h:152
Represents an open connection.
Definition: network_provider.h:161
Network_connection(int parameter_fd, SSL *parameter_ssl_fd, bool parameter_has_error)
Definition: network_provider.h:187
Network_connection(int parameter_fd, SSL *parameter_ssl_fd)
Definition: network_provider.h:172
int fd
Definition: network_provider.h:203
Network_connection(int parameter_fd)
Definition: network_provider.h:162
SSL * ssl_fd
Definition: network_provider.h:205
bool has_error
Definition: network_provider.h:207
Security credentials to establish a connection.
Definition: network_provider.h:94
std::string user
Definition: network_provider.h:95
bool use_ssl
Definition: network_provider.h:97
std::string pass
Definition: network_provider.h:96
Definition: network_provider.h:131
const char * server_key_file
Definition: network_provider.h:133
const char * client_key_file
Definition: network_provider.h:135
const char * ca_path
Definition: network_provider.h:138
const char * cipher
Definition: network_provider.h:141
const char * crl_file
Definition: network_provider.h:139
const char * client_cert_file
Definition: network_provider.h:136
const char * crl_path
Definition: network_provider.h:140
int ssl_mode
Definition: network_provider.h:132
const char * server_cert_file
Definition: network_provider.h:134
const char * ca_file
Definition: network_provider.h:137
Definition: network_provider.h:143
const char * tls_ciphersuites
Definition: network_provider.h:145
const char * tls_version
Definition: network_provider.h:144