MySQL 9.0.0
Source Code Documentation
network_provider.h
Go to the documentation of this file.
1/* Copyright (c) 2015, 2024, 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 designed to work 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 either included with
13 the program or referenced in the documentation.
14
15 This program is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 GNU General Public License, version 2.0, for more details.
19
20 You should have received a copy of the GNU General Public License
21 along with this program; if not, write to the Free Software
22 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
23
24#ifndef NETWORK_PROVIDER_H
25#define NETWORK_PROVIDER_H
26
27#ifndef XCOM_WITHOUT_OPENSSL
28#ifdef _WIN32
29/* In OpenSSL before 1.1.0, we need this first. */
30#include <winsock2.h>
31#endif
32#include <openssl/err.h>
33#include <openssl/ssl.h>
34#endif
35
36#include <atomic>
37#include <functional>
38#include <memory>
39#include <string>
40#include <vector>
41
42/**
43 * @brief Enum that describes the available XCom Communication Stacks
44 */
49};
50
51/*
52 Possible operation modes as explained further down. If you
53 want to add a new mode, do it before the LAST_SSL_MODE.
54*/
63};
64
65/*
66 Possible operation fips modes as explained further down. If you
67 want to add a new ssl fips mode, do it before the LAST_SSL_FIPS_MODE.
68*/
75};
76
77/**
78 * @brief Dynamic log level enum values
79 *
80 * Network Provider will allow external entities to change a given log level,
81 * determined by an external condition.
82 *
83 * For that, we create an enumeration that contains all possible generic log
84 * levels that we have seen in all implementations of a Network Provider.
85 *
86 * Each Network Provider specialization must provide a mapping between
87 * network_provider_dynamic_log_level and their specific log level.
88 *
89 * An example of this mechanism is as follows:
90 *
91 * Let us consider that a coder decided that a certain log output in
92 * open_connection, on an implementation of a network provider, is ERROR.
93 *
94 * At the same time, that developer allows an external entity that calls
95 * open_connection to override that log output. That could happen because the
96 * caller of open_connection wants to lower the verbosity due to too many errors
97 * in a short amount of time.
98 *
99 * The developer must then use the implemented mapping referenced above on
100 * that instruction and consume the input parameter of open_connection that
101 * refers to an external network_provider_dynamic_log_level.
102 */
104 PROVIDED = 0,
105 FATAL,
106 ERROR,
107 WARNING,
108 INFO,
109 DEBUG,
110 TRACE,
112};
113
114/**
115 * @brief This class is a helper to translate a Communication Stack to a
116 string
117 *
118 */
120 public:
121 static const char *to_string(enum_transport_protocol protocol) {
122 static std::vector<const char *> m_running_protocol_to_string = {"XCom",
123 "MySQL"};
124
125 return protocol > INVALID_PROTOCOL && protocol <= MYSQL_PROTOCOL
126 ? m_running_protocol_to_string[protocol]
127 : "Invalid Protocol";
128 }
129};
130
131/**
132 * @brief Security credentials to establish a connection
133 */
135 std::string user;
136 std::string pass;
138};
139
140/*
141 Set the necessary SSL parameters before initialization.
142
143 server_key_file - Path of file that contains the server's X509 key in PEM
144 format.
145 server_cert_file - Path of file that contains the server's X509 certificate
146 in PEM format.
147 client_key_file - Path of file that contains the client's X509 key in PEM
148 format.
149 client_cert_file - Path of file that contains the client's X509 certificate
150 in PEM format.
151 ca_file - Path of file that contains list of trusted SSL CAs.
152 ca_path - Path of directory that contains trusted SSL CA
153 certificates in PEM format.
154 crl_file - Path of file that contains certificate revocation lists.
155 crl_path - Path of directory that contains certificate revocation
156 list files.
157 cipher - List of permitted ciphers to use for connection
158 encryption.
159 tls_version - Protocols permitted for secure connections.
160 tls_ciphersuites - List of permitted ciphersuites to use for TLS 1.3
161 connection encryption.
162
163 Note that only the server_key_file/server_cert_file and the client_key_file/
164 client_cert_file are required and the rest of the pointers can be NULL.
165 If the key is provided along with the certificate, either the key file or
166 the other can be omitted.
167
168 The caller can free the parameters after the SSL is started
169 if this is necessary.
170*/
173 const char *server_key_file;
174 const char *server_cert_file;
175 const char *client_key_file;
176 const char *client_cert_file;
177 const char *ca_file;
178 const char *ca_path;
179 const char *crl_file;
180 const char *crl_path;
181 const char *cipher;
182};
184 const char *tls_version;
185 const char *tls_ciphersuites;
186};
187
188/**
189 * @brief Possible configuration parameters
190 */
192 unsigned short port;
193
196};
197
198/**
199 * @brief Represents an open connection.
200 */
202 Network_connection(int parameter_fd)
203 : fd(parameter_fd)
204#ifndef XCOM_WITHOUT_OPENSSL
205 ,
207#endif
208 ,
209 has_error(false) {
210 }
211
212 Network_connection(int parameter_fd, void *parameter_ssl_fd)
213 : fd(parameter_fd),
214#ifndef XCOM_WITHOUT_OPENSSL
215 ssl_fd(static_cast<SSL *>(parameter_ssl_fd)),
216#endif
217 has_error(false) {
218 }
219
220 Network_connection(int parameter_fd,
221#ifndef XCOM_WITHOUT_OPENSSL
222 SSL *parameter_ssl_fd,
223#endif
224 bool parameter_has_error)
225 : fd(parameter_fd),
226#ifndef XCOM_WITHOUT_OPENSSL
227 ssl_fd(parameter_ssl_fd),
228#endif
229 has_error(parameter_has_error) {
230 }
231
232 int fd;
233#ifndef XCOM_WITHOUT_OPENSSL
234 SSL *ssl_fd;
235#endif
237};
238
239/**
240 * @brief Class that provides Network Namespace services
241 */
243 public:
245
246 /**
247 Method to get the network namespace configured for a channel
248
249 @param[out] net_ns The network namespace to extract
250
251 @return the operation status
252 @retval false OK
253 @retval true Error, channel not found
254*/
255 virtual int channel_get_network_namespace(std::string &net_ns) = 0;
256
257 /**
258 Set active network namespace specified by a name.
259
260 @param network_namespace the name of a network namespace to be set active
261
262 @return false on success, true on error
263 @note all opened descriptors used during function run are closed on error
264 */
265 virtual bool set_network_namespace(const std::string &network_namespace) = 0;
266
267 /**
268 Restore original network namespace used to be active before a new network
269 namespace has been set.
270
271 @return false on success, true on failure
272 */
274};
275
276/**
277 * @brief Base class for External Network Providers
278 *
279 * This virtual class will serve as base class for any external entity that
280 * whishes to provide network connections to XCom.
281 *
282 * It will have to implement the following methods:
283 * - start();
284 * - stop();
285 * - get_─ęd();
286 * - configure();
287 * - open_connection();
288 * - close_connection();
289 *
290 * If provides a lock free implementation of (set)\‍(get)_connection() for
291 * multithreaded usage.
292 *
293 *
294 */
296 public:
298 m_shared_connection.store(nullptr);
299 }
302
305
306 virtual ~Network_provider() {}
307
308 /**
309 * @brief Starts the network provider.
310 *
311 * Each implementation will place here any code that it needs to start a
312 * network provider.
313 *
314 * start() is synchronous. After start() succeeded, it is assumed that XCom
315 * is ready to receive new connections.
316 *
317 * @return a pair of <bool,int>
318 * bool indicates the success of the operation. false means success.
319 * int returns an error code.
320 */
321 virtual std::pair<bool, int> start() = 0;
322
323 /**
324 * @brief Stops the network provider.
325 *
326 * Each implementation will place here any code that it needs to stop a
327 * network provider.
328 *
329 * stop() is synchronous. After stop() succeeded, it is assumed that XCom
330 * shall not receive any new connection.
331 *
332 * @return a pair of <bool,int>
333 * bool indicates the success of the operation. false means success.
334 * int returns an error code.
335 */
336 virtual std::pair<bool, int> stop() = 0;
337
338 /**
339 * @brief Get the communication stack implemented by this provider
340 *
341 * Return a valid value withint the range of RunningProtocol enum.
342 *
343 * @return RunningProtocol valid value
344 */
346
347 /**
348 * @brief Configures a network provider
349 *
350 * @param params a sensible list of possibly configurable network parameters
351 *
352 * @return true in case of a successful configuration.
353 * @return false in case of a unsuccessful configuration.
354 */
355 virtual bool configure(const Network_configuration_parameters &params) = 0;
356
357 /**
358 * @brief Configures the active provider with all things needed to establish
359 * SSL connections
360 *
361 * @param params configuration parameters for SSL.
362 *
363 * @return true In case of success.
364 * @return false In case of failure.
365 */
367 const Network_configuration_parameters &params) = 0;
368
370
371 virtual std::function<void()> get_secure_connections_context_cleaner() {
372 std::function<void()> retval = []() {
373#ifndef XCOM_WITHOUT_OPENSSL
374#if OPENSSL_VERSION_NUMBER < 0x10100000L
375 ERR_remove_thread_state(nullptr);
376#endif /* OPENSSL_VERSION_NUMBER < 0x10100000L */
377#endif
378 };
379
380 return retval;
381 }
382
384
385 /**
386 * @brief Opens a new connection to another XCom endpoint served by the same
387 * Network provider.
388 *
389 * @param address address of the remote endpoint
390 * @param port port of the remote endpoint
391 * @param security_credentials security credentials to connect to the remote
392 * endpoint
393 * @param connection_timeout connection timeout
394 * @param log_level log level @see network_provider_dynamic_log_level for more
395 * information
396 * @return std::unique_ptr<Network_connection> an established connection.
397 * nullptr in case of failure.
398 */
399 virtual std::unique_ptr<Network_connection> open_connection(
400 const std::string &address, const unsigned short port,
401 const Network_security_credentials &security_credentials,
402 int connection_timeout = default_connection_timeout(),
405
406 /**
407 * @brief Closes an open connection to another XCom endpoint served by the
408 * same Network provider.
409 *
410 * @param connection an open and valid connection
411 * @return int an error code in case of error. 0, otherwise.
412 */
413 virtual int close_connection(const Network_connection &connection) = 0;
414
415 /**
416 * @brief Lock-free Set connection
417 *
418 * Sets a new connection received by this provider. It will be consumed
419 * internally by get_new_connection().
420 *
421 * @param connection a newly created connection.
422 */
424 Network_connection *null_desired_value;
425 do {
426 null_desired_value = nullptr;
427 } while (!m_shared_connection.compare_exchange_weak(null_desired_value,
428 connection));
429 }
430
431 /**
432 * @brief Get the new connection object
433 *
434 * @return Network_connection* a new connection coming from this network
435 * provider
436 */
439
441
442 if (new_connection != nullptr) m_shared_connection.store(nullptr);
443
444 return new_connection;
445 }
446
449
450 if (to_purge) {
451 close_connection(*to_purge);
452 }
453
454 delete to_purge;
455 }
456
457 static constexpr int default_connection_timeout() { return 3000; }
458
459 private:
460 std::atomic<Network_connection *> m_shared_connection;
461};
462
463#endif // NETWORK_PROVIDER_H
Kerberos Client Authentication nullptr
Definition: auth_kerberos_client_plugin.cc:251
This class is a helper to translate a Communication Stack to a string.
Definition: network_provider.h:119
static const char * to_string(enum_transport_protocol protocol)
Definition: network_provider.h:121
Class that provides Network Namespace services.
Definition: network_provider.h:242
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:244
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:295
void reset_new_connection()
Definition: network_provider.h:447
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:437
virtual std::function< void()> get_secure_connections_context_cleaner()
Definition: network_provider.h:371
virtual std::pair< bool, int > start()=0
Starts the network provider.
virtual std::pair< bool, int > stop()=0
Stops the network provider.
static constexpr int default_connection_timeout()
Definition: network_provider.h:457
Network_provider()
Definition: network_provider.h:297
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:460
virtual ~Network_provider()
Definition: network_provider.h:306
Network_provider & operator=(Network_provider &param)=delete
virtual enum_transport_protocol get_communication_stack() const =0
Get the communication stack implemented by this provider.
virtual void cleanup_secure_connections_context()=0
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:423
Network_provider(Network_provider &&param)
Definition: network_provider.h:300
Network_provider(Network_provider &param)=delete
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(), network_provider_dynamic_log_level log_level=network_provider_dynamic_log_level::PROVIDED)=0
Opens a new connection to another XCom endpoint served by the same Network provider.
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:308
static loglevel log_level(const Sql_condition *condition)
Definition: histogram.cc:1644
ssl_enum_fips_mode_options
Definition: network_provider.h:69
@ INVALID_SSL_FIPS_MODE
Definition: network_provider.h:70
@ FIPS_MODE_ON
Definition: network_provider.h:72
@ FIPS_MODE_OFF
Definition: network_provider.h:71
@ FIPS_MODE_STRICT
Definition: network_provider.h:73
@ LAST_SSL_FIPS_MODE
Definition: network_provider.h:74
enum_transport_protocol
Enum that describes the available XCom Communication Stacks.
Definition: network_provider.h:45
@ INVALID_PROTOCOL
Definition: network_provider.h:46
@ MYSQL_PROTOCOL
Definition: network_provider.h:48
@ XCOM_PROTOCOL
Definition: network_provider.h:47
ssl_enum_mode_options
Definition: network_provider.h:55
@ LAST_SSL_MODE
Definition: network_provider.h:62
@ SSL_VERIFY_CA
Definition: network_provider.h:60
@ SSL_VERIFY_IDENTITY
Definition: network_provider.h:61
@ SSL_REQUIRED
Definition: network_provider.h:59
@ SSL_PREFERRED
Definition: network_provider.h:58
@ INVALID_SSL_MODE
Definition: network_provider.h:56
@ SSL_DISABLED
Definition: network_provider.h:57
network_provider_dynamic_log_level
Dynamic log level enum values.
Definition: network_provider.h:103
static connection_descriptor * new_connection(int fd, SSL *ssl_fd)
Definition: node_connection.h:61
required string network_namespace
Definition: replication_asynchronous_connection_failover.proto:34
required uint64 port
Definition: replication_asynchronous_connection_failover.proto:33
Possible configuration parameters.
Definition: network_provider.h:191
struct ssl_parameters ssl_params
Definition: network_provider.h:194
struct tls_parameters tls_params
Definition: network_provider.h:195
unsigned short port
Definition: network_provider.h:192
Represents an open connection.
Definition: network_provider.h:201
Network_connection(int parameter_fd, SSL *parameter_ssl_fd, bool parameter_has_error)
Definition: network_provider.h:220
int fd
Definition: network_provider.h:232
Network_connection(int parameter_fd, void *parameter_ssl_fd)
Definition: network_provider.h:212
Network_connection(int parameter_fd)
Definition: network_provider.h:202
SSL * ssl_fd
Definition: network_provider.h:234
bool has_error
Definition: network_provider.h:236
Security credentials to establish a connection.
Definition: network_provider.h:134
std::string user
Definition: network_provider.h:135
bool use_ssl
Definition: network_provider.h:137
std::string pass
Definition: network_provider.h:136
Definition: network_provider.h:171
const char * server_key_file
Definition: network_provider.h:173
const char * client_key_file
Definition: network_provider.h:175
const char * ca_path
Definition: network_provider.h:178
const char * cipher
Definition: network_provider.h:181
const char * crl_file
Definition: network_provider.h:179
const char * client_cert_file
Definition: network_provider.h:176
const char * crl_path
Definition: network_provider.h:180
int ssl_mode
Definition: network_provider.h:172
const char * server_cert_file
Definition: network_provider.h:174
const char * ca_file
Definition: network_provider.h:177
Definition: network_provider.h:183
const char * tls_ciphersuites
Definition: network_provider.h:185
const char * tls_version
Definition: network_provider.h:184