MySQL 8.3.0
Source Code Documentation
network_provider.h
Go to the documentation of this file.
1/* Copyright (c) 2015, 2023, 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/err.h>
32#include <openssl/ssl.h>
33#endif
34
35#include <atomic>
36#include <functional>
37#include <memory>
38#include <string>
39#include <vector>
40
41/**
42 * @brief Enum that describes the available XCom Communication Stacks
43 */
48};
49
50/*
51 Possible operation modes as explained further down. If you
52 want to add a new mode, do it before the LAST_SSL_MODE.
53*/
62};
63
64/*
65 Possible operation fips modes as explained further down. If you
66 want to add a new ssl fips mode, do it before the LAST_SSL_FIPS_MODE.
67*/
74};
75
76/**
77 * @brief This class is a helper to translate a Communication Stack to a
78 string
79 *
80 */
82 public:
83 static const char *to_string(enum_transport_protocol protocol) {
84 static std::vector<const char *> m_running_protocol_to_string = {"XCom",
85 "MySQL"};
86
87 return protocol > INVALID_PROTOCOL && protocol <= MYSQL_PROTOCOL
88 ? m_running_protocol_to_string[protocol]
89 : "Invalid Protocol";
90 }
91};
92
93/**
94 * @brief Security credentials to establish a connection
95 */
97 std::string user;
98 std::string pass;
99 bool use_ssl;
100};
101
102/*
103 Set the necessary SSL parameters before initialization.
104
105 server_key_file - Path of file that contains the server's X509 key in PEM
106 format.
107 server_cert_file - Path of file that contains the server's X509 certificate
108 in PEM format.
109 client_key_file - Path of file that contains the client's X509 key in PEM
110 format.
111 client_cert_file - Path of file that contains the client's X509 certificate
112 in PEM format.
113 ca_file - Path of file that contains list of trusted SSL CAs.
114 ca_path - Path of directory that contains trusted SSL CA
115 certificates in PEM format.
116 crl_file - Path of file that contains certificate revocation lists.
117 crl_path - Path of directory that contains certificate revocation
118 list files.
119 cipher - List of permitted ciphers to use for connection
120 encryption.
121 tls_version - Protocols permitted for secure connections.
122 tls_ciphersuites - List of permitted ciphersuites to use for TLS 1.3
123 connection encryption.
124
125 Note that only the server_key_file/server_cert_file and the client_key_file/
126 client_cert_file are required and the rest of the pointers can be NULL.
127 If the key is provided along with the certificate, either the key file or
128 the other can be omitted.
129
130 The caller can free the parameters after the SSL is started
131 if this is necessary.
132*/
135 const char *server_key_file;
136 const char *server_cert_file;
137 const char *client_key_file;
138 const char *client_cert_file;
139 const char *ca_file;
140 const char *ca_path;
141 const char *crl_file;
142 const char *crl_path;
143 const char *cipher;
144};
146 const char *tls_version;
147 const char *tls_ciphersuites;
148};
149
150/**
151 * @brief Possible configuration parameters
152 */
154 unsigned short port;
155
158};
159
160/**
161 * @brief Represents an open connection.
162 */
164 Network_connection(int parameter_fd)
165 : fd(parameter_fd)
166#ifndef XCOM_WITHOUT_OPENSSL
167 ,
169#endif
170 ,
171 has_error(false) {
172 }
173
174 Network_connection(int parameter_fd
175#ifndef XCOM_WITHOUT_OPENSSL
176 ,
177 SSL *parameter_ssl_fd
178#endif
179 )
180 : fd(parameter_fd)
181#ifndef XCOM_WITHOUT_OPENSSL
182 ,
183 ssl_fd(parameter_ssl_fd)
184#endif
185 ,
186 has_error(false) {
187 }
188
189 Network_connection(int parameter_fd
190#ifndef XCOM_WITHOUT_OPENSSL
191 ,
192 SSL *parameter_ssl_fd
193#endif
194 ,
195 bool parameter_has_error)
196 : fd(parameter_fd)
197#ifndef XCOM_WITHOUT_OPENSSL
198 ,
199 ssl_fd(parameter_ssl_fd)
200#endif
201 ,
202 has_error(parameter_has_error) {
203 }
204
205 int fd;
206#ifndef XCOM_WITHOUT_OPENSSL
207 SSL *ssl_fd;
208#endif
210};
211
212/**
213 * @brief Class that provides Network Namespace services
214 */
216 public:
218
219 /**
220 Method to get the network namespace configured for a channel
221
222 @param[out] net_ns The network namespace to extract
223
224 @return the operation status
225 @retval false OK
226 @retval true Error, channel not found
227*/
228 virtual int channel_get_network_namespace(std::string &net_ns) = 0;
229
230 /**
231 Set active network namespace specified by a name.
232
233 @param network_namespace the name of a network namespace to be set active
234
235 @return false on success, true on error
236 @note all opened descriptors used during function run are closed on error
237 */
238 virtual bool set_network_namespace(const std::string &network_namespace) = 0;
239
240 /**
241 Restore original network namespace used to be active before a new network
242 namespace has been set.
243
244 @return false on success, true on failure
245 */
247};
248
249/**
250 * @brief Base class for External Network Providers
251 *
252 * This virtual class will serve as base class for any external entity that
253 * whishes to provide network connections to XCom.
254 *
255 * It will have to implement the following methods:
256 * - start();
257 * - stop();
258 * - get_─ęd();
259 * - configure();
260 * - open_connection();
261 * - close_connection();
262 *
263 * If provides a lock free implementation of (set)\‍(get)_connection() for
264 * multithreaded usage.
265 *
266 *
267 */
269 public:
271 m_shared_connection.store(nullptr);
272 }
275
278
279 virtual ~Network_provider() {}
280
281 /**
282 * @brief Starts the network provider.
283 *
284 * Each implementation will place here any code that it needs to start a
285 * network provider.
286 *
287 * start() is synchronous. After start() succeeded, it is assumed that XCom
288 * is ready to receive new connections.
289 *
290 * @return a pair of <bool,int>
291 * bool indicates the success of the operation. false means success.
292 * int returns an error code.
293 */
294 virtual std::pair<bool, int> start() = 0;
295
296 /**
297 * @brief Stops the network provider.
298 *
299 * Each implementation will place here any code that it needs to stop a
300 * network provider.
301 *
302 * stop() is synchronous. After stop() succeeded, it is assumed that XCom
303 * shall not receive any new connection.
304 *
305 * @return a pair of <bool,int>
306 * bool indicates the success of the operation. false means success.
307 * int returns an error code.
308 */
309 virtual std::pair<bool, int> stop() = 0;
310
311 /**
312 * @brief Get the communication stack implemented by this provider
313 *
314 * Return a valid value withint the range of RunningProtocol enum.
315 *
316 * @return RunningProtocol valid value
317 */
319
320 /**
321 * @brief Configures a network provider
322 *
323 * @param params a sensible list of possibly configurable network parameters
324 *
325 * @return true in case of a successful configuration.
326 * @return false in case of a unsuccessful configuration.
327 */
328 virtual bool configure(const Network_configuration_parameters &params) = 0;
329
330 /**
331 * @brief Configures the active provider with all things needed to establish
332 * SSL connections
333 *
334 * @param params configuration parameters for SSL.
335 *
336 * @return true In case of success.
337 * @return false In case of failure.
338 */
340 const Network_configuration_parameters &params) = 0;
341
343
344 virtual std::function<void()> get_secure_connections_context_cleaner() {
345 std::function<void()> retval = []() {
346#if OPENSSL_VERSION_NUMBER < 0x10100000L
347 ERR_remove_thread_state(nullptr);
348#endif /* OPENSSL_VERSION_NUMBER < 0x10100000L */
349 };
350
351 return retval;
352 }
353
355
356 /**
357 * @brief Opens a new connection to another XCom endpoint served by the same
358 * Network provider.
359 *
360 * @param address address of the remote endpoint
361 * @param port port of the remote endpoint
362 * @param security_credentials security credentials to connect to the remote
363 * endpoint
364 * @param connection_timeout connection timeout
365 * @return std::unique_ptr<Network_connection> an established connection.
366 * nullptr in case of failure.
367 */
368 virtual std::unique_ptr<Network_connection> open_connection(
369 const std::string &address, const unsigned short port,
370 const Network_security_credentials &security_credentials,
371 int connection_timeout = default_connection_timeout()) = 0;
372
373 /**
374 * @brief Closes an open connection to another XCom endpoint served by the
375 * same Network provider.
376 *
377 * @param connection an open and valid connection
378 * @return int an error code in case of error. 0, otherwise.
379 */
380 virtual int close_connection(const Network_connection &connection) = 0;
381
382 /**
383 * @brief Lock-free Set connection
384 *
385 * Sets a new connection received by this provider. It will be consumed
386 * internally by get_new_connection().
387 *
388 * @param connection a newly created connection.
389 */
391 Network_connection *null_desired_value;
392 do {
393 null_desired_value = nullptr;
394 } while (!m_shared_connection.compare_exchange_weak(null_desired_value,
395 connection));
396 }
397
398 /**
399 * @brief Get the new connection object
400 *
401 * @return Network_connection* a new connection coming from this network
402 * provider
403 */
406
408
409 if (new_connection != nullptr) m_shared_connection.store(nullptr);
410
411 return new_connection;
412 }
413
416
417 if (to_purge) {
418 close_connection(*to_purge);
419 }
420
421 delete to_purge;
422 }
423
424 static constexpr int default_connection_timeout() { return 3000; }
425
426 private:
427 std::atomic<Network_connection *> m_shared_connection;
428};
429
430#endif // NETWORK_PROVIDER_H
Kerberos Client Authentication nullptr
Definition: auth_kerberos_client_plugin.cc:250
This class is a helper to translate a Communication Stack to a string.
Definition: network_provider.h:81
static const char * to_string(enum_transport_protocol protocol)
Definition: network_provider.h:83
Class that provides Network Namespace services.
Definition: network_provider.h:215
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:217
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:268
void reset_new_connection()
Definition: network_provider.h:414
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:404
virtual std::function< void()> get_secure_connections_context_cleaner()
Definition: network_provider.h:344
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:424
Network_provider()
Definition: network_provider.h:270
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:427
virtual ~Network_provider()
Definition: network_provider.h:279
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:390
Network_provider(Network_provider &&param)
Definition: network_provider.h:273
Network_provider(Network_provider &param)=delete
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:68
@ INVALID_SSL_FIPS_MODE
Definition: network_provider.h:69
@ FIPS_MODE_ON
Definition: network_provider.h:71
@ FIPS_MODE_OFF
Definition: network_provider.h:70
@ FIPS_MODE_STRICT
Definition: network_provider.h:72
@ LAST_SSL_FIPS_MODE
Definition: network_provider.h:73
enum_transport_protocol
Enum that describes the available XCom Communication Stacks.
Definition: network_provider.h:44
@ INVALID_PROTOCOL
Definition: network_provider.h:45
@ MYSQL_PROTOCOL
Definition: network_provider.h:47
@ XCOM_PROTOCOL
Definition: network_provider.h:46
ssl_enum_mode_options
Definition: network_provider.h:54
@ LAST_SSL_MODE
Definition: network_provider.h:61
@ SSL_VERIFY_CA
Definition: network_provider.h:59
@ SSL_VERIFY_IDENTITY
Definition: network_provider.h:60
@ SSL_REQUIRED
Definition: network_provider.h:58
@ SSL_PREFERRED
Definition: network_provider.h:57
@ INVALID_SSL_MODE
Definition: network_provider.h:55
@ SSL_DISABLED
Definition: network_provider.h:56
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:153
struct ssl_parameters ssl_params
Definition: network_provider.h:156
struct tls_parameters tls_params
Definition: network_provider.h:157
unsigned short port
Definition: network_provider.h:154
Represents an open connection.
Definition: network_provider.h:163
Network_connection(int parameter_fd, SSL *parameter_ssl_fd, bool parameter_has_error)
Definition: network_provider.h:189
Network_connection(int parameter_fd, SSL *parameter_ssl_fd)
Definition: network_provider.h:174
int fd
Definition: network_provider.h:205
Network_connection(int parameter_fd)
Definition: network_provider.h:164
SSL * ssl_fd
Definition: network_provider.h:207
bool has_error
Definition: network_provider.h:209
Security credentials to establish a connection.
Definition: network_provider.h:96
std::string user
Definition: network_provider.h:97
bool use_ssl
Definition: network_provider.h:99
std::string pass
Definition: network_provider.h:98
Definition: network_provider.h:133
const char * server_key_file
Definition: network_provider.h:135
const char * client_key_file
Definition: network_provider.h:137
const char * ca_path
Definition: network_provider.h:140
const char * cipher
Definition: network_provider.h:143
const char * crl_file
Definition: network_provider.h:141
const char * client_cert_file
Definition: network_provider.h:138
const char * crl_path
Definition: network_provider.h:142
int ssl_mode
Definition: network_provider.h:134
const char * server_cert_file
Definition: network_provider.h:136
const char * ca_file
Definition: network_provider.h:139
Definition: network_provider.h:145
const char * tls_ciphersuites
Definition: network_provider.h:147
const char * tls_version
Definition: network_provider.h:146