From e26dc7f001b32ad129ce3e2179bc5361f97aba0a Mon Sep 17 00:00:00 2001 From: Mathias Date: Fri, 19 Jun 2015 16:39:12 +0200 Subject: [PATCH] =doc add client- and server-side HTTPS section for scala --- .../http/client-side/connection-level.rst | 5 +++ .../scala/http/client-side/https-support.rst | 38 ++++++++++++++++++- .../scala/http/low-level-server-side-api.rst | 23 ++++++++++- .../scala/http/routing-dsl/https-support.rst | 4 -- .../rst/scala/http/routing-dsl/index.rst | 1 - .../main/scala/akka/http/scaladsl/Http.scala | 6 ++- 6 files changed, 68 insertions(+), 9 deletions(-) delete mode 100644 akka-docs-dev/rst/scala/http/routing-dsl/https-support.rst diff --git a/akka-docs-dev/rst/scala/http/client-side/connection-level.rst b/akka-docs-dev/rst/scala/http/client-side/connection-level.rst index 73312901af..a28ec2d5a4 100644 --- a/akka-docs-dev/rst/scala/http/client-side/connection-level.rst +++ b/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 \ No newline at end of file diff --git a/akka-docs-dev/rst/scala/http/client-side/https-support.rst b/akka-docs-dev/rst/scala/http/client-side/https-support.rst index 06c18642a5..45eccee592 100644 --- a/akka-docs-dev/rst/scala/http/client-side/https-support.rst +++ b/akka-docs-dev/rst/scala/http/client-side/https-support.rst @@ -1,4 +1,40 @@ +.. _clientSideHTTPS: + Client-Side HTTPS Support ========================= -TODO \ No newline at end of file +Akka HTTP supports TLS encryption on the client-side as well as on the :ref:`server-side `. + +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 diff --git a/akka-docs-dev/rst/scala/http/low-level-server-side-api.rst b/akka-docs-dev/rst/scala/http/low-level-server-side-api.rst index ffde88505e..380839ad14 100644 --- a/akka-docs-dev/rst/scala/http/low-level-server-side-api.rst +++ b/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 \ No newline at end of file +.. _serverSideHTTPS: + +Server-Side HTTPS Support +------------------------- + +Akka HTTP supports TLS encryption on the server-side as well as on the :ref:`client-side `. + +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 \ No newline at end of file diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/https-support.rst b/akka-docs-dev/rst/scala/http/routing-dsl/https-support.rst deleted file mode 100644 index ad9883d95b..0000000000 --- a/akka-docs-dev/rst/scala/http/routing-dsl/https-support.rst +++ /dev/null @@ -1,4 +0,0 @@ -Server-Side HTTPS Support -========================= - -TODO \ No newline at end of file diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/index.rst b/akka-docs-dev/rst/scala/http/routing-dsl/index.rst index 72801b7f78..fbfb495268 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/index.rst +++ b/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 diff --git a/akka-http-core/src/main/scala/akka/http/scaladsl/Http.scala b/akka-http-core/src/main/scala/akka/http/scaladsl/Http.scala index f598ece862..be038b08d6 100644 --- a/akka-http-core/src/main/scala/akka/http/scaladsl/Http.scala +++ b/akka-http-core/src/main/scala/akka/http/scaladsl/Http.scala @@ -16,7 +16,6 @@ import scala.util.control.NonFatal import scala.collection.{ JavaConverters, immutable } import scala.concurrent.{ ExecutionContext, Promise, Future } import akka.event.LoggingAdapter -import akka.io.Inet import akka.stream.FlowMaterializer import akka.stream.io._ import akka.stream.scaladsl._ @@ -569,11 +568,14 @@ object Http extends ExtensionId[HttpExt] with ExtensionIdProvider { import JavaConverters._ +//# https-context-impl case class HttpsContext(sslContext: SSLContext, enabledCipherSuites: Option[immutable.Seq[String]] = None, enabledProtocols: Option[immutable.Seq[String]] = None, clientAuth: Option[ClientAuth] = None, - sslParameters: Option[SSLParameters] = None) extends akka.http.javadsl.HttpsContext { + sslParameters: Option[SSLParameters] = None) +//# + extends akka.http.javadsl.HttpsContext { def firstSession = NegotiateNewSession(enabledCipherSuites, enabledProtocols, clientAuth, sslParameters) /** Java API */