github.com/letsencrypt/boulder@v0.20251208.0/test/certs/README.md (about)

     1  # Test keys and certificates
     2  
     3  ## Dynamically-Generated PKIs
     4  
     5  This directory contains scripts and programs which generate PKIs (collections of
     6  keys and certificates) for use in our integration tests. Each PKI has its own
     7  subdirectory. The scripts do not regenerate a directory if it already exists, to
     8  allow the generated files to be re-used across many runs on a developer's
     9  machine. To force the scripts to regenerate a PKI, simply delete its whole
    10  directory.
    11  
    12  This script is invoked automatically by the `bsetup` container in our docker
    13  compose system. It is invoked automatically by `t.sh` and `tn.sh`. If you want
    14  to run it manually, the expected way to do so is:
    15  
    16  ```sh
    17  $ docker compose up bsetup
    18  [+] Running 0/1
    19  Attaching to bsetup-1
    20  bsetup-1  | Generating ipki/...
    21  bsetup-1  | Generating webpki/...
    22  bsetup-1 exited with code 0
    23  ```
    24  
    25  To add new certificates to an existing PKI, edit the script which generates that
    26  PKI's subdirectory. To add a whole new PKI, create a new generation script,
    27  execute that script from this directory's top-level `generate.sh`, and add the
    28  new subdirectory to this directory's `.gitignore` file.
    29  
    30  ### webpki
    31  
    32  The "webpki" PKI emulates our publicly-trusted hierarchy. It consists of RSA and
    33  ECDSA roots, several intermediates and cross-signed intermediates, and CRLs.
    34  These certificates and their keys are generated using the `ceremony` tool. The
    35  private keys are stored in SoftHSM in the `.softhsm-tokens` subdirectory.
    36  
    37  This PKI is loaded by the CA, RA, and other components. It is used as the
    38  issuance hierarchy for all end-entity certificates issued as part of the
    39  integration tests.
    40  
    41  ### ipki
    42  
    43  The "ipki" PKI emulates our internal PKI that the various Boulder services use
    44  to authenticate each other when establishing gRPC connections. It includes one
    45  certificate for each service which participates in our gRPC cluster. Some of
    46  these certificates (for the services that we run multiple copies of) have
    47  multiple names, so the same certificate can be loaded by each copy of that
    48  service.
    49  
    50  It also contains some non-gRPC certificates which are nonetheless serving the
    51  role of internal authentication between Let's Encrypt components:
    52  
    53  - The IP-address certificate used by challtestsrv (which acts as the integration
    54    test environment's recursive resolver) for DoH handshakes.
    55  - The certificate presented by the test redis cluster.
    56  - The certificate presented by the WFE's API TLS handler (which is usually
    57    behind some other load-balancer like nginx).
    58  
    59  This PKI is loaded by virtually every Boulder component.
    60  
    61  **Note:** the minica issuer certificate and the "localhost" end-entity
    62  certificate are also used by several ratelimit unit tests. The tests
    63  use these certificates to authenticate to the docker-compose redis cluster, and
    64  therefore cannot succeed outside of the docker environment anyway, so a
    65  dependency on the ipki hierarchy having been generated does not break them
    66  further.
    67  
    68  ## Other Test PKIs
    69  
    70  A variety of other PKIs (collections of keys and certificates) exist in this
    71  repository for the sake of unit and integration testing. We list them here as a
    72  TODO-list of PKIs to remove and clean up:
    73  
    74  - unit test hierarchy: the //test/hierarchy/ directory holds a collection of
    75    certificates used by unit tests which want access to realistic issuer certs
    76    but don't want to rely on the //test/certs/webpki directory being generated.
    77    These should be replaced by certs which the unit tests dynamically generate
    78    in-memory, rather than loading from disk.
    79  - unit test mocks: //test/test-key-5.der and //wfe2/wfe_test.go contain keys and
    80    certificates which are used to elicit specific behavior from //mocks/mocks.go.
    81    These should be replaced with dynamically-generated keys and more flexible
    82    mocks.