From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc8555.txt | 5323 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 5323 insertions(+) create mode 100644 doc/rfc/rfc8555.txt (limited to 'doc/rfc/rfc8555.txt') diff --git a/doc/rfc/rfc8555.txt b/doc/rfc/rfc8555.txt new file mode 100644 index 0000000..ae0477b --- /dev/null +++ b/doc/rfc/rfc8555.txt @@ -0,0 +1,5323 @@ + + + + + + +Internet Engineering Task Force (IETF) R. Barnes +Request for Comments: 8555 Cisco +Category: Standards Track J. Hoffman-Andrews +ISSN: 2070-1721 EFF + D. McCarney + Let's Encrypt + J. Kasten + University of Michigan + March 2019 + + + Automatic Certificate Management Environment (ACME) + +Abstract + + 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. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc8555. + + + + + + + + + + + +Barnes, et al. Standards Track [Page 1] + +RFC 8555 ACME March 2019 + + +Copyright Notice + + Copyright (c) 2019 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (https://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + +Table of Contents + + 1. Introduction ....................................................4 + 2. Deployment Model and Operator Experience ........................5 + 3. Terminology .....................................................7 + 4. Protocol Overview ...............................................7 + 5. Character Encoding .............................................10 + 6. Message Transport ..............................................10 + 6.1. HTTPS Requests ............................................10 + 6.2. Request Authentication ....................................11 + 6.3. GET and POST-as-GET Requests ..............................13 + 6.4. Request URL Integrity .....................................13 + 6.4.1. "url" (URL) JWS Header Parameter ...................14 + 6.5. Replay Protection .........................................14 + 6.5.1. Replay-Nonce .......................................15 + 6.5.2. "nonce" (Nonce) JWS Header Parameter ...............16 + 6.6. Rate Limits ...............................................16 + 6.7. Errors ....................................................16 + 6.7.1. Subproblems ........................................18 + 7. Certificate Management .........................................20 + 7.1. Resources .................................................20 + 7.1.1. Directory ..........................................23 + 7.1.2. Account Objects ....................................24 + 7.1.3. Order Objects ......................................26 + 7.1.4. Authorization Objects ..............................28 + 7.1.5. Challenge Objects ..................................30 + 7.1.6. Status Changes .....................................30 + 7.2. Getting a Nonce ...........................................34 + 7.3. Account Management ........................................34 + 7.3.1. Finding an Account URL Given a Key .................36 + 7.3.2. Account Update .....................................37 + 7.3.3. Changes of Terms of Service ........................38 + 7.3.4. External Account Binding ...........................38 + + + +Barnes, et al. Standards Track [Page 2] + +RFC 8555 ACME March 2019 + + + 7.3.5. Account Key Rollover ...............................40 + 7.3.6. Account Deactivation ...............................43 + 7.4. Applying for Certificate Issuance .........................44 + 7.4.1. Pre-authorization ..................................49 + 7.4.2. Downloading the Certificate ........................51 + 7.5. Identifier Authorization ..................................53 + 7.5.1. Responding to Challenges ...........................54 + 7.5.2. Deactivating an Authorization ......................57 + 7.6. Certificate Revocation ....................................58 + 8. Identifier Validation Challenges ...............................60 + 8.1. Key Authorizations ........................................62 + 8.2. Retrying Challenges .......................................63 + 8.3. HTTP Challenge ............................................63 + 8.4. DNS Challenge .............................................66 + 9. IANA Considerations ............................................68 + 9.1. Media Type: application/pem-certificate-chain .............68 + 9.2. Well-Known URI for the HTTP Challenge .....................69 + 9.3. Replay-Nonce HTTP Header ..................................69 + 9.4. "url" JWS Header Parameter ................................70 + 9.5. "nonce" JWS Header Parameter ..............................70 + 9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) .........70 + 9.7. New Registries ............................................71 + 9.7.1. Fields in Account Objects ..........................71 + 9.7.2. Fields in Order Objects ............................72 + 9.7.3. Fields in Authorization Objects ....................73 + 9.7.4. Error Types ........................................74 + 9.7.5. Resource Types .....................................74 + 9.7.6. Fields in the "meta" Object within a + Directory Object ...................................75 + 9.7.7. Identifier Types ...................................76 + 9.7.8. Validation Methods .................................76 + 10. Security Considerations .......................................78 + 10.1. Threat Model .............................................78 + 10.2. Integrity of Authorizations ..............................80 + 10.3. Denial-of-Service Considerations .........................83 + 10.4. Server-Side Request Forgery ..............................84 + 10.5. CA Policy Considerations .................................84 + 11. Operational Considerations ....................................86 + 11.1. Key Selection ............................................86 + 11.2. DNS Security .............................................87 + 11.3. Token Entropy ............................................88 + 11.4. Malformed Certificate Chains .............................88 + 12. References ....................................................88 + 12.1. Normative References .....................................88 + 12.2. Informative References ...................................92 + Acknowledgements ..................................................94 + Authors' Addresses ................................................95 + + + + +Barnes, et al. Standards Track [Page 3] + +RFC 8555 ACME March 2019 + + +1. Introduction + + Certificates [RFC5280] in the Web PKI are most commonly used to + authenticate 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. + + Different types of certificates reflect different kinds of CA + verification of information about the certificate subject. "Domain + Validation" (DV) certificates are by far the most common type. The + only validation the CA is required to perform in the DV issuance + process is to verify that the requester has effective control of the + domain [CABFBR]. The CA is not required to attempt to verify the + requester's real-world identity. (This is as opposed to + "Organization Validation" (OV) and "Extended Validation" (EV) + certificates, where the process is intended to also verify the real- + world identity of the requester.) + + Existing Web PKI certification authorities tend to use a set of ad + hoc protocols for certificate issuance and identity verification. In + the case of DV certificates, a typical user experience is something + like: + + o Generate a PKCS#10 [RFC2986] Certificate Signing Request (CSR). + + o Cut and paste the CSR into a CA's web page. + + o Prove ownership of the domain(s) in the CSR by one of the + following methods: + + * Put a CA-provided challenge at a specific place on the web + server. + + * Put a CA-provided challenge in a DNS record corresponding to + the target domain. + + * Receive a CA-provided challenge at (hopefully) an + administrator-controlled email address corresponding to the + domain, and then respond to it on the CA's web page. + + o Download the issued certificate and install it on the user's Web + Server. + + With the exception of the CSR itself and the certificates that are + issued, these are all completely ad hoc procedures and are + accomplished by getting the human user to follow interactive natural- + language instructions from the CA rather than by machine-implemented + published protocols. In many cases, the instructions are difficult + + + +Barnes, et al. Standards Track [Page 4] + +RFC 8555 ACME March 2019 + + + to follow and cause significant frustration and confusion. Informal + usability tests by the authors indicate that webmasters often need + 1-3 hours to obtain and install a certificate for a domain. Even in + the best case, the lack of published, standardized mechanisms + presents an obstacle to the wide deployment of HTTPS and other PKIX- + dependent systems because it inhibits mechanization of tasks related + to certificate issuance, deployment, and revocation. + + This document describes an extensible framework for automating the + issuance and domain validation procedure, thereby allowing servers + and infrastructure software to obtain certificates without user + interaction. Use of this protocol should radically simplify the + deployment of HTTPS and the practicality of PKIX-based authentication + for other protocols based on Transport Layer Security (TLS) + [RFC8446]. + + It should be noted that while the focus of this document is on + validating domain names for purposes of issuing certificates in the + Web PKI, ACME supports extensions for uses with other identifiers in + other PKI contexts. For example, as of this writing, there is + ongoing work to use ACME for issuance of Web PKI certificates + attesting to IP addresses [ACME-IP] and Secure Telephone Identity + Revisited (STIR) certificates attesting to telephone numbers + [ACME-TELEPHONE]. + + ACME can also be used to automate some aspects of certificate + management even where non-automated processes are still needed. For + example, the external account binding feature (see Section 7.3.4) can + allow an ACME account to use authorizations that have been granted to + an external, non-ACME account. This allows ACME to address issuance + scenarios that cannot yet be fully automated, such as the issuance of + "Extended Validation" certificates. + +2. Deployment Model and Operator Experience + + The guiding use case for ACME is obtaining certificates for websites + (HTTPS [RFC2818]). In this case, a web server is intended to speak + for one or more domains, and the process of certificate issuance is + intended to verify that this web server actually speaks for the + domain(s). + + DV certificate validation commonly checks claims about properties + related to control of a domain name -- properties that can be + observed by the certificate issuer in an interactive process that can + be conducted purely online. That means that under typical + circumstances, all steps in the request, verification, and issuance + process can be represented and performed by Internet protocols with + no out-of-band human intervention. + + + +Barnes, et al. Standards Track [Page 5] + +RFC 8555 ACME March 2019 + + + Prior to ACME, when deploying an HTTPS server, a server operator + typically gets a prompt to generate a self-signed certificate. If + the operator were instead deploying an HTTPS server using ACME, the + experience would be something like this: + + o The operator's ACME client prompts the operator for the intended + domain name(s) that the web server is to stand for. + + o The ACME client presents the operator with a list of CAs from + which it could get a certificate. (This list will change over + time based on the capabilities of CAs and updates to ACME + configuration.) The ACME client might prompt the operator for + payment information at this point. + + o The operator selects a CA. + + o In the background, the ACME client contacts the CA and requests + that it issue a certificate for the intended domain name(s). + + o The CA verifies that the client controls the requested domain + name(s) by having the ACME client perform some action(s) that can + only be done with control of the domain name(s). For example, the + CA might require a client requesting example.com to provision a + DNS record under example.com or an HTTP resource under + http://example.com. + + o Once the CA is satisfied, it issues the certificate and the ACME + client automatically downloads and installs it, potentially + notifying the operator via email, SMS, etc. + + o The ACME client periodically contacts the CA to get updated + certificates, stapled Online Certificate Status Protocol (OCSP) + responses [RFC6960], or whatever else would be required to keep + the web server functional and its credentials up to date. + + In this way, it would be nearly as easy to deploy with a CA-issued + certificate as with a self-signed certificate. Furthermore, the + maintenance of that CA-issued certificate would require minimal + manual intervention. Such close integration of ACME with HTTPS + servers allows the immediate and automated deployment of certificates + as they are issued, sparing the human administrator from much of the + time-consuming work described in the previous section. + + + + + + + + + +Barnes, et al. Standards Track [Page 6] + +RFC 8555 ACME March 2019 + + +3. Terminology + + 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 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + + The two main roles in ACME are "client" and "server". The ACME + client uses the protocol to request certificate management actions, + such as issuance or revocation. An ACME client may run on a web + server, mail server, or some other server system that requires valid + X.509 certificates. Or, it may run on a separate server that does + not consume the certificate but is authorized to respond to a CA- + provided challenge. The ACME server runs at a certification + authority and responds to client requests, performing the requested + actions if the client is authorized. + + An ACME client authenticates to the server by means of an "account + key pair". The client uses the private key of this key pair to sign + all messages sent to the server. The server uses the public key to + verify the authenticity and integrity of messages from the client. + +4. Protocol Overview + + ACME allows a client to request certificate management actions using + a set of JavaScript Object Notation (JSON) messages [RFC8259] carried + over HTTPS [RFC2818]. Issuance using ACME resembles a traditional + CA's issuance process, in which a user creates an account, requests a + certificate, and proves control of the domain(s) in that certificate + in order for the CA to issue the requested certificate. + + The first phase of ACME is for the client to request an account with + the ACME server. The client generates an asymmetric key pair and + requests a new account, optionally providing contact information, + agreeing to terms of service (ToS), and/or associating the account + with an existing account in another system. The creation request is + signed with the generated private key to prove that the client + controls it. + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 7] + +RFC 8555 ACME March 2019 + + + Client Server + + [Contact Information] + [ToS Agreement] + [Additional Data] + Signature -------> + Account URL + <------- Account Object + + + [] Information covered by request signatures + + Account Creation + + Once an account is registered, there are four major steps the client + needs to take to get a certificate: + + 1. Submit an order for a certificate to be issued + + 2. Prove control of any identifiers requested in the certificate + + 3. Finalize the order by submitting a CSR + + 4. Await issuance and download the issued certificate + + The client's order for a certificate describes the desired + identifiers plus a few additional fields that capture semantics that + are not supported in the CSR format. If the server is willing to + consider issuing such a certificate, it responds with a list of + requirements that the client must satisfy before the certificate will + be issued. + + For example, in most cases, the server will require the client to + demonstrate that it controls the identifiers in the requested + certificate. Because there are many different ways to validate + possession of different types of identifiers, the server will choose + from an extensible set of challenges that are appropriate for the + identifier being claimed. The client responds with a set of + responses that tell the server which challenges the client has + completed. The server then validates that the client has completed + the challenges. + + Once the validation process is complete and the server is satisfied + that the client has met its requirements, the client finalizes the + order by submitting a PKCS#10 Certificate Signing Request (CSR). The + server will issue the requested certificate and make it available to + the client. + + + + +Barnes, et al. Standards Track [Page 8] + +RFC 8555 ACME March 2019 + + + Client Server + + [Order] + Signature -------> + <------- Required Authorizations + + [Responses] + Signature -------> + + <~~~~~~~~Validation~~~~~~~~> + + [CSR] + Signature -------> + <------- Acknowledgement + + <~~~~~~Await issuance~~~~~~> + + [POST-as-GET request] + Signature -------> + <------- Certificate + + [] Information covered by request signatures + + Certificate Issuance + + To revoke a certificate, the client sends a signed revocation request + indicating the certificate to be revoked: + + Client Server + + [Revocation request] + Signature --------> + + <-------- Result + + [] Information covered by request signatures + + Certificate Revocation + + Note that while ACME is defined with enough flexibility to handle + different types of identifiers in principle, the primary use case + addressed by this document is the case where domain names are used as + identifiers. For example, all of the identifier validation + challenges described in Section 8 address validation of domain names. + The use of ACME for other identifiers will require further + specification in order to describe how these identifiers are encoded + in the protocol and what types of validation challenges the server + might require. + + + +Barnes, et al. Standards Track [Page 9] + +RFC 8555 ACME March 2019 + + +5. Character Encoding + + All requests and responses sent via HTTP by ACME clients, ACME + servers, and validation servers as well as any inputs for digest + computations MUST be encoded using the UTF-8 character set [RFC3629]. + Note that identifiers that appear in certificates may have their own + encoding considerations (e.g., DNS names containing non-ASCII + characters are expressed as A-labels rather than U-labels). Any such + encoding considerations are to be applied prior to the aforementioned + UTF-8 encoding. + +6. Message Transport + + Communications between an ACME client and an ACME server are done + over HTTPS, using JSON Web Signature (JWS) [RFC7515] to provide some + additional security properties for messages sent from the client to + the server. HTTPS provides server authentication and + confidentiality. With some ACME-specific extensions, JWS provides + authentication of the client's request payloads, anti-replay + protection, and integrity for the HTTPS request URL. + +6.1. HTTPS Requests + + Each ACME function is accomplished by the client sending a sequence + of HTTPS requests to the server [RFC2818], carrying JSON messages + [RFC8259]. Use of HTTPS is REQUIRED. Each subsection of Section 7 + below describes the message formats used by the function and the + order in which messages are sent. + + In most HTTPS transactions used by ACME, the ACME client is the HTTPS + client and the ACME server is the HTTPS server. The ACME server acts + as a client when validating challenges: an HTTP client when + validating an 'http-01' challenge, a DNS client with 'dns-01', etc. + + ACME servers SHOULD follow the recommendations of [RFC7525] when + configuring their TLS implementations. ACME servers that support TLS + 1.3 MAY allow clients to send early data (0-RTT). This is safe + because the ACME protocol itself includes anti-replay protections + (see Section 6.5) in all cases where they are required. For this + reason, there are no restrictions on what ACME data can be carried in + 0-RTT. + + ACME clients MUST send a User-Agent header field, in accordance with + [RFC7231]. This header field SHOULD include the name and version of + the ACME software in addition to the name and version of the + underlying HTTP client software. + + + + + +Barnes, et al. Standards Track [Page 10] + +RFC 8555 ACME March 2019 + + + ACME clients SHOULD send an Accept-Language header field in + accordance with [RFC7231] to enable localization of error messages. + + ACME servers that are intended to be generally accessible need to use + Cross-Origin Resource Sharing (CORS) in order to be accessible from + browser-based clients [W3C.REC-cors-20140116]. Such servers SHOULD + set the Access-Control-Allow-Origin header field to the value "*". + + Binary fields in the JSON objects used by ACME are encoded using + base64url encoding described in Section 5 of [RFC4648] according to + the profile specified in JSON Web Signature in Section 2 of + [RFC7515]. This encoding uses a URL safe character set. Trailing + '=' characters MUST be stripped. Encoded values that include + trailing '=' characters MUST be rejected as improperly encoded. + +6.2. Request Authentication + + All ACME requests with a non-empty body MUST encapsulate their + payload in a JSON Web Signature (JWS) [RFC7515] object, signed using + the account's private key unless otherwise specified. The server + MUST verify the JWS before processing the request. Encapsulating + request bodies in JWS provides authentication of requests. + + A JWS object sent as the body of an ACME request MUST meet the + following additional criteria: + + o The JWS MUST be in the Flattened JSON Serialization [RFC7515] + + o The JWS MUST NOT have multiple signatures + + o The JWS Unencoded Payload Option [RFC7797] MUST NOT be used + + o The JWS Unprotected Header [RFC7515] MUST NOT be used + + o The JWS Payload MUST NOT be detached + + o The JWS Protected Header MUST include the following fields: + + * "alg" (Algorithm) + + + This field MUST NOT contain "none" or a Message + Authentication Code (MAC) algorithm (e.g. one in which the + algorithm registry description mentions MAC/HMAC). + + * "nonce" (defined in Section 6.5) + + * "url" (defined in Section 6.4) + + + + +Barnes, et al. Standards Track [Page 11] + +RFC 8555 ACME March 2019 + + + * Either "jwk" (JSON Web Key) or "kid" (Key ID) as specified + below + + An ACME server MUST implement the "ES256" signature algorithm + [RFC7518] and SHOULD implement the "EdDSA" signature algorithm using + the "Ed25519" variant (indicated by "crv") [RFC8037]. + + The "jwk" and "kid" fields are mutually exclusive. Servers MUST + reject requests that contain both. + + For newAccount requests, and for revokeCert requests authenticated by + a certificate key, there MUST be a "jwk" field. This field MUST + contain the public key corresponding to the private key used to sign + the JWS. + + For all other requests, the request is signed using an existing + account, and there MUST be a "kid" field. This field MUST contain + the account URL received by POSTing to the newAccount resource. + + If the client sends a JWS signed with an algorithm that the server + does not support, then the server MUST return an error with status + code 400 (Bad Request) and type + "urn:ietf:params:acme:error:badSignatureAlgorithm". The problem + document returned with the error MUST include an "algorithms" field + with an array of supported "alg" values. See Section 6.7 for more + details on the structure of error responses. + + If the server supports the signature algorithm "alg" but either does + not support or chooses to reject the public key "jwk", then the + server MUST return an error with status code 400 (Bad Request) and + type "urn:ietf:params:acme:error:badPublicKey". The problem document + detail SHOULD describe the reason for rejecting the public key; some + example reasons are: + + o "alg" is "RS256" but the modulus "n" is too small (e.g., 512-bit) + + o "alg" is "ES256" but "jwk" does not contain a valid P-256 public + key + + o "alg" is "EdDSA" and "crv" is "Ed448", but the server only + supports "EdDSA" with "Ed25519" + + o the corresponding private key is known to have been compromised + + + + + + + + +Barnes, et al. Standards Track [Page 12] + +RFC 8555 ACME March 2019 + + + Because client requests in ACME carry JWS objects in the Flattened + JSON Serialization, they must have the Content-Type header field set + to "application/jose+json". If a request does not meet this + requirement, then the server MUST return a response with status code + 415 (Unsupported Media Type). + +6.3. GET and POST-as-GET Requests + + Note that authentication via signed JWS request bodies implies that + requests without an entity body are not authenticated, in particular + GET requests. Except for the cases described in this section, if the + server receives a GET request, it MUST return an error with status + code 405 (Method Not Allowed) and type "malformed". + + If a client wishes to fetch a resource from the server (which would + otherwise be done with a GET), then it MUST send a POST request with + a JWS body as described above, where the payload of the JWS is a + zero-length octet string. In other words, the "payload" field of the + JWS object MUST be present and set to the empty string (""). + + We will refer to these as "POST-as-GET" requests. On receiving a + request with a zero-length (and thus non-JSON) payload, the server + MUST authenticate the sender and verify any access control rules. + Otherwise, the server MUST treat this request as having the same + semantics as a GET request for the same resource. + + The server MUST allow GET requests for the directory and newNonce + resources (see Section 7.1), in addition to POST-as-GET requests for + these resources. This enables clients to bootstrap into the ACME + authentication system. + +6.4. Request URL Integrity + + It is common in deployment for the entity terminating TLS for HTTPS + to be different from the entity operating the logical HTTPS server, + with a "request routing" layer in the middle. For example, an ACME + CA might have a content delivery network terminate TLS connections + from clients so that it can inspect client requests for denial-of- + service (DoS) protection. + + These intermediaries can also change values in the request that are + not signed in the HTTPS request, e.g., the request URL and header + fields. ACME uses JWS to provide an integrity mechanism, which + protects against an intermediary changing the request URL to another + ACME URL. + + + + + + +Barnes, et al. Standards Track [Page 13] + +RFC 8555 ACME March 2019 + + + As noted in Section 6.2, all ACME request objects carry a "url" + header parameter in their protected header. This header parameter + encodes the URL to which the client is directing the request. On + receiving such an object in an HTTP request, the server MUST compare + the "url" header parameter to the request URL. If the two do not + match, then the server MUST reject the request as unauthorized. + + Except for the directory resource, all ACME resources are addressed + with URLs provided to the client by the server. In POST requests + sent to these resources, the client MUST set the "url" header + parameter to the exact string provided by the server (rather than + performing any re-encoding on the URL). The server SHOULD perform + the corresponding string equality check, configuring each resource + with the URL string provided to clients and having the resource check + that requests have the same string in their "url" header parameter. + The server MUST reject the request as unauthorized if the string + equality check fails. + +6.4.1. "url" (URL) JWS Header Parameter + + The "url" header parameter specifies the URL [RFC3986] to which this + JWS object is directed. The "url" header parameter MUST be carried + in the protected header of the JWS. The value of the "url" header + parameter MUST be a string representing the target URL. + +6.5. Replay Protection + + In order to protect ACME resources from any possible replay attacks, + ACME POST requests have a mandatory anti-replay mechanism. This + mechanism is based on the server maintaining a list of nonces that it + has issued, and requiring any signed request from the client to carry + such a nonce. + + An ACME server provides nonces to clients using the HTTP Replay-Nonce + header field, as specified in Section 6.5.1. The server MUST include + a Replay-Nonce header field in every successful response to a POST + request and SHOULD provide it in error responses as well. + + Every JWS sent by an ACME client MUST include, in its protected + header, the "nonce" header parameter, with contents as defined in + Section 6.5.2. As part of JWS verification, the ACME server MUST + verify that the value of the "nonce" header is a value that the + server previously provided in a Replay-Nonce header field. Once a + nonce value has appeared in an ACME request, the server MUST consider + it invalid, in the same way as a value it had never issued. + + + + + + +Barnes, et al. Standards Track [Page 14] + +RFC 8555 ACME March 2019 + + + When a server rejects a request because its nonce value was + unacceptable (or not present), it MUST provide HTTP status code 400 + (Bad Request), and indicate the ACME error type + "urn:ietf:params:acme:error:badNonce". An error response with the + "badNonce" error type MUST include a Replay-Nonce header field with a + fresh nonce that the server will accept in a retry of the original + query (and possibly in other requests, according to the server's + nonce scoping policy). On receiving such a response, a client SHOULD + retry the request using the new nonce. + + The precise method used to generate and track nonces is up to the + server. For example, the server could generate a random 128-bit + value for each response, keep a list of issued nonces, and strike + nonces from this list as they are used. + + Other than the constraint above with regard to nonces issued in + "badNonce" responses, ACME does not constrain how servers scope + nonces. Clients MAY assume that nonces have broad scope, e.g., by + having a single pool of nonces used for all requests. However, when + retrying in response to a "badNonce" error, the client MUST use the + nonce provided in the error response. Servers should scope nonces + broadly enough that retries are not needed very often. + +6.5.1. Replay-Nonce + + The Replay-Nonce HTTP header field includes a server-generated value + that the server can use to detect unauthorized replay in future + client requests. The server MUST generate the values provided in + Replay-Nonce header fields in such a way that they are unique to each + message, with high probability, and unpredictable to anyone besides + the server. For instance, it is acceptable to generate Replay-Nonces + randomly. + + The value of the Replay-Nonce header field MUST be an octet string + encoded according to the base64url encoding described in Section 2 of + [RFC7515]. Clients MUST ignore invalid Replay-Nonce values. The + ABNF [RFC5234] for the Replay-Nonce header field follows: + + base64url = ALPHA / DIGIT / "-" / "_" + + Replay-Nonce = 1*base64url + + The Replay-Nonce header field SHOULD NOT be included in HTTP request + messages. + + + + + + + +Barnes, et al. Standards Track [Page 15] + +RFC 8555 ACME March 2019 + + +6.5.2. "nonce" (Nonce) JWS Header Parameter + + The "nonce" header parameter provides a unique value that enables the + verifier of a JWS to recognize when replay has occurred. The "nonce" + header parameter MUST be carried in the protected header of the JWS. + + The value of the "nonce" header parameter MUST be an octet string, + encoded according to the base64url encoding described in Section 2 of + [RFC7515]. If the value of a "nonce" header parameter is not valid + according to this encoding, then the verifier MUST reject the JWS as + malformed. + +6.6. Rate Limits + + Creation of resources can be rate limited by ACME servers to ensure + fair usage and prevent abuse. Once the rate limit is exceeded, the + server MUST respond with an error with the type + "urn:ietf:params:acme:error:rateLimited". Additionally, the server + SHOULD send a Retry-After header field [RFC7231] indicating when the + current request may succeed again. If multiple rate limits are in + place, that is the time where all rate limits allow access again for + the current request with exactly the same parameters. + + In addition to the human-readable "detail" field of the error + response, the server MAY send one or multiple link relations in the + Link header field [RFC8288] pointing to documentation about the + specific rate limit that was hit, using the "help" link relation + type. + +6.7. Errors + + Errors can be reported in ACME both at the HTTP layer and within + challenge objects as defined in Section 8. ACME servers can return + responses with an HTTP error response code (4XX or 5XX). For + example, if the client submits a request using a method not allowed + in this document, then the server MAY return status code 405 (Method + Not Allowed). + + When the server responds with an error status, it SHOULD provide + additional information using a problem document [RFC7807]. To + facilitate automatic response to errors, this document defines the + following standard tokens for use in the "type" field (within the + ACME URN namespace "urn:ietf:params:acme:error:"): + + + + + + + + +Barnes, et al. Standards Track [Page 16] + +RFC 8555 ACME March 2019 + + + +-------------------------+-----------------------------------------+ + | Type | Description | + +-------------------------+-----------------------------------------+ + | accountDoesNotExist | The request specified an account that | + | | does not exist | + | | | + | alreadyRevoked | The request specified a certificate to | + | | be revoked that has already been | + | | revoked | + | | | + | badCSR | The CSR is unacceptable (e.g., due to a | + | | short key) | + | | | + | badNonce | The client sent an unacceptable anti- | + | | replay nonce | + | | | + | badPublicKey | The JWS was signed by a public key the | + | | server does not support | + | | | + | badRevocationReason | The revocation reason provided is not | + | | allowed by the server | + | | | + | badSignatureAlgorithm | The JWS was signed with an algorithm | + | | the server does not support | + | | | + | caa | Certification Authority Authorization | + | | (CAA) records forbid the CA from | + | | issuing a certificate | + | | | + | compound | Specific error conditions are indicated | + | | in the "subproblems" array | + | | | + | connection | The server could not connect to | + | | validation target | + | | | + | dns | There was a problem with a DNS query | + | | during identifier validation | + | | | + | externalAccountRequired | The request must include a value for | + | | the "externalAccountBinding" field | + | | | + | incorrectResponse | Response received didn't match the | + | | challenge's requirements | + | | | + | invalidContact | A contact URL for an account was | + | | invalid | + | | | + | malformed | The request message was malformed | + + + +Barnes, et al. Standards Track [Page 17] + +RFC 8555 ACME March 2019 + + + | | | + | orderNotReady | The request attempted to finalize an | + | | order that is not ready to be finalized | + | | | + | rateLimited | The request exceeds a rate limit | + | | | + | rejectedIdentifier | The server will not issue certificates | + | | for the identifier | + | | | + | serverInternal | The server experienced an internal | + | | error | + | | | + | tls | The server received a TLS error during | + | | validation | + | | | + | unauthorized | The client lacks sufficient | + | | authorization | + | | | + | unsupportedContact | A contact URL for an account used an | + | | unsupported protocol scheme | + | | | + | unsupportedIdentifier | An identifier is of an unsupported type | + | | | + | userActionRequired | Visit the "instance" URL and take | + | | actions specified there | + +-------------------------+-----------------------------------------+ + + This list is not exhaustive. The server MAY return errors whose + "type" field is set to a URI other than those defined above. Servers + MUST NOT use the ACME URN namespace for errors not listed in the + appropriate IANA registry (see Section 9.6). Clients SHOULD display + the "detail" field of all errors. + + In the remainder of this document, we use the tokens in the table + above to refer to error types, rather than the full URNs. For + example, an "error of type 'badCSR'" refers to an error document with + "type" value "urn:ietf:params:acme:error:badCSR". + +6.7.1. Subproblems + + Sometimes a CA may need to return multiple errors in response to a + request. Additionally, the CA may need to attribute errors to + specific identifiers. For instance, a newOrder request may contain + multiple identifiers for which the CA cannot issue certificates. In + this situation, an ACME problem document MAY contain the + "subproblems" field, containing a JSON array of problem documents, + each of which MAY contain an "identifier" field. If present, the + "identifier" field MUST contain an ACME identifier (Section 9.7.7). + + + +Barnes, et al. Standards Track [Page 18] + +RFC 8555 ACME March 2019 + + + The "identifier" field MUST NOT be present at the top level in ACME + problem documents. It can only be present in subproblems. + Subproblems need not all have the same type, and they do not need to + match the top level type. + + ACME clients may choose to use the "identifier" field of a subproblem + as a hint that an operation would succeed if that identifier were + omitted. For instance, if an order contains ten DNS identifiers, and + the newOrder request returns a problem document with two subproblems + (referencing two of those identifiers), the ACME client may choose to + submit another order containing only the eight identifiers not listed + in the problem document. + +HTTP/1.1 403 Forbidden +Content-Type: application/problem+json +Link: ;rel="index" + +{ + "type": "urn:ietf:params:acme:error:malformed", + "detail": "Some of the identifiers requested were rejected", + "subproblems": [ + { + "type": "urn:ietf:params:acme:error:malformed", + "detail": "Invalid underscore in DNS name \"_example.org\"", + "identifier": { + "type": "dns", + "value": "_example.org" + } + }, + { + "type": "urn:ietf:params:acme:error:rejectedIdentifier", + "detail": "This CA will not issue for \"example.net\"", + "identifier": { + "type": "dns", + "value": "example.net" + } + } + ] +} + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 19] + +RFC 8555 ACME March 2019 + + +7. Certificate Management + + In this section, we describe the certificate management functions + that ACME enables: + + o Account Creation + + o Ordering a Certificate + + o Identifier Authorization + + o Certificate Issuance + + o Certificate Revocation + +7.1. Resources + + ACME is structured as an HTTP-based application with the following + types of resources: + + o Account resources, representing information about an account + (Section 7.1.2, Section 7.3) + + o Order resources, representing an account's requests to issue + certificates (Section 7.1.3) + + o Authorization resources, representing an account's authorization + to act for an identifier (Section 7.1.4) + + o Challenge resources, representing a challenge to prove control of + an identifier (Section 7.5, Section 8) + + o Certificate resources, representing issued certificates + (Section 7.4.2) + + o A "directory" resource (Section 7.1.1) + + o A "newNonce" resource (Section 7.2) + + o A "newAccount" resource (Section 7.3) + + o A "newOrder" resource (Section 7.4) + + o A "revokeCert" resource (Section 7.6) + + o A "keyChange" resource (Section 7.3.5) + + The server MUST provide "directory" and "newNonce" resources. + + + +Barnes, et al. Standards Track [Page 20] + +RFC 8555 ACME March 2019 + + + ACME uses different URLs for different management functions. Each + function is listed in a directory along with its corresponding URL, + so clients only need to be configured with the directory URL. These + URLs are connected by a few different link relations [RFC8288]. + + The "up" link relation is used with challenge resources to indicate + the authorization resource to which a challenge belongs. It is also + used, with some media types, from certificate resources to indicate a + resource from which the client may fetch a chain of CA certificates + that could be used to validate the certificate in the original + resource. + + The "index" link relation is present on all resources other than the + directory and indicates the URL of the directory. + + The following diagram illustrates the relations between resources on + an ACME server. For the most part, these relations are expressed by + URLs provided as strings in the resources' JSON representations. + Lines with labels in quotes indicate HTTP link relations. + + directory + | + +--> newNonce + | + +----------+----------+-----+-----+------------+ + | | | | | + | | | | | + V V V V V + newAccount newAuthz newOrder revokeCert keyChange + | | | + | | | + V | V + account | order --+--> finalize + | | | + | | +--> cert + | V + +---> authorization + | ^ + | | "up" + V | + challenge + + ACME Resources and Relationships + + + + + + + + +Barnes, et al. Standards Track [Page 21] + +RFC 8555 ACME March 2019 + + + The following table illustrates a typical sequence of requests + required to establish a new account with the server, prove control of + an identifier, issue a certificate, and fetch an updated certificate + some time after issuance. The "->" is a mnemonic for a Location + header field pointing to a created resource. + + +-------------------+--------------------------------+--------------+ + | Action | Request | Response | + +-------------------+--------------------------------+--------------+ + | Get directory | GET directory | 200 | + | | | | + | Get nonce | HEAD newNonce | 200 | + | | | | + | Create account | POST newAccount | 201 -> | + | | | account | + | | | | + | Submit order | POST newOrder | 201 -> order | + | | | | + | Fetch challenges | POST-as-GET order's | 200 | + | | authorization urls | | + | | | | + | Respond to | POST authorization challenge | 200 | + | challenges | urls | | + | | | | + | Poll for status | POST-as-GET order | 200 | + | | | | + | Finalize order | POST order's finalize url | 200 | + | | | | + | Poll for status | POST-as-GET order | 200 | + | | | | + | Download | POST-as-GET order's | 200 | + | certificate | certificate url | | + +-------------------+--------------------------------+--------------+ + + The remainder of this section provides the details of how these + resources are structured and how the ACME protocol makes use of them. + + + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 22] + +RFC 8555 ACME March 2019 + + +7.1.1. Directory + + In order to help clients configure themselves with the right URLs for + each ACME operation, ACME servers provide a directory object. This + should be the only URL needed to configure clients. It is a JSON + object, whose field names are drawn from the resource registry + (Section 9.7.5) and whose values are the corresponding URLs. + + +------------+--------------------+ + | Field | URL in Value | + +------------+--------------------+ + | newNonce | New nonce | + | | | + | newAccount | New account | + | | | + | newOrder | New order | + | | | + | newAuthz | New authorization | + | | | + | revokeCert | Revoke certificate | + | | | + | keyChange | Key change | + +------------+--------------------+ + + There is no constraint on the URL of the directory except that it + should be different from the other ACME server resources' URLs, and + that it should not clash with other services. For instance: + + o a host that functions as both an ACME and a Web server may want to + keep the root path "/" for an HTML "front page" and place the ACME + directory under the path "/acme". + + o a host that only functions as an ACME server could place the + directory under the path "/". + + If the ACME server does not implement pre-authorization + (Section 7.4.1), it MUST omit the "newAuthz" field of the directory. + + The object MAY additionally contain a "meta" field. If present, it + MUST be a JSON object; each field in the object is an item of + metadata relating to the service provided by the ACME server. + + The following metadata items are defined (Section 9.7.6), all of + which are OPTIONAL: + + termsOfService (optional, string): A URL identifying the current + terms of service. + + + + +Barnes, et al. Standards Track [Page 23] + +RFC 8555 ACME March 2019 + + + website (optional, string): An HTTP or HTTPS URL locating a website + providing more information about the ACME server. + + caaIdentities (optional, array of string): The hostnames that the + ACME server recognizes as referring to itself for the purposes of + CAA record validation as defined in [RFC6844]. Each string MUST + represent the same sequence of ASCII code points that the server + will expect to see as the "Issuer Domain Name" in a CAA issue or + issuewild property tag. This allows clients to determine the + correct issuer domain name to use when configuring CAA records. + + externalAccountRequired (optional, boolean): If this field is + present and set to "true", then the CA requires that all + newAccount requests include an "externalAccountBinding" field + associating the new account with an external account. + + Clients access the directory by sending a GET request to the + directory URL. + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "newNonce": "https://example.com/acme/new-nonce", + "newAccount": "https://example.com/acme/new-account", + "newOrder": "https://example.com/acme/new-order", + "newAuthz": "https://example.com/acme/new-authz", + "revokeCert": "https://example.com/acme/revoke-cert", + "keyChange": "https://example.com/acme/key-change", + "meta": { + "termsOfService": "https://example.com/acme/terms/2017-5-30", + "website": "https://www.example.com/", + "caaIdentities": ["example.com"], + "externalAccountRequired": false + } + } + +7.1.2. Account Objects + + An ACME account resource represents a set of metadata associated with + an account. Account resources have the following structure: + + status (required, string): The status of this account. Possible + values are "valid", "deactivated", and "revoked". The value + "deactivated" should be used to indicate client-initiated + deactivation whereas "revoked" should be used to indicate server- + initiated deactivation. See Section 7.1.6. + + + + +Barnes, et al. Standards Track [Page 24] + +RFC 8555 ACME March 2019 + + + contact (optional, array of string): An array of URLs that the + server can use to contact the client for issues related to this + account. For example, the server may wish to notify the client + about server-initiated revocation or certificate expiration. For + information on supported URL schemes, see Section 7.3. + + termsOfServiceAgreed (optional, boolean): Including this field in a + newAccount request, with a value of true, indicates the client's + agreement with the terms of service. This field cannot be updated + by the client. + + externalAccountBinding (optional, object): Including this field in a + newAccount request indicates approval by the holder of an existing + non-ACME account to bind that account to this ACME account. This + field is not updateable by the client (see Section 7.3.4). + + orders (required, string): A URL from which a list of orders + submitted by this account can be fetched via a POST-as-GET + request, as described in Section 7.1.2.1. + + { + "status": "valid", + "contact": [ + "mailto:cert-admin@example.org", + "mailto:admin@example.org" + ], + "termsOfServiceAgreed": true, + "orders": "https://example.com/acme/orders/rzGoeA" + } + +7.1.2.1. Orders List + + Each account object includes an "orders" URL from which a list of + orders created by the account can be fetched via POST-as-GET request. + The result of the request MUST be a JSON object whose "orders" field + is an array of URLs, each identifying an order belonging to the + account. The server SHOULD include pending orders and SHOULD NOT + include orders that are invalid in the array of URLs. The server MAY + return an incomplete list, along with a Link header field with a + "next" link relation indicating where further entries can be + acquired. + + + + + + + + + + +Barnes, et al. Standards Track [Page 25] + +RFC 8555 ACME March 2019 + + + HTTP/1.1 200 OK + Content-Type: application/json + Link: ;rel="index" + Link: ;rel="next" + + { + "orders": [ + "https://example.com/acme/order/TOlocE8rfgo", + "https://example.com/acme/order/4E16bbL5iSw", + /* more URLs not shown for example brevity */ + "https://example.com/acme/order/neBHYLfw0mg" + ] + } + +7.1.3. Order Objects + + An ACME order object represents a client's request for a certificate + and is used to track the progress of that order through to issuance. + Thus, the object contains information about the requested + certificate, the authorizations that the server requires the client + to complete, and any certificates that have resulted from this order. + + status (required, string): The status of this order. Possible + values are "pending", "ready", "processing", "valid", and + "invalid". See Section 7.1.6. + + expires (optional, string): The timestamp after which the server + will consider this order invalid, encoded in the format specified + in [RFC3339]. This field is REQUIRED for objects with "pending" + or "valid" in the status field. + + identifiers (required, array of object): An array of identifier + objects that the order pertains to. + + type (required, string): The type of identifier. This document + defines the "dns" identifier type. See the registry defined in + Section 9.7.7 for any others. + + value (required, string): The identifier itself. + + notBefore (optional, string): The requested value of the notBefore + field in the certificate, in the date format defined in [RFC3339]. + + notAfter (optional, string): The requested value of the notAfter + field in the certificate, in the date format defined in [RFC3339]. + + + + + + +Barnes, et al. Standards Track [Page 26] + +RFC 8555 ACME March 2019 + + + error (optional, object): The error that occurred while processing + the order, if any. This field is structured as a problem document + [RFC7807]. + + authorizations (required, array of string): For pending orders, the + authorizations that the client needs to complete before the + requested certificate can be issued (see Section 7.5), including + unexpired authorizations that the client has completed in the past + for identifiers specified in the order. The authorizations + required are dictated by server policy; there may not be a 1:1 + relationship between the order identifiers and the authorizations + required. For final orders (in the "valid" or "invalid" state), + the authorizations that were completed. Each entry is a URL from + which an authorization can be fetched with a POST-as-GET request. + + finalize (required, string): A URL that a CSR must be POSTed to once + all of the order's authorizations are satisfied to finalize the + order. The result of a successful finalization will be the + population of the certificate URL for the order. + + certificate (optional, string): A URL for the certificate that has + been issued in response to this order. + + { + "status": "valid", + "expires": "2016-01-20T14:09:07.99Z", + + "identifiers": [ + { "type": "dns", "value": "www.example.org" }, + { "type": "dns", "value": "example.org" } + ], + + "notBefore": "2016-01-01T00:00:00Z", + "notAfter": "2016-01-08T00:00:00Z", + + "authorizations": [ + "https://example.com/acme/authz/PAniVnsZcis", + "https://example.com/acme/authz/r4HqLzrSrpI" + ], + + "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize", + + "certificate": "https://example.com/acme/cert/mAt3xBGaobw" + } + + Any identifier of type "dns" in a newOrder request MAY have a + wildcard domain name as its value. A wildcard domain name consists + of a single asterisk character followed by a single full stop + + + +Barnes, et al. Standards Track [Page 27] + +RFC 8555 ACME March 2019 + + + character ("*.") followed by a domain name as defined for use in the + Subject Alternate Name Extension by [RFC5280]. An authorization + returned by the server for a wildcard domain name identifier MUST NOT + include the asterisk and full stop ("*.") prefix in the authorization + identifier value. The returned authorization MUST include the + optional "wildcard" field, with a value of true. + + The elements of the "authorizations" and "identifiers" arrays are + immutable once set. The server MUST NOT change the contents of + either array after they are created. If a client observes a change + in the contents of either array, then it SHOULD consider the order + invalid. + + The "authorizations" array of the order SHOULD reflect all + authorizations that the CA takes into account in deciding to issue, + even if some authorizations were fulfilled in earlier orders or in + pre-authorization transactions. For example, if a CA allows multiple + orders to be fulfilled based on a single authorization transaction, + then it SHOULD reflect that authorization in all of the orders. + + Note that just because an authorization URL is listed in the + "authorizations" array of an order object doesn't mean that the + client is required to take action. There are several reasons that + the referenced authorizations may already be valid: + + o The client completed the authorization as part of a previous order + + o The client previously pre-authorized the identifier (see + Section 7.4.1) + + o The server granted the client authorization based on an external + account + + Clients SHOULD check the "status" field of an order to determine + whether they need to take any action. + +7.1.4. Authorization Objects + + An ACME authorization object represents a server's authorization for + an account to represent an identifier. In addition to the + identifier, an authorization includes several metadata fields, such + as the status of the authorization (e.g., "pending", "valid", or + "revoked") and which challenges were used to validate possession of + the identifier. + + + + + + + +Barnes, et al. Standards Track [Page 28] + +RFC 8555 ACME March 2019 + + + The structure of an ACME authorization resource is as follows: + + identifier (required, object): The identifier that the account is + authorized to represent. + + type (required, string): The type of identifier (see below and + Section 9.7.7). + + value (required, string): The identifier itself. + + status (required, string): The status of this authorization. + Possible values are "pending", "valid", "invalid", "deactivated", + "expired", and "revoked". See Section 7.1.6. + + expires (optional, string): The timestamp after which the server + will consider this authorization invalid, encoded in the format + specified in [RFC3339]. This field is REQUIRED for objects with + "valid" in the "status" field. + + challenges (required, array of objects): For pending authorizations, + the challenges that the client can fulfill in order to prove + possession of the identifier. For valid authorizations, the + challenge that was validated. For invalid authorizations, the + challenge that was attempted and failed. Each array entry is an + object with parameters required to validate the challenge. A + client should attempt to fulfill one of these challenges, and a + server should consider any one of the challenges sufficient to + make the authorization valid. + + wildcard (optional, boolean): This field MUST be present and true + for authorizations created as a result of a newOrder request + containing a DNS identifier with a value that was a wildcard + domain name. For other authorizations, it MUST be absent. + Wildcard domain names are described in Section 7.1.3. + + The only type of identifier defined by this specification is a fully + qualified domain name (type: "dns"). The domain name MUST be encoded + in the form in which it would appear in a certificate. That is, it + MUST be encoded according to the rules in Section 7 of [RFC5280]. + Servers MUST verify any identifier values that begin with the ASCII- + Compatible Encoding prefix "xn--" as defined in [RFC5890] are + properly encoded. Wildcard domain names (with "*" as the first + label) MUST NOT be included in authorization objects. If an + authorization object conveys authorization for the base domain of a + newOrder DNS identifier containing a wildcard domain name, then the + optional authorizations "wildcard" field MUST be present with a value + of true. + + + + +Barnes, et al. Standards Track [Page 29] + +RFC 8555 ACME March 2019 + + + Section 8 describes a set of challenges for domain name validation. + + { + "status": "valid", + "expires": "2015-03-01T14:09:07.99Z", + + "identifier": { + "type": "dns", + "value": "www.example.org" + }, + + "challenges": [ + { + "url": "https://example.com/acme/chall/prV_B7yEyA4", + "type": "http-01", + "status": "valid", + "token": "DGyRejmCefe7v4NfDGDKfA", + "validated": "2014-12-01T12:05:58.16Z" + } + ], + + "wildcard": false + } + +7.1.5. Challenge Objects + + An ACME challenge object represents a server's offer to validate a + client's possession of an identifier in a specific way. Unlike the + other objects listed above, there is not a single standard structure + for a challenge object. The contents of a challenge object depend on + the validation method being used. The general structure of challenge + objects and an initial set of validation methods are described in + Section 8. + +7.1.6. Status Changes + + Each ACME object type goes through a simple state machine over its + lifetime. The "status" field of the object indicates which state the + object is currently in. + + Challenge objects are created in the "pending" state. They + transition to the "processing" state when the client responds to the + challenge (see Section 7.5.1) and the server begins attempting to + validate that the client has completed the challenge. Note that + within the "processing" state, the server may attempt to validate the + challenge multiple times (see Section 8.2). Likewise, client + + + + + +Barnes, et al. Standards Track [Page 30] + +RFC 8555 ACME March 2019 + + + requests for retries do not cause a state change. If validation is + successful, the challenge moves to the "valid" state; if there is an + error, the challenge moves to the "invalid" state. + + pending + | + | Receive + | response + V + processing <-+ + | | | Server retry or + | | | client retry request + | +----+ + | + | + Successful | Failed + validation | validation + +---------+---------+ + | | + V V + valid invalid + + State Transitions for Challenge Objects + + Authorization objects are created in the "pending" state. If one of + the challenges listed in the authorization transitions to the "valid" + state, then the authorization also changes to the "valid" state. If + the client attempts to fulfill a challenge and fails, or if there is + an error while the authorization is still pending, then the + authorization transitions to the "invalid" state. Once the + authorization is in the "valid" state, it can expire ("expired"), be + deactivated by the client ("deactivated", see Section 7.5.2), or + revoked by the server ("revoked"). + + + + + + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 31] + +RFC 8555 ACME March 2019 + + + pending --------------------+ + | | + Challenge failure | | + or | | + Error | Challenge valid | + +---------+---------+ | + | | | + V V | + invalid valid | + | | + | | + | | + +--------------+--------------+ + | | | + | | | + Server | Client | Time after | + revoke | deactivate | "expires" | + V V V + revoked deactivated expired + + State Transitions for Authorization Objects + + Order objects are created in the "pending" state. Once all of the + authorizations listed in the order object are in the "valid" state, + the order transitions to the "ready" state. The order moves to the + "processing" state after the client submits a request to the order's + "finalize" URL and the CA begins the issuance process for the + certificate. Once the certificate is issued, the order enters the + "valid" state. If an error occurs at any of these stages, the order + moves to the "invalid" state. The order also moves to the "invalid" + state if it expires or one of its authorizations enters a final state + other than "valid" ("expired", "revoked", or "deactivated"). + + + + + + + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 32] + +RFC 8555 ACME March 2019 + + + pending --------------+ + | | + | All authz | + | "valid" | + V | + ready ---------------+ + | | + | Receive | + | finalize | + | request | + V | + processing ------------+ + | | + | Certificate | Error or + | issued | Authorization failure + V V + valid invalid + + State Transitions for Order Objects + + Account objects are created in the "valid" state, since no further + action is required to create an account after a successful newAccount + request. If the account is deactivated by the client or revoked by + the server, it moves to the corresponding state. + + valid + | + | + +-----------+-----------+ + Client | Server | + deactiv.| revoke | + V V + deactivated revoked + + State Transitions for Account Objects + + Note that some of these states may not ever appear in a "status" + field, depending on server behavior. For example, a server that + issues synchronously will never show an order in the "processing" + state. A server that deletes expired authorizations immediately will + never show an authorization in the "expired" state. + + + + + + + + + + +Barnes, et al. Standards Track [Page 33] + +RFC 8555 ACME March 2019 + + +7.2. Getting a Nonce + + Before sending a POST request to the server, an ACME client needs to + have a fresh anti-replay nonce to put in the "nonce" header of the + JWS. In most cases, the client will have gotten a nonce from a + previous request. However, the client might sometimes need to get a + new nonce, e.g., on its first request to the server or if an existing + nonce is no longer valid. + + To get a fresh nonce, the client sends a HEAD request to the newNonce + resource on the server. The server's response MUST include a Replay- + Nonce header field containing a fresh nonce and SHOULD have status + code 200 (OK). The server MUST also respond to GET requests for this + resource, returning an empty body (while still providing a Replay- + Nonce header) with a status code of 204 (No Content). + + HEAD /acme/new-nonce HTTP/1.1 + Host: example.com + + HTTP/1.1 200 OK + Replay-Nonce: oFvnlFP1wIhRlYS2jTaXbA + Cache-Control: no-store + Link: ;rel="index" + + Proxy caching of responses from the newNonce resource can cause + clients to receive the same nonce repeatedly, leading to "badNonce" + errors. The server MUST include a Cache-Control header field with + the "no-store" directive in responses for the newNonce resource, in + order to prevent caching of this resource. + +7.3. Account Management + + In this section, we describe how an ACME client can create an account + on an ACME server and perform some modifications to the account after + it has been created. + + A client creates a new account with the server by sending a POST + request to the server's newAccount URL. The body of the request is a + stub account object containing some subset of the following fields: + + contact (optional, array of string): Same meaning as the + corresponding server field defined in Section 7.1.2. + + termsOfServiceAgreed (optional, boolean): Same meaning as the + corresponding server field defined in Section 7.1.2. + + + + + + +Barnes, et al. Standards Track [Page 34] + +RFC 8555 ACME March 2019 + + + onlyReturnExisting (optional, boolean): If this field is present + with the value "true", then the server MUST NOT create a new + account if one does not already exist. This allows a client to + look up an account URL based on an account key (see + Section 7.3.1). + + externalAccountBinding (optional, object): Same meaning as the + corresponding server field defined in Section 7.1.2 + + POST /acme/new-account HTTP/1.1 + Host: example.com + Content-Type: application/jose+json + + { + "protected": base64url({ + "alg": "ES256", + "jwk": {...}, + "nonce": "6S8IqOGY7eL2lsGoTZYifg", + "url": "https://example.com/acme/new-account" + }), + "payload": base64url({ + "termsOfServiceAgreed": true, + "contact": [ + "mailto:cert-admin@example.org", + "mailto:admin@example.org" + ] + }), + "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I" + } + + The server MUST ignore any values provided in the "orders" fields in + account objects sent by the client, as well as any other fields that + it does not recognize. If new fields are specified in the future, + the specification of those fields MUST describe whether they can be + provided by the client. The server MUST NOT reflect the + "onlyReturnExisting" field or any unrecognized fields in the + resulting account object. This allows clients to detect when servers + do not support an extension field. + + The server SHOULD validate that the contact URLs in the "contact" + field are valid and supported by the server. If the server validates + contact URLs, it MUST support the "mailto" scheme. Clients MUST NOT + provide a "mailto" URL in the "contact" field that contains "hfields" + [RFC6068] or more than one "addr-spec" in the "to" component. If a + server encounters a "mailto" contact URL that does not meet these + criteria, then it SHOULD reject it as invalid. + + + + + +Barnes, et al. Standards Track [Page 35] + +RFC 8555 ACME March 2019 + + + If the server rejects a contact URL for using an unsupported scheme, + it MUST return an error of type "unsupportedContact", with a + description of the error and what types of contact URLs the server + considers acceptable. If the server rejects a contact URL for using + a supported scheme but an invalid value, then the server MUST return + an error of type "invalidContact". + + If the server wishes to require the client to agree to terms under + which the ACME service is to be used, it MUST indicate the URL where + such terms can be accessed in the "termsOfService" subfield of the + "meta" field in the directory object, and the server MUST reject + newAccount requests that do not have the "termsOfServiceAgreed" field + set to "true". Clients SHOULD NOT automatically agree to terms by + default. Rather, they SHOULD require some user interaction for + agreement to terms. + + The server creates an account and stores the public key used to + verify the JWS (i.e., the "jwk" element of the JWS header) to + authenticate future requests from the account. The server returns + this account object in a 201 (Created) response, with the account URL + in a Location header field. The account URL is used as the "kid" + value in the JWS authenticating subsequent requests by this account + (see Section 6.2). The account URL is also used for requests for + management actions on this account, as described below. + + HTTP/1.1 201 Created + Content-Type: application/json + Replay-Nonce: D8s4D2mLs8Vn-goWuPQeKA + Link: ;rel="index" + Location: https://example.com/acme/acct/evOfKhNU60wg + + { + "status": "valid", + + "contact": [ + "mailto:cert-admin@example.org", + "mailto:admin@example.org" + ], + + "orders": "https://example.com/acme/acct/evOfKhNU60wg/orders" + } + +7.3.1. Finding an Account URL Given a Key + + If the server receives a newAccount request signed with a key for + which it already has an account registered with the provided account + key, then it MUST return a response with status code 200 (OK) and + provide the URL of that account in the Location header field. The + + + +Barnes, et al. Standards Track [Page 36] + +RFC 8555 ACME March 2019 + + + body of this response represents the account object as it existed on + the server before this request; any fields in the request object MUST + be ignored. This allows a client that has an account key but not the + corresponding account URL to recover the account URL. + + If a client wishes to find the URL for an existing account and does + not want an account to be created if one does not already exist, then + it SHOULD do so by sending a POST request to the newAccount URL with + a JWS whose payload has an "onlyReturnExisting" field set to "true" + ({"onlyReturnExisting": true}). If a client sends such a request and + an account does not exist, then the server MUST return an error + response with status code 400 (Bad Request) and type + "urn:ietf:params:acme:error:accountDoesNotExist". + +7.3.2. Account Update + + If the client wishes to update this information in the future, it + sends a POST request with updated information to the account URL. + The server MUST ignore any updates to the "orders" field, + "termsOfServiceAgreed" field (see Section 7.3.3), the "status" field + (except as allowed by Section 7.3.6), or any other fields it does not + recognize. If the server accepts the update, it MUST return a + response with a 200 (OK) status code and the resulting account + object. + + For example, to update the contact information in the above account, + the client could send the following request: + + POST /acme/acct/evOfKhNU60wg HTTP/1.1 + Host: example.com + Content-Type: application/jose+json + + { + "protected": base64url({ + "alg": "ES256", + "kid": "https://example.com/acme/acct/evOfKhNU60wg", + "nonce": "ax5RnthDqp_Yf4_HZnFLmA", + "url": "https://example.com/acme/acct/evOfKhNU60wg" + }), + "payload": base64url({ + "contact": [ + "mailto:certificates@example.org", + "mailto:admin@example.org" + ] + }), + "signature": "hDXzvcj8T6fbFbmn...rDzXzzvzpRy64N0o" + } + + + + +Barnes, et al. Standards Track [Page 37] + +RFC 8555 ACME March 2019 + + +7.3.3. Changes of Terms of Service + + As described above, a client can indicate its agreement with the CA's + terms of service by setting the "termsOfServiceAgreed" field in its + account object to "true". + + If the server has changed its terms of service since a client + initially agreed, and the server is unwilling to process a request + without explicit agreement to the new terms, then it MUST return an + error response with status code 403 (Forbidden) and type + "urn:ietf:params:acme:error:userActionRequired". This response MUST + include a Link header field with link relation "terms-of-service" and + the latest terms-of-service URL. + + The problem document returned with the error MUST also include an + "instance" field, indicating a URL that the client should direct a + human user to visit in order for instructions on how to agree to the + terms. + + HTTP/1.1 403 Forbidden + Replay-Nonce: T81bdZroZ2ITWSondpTmAw + Link: ;rel="index" + Link: ;rel="terms-of-service" + Content-Type: application/problem+json + Content-Language: en + + { + "type": "urn:ietf:params:acme:error:userActionRequired", + "detail": "Terms of service have changed", + "instance": "https://example.com/acme/agreement/?token=W8Ih3PswD-8" + } + +7.3.4. External Account Binding + + The server MAY require a value for the "externalAccountBinding" field + to be present in "newAccount" requests. This can be used to + associate an ACME account with an existing account in a non-ACME + system, such as a CA customer database. + + To enable ACME account binding, the CA operating the ACME server + needs to provide the ACME client with a MAC key and a key identifier, + using some mechanism outside of ACME. The key identifier MUST be an + ASCII string. The MAC key SHOULD be provided in base64url-encoded + form, to maximize compatibility between non-ACME provisioning systems + and ACME clients. + + + + + + +Barnes, et al. Standards Track [Page 38] + +RFC 8555 ACME March 2019 + + + The ACME client then computes a binding JWS to indicate the external + account holder's approval of the ACME account key. The payload of + this JWS is the ACME account key being registered, in JWK form. The + protected header of the JWS MUST meet the following criteria: + + o The "alg" field MUST indicate a MAC-based algorithm + + o The "kid" field MUST contain the key identifier provided by the CA + + o The "nonce" field MUST NOT be present + + o The "url" field MUST be set to the same value as the outer JWS + + The "signature" field of the JWS will contain the MAC value computed + with the MAC key provided by the CA. + + POST /acme/new-account HTTP/1.1 + Host: example.com + Content-Type: application/jose+json + + { + "protected": base64url({ + "alg": "ES256", + "jwk": /* account key */, + "nonce": "K60BWPrMQG9SDxBDS_xtSw", + "url": "https://example.com/acme/new-account" + }), + "payload": base64url({ + "contact": [ + "mailto:cert-admin@example.org", + "mailto:admin@example.org" + ], + "termsOfServiceAgreed": true, + + "externalAccountBinding": { + "protected": base64url({ + "alg": "HS256", + "kid": /* key identifier from CA */, + "url": "https://example.com/acme/new-account" + }), + "payload": base64url(/* same as in "jwk" above */), + "signature": /* MAC using MAC key from CA */ + } + }), + "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4" + } + + + + + +Barnes, et al. Standards Track [Page 39] + +RFC 8555 ACME March 2019 + + + If such a CA requires that newAccount requests contain an + "externalAccountBinding" field, then it MUST provide the value "true" + in the "externalAccountRequired" subfield of the "meta" field in the + directory object. If the CA receives a newAccount request without an + "externalAccountBinding" field, then it SHOULD reply with an error of + type "externalAccountRequired". + + When a CA receives a newAccount request containing an + "externalAccountBinding" field, it decides whether or not to verify + the binding. If the CA does not verify the binding, then it MUST NOT + reflect the "externalAccountBinding" field in the resulting account + object (if any). To verify the account binding, the CA MUST take the + following steps: + + 1. Verify that the value of the field is a well-formed JWS + + 2. Verify that the JWS protected field meets the above criteria + + 3. Retrieve the MAC key corresponding to the key identifier in the + "kid" field + + 4. Verify that the MAC on the JWS verifies using that MAC key + + 5. Verify that the payload of the JWS represents the same key as was + used to verify the outer JWS (i.e., the "jwk" field of the outer + JWS) + + If all of these checks pass and the CA creates a new account, then + the CA may consider the new account associated with the external + account corresponding to the MAC key. The account object the CA + returns MUST include an "externalAccountBinding" field with the same + value as the field in the request. If any of these checks fail, then + the CA MUST reject the newAccount request. + +7.3.5. Account Key Rollover + + A client may wish to change the public key that is associated with an + account in order to recover from a key compromise or proactively + mitigate the impact of an unnoticed key compromise. + + To change the key associated with an account, the client sends a + request to the server containing signatures by both the old and new + keys. The signature by the new key covers the account URL and the + old key, signifying a request by the new key holder to take over the + account from the old key holder. The signature by the old key covers + this request and its signature, and indicates the old key holder's + assent to the rollover request. + + + + +Barnes, et al. Standards Track [Page 40] + +RFC 8555 ACME March 2019 + + + To create this request object, the client first constructs a + keyChange object describing the account to be updated and its account + key: + + account (required, string): The URL for the account being modified. + The content of this field MUST be the exact string provided in the + Location header field in response to the newAccount request that + created the account. + + oldKey (required, JWK): The JWK representation of the old key. + + The client then encapsulates the keyChange object in an "inner" JWS, + signed with the requested new account key. This "inner" JWS becomes + the payload for the "outer" JWS that is the body of the ACME request. + + The outer JWS MUST meet the normal requirements for an ACME JWS + request body (see Section 6.2). The inner JWS MUST meet the normal + requirements, with the following differences: + + o The inner JWS MUST have a "jwk" header parameter, containing the + public key of the new key pair. + + o The inner JWS MUST have the same "url" header parameter as the + outer JWS. + + o The inner JWS MUST omit the "nonce" header parameter. + + This transaction has signatures from both the old and new keys so + that the server can verify that the holders of the two keys both + agree to the change. The signatures are nested to preserve the + property that all signatures on POST messages are signed by exactly + one key. The "inner" JWS effectively represents a request by the + holder of the new key to take over the account form the holder of the + old key. The "outer" JWS represents the current account holder's + assent to this request. + + + + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 41] + +RFC 8555 ACME March 2019 + + + POST /acme/key-change HTTP/1.1 + Host: example.com + Content-Type: application/jose+json + + { + "protected": base64url({ + "alg": "ES256", + "kid": "https://example.com/acme/acct/evOfKhNU60wg", + "nonce": "S9XaOcxP5McpnTcWPIhYuB", + "url": "https://example.com/acme/key-change" + }), + "payload": base64url({ + "protected": base64url({ + "alg": "ES256", + "jwk": /* new key */, + "url": "https://example.com/acme/key-change" + }), + "payload": base64url({ + "account": "https://example.com/acme/acct/evOfKhNU60wg", + "oldKey": /* old key */ + }), + "signature": "Xe8B94RD30Azj2ea...8BmZIRtcSKPSd8gU" + }), + "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4" + } + + On receiving a keyChange request, the server MUST perform the + following steps in addition to the typical JWS validation: + + 1. Validate the POST request belongs to a currently active account, + as described in Section 6. + + 2. Check that the payload of the JWS is a well-formed JWS object + (the "inner JWS"). + + 3. Check that the JWS protected header of the inner JWS has a "jwk" + field. + + 4. Check that the inner JWS verifies using the key in its "jwk" + field. + + 5. Check that the payload of the inner JWS is a well-formed + keyChange object (as described above). + + 6. Check that the "url" parameters of the inner and outer JWSs are + the same. + + + + + +Barnes, et al. Standards Track [Page 42] + +RFC 8555 ACME March 2019 + + + 7. Check that the "account" field of the keyChange object contains + the URL for the account matching the old key (i.e., the "kid" + field in the outer JWS). + + 8. Check that the "oldKey" field of the keyChange object is the same + as the account key for the account in question. + + 9. Check that no account exists whose account key is the same as the + key in the "jwk" header parameter of the inner JWS. + + If all of these checks pass, then the server updates the + corresponding account by replacing the old account key with the new + public key and returns status code 200 (OK). Otherwise, the server + responds with an error status code and a problem document describing + the error. If there is an existing account with the new key + provided, then the server SHOULD use status code 409 (Conflict) and + provide the URL of that account in the Location header field. + + Note that changing the account key for an account SHOULD NOT have any + other impact on the account. For example, the server MUST NOT + invalidate pending orders or authorization transactions based on a + change of account key. + +7.3.6. Account Deactivation + + A client can deactivate an account by posting a signed update to the + account URL with a status field of "deactivated". Clients may wish + to do this when the account key is compromised or decommissioned. A + deactivated account can no longer request certificate issuance or + access resources related to the account, such as orders or + authorizations. If a server receives a POST or POST-as-GET from a + deactivated account, it MUST return an error response with status + code 401 (Unauthorized) and type + "urn:ietf:params:acme:error:unauthorized". + + + + + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 43] + +RFC 8555 ACME March 2019 + + + POST /acme/acct/evOfKhNU60wg HTTP/1.1 + Host: example.com + Content-Type: application/jose+json + + { + "protected": base64url({ + "alg": "ES256", + "kid": "https://example.com/acme/acct/evOfKhNU60wg", + "nonce": "ntuJWWSic4WVNSqeUmshgg", + "url": "https://example.com/acme/acct/evOfKhNU60wg" + }), + "payload": base64url({ + "status": "deactivated" + }), + "signature": "earzVLd3m5M4xJzR...bVTqn7R08AKOVf3Y" + } + + The server MUST verify that the request is signed by the account key. + If the server accepts the deactivation request, it replies with a 200 + (OK) status code and the current contents of the account object. + + Once an account is deactivated, the server MUST NOT accept further + requests authorized by that account's key. The server SHOULD cancel + any pending operations authorized by the account's key, such as + certificate orders. A server may take a variety of actions in + response to an account deactivation, e.g., deleting data related to + that account or sending mail to the account's contacts. Servers + SHOULD NOT revoke certificates issued by the deactivated account, + since this could cause operational disruption for servers using these + certificates. ACME does not provide a way to reactivate a + deactivated account. + +7.4. Applying for Certificate Issuance + + The client begins the certificate issuance process by sending a POST + request to the server's newOrder resource. The body of the POST is a + JWS object whose JSON payload is a subset of the order object defined + in Section 7.1.3, containing the fields that describe the certificate + to be issued: + + identifiers (required, array of object): An array of identifier + objects that the client wishes to submit an order for. + + type (required, string): The type of identifier. + + value (required, string): The identifier itself. + + + + + +Barnes, et al. Standards Track [Page 44] + +RFC 8555 ACME March 2019 + + + notBefore (optional, string): The requested value of the notBefore + field in the certificate, in the date format defined in [RFC3339]. + + notAfter (optional, string): The requested value of the notAfter + field in the certificate, in the date format defined in [RFC3339]. + + POST /acme/new-order HTTP/1.1 + Host: example.com + Content-Type: application/jose+json + + { + "protected": base64url({ + "alg": "ES256", + "kid": "https://example.com/acme/acct/evOfKhNU60wg", + "nonce": "5XJ1L3lEkMG7tR6pA00clA", + "url": "https://example.com/acme/new-order" + }), + "payload": base64url({ + "identifiers": [ + { "type": "dns", "value": "www.example.org" }, + { "type": "dns", "value": "example.org" } + ], + "notBefore": "2016-01-01T00:04:00+04:00", + "notAfter": "2016-01-08T00:04:00+04:00" + }), + "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g" + } + + The server MUST return an error if it cannot fulfill the request as + specified, and it MUST NOT issue a certificate with contents other + than those requested. If the server requires the request to be + modified in a certain way, it should indicate the required changes + using an appropriate error type and description. + + If the server is willing to issue the requested certificate, it + responds with a 201 (Created) response. The body of this response is + an order object reflecting the client's request and any + authorizations the client must complete before the certificate will + be issued. + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 45] + +RFC 8555 ACME March 2019 + + + HTTP/1.1 201 Created + Replay-Nonce: MYAuvOpaoIiywTezizk5vw + Link: ;rel="index" + Location: https://example.com/acme/order/TOlocE8rfgo + + { + "status": "pending", + "expires": "2016-01-05T14:09:07.99Z", + + "notBefore": "2016-01-01T00:00:00Z", + "notAfter": "2016-01-08T00:00:00Z", + + "identifiers": [ + { "type": "dns", "value": "www.example.org" }, + { "type": "dns", "value": "example.org" } + ], + + "authorizations": [ + "https://example.com/acme/authz/PAniVnsZcis", + "https://example.com/acme/authz/r4HqLzrSrpI" + ], + + "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize" + } + + The order object returned by the server represents a promise that if + the client fulfills the server's requirements before the "expires" + time, then the server will be willing to finalize the order upon + request and issue the requested certificate. In the order object, + any authorization referenced in the "authorizations" array whose + status is "pending" represents an authorization transaction that the + client must complete before the server will issue the certificate + (see Section 7.5). If the client fails to complete the required + actions before the "expires" time, then the server SHOULD change the + status of the order to "invalid" and MAY delete the order resource. + Clients MUST NOT make any assumptions about the sort order of + "identifiers" or "authorizations" elements in the returned order + object. + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 46] + +RFC 8555 ACME March 2019 + + + Once the client believes it has fulfilled the server's requirements, + it should send a POST request to the order resource's finalize URL. + The POST body MUST include a CSR: + + csr (required, string): A CSR encoding the parameters for the + certificate being requested [RFC2986]. The CSR is sent in the + base64url-encoded version of the DER format. (Note: Because this + field uses base64url, and does not include headers, it is + different from PEM.) + + POST /acme/order/TOlocE8rfgo/finalize HTTP/1.1 + Host: example.com + Content-Type: application/jose+json + + { + "protected": base64url({ + "alg": "ES256", + "kid": "https://example.com/acme/acct/evOfKhNU60wg", + "nonce": "MSF2j2nawWHPxxkE3ZJtKQ", + "url": "https://example.com/acme/order/TOlocE8rfgo/finalize" + }), + "payload": base64url({ + "csr": "MIIBPTCBxAIBADBFMQ...FS6aKdZeGsysoCo4H9P", + }), + "signature": "uOrUfIIk5RyQ...nw62Ay1cl6AB" + } + + The CSR encodes the client's requests with regard to the content of + the certificate to be issued. The CSR MUST indicate the exact same + set of requested identifiers as the initial newOrder request. + Identifiers of type "dns" MUST appear either in the commonName + portion of the requested subject name or in an extensionRequest + attribute [RFC2985] requesting a subjectAltName extension, or both. + (These identifiers may appear in any sort order.) Specifications + that define new identifier types must specify where in the + certificate signing request these identifiers can appear. + + A request to finalize an order will result in an error if the CA is + unwilling to issue a certificate corresponding to the submitted CSR. + For example: + + o If the CSR and order identifiers differ + + o If the account is not authorized for the identifiers indicated in + the CSR + + o If the CSR requests extensions that the CA is not willing to + include + + + +Barnes, et al. Standards Track [Page 47] + +RFC 8555 ACME March 2019 + + + In such cases, the problem document returned by the server SHOULD use + error code "badCSR" and describe specific reasons the CSR was + rejected in its "detail" field. After returning such an error, the + server SHOULD leave the order in the "ready" state, to allow the + client to submit a new finalize request with an amended CSR. + + A request to finalize an order will result in error if the order is + not in the "ready" state. In such cases, the server MUST return a + 403 (Forbidden) error with a problem document of type + "orderNotReady". The client should then send a POST-as-GET request + to the order resource to obtain its current state. The status of the + order will indicate what action the client should take (see below). + + If a request to finalize an order is successful, the server will + return a 200 (OK) with an updated order object. The status of the + order will indicate what action the client should take: + + o "invalid": The certificate will not be issued. Consider this + order process abandoned. + + o "pending": The server does not believe that the client has + fulfilled the requirements. Check the "authorizations" array for + entries that are still pending. + + o "ready": The server agrees that the requirements have been + fulfilled, and is awaiting finalization. Submit a finalization + request. + + o "processing": The certificate is being issued. Send a POST-as-GET + request after the time given in the Retry-After header field of + the response, if any. + + o "valid": The server has issued the certificate and provisioned its + URL to the "certificate" field of the order. Download the + certificate. + + + + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 48] + +RFC 8555 ACME March 2019 + + + HTTP/1.1 200 OK + Replay-Nonce: CGf81JWBsq8QyIgPCi9Q9X + Link: ;rel="index" + Location: https://example.com/acme/order/TOlocE8rfgo + + { + "status": "valid", + "expires": "2016-01-20T14:09:07.99Z", + + "notBefore": "2016-01-01T00:00:00Z", + "notAfter": "2016-01-08T00:00:00Z", + + "identifiers": [ + { "type": "dns", "value": "www.example.org" }, + { "type": "dns", "value": "example.org" } + ], + + "authorizations": [ + "https://example.com/acme/authz/PAniVnsZcis", + "https://example.com/acme/authz/r4HqLzrSrpI" + ], + + "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize", + + "certificate": "https://example.com/acme/cert/mAt3xBGaobw" + } + +7.4.1. Pre-authorization + + The order process described above presumes that authorization objects + are created reactively, in response to a certificate order. Some + servers may also wish to enable clients to obtain authorization for + an identifier proactively, outside of the context of a specific + issuance. For example, a client hosting virtual servers for a + collection of names might wish to obtain authorization before any + virtual servers are created and only create a certificate when a + virtual server starts up. + + In some cases, a CA running an ACME server might have a completely + external, non-ACME process for authorizing a client to issue + certificates for an identifier. In these cases, the CA should + provision its ACME server with authorization objects corresponding to + these authorizations and reflect them as already valid in any orders + submitted by the client. + + If a CA wishes to allow pre-authorization within ACME, it can offer a + "new authorization" resource in its directory by adding the field + "newAuthz" with a URL for the newAuthz resource. + + + +Barnes, et al. Standards Track [Page 49] + +RFC 8555 ACME March 2019 + + + To request authorization for an identifier, the client sends a POST + request to the newAuthz resource specifying the identifier for which + authorization is being requested. + + identifier (required, object): The identifier to appear in the + resulting authorization object (see Section 7.1.4). + + type (required, string): The type of identifier. + + value (required, string): The identifier itself. + + POST /acme/new-authz HTTP/1.1 + Host: example.com + Content-Type: application/jose+json + + { + "protected": base64url({ + "alg": "ES256", + "kid": "https://example.com/acme/acct/evOfKhNU60wg", + "nonce": "uQpSjlRb4vQVCjVYAyyUWg", + "url": "https://example.com/acme/new-authz" + }), + "payload": base64url({ + "identifier": { + "type": "dns", + "value": "example.org" + } + }), + "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" + } + + Note that because the identifier in a pre-authorization request is + the exact identifier to be included in the authorization object, pre- + authorization cannot be used to authorize issuance of certificates + containing wildcard domain names. + + Before processing the authorization request, the server SHOULD + determine whether it is willing to issue certificates for the + identifier. For example, the server should check that the identifier + is of a supported type. Servers might also check names against a + blacklist of known high-value identifiers. If the server is + unwilling to issue for the identifier, it SHOULD return an error with + status code 403 (Forbidden), with a problem document describing the + reason for the rejection. + + + + + + + +Barnes, et al. Standards Track [Page 50] + +RFC 8555 ACME March 2019 + + + If the server is willing to proceed, it builds a pending + authorization object from the inputs submitted by the client: + + o "identifier" the identifier submitted by the client + + o "status" MUST be "pending" unless the server has out-of-band + information about the client's authorization status + + o "challenges" as selected by the server's policy for this + identifier + + The server allocates a new URL for this authorization and returns a + 201 (Created) response with the authorization URL in the Location + header field and the JSON authorization object in the body. The + client then follows the process described in Section 7.5 to complete + the authorization process. + +7.4.2. Downloading the Certificate + + To download the issued certificate, the client simply sends a POST- + as-GET request to the certificate URL. + + The default format of the certificate is application/pem-certificate- + chain (see Section 9). + + The server MAY provide one or more link relation header fields + [RFC8288] with relation "alternate". Each such field SHOULD express + an alternative certificate chain starting with the same end-entity + certificate. This can be used to express paths to various trust + anchors. Clients can fetch these alternates and use their own + heuristics to decide which is optimal. + + + + + + + + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 51] + +RFC 8555 ACME March 2019 + + + POST /acme/cert/mAt3xBGaobw HTTP/1.1 + Host: example.com + Content-Type: application/jose+json + Accept: application/pem-certificate-chain + + { + "protected": base64url({ + "alg": "ES256", + "kid": "https://example.com/acme/acct/evOfKhNU60wg", + "nonce": "uQpSjlRb4vQVCjVYAyyUWg", + "url": "https://example.com/acme/cert/mAt3xBGaobw" + }), + "payload": "", + "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" + } + + HTTP/1.1 200 OK + Content-Type: application/pem-certificate-chain + Link: ;rel="index" + + -----BEGIN CERTIFICATE----- + [End-entity certificate contents] + -----END CERTIFICATE----- + -----BEGIN CERTIFICATE----- + [Issuer certificate contents] + -----END CERTIFICATE----- + -----BEGIN CERTIFICATE----- + [Other certificate contents] + -----END CERTIFICATE----- + + A certificate resource represents a single, immutable certificate. + If the client wishes to obtain a renewed certificate, the client + initiates a new order process to request one. + + Because certificate resources are immutable once issuance is + complete, the server MAY enable the caching of the resource by adding + Expires and Cache-Control header fields specifying a point in time in + the distant future. These header fields have no relation to the + certificate's period of validity. + + The ACME client MAY request other formats by including an Accept + header field [RFC7231] in its request. For example, the client could + use the media type "application/pkix-cert" [RFC2585] or "application/ + pkcs7-mime" [RFC5751] to request the end-entity certificate in DER + format. Server support for alternate formats is OPTIONAL. For + formats that can only express a single certificate, the server SHOULD + + + + + +Barnes, et al. Standards Track [Page 52] + +RFC 8555 ACME March 2019 + + + provide one or more "Link: rel="up"" header fields pointing to an + issuer or issuers so that ACME clients can build a certificate chain + as defined in TLS (see Section 4.4.2 of [RFC8446]). + +7.5. Identifier Authorization + + The identifier authorization process establishes the authorization of + an account to manage certificates for a given identifier. This + process assures the server of two things: + + 1. That the client controls the private key of the account key pair, + and + + 2. That the client controls the identifier in question. + + This process may be repeated to associate multiple identifiers with + an account (e.g., to request certificates with multiple identifiers) + or to associate multiple accounts with an identifier (e.g., to allow + multiple entities to manage certificates). + + Authorization resources are created by the server in response to + newOrder or newAuthz requests submitted by an account key holder; + their URLs are provided to the client in the responses to these + requests. The authorization object is implicitly tied to the account + key used to sign the request. + + When a client receives an order from the server in reply to a + newOrder request, it downloads the authorization resources by sending + POST-as-GET requests to the indicated URLs. If the client initiates + authorization using a request to the newAuthz resource, it will have + already received the pending authorization object in the response to + that request. + + + + + + + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 53] + +RFC 8555 ACME March 2019 + + + POST /acme/authz/PAniVnsZcis HTTP/1.1 + Host: example.com + Content-Type: application/jose+json + + { + "protected": base64url({ + "alg": "ES256", + "kid": "https://example.com/acme/acct/evOfKhNU60wg", + "nonce": "uQpSjlRb4vQVCjVYAyyUWg", + "url": "https://example.com/acme/authz/PAniVnsZcis" + }), + "payload": "", + "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" + } + + HTTP/1.1 200 OK + Content-Type: application/json + Link: ;rel="index" + + { + "status": "pending", + "expires": "2016-01-02T14:09:30Z", + + "identifier": { + "type": "dns", + "value": "www.example.org" + }, + + "challenges": [ + { + "type": "http-01", + "url": "https://example.com/acme/chall/prV_B7yEyA4", + "token": "DGyRejmCefe7v4NfDGDKfA" + }, + { + "type": "dns-01", + "url": "https://example.com/acme/chall/Rg5dV14Gh1Q", + "token": "DGyRejmCefe7v4NfDGDKfA" + } + ] + } + +7.5.1. Responding to Challenges + + To prove control of the identifier and receive authorization, the + client needs to provision the required challenge response based on + the challenge type and indicate to the server that it is ready for + the challenge validation to be attempted. + + + +Barnes, et al. Standards Track [Page 54] + +RFC 8555 ACME March 2019 + + + The client indicates to the server that it is ready for the challenge + validation by sending an empty JSON body ("{}") carried in a POST + request to the challenge URL (not the authorization URL). + + For example, if the client were to respond to the "http-01" challenge + in the above authorization, it would send the following request: + + POST /acme/chall/prV_B7yEyA4 HTTP/1.1 + Host: example.com + Content-Type: application/jose+json + + { + "protected": base64url({ + "alg": "ES256", + "kid": "https://example.com/acme/acct/evOfKhNU60wg", + "nonce": "Q_s3MWoqT05TrdkM2MTDcw", + "url": "https://example.com/acme/chall/prV_B7yEyA4" + }), + "payload": base64url({}), + "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ" + } + + The server updates the authorization document by updating its + representation of the challenge with the response object provided by + the client. The server MUST ignore any fields in the response object + that are not specified as response fields for this type of challenge. + Note that the challenges in this document do not define any response + fields, but future specifications might define them. The server + provides a 200 (OK) response with the updated challenge object as its + body. + + If the client's response is invalid for any reason or does not + provide the server with appropriate information to validate the + challenge, then the server MUST return an HTTP error. On receiving + such an error, the client SHOULD undo any actions that have been + taken to fulfill the challenge, e.g., removing files that have been + provisioned to a web server. + + The server is said to "finalize" the authorization when it has + completed one of the validations. This is done by assigning the + authorization a status of "valid" or "invalid", corresponding to + whether it considers the account authorized for the identifier. If + the final state is "valid", then the server MUST include an "expires" + field. When finalizing an authorization, the server MAY remove + challenges other than the one that was completed, and it may modify + the "expires" field. The server SHOULD NOT remove challenges with + status "invalid". + + + + +Barnes, et al. Standards Track [Page 55] + +RFC 8555 ACME March 2019 + + + Usually, the validation process will take some time, so the client + will need to poll the authorization resource to see when it is + finalized. For challenges where the client can tell when the server + has validated the challenge (e.g., by seeing an HTTP or DNS request + from the server), the client SHOULD NOT begin polling until it has + seen the validation request from the server. + + To check on the status of an authorization, the client sends a POST- + as-GET request to the authorization URL, and the server responds with + the current authorization object. In responding to poll requests + while the validation is still in progress, the server MUST return a + 200 (OK) response and MAY include a Retry-After header field to + suggest a polling interval to the client. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 56] + +RFC 8555 ACME March 2019 + + + POST /acme/authz/PAniVnsZcis HTTP/1.1 + Host: example.com + Content-Type: application/jose+json + + { + "protected": base64url({ + "alg": "ES256", + "kid": "https://example.com/acme/acct/evOfKhNU60wg", + "nonce": "uQpSjlRb4vQVCjVYAyyUWg", + "url": "https://example.com/acme/authz/PAniVnsZcis" + }), + "payload": "", + "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" + } + + HTTP/1.1 200 OK + Content-Type: application/json + Link: ;rel="index" + + { + "status": "valid", + "expires": "2018-09-09T14:09:01.13Z", + + "identifier": { + "type": "dns", + "value": "www.example.org" + }, + + "challenges": [ + { + "type": "http-01", + "url": "https://example.com/acme/chall/prV_B7yEyA4", + "status": "valid", + "validated": "2014-12-01T12:05:13.72Z", + "token": "IlirfxKKXAsHtmzK29Pj8A" + } + ] + } + +7.5.2. Deactivating an Authorization + + If a client wishes to relinquish its authorization to issue + certificates for an identifier, then it may request that the server + deactivate each authorization associated with it by sending POST + requests with the static object {"status": "deactivated"} to each + authorization URL. + + + + + +Barnes, et al. Standards Track [Page 57] + +RFC 8555 ACME March 2019 + + + POST /acme/authz/PAniVnsZcis HTTP/1.1 + Host: example.com + Content-Type: application/jose+json + + { + "protected": base64url({ + "alg": "ES256", + "kid": "https://example.com/acme/acct/evOfKhNU60wg", + "nonce": "xWCM9lGbIyCgue8di6ueWQ", + "url": "https://example.com/acme/authz/PAniVnsZcis" + }), + "payload": base64url({ + "status": "deactivated" + }), + "signature": "srX9Ji7Le9bjszhu...WTFdtujObzMtZcx4" + } + + The server MUST verify that the request is signed by the account key + corresponding to the account that owns the authorization. If the + server accepts the deactivation, it should reply with a 200 (OK) + status code and the updated contents of the authorization object. + + The server MUST NOT treat deactivated authorization objects as + sufficient for issuing certificates. + +7.6. Certificate Revocation + + To request that a certificate be revoked, the client sends a POST + request to the ACME server's revokeCert URL. The body of the POST is + a JWS object whose JSON payload contains the certificate to be + revoked: + + certificate (required, string): The certificate to be revoked, in + the base64url-encoded version of the DER format. (Note: Because + this field uses base64url, and does not include headers, it is + different from PEM.) + + reason (optional, int): One of the revocation reasonCodes defined in + Section 5.3.1 of [RFC5280] to be used when generating OCSP + responses and CRLs. If this field is not set, the server SHOULD + omit the reasonCode CRL entry extension when generating OCSP + responses and CRLs. The server MAY disallow a subset of + reasonCodes from being used by the user. If a request contains a + disallowed reasonCode, then the server MUST reject it with the + error type "urn:ietf:params:acme:error:badRevocationReason". The + problem document detail SHOULD indicate which reasonCodes are + allowed. + + + + +Barnes, et al. Standards Track [Page 58] + +RFC 8555 ACME March 2019 + + + Revocation requests are different from other ACME requests in that + they can be signed with either an account key pair or the key pair in + the certificate. + + Example using an account key pair for the signature: + + POST /acme/revoke-cert HTTP/1.1 + Host: example.com + Content-Type: application/jose+json + + { + "protected": base64url({ + "alg": "ES256", + "kid": "https://example.com/acme/acct/evOfKhNU60wg", + "nonce": "JHb54aT_KTXBWQOzGYkt9A", + "url": "https://example.com/acme/revoke-cert" + }), + "payload": base64url({ + "certificate": "MIIEDTCCAvegAwIBAgIRAP8...", + "reason": 4 + }), + "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" + } + + Example using the certificate key pair for the signature: + + POST /acme/revoke-cert HTTP/1.1 + Host: example.com + Content-Type: application/jose+json + + { + "protected": base64url({ + "alg": "RS256", + "jwk": /* certificate's public key */, + "nonce": "JHb54aT_KTXBWQOzGYkt9A", + "url": "https://example.com/acme/revoke-cert" + }), + "payload": base64url({ + "certificate": "MIIEDTCCAvegAwIBAgIRAP8...", + "reason": 1 + }), + "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" + } + + + + + + + + +Barnes, et al. Standards Track [Page 59] + +RFC 8555 ACME March 2019 + + + Before revoking a certificate, the server MUST verify that the key + used to sign the request is authorized to revoke the certificate. + The server MUST consider at least the following accounts authorized + for a given certificate: + + o the account that issued the certificate. + + o an account that holds authorizations for all of the identifiers in + the certificate. + + The server MUST also consider a revocation request valid if it is + signed with the private key corresponding to the public key in the + certificate. + + If the revocation succeeds, the server responds with status code 200 + (OK). If the revocation fails, the server returns an error. For + example, if the certificate has already been revoked, the server + returns an error response with status code 400 (Bad Request) and type + "urn:ietf:params:acme:error:alreadyRevoked". + + HTTP/1.1 200 OK + Replay-Nonce: IXVHDyxIRGcTE0VSblhPzw + Content-Length: 0 + Link: ;rel="index" + + --- or --- + + HTTP/1.1 403 Forbidden + Replay-Nonce: lXfyFzi6238tfPQRwgfmPU + Content-Type: application/problem+json + Content-Language: en + Link: ;rel="index" + + { + "type": "urn:ietf:params:acme:error:unauthorized", + "detail": "No authorization provided for name example.org" + } + +8. Identifier Validation Challenges + + There are few types of identifiers in the world for which there is a + standardized mechanism to prove possession of a given identifier. In + all practical cases, CAs rely on a variety of means to test whether + an entity applying for a certificate with a given identifier actually + controls that identifier. + + + + + + +Barnes, et al. Standards Track [Page 60] + +RFC 8555 ACME March 2019 + + + Challenges provide the server with assurance that an account holder + is also the entity that controls an identifier. For each type of + challenge, it must be the case that, in order for an entity to + successfully complete the challenge, the entity must both: + + o Hold the private key of the account key pair used to respond to + the challenge, and + + o Control the identifier in question. + + Section 10 documents how the challenges defined in this document meet + these requirements. New challenges will need to document how they + do. + + ACME uses an extensible challenge/response framework for identifier + validation. The server presents a set of challenges in the + authorization object it sends to a client (as objects in the + "challenges" array), and the client responds by sending a response + object in a POST request to a challenge URL. + + This section describes an initial set of challenge types. The + definition of a challenge type includes: + + 1. Content of challenge objects + + 2. Content of response objects + + 3. How the server uses the challenge and response to verify control + of an identifier + + Challenge objects all contain the following basic fields: + + type (required, string): The type of challenge encoded in the + object. + + url (required, string): The URL to which a response can be posted. + + status (required, string): The status of this challenge. Possible + values are "pending", "processing", "valid", and "invalid" (see + Section 7.1.6). + + validated (optional, string): The time at which the server validated + this challenge, encoded in the format specified in [RFC3339]. + This field is REQUIRED if the "status" field is "valid". + + + + + + + +Barnes, et al. Standards Track [Page 61] + +RFC 8555 ACME March 2019 + + + error (optional, object): Error that occurred while the server was + validating the challenge, if any, structured as a problem document + [RFC7807]. Multiple errors can be indicated by using subproblems + Section 6.7.1. A challenge object with an error MUST have status + equal to "invalid". + + All additional fields are specified by the challenge type. If the + server sets a challenge's "status" to "invalid", it SHOULD also + include the "error" field to help the client diagnose why the + challenge failed. + + Different challenges allow the server to obtain proof of different + aspects of control over an identifier. In some challenges, like HTTP + and DNS, the client directly proves its ability to do certain things + related to the identifier. The choice of which challenges to offer + to a client under which circumstances is a matter of server policy. + + The identifier validation challenges described in this section all + relate to validation of domain names. If ACME is extended in the + future to support other types of identifiers, there will need to be + new challenge types, and they will need to specify which types of + identifier they apply to. + +8.1. Key Authorizations + + All challenges defined in this document make use of a key + authorization string. A key authorization is a string that + concatenates the token for the challenge with a key fingerprint, + separated by a "." character: + + keyAuthorization = token || '.' || base64url(Thumbprint(accountKey)) + + The "Thumbprint" step indicates the computation specified in + [RFC7638], using the SHA-256 digest [FIPS180-4]. As noted in + [RFC7518] any prepended zero octets in the fields of a JWK object + MUST be stripped before doing the computation. + + As specified in the individual challenges below, the token for a + challenge is a string comprised entirely of characters in the URL- + safe base64 alphabet. The "||" operator indicates concatenation of + strings. + + + + + + + + + + +Barnes, et al. Standards Track [Page 62] + +RFC 8555 ACME March 2019 + + +8.2. Retrying Challenges + + ACME challenges typically require the client to set up some network- + accessible resource that the server can query in order to validate + that the client controls an identifier. In practice, it is not + uncommon for the server's queries to fail while a resource is being + set up, e.g., due to information propagating across a cluster or + firewall rules not being in place. + + Clients SHOULD NOT respond to challenges until they believe that the + server's queries will succeed. If a server's initial validation + query fails, the server SHOULD retry the query after some time, in + order to account for delay in setting up responses such as DNS + records or HTTP resources. The precise retry schedule is up to the + server, but server operators should keep in mind the operational + scenarios that the schedule is trying to accommodate. Given that + retries are intended to address things like propagation delays in + HTTP or DNS provisioning, there should not usually be any reason to + retry more often than every 5 or 10 seconds. While the server is + still trying, the status of the challenge remains "processing"; it is + only marked "invalid" once the server has given up. + + The server MUST provide information about its retry state to the + client via the "error" field in the challenge and the Retry-After + HTTP header field in response to requests to the challenge resource. + The server MUST add an entry to the "error" field in the challenge + after each failed validation query. The server SHOULD set the Retry- + After header field to a time after the server's next validation + query, since the status of the challenge will not change until that + time. + + Clients can explicitly request a retry by re-sending their response + to a challenge in a new POST request (with a new nonce, etc.). This + allows clients to request a retry when the state has changed (e.g., + after firewall rules have been updated). Servers SHOULD retry a + request immediately on receiving such a POST request. In order to + avoid denial-of-service attacks via client-initiated retries, servers + SHOULD rate-limit such requests. + +8.3. HTTP Challenge + + With HTTP validation, the client in an ACME transaction proves its + control over a domain name by proving that it can provision HTTP + resources on a server accessible under that domain name. The ACME + server challenges the client to provision a file at a specific path, + with a specific string as its content. + + + + + +Barnes, et al. Standards Track [Page 63] + +RFC 8555 ACME March 2019 + + + As a domain may resolve to multiple IPv4 and IPv6 addresses, the + server will connect to at least one of the hosts found in the DNS A + and AAAA records, at its discretion. Because many web servers + allocate a default HTTPS virtual host to a particular low-privilege + tenant user in a subtle and non-intuitive manner, the challenge must + be completed over HTTP, not HTTPS. + + type (required, string): The string "http-01". + + token (required, string): A random value that uniquely identifies + the challenge. This value MUST have at least 128 bits of entropy. + It MUST NOT contain any characters outside the base64url alphabet + and MUST NOT include base64 padding characters ("="). See + [RFC4086] for additional information on randomness requirements. + + { + "type": "http-01", + "url": "https://example.com/acme/chall/prV_B7yEyA4", + "status": "pending", + "token": "LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0" + } + + A client fulfills this challenge by constructing a key authorization + from the "token" value provided in the challenge and the client's + account key. The client then provisions the key authorization as a + resource on the HTTP server for the domain in question. + + The path at which the resource is provisioned is comprised of the + fixed prefix "/.well-known/acme-challenge/", followed by the "token" + value in the challenge. The value of the resource MUST be the ASCII + representation of the key authorization. + + GET /.well-known/acme-challenge/LoqXcYV8...jxAjEuX0 + Host: example.org + + HTTP/1.1 200 OK + Content-Type: application/octet-stream + + LoqXcYV8...jxAjEuX0.9jg46WB3...fm21mqTI + + (In the above, "..." indicates that the token and the JWK thumbprint + in the key authorization have been truncated to fit on the page.) + + A client responds with an empty object ({}) to acknowledge that the + challenge can be validated by the server. + + + + + + +Barnes, et al. Standards Track [Page 64] + +RFC 8555 ACME March 2019 + + + POST /acme/chall/prV_B7yEyA4 + Host: example.com + Content-Type: application/jose+json + + { + "protected": base64url({ + "alg": "ES256", + "kid": "https://example.com/acme/acct/evOfKhNU60wg", + "nonce": "UQI1PoRi5OuXzxuX7V7wL0", + "url": "https://example.com/acme/chall/prV_B7yEyA4" + }), + "payload": base64url({}), + "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" + } + + On receiving a response, the server constructs and stores the key + authorization from the challenge "token" value and the current client + account key. + + Given a challenge/response pair, the server verifies the client's + control of the domain by verifying that the resource was provisioned + as expected. + + 1. Construct a URL by populating the URL template [RFC6570] + "http://{domain}/.well-known/acme-challenge/{token}", where: + + * the domain field is set to the domain name being verified; and + + * the token field is set to the token in the challenge. + + 2. Verify that the resulting URL is well-formed. + + 3. Dereference the URL using an HTTP GET request. This request MUST + be sent to TCP port 80 on the HTTP server. + + 4. Verify that the body of the response is a well-formed key + authorization. The server SHOULD ignore whitespace characters at + the end of the body. + + 5. Verify that key authorization provided by the HTTP server matches + the key authorization stored by the server. + + The server SHOULD follow redirects when dereferencing the URL. + Clients might use redirects, for example, so that the response can be + provided by a centralized certificate management server. See + Section 10.2 for security considerations related to redirects. + + + + + +Barnes, et al. Standards Track [Page 65] + +RFC 8555 ACME March 2019 + + + If all of the above verifications succeed, then the validation is + successful. If the request fails, or the body does not pass these + checks, then it has failed. + + The client SHOULD de-provision the resource provisioned for this + challenge once the challenge is complete, i.e., once the "status" + field of the challenge has the value "valid" or "invalid". + + Note that because the token appears both in the request sent by the + ACME server and in the key authorization in the response, it is + possible to build clients that copy the token from request to + response. Clients should avoid this behavior because it can lead to + cross-site scripting vulnerabilities; instead, clients should be + explicitly configured on a per-challenge basis. A client that does + copy tokens from requests to responses MUST validate that the token + in the request matches the token syntax above (e.g., that it includes + only characters from the base64url alphabet). + +8.4. DNS Challenge + + When the identifier being validated is a domain name, the client can + prove control of that domain by provisioning a TXT resource record + containing a designated value for a specific validation domain name. + + type (required, string): The string "dns-01". + + token (required, string): A random value that uniquely identifies + the challenge. This value MUST have at least 128 bits of entropy. + It MUST NOT contain any characters outside the base64url alphabet, + including padding characters ("="). See [RFC4086] for additional + information on randomness requirements. + + { + "type": "dns-01", + "url": "https://example.com/acme/chall/Rg5dV14Gh1Q", + "status": "pending", + "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA" + } + + A client fulfills this challenge by constructing a key authorization + from the "token" value provided in the challenge and the client's + account key. The client then computes the SHA-256 digest [FIPS180-4] + of the key authorization. + + The record provisioned to the DNS contains the base64url encoding of + this digest. The client constructs the validation domain name by + prepending the label "_acme-challenge" to the domain name being + validated, then provisions a TXT record with the digest value under + + + +Barnes, et al. Standards Track [Page 66] + +RFC 8555 ACME March 2019 + + + that name. For example, if the domain name being validated is + "www.example.org", then the client would provision the following DNS + record: + + _acme-challenge.www.example.org. 300 IN TXT "gfj9Xq...Rg85nM" + + A client responds with an empty object ({}) to acknowledge that the + challenge can be validated by the server. + + POST /acme/chall/Rg5dV14Gh1Q + Host: example.com + Content-Type: application/jose+json + + { + "protected": base64url({ + "alg": "ES256", + "kid": "https://example.com/acme/acct/evOfKhNU60wg", + "nonce": "SS2sSl1PtspvFZ08kNtzKd", + "url": "https://example.com/acme/chall/Rg5dV14Gh1Q" + }), + "payload": base64url({}), + "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" + } + + On receiving a response, the server constructs and stores the key + authorization from the challenge "token" value and the current client + account key. + + To validate a DNS challenge, the server performs the following steps: + + 1. Compute the SHA-256 digest [FIPS180-4] of the stored key + authorization + + 2. Query for TXT records for the validation domain name + + 3. Verify that the contents of one of the TXT records match the + digest value + + If all of the above verifications succeed, then the validation is + successful. If no DNS record is found, or DNS record and response + payload do not pass these checks, then the validation fails. + + The client SHOULD de-provision the resource record(s) provisioned for + this challenge once the challenge is complete, i.e., once the + "status" field of the challenge has the value "valid" or "invalid". + + + + + + +Barnes, et al. Standards Track [Page 67] + +RFC 8555 ACME March 2019 + + +9. IANA Considerations + +9.1. Media Type: application/pem-certificate-chain + + A file of this type contains one or more certificates encoded with + the PEM textual encoding, according to [RFC7468]. The textual + encoding of certificates in this file MUST use the strict encoding + and MUST NOT include explanatory text. The ABNF for this format is + as follows, where "stricttextualmsg" and "eol" are as defined in + Section 3 of RFC 7468: + + certchain = stricttextualmsg *(eol stricttextualmsg) + + In order to provide easy interoperation with TLS, the first + certificate MUST be an end-entity certificate. Each following + certificate SHOULD directly certify the one preceding it. Because + certificate validation requires that trust anchors be distributed + independently, a certificate that represents a trust anchor MAY be + omitted from the chain, provided that supported peers are known to + possess any omitted certificates. + + The following has been registered in the "Media Types" registry: + Type name: application + + Subtype name: pem-certificate-chain + + Required parameters: None + + Optional parameters: None + + Encoding considerations: 7bit + + Security considerations: Carries a cryptographic certificate and its + associated certificate chain. This media type carries no active + content. + + Interoperability considerations: None + + Published specification: RFC 8555 + + Applications that use this media type: ACME clients and servers, HTTP + servers, other applications that need to be configured with a + certificate chain + + Additional information: + + Deprecated alias names for this type: n/a + Magic number(s): n/a + + + +Barnes, et al. Standards Track [Page 68] + +RFC 8555 ACME March 2019 + + + File extension(s): .pem + Macintosh file type code(s): n/a + + Person & email address to contact for further information: See + Authors' Addresses section. + + Intended usage: COMMON + + Restrictions on usage: n/a + + Author: See Authors' Addresses section. + + Change controller: IETF + +9.2. Well-Known URI for the HTTP Challenge + + The following value has been registered in the "Well-Known URIs" + registry (using the template from [RFC5785]): + + URI suffix: acme-challenge + + Change controller: IETF + + Specification document(s): RFC 8555, Section 8.3 + + Related information: N/A + +9.3. Replay-Nonce HTTP Header + + The following value has been registered in the "Message Headers" + registry: + + +-------------------+----------+----------+-------------------------+ + | Header Field Name | Protocol | Status | Reference | + +-------------------+----------+----------+-------------------------+ + | Replay-Nonce | http | standard | RFC 8555, Section 6.5.1 | + +-------------------+----------+----------+-------------------------+ + + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 69] + +RFC 8555 ACME March 2019 + + +9.4. "url" JWS Header Parameter + + The following value has been registered in the "JSON Web Signature + and Encryption Header Parameters" registry: + + o Header Parameter Name: "url" + + o Header Parameter Description: URL + + o Header Parameter Usage Location(s): JWE, JWS + + o Change Controller: IESG + + o Specification Document(s): RFC 8555, Section 6.4.1 + +9.5. "nonce" JWS Header Parameter + + The following value has been registered in the "JSON Web Signature + and Encryption Header Parameters" registry: + + o Header Parameter Name: "nonce" + + o Header Parameter Description: Nonce + + o Header Parameter Usage Location(s): JWE, JWS + + o Change Controller: IESG + + o Specification Document(s): RFC 8555, Section 6.5.2 + +9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) + + The following value has been registered in the "IETF URN Sub- + namespace for Registered Protocol Parameter Identifiers" registry, + following the template in [RFC3553]: + + Registry name: acme + + Specification: RFC 8555 + + Repository: http://www.iana.org/assignments/acme + + Index value: No transformation needed. + + + + + + + + +Barnes, et al. Standards Track [Page 70] + +RFC 8555 ACME March 2019 + + +9.7. New Registries + + IANA has created the following registries: + + 1. ACME Account Object Fields (Section 9.7.1) + + 2. ACME Order Object Fields (Section 9.7.2) + + 3. ACME Authorization Object Fields (Section 9.7.3) + + 4. ACME Error Types (Section 9.7.4) + + 5. ACME Resource Types (Section 9.7.5) + + 6. ACME Directory Metadata Fields (Section 9.7.6) + + 7. ACME Identifier Types (Section 9.7.7) + + 8. ACME Validation Methods (Section 9.7.8) + + All of these registries are under a heading of "Automated Certificate + Management Environment (ACME) Protocol" and are administered under a + Specification Required policy [RFC8126]. + +9.7.1. Fields in Account Objects + + The "ACME Account Object Fields" registry lists field names that are + defined for use in ACME account objects. Fields marked as + "configurable" may be included in a newAccount request. + + Template: + + o Field name: The string to be used as a field name in the JSON + object + + o Field type: The type of value to be provided, e.g., string, + boolean, array of string + + o Requests: Either the value "none" or a list of types of requests + where the field is allowed in a request object, taken from the + following values: + + * "new" - Requests to the "newAccount" URL + + * "account" - Requests to an account URL + + o Reference: Where this field is defined + + + + +Barnes, et al. Standards Track [Page 71] + +RFC 8555 ACME March 2019 + + + Initial contents: The fields and descriptions defined in + Section 7.1.2. + + +------------------------+---------------+--------------+-----------+ + | Field Name | Field Type | Requests | Reference | + +------------------------+---------------+--------------+-----------+ + | status | string | new, account | RFC 8555 | + | | | | | + | contact | array of | new, account | RFC 8555 | + | | string | | | + | | | | | + | externalAccountBinding | object | new | RFC 8555 | + | | | | | + | termsOfServiceAgreed | boolean | new | RFC 8555 | + | | | | | + | onlyReturnExisting | boolean | new | RFC 8555 | + | | | | | + | orders | string | none | RFC 8555 | + +------------------------+---------------+--------------+-----------+ + +9.7.2. Fields in Order Objects + + The "ACME Order Object Fields" registry lists field names that are + defined for use in ACME order objects. Fields marked as + "configurable" may be included in a newOrder request. + + Template: + + o Field name: The string to be used as a field name in the JSON + object + + o Field type: The type of value to be provided, e.g., string, + boolean, array of string + + o Configurable: Boolean indicating whether the server should accept + values provided by the client + + o Reference: Where this field is defined + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 72] + +RFC 8555 ACME March 2019 + + + Initial contents: The fields and descriptions defined in + Section 7.1.3. + + +----------------+-----------------+--------------+-----------+ + | Field Name | Field Type | Configurable | Reference | + +----------------+-----------------+--------------+-----------+ + | status | string | false | RFC 8555 | + | | | | | + | expires | string | false | RFC 8555 | + | | | | | + | identifiers | array of object | true | RFC 8555 | + | | | | | + | notBefore | string | true | RFC 8555 | + | | | | | + | notAfter | string | true | RFC 8555 | + | | | | | + | error | string | false | RFC 8555 | + | | | | | + | authorizations | array of string | false | RFC 8555 | + | | | | | + | finalize | string | false | RFC 8555 | + | | | | | + | certificate | string | false | RFC 8555 | + +----------------+-----------------+--------------+-----------+ + +9.7.3. Fields in Authorization Objects + + The "ACME Authorization Object Fields" registry lists field names + that are defined for use in ACME authorization objects. Fields + marked as "configurable" may be included in a newAuthz request. + + Template: + + o Field name: The string to be used as a field name in the JSON + object + + o Field type: The type of value to be provided, e.g., string, + boolean, array of string + + o Configurable: Boolean indicating whether the server should accept + values provided by the client + + o Reference: Where this field is defined + + + + + + + + +Barnes, et al. Standards Track [Page 73] + +RFC 8555 ACME March 2019 + + + Initial contents: The fields and descriptions defined in + Section 7.1.4. + + +------------+-----------------+--------------+-----------+ + | Field Name | Field Type | Configurable | Reference | + +------------+-----------------+--------------+-----------+ + | identifier | object | true | RFC 8555 | + | | | | | + | status | string | false | RFC 8555 | + | | | | | + | expires | string | false | RFC 8555 | + | | | | | + | challenges | array of object | false | RFC 8555 | + | | | | | + | wildcard | boolean | false | RFC 8555 | + +------------+-----------------+--------------+-----------+ + +9.7.4. Error Types + + The "ACME Error Types" registry lists values that are used within URN + values that are provided in the "type" field of problem documents in + ACME. + + Template: + + o Type: The label to be included in the URN for this error, + following "urn:ietf:params:acme:error:" + + o Description: A human-readable description of the error + + o Reference: Where the error is defined + + Initial contents: The types and descriptions in the table in + Section 6.7 above, with the Reference field set to point to this + specification. + +9.7.5. Resource Types + + The "ACME Resource Types" registry lists the types of resources that + ACME servers may list in their directory objects. + + Template: + + o Field name: The value to be used as a field name in the directory + object + + o Resource type: The type of resource labeled by the field + + + + +Barnes, et al. Standards Track [Page 74] + +RFC 8555 ACME March 2019 + + + o Reference: Where the resource type is defined + + Initial contents: + + +------------+--------------------+-----------+ + | Field Name | Resource Type | Reference | + +------------+--------------------+-----------+ + | newNonce | New nonce | RFC 8555 | + | | | | + | newAccount | New account | RFC 8555 | + | | | | + | newOrder | New order | RFC 8555 | + | | | | + | newAuthz | New authorization | RFC 8555 | + | | | | + | revokeCert | Revoke certificate | RFC 8555 | + | | | | + | keyChange | Key change | RFC 8555 | + | | | | + | meta | Metadata object | RFC 8555 | + +------------+--------------------+-----------+ + +9.7.6. Fields in the "meta" Object within a Directory Object + + The "ACME Directory Metadata Fields" registry lists field names that + are defined for use in the JSON object included in the "meta" field + of an ACME directory object. + + Template: + + o Field name: The string to be used as a field name in the JSON + object + + o Field type: The type of value to be provided, e.g., string, + boolean, array of string + + o Reference: Where this field is defined + + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 75] + +RFC 8555 ACME March 2019 + + + Initial contents: The fields and descriptions defined in + Section 7.1.1. + + +-------------------------+-----------------+-----------+ + | Field Name | Field Type | Reference | + +-------------------------+-----------------+-----------+ + | termsOfService | string | RFC 8555 | + | | | | + | website | string | RFC 8555 | + | | | | + | caaIdentities | array of string | RFC 8555 | + | | | | + | externalAccountRequired | boolean | RFC 8555 | + +-------------------------+-----------------+-----------+ + +9.7.7. Identifier Types + + The "ACME Identifier Types" registry lists the types of identifiers + that can be present in ACME authorization objects. + + Template: + + o Label: The value to be put in the "type" field of the identifier + object + + o Reference: Where the identifier type is defined + + Initial contents: + + +-------+-----------+ + | Label | Reference | + +-------+-----------+ + | dns | RFC 8555 | + +-------+-----------+ + +9.7.8. Validation Methods + + The "ACME Validation Methods" registry lists identifiers for the ways + that CAs can validate control of identifiers. Each method's entry + must specify whether it corresponds to an ACME challenge type. The + "Identifier Type" field must be contained in the Label column of the + "ACME Identifier Types" registry. + + + + + + + + + +Barnes, et al. Standards Track [Page 76] + +RFC 8555 ACME March 2019 + + + Template: + + o Label: The identifier for this validation method + + o Identifier Type: The type of identifier that this method applies + to + + o ACME: "Y" if the validation method corresponds to an ACME + challenge type; "N" otherwise + + o Reference: Where the validation method is defined + + This registry may also contain reserved entries (e.g., to avoid + collisions). Such entries should have the "ACME" field set to "N" + and the "Identifier Type" set to "RESERVED". + + Initial Contents + + +------------+-----------------+------+-----------+ + | Label | Identifier Type | ACME | Reference | + +------------+-----------------+------+-----------+ + | http-01 | dns | Y | RFC 8555 | + | | | | | + | dns-01 | dns | Y | RFC 8555 | + | | | | | + | tls-sni-01 | RESERVED | N | RFC 8555 | + | | | | | + | tls-sni-02 | RESERVED | N | RFC 8555 | + +------------+-----------------+------+-----------+ + + When evaluating a request for an assignment in this registry, the + designated expert should ensure that the method being registered has + a clear, interoperable definition and does not overlap with existing + validation methods. That is, it should not be possible for a client + and server to follow the same set of actions to fulfill two different + validation methods. + + The values "tls-sni-01" and "tls-sni-02" are reserved because they + were used in pre-RFC versions of this specification to denote + validation methods that were removed because they were found not to + be secure in some cases. + + Validation methods do not have to be compatible with ACME in order to + be registered. For example, a CA might wish to register a validation + method to support its use with the ACME extensions to CAA [ACME-CAA]. + + + + + + +Barnes, et al. Standards Track [Page 77] + +RFC 8555 ACME March 2019 + + +10. Security Considerations + + ACME is a protocol for managing certificates that attest to + identifier/key bindings. Thus, the foremost security goal of ACME is + to ensure the integrity of this process, i.e., to ensure that the + bindings attested by certificates are correct and that only + authorized entities can manage certificates. ACME identifies clients + by their account keys, so this overall goal breaks down into two more + precise goals: + + 1. Only an entity that controls an identifier can get an + authorization for that identifier + + 2. Once authorized, an account key's authorizations cannot be + improperly used by another account + + In this section, we discuss the threat model that underlies ACME and + the ways that ACME achieves these security goals within that threat + model. We also discuss the denial-of-service risks that ACME servers + face, and a few other miscellaneous considerations. + +10.1. Threat Model + + As a service on the Internet, ACME broadly exists within the Internet + threat model [RFC3552]. In analyzing ACME, it is useful to think of + an ACME server interacting with other Internet hosts along two + "channels": + + o An ACME channel, over which the ACME HTTPS requests are exchanged + + o A validation channel, over which the ACME server performs + additional requests to validate a client's control of an + identifier + + + + + + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 78] + +RFC 8555 ACME March 2019 + + + +------------+ + | ACME | ACME Channel + | Client |--------------------+ + +------------+ | + V + +------------+ + | ACME | + | Server | + +------------+ + +------------+ | + | Validation |<-------------------+ + | Server | Validation Channel + +------------+ + + Communications Channels Used by ACME + + In practice, the risks to these channels are not entirely separate, + but they are different in most cases. Each channel, for example, + uses a different communications pattern: the ACME channel will + comprise inbound HTTPS connections to the ACME server and the + validation channel outbound HTTP or DNS requests. + + Broadly speaking, ACME aims to be secure against active and passive + attackers on any individual channel. Some vulnerabilities arise + (noted below) when an attacker can exploit both the ACME channel and + one of the others. + + On the ACME channel, in addition to network-layer attackers, we also + need to account for man-in-the-middle (MitM) attacks at the + application layer and for abusive use of the protocol itself. + Protection against application-layer MitM addresses potential + attackers such as Content Distribution Networks (CDNs) and + middleboxes with a TLS MitM function. Preventing abusive use of ACME + means ensuring that an attacker with access to the validation channel + can't obtain illegitimate authorization by acting as an ACME client + (legitimately, in terms of the protocol). + + ACME does not protect against other types of abuse by a MitM on the + ACME channel. For example, such an attacker could send a bogus + "badSignatureAlgorithm" error response to downgrade a client to the + lowest-quality signature algorithm that the server supports. A MitM + that is present on all connections (such as a CDN) can cause denial- + of-service conditions in a variety of ways. + + + + + + + + +Barnes, et al. Standards Track [Page 79] + +RFC 8555 ACME March 2019 + + +10.2. Integrity of Authorizations + + ACME allows anyone to request challenges for an identifier by + registering an account key and sending a newOrder request using that + account key. The integrity of the authorization process thus depends + on the identifier validation challenges to ensure that the challenge + can only be completed by someone who both (1) holds the private key + of the account key pair and (2) controls the identifier in question. + + Validation responses need to be bound to an account key pair in order + to avoid situations where a MitM on ACME HTTPS requests can switch + out a legitimate domain holder's account key for one of his choosing. + Such MitMs can arise, for example, if a CA uses a CDN or third-party + reverse proxy in front of its ACME interface. An attack by such an + MitM could have the following form: + + 1. Legitimate domain holder registers account key pair A + + 2. MitM registers account key pair B + + 3. Legitimate domain holder sends a newOrder request signed using + account key A + + 4. MitM suppresses the legitimate request but sends the same request + signed using account key B + + 5. ACME server issues challenges and MitM forwards them to the + legitimate domain holder + + 6. Legitimate domain holder provisions the validation response + + 7. ACME server performs validation query and sees the response + provisioned by the legitimate domain holder + + 8. Because the challenges were issued in response to a message + signed with account key B, the ACME server grants authorization + to account key B (the MitM) instead of account key A (the + legitimate domain holder) + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 80] + +RFC 8555 ACME March 2019 + + + Domain ACME + Holder MitM Server + | | | + | newAccount(A) | | + |--------------------->|--------------------->| + | | | + | | newAccount(B) | + | |--------------------->| + | newOrder(domain, A) | | + |--------------------->| | + | | newOrder(domain, B) | + | |--------------------->| + | | | + | authz, challenges | authz, challenges | + |<---------------------|<---------------------| + | | | + | response(chall, A) | response(chall, B) | + |--------------------->|--------------------->| + | | | + | validation request | | + |<--------------------------------------------| + | | | + | validation response | | + |-------------------------------------------->| + | | | + | | | Considers challenge + | | | fulfilled by B + | | | + + Man-in-the-Middle Attack Exploiting a Validation + Method without Account Key Binding + + All of the challenges defined in this document have a binding between + the account private key and the validation query made by the server, + via the key authorization. The key authorization reflects the + account public key and is provided to the server in the validation + response over the validation channel. + + The association of challenges to identifiers is typically done by + requiring the client to perform some action that only someone who + effectively controls the identifier can perform. For the challenges + in this document, the actions are as follows: + + o HTTP: Provision files under .well-known on a web server for the + domain + + o DNS: Provision DNS resource records for the domain + + + + +Barnes, et al. Standards Track [Page 81] + +RFC 8555 ACME March 2019 + + + There are several ways that these assumptions can be violated, both + by misconfiguration and by attacks. For example, on a web server + that allows non-administrative users to write to .well-known, any + user can claim to own the web server's hostname by responding to an + HTTP challenge. Similarly, if a server that can be used for ACME + validation is compromised by a malicious actor, then that malicious + actor can use that access to obtain certificates via ACME. + + The use of hosting providers is a particular risk for ACME + validation. If the owner of the domain has outsourced operation of + DNS or web services to a hosting provider, there is nothing that can + be done against tampering by the hosting provider. As far as the + outside world is concerned, the zone or website provided by the + hosting provider is the real thing. + + More limited forms of delegation can also lead to an unintended party + gaining the ability to successfully complete a validation + transaction. For example, suppose an ACME server follows HTTP + redirects in HTTP validation and a website operator provisions a + catch-all redirect rule that redirects requests for unknown resources + to a different domain. Then the target of the redirect could use + that to get a certificate through HTTP validation since the + validation path will not be known to the primary server. + + The DNS is a common point of vulnerability for all of these + challenges. An entity that can provision false DNS records for a + domain can attack the DNS challenge directly and can provision false + A/AAAA records to direct the ACME server to send its HTTP validation + query to a remote server of the attacker's choosing. There are a few + different mitigations that ACME servers can apply: + + o Always querying the DNS using a DNSSEC-validating resolver + (enhancing security for zones that are DNSSEC-enabled) + + o Querying the DNS from multiple vantage points to address local + attackers + + o Applying mitigations against DNS off-path attackers, e.g., adding + entropy to requests [DNS0x20] or only using TCP + + Given these considerations, the ACME validation process makes it + impossible for any attacker on the ACME channel or a passive attacker + on the validation channel to hijack the authorization process to + authorize a key of the attacker's choice. + + An attacker that can only see the ACME channel would need to convince + the validation server to provide a response that would authorize the + attacker's account key, but this is prevented by binding the + + + +Barnes, et al. Standards Track [Page 82] + +RFC 8555 ACME March 2019 + + + validation response to the account key used to request challenges. A + passive attacker on the validation channel can observe the correct + validation response and even replay it, but that response can only be + used with the account key for which it was generated. + + An active attacker on the validation channel can subvert the ACME + process, by performing normal ACME transactions and providing a + validation response for his own account key. The risks due to + hosting providers noted above are a particular case. + + Attackers can also exploit vulnerabilities in Internet routing + protocols to gain access to the validation channel (see, e.g., + [RFC7132]). In order to make such attacks more difficult, it is + RECOMMENDED that the server perform DNS queries and make HTTP + connections from multiple points in the network. Since routing + attacks are often localized or dependent on the position of the + attacker, forcing the attacker to attack multiple points (the + server's validation vantage points) or a specific point (the DNS / + HTTP server) makes it more difficult to subvert ACME validation using + attacks on routing. + +10.3. Denial-of-Service Considerations + + As a protocol run over HTTPS, standard considerations for TCP-based + and HTTP-based DoS mitigation also apply to ACME. + + At the application layer, ACME requires the server to perform a few + potentially expensive operations. Identifier validation transactions + require the ACME server to make outbound connections to potentially + attacker-controlled servers, and certificate issuance can require + interactions with cryptographic hardware. + + In addition, an attacker can also cause the ACME server to send + validation requests to a domain of its choosing by submitting + authorization requests for the victim domain. + + All of these attacks can be mitigated by the application of + appropriate rate limits. Issues closer to the front end, like POST + body validation, can be addressed using HTTP request limiting. For + validation and certificate requests, there are other identifiers on + which rate limits can be keyed. For example, the server might limit + the rate at which any individual account key can issue certificates + or the rate at which validation can be requested within a given + subtree of the DNS. And in order to prevent attackers from + circumventing these limits simply by minting new accounts, servers + would need to limit the rate at which accounts can be registered. + + + + + +Barnes, et al. Standards Track [Page 83] + +RFC 8555 ACME March 2019 + + +10.4. Server-Side Request Forgery + + Server-Side Request Forgery (SSRF) attacks can arise when an attacker + can cause a server to perform HTTP requests to an attacker-chosen + URL. In the ACME HTTP challenge validation process, the ACME server + performs an HTTP GET request to a URL in which the attacker can + choose the domain. This request is made before the server has + verified that the client controls the domain, so any client can cause + a query to any domain. + + Some ACME server implementations include information from the + validation server's response (in order to facilitate debugging). + Such implementations enable an attacker to extract this information + from any web server that is accessible to the ACME server, even if it + is not accessible to the ACME client. For example, the ACME server + might be able to access servers behind a firewall that would prevent + access by the ACME client. + + It might seem that the risk of SSRF through this channel is limited + by the fact that the attacker can only control the domain of the URL, + not the path. However, if the attacker first sets the domain to one + they control, then they can send the server an HTTP redirect (e.g., a + 302 response) which will cause the server to query an arbitrary URL. + + In order to further limit the SSRF risk, ACME server operators should + ensure that validation queries can only be sent to servers on the + public Internet, and not, say, web services within the server + operator's internal network. Since the attacker could make requests + to these public servers himself, he can't gain anything extra through + an SSRF attack on ACME aside from a layer of anonymization. + +10.5. CA Policy Considerations + + The controls on issuance enabled by ACME are focused on validating + that a certificate applicant controls the identifier he claims. + Before issuing a certificate, however, there are many other checks + that a CA might need to perform, for example: + + o Has the client agreed to a subscriber agreement? + + o Is the claimed identifier syntactically valid? + + o For domain names: + + * If the leftmost label is a '*', then have the appropriate + checks been applied? + + * Is the name on the Public Suffix List? + + + +Barnes, et al. Standards Track [Page 84] + +RFC 8555 ACME March 2019 + + + * Is the name a high-value name? + + * Is the name a known phishing domain? + + o Is the key in the CSR sufficiently strong? + + o Is the CSR signed with an acceptable algorithm? + + o Has issuance been authorized or forbidden by a Certification + Authority Authorization (CAA) record ([RFC6844])? + + CAs that use ACME to automate issuance will need to ensure that their + servers perform all necessary checks before issuing. + + CAs using ACME to allow clients to agree to terms of service should + keep in mind that ACME clients can automate this agreement, possibly + not involving a human user. + + ACME does not specify how the server constructs the URLs that it uses + to address resources. If the server operator uses URLs that are + predictable to third parties, this can leak information about what + URLs exist on the server, since an attacker can probe for whether a + POST-as-GET request to the URL returns 404 (Not Found) or 401 + (Unauthorized). + + For example, suppose that the CA uses highly structured URLs with + guessable fields: + + o Accounts: https://example.com/:accountID + + o Orders: https://example.com/:accountID/:domainName + + o Authorizations: https://example.com/:accountID/:domainName + + o Certificates: https://example.com/:accountID/:domainName + + Under that scheme, an attacker could probe for which domain names are + associated with which accounts, which may allow correlation of + ownership between domain names, if the CA does not otherwise permit + it. + + + + + + + + + + + +Barnes, et al. Standards Track [Page 85] + +RFC 8555 ACME March 2019 + + + To avoid leaking these correlations, CAs SHOULD assign URLs with an + unpredictable component. For example, a CA might assign URLs for + each resource type from an independent namespace, using unpredictable + IDs for each resource: + + o Accounts: https://example.com/acct/:accountID + + o Orders: https://example.com/order/:orderID + + o Authorizations: https://example.com/authz/:authorizationID + + o Certificates: https://example.com/cert/:certID + + Such a scheme would leak only the type of resource, hiding the + additional correlations revealed in the example above. + +11. Operational Considerations + + There are certain factors that arise in operational reality that + operators of ACME-based CAs will need to keep in mind when + configuring their services. See the subsections below for examples. + +11.1. Key Selection + + ACME relies on two different classes of key pair: + + o Account key pairs, which are used to authenticate account holders + + o Certificate key pairs, which are used to sign and verify CSRs (and + whose public keys are included in certificates) + + Compromise of the private key of an account key pair has more serious + consequences than compromise of a private key corresponding to a + certificate. While the compromise of a certificate key pair allows + the attacker to impersonate the entities named in the certificate for + the lifetime of the certificate, the compromise of an account key + pair allows the attacker to take full control of the victim's ACME + account and take any action that the legitimate account holder could + take within the scope of ACME: + + 1. Issuing certificates using existing authorizations + + 2. Revoking existing certificates + + 3. Accessing and changing account information (e.g., contacts) + + 4. Changing the account key pair for the account, locking out the + legitimate account holder + + + +Barnes, et al. Standards Track [Page 86] + +RFC 8555 ACME March 2019 + + + For this reason, it is RECOMMENDED that each account key pair be used + only for authentication of a single ACME account. For example, the + public key of an account key pair MUST NOT be included in a + certificate. If an ACME client receives a request from a user for + account creation or key rollover using an account key that the client + knows to be used elsewhere, then the client MUST return an error. + Clients MUST generate a fresh account key for every account creation + or rollover operation. Note that given the requirements of + Section 7.3.1, servers will not create accounts with reused keys + anyway. + + ACME clients and servers MUST verify that a CSR submitted in a + finalize request does not contain a public key for any known account + key pair. In particular, when a server receives a finalize request, + it MUST verify that the public key in a CSR is not the same as the + public key of the account key pair used to authenticate that request. + This assures that vulnerabilities in the protocols with which the + certificate is used (e.g., signing oracles in TLS [JSS15]) do not + result in compromise of the ACME account. Because ACME accounts are + uniquely identified by their account key pair (see Section 7.3.1), + the server MUST not allow account key pair reuse across multiple + accounts. + +11.2. DNS Security + + As noted above, DNS forgery attacks against the ACME server can + result in the server making incorrect decisions about domain control + and thus mis-issuing certificates. Servers SHOULD perform DNS + queries over TCP, which provides better resistance to some forgery + attacks than DNS over UDP. + + An ACME-based CA will often need to make DNS queries, e.g., to + validate control of DNS names. Because the security of such + validations ultimately depends on the authenticity of DNS data, every + possible precaution should be taken to secure DNS queries done by the + CA. Therefore, it is RECOMMENDED that ACME-based CAs make all DNS + queries via DNSSEC-validating stub or recursive resolvers. This + provides additional protection to domains that choose to make use of + DNSSEC. + + An ACME-based CA must only use a resolver if it trusts the resolver + and every component of the network route by which it is accessed. + Therefore, it is RECOMMENDED that ACME-based CAs operate their own + DNSSEC-validating resolvers within their trusted network and use + these resolvers both for CAA record lookups and all record lookups in + furtherance of a challenge scheme (A, AAAA, TXT, etc.). + + + + + +Barnes, et al. Standards Track [Page 87] + +RFC 8555 ACME March 2019 + + +11.3. Token Entropy + + The http-01 and dns-01 validation methods mandate the use of a random + token value to uniquely identify the challenge. The value of the + token is required to contain at least 128 bits of entropy for the + following security properties. First, the ACME client should not be + able to influence the ACME server's choice of token as this may allow + an attacker to reuse a domain owner's previous challenge responses + for a new validation request. Second, the entropy requirement makes + it more difficult for ACME clients to implement a "naive" validation + server that automatically replies to challenges without being + configured per challenge. + +11.4. Malformed Certificate Chains + + ACME provides certificate chains in the widely used format known + colloquially as PEM (though it may diverge from the actual Privacy + Enhanced Mail specification [RFC1421], as noted in [RFC7468]). Some + current software will allow the configuration of a private key and a + certificate in one PEM file by concatenating the textual encodings of + the two objects. In the context of ACME, such software might be + vulnerable to key replacement attacks. A malicious ACME server could + cause a client to use a private key of its choosing by including the + key in the PEM file returned in response to a query for a certificate + URL. + + When processing a file of type "application/pem-certificate-chain", a + client SHOULD verify that the file contains only encoded + certificates. If anything other than a certificate is found (i.e., + if the string "-----BEGIN" is ever followed by anything other than + "CERTIFICATE"), then the client MUST reject the file as invalid. + +12. References + +12.1. Normative References + + [FIPS180-4] + National Institute of Standards and Technology (NIST), + "Secure Hash Standard (SHS)", FIPS PUB 180-4, + DOI 10.6028/NIST.FIPS.180-4, August 2015, + . + + + + + + + + + +Barnes, et al. Standards Track [Page 88] + +RFC 8555 ACME March 2019 + + + [JSS15] Somorovsky, J., Schwenk, J., and J. Somorovsky, "On the + Security of TLS 1.3 and QUIC Against Weaknesses in PKCS#1 + v1.5 Encryption", CSS '15 Proceedings of the 22nd ACM + SIGSAC Conference on Computer and Communications + Security Pages 1185-1196, DOI 10.1145/2810103.2813657, + . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC2585] Housley, R. and P. Hoffman, "Internet X.509 Public Key + Infrastructure Operational Protocols: FTP and HTTP", + RFC 2585, DOI 10.17487/RFC2585, May 1999, + . + + [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, + DOI 10.17487/RFC2818, May 2000, + . + + [RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object + Classes and Attribute Types Version 2.0", RFC 2985, + DOI 10.17487/RFC2985, November 2000, + . + + [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification + Request Syntax Specification Version 1.7", RFC 2986, + DOI 10.17487/RFC2986, November 2000, + . + + [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: + Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, + . + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November + 2003, . + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, DOI 10.17487/RFC3986, January 2005, + . + + [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, + "Randomness Requirements for Security", BCP 106, RFC 4086, + DOI 10.17487/RFC4086, June 2005, + . + + + +Barnes, et al. Standards Track [Page 89] + +RFC 8555 ACME March 2019 + + + [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data + Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, + . + + [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, + DOI 10.17487/RFC5234, January 2008, + . + + [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., + Housley, R., and W. Polk, "Internet X.509 Public Key + Infrastructure Certificate and Certificate Revocation List + (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, + . + + [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet + Mail Extensions (S/MIME) Version 3.2 Message + Specification", RFC 5751, DOI 10.17487/RFC5751, January + 2010, . + + [RFC5890] Klensin, J., "Internationalized Domain Names for + Applications (IDNA): Definitions and Document Framework", + RFC 5890, DOI 10.17487/RFC5890, August 2010, + . + + [RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' + URI Scheme", RFC 6068, DOI 10.17487/RFC6068, October 2010, + . + + [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., + and D. Orchard, "URI Template", RFC 6570, + DOI 10.17487/RFC6570, March 2012, + . + + [RFC6844] Hallam-Baker, P. and R. Stradling, "DNS Certification + Authority Authorization (CAA) Resource Record", RFC 6844, + DOI 10.17487/RFC6844, January 2013, + . + + [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer + Protocol (HTTP/1.1): Semantics and Content", RFC 7231, + DOI 10.17487/RFC7231, June 2014, + . + + [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, + PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, + April 2015, . + + + + +Barnes, et al. Standards Track [Page 90] + +RFC 8555 ACME March 2019 + + + [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web + Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May + 2015, . + + [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, + DOI 10.17487/RFC7518, May 2015, + . + + [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) + Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September + 2015, . + + [RFC7797] Jones, M., "JSON Web Signature (JWS) Unencoded Payload + Option", RFC 7797, DOI 10.17487/RFC7797, February 2016, + . + + [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP + APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, + . + + [RFC8037] Liusvaara, I., "CFRG Elliptic Curve Diffie-Hellman (ECDH) + and Signatures in JSON Object Signing and Encryption + (JOSE)", RFC 8037, DOI 10.17487/RFC8037, January 2017, + . + + [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for + Writing an IANA Considerations Section in RFCs", BCP 26, + RFC 8126, DOI 10.17487/RFC8126, June 2017, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data + Interchange Format", STD 90, RFC 8259, + DOI 10.17487/RFC8259, December 2017, + . + + [RFC8288] Nottingham, M., "Web Linking", RFC 8288, + DOI 10.17487/RFC8288, October 2017, + . + + [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol + Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, + . + + + + + +Barnes, et al. Standards Track [Page 91] + +RFC 8555 ACME March 2019 + + +12.2. Informative References + + [ACME-CAA] + Landau, H., "CAA Record Extensions for Account URI and + ACME Method Binding", Work in Progress, draft-ietf-acme- + caa-06, January 2019. + + [ACME-IP] Shoemaker, R., "ACME IP Identifier Validation Extension", + Work in Progress, draft-ietf-acme-ip-05, February 2019. + + [ACME-TELEPHONE] + Peterson, J. and R. Barnes, "ACME Identifiers and + Challenges for Telephone Numbers", Work in Progress, + draft-ietf-acme-telephone-01, October 2017. + + [CABFBR] CA/Browser Forum, "CA/Browser Forum Baseline + Requirements", September 2018, + . + + [DNS0x20] Vixie, P. and D. Dagon, "Use of Bit 0x20 in DNS Labels to + Improve Transaction Identity", Work in Progress, + draft-vixie-dnsext-dns0x20-00, March 2008. + + [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic + Mail: Part I: Message Encryption and Authentication + Procedures", RFC 1421, DOI 10.17487/RFC1421, February + 1993, . + + [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC + Text on Security Considerations", BCP 72, RFC 3552, + DOI 10.17487/RFC3552, July 2003, + . + + [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An + IETF URN Sub-namespace for Registered Protocol + Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June + 2003, . + [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known + Uniform Resource Identifiers (URIs)", RFC 5785, + DOI 10.17487/RFC5785, April 2010, + . + + [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., + Galperin, S., and C. Adams, "X.509 Internet Public Key + Infrastructure Online Certificate Status Protocol - OCSP", + RFC 6960, DOI 10.17487/RFC6960, June 2013, + . + + + + +Barnes, et al. Standards Track [Page 92] + +RFC 8555 ACME March 2019 + + + [RFC7132] Kent, S. and A. Chi, "Threat Model for BGP Path Security", + RFC 7132, DOI 10.17487/RFC7132, February 2014, + . + + [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, + "Recommendations for Secure Use of Transport Layer + Security (TLS) and Datagram Transport Layer Security + (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May + 2015, . + + [W3C.REC-cors-20140116] + Kesteren, A., Ed., "Cross-Origin Resource Sharing", W3C + Recommendation REC-cors-20140116, January 2014, + . + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 93] + +RFC 8555 ACME March 2019 + + +Acknowledgements + + In addition to the editors listed on the front page, this document + has benefited from contributions from a broad set of contributors, + all the way back to its inception. + + o Andrew Ayer, SSLMate + + o Karthik Bhargavan, INRIA + + o Peter Eckersley, EFF + + o Alex Halderman, University of Michigan + + o Sophie Herold, Hemio + + o Tim Hollebeek, DigiCert + + o Eric Rescorla, Mozilla + + o Seth Schoen, EFF + + o Roland Shoemaker, Let's Encrypt + + o Rob Stradling, Sectigo + + o Martin Thomson, Mozilla + + o Jakub Warmuz, University of Oxford + + This document draws on many concepts established by Eric Rescorla's + "Automated Certificate Issuance Protocol" draft. Martin Thomson + provided helpful guidance in the use of HTTP. + + + + + + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 94] + +RFC 8555 ACME March 2019 + + +Authors' Addresses + + Richard Barnes + Cisco + + Email: rlb@ipv.sx + + + Jacob Hoffman-Andrews + EFF + + Email: jsha@eff.org + + + Daniel McCarney + Let's Encrypt + + Email: cpu@letsencrypt.org + + + James Kasten + University of Michigan + + Email: jdkasten@umich.edu + + + + + + + + + + + + + + + + + + + + + + + + + + + +Barnes, et al. Standards Track [Page 95] + -- cgit v1.2.3