]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | // |
2 | // ssl/context.hpp | |
3 | // ~~~~~~~~~~~~~~~ | |
4 | // | |
5 | // Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com) | |
6 | // | |
7 | // Distributed under the Boost Software License, Version 1.0. (See accompanying | |
8 | // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
9 | // | |
10 | ||
11 | #ifndef BOOST_ASIO_SSL_CONTEXT_HPP | |
12 | #define BOOST_ASIO_SSL_CONTEXT_HPP | |
13 | ||
14 | #if defined(_MSC_VER) && (_MSC_VER >= 1200) | |
15 | # pragma once | |
16 | #endif // defined(_MSC_VER) && (_MSC_VER >= 1200) | |
17 | ||
18 | #include <boost/asio/detail/config.hpp> | |
19 | ||
20 | #if defined(BOOST_ASIO_ENABLE_OLD_SSL) | |
21 | # include <boost/asio/ssl/basic_context.hpp> | |
22 | # include <boost/asio/ssl/context_service.hpp> | |
23 | #else // defined(BOOST_ASIO_ENABLE_OLD_SSL) | |
24 | # include <string> | |
25 | # include <boost/asio/buffer.hpp> | |
26 | # include <boost/asio/io_service.hpp> | |
27 | # include <boost/asio/ssl/context_base.hpp> | |
28 | # include <boost/asio/ssl/detail/openssl_types.hpp> | |
29 | # include <boost/asio/ssl/detail/openssl_init.hpp> | |
30 | # include <boost/asio/ssl/detail/password_callback.hpp> | |
31 | # include <boost/asio/ssl/detail/verify_callback.hpp> | |
32 | # include <boost/asio/ssl/verify_mode.hpp> | |
33 | #endif // defined(BOOST_ASIO_ENABLE_OLD_SSL) | |
34 | ||
35 | #include <boost/asio/detail/push_options.hpp> | |
36 | ||
37 | namespace boost { | |
38 | namespace asio { | |
39 | namespace ssl { | |
40 | ||
41 | #if defined(BOOST_ASIO_ENABLE_OLD_SSL) | |
42 | ||
43 | /// Typedef for the typical usage of context. | |
44 | typedef basic_context<context_service> context; | |
45 | ||
46 | #else // defined(BOOST_ASIO_ENABLE_OLD_SSL) | |
47 | ||
48 | class context | |
49 | : public context_base, | |
50 | private noncopyable | |
51 | { | |
52 | public: | |
53 | /// The native handle type of the SSL context. | |
54 | typedef SSL_CTX* native_handle_type; | |
55 | ||
56 | /// (Deprecated: Use native_handle_type.) The native type of the SSL context. | |
57 | typedef SSL_CTX* impl_type; | |
58 | ||
59 | /// Constructor. | |
60 | BOOST_ASIO_DECL explicit context(method m); | |
61 | ||
62 | /// Deprecated constructor taking a reference to an io_service object. | |
63 | BOOST_ASIO_DECL context(boost::asio::io_service&, method m); | |
64 | ||
65 | #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION) | |
66 | /// Move-construct a context from another. | |
67 | /** | |
68 | * This constructor moves an SSL context from one object to another. | |
69 | * | |
70 | * @param other The other context object from which the move will occur. | |
71 | * | |
72 | * @note Following the move, the following operations only are valid for the | |
73 | * moved-from object: | |
74 | * @li Destruction. | |
75 | * @li As a target for move-assignment. | |
76 | */ | |
77 | BOOST_ASIO_DECL context(context&& other); | |
78 | ||
79 | /// Move-assign a context from another. | |
80 | /** | |
81 | * This assignment operator moves an SSL context from one object to another. | |
82 | * | |
83 | * @param other The other context object from which the move will occur. | |
84 | * | |
85 | * @note Following the move, the following operations only are valid for the | |
86 | * moved-from object: | |
87 | * @li Destruction. | |
88 | * @li As a target for move-assignment. | |
89 | */ | |
90 | BOOST_ASIO_DECL context& operator=(context&& other); | |
91 | #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION) | |
92 | ||
93 | /// Destructor. | |
94 | BOOST_ASIO_DECL ~context(); | |
95 | ||
96 | /// Get the underlying implementation in the native type. | |
97 | /** | |
98 | * This function may be used to obtain the underlying implementation of the | |
99 | * context. This is intended to allow access to context functionality that is | |
100 | * not otherwise provided. | |
101 | */ | |
102 | BOOST_ASIO_DECL native_handle_type native_handle(); | |
103 | ||
104 | /// (Deprecated: Use native_handle().) Get the underlying implementation in | |
105 | /// the native type. | |
106 | /** | |
107 | * This function may be used to obtain the underlying implementation of the | |
108 | * context. This is intended to allow access to context functionality that is | |
109 | * not otherwise provided. | |
110 | */ | |
111 | BOOST_ASIO_DECL impl_type impl(); | |
112 | ||
113 | /// Clear options on the context. | |
114 | /** | |
115 | * This function may be used to configure the SSL options used by the context. | |
116 | * | |
117 | * @param o A bitmask of options. The available option values are defined in | |
118 | * the context_base class. The specified options, if currently enabled on the | |
119 | * context, are cleared. | |
120 | * | |
121 | * @throws boost::system::system_error Thrown on failure. | |
122 | * | |
123 | * @note Calls @c SSL_CTX_clear_options. | |
124 | */ | |
125 | BOOST_ASIO_DECL void clear_options(options o); | |
126 | ||
127 | /// Clear options on the context. | |
128 | /** | |
129 | * This function may be used to configure the SSL options used by the context. | |
130 | * | |
131 | * @param o A bitmask of options. The available option values are defined in | |
132 | * the context_base class. The specified options, if currently enabled on the | |
133 | * context, are cleared. | |
134 | * | |
135 | * @param ec Set to indicate what error occurred, if any. | |
136 | * | |
137 | * @note Calls @c SSL_CTX_clear_options. | |
138 | */ | |
139 | BOOST_ASIO_DECL boost::system::error_code clear_options(options o, | |
140 | boost::system::error_code& ec); | |
141 | ||
142 | /// Set options on the context. | |
143 | /** | |
144 | * This function may be used to configure the SSL options used by the context. | |
145 | * | |
146 | * @param o A bitmask of options. The available option values are defined in | |
147 | * the context_base class. The options are bitwise-ored with any existing | |
148 | * value for the options. | |
149 | * | |
150 | * @throws boost::system::system_error Thrown on failure. | |
151 | * | |
152 | * @note Calls @c SSL_CTX_set_options. | |
153 | */ | |
154 | BOOST_ASIO_DECL void set_options(options o); | |
155 | ||
156 | /// Set options on the context. | |
157 | /** | |
158 | * This function may be used to configure the SSL options used by the context. | |
159 | * | |
160 | * @param o A bitmask of options. The available option values are defined in | |
161 | * the context_base class. The options are bitwise-ored with any existing | |
162 | * value for the options. | |
163 | * | |
164 | * @param ec Set to indicate what error occurred, if any. | |
165 | * | |
166 | * @note Calls @c SSL_CTX_set_options. | |
167 | */ | |
168 | BOOST_ASIO_DECL boost::system::error_code set_options(options o, | |
169 | boost::system::error_code& ec); | |
170 | ||
171 | /// Set the peer verification mode. | |
172 | /** | |
173 | * This function may be used to configure the peer verification mode used by | |
174 | * the context. | |
175 | * | |
176 | * @param v A bitmask of peer verification modes. See @ref verify_mode for | |
177 | * available values. | |
178 | * | |
179 | * @throws boost::system::system_error Thrown on failure. | |
180 | * | |
181 | * @note Calls @c SSL_CTX_set_verify. | |
182 | */ | |
183 | BOOST_ASIO_DECL void set_verify_mode(verify_mode v); | |
184 | ||
185 | /// Set the peer verification mode. | |
186 | /** | |
187 | * This function may be used to configure the peer verification mode used by | |
188 | * the context. | |
189 | * | |
190 | * @param v A bitmask of peer verification modes. See @ref verify_mode for | |
191 | * available values. | |
192 | * | |
193 | * @param ec Set to indicate what error occurred, if any. | |
194 | * | |
195 | * @note Calls @c SSL_CTX_set_verify. | |
196 | */ | |
197 | BOOST_ASIO_DECL boost::system::error_code set_verify_mode( | |
198 | verify_mode v, boost::system::error_code& ec); | |
199 | ||
200 | /// Set the peer verification depth. | |
201 | /** | |
202 | * This function may be used to configure the maximum verification depth | |
203 | * allowed by the context. | |
204 | * | |
205 | * @param depth Maximum depth for the certificate chain verification that | |
206 | * shall be allowed. | |
207 | * | |
208 | * @throws boost::system::system_error Thrown on failure. | |
209 | * | |
210 | * @note Calls @c SSL_CTX_set_verify_depth. | |
211 | */ | |
212 | BOOST_ASIO_DECL void set_verify_depth(int depth); | |
213 | ||
214 | /// Set the peer verification depth. | |
215 | /** | |
216 | * This function may be used to configure the maximum verification depth | |
217 | * allowed by the context. | |
218 | * | |
219 | * @param depth Maximum depth for the certificate chain verification that | |
220 | * shall be allowed. | |
221 | * | |
222 | * @param ec Set to indicate what error occurred, if any. | |
223 | * | |
224 | * @note Calls @c SSL_CTX_set_verify_depth. | |
225 | */ | |
226 | BOOST_ASIO_DECL boost::system::error_code set_verify_depth( | |
227 | int depth, boost::system::error_code& ec); | |
228 | ||
229 | /// Set the callback used to verify peer certificates. | |
230 | /** | |
231 | * This function is used to specify a callback function that will be called | |
232 | * by the implementation when it needs to verify a peer certificate. | |
233 | * | |
234 | * @param callback The function object to be used for verifying a certificate. | |
235 | * The function signature of the handler must be: | |
236 | * @code bool verify_callback( | |
237 | * bool preverified, // True if the certificate passed pre-verification. | |
238 | * verify_context& ctx // The peer certificate and other context. | |
239 | * ); @endcode | |
240 | * The return value of the callback is true if the certificate has passed | |
241 | * verification, false otherwise. | |
242 | * | |
243 | * @throws boost::system::system_error Thrown on failure. | |
244 | * | |
245 | * @note Calls @c SSL_CTX_set_verify. | |
246 | */ | |
247 | template <typename VerifyCallback> | |
248 | void set_verify_callback(VerifyCallback callback); | |
249 | ||
250 | /// Set the callback used to verify peer certificates. | |
251 | /** | |
252 | * This function is used to specify a callback function that will be called | |
253 | * by the implementation when it needs to verify a peer certificate. | |
254 | * | |
255 | * @param callback The function object to be used for verifying a certificate. | |
256 | * The function signature of the handler must be: | |
257 | * @code bool verify_callback( | |
258 | * bool preverified, // True if the certificate passed pre-verification. | |
259 | * verify_context& ctx // The peer certificate and other context. | |
260 | * ); @endcode | |
261 | * The return value of the callback is true if the certificate has passed | |
262 | * verification, false otherwise. | |
263 | * | |
264 | * @param ec Set to indicate what error occurred, if any. | |
265 | * | |
266 | * @note Calls @c SSL_CTX_set_verify. | |
267 | */ | |
268 | template <typename VerifyCallback> | |
269 | boost::system::error_code set_verify_callback(VerifyCallback callback, | |
270 | boost::system::error_code& ec); | |
271 | ||
272 | /// Load a certification authority file for performing verification. | |
273 | /** | |
274 | * This function is used to load one or more trusted certification authorities | |
275 | * from a file. | |
276 | * | |
277 | * @param filename The name of a file containing certification authority | |
278 | * certificates in PEM format. | |
279 | * | |
280 | * @throws boost::system::system_error Thrown on failure. | |
281 | * | |
282 | * @note Calls @c SSL_CTX_load_verify_locations. | |
283 | */ | |
284 | BOOST_ASIO_DECL void load_verify_file(const std::string& filename); | |
285 | ||
286 | /// Load a certification authority file for performing verification. | |
287 | /** | |
288 | * This function is used to load the certificates for one or more trusted | |
289 | * certification authorities from a file. | |
290 | * | |
291 | * @param filename The name of a file containing certification authority | |
292 | * certificates in PEM format. | |
293 | * | |
294 | * @param ec Set to indicate what error occurred, if any. | |
295 | * | |
296 | * @note Calls @c SSL_CTX_load_verify_locations. | |
297 | */ | |
298 | BOOST_ASIO_DECL boost::system::error_code load_verify_file( | |
299 | const std::string& filename, boost::system::error_code& ec); | |
300 | ||
301 | /// Add certification authority for performing verification. | |
302 | /** | |
303 | * This function is used to add one trusted certification authority | |
304 | * from a memory buffer. | |
305 | * | |
306 | * @param ca The buffer containing the certification authority certificate. | |
307 | * The certificate must use the PEM format. | |
308 | * | |
309 | * @throws boost::system::system_error Thrown on failure. | |
310 | * | |
311 | * @note Calls @c SSL_CTX_get_cert_store and @c X509_STORE_add_cert. | |
312 | */ | |
313 | BOOST_ASIO_DECL void add_certificate_authority(const const_buffer& ca); | |
314 | ||
315 | /// Add certification authority for performing verification. | |
316 | /** | |
317 | * This function is used to add one trusted certification authority | |
318 | * from a memory buffer. | |
319 | * | |
320 | * @param ca The buffer containing the certification authority certificate. | |
321 | * The certificate must use the PEM format. | |
322 | * | |
323 | * @param ec Set to indicate what error occurred, if any. | |
324 | * | |
325 | * @note Calls @c SSL_CTX_get_cert_store and @c X509_STORE_add_cert. | |
326 | */ | |
327 | BOOST_ASIO_DECL boost::system::error_code add_certificate_authority( | |
328 | const const_buffer& ca, boost::system::error_code& ec); | |
329 | ||
330 | /// Configures the context to use the default directories for finding | |
331 | /// certification authority certificates. | |
332 | /** | |
333 | * This function specifies that the context should use the default, | |
334 | * system-dependent directories for locating certification authority | |
335 | * certificates. | |
336 | * | |
337 | * @throws boost::system::system_error Thrown on failure. | |
338 | * | |
339 | * @note Calls @c SSL_CTX_set_default_verify_paths. | |
340 | */ | |
341 | BOOST_ASIO_DECL void set_default_verify_paths(); | |
342 | ||
343 | /// Configures the context to use the default directories for finding | |
344 | /// certification authority certificates. | |
345 | /** | |
346 | * This function specifies that the context should use the default, | |
347 | * system-dependent directories for locating certification authority | |
348 | * certificates. | |
349 | * | |
350 | * @param ec Set to indicate what error occurred, if any. | |
351 | * | |
352 | * @note Calls @c SSL_CTX_set_default_verify_paths. | |
353 | */ | |
354 | BOOST_ASIO_DECL boost::system::error_code set_default_verify_paths( | |
355 | boost::system::error_code& ec); | |
356 | ||
357 | /// Add a directory containing certificate authority files to be used for | |
358 | /// performing verification. | |
359 | /** | |
360 | * This function is used to specify the name of a directory containing | |
361 | * certification authority certificates. Each file in the directory must | |
362 | * contain a single certificate. The files must be named using the subject | |
363 | * name's hash and an extension of ".0". | |
364 | * | |
365 | * @param path The name of a directory containing the certificates. | |
366 | * | |
367 | * @throws boost::system::system_error Thrown on failure. | |
368 | * | |
369 | * @note Calls @c SSL_CTX_load_verify_locations. | |
370 | */ | |
371 | BOOST_ASIO_DECL void add_verify_path(const std::string& path); | |
372 | ||
373 | /// Add a directory containing certificate authority files to be used for | |
374 | /// performing verification. | |
375 | /** | |
376 | * This function is used to specify the name of a directory containing | |
377 | * certification authority certificates. Each file in the directory must | |
378 | * contain a single certificate. The files must be named using the subject | |
379 | * name's hash and an extension of ".0". | |
380 | * | |
381 | * @param path The name of a directory containing the certificates. | |
382 | * | |
383 | * @param ec Set to indicate what error occurred, if any. | |
384 | * | |
385 | * @note Calls @c SSL_CTX_load_verify_locations. | |
386 | */ | |
387 | BOOST_ASIO_DECL boost::system::error_code add_verify_path( | |
388 | const std::string& path, boost::system::error_code& ec); | |
389 | ||
390 | /// Use a certificate from a memory buffer. | |
391 | /** | |
392 | * This function is used to load a certificate into the context from a buffer. | |
393 | * | |
394 | * @param certificate The buffer containing the certificate. | |
395 | * | |
396 | * @param format The certificate format (ASN.1 or PEM). | |
397 | * | |
398 | * @throws boost::system::system_error Thrown on failure. | |
399 | * | |
400 | * @note Calls @c SSL_CTX_use_certificate or SSL_CTX_use_certificate_ASN1. | |
401 | */ | |
402 | BOOST_ASIO_DECL void use_certificate( | |
403 | const const_buffer& certificate, file_format format); | |
404 | ||
405 | /// Use a certificate from a memory buffer. | |
406 | /** | |
407 | * This function is used to load a certificate into the context from a buffer. | |
408 | * | |
409 | * @param certificate The buffer containing the certificate. | |
410 | * | |
411 | * @param format The certificate format (ASN.1 or PEM). | |
412 | * | |
413 | * @param ec Set to indicate what error occurred, if any. | |
414 | * | |
415 | * @note Calls @c SSL_CTX_use_certificate or SSL_CTX_use_certificate_ASN1. | |
416 | */ | |
417 | BOOST_ASIO_DECL boost::system::error_code use_certificate( | |
418 | const const_buffer& certificate, file_format format, | |
419 | boost::system::error_code& ec); | |
420 | ||
421 | /// Use a certificate from a file. | |
422 | /** | |
423 | * This function is used to load a certificate into the context from a file. | |
424 | * | |
425 | * @param filename The name of the file containing the certificate. | |
426 | * | |
427 | * @param format The file format (ASN.1 or PEM). | |
428 | * | |
429 | * @throws boost::system::system_error Thrown on failure. | |
430 | * | |
431 | * @note Calls @c SSL_CTX_use_certificate_file. | |
432 | */ | |
433 | BOOST_ASIO_DECL void use_certificate_file( | |
434 | const std::string& filename, file_format format); | |
435 | ||
436 | /// Use a certificate from a file. | |
437 | /** | |
438 | * This function is used to load a certificate into the context from a file. | |
439 | * | |
440 | * @param filename The name of the file containing the certificate. | |
441 | * | |
442 | * @param format The file format (ASN.1 or PEM). | |
443 | * | |
444 | * @param ec Set to indicate what error occurred, if any. | |
445 | * | |
446 | * @note Calls @c SSL_CTX_use_certificate_file. | |
447 | */ | |
448 | BOOST_ASIO_DECL boost::system::error_code use_certificate_file( | |
449 | const std::string& filename, file_format format, | |
450 | boost::system::error_code& ec); | |
451 | ||
452 | /// Use a certificate chain from a memory buffer. | |
453 | /** | |
454 | * This function is used to load a certificate chain into the context from a | |
455 | * buffer. | |
456 | * | |
457 | * @param chain The buffer containing the certificate chain. The certificate | |
458 | * chain must use the PEM format. | |
459 | * | |
460 | * @throws boost::system::system_error Thrown on failure. | |
461 | * | |
462 | * @note Calls @c SSL_CTX_use_certificate and SSL_CTX_add_extra_chain_cert. | |
463 | */ | |
464 | BOOST_ASIO_DECL void use_certificate_chain(const const_buffer& chain); | |
465 | ||
466 | /// Use a certificate chain from a memory buffer. | |
467 | /** | |
468 | * This function is used to load a certificate chain into the context from a | |
469 | * buffer. | |
470 | * | |
471 | * @param chain The buffer containing the certificate chain. The certificate | |
472 | * chain must use the PEM format. | |
473 | * | |
474 | * @param ec Set to indicate what error occurred, if any. | |
475 | * | |
476 | * @note Calls @c SSL_CTX_use_certificate and SSL_CTX_add_extra_chain_cert. | |
477 | */ | |
478 | BOOST_ASIO_DECL boost::system::error_code use_certificate_chain( | |
479 | const const_buffer& chain, boost::system::error_code& ec); | |
480 | ||
481 | /// Use a certificate chain from a file. | |
482 | /** | |
483 | * This function is used to load a certificate chain into the context from a | |
484 | * file. | |
485 | * | |
486 | * @param filename The name of the file containing the certificate. The file | |
487 | * must use the PEM format. | |
488 | * | |
489 | * @throws boost::system::system_error Thrown on failure. | |
490 | * | |
491 | * @note Calls @c SSL_CTX_use_certificate_chain_file. | |
492 | */ | |
493 | BOOST_ASIO_DECL void use_certificate_chain_file(const std::string& filename); | |
494 | ||
495 | /// Use a certificate chain from a file. | |
496 | /** | |
497 | * This function is used to load a certificate chain into the context from a | |
498 | * file. | |
499 | * | |
500 | * @param filename The name of the file containing the certificate. The file | |
501 | * must use the PEM format. | |
502 | * | |
503 | * @param ec Set to indicate what error occurred, if any. | |
504 | * | |
505 | * @note Calls @c SSL_CTX_use_certificate_chain_file. | |
506 | */ | |
507 | BOOST_ASIO_DECL boost::system::error_code use_certificate_chain_file( | |
508 | const std::string& filename, boost::system::error_code& ec); | |
509 | ||
510 | /// Use a private key from a memory buffer. | |
511 | /** | |
512 | * This function is used to load a private key into the context from a buffer. | |
513 | * | |
514 | * @param private_key The buffer containing the private key. | |
515 | * | |
516 | * @param format The private key format (ASN.1 or PEM). | |
517 | * | |
518 | * @throws boost::system::system_error Thrown on failure. | |
519 | * | |
520 | * @note Calls @c SSL_CTX_use_PrivateKey or SSL_CTX_use_PrivateKey_ASN1. | |
521 | */ | |
522 | BOOST_ASIO_DECL void use_private_key( | |
523 | const const_buffer& private_key, file_format format); | |
524 | ||
525 | /// Use a private key from a memory buffer. | |
526 | /** | |
527 | * This function is used to load a private key into the context from a buffer. | |
528 | * | |
529 | * @param private_key The buffer containing the private key. | |
530 | * | |
531 | * @param format The private key format (ASN.1 or PEM). | |
532 | * | |
533 | * @param ec Set to indicate what error occurred, if any. | |
534 | * | |
535 | * @note Calls @c SSL_CTX_use_PrivateKey or SSL_CTX_use_PrivateKey_ASN1. | |
536 | */ | |
537 | BOOST_ASIO_DECL boost::system::error_code use_private_key( | |
538 | const const_buffer& private_key, file_format format, | |
539 | boost::system::error_code& ec); | |
540 | ||
541 | /// Use a private key from a file. | |
542 | /** | |
543 | * This function is used to load a private key into the context from a file. | |
544 | * | |
545 | * @param filename The name of the file containing the private key. | |
546 | * | |
547 | * @param format The file format (ASN.1 or PEM). | |
548 | * | |
549 | * @throws boost::system::system_error Thrown on failure. | |
550 | * | |
551 | * @note Calls @c SSL_CTX_use_PrivateKey_file. | |
552 | */ | |
553 | BOOST_ASIO_DECL void use_private_key_file( | |
554 | const std::string& filename, file_format format); | |
555 | ||
556 | /// Use a private key from a file. | |
557 | /** | |
558 | * This function is used to load a private key into the context from a file. | |
559 | * | |
560 | * @param filename The name of the file containing the private key. | |
561 | * | |
562 | * @param format The file format (ASN.1 or PEM). | |
563 | * | |
564 | * @param ec Set to indicate what error occurred, if any. | |
565 | * | |
566 | * @note Calls @c SSL_CTX_use_PrivateKey_file. | |
567 | */ | |
568 | BOOST_ASIO_DECL boost::system::error_code use_private_key_file( | |
569 | const std::string& filename, file_format format, | |
570 | boost::system::error_code& ec); | |
571 | ||
572 | /// Use an RSA private key from a memory buffer. | |
573 | /** | |
574 | * This function is used to load an RSA private key into the context from a | |
575 | * buffer. | |
576 | * | |
577 | * @param private_key The buffer containing the RSA private key. | |
578 | * | |
579 | * @param format The private key format (ASN.1 or PEM). | |
580 | * | |
581 | * @throws boost::system::system_error Thrown on failure. | |
582 | * | |
583 | * @note Calls @c SSL_CTX_use_RSAPrivateKey or SSL_CTX_use_RSAPrivateKey_ASN1. | |
584 | */ | |
585 | BOOST_ASIO_DECL void use_rsa_private_key( | |
586 | const const_buffer& private_key, file_format format); | |
587 | ||
588 | /// Use an RSA private key from a memory buffer. | |
589 | /** | |
590 | * This function is used to load an RSA private key into the context from a | |
591 | * buffer. | |
592 | * | |
593 | * @param private_key The buffer containing the RSA private key. | |
594 | * | |
595 | * @param format The private key format (ASN.1 or PEM). | |
596 | * | |
597 | * @param ec Set to indicate what error occurred, if any. | |
598 | * | |
599 | * @note Calls @c SSL_CTX_use_RSAPrivateKey or SSL_CTX_use_RSAPrivateKey_ASN1. | |
600 | */ | |
601 | BOOST_ASIO_DECL boost::system::error_code use_rsa_private_key( | |
602 | const const_buffer& private_key, file_format format, | |
603 | boost::system::error_code& ec); | |
604 | ||
605 | /// Use an RSA private key from a file. | |
606 | /** | |
607 | * This function is used to load an RSA private key into the context from a | |
608 | * file. | |
609 | * | |
610 | * @param filename The name of the file containing the RSA private key. | |
611 | * | |
612 | * @param format The file format (ASN.1 or PEM). | |
613 | * | |
614 | * @throws boost::system::system_error Thrown on failure. | |
615 | * | |
616 | * @note Calls @c SSL_CTX_use_RSAPrivateKey_file. | |
617 | */ | |
618 | BOOST_ASIO_DECL void use_rsa_private_key_file( | |
619 | const std::string& filename, file_format format); | |
620 | ||
621 | /// Use an RSA private key from a file. | |
622 | /** | |
623 | * This function is used to load an RSA private key into the context from a | |
624 | * file. | |
625 | * | |
626 | * @param filename The name of the file containing the RSA private key. | |
627 | * | |
628 | * @param format The file format (ASN.1 or PEM). | |
629 | * | |
630 | * @param ec Set to indicate what error occurred, if any. | |
631 | * | |
632 | * @note Calls @c SSL_CTX_use_RSAPrivateKey_file. | |
633 | */ | |
634 | BOOST_ASIO_DECL boost::system::error_code use_rsa_private_key_file( | |
635 | const std::string& filename, file_format format, | |
636 | boost::system::error_code& ec); | |
637 | ||
638 | /// Use the specified memory buffer to obtain the temporary Diffie-Hellman | |
639 | /// parameters. | |
640 | /** | |
641 | * This function is used to load Diffie-Hellman parameters into the context | |
642 | * from a buffer. | |
643 | * | |
644 | * @param dh The memory buffer containing the Diffie-Hellman parameters. The | |
645 | * buffer must use the PEM format. | |
646 | * | |
647 | * @throws boost::system::system_error Thrown on failure. | |
648 | * | |
649 | * @note Calls @c SSL_CTX_set_tmp_dh. | |
650 | */ | |
651 | BOOST_ASIO_DECL void use_tmp_dh(const const_buffer& dh); | |
652 | ||
653 | /// Use the specified memory buffer to obtain the temporary Diffie-Hellman | |
654 | /// parameters. | |
655 | /** | |
656 | * This function is used to load Diffie-Hellman parameters into the context | |
657 | * from a buffer. | |
658 | * | |
659 | * @param dh The memory buffer containing the Diffie-Hellman parameters. The | |
660 | * buffer must use the PEM format. | |
661 | * | |
662 | * @param ec Set to indicate what error occurred, if any. | |
663 | * | |
664 | * @note Calls @c SSL_CTX_set_tmp_dh. | |
665 | */ | |
666 | BOOST_ASIO_DECL boost::system::error_code use_tmp_dh( | |
667 | const const_buffer& dh, boost::system::error_code& ec); | |
668 | ||
669 | /// Use the specified file to obtain the temporary Diffie-Hellman parameters. | |
670 | /** | |
671 | * This function is used to load Diffie-Hellman parameters into the context | |
672 | * from a file. | |
673 | * | |
674 | * @param filename The name of the file containing the Diffie-Hellman | |
675 | * parameters. The file must use the PEM format. | |
676 | * | |
677 | * @throws boost::system::system_error Thrown on failure. | |
678 | * | |
679 | * @note Calls @c SSL_CTX_set_tmp_dh. | |
680 | */ | |
681 | BOOST_ASIO_DECL void use_tmp_dh_file(const std::string& filename); | |
682 | ||
683 | /// Use the specified file to obtain the temporary Diffie-Hellman parameters. | |
684 | /** | |
685 | * This function is used to load Diffie-Hellman parameters into the context | |
686 | * from a file. | |
687 | * | |
688 | * @param filename The name of the file containing the Diffie-Hellman | |
689 | * parameters. The file must use the PEM format. | |
690 | * | |
691 | * @param ec Set to indicate what error occurred, if any. | |
692 | * | |
693 | * @note Calls @c SSL_CTX_set_tmp_dh. | |
694 | */ | |
695 | BOOST_ASIO_DECL boost::system::error_code use_tmp_dh_file( | |
696 | const std::string& filename, boost::system::error_code& ec); | |
697 | ||
698 | /// Set the password callback. | |
699 | /** | |
700 | * This function is used to specify a callback function to obtain password | |
701 | * information about an encrypted key in PEM format. | |
702 | * | |
703 | * @param callback The function object to be used for obtaining the password. | |
704 | * The function signature of the handler must be: | |
705 | * @code std::string password_callback( | |
706 | * std::size_t max_length, // The maximum size for a password. | |
707 | * password_purpose purpose // Whether password is for reading or writing. | |
708 | * ); @endcode | |
709 | * The return value of the callback is a string containing the password. | |
710 | * | |
711 | * @throws boost::system::system_error Thrown on failure. | |
712 | * | |
713 | * @note Calls @c SSL_CTX_set_default_passwd_cb. | |
714 | */ | |
715 | template <typename PasswordCallback> | |
716 | void set_password_callback(PasswordCallback callback); | |
717 | ||
718 | /// Set the password callback. | |
719 | /** | |
720 | * This function is used to specify a callback function to obtain password | |
721 | * information about an encrypted key in PEM format. | |
722 | * | |
723 | * @param callback The function object to be used for obtaining the password. | |
724 | * The function signature of the handler must be: | |
725 | * @code std::string password_callback( | |
726 | * std::size_t max_length, // The maximum size for a password. | |
727 | * password_purpose purpose // Whether password is for reading or writing. | |
728 | * ); @endcode | |
729 | * The return value of the callback is a string containing the password. | |
730 | * | |
731 | * @param ec Set to indicate what error occurred, if any. | |
732 | * | |
733 | * @note Calls @c SSL_CTX_set_default_passwd_cb. | |
734 | */ | |
735 | template <typename PasswordCallback> | |
736 | boost::system::error_code set_password_callback(PasswordCallback callback, | |
737 | boost::system::error_code& ec); | |
738 | ||
739 | private: | |
740 | struct bio_cleanup; | |
741 | struct x509_cleanup; | |
742 | struct evp_pkey_cleanup; | |
743 | struct rsa_cleanup; | |
744 | struct dh_cleanup; | |
745 | ||
746 | // Helper function used to set a peer certificate verification callback. | |
747 | BOOST_ASIO_DECL boost::system::error_code do_set_verify_callback( | |
748 | detail::verify_callback_base* callback, boost::system::error_code& ec); | |
749 | ||
750 | // Callback used when the SSL implementation wants to verify a certificate. | |
751 | BOOST_ASIO_DECL static int verify_callback_function( | |
752 | int preverified, X509_STORE_CTX* ctx); | |
753 | ||
754 | // Helper function used to set a password callback. | |
755 | BOOST_ASIO_DECL boost::system::error_code do_set_password_callback( | |
756 | detail::password_callback_base* callback, boost::system::error_code& ec); | |
757 | ||
758 | // Callback used when the SSL implementation wants a password. | |
759 | BOOST_ASIO_DECL static int password_callback_function( | |
760 | char* buf, int size, int purpose, void* data); | |
761 | ||
762 | // Helper function to set the temporary Diffie-Hellman parameters from a BIO. | |
763 | BOOST_ASIO_DECL boost::system::error_code do_use_tmp_dh( | |
764 | BIO* bio, boost::system::error_code& ec); | |
765 | ||
766 | // Helper function to make a BIO from a memory buffer. | |
767 | BOOST_ASIO_DECL BIO* make_buffer_bio(const const_buffer& b); | |
768 | ||
769 | // The underlying native implementation. | |
770 | native_handle_type handle_; | |
771 | ||
772 | // Ensure openssl is initialised. | |
773 | boost::asio::ssl::detail::openssl_init<> init_; | |
774 | }; | |
775 | ||
776 | #endif // defined(BOOST_ASIO_ENABLE_OLD_SSL) | |
777 | ||
778 | } // namespace ssl | |
779 | } // namespace asio | |
780 | } // namespace boost | |
781 | ||
782 | #include <boost/asio/detail/pop_options.hpp> | |
783 | ||
784 | #include <boost/asio/ssl/impl/context.hpp> | |
785 | #if defined(BOOST_ASIO_HEADER_ONLY) | |
786 | # include <boost/asio/ssl/impl/context.ipp> | |
787 | #endif // defined(BOOST_ASIO_HEADER_ONLY) | |
788 | ||
789 | #endif // BOOST_ASIO_SSL_CONTEXT_HPP |