How to configure signed HTTP exchanges (SXG)

How to generate a TLS certificate with SXG extensions, install tools to generate SXG files, and configure nginx to serve SXG files.

March 11, 2020

Signed HTTP Exchanges (SXG) es una nueva tecnología Web que facilita a los usuarios diferenciar a los creadores de contents de los distribuidores de contenido. Esta guía le muestra cómo configurar SXG.

Compatibilidad con varios browsers

Varios navegadores basados ​​en Chromium admiten SXG, incluidos Google Chrome, Samsung Internet y Microsoft Edge. Consulte la sección de consenso y estandarización de
HTTP exchanges signed by origin
for the most up-to-date information.

Prerequisites

To implement SXG on your website, you must:

• Tenga control sobre su domain, incluidas las entradas de DNS.
• Get certificates. SXG requires the issuance of a dedicated certificate. In particular, you cannot reuse your TLS key or certificate.
• Tenga un server HTTP que pueda generar y servir SXG a través de 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.
• They are using DigiCert to generate certificates that include SXG related extensions, because it currently appears to be the only vendor that supports these extensions.

Also, the example commands in this article assume that your domain is website.test, so you will need to replace website.test with his royal 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 issuing 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 this:

-----BEGIN CERTIFICATE REQUEST-----
MIHuMIGVAgEAMDMxDTALBgNVBAoMBFRlc3QxCzAJBgNVBAYTAlVTMRUwEwYDVQQD
DAx3ZWJzaXRlLnRlc3QwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAS7IVaeMvid
S5UO7BspzSe5eqT5Qk6X6dCggUiV/vyqQaFDjA/ALyTofgXpbCaksorPaDhdA+f9
APdHWkTbbdv1oAAwCgYIKoZIzj0EAwIDSAAwRQIhAIb7n7Kcc6Y6pU3vFr8SDNkB
kEadlVKNA24SVZ/hn3fjAiAS2tWXhYdJX6xjf2+DL/smB36MKbXg7VWy0K1tWmFi
Sg==
-----END CERTIFICATE REQUEST-----

Make sure of that:

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

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

Step 2: install libsxg

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

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 OpenSSL (libssl-dev) matches the version.

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 by hand

If you are not using an environment compatible with .deb files, you can build libsxg yourself. As a precondition, you must install git, cmake, openssland 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 plug

the nginx The plugin allows you to generate SXG dynamically instead of generating them statically before 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
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: compile the plugin manually

Building the nginx module requires the nginx source code. Puede obtener el tarball y construirlo junto con el módulo dinámico SXG usando los siguientes comandos:

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 The configuration has great flexibility. Install on pc nginx anywhere on your system, then specify a respective path of module / config / log / pidfile. This guide assumes that you install it on / opt / nginx.

Step 4: configure the nginx plugin to work with SXG

Option 1: configure an installation from Debian nginx module

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

La entrega de contenido SXG requiere HTTPS. Puede obtener un certificado SSL / TLS de DigiCert, Let’s Encrypt y otros servicios. Tenga en cuenta que NO PUEDE utilizar un certificado SXG para SSL o viceversa, por lo tanto, necesitará dos certificados. El archivo de configuración en /etc/nginx/nginx.conf it should look similar to the following, assuming you put the SSL certificate / key 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 It is essential for browsers to load SXG correctly because it locates the certificate chain. The certificate chain contains OCSP stapling and certificate information in cbor format. Note that you do not need to cert.cbor archivo del mismo origen. Puede servirlo a través de cualquier CDN u otros servicios de servicio de archivos estáticos siempre que be compatible con HTTPS.
• sxg_validitiy_url está previsto que sirva información relacionada con el encabezado de la firma SXG. Si una página no se ha modificado desde el último SXG, técnicamente no es necesario descargar el archivo SXG completo. Por lo tanto, se espera que la actualización de la información del encabezado de la firma por sí sola reduzca el traffic de red. Pero los detalles aún no están implementados.

Start nginx And you're 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 an embedded font nginx module

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

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: deliver your application backend

In the examples above, nginx sirve archivos estáticos en el root directory, pero puede usar directivas ascendentes para sus aplicaciones para hacer SXG para backends de aplicaciones web arbitrarias (como Ruby on Rails, Django o Express) siempre que su nginx works as a front end 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
para probar que los SXG que se sirven sean correctos, asegúrese de que no se notifiquen errores y verifique que los headers y el cuerpo sean los esperados.

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

Post comments

Chromium engineers working at SXG are eager to hear your feedback at [email protected]. You can also join the specification discussionor Report a bug to the team. Your feedback will be of great help in the standardization process and will also help address implementation issues. Thanks!