Skip to content

google/nginx-sxg-module

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

80 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

NGINX SXG module

Build Status

Signed HTTP Exchange (SXG) support for nginx. Nginx will convert responses from the upstream application into SXG when client requests include the Accept: application/signed-exchange;v=b3 HTTP header with highest qvalue.

Installation

There are two options for installation: Debian package or build from source. See this article for more details.

If building from source and you have libsxg installed in a non-system directory, edit config to add ngx_module_incs=path/to/include and add -Lpath/to/lib to the existing ngx_module_libs, and launch nginx with LD_LIBRARY_PATH=path/to/lib.

Configuration

Nginx-SXG module requires configuration on nginx.

Directives

sxg

Activation flag of SXG module. This can be set or overriden inside server and location directives.

  • on: Enable this plugin.
  • off: Disable this plugin.

Default value is off.

sxg_certificate

Full path for the certificate file. The certificate requires all of the conditions below to match. This and all below directives can only be set inside server directives.

  • Has CanSignHttpExchanges extension.
  • Uses ECDSA256 or ECDSA384.

This directive is always required.

sxg_certificate_key

Full path for the private key for the certificate.

This directive is always required.

sxg_cert_url

URL for CBOR encoded certificate file. The protocol must be https.

This directive is always required.

sxg_validity_url

URL for the validity information file. It must be https and must be the same origin with the website.

This directive is always required.

sxg_max_payload

Maximum HTTP body size this module can generate SXG from. Default value is 67108864 (64 MiB).

sxg_cert_path

This directive is optional. If specified, this should be an absolute path corresponding to a file that will be served at the URL specified by sxg_cert_url. This plugin will then automatically generate and refresh the CBOR-encoded certificate file, given the PEM located at sxg_certificate. It requires that the OCSP responder for the certificate is accessible from your nginx server to get OCSP responses.

Alternatively, use gen-certurl to generate a new cert-chain+cbor daily, and serve it statically at the URL specified by sxg_cert_url.

sxg_expiry_seconds

The life-span of generated SXG file in seconds. It must not be bigger than 604800 (1 week). This directive is optional. The default value is 86400 (1 day).

sxg_fallback_host

The hostname of fallback url of generated SXG file. This directive is optional. The default value is Host field parameter of HTTP request header.

Config Example

load_module "modules/ngx_http_sxg_filter_module.so";

http {
    upstream app {
        server 127.0.0.1:3000;
    }
    include       mime.types;
    default_type  application/octet-stream;
    subrequest_output_buffer_size   4096k;

    server {
        listen    80;
        server_name  example.com;

        sxg on;
        sxg_certificate     /path/to/certificate-ecdsa.pem;
        sxg_certificate_key /path/to/private-key-ecdsa.key;
        sxg_cert_url        https://cdn.test.com/example.com.cert.cbor;
        sxg_validity_url    https://example.com/validity/resource.msg;
        sxg_expiry_seconds 604800;
        sxg_fallback_host  example.com;

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

Subresource support

nginx-sxg-module automatically includes signatures of subresources in its responses, allowing end users to prefetch it from distributor. When finding link: rel="preload" entry in HTTP response header from upstream, this plugin will collect the specified resource to the upstream and append rel="allowed-alt-sxg";header-integrity="sha256-...." to the original HTTP response automatically. This functionality is essential to subresource preloading for faster cross-site navigation.

To ensure subresource prefetching works, verify that the header-integrity in:

curl -H 'Accept: application/signed-exchange;v=b3' https://url/of/page.html | dump-signedexchange -payload=false | grep Link:

equals the value of:

curl -H 'Accept: application/signed-exchange;v=b3' https://url/of/subresource.jpg | dump-signedexchange -headerIntegrity