letsencrypt/test-certs-siteA simple server to host the valid, revoked, and expired certificates required by Section 2.2 of the CA/Browser Forum Baseline Requirements.
This is a purpose-built webserver for hosting the test pages required by the CA/Browser forum Baseline Requirements. They contain the following requirement:
The CA SHALL host test Web pages that allow Application Software Suppliers to test their software with Subscriber Certificates that chain up to each publicly trusted Root Certificate. At a minimum, the CA SHALL host separate Web pages using Subscriber Certificates that are valid, revoked, and expired.
It uses the ACME protocol to obtain certificates. It serves a simple website with some information explaining what the test site is for.
From the CA/Browser Forum TLS Baseline Requirements:
While this was built for Let's Encrypt, it should be usable by other ACME CAs.
This is a standalone Go program.
go run main.go -config [path/to/config.json]
See config/config.go for the configuration schema and
config/testdata/test.json for an example of a valid configuration. The
integration test config is generated at runtime by integration/configgen.
We provide a docker-compose.yml file for local testing. It will automatically
deploy Pebble, a test CA. Execute:
docker compose up --build
Then, access one of the test sites.
They are available on:
These URLs may work immediately, but if they don't resolve on your system, you can get curl to resolve them:
curl -k --resolve revoked.localhost:5001:127.0.0.1 'https://revoked.localhost:5001/'
If you want to access the sites from your browser, edit your /etc/hosts file to
include the test certs addresses.
127.0.0.1 valid.localhost revoked.localhost expired.localhost
This software was inspired by several incidents we observed from other CAs, as well as the complexity of our existing solution using off-the-shelf tools.
Some categories of incidents we've observed include:
A server with ACME integration is the most reliable way to ensure certificates are kept up-to-date, but the unusual requirements of serving revoked and expired certificates is not a typical feature of other systems. Monitoring systems also don't typically support ensuring that certificates are revoked or expired.
Currently, test-certs-site only supports the TLS-ALPN-01 validation method. To fulfil this challenge, and to serve the test sites, this program listens on a configurable port, which should be exposed as the TLS port, :443.
Note that in the test configuration listens on :5001 by default, which matches Pebble's default validation port.
Currently, test-certs-site stores all key material as paths on disk. To ease running cert-test-program in cloud or ephemeral environments, we will want to support some mechanism for persisting keys to secrets management.
Other than the key and certificate storage, this program is stateless.
There is a configurable debug listener which exposes /debug/pprof and /metrics. Logs are printed in JSON to stderr.