=doc add client- and server-side HTTPS section for scala

akka-docs-dev/rst/scala/http/client-side/connection-level.rst

@@ -64,3 +64,8 @@ Currently Akka HTTP doesn't implement client-side request timeout checking itsel
 as a more general purpose streaming infrastructure feature.
 However, akka-stream should soon provide such a feature.
 
+
+Stand-Alone HTTP Layer Usage
+----------------------------
+
+// TODO

akka-docs-dev/rst/scala/http/client-side/https-support.rst

@@ -1,4 +1,40 @@
+.. _clientSideHTTPS:
+
 Client-Side HTTPS Support
 =========================
 
-TODO
+Akka HTTP supports TLS encryption on the client-side as well as on the :ref:`server-side <serverSideHTTPS>`.
+
+The central vehicle for configuring encryption is the ``HttpsContext``, which is defined as such:
+
+.. includecode2:: /../../akka-http-core/src/main/scala/akka/http/scaladsl/Http.scala
+   :snippet: https-context-impl
+
+In addition to the ``outgoingConnection``, ``newHostConnectionPool`` and ``cachedHostConnectionPool`` methods the
+`akka.http.scaladsl.Http`_ extension also defines ``outgoingConnectionTls``, ``newHostConnectionPoolTls`` and
+``cachedHostConnectionPoolTls``. These methods work identically to their counterparts without the ``-Tls`` suffix,
+with the exception that all connections will always be encrypted.
+
+The ``singleRequest`` and ``superPool`` methods determine the encryption state via the scheme of the incoming request,
+i.e. requests to an "https" URI will be encrypted, while requests to an "http" URI won't.
+
+The encryption configuration for all HTTPS connections, i.e. the ``HttpsContext`` is determined according to the
+following logic:
+
+1. If the optional ``httpContext`` method parameter is defined it contains the configuration to be used (and thus
+   takes precedence over any potentially set default client-side ``HttpsContext``).
+
+2. If the optional ``httpContext`` method parameter is undefined (which is the default) the default client-side
+   ``HttpsContext`` is used, which can be set via the ``setDefaultClientHttpsContext`` on the ``Http`` extension.
+
+3. If no default client-side ``HttpsContext`` has been set via the ``setDefaultClientHttpsContext`` on the ``Http``
+   extension the default system configuration is used.
+
+Usually the process is, if the default system TLS configuration is not good enough for your application's needs,
+that you configure a custom ``HttpsContext`` instance and set it via ``Http().setDefaultClientHttpsContext``.
+Afterwards you simply use ``outgoingConnectionTls``, ``newHostConnectionPoolTls``, ``cachedHostConnectionPoolTls``,
+``superPool`` or ``singleRequest`` without a specific ``httpContext`` argument, which causes encrypted connections
+to rely on the configured default client-side ``HttpsContext``.
+
+
+.. _akka.http.scaladsl.Http: @github@/akka-http-core/src/main/scala/akka/http/scaladsl/Http.scala

akka-docs-dev/rst/scala/http/low-level-server-side-api.rst

@@ -132,4 +132,25 @@ connection. An often times more convenient alternative is to explicitly add a ``
 connection when it has been sent out.
 
 
-// TODO: show an example of using the HTTP layer independently with a BidFlow join
+.. _serverSideHTTPS:
+
+Server-Side HTTPS Support
+-------------------------
+
+Akka HTTP supports TLS encryption on the server-side as well as on the :ref:`client-side <clientSideHTTPS>`.
+
+The central vehicle for configuring encryption is the ``HttpsContext``, which is defined as such:
+
+.. includecode2:: /../../akka-http-core/src/main/scala/akka/http/scaladsl/Http.scala
+   :snippet: https-context-impl
+
+On the server-side the ``bind``, and ``bindAndHandleXXX`` methods of the `akka.http.scaladsl.Http`_ extension define an
+optional ``httpsContext`` parameter, which can receive the HTTPS configuration in the form of an ``HttpsContext``
+instance.
+If defined encryption is enabled on all accepted connections. Otherwise it is disabled (which is the default).
+
+
+Stand-Alone HTTP Layer Usage
+----------------------------
+
+// TODO

akka-docs-dev/rst/scala/http/routing-dsl/https-support.rst

@@ -1,4 +0,0 @@
-Server-Side HTTPS Support
-=========================
-
-TODO

akka-docs-dev/rst/scala/http/routing-dsl/index.rst

@@ -19,7 +19,6 @@ static content serving.
    path-matchers
    case-class-extraction
    testkit
-   https-support
    websocket-support