Experimenting with NGINX


June 12, 2021

This page describes how to enable support for some features on NGINX, i.e. post-quantum schemes or QUIC protocol. Page is updated on as-needed bases, some parts of it may be specific to Debian Linux.


I’ll get NGINX sources, change it’s the build configuration, re-compile the server and rebuild deb package. To get sources, we have to add the NGINX repositories to the /etc/apt/sources/list.

The following two lines go to the end of a file:

deb https://nginx.org/packages/mainline/debian buster nginx
deb-src https://nginx.org/packages/mainline/debian buster nginx

Then add NGINX public key for verification and download the sources:

sudo wget https://nginx.org/keys/nginx_signing.key
sudo apt-key add nginx_signing.key
sudo apt-get update
sudo apt-get upgrade
sudo apt-get build-dep nginx
sudo apt-get source nginx

Sources should now be downloaded to the nginx directory.

Adding QUIC support

The QUIC protocol specified by RFC9000 opens new possibilities. Something I would definitely like to try. Clone the newest version and overwrite whatever is currently provided by NGINX.

hg clone -b quic https://hg.nginx.org/nginx-quic
rsync -r nginx-quic/ nginx

Again, the rules file needs to be modified to enable the support. Add --with-http_v3_module --with-http_quic_module --with-stream_quic_module to config.env.nginx and config.env.nginx_debug targets (somewhere after --with-stream_ssl_preread_module).

Package creation

Following commands re-create debian package with NGINX, which the can be installed by dpkg. This two step procedure requires, first to modify nginx/debian/changelog file and add information about changes done to the package. Add something like:

nginx (1.21.0-2~buster) buster; urgency=low

  * 1.21.0-1 adds quic

 -- Kris Kwiatkowski <kris@amongbytes.com>  Tue, 12 Jun 2021 16:01:22 +0300

Next step is to build a package. Build process will use GPG key to sign the package. To specify a key I use -kkris@amongbytes.com which identify secret key used for signing.

To start the build use following command:

sudo dpkg-buildpackage -b -kkris@amongbytes.com

NGINX configuration

Following instructions enable post-quantum in TLS and add support for QUIC protocol (unfortunatelly, PQ in QUIC is not supported).

  1. Post-Quantum support: BoringSSL supports post-quantum key exchange. It can be enabled only in TLS v1.3 and uses a variant of NTRU-HRSS mixed with X25519, called CECPQ2 (detailed description here). To enable that support, following line needs to be added to nginx.conf
    ssl_protocols TLSv1.2 TLSv1.3;      # Enable both TLS 1.3 and 1.2
    ssl_ecdh_curve CECPQ2:X25519:P-256; # Enable PQ key exchange

It is important to add CECPQ2 as a first on that list as well as add some classical key exchange algorithm for backward compatibility. This server supports post-quantum key exchange.

  1. QUIC support: for HTTP/3 over QUIC add following changes to the virtual server config:
    listen 443 http3 quic reuseport;
    listen 443 ssl http2;

    quic_retry on;
    ssl_early_data on;

    http3_max_field_size 5000;
    http3_max_table_capacity 50;
    http3_max_blocked_streams 30;
    http3_max_concurrent_pushes 30;
    http3_push 10;
    http3_push_preload on;

    add_header alt-svc '$quic=":443"; ma=3600';

The add_header alt-svc is need to make sure that the web browser will know that your server supported http/3. Other settings also need to setup in order for the NGINX QUIC not to produce 404 error on your file assets.