Today we’re happy to announce the availability of our ACME v2 production endpoint. This is a technical post with some details about the v2 API intended for ACME client developers.
End users can begin issuing trusted, production ready certificates with their ACME v2 compatible clients using the following directory URL:
https://acme-v02.api.letsencrypt.org/directory
Remember: You must use an ACME v2 compatible client to access this endpoint. Please consult our list of ACME v2 compatible clients.
Background
See our previous announcement about the availability of ACME v2 in the staging environment for more information on ACME v2.
Existing Accounts
Existing ACME accounts from the production V1 API will work with the production V2 API. Authorizations held by a V1 account will not be usable in the V2 environment - you must revalidate your domains for use with ACME v2. Similar to ACMEv1, accounts from the V1 or V2 staging environment will not work in the production environment.
Enumerable Orders
ACME v2 order objects are available under predictable sequential ID numbers. This is a difference compared to ACMEv1 that favours transparency but may surprise some users. Previously it was difficult to predict an Authorization’s ID. Sequential order IDs make associated Authorization IDs public and may reveal information related to domain validation attempts (resolved IP addresses, validation error messages).
Rate Limits
The existing rate limits continue to apply to the V2 API. One new rate limit is introduced: New Orders per Account. For the production ACME v2 endpoint one account may not exceed 300 new orders per 3 hours. The staging environment maintains a higher rate limit and we encourage you to perform testing in this environment instead of production. Also note that the Pending Authorization limit is still in effect, and one order may create multiple pending authorizations. So depending on your issuance pattern, you may hit the Pending Authorization limit before you hit the New Order limit.
Wildcard certificates
The V2 API supports issuing wildcard certificates. To request a wildcard certificate simply send a wildcard DNS identifier in the newOrder request. Under Let’s Encrypt’s policy, wildcard identifiers must be validated by a DNS-01 challenge, so order authorizations corresponding to wildcard identifiers will only offer a 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 names for multiple base domains, and can also mix in non-wildcard names.
Orders that contain both a base domain and its wildcard equivalent (e.g. *.example.com and example.com) are valid. In that case, there will be two authorization objects in the order for “example.com”, one of which represents the wildcard validation and one of which represents the base domain validation. Redundant entries will produce an error. For instance, and order containing both *.example.com and www.example.com would produce an error since the wildcard entry makes the latter redundant.
Client Compatibility
This is a non-backward-compatible version of the API, so ACME v1 clients will not work with the ACME v2 endpoint without explicit support. Existing clients will need code changes and new releases in order to support ACME v2.
We are maintaining a list of clients that have added ACME v2 support on our client options documentation page.
Certbot has ACME v2 support since Version 0.22.0. This version may not yet be available depending on how you install Certbot and your system’s software update mechanism.
Please submit a Website pull-request to update the “ACME v2 Compatible Clients” section of the Client Options documentation if you add support to your ACME client!
Specification Divergences
ACME is not yet a final RFC. The draft protocol has continued to evolve alongside our updated implementation. Naturally this has led to some late changes introducing some mild protocol divergences between what Let’s Encrypt does and what the latest draft (acme-draft-10) says.
Presently the following protocol features are not implemented:
- Pre-authorization. This is an optional feature and we have no plans to implement it. V2 clients should use order based issuance without pre-authorization…
- The “orders” field on account objects. We intend to support this non-essential feature in the near future. Please follow Boulder Issue 3335.
Breaking Changes
There is one breaking API change that we have scheduled to remove a protocol divergence introduced recently. By Thursday, March 29th, 2018 all ACME v2 clients will be required to send a Content-Type header with the value application/jose+json for all JWS authenticated POST requests. Please see our API announcement for more information.
We intend to make our v2 endpoint implement the final ACME RFC, so there may be some further small changes, which we will pre-announce in the same API Announcements category as this post. We aim to keep these changes to a minimum.
Thanks everyone,