Updates to SSL documentation. Resolves #1667

This commit is contained in:
WalkerWatch 2017-07-14 11:17:51 -04:00
parent 7b1d4c7ccf
commit 629e41526e
1 changed files with 100 additions and 96 deletions

View File

@ -19,6 +19,16 @@
This document provides an overview of how to configure SSL and TLS for Jetty.
[[configuring-jetty-for-ssl]]
===== Configuring Jetty for SSL
To configure Jetty for SSL, complete the tasks in the following sections:
* xref:generating-key-pairs-and-certificates[]
* xref:requesting-trusted-certificate[]
* xref:loading-keys-and-certificates[]
* xref:configuring-sslcontextfactory[]
[[tls-and-ssl-versions]]
==== TLS and SSL versions
@ -78,16 +88,6 @@ Since Apache and other servers commonly use the OpenSSL tool suite to generate a
If you want the option of using the same certificate with Jetty or a web server such as Apache not written in Java, you might prefer to generate your private key and certificate with OpenSSL.
[[configuring-jetty-for-ssl]]
===== Configuring Jetty for SSL
To configure Jetty for SSL, complete the tasks in the following sections:
* xref:generating-key-pairs-and-certificates[]
* xref:requesting-trusted-certificate[]
* xref:loading-keys-and-certificates[]
* xref:configuring-sslcontextfactory[]
[[generating-key-pairs-and-certificates]]
===== Generating Key Pairs and Certificates
@ -354,84 +354,16 @@ $ keytool -importkeystore -srckeystore jetty.pkcs12 -srcstoretype PKCS12 -destke
If you are updating your configuration to use a newer certificate, as when the old one is expiring, just load the newer certificate as described in the section, xref:loading-keys-and-certificates[].
If you imported the key and certificate originally using the PKCS12 method, use an alias of "1" rather than "jetty", because that is the alias the PKCS12 process enters into the keystore.
==== Configuring SSL in Jetty Distribution
For those of you using the Jetty Distribution, enabling SSL support is as easy as activating the `ssl` module.
An example of this setup:
[source, plain, subs="{sub-order}"]
----
$ cd /path/to/mybase
$ java -jar /path/to/jetty-dist/start.jar --add-to-start=ssl
INFO : server initialised (transitively) in ${jetty.base}/start.d/server.ini
INFO : ssl initialised in ${jetty.base}/start.d/ssl.ini
INFO : Base directory was modified
$ tree
.
├── etc
│   └── keystore
└── start.d
├── server.ini
└── ssl.ini
----
When you open `start.d/ssl.ini`, you will see many commented properties ready for you to configure the `SslContextFactory` basics.
To highlight some of the more commonly used properties:
jetty.ssl.host::
Configures which interfaces the SSL/TLS Connector should listen on.
jetty.ssl.port::
Configures which port the SSL/TLS Connector should listen on.
jetty.httpConfig.securePort::
If a webapp needs to redirect to a secure version of the same resource, then this is the port reported back on the response `location` line (having this be separate is useful if you have something sitting in front of Jetty, such as a Load Balancer or proxy).
jetty.sslContext.keyStorePath::
Sets the location of the `keystore` that you configured with your certificates.
jetty.sslContext.keyStorePassword::
Sets the Password for the `keystore`.
[[two-way-authentication]]
==== Two Way Authentication
To enable two-way authentication, you first need to activate the ssl module as shown in the previous section.
First you need load the `ssl` module and `https` module.
[source%nowrap,ini,linenums]
.$JETTY_BASE/start.d/ssl.ini
----
# Module: ssl
--module=ssl
jetty.ssl.host=0.0.0.0
jetty.ssl.port=8583
jetty.sslContext.keyStorePath=etc/keystore
jetty.sslContext.trustStorePath=etc/keystore
jetty.sslContext.keyStorePassword=OBF:
jetty.sslContext.keyManagerPassword=OBF:
jetty.sslContext.trustStorePassword=OBF:
jetty.sslContext.trustStoreType=JKS
# enable two way authentication
jetty.sslContext.needClientAuth=true
----
[source%nowrap,ini,linenums]
.$JETTY_BASE/start.d/https.ini
----
# Module: https
--module=https
----
[[layout-of-keystore-and-truststore]]
===== Layout of `keystore` and `truststore`
===== Layout of keystore and truststore
`keystore` only contains the server's private key and certificate.
The `keystore` only contains the server's private key and certificate.
[[img-certificate-chain]]
image::images/certificate-chain.png[title="Certificate chain", alt="Certificate chain"]
[literal]
.The structure of KeyStore file
.The structure of KeyStore file:
....
├── PrivateKeyEntry
│   ├── PrivateKey
@ -445,14 +377,10 @@ image::images/certificate-chain.png[title="Certificate chain", alt="Certificate
   └── Root CA certificate
....
[TIP]
====
└── PrivateKeyEntry +
   └── Certificate chain +
      ├── Intermediary CA certificate +
      └── Root CA certificate +
are optional
====
____
[NOTE]
Both the `Intermediary CA certificate` and `Root CA certificate` are optional.
____
[source%nowrap,plain,linenums]
----
@ -529,7 +457,7 @@ Certificate fingerprints:
Signature algorithm name: SHA256withRSA
Version: 3
Extensions:
Extensions:
#1: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
@ -571,7 +499,7 @@ Certificate fingerprints:
Signature algorithm name: SHA256withRSA
Version: 3
Extensions:
Extensions:
#1: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
@ -791,8 +719,84 @@ ____
==== 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.
To support this, the `ExtendedSslContextFactory` is used that will look for multiple X509 certificates within the keystore, each of which may have multiple DNS names (including wildcards) associated with the http://en.wikipedia.org/wiki/SubjectAltName[Subject Alternate Name] extension.
When using the `ExtendedSSlContextFactory`, the correct certificate is automatically selected if the SNI extension is present in the handshake.
To support this, the `SslContextFactory` is used.
The `SslContextFactory` will look for multiple X509 certificates within the keystore, each of which may have multiple DNS names (including wildcards) associated with the http://en.wikipedia.org/wiki/SubjectAltName[Subject Alternate Name] extension.
When using the `SslContextFactory`, the correct certificate is automatically selected if the SNI extension is present in the handshake.
==== Configuring SSL in Jetty Distribution
For those of you using the Jetty Distribution, enabling SSL support is as easy as activating the `ssl` module.
An example of this setup:
[source, plain, subs="{sub-order}"]
----
$ cd /path/to/mybase
$ java -jar /path/to/jetty-dist/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
INFO : Base directory was modified
$ tree
.
├── etc
│   └── keystore
└── start.d
├── server.ini
└── ssl.ini
----
When you open `start.d/ssl.ini`, you will see several commented properties ready for use when configuring `SslContextFactory` basics.
To highlight some of the more commonly used properties:
jetty.ssl.host::
Configures which interfaces the SSL/TLS Connector should listen on.
jetty.ssl.port::
Configures which port the SSL/TLS Connector should listen on.
jetty.httpConfig.securePort::
If a webapp needs to redirect to a secure version of the same resource, then this is the port reported back on the response `location` line (having this be separate is useful if you have something sitting in front of Jetty, such as a Load Balancer or proxy).
jetty.sslContext.keyStorePath::
Sets the location of the `keystore` that you configured with your certificates.
jetty.sslContext.keyStorePassword::
Sets the Password for the `keystore`.
[[two-way-authentication]]
==== Two Way Authentication
To enable two-way authentication in the Jetty Distribution, you need to enable the both the `ssl` and `https` modules.
[source, plain, subs="{sub-order}"]
----
$ cd /path/to/mybase
$ java -jar /path/to/jetty-dist/start.jar --add-to-startd=ssl,https
----
[source%nowrap,ini,linenums]
.$JETTY_BASE/start.d/ssl.ini
----
# Module: ssl
--module=ssl
jetty.ssl.host=0.0.0.0
jetty.ssl.port=8583
jetty.sslContext.keyStorePath=etc/keystore
jetty.sslContext.trustStorePath=etc/keystore
jetty.sslContext.keyStorePassword=OBF:
jetty.sslContext.keyManagerPassword=OBF:
jetty.sslContext.trustStorePassword=OBF:
jetty.sslContext.trustStoreType=JKS
# enable two way authentication
jetty.sslContext.needClientAuth=true
----
[source%nowrap,ini,linenums]
.$JETTY_BASE/start.d/https.ini
----
# Module: https
--module=https
----
[[configuring-sslcontextfactory-cipherSuites]]
==== Disabling/Enabling Specific Cipher Suites
@ -807,7 +811,7 @@ Tools like ssllabs.com might report slightly different names which will be ignor
____
____
[NOTE]
[IMPORTANT]
It's recommended to install the Java Cryptography Extension (JCE) Unlimited Strength policy files in your JRE to get full strength ciphers such as AES-256.
The files can be found on the http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java download page].
Just overwrite the two present JAR files in `<JRE_HOME>/lib/security/`.
@ -815,7 +819,7 @@ ____
Both `setIncludeCipherSuites` and `setExcludeCipherSuites` can be fed by the exact cipher suite name used in the JDK or by using regular expressions.
If you have a need to adjust the Includes or Excludes, then this is best done with a custom blow-in XML that configures the `SslContextFactory` to suit your needs.
If you have a need to adjust the Includes or Excludes, then this is best done with a custom XML that configures the `SslContextFactory` to suit your needs.
To do this, first create a new `${jetty.base}/etc/tweak-ssl.xml` file (this can be any name, just avoid prefixing it with "jetty-").
@ -860,7 +864,7 @@ ____
[NOTE]
The default `SslContextFactory` implementation applies the latest SSL/TLS recommendations surrounding vulnerabilities in SSL/TLS.
Check the release notes (the `VERSION.txt` found in the root of the Jetty Distribution, or the http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.eclipse.jetty%22%20AND%20a%3A%22jetty-project%22[alternate (classified 'version') artifacts for the `jetty-project` component]on Maven Central) for updates.
The Java JVM is also applying exclusions at the JVM level and as such if you have a need to enable something that is generally accepted by the industry as being insecure or vulnerable you will likely have to enable it in BOTH the Java JVM and the Jetty configuration.
The Java JVM also applies exclusions at the JVM level and, as such, if you have a need to enable something that is generally accepted by the industry as being insecure or vulnerable you will likely have to enable it in *both* the Java JVM and your Jetty configuration.
____
____