MySQL 9.0.0
Source Code Documentation
tls_context.h
Go to the documentation of this file.
1/*
2 Copyright (c) 2018, 2024, Oracle and/or its affiliates.
3
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License, version 2.0,
6 as published by the Free Software Foundation.
7
8 This program is designed to work with certain software (including
9 but not limited to OpenSSL) that is licensed under separate terms,
10 as designated in a particular file or component or in included license
11 documentation. The authors of MySQL hereby grant you an additional
12 permission to link the program and your derivative works with the
13 separately licensed software that they have either included with
14 the program or referenced in the documentation.
15
16 This program is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 GNU General Public License for more details.
20
21 You should have received a copy of the GNU General Public License
22 along with this program; if not, write to the Free Software
23 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
24*/
25
26#ifndef MYSQL_HARNESS_TLS_CONTEXT_INCLUDED
27#define MYSQL_HARNESS_TLS_CONTEXT_INCLUDED
28
30
31#include <memory> // unique_ptr
32#include <string>
33#include <system_error>
34#include <vector>
35
36#ifdef _WIN32
37// include windows headers before openssl/ssl.h
38#include <windows.h>
39#include <winsock2.h>
40#include <ws2tcpip.h>
41#endif
42
43#include <openssl/ssl.h> // SSL_METHOD
44
46
47/**
48 * TLS Versions.
49 *
50 * used for set_min_version.
51 *
52 * @note for now own TLS1.2 is used, but others may be added later.
53 */
55
56/**
57 * Verification of Cerifiticates.
58 *
59 * NONE no certificate is verified
60 * PEER verify the cert of the peer
61 */
62enum class TlsVerify { NONE, PEER };
63
65 public:
72};
73
74/**
75 * wraps SSL_CTX.
76 *
77 * TODO:
78 * - SSL_CTX_set_session_cache_mode()
79 * - SSL_CTX_set_alpn_select_cb()
80 * - SSL_CTX_set_tlsext_ticket_key_cb()
81 * - SSL_CTX_set_tlsext_servername_callback() for SNI
82 * - SSL_CTX_set_cert_verify_callback() vs. SSL_CTX_set_verify()
83 *
84 */
86 public:
87 /**
88 * if TLS context allows to change elliptic curves list.
89 *
90 * @returns if curves_list() is supported.
91 * @retval false curves_list() is not supported
92 */
93 static constexpr bool has_set_curves_list() {
94 // 1.0.2 and later
95 return OPENSSL_VERSION_NUMBER >= 0x1000200f;
96 }
97
98 /**
99 * if TLS context allows setting cipher-suites (TLSv1.3 and later).
100 *
101 * @returns if cipher_suites() is supported.
102 * @retval false cipher_suites() is not supported
103 */
104 static constexpr bool has_set_cipher_suites() {
105 // 1.1.1 and later
106 return OPENSSL_VERSION_NUMBER >= 0x1010100f;
107 }
108
109 /**
110 * construct a TlsContext based on the SSL_METHODs provided by openssl.
111 */
112 explicit TlsContext(const SSL_METHOD *method);
113
114 /**
115 * set CA file and CA directory.
116 *
117 * Search-order:
118 *
119 * 1. ca_file (if not empty)
120 * 2. all PEMs in ca_dir (if not empty)
121 *
122 * @see SSL_CTX_load_verify_locations
123 *
124 * @param ca_file path to a PEM file containing a certificate of a CA, ignored
125 * if empty()
126 * @param ca_path path to a directory of PEM files containing certifications,
127 * ignored if empty() of CAs
128 *
129 * @returns success
130 * @retval false if both ca_file and ca_path are empty
131 */
132 stdx::expected<void, std::error_code> ssl_ca(const std::string &ca_file,
133 const std::string &ca_path);
134
135 /**
136 * set CRL file and CRL directory.
137 *
138 * Search-order:
139 *
140 * 1. crl_file (if not empty)
141 * 2. all PEMs in crl_dir (if not empty)
142 *
143 * @see X509_STORE_load_locations
144 *
145 * @param crl_file path to a PEM file containing CRL file,
146 * ignored if empty()
147 * @param crl_path path to a directory of PEM files containing CRL files,
148 * ignored if empty()
149 *
150 * @returns success
151 * @retval false if both ca_file and ca_path are empty
152 */
153 stdx::expected<void, std::error_code> crl(const std::string &crl_file,
154 const std::string &crl_path);
155
156 /**
157 * get non-owning pointer to SSL_CTX.
158 */
159 SSL_CTX *get() const { return ssl_ctx_.get(); }
160
161 /**
162 * set the supported TLS version range.
163 */
164 stdx::expected<void, std::error_code> version_range(TlsVersion min_version,
165 TlsVersion max_version);
166
167 /**
168 * get the min TLS version.
169 */
170 TlsVersion min_version() const;
171
172 /**
173 * init elliptic curves for DH ciphers for Perfect Forward Security.
174 *
175 * @note uses P-512, P-384 or P-256
176 * @see RFC 5480
177 * @see has_curves()
178 *
179 * @param curves colon-separated names of curves
180 * @throws TlsError
181 * @throws std::invalid_argument if API isn't supported
182 * @see has_set_curves_list()
183 */
184 stdx::expected<void, std::error_code> curves_list(const std::string &curves);
185
186 /**
187 * get current cipher-list.
188 */
189 std::vector<std::string> cipher_list() const;
190
191 using InfoCallback = void (*)(const SSL *, int, int);
192
193 /**
194 * set info callback.
195 */
196 void info_callback(InfoCallback);
197
198 /**
199 * get info callback
200 */
201 InfoCallback info_callback() const;
202
203 /**
204 * get security_level.
205 */
206 int security_level() const;
207
208 /**
209 * get session reuse cache hits number
210 */
211 long session_cache_hits() const;
212
213 /**
214 * load key and cert.
215 *
216 * cerifiticate is verified against the key
217 *
218 * @param private_key_file filename of a PEM file containing a key
219 * @param cert_chain_file filename of a PEM file containing a certificate
220 */
222 const std::string &private_key_file, const std::string &cert_chain_file);
223
224 protected:
225 std::unique_ptr<SSL_CTX, decltype(&SSL_CTX_free)> ssl_ctx_{nullptr,
226 &SSL_CTX_free};
227};
228
229#endif
wraps SSL_CTX.
Definition: tls_context.h:85
static constexpr bool has_set_curves_list()
if TLS context allows to change elliptic curves list.
Definition: tls_context.h:93
SSL_CTX * get() const
get non-owning pointer to SSL_CTX.
Definition: tls_context.h:159
static constexpr bool has_set_cipher_suites()
if TLS context allows setting cipher-suites (TLSv1.3 and later).
Definition: tls_context.h:104
void(*)(const SSL *, int, int) InfoCallback
Definition: tls_context.h:191
Definition: tls_context.h:64
TlsLibraryContext(TlsLibraryContext &&)=delete
TlsLibraryContext & operator=(const TlsLibraryContext &)=delete
TlsLibraryContext & operator=(TlsLibraryContext &&)=delete
TlsLibraryContext(const TlsLibraryContext &)=delete
Definition: expected.h:284
std::conditional_t< !std::is_array< T >::value, std::unique_ptr< T, detail::Deleter< T > >, std::conditional_t< detail::is_unbounded_array_v< T >, std::unique_ptr< T, detail::Array_deleter< std::remove_extent_t< T > > >, void > > unique_ptr
The following is a common type that is returned by all the ut::make_unique (non-aligned) specializati...
Definition: ut0new.h:2439
int security_level(void)
Definition: sql_authentication.cc:1287
TlsVerify
Verification of Cerifiticates.
Definition: tls_context.h:62
TlsVersion
TLS Versions.
Definition: tls_context.h:54
#define HARNESS_TLS_EXPORT
Definition: tls_export.h:15