boulder

Boulder is an implementation of an ACME-based certificate authority (CA), and it is the software that runs Let's Encrypt. The ACME protocol lets a CA automatically verify that a certificate applicant actually controls an identifier, and lets subscribers issue and revoke certificates for identifiers they control. Architecture Boulder is split into components separated by security context: - Web Front Ends (one per API version) - Registration Authority - Validation Authority - Certificate Authority - Storage Authority - Publisher - CRL Updater The Web Front End, Validation Authority, CRL Storer and Publisher need Internet access and are therefore at greater risk of compromise. The Registration Authority can operate without Internet connectivity but talks to the Web Front End and Validation Authority. The Certificate Authority only receives instructions from the Registration Authority. All components use the Storage Authority for persistence, which is backed by MariaDB. Components communicate over gRPC; remote components are instantiated as client/server pairs, where the client implements the component's Go interface and the server holds the actual logic. Internally the system is organized around five object types that map directly to ACME resources: accounts, authorizations, challenges, orders and certificates. Requests from ACME clients create new objects and modify existing ones, and the Storage Authority keeps persistent copies of the current object set. Development setup Boulder ships a Dockerfile and uses Docker Compose to install and configure all dependencies. This is the maintainers' recommended way to run it for development and experimentation, and it is explicitly not suitable as a production environment. The project suggests Pebble, a miniature version of Boulder, for continuous integration and quick experimentation by ACME client developers. Typical workflow: - Clone the repository and ensure Docker Engine 1.13.0+ and Docker Compose 1.10.0+ are installed; at least 2GB of RAM is recommended for the Docker host. - Run ./t.sh for the standard battery of lints, unit and integration tests; ./t.sh -u for unit tests, ./t.sh -i for integration tests, and ./tn.sh for the "config-next" configuration representing a likely future state. - Run docker compose run bsetup once to write certificates into test/certs, then docker compose up to start Boulder. - The docker-compose.yml mounts the checkout at /boulder so host edits are reflected immediately in containers. By default Boulder uses a fake DNS resolver that resolves all hostnames to 127.0.0.1, which suits integration tests inside the container. To let a host-based client communicate with Boulder, find the host's Docker IP and set the FAKE_DNS environment variable accordingly; the stubbed resolver (sd-test-srv) then answers all A queries with that address. Host-based firewalls must allow connections from the Docker instance to the host on the required validation ports. Working with ACME clients With the development environment running, ACME endpoints are exposed to the host at http://localhost:4001/directory (ACME v2, HTTP) and https://localhost:4431/directory (ACME v2, HTTPS). Using the HTTPS endpoints requires configuring the client with a truststore containing the test/certs/ipki/minica.pem CA certificate. Because the fake resolver returns 127.0.0.1 for any query, certificates can be issued for any domain as if it resolved to localhost; changing FAKE_DNS changes the returned address, and it is often set to the host machine running the ACME client. The README shows running Certbot against a local Boulder with a custom SERVER environment variable and the --standalone option. Production notes The project states that Boulder is custom built for Let's Encrypt and intended only to support the Web PKI and the CA/Browser Forum baseline requirements. It notes that Boulder is often not the right fit for organizations evaluating it for production, and that a centrally managed PKI without ACME domain authorization is usually a better choice. A deployment and implementation guide is offered describing required work and security considerations. The Docker-based development environment is explicitly not suitable for production: it uses publicly available private key material, exposes debug ports and is brittle to component failure. Support and development prioritize Let's Encrypt's mission, so timely support or pull requests that deviate significantly from first-line goals may not be accepted. Contributing and license Contribution guidelines, code review process, code of conduct and other tips are in CONTRIBUTING.md; the community code of conduct is referenced on the Let's Encrypt community forum. The project is licensed under the Mozilla Public License 2.0.