boost/asio/ssl/basic_context.hpp

   1 //
   2 // basic_context.hpp
   3 // ~~~~~~~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2005 Voipster / Indrek dot Juhani at voipster dot com
   6 // Copyright (c) 2005-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
   7 //
   8 // Distributed under the Boost Software License, Version 1.0. (See accompanying
   9 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
  10 //
  11
  12 #ifndef BOOST_ASIO_SSL_BASIC_CONTEXT_HPP
  13 #define BOOST_ASIO_SSL_BASIC_CONTEXT_HPP
  14
  15 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
  16 # pragma once
  17 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
  18
  19 #include <boost/asio/detail/push_options.hpp>
  20
  21 #include <boost/asio/detail/push_options.hpp>
  22 #include <string>
  23 #include <boost/noncopyable.hpp>
  24 #include <boost/asio/detail/pop_options.hpp>
  25
  26 #include <boost/asio/error.hpp>
  27 #include <boost/asio/io_service.hpp>
  28 #include <boost/asio/ssl/context_base.hpp>
  29 #include <boost/asio/detail/throw_error.hpp>
  30
  31 namespace boost {
  32 namespace asio {
  33 namespace ssl {
  34
  35 /// SSL context.
  36 template <typename Service>
  37 class basic_context
  38   : public context_base,
  39     private boost::noncopyable
  40 {
  41 public:
  42   /// The type of the service that will be used to provide context operations.
  43   typedef Service service_type;
  44
  45   /// The native implementation type of the locking dispatcher.
  46   typedef typename service_type::impl_type impl_type;
  47
  48   /// Constructor.
  49   basic_context(boost::asio::io_service& io_service, method m)
  50     : service_(boost::asio::use_service<Service>(io_service)),
  51       impl_(service_.null())
  52   {
  53     service_.create(impl_, m);
  54   }
  55
  56   /// Destructor.
  57   ~basic_context()
  58   {
  59     service_.destroy(impl_);
  60   }
  61
  62   /// Get the underlying implementation in the native type.
  63   /**
  64    * This function may be used to obtain the underlying implementation of the
  65    * context. This is intended to allow access to context functionality that is
  66    * not otherwise provided.
  67    */
  68   impl_type impl()
  69   {
  70     return impl_;
  71   }
  72
  73   /// Set options on the context.
  74   /**
  75    * This function may be used to configure the SSL options used by the context.
  76    *
  77    * @param o A bitmask of options. The available option values are defined in
  78    * the context_base class. The options are bitwise-ored with any existing
  79    * value for the options.
  80    *
  81    * @throws boost::system::system_error Thrown on failure.
  82    */
  83   void set_options(options o)
  84   {
  85     boost::system::error_code ec;
  86     service_.set_options(impl_, o, ec);
  87     boost::asio::detail::throw_error(ec);
  88   }
  89
  90   /// Set options on the context.
  91   /**
  92    * This function may be used to configure the SSL options used by the context.
  93    *
  94    * @param o A bitmask of options. The available option values are defined in
  95    * the context_base class. The options are bitwise-ored with any existing
  96    * value for the options.
  97    *
  98    * @param ec Set to indicate what error occurred, if any.
  99    */
 100   boost::system::error_code set_options(options o,
 101       boost::system::error_code& ec)
 102   {
 103     return service_.set_options(impl_, o, ec);
 104   }
 105
 106   /// Set the peer verification mode.
 107   /**
 108    * This function may be used to configure the peer verification mode used by
 109    * the context.
 110    *
 111    * @param v A bitmask of peer verification modes. The available verify_mode
 112    * values are defined in the context_base class.
 113    *
 114    * @throws boost::system::system_error Thrown on failure.
 115    */
 116   void set_verify_mode(verify_mode v)
 117   {
 118     boost::system::error_code ec;
 119     service_.set_verify_mode(impl_, v, ec);
 120     boost::asio::detail::throw_error(ec);
 121   }
 122
 123   /// Set the peer verification mode.
 124   /**
 125    * This function may be used to configure the peer verification mode used by
 126    * the context.
 127    *
 128    * @param v A bitmask of peer verification modes. The available verify_mode
 129    * values are defined in the context_base class.
 130    *
 131    * @param ec Set to indicate what error occurred, if any.
 132    */
 133   boost::system::error_code set_verify_mode(verify_mode v,
 134       boost::system::error_code& ec)
 135   {
 136     return service_.set_verify_mode(impl_, v, ec);
 137   }
 138
 139   /// Load a certification authority file for performing verification.
 140   /**
 141    * This function is used to load one or more trusted certification authorities
 142    * from a file.
 143    *
 144    * @param filename The name of a file containing certification authority
 145    * certificates in PEM format.
 146    *
 147    * @throws boost::system::system_error Thrown on failure.
 148    */
 149   void load_verify_file(const std::string& filename)
 150   {
 151     boost::system::error_code ec;
 152     service_.load_verify_file(impl_, filename, ec);
 153     boost::asio::detail::throw_error(ec);
 154   }
 155
 156   /// Load a certification authority file for performing verification.
 157   /**
 158    * This function is used to load the certificates for one or more trusted
 159    * certification authorities from a file.
 160    *
 161    * @param filename The name of a file containing certification authority
 162    * certificates in PEM format.
 163    *
 164    * @param ec Set to indicate what error occurred, if any.
 165    */
 166   boost::system::error_code load_verify_file(const std::string& filename,
 167       boost::system::error_code& ec)
 168   {
 169     return service_.load_verify_file(impl_, filename, ec);
 170   }
 171
 172   /// Add a directory containing certificate authority files to be used for
 173   /// performing verification.
 174   /**
 175    * This function is used to specify the name of a directory containing
 176    * certification authority certificates. Each file in the directory must
 177    * contain a single certificate. The files must be named using the subject
 178    * name's hash and an extension of ".0".
 179    *
 180    * @param path The name of a directory containing the certificates.
 181    *
 182    * @throws boost::system::system_error Thrown on failure.
 183    */
 184   void add_verify_path(const std::string& path)
 185   {
 186     boost::system::error_code ec;
 187     service_.add_verify_path(impl_, path, ec);
 188     boost::asio::detail::throw_error(ec);
 189   }
 190
 191   /// Add a directory containing certificate authority files to be used for
 192   /// performing verification.
 193   /**
 194    * This function is used to specify the name of a directory containing
 195    * certification authority certificates. Each file in the directory must
 196    * contain a single certificate. The files must be named using the subject
 197    * name's hash and an extension of ".0".
 198    *
 199    * @param path The name of a directory containing the certificates.
 200    *
 201    * @param ec Set to indicate what error occurred, if any.
 202    */
 203   boost::system::error_code add_verify_path(const std::string& path,
 204       boost::system::error_code& ec)
 205   {
 206     return service_.add_verify_path(impl_, path, ec);
 207   }
 208
 209   /// Use a certificate from a file.
 210   /**
 211    * This function is used to load a certificate into the context from a file.
 212    *
 213    * @param filename The name of the file containing the certificate.
 214    *
 215    * @param format The file format (ASN.1 or PEM).
 216    *
 217    * @throws boost::system::system_error Thrown on failure.
 218    */
 219   void use_certificate_file(const std::string& filename, file_format format)
 220   {
 221     boost::system::error_code ec;
 222     service_.use_certificate_file(impl_, filename, format, ec);
 223     boost::asio::detail::throw_error(ec);
 224   }
 225
 226   /// Use a certificate from a file.
 227   /**
 228    * This function is used to load a certificate into the context from a file.
 229    *
 230    * @param filename The name of the file containing the certificate.
 231    *
 232    * @param format The file format (ASN.1 or PEM).
 233    *
 234    * @param ec Set to indicate what error occurred, if any.
 235    */
 236   boost::system::error_code use_certificate_file(const std::string& filename,
 237       file_format format, boost::system::error_code& ec)
 238   {
 239     return service_.use_certificate_file(impl_, filename, format, ec);
 240   }
 241
 242   /// Use a certificate chain from a file.
 243   /**
 244    * This function is used to load a certificate chain into the context from a
 245    * file.
 246    *
 247    * @param filename The name of the file containing the certificate. The file
 248    * must use the PEM format.
 249    *
 250    * @throws boost::system::system_error Thrown on failure.
 251    */
 252   void use_certificate_chain_file(const std::string& filename)
 253   {
 254     boost::system::error_code ec;
 255     service_.use_certificate_chain_file(impl_, filename, ec);
 256     boost::asio::detail::throw_error(ec);
 257   }
 258
 259   /// Use a certificate chain from a file.
 260   /**
 261    * This function is used to load a certificate chain into the context from a
 262    * file.
 263    *
 264    * @param filename The name of the file containing the certificate. The file
 265    * must use the PEM format.
 266    *
 267    * @param ec Set to indicate what error occurred, if any.
 268    */
 269   boost::system::error_code use_certificate_chain_file(
 270       const std::string& filename, boost::system::error_code& ec)
 271   {
 272     return service_.use_certificate_chain_file(impl_, filename, ec);
 273   }
 274
 275   /// Use a private key from a file.
 276   /**
 277    * This function is used to load a private key into the context from a file.
 278    *
 279    * @param filename The name of the file containing the private key.
 280    *
 281    * @param format The file format (ASN.1 or PEM).
 282    *
 283    * @throws boost::system::system_error Thrown on failure.
 284    */
 285   void use_private_key_file(const std::string& filename, file_format format)
 286   {
 287     boost::system::error_code ec;
 288     service_.use_private_key_file(impl_, filename, format, ec);
 289     boost::asio::detail::throw_error(ec);
 290   }
 291
 292   /// Use a private key from a file.
 293   /**
 294    * This function is used to load a private key into the context from a file.
 295    *
 296    * @param filename The name of the file containing the private key.
 297    *
 298    * @param format The file format (ASN.1 or PEM).
 299    *
 300    * @param ec Set to indicate what error occurred, if any.
 301    */
 302   boost::system::error_code use_private_key_file(const std::string& filename,
 303       file_format format, boost::system::error_code& ec)
 304   {
 305     return service_.use_private_key_file(impl_, filename, format, ec);
 306   }
 307
 308   /// Use an RSA private key from a file.
 309   /**
 310    * This function is used to load an RSA private key into the context from a
 311    * file.
 312    *
 313    * @param filename The name of the file containing the RSA private key.
 314    *
 315    * @param format The file format (ASN.1 or PEM).
 316    *
 317    * @throws boost::system::system_error Thrown on failure.
 318    */
 319   void use_rsa_private_key_file(const std::string& filename, file_format format)
 320   {
 321     boost::system::error_code ec;
 322     service_.use_rsa_private_key_file(impl_, filename, format, ec);
 323     boost::asio::detail::throw_error(ec);
 324   }
 325
 326   /// Use an RSA private key from a file.
 327   /**
 328    * This function is used to load an RSA private key into the context from a
 329    * file.
 330    *
 331    * @param filename The name of the file containing the RSA private key.
 332    *
 333    * @param format The file format (ASN.1 or PEM).
 334    *
 335    * @param ec Set to indicate what error occurred, if any.
 336    */
 337   boost::system::error_code use_rsa_private_key_file(
 338       const std::string& filename, file_format format,
 339       boost::system::error_code& ec)
 340   {
 341     return service_.use_rsa_private_key_file(impl_, filename, format, ec);
 342   }
 343
 344   /// Use the specified file to obtain the temporary Diffie-Hellman parameters.
 345   /**
 346    * This function is used to load Diffie-Hellman parameters into the context
 347    * from a file.
 348    *
 349    * @param filename The name of the file containing the Diffie-Hellman
 350    * parameters. The file must use the PEM format.
 351    *
 352    * @throws boost::system::system_error Thrown on failure.
 353    */
 354   void use_tmp_dh_file(const std::string& filename)
 355   {
 356     boost::system::error_code ec;
 357     service_.use_tmp_dh_file(impl_, filename, ec);
 358     boost::asio::detail::throw_error(ec);
 359   }
 360
 361   /// Use the specified file to obtain the temporary Diffie-Hellman parameters.
 362   /**
 363    * This function is used to load Diffie-Hellman parameters into the context
 364    * from a file.
 365    *
 366    * @param filename The name of the file containing the Diffie-Hellman
 367    * parameters. The file must use the PEM format.
 368    *
 369    * @param ec Set to indicate what error occurred, if any.
 370    */
 371   boost::system::error_code use_tmp_dh_file(const std::string& filename,
 372       boost::system::error_code& ec)
 373   {
 374     return service_.use_tmp_dh_file(impl_, filename, ec);
 375   }
 376
 377   /// Set the password callback.
 378   /**
 379    * This function is used to specify a callback function to obtain password
 380    * information about an encrypted key in PEM format.
 381    *
 382    * @param callback The function object to be used for obtaining the password.
 383    * The function signature of the handler must be:
 384    * @code std::string password_callback(
 385    *   std::size_t max_length,  // The maximum size for a password.
 386    *   password_purpose purpose // Whether password is for reading or writing.
 387    * ); @endcode
 388    * The return value of the callback is a string containing the password.
 389    *
 390    * @throws boost::system::system_error Thrown on failure.
 391    */
 392   template <typename PasswordCallback>
 393   void set_password_callback(PasswordCallback callback)
 394   {
 395     boost::system::error_code ec;
 396     service_.set_password_callback(impl_, callback, ec);
 397     boost::asio::detail::throw_error(ec);
 398   }
 399
 400   /// Set the password callback.
 401   /**
 402    * This function is used to specify a callback function to obtain password
 403    * information about an encrypted key in PEM format.
 404    *
 405    * @param callback The function object to be used for obtaining the password.
 406    * The function signature of the handler must be:
 407    * @code std::string password_callback(
 408    *   std::size_t max_length,  // The maximum size for a password.
 409    *   password_purpose purpose // Whether password is for reading or writing.
 410    * ); @endcode
 411    * The return value of the callback is a string containing the password.
 412    *
 413    * @param ec Set to indicate what error occurred, if any.
 414    */
 415   template <typename PasswordCallback>
 416   boost::system::error_code set_password_callback(PasswordCallback callback,
 417       boost::system::error_code& ec)
 418   {
 419     return service_.set_password_callback(impl_, callback, ec);
 420   }
 421
 422 private:
 423   /// The backend service implementation.
 424   service_type& service_;
 425
 426   /// The underlying native implementation.
 427   impl_type impl_;
 428 };
 429
 430 } // namespace ssl
 431 } // namespace asio
 432 } // namespace boost
 433
 434 #include <boost/asio/detail/pop_options.hpp>
 435
 436 #endif // BOOST_ASIO_SSL_BASIC_CONTEXT_HPP