Added docoumentation for Conscrypt SSL.
Consolidated exisitng SSL documentation and move non-root-port80 doc. Resolves #1830.
This commit is contained in:
WalkerWatch
parent
b5a38d82ce
commit
81ec56b7c3
|
|
@ -26,13 +26,8 @@ Modules for tag '*':
|
|||
--------------------
|
||||
|
||||
Module: alpn
|
||||
: Enables the ALPN extension to TLS(SSL) by adding modified classes to
|
||||
: the JVM bootpath.
|
||||
: This modification has a tight dependency on specific recent updates of
|
||||
: Java 1.7 and Java 1.8 (Java versions prior to 1.7u40 are not supported).
|
||||
: The alpn module will use an appropriate alpn-boot jar for your
|
||||
: specific version of Java.
|
||||
Depend: alpn-impl/alpn-${java.version}, ssl
|
||||
: Enables the ALPN (Application Layer Protocol Negotiation) TLS extension.
|
||||
Depend: ssl, alpn-impl/alpn-9
|
||||
LIB: lib/jetty-alpn-client-${jetty.version}.jar
|
||||
LIB: lib/jetty-alpn-server-${jetty.version}.jar
|
||||
XML: etc/jetty-alpn.xml
|
||||
|
|
@ -54,7 +49,7 @@ Modules for tag '*':
|
|||
|
||||
Module: cdi
|
||||
: Experimental CDI/Weld integration
|
||||
Depend: jsp, annotations, plus, deploy
|
||||
Depend: deploy, annotations, plus, jsp
|
||||
LIB: lib/cdi/*.jar
|
||||
LIB: lib/cdi-core-${jetty.version}.jar
|
||||
LIB: lib/cdi-servlet-${jetty.version}.jar
|
||||
|
|
@ -87,6 +82,16 @@ Modules for tag '*':
|
|||
JVM: -XX:+UnlockCommercialFeatures
|
||||
JVM: -XX:+FlightRecorder
|
||||
|
||||
Module: hazelcast-embedded-sessions
|
||||
Depend: annotations, webapp
|
||||
LIB: lib/hazelcast/*.jar
|
||||
XML: etc/sessions/hazelcast/default.xml
|
||||
|
||||
Module: hazelcast-remote-sessions
|
||||
Depend: annotations, webapp
|
||||
LIB: lib/hazelcast/*.jar
|
||||
XML: etc/sessions/hazelcast/remote.xml
|
||||
|
||||
Module: home-base-warning
|
||||
: Generates a warning that server has been run from $JETTY_HOME
|
||||
: rather than from a $JETTY_BASE.
|
||||
|
|
@ -118,13 +123,13 @@ Modules for tag '*':
|
|||
|
||||
Module: jndi
|
||||
: Adds the Jetty JNDI implementation to the classpath.
|
||||
Depend: server
|
||||
Depend: server, mail
|
||||
LIB: lib/jetty-jndi-${jetty.version}.jar
|
||||
LIB: lib/jndi/*.jar
|
||||
|
||||
Module: jsp
|
||||
: Enables JSP for all webapplications deployed on the server.
|
||||
Depend: apache-jsp, servlet, annotations
|
||||
Depend: servlet, annotations, apache-jsp
|
||||
|
||||
Module: jstl
|
||||
: Enables JSTL for all webapplications deployed on the server
|
||||
|
|
@ -141,11 +146,15 @@ Modules for tag '*':
|
|||
Depend: server
|
||||
XML: etc/jetty-lowresources.xml
|
||||
|
||||
Module: mail
|
||||
: Adds the javax.mail implementation to the classpath.
|
||||
LIB: lib/mail/*.jar
|
||||
|
||||
Module: plus
|
||||
: Enables JNDI and resource injection for webapplications
|
||||
: and other servlet 3.x features not supported in the core
|
||||
: jetty webapps module.
|
||||
Depend: webapp, server, security, jndi
|
||||
Depend: server, security, jndi, webapp, transactions
|
||||
LIB: lib/jetty-plus-${jetty.version}.jar
|
||||
XML: etc/jetty-plus.xml
|
||||
|
||||
|
|
@ -169,7 +178,7 @@ Modules for tag '*':
|
|||
Module: quickstart
|
||||
: Enables the Jetty Quickstart module for rapid
|
||||
: deployment of preconfigured webapplications.
|
||||
Depend: server, annotations, plus
|
||||
Depend: server, plus, annotations
|
||||
LIB: lib/jetty-quickstart-${jetty.version}.jar
|
||||
|
||||
Module: rewrite
|
||||
|
|
@ -208,6 +217,7 @@ Modules for tag '*':
|
|||
LIB: lib/jetty-util-${jetty.version}.jar
|
||||
LIB: lib/jetty-io-${jetty.version}.jar
|
||||
XML: etc/jetty.xml
|
||||
Enabled: transitive provider of server for ssl
|
||||
|
||||
Module: servlet
|
||||
: Enables standard Servlet handling.
|
||||
|
|
@ -236,21 +246,37 @@ Modules for tag '*':
|
|||
Depend: server
|
||||
LIB: lib/spring/*.jar
|
||||
|
||||
Module: stop
|
||||
: This module causes jetty to stop immediately after starting. This is good for testing configuration and/or precompiling quickstart webapps
|
||||
XML: etc/jetty-stop.xml
|
||||
|
||||
Module: transactions
|
||||
: Puts javax.transaction api on the classpath
|
||||
LIB: lib/transactions/*.jar
|
||||
|
||||
Module: webapp
|
||||
: Adds support for servlet specification webapplication to the server
|
||||
: classpath. Without this, only Jetty specific handlers may be deployed.
|
||||
Depend: security, servlet
|
||||
Depend: servlet, security
|
||||
LIB: lib/jetty-webapp-${jetty.version}.jar
|
||||
XML: etc/jetty-webapp.xml
|
||||
|
||||
Module: websocket
|
||||
: Enable websockets for deployed web applications
|
||||
Depend: annotations
|
||||
Depend: client, annotations
|
||||
LIB: lib/websocket/*.jar
|
||||
|
||||
Modules for tag '3rdparty':
|
||||
---------------------------
|
||||
|
||||
Module: conscrypt
|
||||
: Installs the Conscrypt JSSE provider
|
||||
Tags: 3rdparty
|
||||
Depend: ssl
|
||||
LIB: lib/conscrypt/**.jar
|
||||
XML: etc/conscrypt.xml
|
||||
Enabled: ${jetty.base}/start.d/conscrypt.ini
|
||||
|
||||
Module: gcloud
|
||||
: Control GCloud API classpath
|
||||
Tags: 3rdparty, gcloud
|
||||
|
|
@ -259,32 +285,32 @@ Modules for tag '3rdparty':
|
|||
Module: gcloud-datastore
|
||||
: Enables GCloud Datastore API and implementation
|
||||
Tags: 3rdparty, gcloud
|
||||
Depend: jcl-slf4j, gcloud
|
||||
Depend: gcloud, jcl-slf4j, jul-impl
|
||||
|
||||
Module: hawtio
|
||||
: Deploys the Hawtio console as a webapplication.
|
||||
Tags: 3rdparty
|
||||
Depend: jmx, stats, deploy
|
||||
Depend: stats, deploy, jmx
|
||||
XML: etc/hawtio.xml
|
||||
|
||||
Module: jamon
|
||||
: Deploys the JAMon webapplication
|
||||
Tags: 3rdparty
|
||||
Depend: jmx, stats, jsp, deploy
|
||||
Depend: stats, deploy, jmx, jsp
|
||||
LIB: lib/jamon/**.jar
|
||||
XML: etc/jamon.xml
|
||||
|
||||
Module: jminix
|
||||
: Deploys the Jminix JMX Console within the server
|
||||
Tags: 3rdparty
|
||||
Depend: jmx, stats, jcl-impl, jcl-api
|
||||
Depend: stats, jmx, jcl-api, jcl-impl
|
||||
LIB: lib/jminix/**.jar
|
||||
XML: etc/jminix.xml
|
||||
|
||||
Module: jolokia
|
||||
: Deploys the Jolokia console as a web application.
|
||||
Tags: 3rdparty
|
||||
Depend: jmx, stats, deploy
|
||||
Depend: stats, deploy, jmx
|
||||
XML: etc/jolokia.xml
|
||||
|
||||
Modules for tag 'classpath':
|
||||
|
|
@ -306,6 +332,12 @@ Modules for tag 'classpath':
|
|||
Modules for tag 'connector':
|
||||
----------------------------
|
||||
|
||||
Module: connectionlimit
|
||||
: Enable a server wide connection limit
|
||||
Tags: connector
|
||||
Depend: server
|
||||
XML: etc/jetty-connectionlimit.xml
|
||||
|
||||
Module: http
|
||||
: Enables a HTTP connector on the server.
|
||||
: By default HTTP/1 is support, but HTTP2C can
|
||||
|
|
@ -325,7 +357,7 @@ Modules for tag 'connector':
|
|||
: Enables HTTP2 protocol support on the TLS(SSL) Connector,
|
||||
: using the ALPN extension to select which protocol to use.
|
||||
Tags: connector, http2, http, ssl
|
||||
Depend: alpn, ssl
|
||||
Depend: ssl, alpn
|
||||
LIB: lib/http2/*.jar
|
||||
XML: etc/jetty-http2.xml
|
||||
|
||||
|
|
@ -362,6 +394,7 @@ Modules for tag 'connector':
|
|||
Depend: server
|
||||
XML: etc/jetty-ssl.xml
|
||||
XML: etc/jetty-ssl-context.xml
|
||||
Enabled: ${jetty.base}/start.d/ssl.ini
|
||||
|
||||
Module: unixsocket
|
||||
: Enables a Unix Domain Socket Connector that can receive
|
||||
|
|
@ -484,53 +517,46 @@ Modules for tag 'logging':
|
|||
LIB: resources/
|
||||
XML: etc/console-capture.xml
|
||||
|
||||
Module: logging-jcl [logging]
|
||||
: Configure jetty logging to use Java Commons Logging (jcl)
|
||||
: SLF4J is used as the core logging mechanism.
|
||||
Tags: logging
|
||||
Depend: jcl-impl, slf4j-jcl
|
||||
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
|
||||
|
||||
Module: logging-jetty [logging]
|
||||
: Configure jetty logging mechanism.
|
||||
: Provides a ${jetty.base}/resources/jetty-logging.properties.
|
||||
Tags: logging
|
||||
Depend: console-capture, resources
|
||||
Depend: resources
|
||||
|
||||
Module: logging-jul [logging]
|
||||
: Configure jetty logging to use Java Util Logging (jul)
|
||||
: SLF4J is used as the core logging mechanism.
|
||||
Tags: logging
|
||||
Depend: jul-impl, slf4j-jul
|
||||
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
|
||||
Depend: slf4j-jul, jul-impl
|
||||
JVM: -Dorg.eclipse.jetty.util.log.class?=org.eclipse.jetty.util.log.Slf4jLog
|
||||
|
||||
Module: logging-log4j [logging]
|
||||
: Configure jetty logging to use Log4j Logging
|
||||
: SLF4J is used as the core logging mechanism.
|
||||
Tags: logging
|
||||
Depend: log4j-impl, slf4j-log4j
|
||||
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
|
||||
Depend: slf4j-log4j, log4j-impl
|
||||
JVM: -Dorg.eclipse.jetty.util.log.class?=org.eclipse.jetty.util.log.Slf4jLog
|
||||
|
||||
Module: logging-log4j2 [logging]
|
||||
: Configure jetty logging to use log4j version 2
|
||||
: SLF4J is used as the core logging mechanism.
|
||||
Tags: logging
|
||||
Depend: slf4j-log4j2, log4j2-impl
|
||||
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
|
||||
JVM: -Dorg.eclipse.jetty.util.log.class?=org.eclipse.jetty.util.log.Slf4jLog
|
||||
|
||||
Module: logging-logback [logging]
|
||||
: Configure jetty logging to use Logback Logging.
|
||||
: SLF4J is used as the core logging mechanism.
|
||||
Tags: logging
|
||||
Depend: logback-impl, slf4j-logback
|
||||
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
|
||||
Depend: slf4j-logback, logback-impl
|
||||
JVM: -Dorg.eclipse.jetty.util.log.class?=org.eclipse.jetty.util.log.Slf4jLog
|
||||
|
||||
Module: logging-slf4j [logging]
|
||||
: Configure jetty logging to use slf4j.
|
||||
: Any slf4j-impl implementation is used
|
||||
Tags: logging
|
||||
Depend: slf4j-api, slf4j-impl
|
||||
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
|
||||
JVM: -Dorg.eclipse.jetty.util.log.class?=org.eclipse.jetty.util.log.Slf4jLog
|
||||
|
||||
Modules for tag 'requestlog':
|
||||
-----------------------------
|
||||
|
|
@ -538,7 +564,7 @@ Modules for tag 'requestlog':
|
|||
Module: logback-access [requestlog]
|
||||
: Enables logback request log.
|
||||
Tags: requestlog, logging, logback
|
||||
Depend: server, logback-core, resources
|
||||
Depend: server, logback-impl, resources
|
||||
LIB: lib/logback/logback-access-${logback.version}.jar
|
||||
XML: etc/jetty-logback-access.xml
|
||||
|
||||
|
|
@ -581,23 +607,41 @@ Modules for tag 'session':
|
|||
Module: session-store-gcloud [session-store]
|
||||
: Enables GCloudDatastore session management.
|
||||
Tags: session, gcloud
|
||||
Depend: webapp, sessions, gcloud-datastore, annotations
|
||||
Depend: gcloud-datastore, annotations, webapp, sessions
|
||||
LIB: lib/jetty-gcloud-session-manager-${jetty.version}.jar
|
||||
XML: etc/sessions/gcloud/session-store.xml
|
||||
|
||||
Module: session-store-hazelcast-embedded [session-store]
|
||||
: Enables session data store in an embedded Hazelcast Map
|
||||
Tags: session
|
||||
Depend: sessions
|
||||
LIB: lib/jetty-hazelcast-${jetty.version}.jar
|
||||
LIB: lib/hazelcast/*.jar
|
||||
XML: etc/sessions/hazelcast/default.xml
|
||||
|
||||
Module: session-store-hazelcast-remote [session-store]
|
||||
: Enables session data store in a remote Hazelcast Map
|
||||
Tags: session
|
||||
Depend: sessions
|
||||
LIB: lib/jetty-hazelcast-${jetty.version}.jar
|
||||
LIB: lib/hazelcast/*.jar
|
||||
XML: etc/sessions/hazelcast/remote.xml
|
||||
|
||||
Module: session-store-infinispan-embedded [session-store]
|
||||
: Enables session data store in a local Infinispan cache
|
||||
Tags: session
|
||||
Depend: sessions, sessions/infinispan/default
|
||||
Depend: sessions
|
||||
LIB: lib/jetty-infinispan-${jetty.version}.jar
|
||||
LIB: lib/infinispan/*.jar
|
||||
XML: etc/sessions/infinispan/default.xml
|
||||
|
||||
Module: session-store-infinispan-remote [session-store]
|
||||
: Enables session data store in a remote Infinispan cache
|
||||
Tags: session
|
||||
Depend: sessions/infinispan/remote, sessions
|
||||
Depend: sessions
|
||||
LIB: lib/jetty-infinispan-${jetty.version}.jar
|
||||
LIB: lib/infinispan/*.jar
|
||||
XML: etc/sessions/infinispan/remote.xml
|
||||
|
||||
Module: session-store-jdbc [session-store]
|
||||
: Enables JDBC peristent/distributed session storage.
|
||||
|
|
@ -608,10 +652,9 @@ Modules for tag 'session':
|
|||
Module: session-store-mongo [session-store]
|
||||
: Enables NoSql session management with a MongoDB driver.
|
||||
Tags: session
|
||||
Depend: sessions
|
||||
Depend: sessions, sessions/mongo/${connection-type}
|
||||
LIB: lib/jetty-nosql-${jetty.version}.jar
|
||||
LIB: lib/nosql/*.jar
|
||||
XML: etc/sessions/mongo/session-store.xml
|
||||
|
||||
Module: sessions
|
||||
: The session management. By enabling this module, it allows
|
||||
|
|
|
|||
|
|
@ -29,8 +29,8 @@ The default distribution has a co-mingled `${jetty.home}` and `${jetty.base}` wh
|
|||
It is highly encouraged that you learn about the differences in link:#startup-base-and-home[Jetty Base vs Jetty Home] and take full advantage of this setup.
|
||||
____
|
||||
|
||||
Enabling a module is a simple process: simply add the `--add-to-start` syntax on the command line.
|
||||
Doing this will enable the module and any dependent modules.
|
||||
Enabling a module is a simple process: simply add the `--add-to-start=<module-name1>,<module-name2>,...etc.` syntax on the command line.
|
||||
Doing this will enable the specified module and any dependent modules.
|
||||
|
||||
An example of this with a new, empty, base directory:
|
||||
|
||||
|
|
|
|||
|
|
@ -21,4 +21,4 @@ This chapter discusses various options for configuring Jetty connectors.
|
|||
|
||||
include::configuring-connectors.adoc[]
|
||||
include::configuring-ssl.adoc[]
|
||||
include::setting-port80-access-for-non-root-user.adoc[]
|
||||
include::configuring-ssl-distribution.adoc[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,128 @@
|
|||
// ========================================================================
|
||||
// Copyright (c) 1995-2017 Mort Bay Consulting Pty. Ltd.
|
||||
// ========================================================================
|
||||
// All rights reserved. This program and the accompanying materials
|
||||
// are made available under the terms of the Eclipse Public License v1.0
|
||||
// and Apache License v2.0 which accompanies this distribution.
|
||||
//
|
||||
// The Eclipse Public License is available at
|
||||
// http://www.eclipse.org/legal/epl-v10.html
|
||||
//
|
||||
// The Apache License v2.0 is available at
|
||||
// http://www.opensource.org/licenses/apache2.0.php
|
||||
//
|
||||
// You may elect to redistribute this code under either of these licenses.
|
||||
// ========================================================================
|
||||
|
||||
[[jetty-ssl-distribution]]
|
||||
=== SSL in the Jetty Distribution
|
||||
|
||||
==== Configuration
|
||||
|
||||
When making use of the Jetty Distribution, enabling SSL support is as easy as activating the appropriate module.
|
||||
Jetty provides support for both the native https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html[JSSE] and https://github.com/google/conscrypt/[Conscrypt] SSL implementations.
|
||||
|
||||
For native support, simply activate the `ssl` module:
|
||||
|
||||
[source, plain, subs="{sub-order}"]
|
||||
----
|
||||
$ cd /path/to/mybase
|
||||
$ java -jar ${JETTY_HOME}/start.jar --create-startd
|
||||
...
|
||||
$ java -jar ${JETTY_HOME}/start.jar --add-to-startd=ssl
|
||||
INFO : server initialised (transitively) in ${jetty.base}/start.d/server.ini
|
||||
INFO : ssl initialised in ${jetty.base}/start.d/ssl.ini
|
||||
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`.
|
||||
|
||||
Enabling Conscrypt SSL is just as easy as native SSL - enable both the `conscrypt` and `ssl` modules:
|
||||
|
||||
[source, plain, subs="{sub-order}"]
|
||||
----
|
||||
$ cd ${JETTY_HOME}
|
||||
$ java -jar ${JETTY_HOME}/start.jar --create-startd
|
||||
...
|
||||
$ java -jar ../start.jar --add-to-start=ssl,conscrypt
|
||||
|
||||
ALERT: There are enabled module(s) with licenses.
|
||||
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: http://central.maven.org/maven2/org/conscrypt/conscrypt-openjdk-uber/1.0.0.RC9/conscrypt-openjdk-uber-1.0.0.RC9.jar to ${jetty.base}/lib/conscrypt/conscrypt-uber-1.0.0.RC9.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.
|
||||
|
||||
[[two-way-authentication]]
|
||||
==== Two Way Authentication
|
||||
|
||||
To enable two-way authentication in the Jetty Distribution, you need to enable the both the `ssl` and `https` modules.
|
||||
|
||||
[source, plain, subs="{sub-order}"]
|
||||
----
|
||||
$ cd /path/to/mybase
|
||||
$ java -jar /path/to/jetty-dist/start.jar --add-to-startd=ssl,https
|
||||
----
|
||||
|
||||
[source%nowrap,ini,linenums]
|
||||
.$JETTY_BASE/start.d/ssl.ini
|
||||
----
|
||||
# Module: ssl
|
||||
--module=ssl
|
||||
|
||||
jetty.ssl.host=0.0.0.0
|
||||
jetty.ssl.port=8583
|
||||
jetty.sslContext.keyStorePath=etc/keystore
|
||||
jetty.sslContext.trustStorePath=etc/keystore
|
||||
jetty.sslContext.keyStorePassword=OBF:
|
||||
jetty.sslContext.keyManagerPassword=OBF:
|
||||
jetty.sslContext.trustStorePassword=OBF:
|
||||
jetty.sslContext.trustStoreType=JKS
|
||||
# enable two way authentication
|
||||
jetty.sslContext.needClientAuth=true
|
||||
----
|
||||
|
||||
[source%nowrap,ini,linenums]
|
||||
.$JETTY_BASE/start.d/https.ini
|
||||
----
|
||||
# Module: https
|
||||
--module=https
|
||||
----
|
||||
|
|
@ -724,90 +724,18 @@ To support this, the `SslContextFactory` is used.
|
|||
The `SslContextFactory` will look for multiple X509 certificates within the keystore, each of which may have multiple DNS names (including wildcards) associated with the http://en.wikipedia.org/wiki/SubjectAltName[Subject Alternate Name] extension.
|
||||
When using the `SslContextFactory`, the correct certificate is automatically selected if the SNI extension is present in the handshake.
|
||||
|
||||
|
||||
==== Configuring SSL in Jetty Distribution
|
||||
|
||||
For those of you using the Jetty Distribution, enabling SSL support is as easy as activating the `ssl` module.
|
||||
|
||||
An example of this setup:
|
||||
|
||||
[source, plain, subs="{sub-order}"]
|
||||
----
|
||||
$ cd /path/to/mybase
|
||||
$ java -jar /path/to/jetty-dist/start.jar --add-to-startd=ssl
|
||||
INFO : server initialised (transitively) in ${jetty.base}/start.d/server.ini
|
||||
INFO : ssl initialised in ${jetty.base}/start.d/ssl.ini
|
||||
INFO : Base directory was modified
|
||||
$ tree
|
||||
.
|
||||
├── etc
|
||||
│ └── keystore
|
||||
└── start.d
|
||||
├── server.ini
|
||||
└── ssl.ini
|
||||
----
|
||||
|
||||
When you open `start.d/ssl.ini`, you will see several commented properties ready for use when configuring `SslContextFactory` basics.
|
||||
|
||||
To highlight some of the more commonly used properties:
|
||||
|
||||
jetty.ssl.host::
|
||||
Configures which interfaces the SSL/TLS Connector should listen on.
|
||||
jetty.ssl.port::
|
||||
Configures which port the SSL/TLS Connector should listen on.
|
||||
jetty.httpConfig.securePort::
|
||||
If a webapp needs to redirect to a secure version of the same resource, then this is the port reported back on the response `location` line (having this be separate is useful if you have something sitting in front of Jetty, such as a Load Balancer or proxy).
|
||||
jetty.sslContext.keyStorePath::
|
||||
Sets the location of the `keystore` that you configured with your certificates.
|
||||
jetty.sslContext.keyStorePassword::
|
||||
Sets the Password for the `keystore`.
|
||||
|
||||
[[two-way-authentication]]
|
||||
==== Two Way Authentication
|
||||
|
||||
To enable two-way authentication in the Jetty Distribution, you need to enable the both the `ssl` and `https` modules.
|
||||
|
||||
[source, plain, subs="{sub-order}"]
|
||||
----
|
||||
$ cd /path/to/mybase
|
||||
$ java -jar /path/to/jetty-dist/start.jar --add-to-startd=ssl,https
|
||||
----
|
||||
|
||||
[source%nowrap,ini,linenums]
|
||||
.$JETTY_BASE/start.d/ssl.ini
|
||||
----
|
||||
# Module: ssl
|
||||
--module=ssl
|
||||
|
||||
jetty.ssl.host=0.0.0.0
|
||||
jetty.ssl.port=8583
|
||||
jetty.sslContext.keyStorePath=etc/keystore
|
||||
jetty.sslContext.trustStorePath=etc/keystore
|
||||
jetty.sslContext.keyStorePassword=OBF:
|
||||
jetty.sslContext.keyManagerPassword=OBF:
|
||||
jetty.sslContext.trustStorePassword=OBF:
|
||||
jetty.sslContext.trustStoreType=JKS
|
||||
# enable two way authentication
|
||||
jetty.sslContext.needClientAuth=true
|
||||
----
|
||||
|
||||
[source%nowrap,ini,linenums]
|
||||
.$JETTY_BASE/start.d/https.ini
|
||||
----
|
||||
# Module: https
|
||||
--module=https
|
||||
----
|
||||
|
||||
[[configuring-sslcontextfactory-cipherSuites]]
|
||||
==== Disabling/Enabling Specific Cipher Suites
|
||||
|
||||
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...)].
|
||||
|
||||
____
|
||||
[NOTE]
|
||||
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 ssllabs.com might report slightly different names which will be ignored.
|
||||
Tools like https://www.ssllabs.com/[ssllabs.com] might report slightly different names which will be ignored.
|
||||
____
|
||||
|
||||
____
|
||||
|
|
|
|||
|
|
@ -1,39 +0,0 @@
|
|||
// ========================================================================
|
||||
// Copyright (c) 1995-2017 Mort Bay Consulting Pty. Ltd.
|
||||
// ========================================================================
|
||||
// All rights reserved. This program and the accompanying materials
|
||||
// are made available under the terms of the Eclipse Public License v1.0
|
||||
// and Apache License v2.0 which accompanies this distribution.
|
||||
//
|
||||
// The Eclipse Public License is available at
|
||||
// http://www.eclipse.org/legal/epl-v10.html
|
||||
//
|
||||
// The Apache License v2.0 is available at
|
||||
// http://www.opensource.org/licenses/apache2.0.php
|
||||
//
|
||||
// You may elect to redistribute this code under either of these licenses.
|
||||
// ========================================================================
|
||||
|
||||
[[configuring-security-authorization]]
|
||||
=== Authorization
|
||||
|
||||
There are two aspects to securing a web application(or context) within
|
||||
Jetty:
|
||||
|
||||
Authentication::
|
||||
The web application can be configured with a mechanism to determine
|
||||
the identity of the user. See
|
||||
link:#configuring-security-authentication[Configurating Security -
|
||||
Authentication].
|
||||
Authorization::
|
||||
Once the identify of the user is known (or not known), the web
|
||||
application can be configured with security constraints that declare
|
||||
what resources that user may access. This is covered in this section.
|
||||
|
||||
==== Blah blah blah
|
||||
|
||||
blah blah blah
|
||||
|
||||
==== Blah blah blah
|
||||
|
||||
blah blah blah
|
||||
|
|
@ -17,10 +17,10 @@
|
|||
[[configuring-security]]
|
||||
== Configuring Security
|
||||
|
||||
include::jetty-home-and-jetty-base.adoc[]
|
||||
include::authentication.adoc[]
|
||||
include::configuring-form-size.adoc[]
|
||||
include::serving-aliased-files.adoc[]
|
||||
include::secure-passwords.adoc[]
|
||||
include::setting-port80-access-for-non-root-user.adoc[]
|
||||
include::jaas-support.adoc[]
|
||||
include::spnego-support.adoc[]
|
||||
|
|
|
|||
|
|
@ -1,344 +0,0 @@
|
|||
// ========================================================================
|
||||
// Copyright (c) 1995-2017 Mort Bay Consulting Pty. Ltd.
|
||||
// ========================================================================
|
||||
// All rights reserved. This program and the accompanying materials
|
||||
// are made available under the terms of the Eclipse Public License v1.0
|
||||
// and Apache License v2.0 which accompanies this distribution.
|
||||
//
|
||||
// The Eclipse Public License is available at
|
||||
// http://www.eclipse.org/legal/epl-v10.html
|
||||
//
|
||||
// The Apache License v2.0 is available at
|
||||
// http://www.opensource.org/licenses/apache2.0.php
|
||||
//
|
||||
// You may elect to redistribute this code under either of these licenses.
|
||||
// ========================================================================
|
||||
|
||||
[[jetty-home-and-jetty-base]]
|
||||
=== Configuring Security with Jetty Home and Base Directories
|
||||
|
||||
Jetty implementations are structured around the idea of `${jetty.base}` and `${jetty.home}` directories.
|
||||
|
||||
* `${jetty.home}` is the directory location for the Jetty distribution (the binaries) should not be modified.
|
||||
* `${jetty.base}` is the directory location for your customizations to the distribution.
|
||||
|
||||
This separation:
|
||||
|
||||
* Allows you to manage multiple Jetty installations.
|
||||
* Makes it simple to retain your current configuration when you upgrade your Jetty distribution.
|
||||
|
||||
For more information, see xref:startup-base-and-home[].
|
||||
|
||||
Further, Jetty 9.1 parameterized all of the standard configuration XMLs.
|
||||
For SSL, parameters are now properties in the `start.ini` or `start.d\ssl.ini`, reducing to eliminating the need to edit XML files.
|
||||
|
||||
Instead of explicitly listing all the libraries, properties, and XML files for a feature, Jetty 9.1 introduced a new module system.
|
||||
A module is defined in a `modules/*.mod` file, including the libraries, dependencies, XML, and template INI files for a Jetty feature.
|
||||
Thus you can use a single `--module=name` command line option as the equivalent of specifying many `--lib=location, feature.xml, name=value` arguments for a feature and all its dependencies.
|
||||
Modules use their dependencies to control the ordering of libraries and XML files.
|
||||
For more information, see xref:startup-modules[].
|
||||
|
||||
[[configuring-security-jetty91]]
|
||||
==== Configuring SSL in with modules
|
||||
|
||||
This page describes how to configure SSL in Jetty with modules.
|
||||
It provides an example of using the `${jetty.home}` and `${jetty.base}` to maximum effect.
|
||||
It also includes a detailed explanation of how modules work.
|
||||
|
||||
This example assumes you have the jetty-distribution unpacked in `/home/user/jetty-distribution-{VERSION}`.
|
||||
It also assumes you are using `start.ini` to configure your server features.
|
||||
|
||||
1. Create a base directory anywhere.
|
||||
+
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[/home/user]$ mkdir my-base
|
||||
[/home/user]$ cd my-base
|
||||
....
|
||||
2. Add the modules for SSL, HTTP, and webapp deployment.
|
||||
Adding modules in this way will append the associated module properties to the `${jetty.base}/start.ini` file.
|
||||
+
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar --add-to-start=http,https,deploy
|
||||
|
||||
ssl initialised in ${jetty.base}/start.ini (appended)
|
||||
ssl enabled in ${jetty.base}/start.ini
|
||||
DOWNLOAD: https://github.com/eclipse/jetty.project/raw/master/jetty-server/src/main/config/etc/keystore to etc/keystore
|
||||
server initialised in ${jetty.base}/start.ini (appended)
|
||||
server enabled in ${jetty.base}/start.ini
|
||||
http initialised in ${jetty.base}/start.ini (appended)
|
||||
http enabled in ${jetty.base}/start.ini
|
||||
server enabled in ${jetty.base}/start.ini
|
||||
deploy initialised in ${jetty.base}/start.ini (appended)
|
||||
deploy enabled in ${jetty.base}/start.ini
|
||||
MKDIR: ${jetty.base}/webapps
|
||||
server enabled in ${jetty.base}/start.ini
|
||||
....
|
||||
3. Look at your directory.
|
||||
+
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[my-base]$ ls -la
|
||||
total 20
|
||||
drwxrwxr-x 4 user group 4096 Oct 8 06:55 ./
|
||||
drwxr-xr-x 103 user group 4096 Oct 8 06:53 ../
|
||||
drwxrwxr-x 2 user group 4096 Oct 8 06:55 etc/
|
||||
-rw-rw-r-- 1 user group 815 Oct 8 06:55 start.ini
|
||||
drwxrwxr-x 2 user group 4096 Oct 8 06:55 webapps/
|
||||
....
|
||||
4. Copy your WAR files into webapps.
|
||||
+
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[my-base]$ ls -la
|
||||
[my-base]$ cp ~/code/project/target/gadget.war webapps/
|
||||
....
|
||||
5. Copy your keystore into place.
|
||||
+
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[my-base]$ cp ~/code/project/keystore etc/keystore
|
||||
....
|
||||
6. Edit the `start.ini` to configure your SSL settings.
|
||||
+
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[my-base]$ cat start.ini
|
||||
....
|
||||
7. Initialize module ssl.
|
||||
+
|
||||
....
|
||||
--module=ssl
|
||||
....
|
||||
8. Define the port to use for secure redirection.
|
||||
+
|
||||
....
|
||||
jetty.secure.port=8443
|
||||
....
|
||||
9. Set up a demonstration keystore and truststore.
|
||||
+
|
||||
....
|
||||
jetty.keystore=etc/keystore
|
||||
jetty.truststore=etc/keystore
|
||||
....
|
||||
10. Set the demonstration passwords.
|
||||
+
|
||||
....
|
||||
jetty.keystore.password=OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
|
||||
jetty.keymanager.password=OBF:1u2u1wml1z7s1z7a1wnl1u2g
|
||||
jetty.truststore.password=OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
|
||||
....
|
||||
11. Initialize the module server.
|
||||
+
|
||||
....
|
||||
--module=server
|
||||
threads.min=10
|
||||
threads.max=200
|
||||
threads.timeout=60000
|
||||
#jetty.host=myhost.com
|
||||
jetty.dump.start=false
|
||||
jetty.dump.stop=false
|
||||
....
|
||||
12. Initialize module http.
|
||||
+
|
||||
....
|
||||
--module=http
|
||||
jetty.http.port=8080
|
||||
http.timeout=30000
|
||||
....
|
||||
13. Initialize module deploy.
|
||||
+
|
||||
....
|
||||
--module=deploy
|
||||
....
|
||||
|
||||
Look at the configuration you have at this point.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar --list-config
|
||||
|
||||
Java Environment:
|
||||
-----------------
|
||||
java.home=/usr/lib/jvm/jdk-7u21-x64/jre
|
||||
java.vm.vendor=Oracle Corporation
|
||||
java.vm.version=23.21-b01
|
||||
java.vm.name=Java HotSpot(TM) 64-Bit Server VM
|
||||
java.vm.info=mixed mode
|
||||
java.runtime.name=Java(TM) SE Runtime Environment
|
||||
java.runtime.version=1.7.0_21-b11
|
||||
java.io.tmpdir=/tmp
|
||||
|
||||
Jetty Environment:
|
||||
-----------------
|
||||
jetty.home=/home/user/jetty-distribution-{VERSION}
|
||||
jetty.base=/home/user/my-base
|
||||
jetty.version={VERSION}
|
||||
|
||||
JVM Arguments:
|
||||
--------------
|
||||
(no jvm args specified)
|
||||
|
||||
System Properties:
|
||||
------------------
|
||||
jetty.base = /home/user/my-base
|
||||
jetty.home = /home/user/jetty-distribution-{VERSION}
|
||||
|
||||
Properties:
|
||||
-----------
|
||||
http.timeout = 30000
|
||||
jetty.dump.start = false
|
||||
jetty.dump.stop = false
|
||||
jetty.keymanager.password = OBF:1u2u1wml1z7s1z7a1wnl1u2g
|
||||
jetty.keystore = etc/keystore
|
||||
jetty.keystore.password = OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
|
||||
jetty.http.port = 8080
|
||||
jetty.secure.port = 8443
|
||||
jetty.truststore = etc/keystore
|
||||
jetty.truststore.password = OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
|
||||
threads.max = 200
|
||||
threads.min = 10
|
||||
threads.timeout = 60000
|
||||
|
||||
Jetty Server Classpath:
|
||||
-----------------------
|
||||
Version Information on 11 entries in the classpath.
|
||||
: order presented here is how they would appear on the classpath.
|
||||
changes to the --module=name command line options will be reflected here.
|
||||
0: 3.1.0 | ${jetty.home}/lib/servlet-api-3.1.jar
|
||||
1: 3.1.RC0 | ${jetty.home}/lib/jetty-schemas-3.1.jar
|
||||
2: {VERSION} | ${jetty.home}/lib/jetty-http-{VERSION}.jar
|
||||
3: {VERSION} | ${jetty.home}/lib/jetty-continuation-{VERSION}.jar
|
||||
4: {VERSION} | ${jetty.home}/lib/jetty-server-{VERSION}.jar
|
||||
5: {VERSION} | ${jetty.home}/lib/jetty-xml-{VERSION}.jar
|
||||
6: {VERSION} | ${jetty.home}/lib/jetty-util-{VERSION}.jar
|
||||
7: {VERSION} | ${jetty.home}/lib/jetty-io-{VERSION}.jar
|
||||
8: {VERSION} | ${jetty.home}/lib/jetty-servlet-{VERSION}.jar
|
||||
9: {VERSION} | ${jetty.home}/lib/jetty-webapp-{VERSION}.jar
|
||||
10: {VERSION} | ${jetty.home}/lib/jetty-deploy-{VERSION}.jar
|
||||
|
||||
Jetty Active XMLs:
|
||||
------------------
|
||||
${jetty.home}/etc/jetty.xml
|
||||
${jetty.home}/etc/jetty-http.xml
|
||||
${jetty.home}/etc/jetty-ssl.xml
|
||||
${jetty.home}/etc/jetty-deploy.xml
|
||||
....
|
||||
|
||||
Now start Jetty.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar
|
||||
2013-10-08 07:06:55.837:INFO:oejs.Server:main: jetty-{VERSION}
|
||||
2013-10-08 07:06:55.853:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
|
||||
2013-10-08 07:06:55.872:INFO:oejs.ServerConnector:main: Started ServerConnector@72974691{HTTP/1.1}{0.0.0.0:8080}
|
||||
....
|
||||
|
||||
[[reviewing-ssl-config]]
|
||||
==== Reviewing the Configuration
|
||||
|
||||
The following sections review this configuration.
|
||||
|
||||
[[jetty-base-jetty-home]]
|
||||
===== $\{jetty.base} and $\{jetty.home}
|
||||
|
||||
First notice the separation of `${jetty.base}` and `${jetty.home}`.
|
||||
|
||||
* `${jetty.home}` is where your distribution lies, unchanged, unedited.
|
||||
* `${jetty.base}` is where your customizations are.
|
||||
|
||||
[[modules]]
|
||||
===== Modules
|
||||
|
||||
Notice that you have `--module=<name>` here and there; you have wrapped up the goal of a module (libs, configuration XMLs, and properties) into a single unit, with dependencies on other modules.
|
||||
|
||||
You can see the list of modules by appending `--list-modules` to the command line.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[my-base] $ java -jar ../jetty-distribution-{VERSION}/start.jar --list-modules
|
||||
....
|
||||
|
||||
These are the modules by name, the libraries they bring in, the XML configurations they use, the other modules they depend on (even optional ones), and if the module is in use, where it was enabled.
|
||||
|
||||
While you can manage the list of active modules yourself, it is much easier to edit the `${jetty.base}/start.ini`.
|
||||
|
||||
If you want to start using a new module:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[my-base] $ java -jar ../jetty-distribution-{VERSION}/start.jar --add-to-start=https
|
||||
....
|
||||
|
||||
This adds the `--module=` lines and associated properties (the parameterized values mentioned above), to your `start.ini`.
|
||||
|
||||
____
|
||||
[IMPORTANT]
|
||||
Do not edit the modules and XML files in the `${jetty.home}` directory; there is no need to be moving or copying them unless you want to make your own modules or override the behavior of an existing module.
|
||||
____
|
||||
|
||||
Notice that your `${jetty.base}/start.ini` has no references to the XML files.
|
||||
That's because the module system and its graph of dependencies now dictate all of the XML files, and their load order.
|
||||
Much more information on modules can be found in the section on link:#startup-modules[Managing Startup Modules.]
|
||||
|
||||
[[parameterizing]]
|
||||
===== Parameters
|
||||
|
||||
Next is parameterizing all of the standard configuration XMLs.
|
||||
In this example all of the SSL parameters are now just properties in the `start.ini`, reducing or eliminating the need to edit XML files.
|
||||
|
||||
[[override-jetty.home]]
|
||||
===== Overriding $\{jetty.home} in $\{jetty.base}
|
||||
|
||||
Finally, you can override anything you see in `${jetty.home}` in `${jetty.base}`, even XML configurations and libraries.
|
||||
|
||||
For more information on the `start.jar` in 9.1, see xref:start-jar[].
|
||||
|
||||
[[summary-configuring-SSL-Jetty]]
|
||||
==== Summary of Configuring SSL
|
||||
|
||||
1. Download and unpack Jetty into `/home/user/jetty-distribution-{VERSION}`.
|
||||
2. Go to your base directory and just use the distribution, no editing.
|
||||
+
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar
|
||||
....
|
||||
* The Jetty distribution provides, out of the box, the XML configuration files, in this case `jetty-http.xml` and `jetty-ssl.xml`.
|
||||
These can be found in the `${jetty.home}/etc/` directory.
|
||||
* We have parameterized all of the configurable values in those XMLs.
|
||||
You can now set the values using simple properties, either on the command line, or within the `${jetty.base}/start.ini`.
|
||||
* When you activate the module for HTTP or HTTPs, Jetty automatically adds the appropriate libraries and XML to start Jetty.
|
||||
Unless you have a highly custom setup (such as listening on two different ports, using SSL on each, each with its own keystore and configuration), there is no need to muck around in XML files.
|
||||
3. Use modules to configure HTTPS:
|
||||
* http -> server
|
||||
* https -> ssl -> server
|
||||
+
|
||||
You can find the details about the modules in `${jetty.home}/modules/`.
|
||||
For SSL they include `modules/http.mod`, `modules/https.mod`, `modules/ssl.mod`, and `modules/server.mod`.
|
||||
+
|
||||
Ideally, this level of detail is not important to you.
|
||||
What is important is that you want to use HTTPS and want to configure it.
|
||||
You accomplish that by adding the `--module=https` to your `start.ini`.
|
||||
By default, the module system keeps things sane, and transitively includes all dependent modules as well.
|
||||
|
||||
You can see what the configuration looks like, after all of the modules are resolved, without starting Jetty via:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[my-base] $ java -jar ../jetty-distribution-{VERSION}/start.jar --list-config
|
||||
....
|
||||
|
||||
Just because the JARs exist on disk does not mean that they are in use.
|
||||
The configuration controls what is used.
|
||||
|
||||
Use the `--list-config` to see the configuration.
|
||||
Notice that only a subset of the JARs from the distribution are in use.
|
||||
The modules you have enabled determine that subset.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[my-base]$ java -jar ~/jetty-distribution-{VERSION}/start.jar --list-config
|
||||
....
|
||||
Loading…
Reference in New Issue