We’re pleased to announce that ACMEv2 and wildcard certificate support is live! With today’s new features we’re continuing to break down barriers for HTTPS adoption across the Web by making it even easier for every website to get and manage certificates.
ACMEv2903 is an updated version of our ACME protocol which has gone through the IETF standards process, taking into account feedback from industry experts and other organizations that might want to use the ACME protocol for certificate issuance and management some day.
Wildcard certificates1.1k allow you to secure all subdomains of a domain with a single certificate. Wildcard certificates can make certificate management easier in some cases, and we want to address those cases in order to help get the Web to 100% HTTPS. We still recommend non-wildcard certificates for most use cases.
Wildcard certificates are only available via ACMEv2. In order to use ACMEv2 for wildcard or non-wildcard certificates you’ll need a client that has been updated to support ACMEv22.3k. It is our intent to transition all clients and subscribers to ACMEv2, though we have not set an end-of-life date for our ACMEv1 API yet.
Additionally, wildcard domains must be validated using the DNS-01 challenge type. This means that you’ll need to modify DNS TXT records in order to demonstrate control over a domain for the purpose of obtaining a wildcard certificate.
See our previous announcement40 about the availability of ACME v2 in the staging environment for more information on ACME v2.
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.
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).
The existing rate limits25 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 environment40 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.
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.com8”, 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.
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.
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-request18 to update the “ACME v2 Compatible Clients” section of the Client Options documentation if you add support to your ACME client!
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-1011) 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 333512.
The “ready” state on order objects is not implemented. Orders remain “pending” when associated authorizations are all valid and finalization may occur. Client developers should check the authorization statuses to determine if the order is ready. Please follow Boulder Issue 35307.
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 announcement47 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.