Boulder - An ACME CA
This is an initial implementation of an ACME-based CA. The ACME protocol allows the CA to automatically verify that an applicant for a certificate actually controls an identifier, and allows domain holders to issue and revoke certificates for their domains.
Boulder is available as a Docker image from Quay.io. The Docker image expects the
config.json file to be located at
/boulder/config.json within the container.
(Note: You can override the
config.json location by specifying a different BOULDER_CONFIG environment variable, such as with
There are no default commands; you must choose one of the executables from the
There are several tags available:
stableis maintained by the Let's Encrypt team as a fairly stable copy of Boulder.
latestis a more recent build of Boulder. It may lag behind the
masterref, as automated builds are being reworked.
- Tags for individual short-format git refs, representing those builds.
A quick-start method for running a Boulder instance is to use one of the example configurations:
> mkdir .boulder-config > cp test/example-config.json .boulder-config/config.json > docker run --name=boulder --read-only=true --rm=true -v $(pwd)/.boulder-config:/boulder:ro -p 4000:4000 quay.io/letsencrypt/boulder:latest boulder
To run a single module, specifying the AMQP server, you might use something more like:
> docker run --name=boulder --read-only=true --rm=true -v $(pwd)/.boulder-config:/boulder:ro quay.io/letsencrypt/boulder:stable boulder-ra
Install RabbitMQ from https://rabbitmq.com/download.html. It's required to run tests.
> go get github.com/letsencrypt/boulder # Ignore errors about no buildable files > cd $GOPATH/src/github.com/letsencrypt/boulder # This starts each Boulder component with test configs. Ctrl-C kills all. > python ./start.py > cd test/js > npm install > nodejs test.js > ./test.sh
You can also check out the official client from https://github.com/letsencrypt/lets-encrypt-preview/ and follow the setup instructions there.
The CA is divided into the following main components:
- Web Front End
- Registration Authority
- Validation Authority
- Certificate Authority
- Storage Authority
This component model lets us separate the function of the CA by security context. The Web Front End and Validation Authority need access to the Internet, which puts them at greater risk of compromise. The Registration Authority can live without Internet connectivity, but still needs to talk to the Web Front End and Validation Authority. The Certificate Authority need only receive instructions from the Registration Authority.
client <--ACME--> WFE ---+ . | . +--- RA --- CA . | client <-checks-> VA ---+
In Boulder, these components are represented by Go interfaces. This allows us to have two operational modes: Consolidated and distributed. In consolidated mode, the objects representing the different components interact directly, through function calls. In distributed mode, each component runs in a separate process (possibly on a separate machine), and sees the other components' methods by way of a messaging layer.
Internally, the logic of the system is based around two types of objects, authorizations and certificates, mapping directly to the resources of the same name in ACME.
Requests from ACME clients result in new objects and changes to objects. The Storage Authority maintains persistent copies of the current set of objects.
Objects are also passed from one component to another on change events. For example, when a client provides a successful response to a validation challenge, it results in a change to the corresponding validation object. The Validation Authority forward the new validation object to the Storage Authority for storage, and to the Registration Authority for any updates to a related Authorization object.
Boulder supports distributed operation using AMQP as a message bus (e.g., via RabbitMQ). For components that you want to be remote, it is necessary to instantiate a "client" and "server" for that component. The client implements the component's Go interface, while the server has the actual logic for the component. More details in
The full details of how the various ACME operations happen in Boulder are laid out in DESIGN.md
# Disable insecure fallback by blocking port 80. sudo /sbin/iptables -A OUTPUT -p tcp --dport 80 -j DROP # Update to the latest version of a dependency. Alternately you can cd to the # directory under GOPATH and check out a specific revision. go get -u github.com/cloudflare/cfssl/... # Update the Godep config to the appropriate version. godep update github.com/cloudflare/cfssl/... # Save the dependencies, rewriting any internal or external dependencies that # may have been added. godep save -r ./... git add Godeps git commit # Assuming you had no other iptables rules, re-enable port 80. sudo iptables -D OUTPUT 1
See the issues list