Skip to content

Add documentation for SSL support #398

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 22, 2014
Merged

Add documentation for SSL support #398

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c8908c1
Add documentation for SSL support
jellevdd May 21, 2014
f264f25
Update to documentation/add example
jellevdd May 21, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Add documentation for SSL support
  • Loading branch information
@jellevdd
jellevdd committed May 21, 2014
commit c8908c11d434c44ce35e426647940c904afdaa83
2 changes: 1 addition & 1 deletion libs/network/doc/html/.buildinfo
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: ae3dc7fdd27083cd0960e8fba1dd2084
config: 247e8c3d216dc851efe8ee3a759ed678
tags: 645f666f9bcd5a90fca523b33c5a78b7
78 changes: 44 additions & 34 deletions libs/network/doc/html/_sources/reference/http_client.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,40 +168,50 @@ initialization.
Constructor taking a ``client_options<Tag>`` object. The following table
shows the options you can set on a ``client_options<Tag>`` instance.

+---------------------+----------------------------+--------------------------+
| Parameter Name | Type | Description |
+=====================+============================+==========================+
| follow_redirects | ``bool`` | Boolean to specify |
| | | whether the client |
| | | should follow HTTP |
| | | redirects. Default is |
| | | ``false``. |
+---------------------+----------------------------+--------------------------+
| cache_resolved | ``bool`` | Boolean to specify |
| | | whether the client |
| | | should cache resolved |
| | | endpoints. The default |
| | | is ``false``. |
+---------------------+----------------------------+--------------------------+
| io_service | ``shared_ptr<io_service>`` | Shared pointer to a |
| | | Boost.Asio |
| | | ``io_service``. |
+---------------------+----------------------------+--------------------------+
| openssl_certificate | ``string`` | The filename of the |
| | | certificate to load for |
| | | the SSL connection for |
| | | verification. |
+---------------------+----------------------------+--------------------------+
| openssl_verify_path | ``string`` | The directory from |
| | | which the certificate |
| | | authority files are |
| | | located. |
+---------------------+----------------------------+--------------------------+
| always_verify_peer | ``bool`` | Boolean to specify |
| | | whether the client |
| | | should always verify |
| | | peers in SSL connections |
+---------------------+----------------------------+--------------------------+
+--------------------------+----------------------------+--------------------------+
| Parameter Name | Type | Description |
+==========================+============================+==========================+
| follow_redirects | ``bool`` | Boolean to specify |
| | | whether the client |
| | | should follow HTTP |
| | | redirects. Default is |
| | | ``false``. |
+--------------------------+----------------------------+--------------------------+
| cache_resolved | ``bool`` | Boolean to specify |
| | | whether the client |
| | | should cache resolved |
| | | endpoints. The default |
| | | is ``false``. |
+--------------------------+----------------------------+--------------------------+
| io_service | ``shared_ptr<io_service>`` | Shared pointer to a |
| | | Boost.Asio |
| | | ``io_service``. |
+--------------------------+----------------------------+--------------------------+
| openssl_certificate | ``string`` | The filename of the |
| | | certificate to load for |
| | | the SSL connection for |
| | | verification. |
+--------------------------+----------------------------+--------------------------+
| openssl_verify_path | ``string`` | The directory from |
| | | which the certificate |
| | | authority files are |
| | | located. |
+--------------------------+----------------------------+--------------------------+
| always_verify_peer | ``bool`` | Boolean to specify |
| | | whether the client |
| | | should always verify |
| | | peers in SSL connections |
+--------------------------+----------------------------+--------------------------+
| openssl_certificate_file | ``string`` | Filename of the |
| | | certificate to use for |
| | | client-side SSL session |
| | | establishment. |
+--------------------------+----------------------------+--------------------------+
| openssl_private_key_file | ``string`` | Filename of the |
| | | private key to use for |
| | | client-side SSL session |
| | | establishment. |
+--------------------------+----------------------------+--------------------------+


To use the above supported named parameters, you'll have code that looks like
Expand Down
36 changes: 36 additions & 0 deletions libs/network/doc/html/_sources/reference/http_server.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,6 +217,9 @@ Constructor
| linger_timeout | ``int`` | An optional int to define the timeout to wait for socket closes before it is set to linger. |
| | | The default is ``0``. |
+-----------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+
| context | ``shared_ptr<context>`` | An optional shared pointer to an instance of ``boost::asio::ssl::context`` -- this contains the |
| | | settings needed to support SSL. This parameter is only applicable for ``async_server`` instances.|
+-----------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+

To use the above supported named parameters, you'll have code that looks like the following:

