From 7e75215cfc69e62b4c29fd84bc8d6e3bfd410514 Mon Sep 17 00:00:00 2001 From: Simone Bordet Date: Mon, 5 Oct 2020 18:12:29 +0200 Subject: [PATCH] Improvements to the Jetty documentation. Ported the TLS documentation. Signed-off-by: Simone Bordet --- .../asciidoc/old_docs/connectors/chapter.adoc | 2 - .../configuring-ssl-distribution.adoc | 129 --- .../old_docs/connectors/configuring-ssl.adoc | 1003 ----------------- .../main/asciidoc/operations-guide/index.adoc | 1 + .../operations-guide/keystore/chapter.adoc | 12 +- .../keystore/keystore-client-authn.adoc | 146 +++ .../keystore/keystore-create.adoc | 60 + .../keystore/keystore-csr.adoc | 83 ++ .../operations-guide/modules/module-http.adoc | 6 +- .../modules/module-ssl-reload.adoc | 29 + .../operations-guide/modules/module-ssl.adoc | 48 +- .../modules/module-test-keystore.adoc | 4 +- .../protocols/protocols-http2s.adoc | 6 +- .../protocols/protocols-https.adoc | 6 +- .../protocols/protocols-ssl.adoc | 257 ++++- jetty-server/src/main/config/modules/http.mod | 40 +- .../src/main/config/modules/ssl-reload.mod | 8 +- jetty-server/src/main/config/modules/ssl.mod | 101 +- 18 files changed, 698 insertions(+), 1243 deletions(-) delete mode 100644 jetty-documentation/src/main/asciidoc/old_docs/connectors/configuring-ssl-distribution.adoc delete mode 100644 jetty-documentation/src/main/asciidoc/old_docs/connectors/configuring-ssl.adoc create mode 100644 jetty-documentation/src/main/asciidoc/operations-guide/keystore/keystore-client-authn.adoc create mode 100644 jetty-documentation/src/main/asciidoc/operations-guide/keystore/keystore-create.adoc create mode 100644 jetty-documentation/src/main/asciidoc/operations-guide/keystore/keystore-csr.adoc create mode 100644 jetty-documentation/src/main/asciidoc/operations-guide/modules/module-ssl-reload.adoc diff --git a/jetty-documentation/src/main/asciidoc/old_docs/connectors/chapter.adoc b/jetty-documentation/src/main/asciidoc/old_docs/connectors/chapter.adoc index 3ec96a46951..396cb5a223d 100644 --- a/jetty-documentation/src/main/asciidoc/old_docs/connectors/chapter.adoc +++ b/jetty-documentation/src/main/asciidoc/old_docs/connectors/chapter.adoc @@ -22,5 +22,3 @@ This chapter discusses various options for configuring Jetty connectors. include::configuring-connectors.adoc[] -include::configuring-ssl.adoc[] -include::configuring-ssl-distribution.adoc[] diff --git a/jetty-documentation/src/main/asciidoc/old_docs/connectors/configuring-ssl-distribution.adoc b/jetty-documentation/src/main/asciidoc/old_docs/connectors/configuring-ssl-distribution.adoc deleted file mode 100644 index 7b5f58f1cb8..00000000000 --- a/jetty-documentation/src/main/asciidoc/old_docs/connectors/configuring-ssl-distribution.adoc +++ /dev/null @@ -1,129 +0,0 @@ -// -// ======================================================================== -// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others. -// -// This program and the accompanying materials are made available under -// the terms of the Eclipse Public License 2.0 which is available at -// https://www.eclipse.org/legal/epl-2.0 -// -// This Source Code may also be made available under the following -// Secondary Licenses when the conditions for such availability set -// forth in the Eclipse Public License, v. 2.0 are satisfied: -// the Apache License v2.0 which is available at -// https://www.apache.org/licenses/LICENSE-2.0 -// -// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 -// ======================================================================== -// - -[[jetty-ssl-distribution]] -=== SSL in the Jetty Distribution - -When making use of the Jetty Distribution, enabling SSL support is as easy as activating the appropriate module. -Jetty supports both the default https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html[JSSE] -provider and the https://github.com/google/conscrypt/[Conscrypt] provider as SSL implementations. - -==== Default JSSE SSL Configuration - -For the default SSL support, simply activate the `ssl` link:#startup-modules[module]: - -[source, plain, subs="{sub-order}"] ----- -$ cd /path/to/mybase -$ 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 -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`. - -[[jetty-conscrypt-distribution]] -==== Conscrypt SSL Configuration - -Enabling Conscrypt SSL is just as easy as default SSL - enable both the `conscrypt` and `ssl` link:#startup-modules[modules]: - -[source,plain,subs="{sub-order}"] ----- -$ cd ${JETTY_BASE} -$ java -jar /path/to/jetty-home/start.jar --add-to-start=ssl,conscrypt - -ALERT: There are enabled module(s) with licenses. -The following 1 module(s): - + contains software not provided by the Eclipse Foundation! - + contains software not covered by the Eclipse Public License! - + has not been audited for compliance with its license - - Module: conscrypt - + Conscrypt is distributed under the Apache Licence 2.0 - + https://github.com/google/conscrypt/blob/master/LICENSE - -Proceed (y/N)? y -INFO : server transitively enabled, ini template available with --add-to-start=server -INFO : conscrypt initialized in ${jetty.base}/start.d/conscrypt.ini -INFO : ssl initialized in ${jetty.base}/start.d/ssl.ini -MKDIR : ${jetty.base}/lib/conscrypt -DOWNLD: https://repo1.maven.org/maven2/org/conscrypt/conscrypt-openjdk-uber/1.0.0.RC11/conscrypt-openjdk-uber-1.0.0.RC11.jar to ${jetty.base}/lib/conscrypt/conscrypt-uber-1.0.0.RC11.jar -MKDIR : ${jetty.base}/etc -COPY : ${jetty.home}/modules/conscrypt/conscrypt.xml to ${jetty.base}/etc/conscrypt.xml -COPY : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore -INFO : Base directory was modified ----- - -No additional Conscrypt configuration is needed. -SSL-specific parameters, like `keyStorePath` and `keyStorePassword` can still configured as in the example above, making use of the `${JETTY_BASE}/start.d/ssl.ini` file. - -[[client-certificate-authentication]] -==== Client Certificate Authentication - -To enable client certificate 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/truststore -jetty.sslContext.keyStorePassword=OBF: -jetty.sslContext.keyManagerPassword=OBF: -jetty.sslContext.trustStorePassword=OBF: -# Enable client certificate authentication. -jetty.sslContext.needClientAuth=true ----- - -[source%nowrap,ini,linenums] -.$JETTY_BASE/start.d/https.ini ----- -# Module: https ---module=https ----- diff --git a/jetty-documentation/src/main/asciidoc/old_docs/connectors/configuring-ssl.adoc b/jetty-documentation/src/main/asciidoc/old_docs/connectors/configuring-ssl.adoc deleted file mode 100644 index c62d74551bd..00000000000 --- a/jetty-documentation/src/main/asciidoc/old_docs/connectors/configuring-ssl.adoc +++ /dev/null @@ -1,1003 +0,0 @@ -// -// ======================================================================== -// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others. -// -// This program and the accompanying materials are made available under -// the terms of the Eclipse Public License 2.0 which is available at -// https://www.eclipse.org/legal/epl-2.0 -// -// This Source Code may also be made available under the following -// Secondary Licenses when the conditions for such availability set -// forth in the Eclipse Public License, v. 2.0 are satisfied: -// the Apache License v2.0 which is available at -// https://www.apache.org/licenses/LICENSE-2.0 -// -// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 -// ======================================================================== -// - -[[configuring-ssl]] -=== Configuring SSL/TLS - -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 - -Which browser/OS supports which protocols can be https://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers[found on Wikipedia]. - -* TLS v1.2: The protocol which should be used wherever possible. -All CBC based ciphers are supported since Java 7, the new GCM modes are supported since Java 8. - -===== Older Protocols - -TLS v1.0, v1.1 and SSL v3 are no longer supported by default. If your Jetty implementation requires these protocols for legacy support, they can be enabled manually. - -____ -[NOTE] -Once TLS v1.3 is released, there will be no workaround available for TLS v1.0 or v1.1. -Plans for TLS v1.3 include banning ciphers with known vulnerabilities from being present at any level. -It is recommended to upgrade any clients using these ciphers as soon as possible or face being locked into a outdated version of Jetty, Java or even OS. -____ - -By default, Jetty excludes these ciphers in the link:{GITBROWSEURL}/jetty-util/src/main/java/org/eclipse/jetty/util/ssl/SslContextFactory.java#L249-L256[`SslContextFactory`.] -You can re-enable these by re-declaring the ciphers you want excluded in code: - -[source, java, subs="{sub-order}"] ----- -SslContextFactory.Server sslContextFactory = new SslContextFactory.Server(); -sslContextFactory.setExcludeCipherSuites("^.*_(MD5|SHA|SHA1)$"); ----- - -If, after making these changes, you still have issues using these ciphers they are likely being blocked at the JVM level. -Locate the `$JAVA_HOME/jre/lib/security/` directory for the `java.security` file and examine it for any configuration that is excluding _ciphers_ or _algorithms_ (depending on the version of the JVM you are using the nomenclature may be different). - -[[understanding-certificates-and-keys]] -==== Understanding Certificates and Keys - -Configuring SSL can be a confusing experience of keys, certificates, protocols and formats, thus it helps to have a reasonable understanding of the basics. -The following links provide some good starting points: - -* Certificates: -** http://en.tldp.org/HOWTO/SSL-Certificates-HOWTO/index.html[SSL Certificates HOWTO] -** http://mindprod.com/jgloss/certificate.html[Mindprod Java Glossary: Certificates] -* Keytool: -** http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html[Keytool for Unix] -** http://docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html[Keytool for Windows] -* Other tools: -** https://www.ibm.com/developerworks/mydeveloperworks/groups/service/html/communityview?communityUuid=6fb00498-f6ea-4f65-bf0c-adc5bd0c5fcc[IBM Keyman] -* OpenSSL: -** http://www.openssl.org/support/faq.html[OpenSSL FAQ] - -[[openssl-vs-keytool]] -===== OpenSSL vs. Keytool - -For testing, the `keytool` utility bundled with the JDK provides the simplest way to generate the key and certificate you need. - -You can also use the OpenSSL tools to generate keys and certificates, or to convert those that you have used with Apache or other servers. -Since Apache and other servers commonly use the OpenSSL tool suite to generate and manipulate keys and certificates, you might already have some keys and certificates created by OpenSSL, or you might also prefer the formats OpenSSL produces. - -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. - -[[generating-key-pairs-and-certificates]] -===== Generating Key Pairs and Certificates - -The simplest way to generate keys and certificates is to use the `keytool` application that comes with the JDK, as it generates keys and certificates directly into the keystore. -See xref:generating-key-pairs-and-certificates-JDK-keytool[]. - -If you already have keys and certificates, see xref:loading-keys-and-certificates[] to load them into a JSSE keystore. -This section also applies if you have a renewal certificate to replace one that is expiring. - -The examples below generate only basic keys and certificates. -You should read the full manuals of the tools you are using if you want to specify: - -* The key size -* The certificate expiration date -* Alternate security providers - -[[generating-key-pairs-and-certificates-JDK-keytool]] -====== Generating Keys and Certificates with JDK's keytool - -The following command generates a key pair and certificate directly into file `keystore`: - -[source, screen, subs="{sub-order}"] ----- -$ keytool -keystore keystore -alias jetty -genkey -keyalg RSA ----- - -____ -[NOTE] -The DSA key algorithm certificate produces an error after loading several pages. -In a browser, it displays a message "Could not establish an encrypted connection because certificate presented by localhost as an invalid signature." -The solution is to use RSA for the key algorithm. -____ - -This command prompts for information about the certificate and for passwords to protect both the keystore and the keys within it. -The only mandatory response is to provide the fully qualified host name of the server at the "first and last name" prompt. -For example: - -[source, screen, subs="{sub-order}"] ----- -$ keytool -keystore keystore -alias jetty -genkey -keyalg RSA -sigalg SHA256withRSA - Enter keystore password: password - What is your first and last name? - [Unknown]: jetty.eclipse.org - What is the name of your organizational unit? - [Unknown]: Jetty - What is the name of your organization? - [Unknown]: Mort Bay Consulting Pty. Ltd. - What is the name of your City or Locality? - [Unknown]: - What is the name of your State or Province? - [Unknown]: - What is the two-letter country code for this unit? - [Unknown]: - Is CN=jetty.eclipse.org, OU=Jetty, O=Mort Bay Consulting Pty. Ltd., - L=Unknown, ST=Unknown, C=Unknown correct? - [no]: yes - - Enter key password for - (RETURN if same as keystore password): - $ ----- - -You now have the minimal requirements to run an SSL connection and could proceed directly to link:#configuring-sslcontextfactory[configure an SSL connector]. -However, the browser _will not_ trust the certificate you have generated, and prompts the user to this effect. -While what you have at this point is often sufficient for testing, most public sites need a trusted certificate, which is demonstrated in the section link:#generating-csr-from-keytool[generating a CSR with keytool]. - -If you want to use only a self signed certificate for some kind of internal admin panel add -validity to the keytool call above, otherwise your certificate is only valid for one month. - -If you are using Java 8 or later, then you may also use the SAN extension to set one or more names that the certificate applies to: - -[source, screen, subs="{sub-order}"] ----- -$ keytool -keystore keystore -alias jetty -genkey -keyalg RSA -sigalg SHA256withRSA -ext 'SAN=dns:jetty.eclipse.org,dns:*.jetty.org' - ... ----- - -[[generating-keys-and-certificates-openssl]] -====== Generating Keys and Certificates with OpenSSL - -The following command generates a key pair in the file `jetty.key`: - -[source, screen, subs="{sub-order}"] ----- -$ openssl genrsa -aes128 -out jetty.key ----- - -You might also want to use the `-rand` file argument to provide an arbitrary file that helps seed the random number generator. - -The following command generates a certificate for the key into the file `jetty.crt`: - -[source, screen, subs="{sub-order}"] ----- -$ openssl req -new -x509 -newkey rsa:2048 -sha256 -key jetty.key -out jetty.crt ----- - -Adding -sha256 ensures to get a certificate with the now recommended SHA-256 signature algorithm. -For the those with heightened security in mind, add -b4096 to get a 4069 bit key. - -The next command prompts for information about the certificate and for passwords to protect both the keystore and the keys within it. -The only mandatory response is to provide the fully qualified host name of the server at the "Common Name" prompt. For example: - -[source, screen, subs="{sub-order}"] ----- -$ openssl genrsa -aes128 -out jetty.key -Generating RSA private key, 2048 bit long modulus -..............+++ -......................................................................+++ -e is 65537 (0x10001) -Enter pass phrase for jetty.key: -Verifying - Enter pass phrase for jetty.key: - -$ openssl req -new -x509 -newkey rsa:2048 -sha256 -key jetty.key -out jetty.crt -Enter pass phrase for jetty.key: -You are about to be asked to enter information that will be incorporated into your certificate request. -What you are about to enter is what is called a Distinguished Name or a DN. -There are quite a few fields but you can leave some blank. -For some fields there will be a default value. -If you enter '.', the field will be left blank. - -Country Name (2 letter code) [AU]: -State or Province Name (full name) [Some-State]: -Locality Name (eg, city) []: -Organization Name (eg, company) [Internet Widgits Pty Ltd]:Mort Bay Consulting Pty. Ltd. -Organizational Unit Name (eg, section) []:Jetty -Common Name (e.g. server FQDN or YOUR name) []:jetty.eclipse.org -Email Address []: - -$ ----- - -You now have the minimal requirements to run an SSL connection and could proceed directly to xref:loading-keys-and-certificates[] to load these keys and certificates into a JSSE keystore. -However the browser _will not_ trust the certificate you have generated, and prompts the user to this effect. -While what you have at this point is often sufficient for testing, most public sites need a trusted certificate, which is demonstrated in the section, xref:generating-csr-from-openssl[] to obtain a certificate. - -[[using-keys-and-certificates-from-other-sources]] -====== Using Keys and Certificates from Other Sources - -If you have keys and certificates from other sources, you can proceed directly to xref:loading-keys-and-certificates[]. - -[[requesting-trusted-certificate]] -===== Requesting a Trusted Certificate - -The keys and certificates generated with JDK's `keytool` and OpenSSL are sufficient to run an SSL connector. -However the browser will not trust the certificate you have generated, and it will prompt the user to this effect. - -To obtain a certificate that most common browsers will trust, you need to request a well-known certificate authority (CA) to sign your key/certificate. -Such trusted CAs include: AddTrust, Entrust, GeoTrust, RSA Data Security, Thawte, VISA, ValiCert, Verisign, and beTRUSTed, among others. -Each CA has its own instructions (look for JSSE or OpenSSL sections), but all involve a step that generates a certificate signing request (CSR). - -[[generating-csr-from-keytool]] -====== Generating a CSR with keytool - -The following command generates the file `jetty.csr` using `keytool` for a key/cert already in the keystore: - -[source, screen, subs="{sub-order}"] ----- -$ keytool -certreq -alias jetty -keystore keystore -file jetty.csr ----- - -[[generating-csr-from-openssl]] -====== Generating a CSR from OpenSSL - -The following command generates the file `jetty.csr` using OpenSSL for a key in the file `jetty.key`: - -[source, screen, subs="{sub-order}"] ----- -$ openssl req -new -key jetty.key -out jetty.csr ----- - -Notice that this command uses only the existing key from `jetty.key` file, and not a certificate in `jetty.crt` as generated with OpenSSL. -You need to enter the details for the certificate again. - -[[loading-keys-and-certificates]] -===== Loading Keys and Certificates - -Once a CA has sent you a certificate, or if you generated your own certificate without `keytool`, you need to load it into a JSSE keystore. - -____ -[NOTE] -You need both the private key and the certificate in the JSSE keystore. -You should load the certificate into the keystore used to generate the CSR with `keytool`. -If your key pair is not already in a keystore (for example, because it has been generated with OpenSSL), you need to use the PKCS12 format to load both key and certificate (see link:#loading-keys-and-certificates-via-pkcks12[PKCKS12 Keys &Certificates]). -____ - -[[loading-certificates-with-keytool]] -====== Loading Certificates with keytool - -You can use `keytool` to load a certificate in PEM form directly into a keystore. -The PEM format is a text encoding of certificates; it is produced by OpenSSL, and is returned by some CAs. -An example PEM file is: - -[source, screen, subs="{sub-order}"] ----- -jetty.crt ------BEGIN CERTIFICATE----- -MIICSDCCAfKgAwIBAgIBADANBgkqhkiG9w0BAQQFADBUMSYwJAYDVQQKEx1Nb3J0 -IEJheSBDb25zdWx0aW5nIFB0eS4gTHRkLjEOMAwGA1UECxMFSmV0dHkxGjAYBgNV -BAMTEWpldHR5Lm1vcnRiYXkub3JnMB4XDTAzMDQwNjEzMTk1MFoXDTAzMDUwNjEz -MTk1MFowVDEmMCQGA1UEChMdTW9ydCBCYXkgQ29uc3VsdGluZyBQdHkuIEx0ZC4x -DjAMBgNVBAsTBUpldHR5MRowGAYDVQQDExFqZXR0eS5tb3J0YmF5Lm9yZzBcMA0G -CSqGSIb3DQEBAQUAA0sAMEgCQQC5V4oZeVdhdhHqa9L2/ZnKySPWUqqy81riNfAJ -7uALW0kEv/LtlG34dOOcVVt/PK8/bU4dlolnJx1SpiMZbKsFAgMBAAGjga4wgasw -HQYDVR0OBBYEFFV1gbB1XRvUx1UofmifQJS/MCYwMHwGA1UdIwR1MHOAFFV1gbB1 -XRvUx1UofmifQJS/MCYwoVikVjBUMSYwJAYDVQQKEx1Nb3J0IEJheSBDb25zdWx0 -aW5nIFB0eS4gTHRkLjEOMAwGA1UECxMFSmV0dHkxGjAYBgNVBAMTEWpldHR5Lm1v -cnRiYXkub3JnggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEEBQADQQA6NkaV -OtXzP4ayzBcgK/qSCmF44jdcARmrXhiXUcXzjxsLjSJeYPJojhUdC2LQKy+p4ki8 -Rcz6oCRvCGCe5kDB ------END CERTIFICATE----- ----- - -The following command loads a PEM encoded certificate in the `jetty.crt` file into a JSSE keystore: - -[source, screen, subs="{sub-order}"] ----- -$ keytool -keystore keystore -import -alias jetty -file jetty.crt -trustcacerts ----- - -If the certificate you receive from the CA is not in a format that `keytool` understands, you can use the `openssl` command to convert formats: - -[source, screen, subs="{sub-order}"] ----- -$ openssl x509 -in jetty.der -inform DER -outform PEM -out jetty.crt ----- - -[[loading-keys-and-certificates-via-pkcks12]] -====== Loading Keys and Certificates via PKCS12 - -If you have a key and certificate in separate files, you need to combine them into a PKCS12 format file to load into a new keystore. -The certificate can be one you generated yourself or one returned from a CA in response to your CSR. - -The following OpenSSL command combines the keys in `jetty.key` and the certificate in the `jetty.crt` file into the `jetty.pkcs12` file: - -[source, screen, subs="{sub-order}"] ----- -$ openssl pkcs12 -inkey jetty.key -in jetty.crt -export -out jetty.pkcs12 ----- - -If you have a chain of certificates, because your CA is an intermediary, build the PKCS12 file as follows: - -[source, screen, subs="{sub-order}"] ----- -$ cat example.crt intermediate.crt [intermediate2.crt] ... rootCA.crt > cert-chain.txt -$ openssl pkcs12 -export -inkey example.key -in cert-chain.txt -out example.pkcs12 ----- - -____ -[NOTE] -The order of certificates must be from server to rootCA, as per link:https://www.ietf.org/rfc/rfc2246.txt[RFC2246 section 7.4.2.] -____ - -OpenSSL asks for an __export password__. -A non-empty password is required to make the next step work. -Load the resulting PKCS12 file into a JSSE keystore with `keytool`: - -[source, screen, subs="{sub-order}"] ----- -$ keytool -importkeystore -srckeystore jetty.pkcs12 -srcstoretype PKCS12 -destkeystore keystore ----- - -[[renewing-certificates]] -===== Renewing Certificates - -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. - -[[layout-of-keystore-and-truststore]] -===== Layout of keystore and truststore - -The `keystore` only contains the server's private key and certificate. - -[[img-certificate-chain]] -image::certificate-chain.png[title="Certificate chain", alt="Certificate chain"] - -[literal] -.The structure of KeyStore file: -.... -├── PrivateKeyEntry -│   ├── PrivateKey -│   ├── Certificate chain -│   │   ├── Server certificate (end entity) -│   │   ├── Intermediary CA certificate -│   │   └── Root CA certificate -├── TrustedCertEntry -│   └── Intermediary CA certificate -└── TrustedCertEntry -    └── Root CA certificate -.... - -____ -[NOTE] -Both the `Intermediary CA certificate` and `Root CA certificate` are optional. -____ - -[source%nowrap,plain,linenums] ----- -$ cd $JETTY_BASE -$ keytool -v -list -keystore etc/keystore - -Keystore type: PKCS12 -Keystore provider: SUN - -Your keystore contains 3 entries - -Alias name: *.example.com -Creation date: Sep 20, 2016 -Entry type: PrivateKeyEntry -Certificate chain length: 3 -Certificate[1]: -Owner: CN=*.example.com, OU=Web Servers, O="Example.com Co.,Ltd.", C=CN -Issuer: CN="Example.com Co.,Ltd. ETP CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN -Serial number: b63af619ff0b4c368735113ba5db8997 -Valid from: Mon Sep 12 15:09:49 CST 2016 until: Wed Sep 12 15:09:49 CST 2018 -Certificate fingerprints: - MD5: D9:26:CC:27:77:9D:26:FE:67:4C:BE:FF:E3:95:1E:97 - SHA1: AF:DC:D2:65:6A:33:42:E3:81:9E:4D:19:0D:22:20:C7:6F:2F:11:D0 - SHA256: 43:E8:21:5D:C6:FB:A0:7D:5D:7B:9C:8B:8D:E9:4B:52:BF:50:0D:90:4F:61:C2:18:9E:89:AA:4C:C2:93:BD:32 - Signature algorithm name: SHA256withRSA - Version: 3 - -Extensions: - -#1: ObjectId: 2.5.29.35 Criticality=false -AuthorityKeyIdentifier [ -KeyIdentifier [ -0000: 44 9B AD 31 E7 FE CA D5 5A 8E 17 55 F9 F0 1D 6B D..1....Z..U...k -0010: F5 A5 8F C1 .... -] -] - -#2: ObjectId: 2.5.29.19 Criticality=true -BasicConstraints:[ - CA:false - PathLen: undefined -] - -#3: ObjectId: 2.5.29.37 Criticality=true -ExtendedKeyUsages [ - serverAuth - clientAuth -] - -#4: ObjectId: 2.5.29.15 Criticality=true -KeyUsage [ - DigitalSignature - Key_Encipherment - Data_Encipherment -] - -#5: ObjectId: 2.5.29.14 Criticality=false -SubjectKeyIdentifier [ -KeyIdentifier [ -0000: 7D 26 36 73 61 5E 08 94 AD 25 13 46 DB DB 95 25 .&6sa^...%.F...% -0010: BF 82 5A CA ..Z. -] -] - -Certificate[2]: -Owner: CN="Example.com Co.,Ltd. ETP CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN -Issuer: CN="Example.com Co.,Ltd. Root CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN -Serial number: f6e7b86f6fdb467f9498fb599310198f -Valid from: Wed Nov 18 00:00:00 CST 2015 until: Sun Nov 18 00:00:00 CST 2035 -Certificate fingerprints: - MD5: ED:A3:91:57:D8:B8:6E:B1:01:58:55:5C:33:14:F5:99 - SHA1: D9:A4:93:9D:A6:F8:A3:F9:FD:85:51:E2:C5:2E:0B:EE:80:E7:D0:22 - SHA256: BF:54:7A:F6:CA:0C:FA:EF:93:B6:6B:6E:2E:D7:44:A8:40:00:EC:69:3A:2C:CC:9A:F7:FE:8E:6F:C0:FA:22:38 - Signature algorithm name: SHA256withRSA - Version: 3 - -Extensions: - -#1: ObjectId: 2.5.29.35 Criticality=false -AuthorityKeyIdentifier [ -KeyIdentifier [ -0000: A6 BD 5F B3 E8 7D 74 3D 20 44 66 1A 16 3B 1B DF .._...t= Df..;.. -0010: E6 E6 04 46 ...F -] -] - -#2: ObjectId: 2.5.29.19 Criticality=true -BasicConstraints:[ - CA:true - PathLen:2147483647 -] - -#3: ObjectId: 2.5.29.15 Criticality=true -KeyUsage [ - Key_CertSign - Crl_Sign -] - -#4: ObjectId: 2.5.29.14 Criticality=false -SubjectKeyIdentifier [ -KeyIdentifier [ -0000: 44 9B AD 31 E7 FE CA D5 5A 8E 17 55 F9 F0 1D 6B D..1....Z..U...k -0010: F5 A5 8F C1 .... -] -] - -Certificate[3]: -Owner: CN="Example.com Co.,Ltd. Root CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN -Issuer: CN="Example.com Co.,Ltd. Root CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN -Serial number: f0a45bc9972c458cbeae3f723055f1ac -Valid from: Wed Nov 18 00:00:00 CST 2015 until: Sun Nov 18 00:00:00 CST 2114 -Certificate fingerprints: - MD5: 50:61:62:22:71:60:F7:69:2E:27:42:6B:62:31:82:79 - SHA1: 7A:6D:A6:48:B1:43:03:3B:EA:A0:29:2F:19:65:9C:9B:0E:B1:03:1A - SHA256: 05:3B:9C:5B:8E:18:61:61:D1:9C:AA:0E:8C:B1:EA:44:C2:6E:67:5D:96:30:EC:8C:F6:6F:E1:EC:AD:00:60:F1 - Signature algorithm name: SHA256withRSA - Version: 3 - -Extensions: - -#1: ObjectId: 2.5.29.35 Criticality=false -AuthorityKeyIdentifier [ -KeyIdentifier [ -0000: A6 BD 5F B3 E8 7D 74 3D 20 44 66 1A 16 3B 1B DF .._...t= Df..;.. -0010: E6 E6 04 46 ...F -] -] - -#2: ObjectId: 2.5.29.19 Criticality=true -BasicConstraints:[ - CA:true - PathLen:2147483647 -] - -#3: ObjectId: 2.5.29.15 Criticality=true -KeyUsage [ - Key_CertSign - Crl_Sign -] - -#4: ObjectId: 2.5.29.14 Criticality=false -SubjectKeyIdentifier [ -KeyIdentifier [ -0000: A6 BD 5F B3 E8 7D 74 3D 20 44 66 1A 16 3B 1B DF .._...t= Df..;.. -0010: E6 E6 04 46 ...F -] -] - - - -******************************************* -******************************************* - - -Alias name: example.com co.,ltd. etp ca -Creation date: Sep 20, 2016 -Entry type: trustedCertEntry - -Owner: CN="Example.com Co.,Ltd. ETP CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN -Issuer: CN="Example.com Co.,Ltd. Root CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN -Serial number: f6e7b86f6fdb467f9498fb599310198f -Valid from: Wed Nov 18 00:00:00 CST 2015 until: Sun Nov 18 00:00:00 CST 2035 -Certificate fingerprints: - MD5: ED:A3:91:57:D8:B8:6E:B1:01:58:55:5C:33:14:F5:99 - SHA1: D9:A4:93:9D:A6:F8:A3:F9:FD:85:51:E2:C5:2E:0B:EE:80:E7:D0:22 - SHA256: BF:54:7A:F6:CA:0C:FA:EF:93:B6:6B:6E:2E:D7:44:A8:40:00:EC:69:3A:2C:CC:9A:F7:FE:8E:6F:C0:FA:22:38 - Signature algorithm name: SHA256withRSA - Version: 3 - -Extensions: - -#1: ObjectId: 2.5.29.35 Criticality=false -AuthorityKeyIdentifier [ -KeyIdentifier [ -0000: A6 BD 5F B3 E8 7D 74 3D 20 44 66 1A 16 3B 1B DF .._...t= Df..;.. -0010: E6 E6 04 46 ...F -] -] - -#2: ObjectId: 2.5.29.19 Criticality=true -BasicConstraints:[ - CA:true - PathLen:2147483647 -] - -#3: ObjectId: 2.5.29.15 Criticality=true -KeyUsage [ - Key_CertSign - Crl_Sign -] - -#4: ObjectId: 2.5.29.14 Criticality=false -SubjectKeyIdentifier [ -KeyIdentifier [ -0000: 44 9B AD 31 E7 FE CA D5 5A 8E 17 55 F9 F0 1D 6B D..1....Z..U...k -0010: F5 A5 8F C1 .... -] -] - - - -******************************************* -******************************************* - - -Alias name: example.com co.,ltd. root ca -Creation date: Sep 20, 2016 -Entry type: trustedCertEntry - -Owner: CN="Example.com Co.,Ltd. Root CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN -Issuer: CN="Example.com Co.,Ltd. Root CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN -Serial number: f0a45bc9972c458cbeae3f723055f1ac -Valid from: Wed Nov 18 00:00:00 CST 2015 until: Sun Nov 18 00:00:00 CST 2114 -Certificate fingerprints: - MD5: 50:61:62:22:71:60:F7:69:2E:27:42:6B:62:31:82:79 - SHA1: 7A:6D:A6:48:B1:43:03:3B:EA:A0:29:2F:19:65:9C:9B:0E:B1:03:1A - SHA256: 05:3B:9C:5B:8E:18:61:61:D1:9C:AA:0E:8C:B1:EA:44:C2:6E:67:5D:96:30:EC:8C:F6:6F:E1:EC:AD:00:60:F1 - Signature algorithm name: SHA256withRSA - Version: 3 - -Extensions: - -#1: ObjectId: 2.5.29.35 Criticality=false -AuthorityKeyIdentifier [ -KeyIdentifier [ -0000: A6 BD 5F B3 E8 7D 74 3D 20 44 66 1A 16 3B 1B DF .._...t= Df..;.. -0010: E6 E6 04 46 ...F -] -] - -#2: ObjectId: 2.5.29.19 Criticality=true -BasicConstraints:[ - CA:true - PathLen:2147483647 -] - -#3: ObjectId: 2.5.29.15 Criticality=true -KeyUsage [ - Key_CertSign - Crl_Sign -] - -#4: ObjectId: 2.5.29.14 Criticality=false -SubjectKeyIdentifier [ -KeyIdentifier [ -0000: A6 BD 5F B3 E8 7D 74 3D 20 44 66 1A 16 3B 1B DF .._...t= Df..;.. -0010: E6 E6 04 46 ...F -] -] - - - -******************************************* -******************************************* ----- - -In addition, you can split `$JETTY/etc/keystore` as two files. -One is `$JETTY/etc/keystore` which only contains the server’s private key and certificate, -the other is `$JETTY/etc/truststore` which contains intermediary CA and root CA. - -[literal] -.The structure of `$JETTY/etc/keystore` -.... -└── PrivateKeyEntry -    ├── PrivateKey -    └── Certificate chain -       └── Server certificate (end entity) -.... - -[literal] -.The structure of `$JETTY/etc/truststore` -.... -├── TrustedCertEntry -│   └── Intermediary CA certificate -└── TrustedCertEntry -    └── Root CA certificate -.... - -[[configuring-sslcontextfactory]] -==== Configuring the Jetty SslContextFactory - -The generated SSL certificates from above are held in the key store are configured in an instance of link:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.Server.html[SslContextFactory.Server] object. - -The `SslContextFactory` is responsible for: - -* Creating the Java `SslEngine` used by Jetty's Connectors and Jetty's Clients (HTTP/1, HTTP/2, and WebSocket). -* Managing Keystore Access -* Managing Truststore Access -* Managing Protocol selection via Excludes / Includes list -* Managing Cipher Suite selection via Excludes / Includes list -* Managing order of Ciphers offered (important for TLS/1.2 and HTTP/2 support) -* SSL Session Caching options -* Certificate https://en.wikipedia.org/wiki/Revocation_list[Revocation Lists] and Distribution Points (CRLDP) -* https://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol[OCSP] Support -* Client Authentication Support - -For Jetty Connectors, the configured `SslContextFactory.Server` is injected into a specific ServerConnector `SslConnectionFactory`. - -For Jetty Clients, the various constructors support using a configured `SslContextFactory.Client`. - -While the `SslContextFactory` can operate without a keystore (this mode is most suitable for the various Jetty Clients) it is best practice to at least configure the keystore being used. - -setKeyStorePath:: - The configured keystore to use for all SSL/TLS in configured Jetty Connector (or Client). -____ -[NOTE] -As a keystore is vital security information, it can be desirable to locate the file in a directory with *very* restricted access. -____ - -setKeyStorePassword:: - The keystore password may be set here in plain text, or as some measure of protection from casual observation, it may be obfuscated using the link:{JDURL}/org/eclipse/jetty/util/security/Password.html[Password] class. -setTrustStorePath:: - This is used if validating client certificates and is typically set to the same path as the keystore. -setKeyManagerPassword:: - The password that is passed to the `KeyManagerFactory.init(...)`. - If there is no `keymanagerpassword`, then the `keystorepassword` is used instead. - If there is no `trustmanager` set, then the keystore is used as the trust store and the `keystorepassword` is used as the truststore password. -setExcludeCipherSuites / setIncludeCipherSuites:: - This allows for the customization of the selected Cipher Suites that will be used by SSL/TLS. -setExcludeProtocols / setIncludeProtocols:: - This allows for the customization of the selected Protocols that will be used by SSL/TLS. - -____ -[NOTE] -When working with Includes / Excludes, it is important to know that *Excludes will always win.* -The selection process is to process the JVM list of available Cipher Suites or Protocols against the include list, then remove the excluded ones. -Be aware that each Include / Exclude list has a Set method (replace the list) or Add method (append the list). -____ - -____ -[CAUTION] -The keystore and truststore passwords may also be set using the system properties: `org.eclipse.jetty.ssl.keypassword` `org.eclipse.jetty.ssl.password`. -This is _not_ a recommended usage. -____ - -[[conscrypt]] -==== Conscrypt SSL - -Jetty 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 for the link:{GITBROWSEURL}/jetty-alpn/jetty-alpn-conscrypt-server/src/test/java/org/eclipse/jetty/alpn/conscrypt/server/ConscryptHTTP2Server.java[server] or link:{GITBROWSEURL}/jetty-alpn/jetty-alpn-conscrypt-client/src/test/java/org/eclipse/jetty/alpn/java/client/ConscryptHTTP2Client.java[client] 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(new OpenSSLProvider()); -... -SslContextFactory.Server sslContextFactory = new SslContextFactory.Server(); -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.] - -If you are using Conscrypt with Java 8, you must exclude `TLSv1.3` protocol as it is now enabled per default with Conscrypt 2.0.0 but not supported by Java 8. - - -==== 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 `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-sslcontextfactory-cipherSuites]] -==== Disabling/Enabling Specific Cipher Suites - -New cipher suites are always being developed to stay ahead of attacks. -It's only a matter of time before the best of suites is exploited though, and making sure your server is up-to-date in this regard is paramount for any implementation. -As an example, to avoid the BEAST attack it is necessary to configure a specific set of cipher suites.This can either be done via link:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.html#setIncludeCipherSuites(java.lang.String...)[SslContext.setIncludeCipherSuites(java.lang.String...)] or vialink:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.html#setExcludeCipherSuites(java.lang.String...)[SslContext.setExcludeCipherSuites(java.lang.String...)]. - -It's crucial that you use the _exact_ names of the cipher suites as used/known by the JDK. -You can get them by obtaining an instance of SSLEngine and call `getSupportedCipherSuites()`. -Tools like https://www.ssllabs.com/[ssllabs.com] might report slightly different names which will be ignored. - -____ -[IMPORTANT] -It is important to stay up-to-date with the latest supported cipher suites. -Be sure to consult Oracle's link:https://java.com/en/jre-jdk-cryptoroadmap.html[JRE and JDK Cryptographic Roadmap] frequently for recent and upcoming changes to supported ciphers. -____ - -____ -[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 `/lib/security/`. -____ - -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 XML that configures the `SslContextFactory` to suit your needs. - -____ -[NOTE] -Jetty *does* allow users to enable weak/deprecated cipher suites (or even no cipher suites at all). -By default, if you have these suites enabled warning messages will appear in the server logs. -____ - -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-"). - -[source, xml, subs="{sub-order}"] ----- - - - - - - - - .*_RSA_.*SHA1$ - .*_RSA_.*SHA$ - .*_RSA_.*MD5$ - - - - ----- - -This new XML will configure the id `sslContextFactory` further (this id is first created by the `ssl` module and its associated `${jetty.home}/etc/jetty-ssl-context.xml`). -You can do anything you want with the `SslContextFactory` in use by the Jetty Distribution from this tweaked XML. - -To make sure that your `${jetty.base}` uses this new XML, add it to the end of your `${jetty.base}/start.ini` or `${jetty.base}/start.d/server.ini`. - -[source, plain, subs="{sub-order}"] ----- -$ cd /path/to/mybase -$ ls -l -drwxrwxr-x. 2 user group 4096 Feb 2 11:47 etc/ --rw-rw-r--. 1 user group 4259 Feb 2 11:47 start.ini -$ tail start.ini -# Module: https ---module=https -etc/tweak-ssl.xml -$ ----- - -____ -[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 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. -____ - -____ -[TIP] -You can enable the `org.eclipse.jetty.util.ssl` named logger at `DEBUG` level to see what the list of selected Protocols and Cipher suites are at startup of Jetty. -____ - -Additional Include / Exclude examples: - -*Example*: Include all ciphers which support https://en.wikipedia.org/wiki/Forward_secrecy[Forward Secrecy] using regex: - -[source, xml, subs="{sub-order}"] ----- - - - - TLS_DHE_RSA.* - TLS_ECDHE.* - - ----- - -*Example*: Exclude all old, insecure or anonymous cipher suites: - -[source, xml, subs="{sub-order}"] ----- - - - - - .*NULL.* - .*RC4.* - .*MD5.* - .*DES.* - .*DSS.* - - - ----- - -*Example*: Since 2014 SSLv3 is considered insecure and should be disabled. - -[source, xml, subs="{sub-order}"] ----- - - - - - SSL - SSLv2 - SSLv2Hello - SSLv3 - - - ----- - -____ -[NOTE] -Note that disabling SSLv3 prevents very old browsers like Internet Explorer 6 on Windows XP from connecting. -____ - -*Example*: TLS renegotiation could be disabled too to prevent an attack based on this feature. - -[source, xml, subs="{sub-order}"] ----- - FALSE ----- - -[[ssl-dump-ciphers]] - -You can view what cipher suites are enabled and disabled by performing a server dump. - -To perform a server dump upon server startup, add `jetty.server.dumpAfterStart=true` to the command line when starting the server. -You can also dump the server when shutting down the server instance by adding `jetty.server.dumpBeforeStop`. - -Specifically, you will want to look for the `SslConnectionFactory` portion of the dump. - -[source,screen,subs="{sub-order}"] ----- -[my-base]$ java -jar /path/to/jetty-home/start.jar jetty.server.dumpAfterStart=true - -... -| += SslConnectionFactory@18be83e4{SSL->http/1.1} - STARTED -| | += SslContextFactory@42530531(null,null) trustAll=false -| | +- Protocol Selections -| | | +- Enabled (size=3) -| | | | +- TLSv1 -| | | | +- TLSv1.1 -| | | | +- TLSv1.2 -| | | +- Disabled (size=2) -| | | +- SSLv2Hello - ConfigExcluded:'SSLv2Hello' -| | | +- SSLv3 - JreDisabled:java.security, ConfigExcluded:'SSLv3' -| | +- Cipher Suite Selections -| | +- Enabled (size=15) -| | | +- TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 -| | | +- TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 -| | | +- TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 -| | | +- TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 -| | | +- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 -| | | +- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 -| | | +- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 -| | | +- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 -| | | +- TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 -| | | +- TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 -| | | +- TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 -| | | +- TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 -| | | +- TLS_EMPTY_RENEGOTIATION_INFO_SCSV -| | | +- TLS_RSA_WITH_AES_128_CBC_SHA256 -| | | +- TLS_RSA_WITH_AES_128_GCM_SHA256 -| | +- Disabled (size=42) -| | +- SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- SSL_DHE_DSS_WITH_DES_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- SSL_DHE_RSA_WITH_DES_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- SSL_DH_anon_WITH_3DES_EDE_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- SSL_DH_anon_WITH_DES_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- SSL_RSA_EXPORT_WITH_DES40_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- SSL_RSA_WITH_3DES_EDE_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- SSL_RSA_WITH_DES_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- SSL_RSA_WITH_NULL_MD5 - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- SSL_RSA_WITH_NULL_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_DHE_DSS_WITH_AES_128_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_DHE_RSA_WITH_AES_128_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_DH_anon_WITH_AES_128_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_DH_anon_WITH_AES_128_CBC_SHA256 - JreDisabled:java.security -| | +- TLS_DH_anon_WITH_AES_128_GCM_SHA256 - JreDisabled:java.security -| | +- TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_ECDHE_ECDSA_WITH_NULL_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_ECDHE_RSA_WITH_NULL_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_ECDH_ECDSA_WITH_NULL_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_ECDH_RSA_WITH_AES_128_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_ECDH_RSA_WITH_NULL_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_ECDH_anon_WITH_AES_128_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_ECDH_anon_WITH_NULL_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5 - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_KRB5_WITH_3DES_EDE_CBC_MD5 - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_KRB5_WITH_3DES_EDE_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_KRB5_WITH_DES_CBC_MD5 - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_KRB5_WITH_DES_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_RSA_WITH_AES_128_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$' -| | +- TLS_RSA_WITH_NULL_SHA256 - JreDisabled:java.security -... ----- - -In the example above you can see both the enabled/disabled protocols and included/excluded cipher suites. -For disabled or excluded protocols and ciphers, the reason they are disabled is given - either due to JVM restrictions, configuration or both. -As a reminder, when configuring your includes/excludes, *excludes always win*. - -Dumps can be configured as part of the `jetty.xml` configuration for your server. -Please see the documentation on the link:#jetty-dump-tool[Jetty Dump Tool] for more information. - - -==== SslContextFactory KeyStore Reload - -Jetty can be configured to monitor the directory of the KeyStore file specified in the SslContextFactory, and reload the -SslContextFactory if any changes are detected to the KeyStore file. - -If changes need to be done to other file such as the TrustStore file, this must be done before the change to the Keystore -file which will then trigger the `SslContextFactory` reload. - -With the Jetty distribution this feature can be used by simply activating the `ssl-reload` startup module. -For embedded usage the `KeyStoreScanner` should be created given the `SslContextFactory` and added as a bean on the Server. diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc index 8d3ded80c29..33b1223c104 100644 --- a/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc +++ b/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc @@ -29,6 +29,7 @@ include::begin/chapter.adoc[] include::start/chapter.adoc[] include::deploy/chapter.adoc[] include::protocols/chapter.adoc[] +include::keystore/chapter.adoc[] include::modules/chapter.adoc[] include::sessions/chapter.adoc[] include::xml/chapter.adoc[] diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/keystore/chapter.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/keystore/chapter.adoc index 74693b7a560..1074dfb0154 100644 --- a/jetty-documentation/src/main/asciidoc/operations-guide/keystore/chapter.adoc +++ b/jetty-documentation/src/main/asciidoc/operations-guide/keystore/chapter.adoc @@ -19,5 +19,13 @@ [[og-keystore]] === Configuring KeyStores -TODO -// TODO: see old_docs/connectors/configuring-ssl.adoc +A KeyStore is a file on the file system that contains a private key and a public certificate, along with the certificate chain of the certificate authorities that issued the certificate. +The private key, the public certificate and the certificate chain, but more generally the items present in a KeyStore, are typically referred to as "cryptographic material". + +Keystores may encode the cryptographic material with different encodings, the most common being link:https://en.wikipedia.org/wiki/PKCS_12[PKCS12], and are typically protected by a password. + +Refer to the xref:og-protocols-ssl[secure protocols section] for more information about how to configure a secure connector using a KeyStore. + +include::keystore-create.adoc[] +include::keystore-csr.adoc[] +include::keystore-client-authn.adoc[] diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/keystore/keystore-client-authn.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/keystore/keystore-client-authn.adoc new file mode 100644 index 00000000000..51961cb4c2d --- /dev/null +++ b/jetty-documentation/src/main/asciidoc/operations-guide/keystore/keystore-client-authn.adoc @@ -0,0 +1,146 @@ +// +// ======================================================================== +// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others. +// +// This program and the accompanying materials are made available under +// the terms of the Eclipse Public License 2.0 which is available at +// https://www.eclipse.org/legal/epl-2.0 +// +// This Source Code may also be made available under the following +// Secondary Licenses when the conditions for such availability set +// forth in the Eclipse Public License, v. 2.0 are satisfied: +// the Apache License v2.0 which is available at +// https://www.apache.org/licenses/LICENSE-2.0 +// +// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +// ======================================================================== +// + +[[og-keystore-client-authn]] +==== Creating a KeyStore for Client Certificate Authentication + +For the majority of secure web sites, it is the client (typically the browser) that validates the certificate sent by the server (by verifying the certificate chain). +This is the _server domain certificate_. + +However, the TLS protocol supports a _mutual authentication_ mode where also the client must send a certificate to the server, that the server validates. + +You typically want to sign the client certificate(s) with a server certificate that you control, and you must distribute the client certificate(s) to all the clients that need it, and redistribute the client certificates when they expire. +The _server authentication certificate_ may be different from the _server domain certificate_, but it's typically stored in the same KeyStore for simplicity (although under a different alias). + +First, you want to create the private key and server authentication certificate that you will use to sign client certificates: + +[source,subs=verbatim] +---- +keytool + -genkeypair + -alias server_authn <1> + -validity 90 + -keyalg RSA + -keysize 2048 + -keystore keystore.p12 <2> + -storetype pkcs12 + -dname "CN=server_authn, OU=Unit, O=Company, L=City, S=State, C=Country" <3> + -ext bc=ca:true <4> + -v +---- +<1> use the `server_authn` alias to differentiate from the alias of the server certificate +<2> the KeyStore file +<3> the CN is not that important, since this certificate will not be validated by clients +<4> the extension with the basic constraints (more below) + +IMPORTANT: The important difference with the xref:og-keystore-create[creation of a server certificate] is the _basic constraints_ extension (`bc`) that indicates that this certificates acts as a certificate authority (`ca:true`). + +Now you want to export both the private key and server authentication certificate. +Unfortunately, the `keytool` program cannot export private keys, so you need to use a different command line program like `openssl`, or a graphical program like link:https://keystore-explorer.org/[KeyStore Explorer]. + +Let's use `openssl` to export the server authentication private key: + +---- +openssl + pkcs12 + -in keystore.p12 + -nodes + -nocerts + -out server_authn.key +---- + +Now let's export the server authentication certificate: + +---- +keytool + -exportcert + -keystore keystore.p12 + -rfc + -file server_authn.crt + -v +---- + +At this point, you want to create a client KeyStore, so that you can sign the client certificate with the server authentication cryptographic material: + +[source,subs=verbatim] +---- +keytool + -genkeypair + -validity 90 + -keyalg RSA + -keysize 2048 + -keystore client_keystore.p12 <1> + -storetype pkcs12 + -dname "CN=client, OU=Unit, O=Company, L=City, S=State, C=Country" <2> + -v +---- +<1> the client KeyStore file +<2> the CN is not that important, since it will not be validated by the server + +Now produce a certificate signing request (CSR): + +---- +keytool + -certreq + -file client.csr + -keystore client_keystore.p12 +---- + +Now you need to sign the CSR, but again the `keytool` program does not have this functionality, and you must resort again to use `openssl`: + +---- +openssl + x509 + -req + -days 90 + -in client.csr + -CA server_authn.crt + -CAkey server_authn.key + -CAcreateserial + -sha256 + -out signed.crt +---- + +Now you need to import the server authentication certificate and the signed client certificate into the client KeyStore. + +First, the server authentication certificate: + +---- +keytool + -importcert + -alias ca + -file server_authn.crt + -keystore client_keystore.p12 + -v +---- + +Then, the signed client certificate: + +---- +keytool + -importcert + -file signed.crt + -keystore client_keystore.p12 + -v +---- + +Now you can distribute `client_keystore.p12` to your client(s). + +// TODO: add a section about renewal? + +Refer to the section about configuring xref:og-protocols-ssl[secure protocols] to configure the secure connector to require client authentication. diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/keystore/keystore-create.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/keystore/keystore-create.adoc new file mode 100644 index 00000000000..c577950f964 --- /dev/null +++ b/jetty-documentation/src/main/asciidoc/operations-guide/keystore/keystore-create.adoc @@ -0,0 +1,60 @@ +// +// ======================================================================== +// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others. +// +// This program and the accompanying materials are made available under +// the terms of the Eclipse Public License 2.0 which is available at +// https://www.eclipse.org/legal/epl-2.0 +// +// This Source Code may also be made available under the following +// Secondary Licenses when the conditions for such availability set +// forth in the Eclipse Public License, v. 2.0 are satisfied: +// the Apache License v2.0 which is available at +// https://www.apache.org/licenses/LICENSE-2.0 +// +// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +// ======================================================================== +// + +[[og-keystore-create]] +==== Creating a KeyStore + +KeyStores are created with the JDK tool `$JAVA_HOME/bin/keytool`. + +The following command creates a KeyStore file containing a private key and a self-signed certificate: + +[source,subs=verbatim] +---- +keytool + -genkeypair <1> + -validity 90 <2> + -keyalg RSA <3> + -keysize 2048 <4> + -keystore /path/to/keystore.p12 <5> + -storetype pkcs12 <6> + -dname "CN=domain.com, OU=Unit, O=Company, L=City, S=State, C=Country" <7> + -ext san=dns:www.domain.com,dns:domain.org <8> + -v <9> +---- +<1> the command to generate a key and certificate pair +<2> specifies the number of days after which the certificate expires +<3> the algorithm _must_ be RSA (the DSA algorithm does not work for web sites) +<4> indicates the strength of the key +<5> the keyStore file +<6> the keyStore type, stick with the standard PKCS12 +<7> the distinguished name (more below) -- customize it with your values for CN, OU, O, L, S and C +<8> the extension with the subject alternative names (more below) +<9> verbose output + +The command prompts for the KeyStore password that you must choose to protect the access to the KeyStore. + +[IMPORTANT] +==== +The important parts of the command above are the _Common Name_ (CN) part of the distinguished name, and the subject alternative names (SAN). + +The CN value must be the main domain you own and that you want to use for your web applications. +For example, if you have bought domains `domain.com` and `domain.org`, you want to specify `CN=domain.com` as your main domain. + +Furthermore, to specify additional domains or subdomains within the same certificate, you must specify the SAN extension. +In the example above, `san=dns:www.domain.com,dns:domain.org` specifies `www.domain.com` and `domain.org` as alternative names for your web applications (that you can configure using xref:og-deploy-virtual-hosts[virtual hosts]). +==== diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/keystore/keystore-csr.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/keystore/keystore-csr.adoc new file mode 100644 index 00000000000..7ade0e11218 --- /dev/null +++ b/jetty-documentation/src/main/asciidoc/operations-guide/keystore/keystore-csr.adoc @@ -0,0 +1,83 @@ +// +// ======================================================================== +// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others. +// +// This program and the accompanying materials are made available under +// the terms of the Eclipse Public License 2.0 which is available at +// https://www.eclipse.org/legal/epl-2.0 +// +// This Source Code may also be made available under the following +// Secondary Licenses when the conditions for such availability set +// forth in the Eclipse Public License, v. 2.0 are satisfied: +// the Apache License v2.0 which is available at +// https://www.apache.org/licenses/LICENSE-2.0 +// +// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +// ======================================================================== +// + +[[og-keystore-csr]] +==== Creating a Certificate Signing Request + +Self-signed certificates are not trusted by browsers and generic clients: you need to establish a trust chain by having your self-signed certificate signed by a certificate authority (CA). + +Browsers and generic clients (e.g. Java clients) have an internal list of trusted certificate authorities root certificates; they use these trusted certificates to verify the certificate they received from the server when they connect to your web applications. + +To have your self-signed certificate signed by a certificate authority you first need to produce a _certificate signing request_ (CSR): + +[source,subs=verbatim] +---- +keytool + -certreq <1> + -file domain.com.csr <2> + -keystore keystore.p12 <3> +---- +<1> the command to generate a certificate signing request +<2> the file to save the CSR +<3> the keystore that contains the self-signed certificate + +Then, you have to send the CSR file to the certificate authority of your choice, and wait for their reply (they will probably require a proof that you really own the domains indicated in your certificate). + +Eventually, the certificate authority will reply to you with one or more files containing the CA certificate chain, and your certificate signed by their certificate chain. + +[[og-keystore-csr-import]] +==== Importing the Signed Certificate + +The file you receive from the CA is typically in PEM format, and you *must* import it back into the same KeyStore file you used to generate the CSR. +You must import *both* the certificate chain and your signed certificate. + +First, import the certificate chain: + +[source,subs=verbatim] +---- +keytool + -importcert <1> + -alias ca <2> + -file chain_from_ca.pem <3> + -keystore keystore.p12 <4> + -trustcacerts <5> + -v <6> +---- +<1> the command to import certificates +<2> use the `ca` alias to differentiate from the alias of the server certificate +<3> the file containing the certificate chain received from the CA +<4> your KeyStore file +<5> specify that you trust CA certificates +<6> verbose output + +Then, import the signed certificate: + +---- +keytool + -importcert + -file signed_certificate.pem + -keystore keystore.p12 + -trustcacerts + -v +---- + +Now you have a trusted certificate in your KeyStore that you can use for the domains of your web applications. + +// TODO: add a section about renewal? + +Refer to the section about configuring xref:og-protocols-ssl[secure protocols] to configure the secure connector with your newly created KeyStore. diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-http.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-http.adoc index 7044dac497b..09453c1f9f8 100644 --- a/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-http.adoc +++ b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-http.adoc @@ -19,12 +19,12 @@ [[og-module-http]] ==== Module `http` -The `http` module provides support for the clear-text HTTP/1.1 protocol and depends on the xref:og-module-server[`server` module]. +The `http` module provides the clear-text connector and support for the clear-text HTTP/1.1 protocol, and depends on the xref:og-module-server[`server` module]. -The module file is `$JETTY_HOME/modules/http.mod`: +The module properties to configure the clear-text connector are: ---- -include::{JETTY_HOME}/modules/http.mod[] +include::{JETTY_HOME}/modules/http.mod[tags=documentation] ---- Among the configurable properties, the most relevant are: diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-ssl-reload.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-ssl-reload.adoc new file mode 100644 index 00000000000..56e65801dd6 --- /dev/null +++ b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-ssl-reload.adoc @@ -0,0 +1,29 @@ +// +// ======================================================================== +// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others. +// +// This program and the accompanying materials are made available under +// the terms of the Eclipse Public License 2.0 which is available at +// https://www.eclipse.org/legal/epl-2.0 +// +// This Source Code may also be made available under the following +// Secondary Licenses when the conditions for such availability set +// forth in the Eclipse Public License, v. 2.0 are satisfied: +// the Apache License v2.0 which is available at +// https://www.apache.org/licenses/LICENSE-2.0 +// +// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +// ======================================================================== +// + +[[og-module-ssl-reload]] +==== Module `ssl-reload` + +The `ssl-reload` module provides a periodic scanning of the directory where the KeyStore file resides. +When the scanning detects a change to the KeyStore file, the correspondent `SslContextFactory.Server` component is reloaded with the new KeyStore configuration. + +The module properties are: + +---- +include::{JETTY_HOME}/modules/ssl-reload.mod[tags=documentation] +---- diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-ssl.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-ssl.adoc index 11b105ec44d..ffadc3bf435 100644 --- a/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-ssl.adoc +++ b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-ssl.adoc @@ -19,14 +19,54 @@ [[og-module-ssl]] ==== Module `ssl` -The `ssl` module provides the secure connector, and allows you to configure the keystore properties and the TLS parameters. +The `ssl` module provides the secure connector, and allows you to configure the KeyStore properties and the TLS parameters, and depends on the xref:og-module-server[`server` module]. -The module file is `$JETTY_HOME/modules/ssl.mod`: +[[og-module-ssl-connector]] +===== Secure Connector Properties + +The module properties to configure the secure connector are: ---- -include::{JETTY_HOME}/modules/ssl.mod[] +include::{JETTY_HOME}/modules/ssl.mod[tags=documentation-connector] ---- Among the configurable properties, the most relevant are: -TODO +`jetty.ssl.port`:: +the network port that Jetty listens to for secure connections -- default `8443`. +`jetty.http.idleTimeout`:: +the amount of time a connection can be idle (i.e. no bytes received and no bytes sent) until the server decides to close it to save resources -- default `30000` milliseconds. +`jetty.http.acceptors`:: +the number of threads that compete to accept connections -- default -1 (i.e. an accept heuristic decides the value based on the number of cores). +Refer to xref:og-module-http-acceptors[this section] for more information about acceptor threads. +`jetty.http.selectors`:: +the number of NIO selectors (with an associated thread) that manage connections -- default -1 (i.e. a select heuristic decides the value based on the number of cores). +Refer to xref:og-module-http-selectors[this section] for more information about selector threads. + +The module properties to configure the KeyStore and TLS parameters are: + +---- +include::{JETTY_HOME}/modules/ssl.mod[tags=documentation-ssl-context] +---- + +[[og-module-ssl-keystore-tls]] +===== KeyStore Properties and TLS Properties + +Among the configurable properties, the most relevant are: + +jetty.sslContext.keyStorePath:: +the KeyStore path on the file system. +If it is a relative path, it is relative to `$JETTY_BASE`. +Defaults to `$JETTY_BASE/etc/keystore.p12`. +`jetty.sslContext.keyStorePassword`:: +the KeyStore password, which you want to explicitly configure. +The password may be obfuscated with the xref:og-password[Jetty Password Tool]. + +If you need to configure client certificate authentication, you want to configure one of these properties (they are mutually exclusive): + +`jetty.sslContext.needClientAuth`:: +whether client certificate authentication should be required. +`jetty.sslContext.wantClientAuth`:: +whether client certificate authentication should be requested. + +If you configure client certificate authentication, you need to configure and distribute a client KeyStore as explained in xref:og-keystore-client-authn[this section]. diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-test-keystore.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-test-keystore.adoc index eee9a0a42a0..16e5c4dbb24 100644 --- a/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-test-keystore.adoc +++ b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-test-keystore.adoc @@ -19,7 +19,7 @@ [[og-module-test-keystore]] ==== Module `test-keystore` -The `test-keystore` module provides a keystore containing a self-signed certificate for domain `localhost`. +The `test-keystore` module provides a KeyStore containing a self-signed certificate for domain `localhost`. The module file is `$JETTY_HOME/modules/test-keystore.mod`: @@ -28,4 +28,4 @@ include::{JETTY_HOME}/modules/test-keystore.mod[] ---- Note how properties `jetty.sslContext.keyStorePath` and `jetty.sslContext.keyStorePassword` are configured, only if not already set (via the `?=` operator), directly in the module file, rather than in a `+*.ini+` file. -This is done to avoid that these properties accidentally overwrite a real keystore configuration. +This is done to avoid that these properties accidentally overwrite a real KeyStore configuration. diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http2s.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http2s.adoc index d171bd5420e..40ae32e2224 100644 --- a/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http2s.adoc +++ b/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http2s.adoc @@ -23,7 +23,7 @@ When you enable secure HTTP/2 you typically want to enable also secure HTTP/1.1, You need to enable: -* the `ssl` Jetty module, which provides the secure connector and the keystore and TLS configuration +* the `ssl` Jetty module, which provides the secure connector and the KeyStore and TLS configuration * the `http2` Jetty module, which adds ALPN handling and adds the HTTP/2 protocol to the secured connector * optionally, the `https` Jetty module, which adds the HTTP/1.1 protocol to the secured connector @@ -33,9 +33,9 @@ Use the following command (issued from within the `$JETTY_BASE` directory): $ java -jar $JETTY_HOME/start.jar --add-modules=ssl,http2,https ---- -As when enabling the `https` Jetty module, you need a valid keystore (read xref:og-keystore[this section] to create your own keystore). +As when enabling the `https` Jetty module, you need a valid KeyStore (read xref:og-keystore[this section] to create your own KeyStore). -As a quick example, you can enable the xref:og-module-test-keystore[`test-keystore` module], that provides a keystore containing a self-signed certificate: +As a quick example, you can enable the xref:og-module-test-keystore[`test-keystore` module], that provides a KeyStore containing a self-signed certificate: ---- $ java -jar $JETTY_HOME/start.jar --add-modules=test-keystore diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-https.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-https.adoc index fe43c38973f..126bd7fef8b 100644 --- a/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-https.adoc +++ b/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-https.adoc @@ -40,7 +40,7 @@ INFO : copy ${jetty.home}/modules/logging/jetty/resources/jetty-logging.propert INFO : Base directory was modified ---- -The command above enables the `ssl` module, that provides the secure network connector, the keystore configuration and TLS configuration -- for more details see xref:og-protocols-ssl[this section]. +The command above enables the `ssl` module, that provides the secure network connector, the KeyStore configuration and TLS configuration -- for more details see xref:og-protocols-ssl[this section]. Then, the xref:og-module-https[`https` module] adds HTTP/1.1 as the protocol secured by TLS. The `$JETTY_BASE` directory looks like this: @@ -55,13 +55,13 @@ $JETTY_BASE └── ssl.ini ---- -Note that the keystore file is missing, because you have to provide one with the cryptographic material you want (read xref:og-keystore[this section] to create your own keystore). +Note that the KeyStore file is missing, because you have to provide one with the cryptographic material you want (read xref:og-keystore[this section] to create your own KeyStore). You need to configure these two properties by editing `ssl.ini`: * `jetty.sslContext.keyStorePath` * `jetty.sslContext.keyStorePassword` -As a quick example, you can enable the xref:og-module-test-keystore[`test-keystore` module], that provides a keystore containing a self-signed certificate: +As a quick example, you can enable the xref:og-module-test-keystore[`test-keystore` module], that provides a KeyStore containing a self-signed certificate: ---- $ java -jar $JETTY_HOME/start.jar --add-modules=test-keystore diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-ssl.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-ssl.adoc index 0d2032b8d4b..7f29ed4911b 100644 --- a/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-ssl.adoc +++ b/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-ssl.adoc @@ -19,29 +19,252 @@ [[og-protocols-ssl]] ==== Configuring Secure Protocols -Secure protocols are normal protocols such as HTTP/1.1 or WebSocket that are wrapped by the link:https://en.wikipedia.org/wiki/Transport_Layer_Security[TLS protocol]. +Secure protocols are normal protocols such as HTTP/1.1, HTTP/2 or WebSocket that are wrapped by the link:https://en.wikipedia.org/wiki/Transport_Layer_Security[TLS protocol]. Any network protocol can be wrapped with TLS. -The `https` scheme used in URIs really means `tls+http/1.1` and similarly the `wss` scheme used in URIs really means `tls+websocket`, etc. -Senders wrap the underlying protocol bytes (e.g. HTTP/1.1 bytes or WebSocket bytes) with the TLS protocol, while receivers first interpret the TLS protocol to obtain the underlying protocol bytes, and then interpret the wrapped bytes. +The `https` scheme used in URIs really means `tls+http/1.1` (or `tls+http/2`) and similarly the `wss` scheme used in URIs really means `tls+websocket`, etc. +Senders wrap the underlying protocol bytes (e.g. HTTP bytes or WebSocket bytes) with the TLS protocol, while receivers first interpret the TLS protocol to obtain the underlying protocol bytes, and then interpret the wrapped bytes. -Secure protocols have a slightly more complicated configuration since they require to configure a _keystore_. - -A keystore is a file on the file system that contains a private key and a public certificate, along with the certificate chain of the certificate authorities that issued the certificate. -The private key, the public certificate and the certificate chain, but more generally the items present in a keystore, are typically referred to as "cryptographic material". - -Keystores may encode the cryptographic material with different encodings, the most common being link:https://en.wikipedia.org/wiki/PKCS_12[PKCS12], and are typically protected by a password. - -After configuring the keystore path and keystore password, you may want to further customize the parameters of the TLS protocol, such as the minimum TLS protocol version, or the TLS algorithms, etc. - -The `ssl` Jetty module allows you to configure a secure network connector -- i.e. a connector configured with the TLS protocol, the keystore and the TLS parameters; if other modules require encryption, they declare a dependency on the `ssl` module. +The xref:og-module-ssl[`ssl` Jetty module] allows you to configure a secure network connector; if other modules require encryption, they declare a dependency on the `ssl` module. It is the job of other Jetty modules to configure the wrapped protocol. - For example, it is the xref:og-protocols-https[`https` module] that configures the wrapped protocol to be HTTP/1.1. Similarly, it is the xref:og-protocols-http2[`http2` module] that configures the wrapped protocol to be HTTP/2. +If you enable _both_ the `https` and the `http2` module, you will have a single secure connector that will be able to interpret both HTTP/1.1 and HTTP/2. -Recall from the xref:og-modules[section about modules], that only modules that are explicitly enabled get their module configuration file (`+*.ini+`) saved in `$JETTY_BASE/start.d/`, and you want `$JETTY_BASE/start.d/ssl.ini` to be present so that you can configure the connector properties, the keystore properties and the TLS properties. +TIP: Recall from the xref:og-modules[section about modules], that only modules that are explicitly enabled get their module configuration file (`+*.ini+`) saved in `$JETTY_BASE/start.d/`, and you want `$JETTY_BASE/start.d/ssl.ini` to be present so that you can configure the connector properties, the KeyStore properties and the TLS properties. -// TODO: section about client authentication with certificates? -// See readme_keystores.txt about the fact that the server keystore needs the CA=true extension. +===== Customizing KeyStore and TLS Configuration + +Secure protocols have a slightly more complicated configuration since they require to configure a _KeyStore_. +Refer to the xref:og-keystore[KeyStore section] for more information about how to create and manage a KeyStore. + +For simple cases, you only need to configure the KeyStore path and KeyStore password as explained in xref:og-module-ssl-keystore-tls[this section]. + +For more advanced configuration you may want to configure the TLS protocol versions, or the ciphers to include/exclude, etc. +The correct way of doing this is to create a custom xref:og-xml[Jetty XML file] and reference it in `$JETTY_BASE/start.d/ssl.ini`: + +.ssl.ini +[source,subs=verbatim] +---- +jetty.sslContext.keyStorePassword=my_passwd! <1> +etc/tls-config.xml <2> +---- +<1> Configures the `jetty.sslContext.keyStorePassword` property with the KeyStore password. +<2> References your newly created `$JETTY_BASE/etc/tls-config.xml`. + +The `ssl.ini` file above only shows the lines that are not commented out (you can leave the lines that are commented unmodified for future reference). + +You want to create the `$JETTY_BASE/etc/tls-config.xml` with the following template content: + +.tls-config.xml +[source,xml,subs=verbatim] +---- + + + + + + ... <1> + + +---- +<1> Here goes your advanced configuration. + +The `tls-config.xml` file references the `sslContextFactory` component (created by the `ssl` Jetty module) that configures the KeyStore and TLS parameters, so that you can now call its APIs via XML, and you will have full flexibility for any advanced configuration you want (see below for few examples). + +Refer to the link:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.html[SslContextFactory javadocs] for the list of methods that you can call through the Jetty XML file. + +CAUTION: Use module properties whenever possible, and only resort to use a Jetty XML file for advanced configuration that you cannot do using module properties. + +====== Customizing TLS Protocol Versions + +By default, the SSL protocols (SSL, SSLv2, SSLv3, etc.) are already excluded because they are vulnerable. +To explicitly add the exclusion of TLSv1.0 and TLSv1.1 (that are also vulnerable -- which leaves only TLSv1.2 and TLSv1.3 available), you want to use this XML: + +.tls-config.xml +[source,xml] +---- + + + + + + + + + TLSv1.0 + TLSv1.1 + + + + + +---- + +====== Customizing TLS Ciphers + +You can precisely set the list of excluded ciphers, completely overriding Jetty's default, with this XML: + +.tls-config.xml +[source,xml] +---- + + + + + + + + ^TLS_RSA_.*$ + ^.*_RSA_.*_(MD5|SHA|SHA1)$ + ^.*_DHE_RSA_.*$ + SSL_RSA_WITH_DES_CBC_SHA + SSL_DHE_RSA_WITH_DES_CBC_SHA + SSL_DHE_DSS_WITH_DES_CBC_SHA + SSL_RSA_EXPORT_WITH_RC4_40_MD5 + SSL_RSA_EXPORT_WITH_DES40_CBC_SHA + SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA + SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA + + + + +---- + +Note how each array item specifies a _regular expression_ that matches multiple ciphers, or specifies a precise cipher to exclude. + +You can choose to create multiple XML files, and reference them all from `$JETTY_BASE/start.d/ssl.ini`, or put all your custom configurations in a single XML file. + +[[og-protocols-ssl-renew]] +===== Renewing the Certificates + +When you create a certificate, you must specify for how many days it is valid. + +The typical validity is 90 days, and while this period may seem short, it has two advantages: + +* Reduces the risk in case of compromised/stolen keys. +* Encourages automation, i.e. certificate renewal performed by automated tools (rather than manually) at scheduled times. + +To renew a certificate, you must go through the xref:og-keystore-create[same steps] you followed to create the certificate the first time, and then you can xref:og-protocols-ssl-reload[reload the KeyStore] without the need to stop Jetty. + +[[og-protocols-ssl-reload]] +===== Watching and Reloading the KeyStore + +Jetty can be configured to monitor the directory of the KeyStore file, and reload the `SslContextFactory` component if the KeyStore file changed. + +This feature can be enabled by activating the `ssl-reload` Jetty module: + +---- +$ java -jar $JETTY_HOME/start.jar --add-module=ssl-reload +---- + +For more information about the configuration of the `ssl-reload` Jetty module, see xref:og-module-ssl-reload[this section]. + +===== Using Conscrypt as TLS Provider + +By default, the standard TLS provider that comes with the JDK is used. + +The standard TLS provider from OpenJDK is implemented in Java (no native code), and its performance is not optimal, both in CPU usage and memory usage. + +A faster alternative, implemented natively, is Google's link:https://github.com/google/conscrypt/[Conscrypt], which is built on link:https://boringssl.googlesource.com/boringssl/[BoringSSL], which is Google's fork of link:https://www.openssl.org/[OpenSSL]. + +CAUTION: As Conscrypt eventually binds to a native library, there is a higher risk that a bug in Conscrypt or in the native library causes a JVM crash, while the Java implementation will not cause a JVM crash. + +To use Conscrypt as the TLS provider just enable the `conscrypt` Jetty module: + +---- +$ java -jar $JETTY_HOME/start.jar --add-module=conscrypt +---- + +===== Configuring SNI + +Server Name Indication (SNI) is a TLS extension that clients send to indicate what domain they want to connect to during the initial TLS handshake. + +Modern TLS clients (e.g. browsers) always send the SNI extension; however, older TLS clients may not send the SNI extension. + +Being able to handle the SNI is important when you have xref:og-deploy-virtual-hosts[virtual hosts] and a KeyStore with multiple certificates, one for each domain. + +For example, you have deployed over a secure connector two web applications, both at context path `/`, one at virtual host `one.com` and one at virtual host `two.net`. +The KeyStore contains two certificates, one for `one.com` and one for `two.net`. + +There are three `ssl` module properties that control the SNI behavior on the server: one that works at the TLS level, and two that works at the HTTP level. + +`jetty.sslContext.sniRequired`:: +This is the TLS level property, defaults to `false`. + +Its behavior is explained by the following table: + +.Behavior of the `jetty.sslContext.sniRequired` property +[cols="3*a"] +|=== + +| +| `sniRequired=false` +| `sniRequired=true` + +| SNI = `null` +| client receives default certificate +| client receives TLS failure + +| SNI = `wrong.org` +| client receives default certificate +| client receives TLS failure + +| SNI = `one.com` +| client receives `one.com` certificate +| client receives `one.com` certificate + +|=== + +WARNING: The _default certificate_ is the certificate returned by the TLS implementation in case there is no SNI match, and you should not rely on this certificate to be the same across Java vendors and versions, or Jetty versions, or TLS provider vendors and versions. + +`jetty.ssl.sniRequired`:: +Whether SNI is required at the HTTP level, defaults to `false`. +`jetty.ssl.sniHostCheck`:: +Whether the SNI domain must be verified at the HTTP level against the `Host` header, defaults to `true`. + +Their combined behavior is explained by the following table. + +.Behavior of the `jetty.ssl.[sniRequired|sniHostCheck]` properties +[cols="5*a"] +|=== + +| +| `sniRequired=false` + + `sniHostCheck=false` + +| `sniRequired=false` + + `sniHostCheck=true` + +| `sniRequired=true` + + `sniHostCheck=false` + +| `sniRequired=true` + + `sniHostCheck=true` + +| SNI = `null` +| 200 OK +| 200 OK +| 400 Bad Request +| 400 Bad Request + +| SNI = `wrong.org` +| 200 OK +| 400 Bad Request +| 400 Bad Request +| 400 Bad Request + +| SNI = `one.com` +| 200 OK +| SNI matches `Host` header ? + +200 OK : 400 Bad Request +| 200 OK +| SNI matches `Host` header ? + +200 OK : 400 Bad Request + +|=== + +In the normal case, with modern TLS clients and HTTP requests with a correct `Host` header, Jetty will pick the correct certificate from the KeyStore based on the SNI and respond with an HTTP 200 OK. + +You may modify the default values of the SNI properties if you want stricter control over old/broken TLS clients or bad HTTP requests. diff --git a/jetty-server/src/main/config/modules/http.mod b/jetty-server/src/main/config/modules/http.mod index 998869f5bd7..4134e2276d1 100644 --- a/jetty-server/src/main/config/modules/http.mod +++ b/jetty-server/src/main/config/modules/http.mod @@ -1,8 +1,6 @@ -# DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html - [description] -Enables an HTTP connector on the server. -By default HTTP/1 is support, but HTTP2C can be added to the connector by enabling the http2c module. +Enables a clear-text HTTP connector. +By default clear-text HTTP/1.1 is enabled, and clear-text HTTP/2 may be added by enabling the "http2c" module. [tags] connector @@ -15,43 +13,41 @@ server etc/jetty-http.xml [ini-template] -### HTTP Connector Configuration +# tag::documentation[] +### Clear-Text HTTP Connector Configuration -## Connector host/address to bind to +## The host/address to bind the connector to. # jetty.http.host=0.0.0.0 -## Connector port to listen on +## The port the connector listens on. # jetty.http.port=8080 -## Connector idle timeout in milliseconds +## The connector idle timeout, in milliseconds. # jetty.http.idleTimeout=30000 -## Number of acceptors (-1 picks default based on number of cores) +## The number of acceptors (-1 picks a default value based on number of cores). # jetty.http.acceptors=-1 -## Number of selectors (-1 picks default based on number of cores) +## The number of selectors (-1 picks a default value based on number of cores). # jetty.http.selectors=-1 -## ServerSocketChannel backlog (0 picks platform default) +## The ServerSocketChannel accept queue backlog (0 picks the platform default). # jetty.http.acceptQueueSize=0 -## Thread priority delta to give to acceptor threads +## The thread priority delta to give to acceptor threads. # jetty.http.acceptorPriorityDelta=0 -## The requested maximum length of the queue of incoming connections. -# jetty.http.acceptQueueSize=0 - -## Enable/disable the SO_REUSEADDR socket option. +## Whether to enable the SO_REUSEADDR socket option. # jetty.http.reuseAddress=true -## Enable/disable TCP_NODELAY on accepted sockets. +## Whether to enable the TCP_NODELAY socket option on accepted sockets. # jetty.http.acceptedTcpNoDelay=true -## The SO_RCVBUF option to set on accepted sockets. A value of -1 indicates that it is left to its default value. +## The SO_RCVBUF socket option to set on accepted sockets. +## A value of -1 indicates that the platform default is used. # jetty.http.acceptedReceiveBufferSize=-1 -## The SO_SNDBUF option to set on accepted sockets. A value of -1 indicates that it is left to its default value. +## The SO_SNDBUF socket option to set on accepted sockets. +## A value of -1 indicates that the platform default is used. # jetty.http.acceptedSendBufferSize=-1 - -## Connect Timeout in milliseconds -# jetty.http.connectTimeout=15000 +# end::documentation[] diff --git a/jetty-server/src/main/config/modules/ssl-reload.mod b/jetty-server/src/main/config/modules/ssl-reload.mod index 03f641e8a9f..9dca8473d55 100644 --- a/jetty-server/src/main/config/modules/ssl-reload.mod +++ b/jetty-server/src/main/config/modules/ssl-reload.mod @@ -1,7 +1,5 @@ -# DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html - [description] -Enables the SSL keystore to be reloaded after any changes are detected on the file system. +Enables the KeyStore to be reloaded when the KeyStore file changes. [tags] connector @@ -14,5 +12,7 @@ ssl etc/jetty-ssl-context-reload.xml [ini-template] -# Monitored directory scan period (seconds) +# tag::documentation[] +# Monitored directory scan period, in seconds. # jetty.sslContext.reload.scanInterval=1 +# end::documentation[] diff --git a/jetty-server/src/main/config/modules/ssl.mod b/jetty-server/src/main/config/modules/ssl.mod index 4ae5a5d3a7b..66340a195b5 100644 --- a/jetty-server/src/main/config/modules/ssl.mod +++ b/jetty-server/src/main/config/modules/ssl.mod @@ -1,8 +1,6 @@ -# DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html - [description] -Enables a TLS(SSL) Connector on the server. -This may be used for HTTPS and/or HTTP2 by enabling the associated support modules. +Enables a TLS (SSL) connector to support secure protocols. +Secure HTTP/1.1 is provided by enabling the "https" module and secure HTTP/2 is provided by enabling the "http2" module. [tags] connector @@ -17,114 +15,119 @@ etc/jetty-ssl.xml etc/jetty-ssl-context.xml [ini-template] -### TLS(SSL) Connector Configuration +# tag::documentation-connector[] +### TLS (SSL) Connector Configuration -## Connector host/address to bind to +## The host/address to bind the connector to. # jetty.ssl.host=0.0.0.0 -## Connector port to listen on +## The port the connector listens on. # jetty.ssl.port=8443 -## Connector idle timeout in milliseconds +## The connector idle timeout, in milliseconds. # jetty.ssl.idleTimeout=30000 -## Number of acceptors (-1 picks default based on number of cores) +## The number of acceptors (-1 picks a default value based on number of cores). # jetty.ssl.acceptors=-1 -## Number of selectors (-1 picks default based on number of cores) +## The number of selectors (-1 picks a default value based on number of cores). # jetty.ssl.selectors=-1 -## ServerSocketChannel backlog (0 picks platform default) +## The ServerSocketChannel accept queue backlog (0 picks the platform default). # jetty.ssl.acceptQueueSize=0 -## Thread priority delta to give to acceptor threads +## The thread priority delta to give to acceptor threads. # jetty.ssl.acceptorPriorityDelta=0 -## The requested maximum length of the queue of incoming connections. -# jetty.ssl.acceptQueueSize=0 - -## Enable/disable the SO_REUSEADDR socket option. +## Whether to enable the SO_REUSEADDR socket option. # jetty.ssl.reuseAddress=true -## Enable/disable TCP_NODELAY on accepted sockets. +## Whether to enable the TCP_NODELAY socket option on accepted sockets. # jetty.ssl.acceptedTcpNoDelay=true -## The SO_RCVBUF option to set on accepted sockets. A value of -1 indicates that it is left to its default value. +## The SO_RCVBUF socket option to set on accepted sockets. +## A value of -1 indicates that the platform default is used. # jetty.ssl.acceptedReceiveBufferSize=-1 -## The SO_SNDBUF option to set on accepted sockets. A value of -1 indicates that it is left to its default value. +## The SO_SNDBUF socket option to set on accepted sockets. +## A value of -1 indicates that the platform default is used. # jetty.ssl.acceptedSendBufferSize=-1 -## Connect Timeout in milliseconds -# jetty.ssl.connectTimeout=15000 - -## Whether SNI is required for all secure connections. Rejections are in HTTP 400 response. +## Whether client SNI data is required for all secure connections. +## When SNI is required, clients that do not send SNI data are rejected with an HTTP 400 response. # jetty.ssl.sniRequired=false -## Whether request host names are checked to match any SNI names +## Whether client SNI data is checked to match CN and SAN in server certificates. +## When SNI is checked, if the match fails the connection is rejected with an HTTP 400 response. # jetty.ssl.sniHostCheck=true -## max age in seconds for a Strict-Transport-Security response header (default -1) +## The max age, in seconds, for the Strict-Transport-Security response header. # jetty.ssl.stsMaxAgeSeconds=31536000 -## include subdomain property in any Strict-Transport-Security header (default false) +## Whether to include the subdomain property in any Strict-Transport-Security header. # jetty.ssl.stsIncludeSubdomains=true +# end::documentation-connector[] +# tag::documentation-ssl-context[] ### SslContextFactory Configuration -## Note that OBF passwords are not secure, just protected from casual observation -## See https://eclipse.org/jetty/documentation/current/configuring-security-secure-passwords.html +## Note that OBF passwords are not secure, just protected from casual observation. -## Whether SNI is required for all secure connections. Rejections are in TLS handshakes. +## Whether client SNI data is required for all secure connections. +## When SNI is required, clients that do not send SNI data are rejected with a TLS handshake error. # jetty.sslContext.sniRequired=false -## The Endpoint Identification Algorithm -## Same as javax.net.ssl.SSLParameters#setEndpointIdentificationAlgorithm(String) -#jetty.sslContext.endpointIdentificationAlgorithm= +## The Endpoint Identification Algorithm. +## Same as javax.net.ssl.SSLParameters#setEndpointIdentificationAlgorithm(String). +# jetty.sslContext.endpointIdentificationAlgorithm= -## SSL JSSE Provider +## The JSSE Provider. # jetty.sslContext.provider= -## Keystore file path (relative to $jetty.base) +## The KeyStore file path (relative to $JETTY_BASE). # jetty.sslContext.keyStorePath=etc/keystore.p12 -## Truststore file path (relative to $jetty.base) +## The TrustStore file path (relative to $JETTY_BASE). # jetty.sslContext.trustStorePath=etc/keystore.p12 -## Keystore password +## The KeyStore password. # jetty.sslContext.keyStorePassword= -## Keystore type and provider +## The Keystore type. # jetty.sslContext.keyStoreType=PKCS12 + +## The KeyStore provider. # jetty.sslContext.keyStoreProvider= -## KeyManager password +## The KeyManager password. # jetty.sslContext.keyManagerPassword= -## Truststore password +## The TrustStore password. # jetty.sslContext.trustStorePassword= -## Truststore type and provider +## The TrustStore type. # jetty.sslContext.trustStoreType=PKCS12 + +## The TrustStore provider. # jetty.sslContext.trustStoreProvider= -## whether client certificate authentication is required +## Whether client certificate authentication is required. # jetty.sslContext.needClientAuth=false -## Whether client certificate authentication is desired +## Whether client certificate authentication is desired, but not required. # jetty.sslContext.wantClientAuth=false -## Whether cipher order is significant (since java 8 only) +## Whether cipher order is significant. # jetty.sslContext.useCipherSuitesOrder=true -## To configure Includes / Excludes for Cipher Suites or Protocols see tweak-ssl.xml example at -## https://www.eclipse.org/jetty/documentation/current/configuring-ssl.html#configuring-sslcontextfactory-cipherSuites - -## Set the size of the SslSession cache +## The SSLSession cache size. # jetty.sslContext.sslSessionCacheSize=-1 -## Set the timeout (in seconds) of the SslSession cache timeout +## The SSLSession cache timeout (in seconds). # jetty.sslContext.sslSessionTimeout=-1 -## Allow SSL renegotiation +## Whether TLS renegotiation is allowed. # jetty.sslContext.renegotiationAllowed=true + +## The max number of TLS renegotiations per connection. # jetty.sslContext.renegotiationLimit=5 +# end::documentation-ssl-context[]