Hiroki Kumazaki on web.dev

How to distribute Signed HTTP Exchanges (SXG) using nginx

2020-03-11T00:00:00Z

As a Signed HTTP Exchanges (SXG) distributor, you can deliver SXG files on behalf of the original content creators. Web browsers that support SXG will display such SXG files as if they were delivered from the original content creators. This enables you to implement cross-site preloading without violating privacy. This guide shows you how to distribute SXG properly.

Cross-browser support #

Chrome is currently the only browser that supports SXG. See the Consensus & Standardization section of Origin-Signed HTTP Exchanges for more up-to-date information.

Get SXG files #

Specify in your Accept request header that you want the server to return an SXG file along with the request:

Accept: application/signed-exchange;v=b3,*/*;q=0.8

This guide assumes that you put your SXG files in /var/www/sxg.

Serve a simple SXG file #

Attach the following headers to distribute a single SXG file:

Content-Type: application/signed-exchange;v=v3
X-Content-Type-Options: nosniff

Configure nginx:

http {
    ...
    types {
        application/signed-exchange;v=b3  sxg;
    }
    add_header X-Content-Type-Options nosniff;

    location / {
        more_set_headers "Content-Type: application/signed-exchange;v=b3";
        alias /var/www/sxg/;
        try_files $uri.sxg $uri =404;
        autoindex off;
    }
    ...

Load the new configuration into nginx:

sudo systemctl restart nginx.service

nginx will start serving SXG files. When Chrome accesses your server, the address of the original content publisher will appear in the bar!

Prefetch subresources #

Most web pages consist of multiple subresources, such as CSS, JavaScript, fonts, and images. The content of SXG cannot be changed without the content creator's private key. This causes problems when the browser tries to resolve subresources.

For example, suppose index.html.sxg from https://website.test/index.html has a link to https://website.test/app.js. When a user's browser receives the SXG file from https://distributor.test/example.com/index.html.sxg, it will find the link to https://website.test/app.js. The browser can fetch https://website.test/app.js directly on actual access, but it should not be done in the preload phase to preserve privacy. If the resource was fetched during the preload phase, it would be possible for the content creator (website.test) to be able to detect which content distributor (distributor.test) is requesting the resource.

If the distributor wants to serve app.js.sxg from their own service and tries to modify https://website.test/app.js to be the distributor's version of that subresource (such as https://distributor.test/website.test/app.js.sxg), it will cause a signature mismatch and make the SXG invalid.

To solve this problem, there's an experimental SXG subresource prefetching feature in Chrome now. You can enable it at: about://flags/#enable-sxg-subresource-prefetching. To use subresource prefetching the following conditions must be met:

The publisher must embed a response header entry in SXG, such as: link: <https://website.test/app.js>;rel="preload";as="script",<https://website.test/app.js>;rel="allowed-alt-sxg";header-integrity="sha256-h6GuCtTXe2nITIHHpJM+xCxcKrYDpOFcIXjihE4asxk=". This specifies the subresource that can be substituted with the SXG's specific integrity hash.
The distributor must attach a response header when serving the SXG, such as: link: <https://distributor.test/website.test/app.js.sxg>;rel="alternate";type="application/signed-exchange;v=b3";anchor="https://website.test/app.js". This specifies the path of app.js and corresponds to the subresource.

The first one is relatively easy because nginx-sxg-module can calculate integrity hashes and embed them into link headers from upstream responses. But the second one is more difficult because the content distributor must be aware of the specified subresources in the SXG.

If there are no subresources other than https://website.test/app.js, then all you need to append in your nginx config is:

add_header link <https://distributor.test/website.test/app.js.sxg>;rel="alter...

But such cases are rare because typical websites consist of a lot of subresources. Additionally, the distributor must attach the proper anchor link header when serving an SXG file. Currently, there is no easy way to resolve this issue, so stay tuned for updates!

Send feedback #

Chromium engineers are keen to hear your feedback on distributing SXG at webpackage-dev@chromium.org. You can also join the spec discussion, or report a bug to the team. Your feedback will greatly help the standardization process and also help address implementation issues. Thank you!

How to set up Signed HTTP Exchanges (SXG) using nginx

2020-03-11T00:00:00Z

Signed HTTP Exchanges (SXG) is a new web technology that makes it easier for users to tell content creators apart from content distributors. This guide shows you how to set up SXG.

Cross-browser support #

Several Chromium-based browsers support SXG, including Google Chrome, Samsung Internet, and Microsoft Edge. See the Consensus and Standardization section of Origin-Signed HTTP Exchanges for more up-to-date information.

Prerequisites #

To implement SXG on your website, you must:

Have control over your domain, including DNS entries.
Get certificates. SXG requires the issuance of a dedicated certificate. In particular, you cannot reuse your TLS key or certificate.
Have an HTTP server that can generate and serve SXG over HTTPS.

Assumptions #

This guide assumes that you:

Have an OpenSSL 1.1.1 environment. This guide was written with Ubuntu 18.04 LTS on amd64 ISA.
Have the ability to run sudo to install executables.
Use nginx as an HTTP server.
Are using DigiCert to generate certificates that include SXG-related extensions, because it currently appears to be the only provider that supports these extensions.

Also, the example commands in this article assume your domain is website.test, so you'll need to replace website.test with your actual domain.

Step 1: Get your certificate for SXG #

To generate SXG, you need a TLS certificate with the CanSignHttpExchanges extension, as well as a particular key type. DigiCert provides certificates with this extension. You need a CSR file for issuance of a certificate, so generate it with the following commands:

openssl ecparam -genkey -name prime256v1 -out mySxg.key
openssl req -new -key mySxg.key -nodes -out mySxg.csr -subj "/O=Test/C=US/CN=website.test"

You will get a CSR file that looks like the following:

Make sure that:

The validity period does not exceed 90 days.
The Include the CanSignHttpExchanges extension in the certificate checkbox is enabled, which is found under Additional Certificate Options.

The Include the CanSignHttpExchanges extension in the certificate checkbox.

If your certificate does not match these conditions, browsers and distributors will reject your SXG for security reasons. This guide assumes that the filename of the certificate you got from DigiCert is mySxg.pem.

Step 2: Install `libsxg` #

The SXG format is complex and hard to generate without using tools. You can use one of the following options to generate SXG:

The gen-signedexchange tool written in Go.
The libsxg library written in C.

This guide uses libsxg.

Option 1: Install `libsxg` from a Debian package #

You can install the package in the usual Debian way, as long as the OpenSSL (libssl-dev) version matches.

sudo apt install -y libssl-dev
wget https://github.com/google/libsxg/releases/download/v0.2/libsxg0_0.2-1_amd64.deb
wget https://github.com/google/libsxg/releases/download/v0.2/libsxg-dev_0.2-1_amd64.deb
sudo dpkg -i libsxg0_0.2-1_amd64.deb
sudo dpkg -i libsxg-dev_0.2-1_amd64.deb

Option 2: Build `libsxg` manually #

If you are not using an environment compatible with .deb files, you can build libsxg yourself. As a precondition, you need to install git, cmake, openssl, and gcc.

git clone https://github.com/google/libsxg
mkdir libsxg/build
cd libsxg/build
cmake .. -DRUN_TEST=false -DCMAKE_BUILD_TYPE=Release
make
sudo make install

Step 3: Install `nginx` plugin #

The nginx plugin allows you to generate SXG dynamically instead of statically generating them prior to serving.

Option 1: Install the plugin from a Debian package #

The SXG module for nginx is distributed on GitHub. On Debian-based systems, you can install it as a binary package:

sudo apt install -y nginx=1.15.9-0
wget https://github.com/google/nginx-sxg-module/releases/download/v0.1/libnginx-mod-http-sxg-filter_1.15.9-0ubuntu1.1_amd64.deb
sudo dpkg -i libnginx-mod-http-sxg-filter_1.15.9-0ubuntu1.1_amd64.deb

Option 2: Build plugin manually #

Building the nginx module requires the nginx source code. You can get the tarball and build it along with the SXG dynamic module using the commands below:

git clone https://github.com/google/nginx-sxg-module
wget https://nginx.org/download/nginx-1.17.5.tar.gz
tar xvf nginx-1.17.5.tar.gz
cd nginx-1.17.5
./configure --prefix=/opt/nginx --add-dynamic-module=../nginx-sxg-module --without-http_rewrite_module --with-http_ssl_module
make
sudo make install

The nginx configuration has great flexibility. Install nginx anywhere in your system, then specify a respective path of module/config/log/pidfile. This guide assumes that you install it to /opt/nginx.

Step 4: Configure the `nginx` plugin to work with SXG #

Option 1: Configure an installed-from-Debian `nginx` module #

Follow these instructions if you used Step 3, Option 1 earlier.

Delivering SXG content requires HTTPS. You can get an SSL/TLS certificate from DigiCert, Let's Encrypt, and other services. Note that you CANNOT use an SXG certificate for SSL or vice versa, therefore you will need two certificates. The configuration file in /etc/nginx/nginx.conf should look similar to the following, assuming that you put the SSL key/certificate pair in /path/to/ssl/ and the SXG key/certificate pair in /path/to/sxg/:

user www-data;
include /etc/nginx/modules-enabled/*.conf;

events {
     worker_connections 768;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
    add_header  X-Content-Type-Options nosniff;

    server {
        listen 443 ssl;
        ssl_certificate     /path/to/ssl/fullchain.pem;
        ssl_certificate_key /path/to/ssl/privkey.pem;
        server_name  website.test;

        sxg on;
        sxg_certificate     /path/to/sxg/mySxg.pem;
        sxg_certificate_key /path/to/sxg/mySxg.key;
        sxg_cert_url        https://website.test/certs/cert.cbor;
        sxg_validity_url    https://website.test/validity/resource.msg;
        sxg_cert_path       /certs/cert.cbor;

        root /var/www/html;
    }
}

sxg_cert_url is essential for browsers to load SXG properly because it locates the certificate chain. The certificate chain contains certificate and OCSP stapling information with cbor format. Note that you do not have to serve the cert.cbor file from the same origin. You can serve it via any CDNs or other static file serving services as long as it supports HTTPS.
sxg_validitiy_url is planned to serve SXG-signature-header-related information. If a page has not been modified since the last SXG, downloading the entire SXG file is not required technically. So updating signature header information alone is expected to reduce network traffic. But the details are not implemented yet.

Start nginx and you are ready to serve SXG!

sudo systemctl start nginx.service
curl -H"Accept: application/signed-exchange;v=b3" https://website.test/ > index.html.sxg
cat index.html.sxg
sxg1-b3...https://website.test/...(omit)

Option 2: Configure a built-from-source `nginx` module #

Follow these instructions if you used Step 3, Option 2 earlier.

Configure your nginx system installed under /opt/nginx to look similar to the following example:

load_module "/opt/nginx/modules/ngx_http_sxg_filter_module.so";

events {
    worker_connections 768;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
    add_header X-Content-Type-Options nosniff;

    server {
        listen 443 ssl;
        ssl_certificate     /path/to/ssl/fullchain.pem;
        ssl_certificate_key /path/to/ssl/privkey.pem;
        server_name  example.com;

        sxg on;
        sxg_certificate     /path/to/sxg/mySxg.pem;
        sxg_certificate_key /path/to/sxg/mySxg.key;
        sxg_cert_url        https://website.test/certs/cert.cbor;
        sxg_validity_url    https://website.test/validity/resource.msg;
        sxg_cert_path       /certs/cert.cbor;

        root /opt/nginx/html;
    }
}

Then start nginx. Now you can get your SXG!

cd /opt/nginx/sbin
sudo ./nginx
curl -H "Accept: application/signed-exchange;v=b3" https://website.test/ > index.html.sxg
less index.html.sxg
sxg1-b3...https://website.test/...(omit)

Step 5: Serve your application backend #

In the above examples, nginx serves static files in the root directory, but you can use upstream directives for your applications to make SXG for arbitrary web application backends (such as Ruby on Rails, Django, or Express) as long as your nginx works as a front HTTP(S) server.

upstream app {
    server 127.0.0.1:8080;
}

server {
    location / {
        proxy_pass http://app;
    }
}

Step 6: Test #

Use the dump-signedexchange tool to test that the SXGs being served are correct, ensure that no errors are reported, and verify that the headers and body are as expected.

go get -u github.com/WICG/webpackage/go/signedexchange/cmd/dump-signedexchange
export PATH=$PATH:~/go/bin
dump-signedexchange -verify -uri https://website.test/ | less

Send feedback #

The Chromium engineers working on SXG are keen to hear your feedback at webpackage-dev@chromium.org. You can also join the spec discussion, or report a bug to the team. Your feedback will greatly help the standardization process and also help address implementation issues. Thank you!

Hiroki Kumazaki on web.dev

How to distribute Signed HTTP Exchanges (SXG) using nginx

Cross-browser support #

Get SXG files #

Serve a simple SXG file #

Prefetch subresources #

Send feedback #

How to set up Signed HTTP Exchanges (SXG) using nginx

Cross-browser support #

Prerequisites #

Assumptions #

Step 1: Get your certificate for SXG #

Step 2: Install libsxg #

Option 1: Install libsxg from a Debian package #

Option 2: Build libsxg manually #

Step 3: Install nginx plugin #

Option 1: Install the plugin from a Debian package #

Option 2: Build plugin manually #

Step 4: Configure the nginx plugin to work with SXG #

Option 1: Configure an installed-from-Debian nginx module #

Option 2: Configure a built-from-source nginx module #

Step 5: Serve your application backend #

Step 6: Test #

Send feedback #

Step 2: Install `libsxg` #

Option 1: Install `libsxg` from a Debian package #

Option 2: Build `libsxg` manually #

Step 3: Install `nginx` plugin #

Step 4: Configure the `nginx` plugin to work with SXG #

Option 1: Configure an installed-from-Debian `nginx` module #

Option 2: Configure a built-from-source `nginx` module #