Expand Down Expand Up @@ -524,6 +527,39 @@ primary means for reading from and writing to the connection.
The function throws an instance of ``std::logic_error`` if you try to set
the headers for a connection more than once.

Adding SSL support to Asynchronous Server
-----------------------------------------

In order to setup SSL support for an Asynchronous Server, it is best to start from
a regular Asynchronous Server (see above). Once this server is setup, SSL can be
enabled by adding a Boost.Asio.Ssl.Context_ to the options. The settings that can be
used are defined in the link.

.. code-block:: c++

boost::shared_ptr<boost::asio::ssl::context> ctx = boost::make_shared<boost::asio::ssl::context>(boost::asio::ssl::context::sslv23);
ctx->set_options(
boost::asio::ssl::context::default_workarounds
| boost::asio::ssl::context::no_sslv2
| boost::asio::ssl::context::single_dh_use);
context_.set_password_callback(boost::bind(&server::get_password, this));
context_.use_certificate_chain_file("server.pem");
context_.use_private_key_file("server.pem", boost::asio::ssl::context::pem);
context_.use_tmp_dh_file("dh512.pem");

handler_type handler;
http_server::options options(handler);
options.thread_pool(boost::make_shared<boost::network::utils::thread_pool>(2));
http_server server(options.address("127.0.0.1").port("8000").context(ctx));


.. code-block:: c++

std::string get_password() const
{
return "test";
}

.. _Boost.Range: http://www.boost.org/libs/range
.. _Boost.Function: http://www.boost.org/libs/function
.. _Boost.Asio.SSL.Context: http://www.boost.org/doc/libs/1_55_0/doc/html/boost_asio/reference/ssl__context.html
4 changes: 4 additions & 0 deletions libs/network/doc/html/_sources/whats_new.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,11 @@ v0.11.0
``cpp-netlib-utils_base64_test`` still fails in this platform. (`#287`_)
* Provide a client option to always validate peers for HTTPS requests made by
the client. (`#349`_)
* Back-port fix for `#163`_ for improved URI parsing.
* Added support for client-side certificates and private keys (`#361`_).

.. _`#129`: https://github.com/cpp-netlib/cpp-netlib/issues/129
.. _`#163`: https://github.com/cpp-netlib/cpp-netlib/issues/163
.. _`#245`: https://github.com/cpp-netlib/cpp-netlib/issues/245
.. _`#277`: https://github.com/cpp-netlib/cpp-netlib/issues/277
.. _`#279`: https://github.com/cpp-netlib/cpp-netlib/issues/279
Expand All @@ -40,6 +43,7 @@ v0.11.0
.. _`#349`: https://github.com/cpp-netlib/cpp-netlib/issues/349
.. _`#69`: https://github.com/cpp-netlib/cpp-netlib/issues/69
.. _`#86`: https://github.com/cpp-netlib/cpp-netlib/issues/86
.. _`#361`: https://github.com/cpp-netlib/cpp-netlib/pull/361

:mod:`cpp-netlib` 0.10
----------------------
Expand Down
3 changes: 2 additions & 1 deletion libs/network/doc/html/_static/basic.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
*
* Sphinx stylesheet -- basic theme.
*
* :copyright: Copyright 2007-2013 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
Expand Down Expand Up @@ -89,6 +89,7 @@ div.sphinxsidebar #searchbox input[type="submit"] {

img {
border: 0;
max-width: 100%;
}

