summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/asio/src/doc/overview/ssl.qbk
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/asio/src/doc/overview/ssl.qbk')
-rw-r--r--3rdparty/asio/src/doc/overview/ssl.qbk123
1 files changed, 123 insertions, 0 deletions
diff --git a/3rdparty/asio/src/doc/overview/ssl.qbk b/3rdparty/asio/src/doc/overview/ssl.qbk
new file mode 100644
index 00000000000..e5a4d73c010
--- /dev/null
+++ b/3rdparty/asio/src/doc/overview/ssl.qbk
@@ -0,0 +1,123 @@
+[/
+ / Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:ssl SSL]
+
+Asio contains classes and class templates for basic SSL support. These classes
+allow encrypted communication to be layered on top of an existing stream, such
+as a TCP socket.
+
+Before creating an encrypted stream, an application must construct an SSL
+context object. This object is used to set SSL options such as verification
+mode, certificate files, and so on. As an illustration, client-side
+initialisation may look something like:
+
+ ssl::context ctx(ssl::context::sslv23);
+ ctx.set_verify_mode(ssl::verify_peer);
+ ctx.load_verify_file("ca.pem");
+
+To use SSL with a TCP socket, one may write:
+
+ ssl::stream<ip::tcp::socket> ssl_sock(my_io_context, ctx);
+
+To perform socket-specific operations, such as establishing an outbound
+connection or accepting an incoming one, the underlying socket must first be
+obtained using the `ssl::stream` template's [link
+asio.reference.ssl__stream.lowest_layer `lowest_layer()`] member function:
+
+ ip::tcp::socket::lowest_layer_type& sock = ssl_sock.lowest_layer();
+ sock.connect(my_endpoint);
+
+In some use cases the underlying stream object will need to have a longer
+lifetime than the SSL stream, in which case the template parameter should be a
+reference to the stream type:
+
+ ip::tcp::socket sock(my_io_context);
+ ssl::stream<ip::tcp::socket&> ssl_sock(sock, ctx);
+
+SSL handshaking must be performed prior to transmitting or receiving data over
+an encrypted connection. This is accomplished using the `ssl::stream`
+template's [link asio.reference.ssl__stream.handshake handshake()] or [link
+asio.reference.ssl__stream.async_handshake async_handshake()] member functions.
+
+Once connected, SSL stream objects are used as synchronous or asynchronous read
+and write streams. This means the objects can be used with any of the [link
+asio.reference.read read()], [link asio.reference.async_read async_read()],
+[link asio.reference.write write()], [link asio.reference.async_write
+async_write()], [link asio.reference.read_until read_until()] or [link
+asio.reference.async_read_until async_read_until()] free functions.
+
+[heading Certificate Verification]
+
+Asio provides various methods for configuring the way SSL certificates are
+verified:
+
+* [link asio.reference.ssl__context.set_default_verify_paths ssl::context::set_default_verify_paths()]
+* [link asio.reference.ssl__context.set_verify_mode ssl::context::set_verify_mode()]
+* [link asio.reference.ssl__context.set_verify_callback ssl::context::set_verify_callback()]
+* [link asio.reference.ssl__context.load_verify_file ssl::context::load_verify_file()]
+* [link asio.reference.ssl__stream.set_verify_mode ssl::stream::set_verify_mode()]
+* [link asio.reference.ssl__stream.set_verify_callback ssl::stream::set_verify_callback()]
+
+To simplify use cases where certificates are verified according to the rules in
+RFC 2818 (certificate verification for HTTPS), Asio provides a reusable
+verification callback as a function object:
+
+* [link asio.reference.ssl__rfc2818_verification ssl::rfc2818_verification]
+
+The following example shows verification of a remote host's certificate
+according to the rules used by HTTPS:
+
+ using asio::ip::tcp;
+ namespace ssl = asio::ssl;
+ typedef ssl::stream<tcp::socket> ssl_socket;
+
+ // Create a context that uses the default paths for
+ // finding CA certificates.
+ ssl::context ctx(ssl::context::sslv23);
+ ctx.set_default_verify_paths();
+
+ // Open a socket and connect it to the remote host.
+ asio::io_context io_context;
+ ssl_socket sock(io_context, ctx);
+ tcp::resolver resolver(io_context);
+ tcp::resolver::query query("host.name", "https");
+ asio::connect(sock.lowest_layer(), resolver.resolve(query));
+ sock.lowest_layer().set_option(tcp::no_delay(true));
+
+ // Perform SSL handshake and verify the remote host's
+ // certificate.
+ sock.set_verify_mode(ssl::verify_peer);
+ sock.set_verify_callback(ssl::rfc2818_verification("host.name"));
+ sock.handshake(ssl_socket::client);
+
+ // ... read and write as normal ...
+
+[heading SSL and Threads]
+
+SSL stream objects perform no locking of their own. Therefore, it is essential
+that all asynchronous SSL operations are performed in an implicit or explicit
+[link asio.overview.core.strands strand]. Note that this means that no
+synchronisation is required (and so no locking overhead is incurred) in single
+threaded programs.
+
+[heading See Also]
+
+[link asio.reference.ssl__context ssl::context],
+[link asio.reference.ssl__rfc2818_verification ssl::rfc2818_verification],
+[link asio.reference.ssl__stream ssl::stream],
+[link asio.examples.cpp03_examples.ssl SSL example].
+
+[heading Notes]
+
+[@http://www.openssl.org OpenSSL] is required to make use of Asio's SSL
+support. When an application needs to use OpenSSL functionality that is not
+wrapped by Asio, the underlying OpenSSL types may be obtained by calling [link
+asio.reference.ssl__context.native_handle `ssl::context::native_handle()`] or
+[link asio.reference.ssl__stream.native_handle `ssl::stream::native_handle()`].
+
+[endsect]