Staging endpoint for ACME v2

We’re happy to announce that our ACME v2 staging endpoint is now available for public testing. You can begin testing ACME v2 support for your client using the following directory URL:

https://acme-staging-v02.api.letsencrypt.org/directory

Remember that since the staging environment root certificate is not present in browser/client trust stores this endpoint is inappropriate for production use. A production ready v2 API endpoint will be available February 27th.

Edit 2018-03-13: The production ACME v2 environment is now available: ACME v2 Production Envrionment & Wildcards

We look forward to working with ACME client developers to prepare for ACME v2 and wildcard issuance ahead of our full launch.

Edit: We’re collecting reported bugs/known issues in this forum thread

Background

Let’s Encrypt and the ACME standard have evolved side-by-side since our launch. As the draft has moved through the IETF standardization process we accumulated a number of divergences where the specification changed in non-backwards-compatible ways. Now that the draft standard is in last-call and the pace of major changes has slowed, we’re able to release a “v2” API that is much closer to what will become the final ACME RFC. We may plan to sunset the v1 API at some point in the future, but have not set a date. We will give plenty of advance warning to clients and integrators for any such plan.

Existing Accounts

Existing ACME accounts from the v1 API will work with the v2 API. Existing authorizations from the v1 API will not be usable with the v2 API, meaning that you will have to reauthorize all domains prior to issuance with the v2 API (note: this is not currently implemented in the staging API, so you may see some reuse there).

Rate limits

The existing staging environment rate limits still apply for the V2 API. There’s one new rate limit, Pending Orders Per Account. One ACME account can have no more than 300 pending orders outstanding at a time.

Client compatibility

This is a non-backward-compatible version of the API, so ACME v1 clients (almost all clients available today) will not work with the ACME v2 endpoint. Existing clients will need code changes and new releases in order to support ACME v2.

Certbot is not yet ACME v2 compatible. We expect Certbot to support ACME v2 by February 27. To date, only
ACME4J
has implemented ACME v2. Please start a new thread in the “client dev” category on the forum to let us know if your ACME client has added v2 support! We will soon start marking ACME v2 compatible clients in our list of available ACME clients.

If you use an ACME v1 client with the ACME v2 API you will likely receive errors about an incompatible /directory response, perhaps mentioning missing endpoints (new-reg, new-authz, etc). To reiterate, ACME v1 clients will not work with ACME v2 without code changes.

Wildcard certificates

The V2 API supports issuing wildcard certificates. To request a wildcard certificate simply send a wildcard DNS identifier in the newOrder request. Wildcard identifiers may only be authorized by DNS-01 challenge, so order authorizations corresponding to wildcard identifiers will only include a pending DNS-01 challenge. DNS names in certificates may only have a single wildcard character, and it must be the entire leftmost DNS label, for instance “*.example.com”. A single certificate can have wildcard DNS identifiers for multiple base domains.

v2 vs v1

ACME v2 has a number of differences from the v1 API based on earlier drafts. Here are a few of the high level changes we want to draw client developer attention to:

  1. The authorization/issuance flow has changed.
  2. JWS request authorization has changed.
  3. The "resource" field of JWS request bodies is replaced by a new JWS header: “url”.
  4. Directory endpoint/resource renaming.
  5. URI -> URL renaming in challenge resources.
  6. Account creation and ToS agreement are one step instead of two.
  7. There is a new challenge type, TLS-SNI-02, and TLS-SNI-01 has been removed (to be implemented).

Previously clients requested individual authorizations per-identifier using the new-authz endpoint, satisfied challenges associated with those authorizations, and then submitted a CSR to the new-cert. With the V2 API clients will create a new-order for a number of identifiers, receive authorizations in the order response, satisfy challenges associated with those authorizations, and then finalize the order by sending a CSR to its finalization URI.

In ACME all POST requests are authenticated by a JWS signature. In ACME v1, the key to verify that signature with was included in the JWS headers. In ACME v2 only the newAccount and revokeCert endpoints follow this pattern. All other endpoints expect a JWS “kid” (key ID) header, with the contents of the header set to the account URL authorizing the request.

ACME v2 also replaces the resource field from JWS request bodies. Previously clients would include the resource name they intended to POST to in the JWS body’s “resource” field to ensure the signed body couldn’t be used for a different resource/endpoint. In ACME v2 clients now include the URL they are POSTing as a JWS protected header.

ACME v2 applies a consistent "camelCase" for all field names. This means ACME v1 directory entries like revoke-cert and new-account are now revokeCert and newAccount.

In ACME v2, clients are expected to fetch the Terms of Service before creating an account, and simply set the termsOfServiceAgreed field to true in their newAccount field. The Terms of Service (aka Subscriber Agreement) can be found in the “termsOfService” field in the “meta” section of the directory object. Note that Boulder currently has a non-standard /terms URL. In the v1 API, we will keep this for backwards compatibility but in v2 we will remove it shortly.

There’s also a new challenge type, TLS-SNI-02. This is very similar to TLS-SNI-01, but computes different values for the challenge certificate to reduce implementation errors for clients. Our plan is to offer only TLS-SNI-02 in ACME v2, but as of today, our ACME v2 endpoint offers TLS-SNI-01 and not TLS-SNI-02.

There are a number of other changes that have been made and we encourage developers to read the most  ACME draft, ACME Draft-09 for full details.

Testing

As always, you are welcome to use Boulder for your integration tests. However, new for ACME v2, we have developed a smaller standalone ACME server called Pebble. Pebble is specifically designed for integration testing, and is easier to set up than Boulder. We are also happy to accept pull requests to Pebble that add hooks for testing purposes, for instance adding hooks to trigger certain errors or delays on demand. Please try it out for your ACME v2 testing!

28 Likes

The production endpoint is now available: ACME v2 Production Envrionment & Wildcards

6 Likes