/* -- search page ----------------------------------------------------------- */
Expand Down
5 changes: 4 additions & 1 deletion libs/network/doc/html/_static/doctools.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
*
* Sphinx JavaScript utilities for all documentation.
*
* :copyright: Copyright 2007-2013 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
Expand Down Expand Up @@ -168,6 +168,9 @@ var Documentation = {
var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : [];
if (terms.length) {
var body = $('div.body');
if (!body.length) {
body = $('body');
}
window.setTimeout(function() {
$.each(terms, function() {
body.highlightText(this.toLowerCase(), 'highlighted');
Expand Down
2 changes: 1 addition & 1 deletion libs/network/doc/html/_static/epub.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
*
* Sphinx stylesheet -- default theme.
*
* :copyright: Copyright 2007-2013 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
Expand Down
2 changes: 1 addition & 1 deletion libs/network/doc/html/_static/pyramid.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
*
* Sphinx stylesheet -- pylons theme.
*
* :copyright: Copyright 2007-2013 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
Expand Down
6 changes: 3 additions & 3 deletions libs/network/doc/html/_static/searchtools.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
*
* Sphinx JavaScript utilties for the full-text search.
*
* :copyright: Copyright 2007-2013 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
Expand Down Expand Up @@ -330,13 +330,13 @@ var Search = {
objectterms.push(tmp[i].toLowerCase());
}

if ($u.indexOf(stopwords, tmp[i]) != -1 || tmp[i].match(/^\d+$/) ||
if ($u.indexOf(stopwords, tmp[i].toLowerCase()) != -1 || tmp[i].match(/^\d+$/) ||
tmp[i] === "") {
// skip this "word"
continue;
}
// stem the word
var word = stemmer.stemWord(tmp[i]).toLowerCase();
var word = stemmer.stemWord(tmp[i].toLowerCase());
var toAppend;
// select the correct list
if (word[0] == '-') {
Expand Down
2 changes: 1 addition & 1 deletion libs/network/doc/html/_static/websupport.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
*
* sphinx.websupport utilties for all documentation.
*
* :copyright: Copyright 2007-2013 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
Expand Down
5 changes: 3 additions & 2 deletions libs/network/doc/html/contents.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,7 @@ <h3>Navigation</h3>
<li class="toctree-l4"><a class="reference internal" href="reference/http_server.html#id5">API Documentation</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="reference/http_server.html#adding-ssl-support-to-asynchronous-server">Adding SSL support to Asynchronous Server</a></li>
</ul>
</li>
</ul>
Expand Down Expand Up @@ -279,8 +280,8 @@ <h3>Navigation</h3>
</div>
<div class="footer">
&copy; Copyright 2008-2013, Glyn Matthews, Dean Michael Berris; 2013 Google, Inc..
Last updated on Jan 25, 2014.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.
Last updated on May 21, 2014.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>
8 changes: 3 additions & 5 deletions libs/network/doc/html/examples.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,9 +87,7 @@ <h2>HTTP examples<a class="headerlink" href="#http-examples" title="Permalink to
<h3><a href="contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Examples</a><ul>
<li><a class="reference internal" href="#http-examples">HTTP examples</a><ul>
</ul>
</li>
<li><a class="reference internal" href="#http-examples">HTTP examples</a></li>
</ul>
</li>
</ul>
Expand Down Expand Up @@ -131,8 +129,8 @@ <h3>Navigation</h3>
</div>
<div class="footer">
&copy; Copyright 2008-2013, Glyn Matthews, Dean Michael Berris; 2013 Google, Inc..
Last updated on Dec 21, 2013.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.
Last updated on May 21, 2014.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>
4 changes: 2 additions & 2 deletions libs/network/doc/html/examples/http/atom_reader.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,8 +175,8 @@ <h3>Navigation</h3>
</div>
<div class="footer">
&copy; Copyright 2008-2013, Glyn Matthews, Dean Michael Berris; 2013 Google, Inc..
Last updated on Dec 21, 2013.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.
Last updated on May 21, 2014.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>
4 changes: 2 additions & 2 deletions libs/network/doc/html/examples/http/hello_world_client.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -192,8 +192,8 @@ <h3>Navigation</h3>
</div>
<div class="footer">
&copy; Copyright 2008-2013, Glyn Matthews, Dean Michael Berris; 2013 Google, Inc..
Last updated on Dec 21, 2013.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.
Last updated on May 21, 2014.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>
4 changes: 2 additions & 2 deletions libs/network/doc/html/examples/http/hello_world_server.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -233,8 +233,8 @@ <h3>Navigation</h3>
</div>
<div class="footer">
&copy; Copyright 2008-2013, Glyn Matthews, Dean Michael Berris; 2013 Google, Inc..
Last updated on Dec 21, 2013.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.
Last updated on May 21, 2014.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>
4 changes: 2 additions & 2 deletions libs/network/doc/html/examples/http/http_client.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -206,8 +206,8 @@ <h3>Navigation</h3>
</div>
<div class="footer">
&copy; Copyright 2008-2013, Glyn Matthews, Dean Michael Berris; 2013 Google, Inc..
Last updated on Dec 21, 2013.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.
Last updated on May 21, 2014.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>
4 changes: 2 additions & 2 deletions libs/network/doc/html/examples/http/simple_wget.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,8 +203,8 @@ <h3>Navigation</h3>
</div>
<div class="footer">
&copy; Copyright 2008-2013, Glyn Matthews, Dean Michael Berris; 2013 Google, Inc..
Last updated on Dec 21, 2013.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.
Last updated on May 21, 2014.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>
4 changes: 2 additions & 2 deletions libs/network/doc/html/examples/http/twitter_search.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,8 +209,8 @@ <h3>Navigation</h3>
</div>
<div class="footer">
&copy; Copyright 2008-2013, Glyn Matthews, Dean Michael Berris; 2013 Google, Inc..
Last updated on Dec 21, 2013.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.
Last updated on May 21, 2014.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>
Loading