boostorg/beast
1
0
Fork 1
mirror of https://github.com/boostorg/beast.git synced 2025-08-03 14:54:32 +02:00
Code Issues Packages Projects Releases Wiki Activity

Documentation work

Browse Source
This commit is contained in:
Vinnie Falco
2018-12-01 13:22:21 -08:00
parent 773048c551
commit 7005f6b918
8 changed files with 134 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGELOG.md
View File

@@ -2,6 +2,7 @@ Version 195:
* net is a namespace alias for boost::asio
* Simplify multi_buffer and static_buffer sequences
* Documentation work
--------------------------------------------------------------------------------

22
doc/qbk/00_main.qbk
View File

@@ -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]]]

87
doc/qbk/01_intro.qbk
View File

@@ -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'''<?dbhtml stop-chunking?>''']
[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'''
<mediaobject>
<videoobject>
<videodata fileref="https://www.youtube.com/embed/4TtyYbGDAj0?rel=0"
align="center" contentwidth="560" contentdepth="315"/>
</videoobject>
</mediaobject>
''']
[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]

70
doc/qbk/01_intro/1_reports.qbk Normal file
View File

@@ -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'''<?dbhtml stop-chunking?>''']
[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'''
<mediaobject>
<videoobject>
<videodata fileref="https://www.youtube.com/embed/4TtyYbGDAj0?rel=0"
align="center" contentwidth="560" contentdepth="315"/>
</videoobject>
</mediaobject>
''']
[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]

6
doc/qbk/03_core.qbk
View File

@@ -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]

12
doc/qbk/03_core/1_asio.qbk
View File

@@ -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::asio::ip::tcp::socket>`]
[@boost:/doc/html/boost_asio/reference/ssl__stream.html `net::ssl::stream<tcp::socket>`]
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<boost::asio::ip::tcp::socket>`]
[link beast.ref.boost__beast__websocket__stream `websocket::stream<tcp::socket>`]
which is already connected with a remote host.
]]
]

13
doc/qbk/03_core/2_streams.qbk
View File

@@ -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]]

19
test/doc/core_snippets.cpp
View File

@@ -11,6 +11,7 @@
#include <boost/beast/core.hpp>
#include <boost/asio.hpp>
#include <boost/asio/ssl.hpp>
#include <iostream>
#include <thread>
@@ -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.