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.

Docker

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 -e BOULDER_CONFIG=mypath/myfile.config.)

The default command is the monolithic "boulder" executable, which does not require an AMQP service.

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:latest boulder-ra

The submodules are under the cmd/ directory.

Quickstart

> go get github.com/letsencrypt/boulder # Ignore errors about no buildable files
> cd $GOPATH/src/github.com/letsencrypt/boulder
# This starts both Boulder and cfssl with test configs. Ctrl-C kills both.
> ./start.sh
> cd test/js
> npm install
> nodejs test.js

You can also check out the official client from https://github.com/letsencrypt/lets-encrypt-preview/ and follow the setup instructions there.

Component Model

The CA is divided into the following main components:

1. Web Front End
2. Registration Authority
3. Validation Authority
4. Certificate Authority
5. 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 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 amqp-rpc.go.

Files

• interfaces.go - Interfaces to the components, implemented in:
  • web-front-end.go
  • registration-authority.go
  • validation-authority.go
  • certificate-authority.go
  • storage-authority.go
• amqp-rpc.go - A lightweight RPC framework overlaid on AMQP
  • rpc-wrappers.go - RPC wrappers for the various component type
• objects.go - Objects that are passed between components
• util.go - Miscellaneous utility methods
• boulder_test.go - Unit tests

Dependencies:

All dependencies are vendorized under the Godeps directory, both to make dependency management easier and to avoid insecure fallback in go get. To update dependencies:

# 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

ACME Processing

Client -> WebFE:  challengeRequest
WebFE -> RA:      NewAuthorization(AuthorizationRequest)
RA -> RA:         [ select challenges ]
RA -> RA:         [ create Validations with challenges ]
RA -> RA:         [ create Authorization with Validations ]
RA -> SA:         Update(Authorization.ID, Authorization)
RA -> WebFE:      Authorization
WebFE -> WebFE:   [ create challenge from Authorization ]
WebFE -> WebFE:   [ generate nonce and add ]
WebFE -> Client:  challenge

----------

Client -> WebFE:  authorizationRequest
WebFE -> WebFE:   [ look up authorization based on nonce ]
WebFE -> WebFE:   [ verify authorization signature ]
WebFE -> RA:      UpdateAuthorization(Authorization)
RA -> RA:         [ add responses to authorization ]
RA -> SA:         Update(Authorization.ID, Authorization)
RA -> VA:         UpdateValidations(Authorization)
WebFE -> Client:  defer(authorizationID)

VA -> SA:         Update(Authorization.ID, Authorization)
VA -> RA:         OnValidationUpdate(Authorization)
RA -> RA:         [ check that validation sufficient ]
RA -> RA:         [ finalize authorization ]
RA -> SA:         Update(Authorization.ID, Authorization)
RA -> WebFE:      OnAuthorizationUpdate(Authorization)
Client -> WebFE:  statusRequest
WebFE -> Client:  error / authorization

----------

Client -> WebFE:  certificateRequest
WebFE -> WebFE:   [ verify authorization signature ]
WebFE -> RA:      NewCertificate(CertificateRequest)
RA -> RA:         [ verify CSR signature ]
RA -> RA:         [ verify authorization to issue ]
RA -> RA:         [ select CA based on issuer ]
RA -> CA:         IssueCertificate(CertificateRequest)
CA -> RA:         Certificate
RA -> CA:         [ look up ancillary data ]
RA -> WebFE:      AcmeCertificate
WebFE -> Client:  certificate

----------

Client -> WebFE:  revocationRequest
WebFE -> WebFE:   [ verify authorization signature ]
WebFE -> RA:      RevokeCertificate(RevocationRequest)
RA -> RA:         [ verify authorization ]
RA -> CA:         RevokeCertificate(Certificate)
CA -> RA:         RevocationResult
RA -> WebFE:      RevocationResult
WebFE -> Client:  revocation

TODO

• Ensure that distributed mode works with multiple processes
• Add message signing and verification to the AMQP message layer
• Add monitoring / syslog
• Factor out policy layer (e.g., selection of challenges)
• Add persistent storage