5 // Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com)
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)
11 #ifndef BOOST_ASIO_SSL_CONTEXT_HPP
12 #define BOOST_ASIO_SSL_CONTEXT_HPP
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18 #include <boost/asio/detail/config.hpp>
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)
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)
35 #include <boost/asio/detail/push_options.hpp>
41 #if defined(BOOST_ASIO_ENABLE_OLD_SSL)
43 /// Typedef for the typical usage of context.
44 typedef basic_context<context_service> context;
46 #else // defined(BOOST_ASIO_ENABLE_OLD_SSL)
49 : public context_base,
53 /// The native handle type of the SSL context.
54 typedef SSL_CTX* native_handle_type;
56 /// (Deprecated: Use native_handle_type.) The native type of the SSL context.
57 typedef SSL_CTX* impl_type;
60 BOOST_ASIO_DECL explicit context(method m);
62 /// Deprecated constructor taking a reference to an io_service object.
63 BOOST_ASIO_DECL context(boost::asio::io_service&, method m);
65 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
66 /// Move-construct a context from another.
68 * This constructor moves an SSL context from one object to another.
70 * @param other The other context object from which the move will occur.
72 * @note Following the move, the following operations only are valid for the
75 * @li As a target for move-assignment.
77 BOOST_ASIO_DECL context(context&& other);
79 /// Move-assign a context from another.
81 * This assignment operator moves an SSL context from one object to another.
83 * @param other The other context object from which the move will occur.
85 * @note Following the move, the following operations only are valid for the
88 * @li As a target for move-assignment.
90 BOOST_ASIO_DECL context& operator=(context&& other);
91 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
94 BOOST_ASIO_DECL ~context();
96 /// Get the underlying implementation in the native type.
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.
102 BOOST_ASIO_DECL native_handle_type native_handle();
104 /// (Deprecated: Use native_handle().) Get the underlying implementation in
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.
111 BOOST_ASIO_DECL impl_type impl();
113 /// Clear options on the context.
115 * This function may be used to configure the SSL options used by the context.
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.
121 * @throws boost::system::system_error Thrown on failure.
123 * @note Calls @c SSL_CTX_clear_options.
125 BOOST_ASIO_DECL void clear_options(options o);
127 /// Clear options on the context.
129 * This function may be used to configure the SSL options used by the context.
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.
135 * @param ec Set to indicate what error occurred, if any.
137 * @note Calls @c SSL_CTX_clear_options.
139 BOOST_ASIO_DECL boost::system::error_code clear_options(options o,
140 boost::system::error_code& ec);
142 /// Set options on the context.
144 * This function may be used to configure the SSL options used by the context.
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.
150 * @throws boost::system::system_error Thrown on failure.
152 * @note Calls @c SSL_CTX_set_options.
154 BOOST_ASIO_DECL void set_options(options o);
156 /// Set options on the context.
158 * This function may be used to configure the SSL options used by the context.
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.
164 * @param ec Set to indicate what error occurred, if any.
166 * @note Calls @c SSL_CTX_set_options.
168 BOOST_ASIO_DECL boost::system::error_code set_options(options o,
169 boost::system::error_code& ec);
171 /// Set the peer verification mode.
173 * This function may be used to configure the peer verification mode used by
176 * @param v A bitmask of peer verification modes. See @ref verify_mode for
179 * @throws boost::system::system_error Thrown on failure.
181 * @note Calls @c SSL_CTX_set_verify.
183 BOOST_ASIO_DECL void set_verify_mode(verify_mode v);
185 /// Set the peer verification mode.
187 * This function may be used to configure the peer verification mode used by
190 * @param v A bitmask of peer verification modes. See @ref verify_mode for
193 * @param ec Set to indicate what error occurred, if any.
195 * @note Calls @c SSL_CTX_set_verify.
197 BOOST_ASIO_DECL boost::system::error_code set_verify_mode(
198 verify_mode v, boost::system::error_code& ec);
200 /// Set the peer verification depth.
202 * This function may be used to configure the maximum verification depth
203 * allowed by the context.
205 * @param depth Maximum depth for the certificate chain verification that
208 * @throws boost::system::system_error Thrown on failure.
210 * @note Calls @c SSL_CTX_set_verify_depth.
212 BOOST_ASIO_DECL void set_verify_depth(int depth);
214 /// Set the peer verification depth.
216 * This function may be used to configure the maximum verification depth
217 * allowed by the context.
219 * @param depth Maximum depth for the certificate chain verification that
222 * @param ec Set to indicate what error occurred, if any.
224 * @note Calls @c SSL_CTX_set_verify_depth.
226 BOOST_ASIO_DECL boost::system::error_code set_verify_depth(
227 int depth, boost::system::error_code& ec);
229 /// Set the callback used to verify peer certificates.
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.
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.
240 * The return value of the callback is true if the certificate has passed
241 * verification, false otherwise.
243 * @throws boost::system::system_error Thrown on failure.
245 * @note Calls @c SSL_CTX_set_verify.
247 template <typename VerifyCallback>
248 void set_verify_callback(VerifyCallback callback);
250 /// Set the callback used to verify peer certificates.
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.
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.
261 * The return value of the callback is true if the certificate has passed
262 * verification, false otherwise.
264 * @param ec Set to indicate what error occurred, if any.
266 * @note Calls @c SSL_CTX_set_verify.
268 template <typename VerifyCallback>
269 boost::system::error_code set_verify_callback(VerifyCallback callback,
270 boost::system::error_code& ec);
272 /// Load a certification authority file for performing verification.
274 * This function is used to load one or more trusted certification authorities
277 * @param filename The name of a file containing certification authority
278 * certificates in PEM format.
280 * @throws boost::system::system_error Thrown on failure.
282 * @note Calls @c SSL_CTX_load_verify_locations.
284 BOOST_ASIO_DECL void load_verify_file(const std::string& filename);
286 /// Load a certification authority file for performing verification.
288 * This function is used to load the certificates for one or more trusted
289 * certification authorities from a file.
291 * @param filename The name of a file containing certification authority
292 * certificates in PEM format.
294 * @param ec Set to indicate what error occurred, if any.
296 * @note Calls @c SSL_CTX_load_verify_locations.
298 BOOST_ASIO_DECL boost::system::error_code load_verify_file(
299 const std::string& filename, boost::system::error_code& ec);
301 /// Add certification authority for performing verification.
303 * This function is used to add one trusted certification authority
304 * from a memory buffer.
306 * @param ca The buffer containing the certification authority certificate.
307 * The certificate must use the PEM format.
309 * @throws boost::system::system_error Thrown on failure.
311 * @note Calls @c SSL_CTX_get_cert_store and @c X509_STORE_add_cert.
313 BOOST_ASIO_DECL void add_certificate_authority(const const_buffer& ca);
315 /// Add certification authority for performing verification.
317 * This function is used to add one trusted certification authority
318 * from a memory buffer.
320 * @param ca The buffer containing the certification authority certificate.
321 * The certificate must use the PEM format.
323 * @param ec Set to indicate what error occurred, if any.
325 * @note Calls @c SSL_CTX_get_cert_store and @c X509_STORE_add_cert.
327 BOOST_ASIO_DECL boost::system::error_code add_certificate_authority(
328 const const_buffer& ca, boost::system::error_code& ec);
330 /// Configures the context to use the default directories for finding
331 /// certification authority certificates.
333 * This function specifies that the context should use the default,
334 * system-dependent directories for locating certification authority
337 * @throws boost::system::system_error Thrown on failure.
339 * @note Calls @c SSL_CTX_set_default_verify_paths.
341 BOOST_ASIO_DECL void set_default_verify_paths();
343 /// Configures the context to use the default directories for finding
344 /// certification authority certificates.
346 * This function specifies that the context should use the default,
347 * system-dependent directories for locating certification authority
350 * @param ec Set to indicate what error occurred, if any.
352 * @note Calls @c SSL_CTX_set_default_verify_paths.
354 BOOST_ASIO_DECL boost::system::error_code set_default_verify_paths(
355 boost::system::error_code& ec);
357 /// Add a directory containing certificate authority files to be used for
358 /// performing verification.
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".
365 * @param path The name of a directory containing the certificates.
367 * @throws boost::system::system_error Thrown on failure.
369 * @note Calls @c SSL_CTX_load_verify_locations.
371 BOOST_ASIO_DECL void add_verify_path(const std::string& path);
373 /// Add a directory containing certificate authority files to be used for
374 /// performing verification.
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".
381 * @param path The name of a directory containing the certificates.
383 * @param ec Set to indicate what error occurred, if any.
385 * @note Calls @c SSL_CTX_load_verify_locations.
387 BOOST_ASIO_DECL boost::system::error_code add_verify_path(
388 const std::string& path, boost::system::error_code& ec);
390 /// Use a certificate from a memory buffer.
392 * This function is used to load a certificate into the context from a buffer.
394 * @param certificate The buffer containing the certificate.
396 * @param format The certificate format (ASN.1 or PEM).
398 * @throws boost::system::system_error Thrown on failure.
400 * @note Calls @c SSL_CTX_use_certificate or SSL_CTX_use_certificate_ASN1.
402 BOOST_ASIO_DECL void use_certificate(
403 const const_buffer& certificate, file_format format);
405 /// Use a certificate from a memory buffer.
407 * This function is used to load a certificate into the context from a buffer.
409 * @param certificate The buffer containing the certificate.
411 * @param format The certificate format (ASN.1 or PEM).
413 * @param ec Set to indicate what error occurred, if any.
415 * @note Calls @c SSL_CTX_use_certificate or SSL_CTX_use_certificate_ASN1.
417 BOOST_ASIO_DECL boost::system::error_code use_certificate(
418 const const_buffer& certificate, file_format format,
419 boost::system::error_code& ec);
421 /// Use a certificate from a file.
423 * This function is used to load a certificate into the context from a file.
425 * @param filename The name of the file containing the certificate.
427 * @param format The file format (ASN.1 or PEM).
429 * @throws boost::system::system_error Thrown on failure.
431 * @note Calls @c SSL_CTX_use_certificate_file.
433 BOOST_ASIO_DECL void use_certificate_file(
434 const std::string& filename, file_format format);
436 /// Use a certificate from a file.
438 * This function is used to load a certificate into the context from a file.
440 * @param filename The name of the file containing the certificate.
442 * @param format The file format (ASN.1 or PEM).
444 * @param ec Set to indicate what error occurred, if any.
446 * @note Calls @c SSL_CTX_use_certificate_file.
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);
452 /// Use a certificate chain from a memory buffer.
454 * This function is used to load a certificate chain into the context from a
457 * @param chain The buffer containing the certificate chain. The certificate
458 * chain must use the PEM format.
460 * @throws boost::system::system_error Thrown on failure.
462 * @note Calls @c SSL_CTX_use_certificate and SSL_CTX_add_extra_chain_cert.
464 BOOST_ASIO_DECL void use_certificate_chain(const const_buffer& chain);
466 /// Use a certificate chain from a memory buffer.
468 * This function is used to load a certificate chain into the context from a
471 * @param chain The buffer containing the certificate chain. The certificate
472 * chain must use the PEM format.
474 * @param ec Set to indicate what error occurred, if any.
476 * @note Calls @c SSL_CTX_use_certificate and SSL_CTX_add_extra_chain_cert.
478 BOOST_ASIO_DECL boost::system::error_code use_certificate_chain(
479 const const_buffer& chain, boost::system::error_code& ec);
481 /// Use a certificate chain from a file.
483 * This function is used to load a certificate chain into the context from a
486 * @param filename The name of the file containing the certificate. The file
487 * must use the PEM format.
489 * @throws boost::system::system_error Thrown on failure.
491 * @note Calls @c SSL_CTX_use_certificate_chain_file.
493 BOOST_ASIO_DECL void use_certificate_chain_file(const std::string& filename);
495 /// Use a certificate chain from a file.
497 * This function is used to load a certificate chain into the context from a
500 * @param filename The name of the file containing the certificate. The file
501 * must use the PEM format.
503 * @param ec Set to indicate what error occurred, if any.
505 * @note Calls @c SSL_CTX_use_certificate_chain_file.
507 BOOST_ASIO_DECL boost::system::error_code use_certificate_chain_file(
508 const std::string& filename, boost::system::error_code& ec);
510 /// Use a private key from a memory buffer.
512 * This function is used to load a private key into the context from a buffer.
514 * @param private_key The buffer containing the private key.
516 * @param format The private key format (ASN.1 or PEM).
518 * @throws boost::system::system_error Thrown on failure.
520 * @note Calls @c SSL_CTX_use_PrivateKey or SSL_CTX_use_PrivateKey_ASN1.
522 BOOST_ASIO_DECL void use_private_key(
523 const const_buffer& private_key, file_format format);
525 /// Use a private key from a memory buffer.
527 * This function is used to load a private key into the context from a buffer.
529 * @param private_key The buffer containing the private key.
531 * @param format The private key format (ASN.1 or PEM).
533 * @param ec Set to indicate what error occurred, if any.
535 * @note Calls @c SSL_CTX_use_PrivateKey or SSL_CTX_use_PrivateKey_ASN1.
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);
541 /// Use a private key from a file.
543 * This function is used to load a private key into the context from a file.
545 * @param filename The name of the file containing the private key.
547 * @param format The file format (ASN.1 or PEM).
549 * @throws boost::system::system_error Thrown on failure.
551 * @note Calls @c SSL_CTX_use_PrivateKey_file.
553 BOOST_ASIO_DECL void use_private_key_file(
554 const std::string& filename, file_format format);
556 /// Use a private key from a file.
558 * This function is used to load a private key into the context from a file.
560 * @param filename The name of the file containing the private key.
562 * @param format The file format (ASN.1 or PEM).
564 * @param ec Set to indicate what error occurred, if any.
566 * @note Calls @c SSL_CTX_use_PrivateKey_file.
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);
572 /// Use an RSA private key from a memory buffer.
574 * This function is used to load an RSA private key into the context from a
577 * @param private_key The buffer containing the RSA private key.
579 * @param format The private key format (ASN.1 or PEM).
581 * @throws boost::system::system_error Thrown on failure.
583 * @note Calls @c SSL_CTX_use_RSAPrivateKey or SSL_CTX_use_RSAPrivateKey_ASN1.
585 BOOST_ASIO_DECL void use_rsa_private_key(
586 const const_buffer& private_key, file_format format);
588 /// Use an RSA private key from a memory buffer.
590 * This function is used to load an RSA private key into the context from a
593 * @param private_key The buffer containing the RSA private key.
595 * @param format The private key format (ASN.1 or PEM).
597 * @param ec Set to indicate what error occurred, if any.
599 * @note Calls @c SSL_CTX_use_RSAPrivateKey or SSL_CTX_use_RSAPrivateKey_ASN1.
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);
605 /// Use an RSA private key from a file.
607 * This function is used to load an RSA private key into the context from a
610 * @param filename The name of the file containing the RSA private key.
612 * @param format The file format (ASN.1 or PEM).
614 * @throws boost::system::system_error Thrown on failure.
616 * @note Calls @c SSL_CTX_use_RSAPrivateKey_file.
618 BOOST_ASIO_DECL void use_rsa_private_key_file(
619 const std::string& filename, file_format format);
621 /// Use an RSA private key from a file.
623 * This function is used to load an RSA private key into the context from a
626 * @param filename The name of the file containing the RSA private key.
628 * @param format The file format (ASN.1 or PEM).
630 * @param ec Set to indicate what error occurred, if any.
632 * @note Calls @c SSL_CTX_use_RSAPrivateKey_file.
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);
638 /// Use the specified memory buffer to obtain the temporary Diffie-Hellman
641 * This function is used to load Diffie-Hellman parameters into the context
644 * @param dh The memory buffer containing the Diffie-Hellman parameters. The
645 * buffer must use the PEM format.
647 * @throws boost::system::system_error Thrown on failure.
649 * @note Calls @c SSL_CTX_set_tmp_dh.
651 BOOST_ASIO_DECL void use_tmp_dh(const const_buffer& dh);
653 /// Use the specified memory buffer to obtain the temporary Diffie-Hellman
656 * This function is used to load Diffie-Hellman parameters into the context
659 * @param dh The memory buffer containing the Diffie-Hellman parameters. The
660 * buffer must use the PEM format.
662 * @param ec Set to indicate what error occurred, if any.
664 * @note Calls @c SSL_CTX_set_tmp_dh.
666 BOOST_ASIO_DECL boost::system::error_code use_tmp_dh(
667 const const_buffer& dh, boost::system::error_code& ec);
669 /// Use the specified file to obtain the temporary Diffie-Hellman parameters.
671 * This function is used to load Diffie-Hellman parameters into the context
674 * @param filename The name of the file containing the Diffie-Hellman
675 * parameters. The file must use the PEM format.
677 * @throws boost::system::system_error Thrown on failure.
679 * @note Calls @c SSL_CTX_set_tmp_dh.
681 BOOST_ASIO_DECL void use_tmp_dh_file(const std::string& filename);
683 /// Use the specified file to obtain the temporary Diffie-Hellman parameters.
685 * This function is used to load Diffie-Hellman parameters into the context
688 * @param filename The name of the file containing the Diffie-Hellman
689 * parameters. The file must use the PEM format.
691 * @param ec Set to indicate what error occurred, if any.
693 * @note Calls @c SSL_CTX_set_tmp_dh.
695 BOOST_ASIO_DECL boost::system::error_code use_tmp_dh_file(
696 const std::string& filename, boost::system::error_code& ec);
698 /// Set the password callback.
700 * This function is used to specify a callback function to obtain password
701 * information about an encrypted key in PEM format.
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.
709 * The return value of the callback is a string containing the password.
711 * @throws boost::system::system_error Thrown on failure.
713 * @note Calls @c SSL_CTX_set_default_passwd_cb.
715 template <typename PasswordCallback>
716 void set_password_callback(PasswordCallback callback);
718 /// Set the password callback.
720 * This function is used to specify a callback function to obtain password
721 * information about an encrypted key in PEM format.
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.
729 * The return value of the callback is a string containing the password.
731 * @param ec Set to indicate what error occurred, if any.
733 * @note Calls @c SSL_CTX_set_default_passwd_cb.
735 template <typename PasswordCallback>
736 boost::system::error_code set_password_callback(PasswordCallback callback,
737 boost::system::error_code& ec);
742 struct evp_pkey_cleanup;
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);
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);
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);
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);
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);
766 // Helper function to make a BIO from a memory buffer.
767 BOOST_ASIO_DECL BIO* make_buffer_bio(const const_buffer& b);
769 // The underlying native implementation.
770 native_handle_type handle_;
772 // Ensure openssl is initialised.
773 boost::asio::ssl::detail::openssl_init<> init_;
776 #endif // defined(BOOST_ASIO_ENABLE_OLD_SSL)
782 #include <boost/asio/detail/pop_options.hpp>
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)
789 #endif // BOOST_ASIO_SSL_CONTEXT_HPP