README
¶
Test keys and certificates
Dynamically-Generated PKIs
This directory contains scripts and programs which generate PKIs (collections of keys and certificates) for use in our integration tests. Each PKI has its own subdirectory. The scripts do not regenerate a directory if it already exists, to allow the generated files to be re-used across many runs on a developer's machine. To force the scripts to regenerate a PKI, simply delete its whole directory.
This script is invoked automatically by the bsetup container in our docker
compose system. It is invoked automatically by t.sh and tn.sh. If you want
to run it manually, the expected way to do so is:
$ docker compose up bsetup
[+] Running 0/1
Attaching to bsetup-1
bsetup-1 | Generating ipki/...
bsetup-1 | Generating webpki/...
bsetup-1 exited with code 0
To add new certificates to an existing PKI, edit the script which generates that
PKI's subdirectory. To add a whole new PKI, create a new generation script,
execute that script from this directory's top-level generate.sh, and add the
new subdirectory to this directory's .gitignore file.
webpki
The "webpki" PKI emulates our publicly-trusted hierarchy. It consists of RSA and
ECDSA roots, several intermediates and cross-signed intermediates, and CRLs.
These certificates and their keys are generated using the ceremony tool. The
private keys are stored in SoftHSM in the .softhsm-tokens subdirectory.
This PKI is loaded by the CA, RA, and other components. It is used as the issuance hierarchy for all end-entity certificates issued as part of the integration tests.
ipki
The "ipki" PKI emulates our internal PKI that the various Boulder services use to authenticate each other when establishing gRPC connections. It includes one certificate for each service which participates in our gRPC cluster. Some of these certificates (for the services that we run multiple copies of) have multiple names, so the same certificate can be loaded by each copy of that service.
It also contains some non-gRPC certificates which are nonetheless serving the role of internal authentication between Let's Encrypt components:
- The IP-address certificate used by challtestsrv (which acts as the integration test environment's recursive resolver) for DoH handshakes.
- The certificate presented by mail-test-srv's SMTP endpoint.
- The certificate presented by the test redis cluster.
- The certificate presented by the WFE's API TLS handler (which is usually behind some other load-balancer like nginx).
This PKI is loaded by virtually every Boulder component.
Note: the minica issuer certificate and the "localhost" end-entity certificate are also used by several rocsp and ratelimit unit tests. The tests use these certificates to authenticate to the docker-compose redis cluster, and therefore cannot succeed outside of the docker environment anyway, so a dependency on the ipki hierarchy having been generated does not break them further.
Other Test PKIs
A variety of other PKIs (collections of keys and certificates) exist in this repository for the sake of unit and integration testing. We list them here as a TODO-list of PKIs to remove and clean up:
- unit test hierarchy: the //test/hierarchy/ directory holds a collection of certificates used by unit tests which want access to realistic issuer certs but don't want to rely on the //test/certs/webpki directory being generated. These should be replaced by certs which the unit tests dynamically generate in-memory, rather than loading from disk.
- unit test mocks: //test/test-key-5.der and //wfe2/wfe_test.go contain keys and certificates which are used to elicit specific behavior from //mocks/mocks.go. These should be replaced with dynamically-generated keys and more flexible mocks.
Documentation
Source Files