!htc #20371 allows for simple HTTPS usage from Java, fixes typo in APIs (#20373)

akka-docs/rst/java/code/docs/http/javadsl/server/HttpsServerExampleTest.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright (C) 2009-2016 Lightbend Inc. <http://www.lightbend.com>
+ */
+
+package docs.http.javadsl.server;
+
+import akka.actor.ActorSystem;
+import com.typesafe.sslconfig.akka.AkkaSSLConfig;
+import org.junit.Test;
+import org.scalatest.junit.JUnitSuite;
+
+/* COMPILE ONLY TEST */
+public class HttpsServerExampleTest extends JUnitSuite {
+
+  @Test
+  public void compileOnlySpec() throws Exception {
+    // just making sure for it to be really compiled / run even if empty
+  }
+
+  void sslConfigGet() {
+    //#akka-ssl-config
+    final ActorSystem system = ActorSystem.create();
+
+    final AkkaSSLConfig sslConfig = AkkaSSLConfig.get(system);
+    //#
+  }
+}

akka-docs/rst/java/http/client-side/client-https-support.rst

@@ -125,7 +125,7 @@ Disabling TLS security features, at your own risk
 
 The following shows an example of disabling SNI for a given connection:
 
-.. includecode:: ../../code/docs/http/scaladsl/HttpsExamplesSpec.scala
+.. includecode:: ../../code/docs/http/javadsl/HttpsExamplesDocTest.java
    :include: disable-sni-connection
 
 The ``badSslConfig`` is a copy of the default ``AkkaSSLConfig`` with with the slightly changed configuration to disable SNI.

akka-docs/rst/java/http/client-side/index.rst

@@ -26,5 +26,5 @@ Akka HTTP will happily handle many thousand concurrent connections to a single o
    connection-level
    host-level
    request-level
-   https-support
+   client-https-support
    websocket-support

akka-docs/rst/java/http/index.rst

@@ -36,6 +36,7 @@ akka-http-jackson
    server-side/websocket-support
    routing-dsl/index
    client-side/index
+   server-side-https-support
    configuration
 
 .. _jackson: https://github.com/FasterXML/jackson

akka-docs/rst/java/http/server-side-https-support.rst

@@ -0,0 +1,92 @@
+.. _serverSideHTTPS-java:
+
+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 ``HttpsConnectionContext``, which can be created using
+the static method ``ConnectionContext.https`` which is defined like this:
+
+.. includecode:: /../../akka-http-core/src/main/scala/akka/http/javadsl/ConnectionContext.scala
+   :include: https-context-creation
+
+On the server-side the ``bind``, and ``bindAndHandleXXX`` methods of the `akka.http.javadsl.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).
+
+For detailed documentation for client-side HTTPS support refer to :ref:`clientSideHTTPS`.
+
+
+.. _akka.http.javadsl.Http: https://github.com/akka/akka/blob/master/akka-http-core/src/main/scala/akka/http/javadsl/Http.scala
+
+SSL-Config
+----------
+
+Akka HTTP heavily relies on, and delegates most configuration of any SSL/TLS related options to
+`Lightbend SSL-Config`_, which is a library specialized in providing an secure-by-default SSLContext
+and related options.
+
+Please refer to the `Lightbend SSL-Config`_ documentation for detailed documentation of all available settings.
+
+SSL Config settings used by Akka HTTP (as well as Streaming TCP) are located under the `akka.ssl-config` namespace.
+
+.. _Lightbend SSL-Config: http://typesafehub.github.io/ssl-config/
+
+In order to use SSL-Config in Akka so it logs to the right ActorSystem-wise logger etc., the
+``AkkaSSLConfig`` extension is provided. Obtaining it is as simple as:
+
+.. includecode2:: ../code/docs/http/javadsl/server/HttpsServerExampleTest.java
+   :snippet: akka-ssl-config
+
+While typical usage, for example for configuring http client settings would be applied globally by configuring
+ssl-config in ``application.conf``, it's possible to obtain the extension and ``copy`` it while modifying any
+configuration that you might need to change and then use that specific ``AkkaSSLConfig`` instance while establishing
+connections be it client or server-side.
+
+Obtaining SSL/TLS Certificates
+------------------------------
+In order to run an HTTPS server a certificate has to be provided, which usually is either obtained from a signing
+authority or created by yourself for local or staging environment purposes.
+
+Signing authorities often provide instructions on how to create a Java keystore (typically with reference to Tomcat
+configuration). If you want to generate your own certificates, the official Oracle documentation on how to generate
+keystores using the JDK keytool utility can be found `here <https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html>`_.
+
+SSL-Config provides a more targeted guide on generating certificates, so we recommend you start with the guide
+titled `Generating X.509 Certificates <http://typesafehub.github.io/ssl-config/CertificateGeneration.html>`_.
+
+Using HTTPS
+-----------
+
+Once you have obtained the server certificate, using it is as simple as preparing an ``HttpsConnectionContext``
+and either setting it as the default one to be used by all servers started by the given ``Http`` extension
+or passing it in explicitly when binding the server.
+
+The below example shows how setting up HTTPS works when using the ``akka.http.javadsl.server.HttpApp`` convenience class:
+
+.. includecode2:: ../../../../akka-http-tests/src/main/java/akka/http/javadsl/server/examples/simple/SimpleServerApp.java
+   :snippet: https-http-app
+
+
+Further reading
+---------------
+
+The topic of properly configuring HTTPS for your web server is an always changing one,
+thus we recommend staying up to date with various security breach news and of course
+keep your JVM at the latest version possible, as the default settings are often updated by
+Oracle in reaction to various security updates and known issues.
+
+We also recommend having a look at the `Play documentation about securing your app`_,
+as well as the techniques described in the Play documentation about setting up a `reverse proxy to terminate TLS in
+front of your application`_ instead of terminating TLS inside the JVM, and therefore Akka HTTP, itself.
+
+Other excellent articles on the subject:
+
+- `Oracle Java SE 8: Creating a Keystore using JSSE <https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html#CreateKeystore>`_
+- `Java PKI Programmer's Guide <https://docs.oracle.com/javase/8/docs/technotes/guides/security/certpath/CertPathProgGuide.html>`_
+- `Fixing X.509 Certificates <https://tersesystems.com/2014/03/20/fixing-x509-certificates/>`_
+
+.. _Play documentation about securing your app: https://www.playframework.com/documentation/2.5.x/ConfiguringHttps#ssl-certificates
+.. _reverse proxy to terminate TLS in front of your application: https://www.playframework.com/documentation/2.5.x/HTTPServer