Eclipse
/
jetty.project
mirror of https://github.com/jetty/jetty.project.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fixes #2011 - Improve ALPN documentation. 

Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet 2018-03-01 11:34:26 +01:00
parent c684295f7e
commit fde21a45f7
2 changed files with 47 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
jetty-documentation/src/main/asciidoc/administration/alpn/alpn.adoc
View File

@ -23,48 +23,40 @@ Application Layer Protocol Negotiation (ALPN) is a TLS extension that allows cli
Any protocol can be negotiated by ALPN within a TLS connection; the protocols that are most commonly negotiated are HTTP/2 and HTTP/1.1.
Browsers only support HTTP/2 over TLS by negotiating the HTTP/2 protocol via ALPN.
You need to configure the server to support TLS and ALPN if you want browsers to use
the HTTP/2 protocol, otherwise they will default to HTTP/1.1.
In the Jetty project, ALPN is _used_ in two artifacts: `jetty-alpn-client` and `jetty-alpn-server`, respectively for the client and for the server.
When using Jetty as a standalone server via the Jetty distribution, the `jetty-alpn-server` artifact is automatically included in the server classpath by the Jetty module system.
When using Jetty embedded, the `jetty-alpn-client` and `jetty-alpn-server` artifacts must be included in the classpath, respectively for client and server use cases.
ALPN may be _provided_ to these two artifacts with the following three options:
The ALPN implementation is _provided_ to these two artifacts with the following three options:
* For JDK 9 or later, a provider based on the ALPN APIs present in the JDK
* For JDK 8 or later, a provider based on the link:#conscrypt[Conscrypt security provider]
* For JDK 8 only, a provider based on modified OpenJDK classes
** Only works with JDK 8, pure Java implementation
** Requires the `-Xbootclasspath/p` option on command line
* For JDK 8 or later, a provider based on the link:#conscrypt[Conscrypt security provider]
** Works with JDK 8 or later and provides improved performance
** Binds to the OpenSSL native library shipped by Conscrypt and is therefore only available on the platforms supported by Conscrypt
* For JDK 9 or later, a provider based on the ALPN APIs present in the JDK
** Works with JDK 9 or later, pure Java implementation
** Lower performance than Conscrypt
The latter, although hosted under the umbrella of the Jetty project, is independent of Jetty (the Servlet Container); you can use it in any other Java network server.
The first, although hosted under the umbrella of the Jetty project, is independent of Jetty (the Servlet Container); you can use it in any other Java network server.
Each provider above provides a _service_ implementation; Jetty uses the `ServiceLoader` mechanism to load these service implementations.
The absence of implementations is an error at startup (see also the link:#alpn-troubleshooting[troubleshooting section]).
Each provider above provides an ALPN _service_ implementation; Jetty uses the `ServiceLoader` mechanism to load these service implementations.
At least one valid provider must be present in the server classpath.
For example, using JDK 8 with the JDK 9 ALPN provider is an _invalid_ combination.
The absence of valid implementations is an error at startup (see also the link:#alpn-troubleshooting[troubleshooting section]).
There may be multiple ALPN service providers in the server classpath.
When a new connection is created, an `SSLEngine` instance is associated to it; each `SSLEngine` is passed all service implementations, until one accepts it.
It is therefore possible to have multiple providers active at the same time, for example the JDK 9 provider and the Conscrypt provider, and at runtime the correct one will be chosen by the Jetty runtime.
[[alpn-jdk9]]
==== ALPN and JDK 9
When using JDK 9 or later and Jetty as a standalone server via the Jetty distribution, ALPN support is automatically enabled when the `http2` module is enabled.
This enables transitively the `alpn-9` module which puts the `jetty-alpn-java-server` artifact in the server classpath, providing the ALPN JDK 9 service implementation.
When using JDK 9 or later and Jetty embedded, the ALPN service implementation is provided by the `jetty-alpn-java-client` and `jetty-alpn-java-server` artifacts, respectively for client usage and server usage, and must be added to the classpath.
[[alpn-conscrypt]]
==== ALPN and Conscrypt
When using JDK 8 or later, you can use the https://conscrypt.org/[Conscrypt] security provider to provide the ALPN service implementation.
Conscrypt binds natively to BoringSSL (a fork of OpenSSL by Google), so ALPN will be supported via the support provided by BoringSSL (bundled together with Conscrypt).
When using Jetty as a standalone server via the Jetty distribution, ALPN is enabled by enabling the `conscrypt` module.
When using Jetty embedded, ALPN is enabled by the `jetty-alpn-conscrypt-client` and `jetty-alpn-conscrypt-server` artifacts, respectively for client usage and server usage.
In addition, you also need the Conscrypt artifacts, typically the `org.conscrypt:conscrypt-openjdk-uber` artifact.
All these artifacts must be added to the classpath.
[[alpn-openjdk8]]
==== ALPN and OpenJDK 8
@ -94,6 +86,27 @@ Where `path_to_alpn_boot_jar` is the path on the file system for the `alpn-boot`
Be certain to get the link:#alpn-versions[ALPN boot artifact version that matches the version of your JRE].
[[alpn-conscrypt]]
==== ALPN and Conscrypt
When using JDK 8 or later, you can use the https://conscrypt.org/[Conscrypt] security provider to provide the ALPN service implementation.
Conscrypt binds natively to BoringSSL (a fork of OpenSSL by Google), so ALPN will be supported via the support provided by BoringSSL (bundled together with Conscrypt).
When using Jetty as a standalone server via the Jetty distribution, ALPN is enabled by enabling the `conscrypt` module.
When using Jetty embedded, ALPN is enabled by the `jetty-alpn-conscrypt-client` and `jetty-alpn-conscrypt-server` artifacts, respectively for client usage and server usage.
In addition, you also need the Conscrypt artifacts, typically the `org.conscrypt:conscrypt-openjdk-uber` artifact.
All these artifacts must be added to the classpath.
[[alpn-jdk9]]
==== ALPN and JDK 9
When using JDK 9 or later and Jetty as a standalone server via the Jetty distribution, ALPN support is automatically enabled when the `http2` module is enabled.
This enables transitively the `alpn-9` module which puts the `jetty-alpn-java-server` artifact in the server classpath, providing the ALPN JDK 9 service implementation.
When using JDK 9 or later and Jetty embedded, the ALPN service implementation is provided by the `jetty-alpn-java-client` and `jetty-alpn-java-server` artifacts, respectively for client usage and server usage, and must be added to the classpath.
[[alpn-osgi]]
===== Starting in OSGi

11
jetty-documentation/src/main/asciidoc/administration/alpn/chapter.adoc
View File

@ -19,12 +19,15 @@
[[alpn-chapter]]
== Application Layer Protocol Negotiation (ALPN)
The development of new web protocols such as HTTP/2 raised the need of protocol negotiation within a Transport Layer Security (TLS) handshake.
A protocol negotiation called https://tools.ietf.org/html/rfc7301[ALPN] (Application Layer Protocol Negotiation) RFC7301 has been defined to accomplish this.
The development of new web protocols such as HTTP/2 raised the need of protocol
negotiation within a Transport Layer Security (TLS) handshake.
A protocol negotiation called ALPN (Application Layer Protocol Negotiation -
https://tools.ietf.org/html/rfc7301[RFC7301]) has been defined to accomplish this.
ALPN has now replaced the older (and now fully deprecated) NPN in the general Web of 2016.
ALPN has now replaced the older (and now fully deprecated) NPN in the general Web
as of 2016.
For those browsers that support HTTP/2, they all now support the ALPN negotiation layers for TLS.
For those browsers that support HTTP/2, they all now support ALPN.
Starting with Jetty 9.3.0, only ALPN is supported by Jetty.
include::alpn.adoc[]