Configuring HTTP/2

Edit page
Last modified: 11 May 2022

Code examples: http2-netty, http2-jetty

tip

This help topic is in development and will be updated in the future.

HTTP/2 is a modern binary duplex multiplexing protocol designed as a replacement for HTTP/1.x.

Jetty, Netty, and Tomcat engines provide HTTP/2 implementations that Ktor can use. However, there are significant differences, and each engine requires additional configuration. Once your host is configured properly for Ktor, HTTP/2 support will be activated automatically.

Key requirements:

  • SSL certificate (can be self-signed)

  • ALPN implementation suitable for a particular engine (see corresponding sections for Netty, Jetty, and Tomcat)

SSL certificate

As per the specification, HTTP/2 does not require encryption, but all browsers will require encrypted connections to be used with HTTP/2. That's why a working TLS environment is a prerequisite for enabling HTTP/2. Therefore, a certificate is required to enable encryption. For testing purposes, it can be generated with keytool from the JDK ...

keytool -keystore test.jks -genkeypair -alias testkey -keyalg RSA -keysize 4096 -validity 5000 -dname 'CN=localhost, OU=ktor, O=ktor, L=Unspecified, ST=Unspecified, C=US'

... or by using the generateCertificate function.

The next step is configuring Ktor to use your keystore. See the example application.conf:

ktor {
    deployment {
        port = 8080
        sslPort = 8443
    }

    application {
        modules = [ com.example.ApplicationKt.main ]
    }

    security {
        ssl {
            keyStore = test.jks
            keyAlias = testkey
            keyStorePassword = foobar
            privateKeyPassword = foobar
        }
    }
}

ALPN implementation

HTTP/2 requires ALPN (Application-Layer Protocol Negotiation) to be enabled. The first option is to use an external ALPN implementation that needs to be added to the boot classpath. Another option is to use OpenSSL native bindings and precompiled native binaries. Also, each particular engine can support only one of these methods.

Jetty

Since ALPN APIs are supported starting with Java 8, the Jetty engine doesn't require any specific configurations for using HTTP/2. So, you only need to:

  1. Create a server with the Jetty engine.

  2. Add an SSL configuration as described in SSL certificate.

  3. Configure sslPort.

The http2-jetty runnable example demonstrates HTTP/2 support for Jetty.

Netty

The easiest way to enable HTTP/2 in Netty is to use OpenSSL bindings (tcnative netty port). Add an API jar to dependencies:

implementation "io.netty:netty-tcnative:$tcnative_version"

and then native implementation (statically linked BoringSSL library, a fork of OpenSSL):

implementation "io.netty:netty-tcnative-boringssl-static:$tcnative_version"
implementation "io.netty:netty-tcnative-boringssl-static:$tcnative_version:$tcnative_classifier"

where tc.native.classifier should be one of the following: linux-x86_64, osx-x86_64 or windows-x86_64. The http2-netty runnable example demonstrates how to enable HTTP/2 support for Netty.

Tomcat and other servlet containers

Similar to Netty, to get HTTP/2 working in Tomcat you need native OpenSSL bindings. Unfortunately, Tomcat's tcnative is not completely compatible with the Netty one. This is why you need a slightly different binary. You can get it here (https://tomcat.apache.org/native-doc/), or you can try Netty's tcnative. However, you'll have to guess which exact version is compatible with your specific Tomcat version.

If you are deploying your Ktor application as a war package into the server (servlet container), then you will have to configure your Tomcat server properly: