diff --git a/CHANGELOG.md b/CHANGELOG.md index faf23487..5421a8c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ Version 195: * net is a namespace alias for boost::asio * Simplify multi_buffer and static_buffer sequences +* Documentation work -------------------------------------------------------------------------------- diff --git a/doc/qbk/00_main.qbk b/doc/qbk/00_main.qbk index a2f85977..b9fcad8e 100644 --- a/doc/qbk/00_main.qbk +++ b/doc/qbk/00_main.qbk @@ -40,17 +40,17 @@ [def __asio_handler_allocate__ [@boost:/doc/html/boost_asio/reference/asio_handler_allocate.html `asio_handler_allocate`]] [def __asio_handler_invoke__ [@boost:/doc/html/boost_asio/reference/asio_handler_invoke.html `asio_handler_invoke`]] [def __deduced__ [@boost:/doc/html/boost_asio/reference/asynchronous_operations.html#boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]] -[def __executor_work_guard__ [@boost:/doc/html/boost_asio/reference/executor_work_guard.html `boost::asio::executor_work_guard`]] -[def __get_associated_allocator__ [@boost:/doc/html/boost_asio/reference/get_associated_allocator.html `get_associated_allocator`]] -[def __get_associated_executor__ [@boost:/doc/html/boost_asio/reference/get_associated_executor.html `get_associated_executor`]] -[def __io_context__ [@boost:/doc/html/boost_asio/reference/io_context.html `boost::asio::io_context`]] -[def __post__ [@boost:/doc/html/boost_asio/reference/post.html `boost::asio::post`]] -[def __socket__ [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `boost::asio::ip::tcp::socket`]] -[def __ssl_context__ [@boost:/doc/html/boost_asio/reference/ssl__context.html `boost::asio::ssl::context`]] -[def __ssl_stream__ [@boost:/doc/html/boost_asio/reference/ssl__stream.html `boost::asio::ssl::stream`]] -[def __streambuf__ [@boost:/doc/html/boost_asio/reference/streambuf.html `boost::asio::streambuf`]] -[def __use_future__ [@boost:/doc/html/boost_asio/reference/use_future_t.html `boost::asio::use_future`]] -[def __yield_context__ [@boost:/doc/html/boost_asio/reference/yield_context.html `boost::asio::yield_context`]] +[def __executor_work_guard__ [@boost:/doc/html/boost_asio/reference/executor_work_guard.html `net::executor_work_guard`]] +[def __get_associated_allocator__ [@boost:/doc/html/boost_asio/reference/get_associated_allocator.html `net::get_associated_allocator`]] +[def __get_associated_executor__ [@boost:/doc/html/boost_asio/reference/get_associated_executor.html `net::get_associated_executor`]] +[def __io_context__ [@boost:/doc/html/boost_asio/reference/io_context.html `net::io_context`]] +[def __post__ [@boost:/doc/html/boost_asio/reference/post.html `net::post`]] +[def __socket__ [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `tcp::socket`]] +[def __ssl_context__ [@boost:/doc/html/boost_asio/reference/ssl__context.html `net::ssl::context`]] +[def __ssl_stream__ [@boost:/doc/html/boost_asio/reference/ssl__stream.html `net::ssl::stream`]] +[def __streambuf__ [@boost:/doc/html/boost_asio/reference/streambuf.html `net::streambuf`]] +[def __use_future__ [@boost:/doc/html/boost_asio/reference/use_future_t.html `net::use_future`]] +[def __yield_context__ [@boost:/doc/html/boost_asio/reference/yield_context.html `net::yield_context`]] [def __AsyncReadStream__ [@boost:/doc/html/boost_asio/reference/AsyncReadStream.html [*AsyncReadStream]]] [def __AsyncWriteStream__ [@boost:/doc/html/boost_asio/reference/AsyncWriteStream.html [*AsyncWriteStream]]] diff --git a/doc/qbk/01_intro.qbk b/doc/qbk/01_intro.qbk index 9a680efb..28faddd6 100644 --- a/doc/qbk/01_intro.qbk +++ b/doc/qbk/01_intro.qbk @@ -60,16 +60,27 @@ Beast requires: * [*Boost:] Beast only works with Boost, not stand-alone Asio * [*OpenSSL:] Optional, for using TLS/Secure sockets. -Supported compilers: msvc-14+, gcc 4.8+, clang 3.6+ +Tested with these compilers: msvc-14+, gcc 4.8.4+, clang 3.6+. -Sources are [*header-only]. -To link a program using Beast successfully, add the -[@boost:/libs/system/index.html Boost.System] -library to your build scripts. If you use coroutines you'll also need the +Sources are [*header-only]. Adding additional libraries to the +linking step for your programs to use Beast is normally not +necessary, except for these cases: + +* When using coroutines created by calling +[@boost:/doc/html/boost_asio/reference/spawn.html `boost::asio::spawn`], +you will need to add the [@boost:/libs/coroutine/index.html Boost.Coroutine] -library. Please visit the -[@boost:/more/getting_started.html Boost documentation] -for instructions on how to do this for your particular build system. +library to your program. + +* When using +[@boost:/doc/html/boost_asio/reference/ssl__stream.html `boost::asio::ssl::stream`], +you will need to add the +[@https://www.openssl.org/ OpenSSL] +library to your program. + +Please visit the [@boost:/more/getting_started.html Boost documentation] +for instructions on how to build and link with Boost libraries for your +particular environment system. [endsect] @@ -115,8 +126,8 @@ Many thanks to [@http://www.boost.org/users/people/glen_fernandes.html Glen Fernandes], and [@https://github.com/pdimov Peter Dimov] -for tirelessly answering questions on -[@https://cpplang.slack.com/ Cpplang-Slack]. +for tirelessly answering questions on the +[@https://slack.cpp.al/ C++ Language Slack Workspace]. Thanks to [@https://github.com/djarek Damian Jarek] @@ -126,58 +137,4 @@ for his generous participation and source code contributions. -[section Reports] -[block''''''] - -[section Security Review (Bishop Fox)] - -Since 2005, [@https://www.bishopfox.com/ Bishop Fox] has provided -security consulting services to the Fortune 1000, high-tech startups, -and financial institutions worldwide. -Beast engaged Bishop Fox to assess the security of the Boost C++ Beast HTTP/S -networking library. The following report details the findings identified during -the course of the engagement, which started on September 11, 2017. - -The assessment team conducted a hybrid application assessment of the Beast -library. Bishop Fox’s hybrid application assessment methodology leverages -the real-world attack techniques of application penetration testing in -combination with targeted source code review to thoroughly identify -application security vulnerabilities. These fullknowledge assessments -begin with automated scans of the deployed application and source code. -Next, analyses of the scan results are combined with manual review to -thoroughly identify potential application security vulnerabilities. In -addition, the team performs a review of the application architecture and -business logic to locate any design-level issues. Finally, the team performs -manual exploitation and review of these issues to validate the findings. - -[@https://vinniefalco.github.io/BeastAssets/Beast%20-%20Hybrid%20Application%20Assessment%202017%20-%20Assessment%20Report%20-%2020171114.pdf [*Beast - Hybrid Application Assessment 2017]] - -[block''' - - - - - -'''] - -[endsect] - -[section WebSocket (Autobahn|Testsuite)] - -The -[@https://github.com/crossbario/autobahn-testsuite Autobahn WebSockets Testsuite] -provides a fully automated test suite to -verify client and server implementations of The WebSocket Protocol -for specification conformance and implementation robustness. -The test suite will check an implementation by doing basic -WebSocket conversations, extensive protocol compliance -verification and performance and limits testing. -Autobahn|Testsuite is used across the industry and -contains over 500 test cases. - -[@https://vinniefalco.github.io/BeastAssets/reports/autobahn/index.html [*Autobahn|Testsuite WebSocket Results]] - -[endsect] - -[endsect] +[include 01_intro/1_reports.qbk] diff --git a/doc/qbk/01_intro/1_reports.qbk b/doc/qbk/01_intro/1_reports.qbk new file mode 100644 index 00000000..a3b37c05 --- /dev/null +++ b/doc/qbk/01_intro/1_reports.qbk @@ -0,0 +1,70 @@ +[/ + Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail 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) + + Official repository: https://github.com/boostorg/beast +] + +[section Reports] +[block''''''] + + + +[section Security Review (Bishop Fox)] + +Since 2005, [@https://www.bishopfox.com/ Bishop Fox] has provided +security consulting services to the Fortune 1000, high-tech startups, +and financial institutions worldwide. +Beast engaged Bishop Fox to assess the security of the Boost C++ Beast HTTP/S +networking library. The following report details the findings identified during +the course of the engagement, which started on September 11, 2017. + +The assessment team conducted a hybrid application assessment of the Beast +library. Bishop Fox’s hybrid application assessment methodology leverages +the real-world attack techniques of application penetration testing in +combination with targeted source code review to thoroughly identify +application security vulnerabilities. These fullknowledge assessments +begin with automated scans of the deployed application and source code. +Next, analyses of the scan results are combined with manual review to +thoroughly identify potential application security vulnerabilities. In +addition, the team performs a review of the application architecture and +business logic to locate any design-level issues. Finally, the team performs +manual exploitation and review of these issues to validate the findings. + +[@https://vinniefalco.github.io/BeastAssets/Beast%20-%20Hybrid%20Application%20Assessment%202017%20-%20Assessment%20Report%20-%2020171114.pdf [*Beast - Hybrid Application Assessment 2017]] + +[block''' + + + + + +'''] + +[endsect] + + + +[section WebSocket (Autobahn|Testsuite)] + +The +[@https://github.com/crossbario/autobahn-testsuite Autobahn WebSockets Testsuite] +provides a fully automated test suite to +verify client and server implementations of The WebSocket Protocol +for specification conformance and implementation robustness. +The test suite will check an implementation by doing basic +WebSocket conversations, extensive protocol compliance +verification and performance and limits testing. +Autobahn|Testsuite is used across the industry and +contains over 500 test cases. + +[@https://vinniefalco.github.io/BeastAssets/reports/autobahn/index.html [*Autobahn|Testsuite WebSocket Results]] + +[endsect] + + + +[endsect] diff --git a/doc/qbk/03_core.qbk b/doc/qbk/03_core.qbk index be7cf8c3..24ba3400 100644 --- a/doc/qbk/03_core.qbk +++ b/doc/qbk/03_core.qbk @@ -7,7 +7,7 @@ Official repository: https://github.com/boostorg/beast ] -[section:using_io Using I/O] +[section:using_io Using Core Facilities] This library makes I/O primitives used by the implementation publicly available so users can take advantage of them in their own libraries. @@ -16,6 +16,8 @@ and helpers for implementing asynchronous operations compatible with __Asio__ and described in __N3747__. This section lists these facilities by group, with descriptions. +[section Aliases and Abbreviations] + [important This documentation assumes familiarity with __Asio__. Sample code and identifiers used throughout are written as if the @@ -25,6 +27,8 @@ by group, with descriptions. [snippet_core_1b] ] +[endsect] + [include 03_core/1_asio.qbk] [include 03_core/2_streams.qbk] [include 03_core/3_buffers.qbk] diff --git a/doc/qbk/03_core/1_asio.qbk b/doc/qbk/03_core/1_asio.qbk index 5a18e41b..5149c387 100644 --- a/doc/qbk/03_core/1_asio.qbk +++ b/doc/qbk/03_core/1_asio.qbk @@ -7,7 +7,7 @@ Official repository: https://github.com/boostorg/beast ] -[section Asio Refresher] +[section:asio_refresher Networking Refresher] [warning Beast does not manage sockets, make outgoing connections, @@ -18,8 +18,8 @@ ] Library stream algorithms require a __socket__, __ssl_stream__, or other -__Stream__ object that has already established communication with an -endpoint. This example is provided as a reminder of how to work with +__Stream__ object that has already established communication with a remote +peer. This example is provided as a reminder of how to work with sockets: [snippet_core_2] @@ -39,21 +39,21 @@ special meaning: [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html [*`sock`]] ][ A variable of type - [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `boost::asio::ip::tcp::socket`] + [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `tcp::socket`] which has already been connected to a remote host. ]] [[ [@boost:/doc/html/boost_asio/reference/ssl__stream.html [*`ssl_sock`]] ][ A variable of type - [@boost:/doc/html/boost_asio/reference/ssl__stream.html `boost::asio::ssl::stream`] + [@boost:/doc/html/boost_asio/reference/ssl__stream.html `net::ssl::stream`] which is already connected and has handshaked with a remote host. ]] [[ [link beast.ref.boost__beast__websocket__stream [*`ws`]] ][ A variable of type - [link beast.ref.boost__beast__websocket__stream `websocket::stream`] + [link beast.ref.boost__beast__websocket__stream `websocket::stream`] which is already connected with a remote host. ]] ] diff --git a/doc/qbk/03_core/2_streams.qbk b/doc/qbk/03_core/2_streams.qbk index b2db0734..d9d20c01 100644 --- a/doc/qbk/03_core/2_streams.qbk +++ b/doc/qbk/03_core/2_streams.qbk @@ -9,13 +9,12 @@ [section Stream Types] -A __Stream__ is a communication channel where data is transferred as -an ordered sequence of octet buffers. Streams are either synchronous -or asynchronous, and may allow reading, writing, or both. Note that -a particular type may model more than one concept. For example, the -Asio types __socket__ and __ssl_stream__ support both __SyncStream__ -and __AsyncStream__. All stream algorithms in Beast are declared as -template functions using these concepts: +A __Stream__ is a communication channel where data is reliably transferred as +an ordered sequence of bytes. Streams are either synchronous or asynchronous, +and may allow reading, writing, or both. Note that a particular type may model +more than one concept. For example, the networking types __socket__ and +__ssl_stream__ support both __SyncStream__ and __AsyncStream__. All stream +algorithms in Beast are declared as template functions using these concepts: [table Stream Concepts [[Concept][Description]] diff --git a/test/doc/core_snippets.cpp b/test/doc/core_snippets.cpp index 92923c13..9acfb912 100644 --- a/test/doc/core_snippets.cpp +++ b/test/doc/core_snippets.cpp @@ -11,6 +11,7 @@ #include #include +#include #include #include @@ -25,13 +26,16 @@ void fxx() //[snippet_core_1b // using namespace boost::beast; +namespace net = boost::asio; +namespace ssl = boost::asio::ssl; +using tcp = net::ip::tcp; net::io_context ioc; auto work = net::make_work_guard(ioc); std::thread t{[&](){ ioc.run(); }}; error_code ec; -net::ip::tcp::socket sock{ioc}; +tcp::socket sock{ioc}; //] boost::ignore_unused(ec); @@ -39,11 +43,14 @@ net::ip::tcp::socket sock{ioc}; { //[snippet_core_2 -char const* const host = "www.example.com"; -net::ip::tcp::resolver r{ioc}; -net::ip::tcp::socket stream{ioc}; -auto const results = r.resolve(host, "http"); -net::connect(stream, results.begin(), results.end()); +// The resolver is used to look up IP addresses and port numbers from a domain and service name pair +tcp::resolver r{ioc}; + +// A socket represents the local end of a connection between two peers +tcp::socket stream{ioc}; + +// Establish a connection before sending and receiving data +net::connect(stream, r.resolve("www.example.com", "http")); // At this point `stream` is a connected to a remote // host and may be used to perform stream operations.