Skip navigation

Requirements for 4.x

Did you know this page is automatically generated from a Github Wiki page? You can improve it by yourself here!


The Netty project consists of various sub-modules. For specific requirements for each sub-module refer to their specific section below.

In general the base functionality of each sub-module requires Java 6+ to run and Java 7+ to compile.

This codec provides an implementation for the HTTP/2 Protocol including HPACK.

Transport Security (TLS)

Although the HTTP/2 RFC does not require using TLS the RFC does enforce requirements if TLS is in use [1][2][3]. HTTP/2 over TLS mandates the use of ALPN to negotiate the use of the h2 protocol. ALPN is a fairly new standard and (where possible) Netty supports protocol negotiation via NPN for systems that do not yet support ALPN.

TLS with OpenSSL

This is currently the recommended approach for doing TLS with Netty.

Benefits of using OpenSSL

  1. Speed: In local testing, we've seen performance improvements of 3x over the JDK. GCM, which is used by the only cipher suite required by the HTTP/2 RFC, is 10-500x faster.
  2. Ciphers: OpenSSL has its own ciphers and is not dependent on the limitations of the JDK. This allows supporting GCM on Java 7.
  3. ALPN to NPN Fallback: OpenSSL can support ALPN and NPN simultaneously. The JDK implementation by Netty only supports either ALPN or NPN at any given time and NPN is only supported in JDK 7.
  4. Java Version Independence: does not require using a different library version depending on the JDK update. This is a limitation of the JDK ALPN and NPN implementation used by Netty.

Requirements for using OpenSSL

  1. OpenSSL version >= 1.0.2 for ALPN support, or version >= 1.0.1 for NPN.
  2. netty-tcnative version >= 1.1.33.Fork7 must be on classpath.
  3. Supported platforms (for netty-tcnative): linux-x86_64, mac-x86_64, windows-x86_64. Supporting other platforms will require manually building netty-tcnative.

If the above requirements are met, Netty will automatically select OpenSSL as the default TLS provider.

Configuring netty-tcnative

See the netty-tcnative wiki.

TLS with JDK (Jetty ALPN/NPN)

If you are not able to use OpenSSL then the alternative is to use the JDK for TLS.

Java supports ALPN or NPN only from version 8u251 and 9. For lack of support in older JDKs we need to use the Jetty-ALPN (or Jetty-NPN if on Java < 8) bootclasspath extension for OpenJDK. To do this, add a Xbootclasspath JVM option referencing the path to the Jetty alpn-boot jar.

java -Xbootclasspath/p:/path/to/jetty/alpn/extension.jar ...

Note that you must use the release of the Jetty-ALPN jar specific to the version of Java you are using.

JDK Ciphers

Java 7 does not support the cipher suites recommended by the HTTP2 RFC. To address this we suggest servers use Java 8 where possible or use an alternative JCE implementation such as Bouncy Castle. If this is not practical it is possible to use other ciphers but you need to ensure that the services you intend to call also support these ciphers forbidden by the HTTP/2 RFC and have evaluated the security risks of doing so.

Users should be aware that GCM is very slow (1 MB/s) before Java 8u60. With Java 8u60 GCM is 10x faster (10-20 MB/s), but that is still slow compared to OpenSSL (~200 MB/s), especially with AES-NI support (~1 GB/s). GCM cipher suites are the only suites available that comply with HTTP2's cipher requirements.

Enabling ALPN or NPN

The SslContextBuilder has a setter for an ApplicationProtocolConfig which is used to configure ALPN or NPN. See the HTTP/2 examples for ALPN and SPDY examples for NPN usage.

Last retrieved on 02-May-2024