From b02f225470aa2f1777485b6aab636dc94b1bb91e Mon Sep 17 00:00:00 2001 From: WalkerWatch Date: Tue, 21 Nov 2017 17:13:14 -0500 Subject: [PATCH] Additional documentation for Conscrypt. Resolves #1830 --- .../jetty/embedded/ManyConnectors.java | 8 ++++++-- .../configuring-ssl-distribution.adoc | 15 +++++++------- .../connectors/configuring-ssl.adoc | 20 +++++++++++++++++++ 3 files changed, 33 insertions(+), 10 deletions(-) diff --git a/examples/embedded/src/main/java/org/eclipse/jetty/embedded/ManyConnectors.java b/examples/embedded/src/main/java/org/eclipse/jetty/embedded/ManyConnectors.java index 1a81f776131..9de1e57bb40 100644 --- a/examples/embedded/src/main/java/org/eclipse/jetty/embedded/ManyConnectors.java +++ b/examples/embedded/src/main/java/org/eclipse/jetty/embedded/ManyConnectors.java @@ -89,13 +89,17 @@ public class ManyConnectors // including things like choosing the particular certificate out of a // keystore to be used. - Security.addProvider((Provider)ClassLoader.getSystemClassLoader().loadClass("org.conscrypt.OpenSSLProvider").newInstance()); - SslContextFactory sslContextFactory = new SslContextFactory(); sslContextFactory.setKeyStorePath(keystoreFile.getAbsolutePath()); sslContextFactory.setKeyStorePassword("OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4"); sslContextFactory.setKeyManagerPassword("OBF:1u2u1wml1z7s1z7a1wnl1u2g"); + // OPTIONAL: Un-comment the following to use Conscrypt for SSL instead of + // the native JSSE implementation. + + //Security.addProvider((Provider)ClassLoader.getSystemClassLoader().loadClass("org.conscrypt.OpenSSLProvider").newInstance()); + //sslContextFactory.setProvider("Conscrypt"); + // HTTPS Configuration // A new HttpConfiguration object is needed for the next connector and // you can pass the old one as an argument to effectively clone the diff --git a/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl-distribution.adoc b/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl-distribution.adoc index 63b4819940d..e8d1d75f284 100644 --- a/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl-distribution.adoc +++ b/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl-distribution.adoc @@ -17,18 +17,16 @@ [[jetty-ssl-distribution]] === SSL in the Jetty Distribution -==== Configuration - When making use of the Jetty Distribution, enabling SSL support is as easy as activating the appropriate module. Jetty provides support for both the native https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html[JSSE] and https://github.com/google/conscrypt/[Conscrypt] SSL implementations. -For native support, simply activate the `ssl` module: +==== Native SSL Configuration + +For native support, simply activate the `ssl` link:#startup-modules[module:] [source, plain, subs="{sub-order}"] ---- $ cd /path/to/mybase -$ java -jar ${JETTY_HOME}/start.jar --create-startd -... $ java -jar ${JETTY_HOME}/start.jar --add-to-startd=ssl INFO : server initialised (transitively) in ${jetty.base}/start.d/server.ini INFO : ssl initialised in ${jetty.base}/start.d/ssl.ini @@ -57,13 +55,14 @@ jetty.sslContext.keyStorePath:: jetty.sslContext.keyStorePassword:: Sets the Password for the `keystore`. -Enabling Conscrypt SSL is just as easy as native SSL - enable both the `conscrypt` and `ssl` modules: +[[jetty-conscrypt-distribution]] +==== Conscrypt SSL Configuration + +Enabling Conscrypt SSL is just as easy as native SSL - enable both the `conscrypt` and `ssl` link:#startup-modules[modules:] [source, plain, subs="{sub-order}"] ---- $ cd ${JETTY_HOME} -$ java -jar ${JETTY_HOME}/start.jar --create-startd -... $ java -jar ../start.jar --add-to-start=ssl,conscrypt ALERT: There are enabled module(s) with licenses. diff --git a/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl.adoc b/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl.adoc index 164c08f835d..6376e8beeed 100644 --- a/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl.adoc +++ b/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl.adoc @@ -716,6 +716,26 @@ The keystore and truststore passwords may also be set using the system propertie This is _not_ a recommended usage. ____ +===== Conscrypt SSL + +Jetty also includes support for Google's https://github.com/google/conscrypt/[Conscrypt SSL], which is built on their fork of https://www.openssl.org/[OpenSSL], https://boringssl.googlesource.com/boringssl/[BoringSSL]. +Implementing Conscrypt is very straightforward process - simply instantiate an instance of Conscrypt's `OpenSSLProvider` and set `Conscrypt` as a provider for Jetty's `SslContextFactory`: + +[source, java, subs="{sub-order}"] +---- +... +Security.addProvider((Provider)ClassLoader.getSystemClassLoader().loadClass("org.conscrypt.OpenSSLProvider").newInstance()); +... +SslContextFactory sslContextFactory = new SslContextFactory(); +sslContextFactory.setKeyStorePath("path/to/keystore"); +sslContextFactory.setKeyStorePassword("CleverKeyStorePassword"); +sslContextFactory.setKeyManagerPassword("OBF:VerySecretManagerPassword"); +sslContextFactory.setProvider("Conscrypt"); +... +---- + +If you are using the Jetty Distribution, please see the section on enabling the link:#jetty-conscrypt-distribution[Conscrypt SSL module.] + ==== Configuring SNI From Java 8, the JVM contains support for the http://en.wikipedia.org/wiki/Server_Name_Indication[Server Name Indicator (SNI)] extension, which allows a SSL connection handshake to indicate one or more DNS names that it applies to.