diff --git a/akka-docs-dev/rst/java/http/client-side/https-support.rst b/akka-docs-dev/rst/java/http/client-side/https-support.rst index c9175c080d..da4c6baa78 100644 --- a/akka-docs-dev/rst/java/http/client-side/https-support.rst +++ b/akka-docs-dev/rst/java/http/client-side/https-support.rst @@ -3,6 +3,39 @@ Client-Side HTTPS Support ========================= -TODO +Akka HTTP supports TLS encryption on the client-side as well as on the :ref:`server-side `. -For the time being, :ref:`see the Scala chapter on the same topic `. \ No newline at end of file +The central vehicle for configuring encryption is the ``HttpsContext``, which can be created using +the static method ``HttpsContext.create`` which is defined like this: + +.. includecode:: /../../akka-http-core/src/main/java/akka/http/javadsl/HttpsContext.java + :include: http-context-creation + +In addition to the ``outgoingConnection``, ``newHostConnectionPool`` and ``cachedHostConnectionPool`` methods the +`akka.http.javadsl.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 ``httpsContext`` 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 ``httpsContext`` 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.get(system).setDefaultClientHttpsContext``. +Afterwards you simply use ``outgoingConnectionTls``, ``newHostConnectionPoolTls``, ``cachedHostConnectionPoolTls``, +``superPool`` or ``singleRequest`` without a specific ``httpsContext`` argument, which causes encrypted connections +to rely on the configured default client-side ``HttpsContext``. + + +.. _akka.http.javadsl.Http: @github@/akka-http-core/src/main/scala/akka/http/javadsl/Http.scala diff --git a/akka-docs-dev/rst/java/http/server-side/low-level-server-side-api.rst b/akka-docs-dev/rst/java/http/server-side/low-level-server-side-api.rst index 2a5aa7e457..e6e85561c3 100644 --- a/akka-docs-dev/rst/java/http/server-side/low-level-server-side-api.rst +++ b/akka-docs-dev/rst/java/http/server-side/low-level-server-side-api.rst @@ -138,8 +138,8 @@ 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 can be created using ``HttpsContext.create`` -which is defined like this: +The central vehicle for configuring encryption is the ``HttpsContext``, which can be created using +the static method ``HttpsContext.create`` which is defined like this: .. includecode:: /../../akka-http-core/src/main/java/akka/http/javadsl/HttpsContext.java :include: http-context-creation 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 45eccee592..f2627640b8 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 @@ -21,10 +21,10 @@ i.e. requests to an "https" URI will be encrypted, while requests to an "http" U 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 +1. If the optional ``httpsContext`` 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 +2. If the optional ``httpsContext`` 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`` @@ -33,7 +33,7 @@ following logic: 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 +``superPool`` or ``singleRequest`` without a specific ``httpsContext`` argument, which causes encrypted connections to rely on the configured default client-side ``HttpsContext``.