Learn how to serve signed exchanges (SXGs) using Web Packager.
A signed exchange (SXG) is a delivery mechanism that makes it possible to authenticate the origin of a resource independently of how it was delivered. The following instructions explain how to set up Signed Exchanges using Web Packager. Instructions are included for both self-signed and
Using a self-signed certificate to serve SXGs is primarily used for demonstration and testing purposes. SXGs signed with a self-signed certificate will generate error messages in the browser when used outside of testing environments and should not be served to crawlers.
To follow these instructions you will need to have openssl and Go installed in your development environment. You will also need an existing HTTPS site.
These instructions use the following architecture to serve SXGs:
Following these instructions verbatim will setup a
webpackager instance that packages and serves content from
example.com as a SXG. To generate SXGs for a different site, replace the mentions of
example.com in these instructions with the site of your choice. In production environments you will only be able to generate SXGs for sites that you own.
This section explains how to generate a self-signed certificate that can be used with signed exchanges.
Generate a private key.
openssl ecparam -out priv.key -name prime256v1 -genkey
The private key will be saved as a file named
Create a certificate signing request (CSR).
openssl req -new -sha256 -key priv.key -out cert.csr -subj '/O=Web Packager Demo /CN=example.com'
A certificate signing request is a block of encoded text that conveys the information necessary to request a certificate from a certificate authority(CA). Although you will not be requesting a certificate from a CA, it is still necessary to create a certificate signing request.
The command above creates a certificate signing request for an organization named
Web Packager Demo that has the common name
example.com. The common name should be the fully qualified domain name of the site that contains the content that you want to package as SXG.
In a production SXG setup, this would be a site that you own. However, in a testing environment like the one described in these instructions, it can be any site.
Create a certificate that has the
openssl x509 -req -days 90 -in cert.csr -signkey priv.key -out cert.pem -extfile <(echo -e "126.96.36.199.4.1.11188.8.131.52 = ASN1:NULL\nsubjectAltName=DNS:example.com")
This command uses the private key and the CSR created in steps 1 and 2 to create the certificate file
-extfile flag associates the certificate with the
CanSignHttpExchanges certificate extension (
184.108.40.206.4.1.11220.127.116.11 is the object identifier for the
CanSignHttpExchanges extension). In addition, the
-extfile flag also defines
example.com as a Subject Alternative Name.
If you are curious about the contents of
cert.pem, you can view them using the following command:
openssl x509 -in cert.pem -noout -text
You are done creating private keys and certificates. You will need the
cert.pem files in the next section.
Install Web Packager.
git clone https://github.com/google/webpackager.git
go build .
webpkgserver is a specific binary within the Web Packager project.
webpkgserver has been installed correctly.
This command should return information about the usage of
webpkgserver. If this does not work, a good first troubleshooting step is to verify that your GOPATH is configured correctly.
Navigate to the
webpackager directory (you might already be in this directory).
webpkgsever.toml file by copying the example.
cp ./webpkgserver.example.toml ./webpkgserver.toml
This file contains the configuration options for
webpkgserver.toml with an editor of your choice and make the following changes:
#AllowTestCert = falseto
AllowTestCert = true.
PEMFile = 'path/to/your.pem'to reflect the path to the PEM certificate,
cert.pem, that you created. Do not change the line mentioning
TLS.PEMFile—this is a different configuration option.
KeyFile = 'priv.key'to reflect the path of the private key,
priv.key, that you created. Do not change the line mentioning
TLS.KeyFile—this is a different configuration option.
Domain = 'example.org'to reflect the domain that you created a certificate for. If you have followed the instructions in this article verbatim, this should be changed to
webpkgserverwill only fetch content from the domain indicated by
webpkgserver.toml. If you try to fetch pages from a different domain without updating
webpkgserverlogs will show the error message
URL doesn't match the fetch targets.
#PreloadCSS = falseto
PreloadCSS = true. In addition, change the line
#PreloadJS = falseto
PreloadJS = true. For more information about subresource substitution, check out the explainer.
If the server has started successfully, you should see the message
Listening at 127.0.0.1:8080. If you do not see this message, a good first troubleshooting step is to double-check
Next, in order to test SXGs that use a self-signed certificate, you will need to enable the
Allow Signed HTTP Exchange certificates without extension flag in Chrome.
Open Chrome, go to
chrome://flags, and then set
Allow Signed HTTP Exchange certificates without extension to Enabled. Then click the Relaunch button to have these changes take effect.
Open the DevTools Network tab, then visit the following URL:
This makes a request to the
webpackager instance running at
http://localhost:8080 for a SXG containing the contents of
/priv/doc/ is the default API endpoint used by
A resource with the type
signed-exchange should be listed in the Network tab. If you don't see this resource, try clearing the cache, then reloading
DevTools highlights the SXG in red because the SXG has errors associated with it. To view these errors and other information about the SXG, click on the SXG, then click Preview.
The Preview tab displays information about the Signed Exchange and its signature. At the top of the Preview tab you should see the error
Failed to fetch certificate. The browser displays this error when it is unable to load a certificate from the Certificate URL indicated in the signature. The next section explains how to fix this error by uploading a certificate.
Without the certificate, the browser is unable to authenticate the SXG and it falls back to loading the resource without using SXG. This is why there is an additional request to
example.com listed in the Network panel.
To establish the authenticity of a SXG, the browser must be able to load the certificate that was used to sign the SXG from the Certificate URL indicated in the signature. If the browser is unable to load this certificate, it will request that the content be delivered without using SXG.
These instructions explain how to serve a certificate from an existing HTTPS environment.
webpkgserver can be configured to use a locally-hosted certificate. For information on this configuration option, refer to the
CertURLBase option in
webpkgserver.toml. Learn more about how to use HTTPS for local development.
The instructions in this section assume that you have the ability to upload a certificate to an existing HTTPS site. In addition, you should be comfortable adjusting the server configuration of this site.
In DevTools, locate the Certificate URL indicated in the Signature of the SXG. Copy the hash that is located at the end of this string.
This hash is an identifier that corresponds to the certificate. If you were to regenerate the SXG using a different certificate, the Certificate URL listed in the Signature would be different.
Create a copy of
cert.pem. The filename of the new version should match the hash you just copied—for example,
cp cert.pem dKqTlYij_pSjvADDzlMTv4MBF6lUcGR2vaY1ZbfNKww
Upload the renamed certificate to your site. The particular directory that you upload the certificate to does not matter.
webpkgserver.toml with the editor of your choice and make the following changes:
#CertURLBase = '/webpkg/cert'to match the deployed location of your certificate. For most people, this location will be similar to
https://mysite.com/. If you get the error
CertURLBase: must be set non-emptyafter starting
webpkgserver, try adding a
/at the end of the URL.
#CertPath = '/webpkg/cert'to match the deployed location of your certificate. For example, if the certificate will be served from your root directory, change this value to
The Network panel shows that the SXG and its certificate were loaded with no errors.
The instructions in this section explain how to serve SXGs using a
CanSignHttpExchanges certificate. Production use of SXGs requires a
These instructions are fairly similar to those for serving SXGs with a self-signed certificate. For the sake of brevity, these instructions are written with the assumption that you understand the concepts discussed in the Setup Signed Exchanges using a self-signed certificate section.
You have a
CanSignHttpExchanges certificate. This page lists the CAs that offer this type of certificate.
go get -v -u github.com/WICG/webpackage/go/signedexchange/cmd/gen-certurl
gen-certurl is a tool that converts certificates to the certificate format used by signed exchanges.
gen-certurl has been installed correctly.
This command should return information about its usage.
Follow the steps 1 through 3 of Generate a self-signed certificate.
cert.pem to the
gen-certurl -pem cert.pem -ocsp <(echo ocsp) > cert.cbor
Certificates come in many formats.
cert.pem is in the PEM format. Certificates for signed exchanges must be in the
When using a self-signed certificate,
webpkgserver automatically converts the certificate indicated by the
PEMFile option in
webpkgserver.toml to the
application/cert-chain+cbor format. However, if you are using a
CanSignHttpExchanges certificate, you must generate the CBOR-encoded certificate yourself.
Follow steps 1 and 2 of Setup the Web Packager Server for testing.
webpkgserver.toml with the editor of your choice and make the following changes:
PEMFile = cert.pemto
PEMFile = cert.cbor.
Follow steps 1 through 4 of Upload the self-signed certificate to upload
Adjust your server config to serve
cert.cbor using the
Content-Type: application/cert-chain+cbor response header.
If this header is not set, you will see the following error when you inspect the SXG in DevTools:
Content type of cert-url must be application/cert-chain+cbor. Actual content type: text/html.