]> Internet Security Research Group

aaron@letsencrypt.org

Security Automated Certificate Management Environment This document defines how an ACME Server may offer a selection of different certificate profiles to ACME Clients, and how those clients may indicate which profile they want. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Automated Certificate Management Environment Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at . Current Implementations This note is to be removed before publishing as an RFC. This document is implemented by at least two ACME Servers (Boulder and Pebble), and at least seven ACME Clients (Certbot, Lego, eggsampler/acme, caddy, certifytheweb, poshacme, and dehydrated). It is deployed by the Let's Encrypt CA, and is being actively used to manage migrations away from the tlsClientAuth EKU and towards shorter-lived certificates.

Introduction Throughout the history of the WebPKI, Certificate Authorities have used "profiles" to describe the kinds of certificates they issue. For example, an "S/MIME" profile might indicate that the resulting certificate will contain the id-kp-emailProtection Extended Key Usage and use a Certificate Policy OID to assert compliance with the CA/Browser Forum S/MIME Baseline Requirements; or a "Constrained Sub-CA" profile might indicate the inclusion of the Basic Constraints extension, the keyCertSign Key Usage, and a Name Constraints extension. Subscribers generally select a profile as part of their certificate ordering process or negotiations with the CA, depending on their needs (and sometimes their budget). The ACME protocol only allows clients to customize their certificate in two ways: the newOrder request allows selection of the identifiers (generally Subject Alternative Names) and validity period; and the finalize request contains a CSR in which the client can theoretically include any combination of fields and extensions that they desire. But requesting certificate features via the CSR is onerous, error-prone, and dangerous. Numerous compliance incidents across the WebPKI have been caused by CAs trusting values included in a CSR and copying them directly into the issued certificate. It requires clients to know how to construct a valid CSR, provides no mechanism for servers to advertise what CSR fields they're willing to accept, and means that CAs have to evaluate on a case-by-case basis which combinations of requested features they're willing to issue. This document provides a mechanism for ACME Servers to advertise what certificate profiles they offer, and for ACME Clients to select a profile when creating a new Order. This allows site operators to make informed decisions about the kind of certificate they request, without placing an undue burden on ACME Clients or Servers to transmit such information in the form of a CSR. It also encourages the evolution of the WebPKI by allowing CAs to more easily offer new and improved profiles while maintaining backwards compatibility for old subscribers.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Extensions to the Directory Resource An ACME Server which wishes to allow Clients to select profiles MUST include a new field, profiles, in the meta field of its Directory object. profiles (optional, object): A map of profile names to URLs. Each profile name is a short unique identifier of the profile, and each URL points to a human-readable description of that profile. CAs MAY use data URIs to provide an in-line text description if they do not wish to host external documentation pages. ACME Clients SHOULD present these profile names and URLs to their operator during initial setup and at appropriate times thereafter.

Extensions to the Order Resource In order to convey information about the profile associated with an Order, a new field is added to the Order object: profile (string, optional): A string uniquely identifying the profile which will be used to affect issuance of the certificate requested by this Order. To select a profile, the client includes the desired profile name in the profile field of the Order object they supply to the newOrder request. The client SHOULD NOT request a profile name that is not advertised in the server's Directory metadata object. The server MUST reject all newOrder requests which specify a profile that is incompatible with the rest of the contents of the request (e.g. a "tls-server-auth" profile alongside an identifier of type "email", or a "super-special" profile requested by an account which is not on the appropriate allowlist). In such cases, the server MUST respond with a problem document of type "invalidProfile" (see Section 6.3). The server SHOULD reject all newOrder requests which specify a profile that the server is not advertising, but MAY accept them in extenuating circumstances. For example, when a private profile name has been agreed upon with the client via out-of-band mechanisms, or when replacing a certificate during a mass revocation event that was originally issued under a now-deprecated profile. If it accepts the request, the server responds with an Order object including the selected profile. ;rel="index" Location: https://acme.example.com/order/TOlocE8rfgo { "status": "valid", "expires": "2025-01-01T12:00:00Z", "identifiers": [{"type": "dns", "value": "example.org"}], "profile": "profile1", "authorizations": ["https://acme.example.com/authz/PAniVnsZcis"], "finalize": "https://acme.example.com/order/TOlocE8rfgo/finalize", } ]]> If the server is advertizing profiles and receives a newOrder request which does not identify a specific profile, it is RECOMMENDED that the server select a profile and associate it with the new Order object. If a server receives a request to finalize an Order whose profile the CA is no longer willing to issue under, it MUST respond with a problem document of type "invalidProfile". The server SHOULD attempt to avoid this situation, e.g. by ensuring that all Orders for a profile have expired before it stops issuing under that profile.

Security Considerations The extensions to the ACME protocol described in this document build upon the Security Considerations and threat model defined in . It does not change the account management or identifier validation flows, so the security considerations are largely unchanged. The one exception is in regards to CA Policy Considerations. RFC 8555 did not address how a server should determine whether it is willing to issue the certificate as requested by the finalize CSR. This document greatly simplifies this determination by making the contents of the CSR (beyond the Subject Alternative Names and Subject Public Key) irrelevant to the decision-making process. Additionally, by moving profile selection out of the finalize CSR and into the Order resource itself, this document reduces the need for ACME Clients and Servers to parse and process x509 ASN.1. This increases the security and stability of the WebPKI as a whole by reducing the incidence of parsing errors and the likelihood of values being copied directly from the CSR into the resulting certificate.

IANA Considerations

ACME Directory Metadata Fields IANA will add the following entry to the "ACME Directory Metadata Fields" registry within the "Automated Certificate Management Environment (ACME) Protocol" registry group at https://www.iana.org/assignments/acme:

Field Name	Field Type	Reference
profiles	object	This document

ACME Order Object Fields IANA will add the following entry to the "ACME Order Object Fields" registry within the "Automated Certificate Management Environment (ACME) Protocol" registry group at https://www.iana.org/assignments/acme:

Field Name	Field Type	Configurable	Reference
profile	string	true	This document

ACME Error Types IANA will add the following entry to the "ACME Error Types" registry within the "Automated Certificate Management Environment (ACME) Protocol" registry group at https://www.iana.org/assignments/acme:

Type	Description	Reference
invalidProfile	The request specified a profile which this server does not support	This document

Normative References Public Key Infrastructure using X.509 (PKIX) certificates are used for a number of purposes, the most significant of which is the authentication of domain names. Thus, certification authorities (CAs) in the Web PKI are trusted to verify that an applicant for a certificate legitimately represents the domain name(s) in the certificate. As of this writing, this verification is done through a collection of ad hoc mechanisms. This document describes a protocol that a CA and an applicant can use to automate the process of verification and certificate issuance. The protocol also provides facilities for other certificate management functions, such as certificate revocation. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.

Acknowledgments My thanks to Phil Porada for spearheading the implementation of this protocol in the Boulder software. Thanks also to Jacob Hoffman-Andrews, Samantha Frank, James Kasten, and Jason Baker for discussions and brainstorming on what this protocol should look like.