• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1[/
2 / Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com)
3 /
4 / Distributed under the Boost Software License, Version 1.0. (See accompanying
5 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6 /]
7
8[section:ssl SSL]
9
10Boost.Asio contains classes and class templates for basic SSL support. These classes
11allow encrypted communication to be layered on top of an existing stream, such
12as a TCP socket.
13
14Before creating an encrypted stream, an application must construct an SSL
15context object. This object is used to set SSL options such as verification
16mode, certificate files, and so on. As an illustration, client-side
17initialisation may look something like:
18
19  ssl::context ctx(ssl::context::sslv23);
20  ctx.set_verify_mode(ssl::verify_peer);
21  ctx.load_verify_file("ca.pem");
22
23To use SSL with a TCP socket, one may write:
24
25  ssl::stream<ip::tcp::socket> ssl_sock(my_io_context, ctx);
26
27To perform socket-specific operations, such as establishing an outbound
28connection or accepting an incoming one, the underlying socket must first be
29obtained using the `ssl::stream` template's [link
30boost_asio.reference.ssl__stream.lowest_layer `lowest_layer()`] member function:
31
32  ip::tcp::socket::lowest_layer_type& sock = ssl_sock.lowest_layer();
33  sock.connect(my_endpoint);
34
35In some use cases the underlying stream object will need to have a longer
36lifetime than the SSL stream, in which case the template parameter should be a
37reference to the stream type:
38
39  ip::tcp::socket sock(my_io_context);
40  ssl::stream<ip::tcp::socket&> ssl_sock(sock, ctx);
41
42SSL handshaking must be performed prior to transmitting or receiving data over
43an encrypted connection. This is accomplished using the `ssl::stream`
44template's [link boost_asio.reference.ssl__stream.handshake handshake()] or [link
45boost_asio.reference.ssl__stream.async_handshake async_handshake()] member functions.
46
47Once connected, SSL stream objects are used as synchronous or asynchronous read
48and write streams. This means the objects can be used with any of the [link
49boost_asio.reference.read read()], [link boost_asio.reference.async_read async_read()],
50[link boost_asio.reference.write write()], [link boost_asio.reference.async_write
51async_write()], [link boost_asio.reference.read_until read_until()] or [link
52boost_asio.reference.async_read_until async_read_until()] free functions.
53
54[heading Certificate Verification]
55
56Boost.Asio provides various methods for configuring the way SSL certificates are
57verified:
58
59* [link boost_asio.reference.ssl__context.set_default_verify_paths ssl::context::set_default_verify_paths()]
60* [link boost_asio.reference.ssl__context.set_verify_mode ssl::context::set_verify_mode()]
61* [link boost_asio.reference.ssl__context.set_verify_callback ssl::context::set_verify_callback()]
62* [link boost_asio.reference.ssl__context.load_verify_file ssl::context::load_verify_file()]
63* [link boost_asio.reference.ssl__stream.set_verify_mode ssl::stream::set_verify_mode()]
64* [link boost_asio.reference.ssl__stream.set_verify_callback ssl::stream::set_verify_callback()]
65
66To simplify use cases where certificates are verified according to the rules in
67RFC 6125 (identity verification in the context of Transport Layer Security),
68Boost.Asio provides a reusable verification callback as a function object:
69
70* [link boost_asio.reference.ssl__host_name_verification ssl::host_name_verification]
71
72The following example shows verification of a remote host's certificate
73according to the rules used by HTTPS:
74
75  using boost::asio::ip::tcp;
76  namespace ssl = boost::asio::ssl;
77  typedef ssl::stream<tcp::socket> ssl_socket;
78
79  // Create a context that uses the default paths for
80  // finding CA certificates.
81  ssl::context ctx(ssl::context::sslv23);
82  ctx.set_default_verify_paths();
83
84  // Open a socket and connect it to the remote host.
85  boost::asio::io_context io_context;
86  ssl_socket sock(io_context, ctx);
87  tcp::resolver resolver(io_context);
88  tcp::resolver::query query("host.name", "https");
89  boost::asio::connect(sock.lowest_layer(), resolver.resolve(query));
90  sock.lowest_layer().set_option(tcp::no_delay(true));
91
92  // Perform SSL handshake and verify the remote host's
93  // certificate.
94  sock.set_verify_mode(ssl::verify_peer);
95  sock.set_verify_callback(ssl::host_name_verification("host.name"));
96  sock.handshake(ssl_socket::client);
97
98  // ... read and write as normal ...
99
100[heading SSL and Threads]
101
102SSL stream objects perform no locking of their own. Therefore, it is essential
103that all asynchronous SSL operations are performed in an implicit or explicit
104[link boost_asio.overview.core.strands strand]. Note that this means that no
105synchronisation is required (and so no locking overhead is incurred) in single
106threaded programs.
107
108[heading See Also]
109
110[link boost_asio.reference.ssl__context ssl::context],
111[link boost_asio.reference.ssl__host_name_verification ssl::host_name_verification],
112[link boost_asio.reference.ssl__stream ssl::stream],
113[link boost_asio.examples.cpp03_examples.ssl SSL example (C++03)],
114[link boost_asio.examples.cpp11_examples.ssl SSL example (C++11)].
115
116[heading Notes]
117
118[@http://www.openssl.org OpenSSL] is required to make use of Boost.Asio's SSL
119support. When an application needs to use OpenSSL functionality that is not
120wrapped by Boost.Asio, the underlying OpenSSL types may be obtained by calling [link
121boost_asio.reference.ssl__context.native_handle `ssl::context::native_handle()`] or
122[link boost_asio.reference.ssl__stream.native_handle `ssl::stream::native_handle()`].
123
124[endsect]
125