idnits 2.17.1 draft-ietf-acme-acme-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 15 characters in excess of 72. ** The abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 856 has weird spacing: '...Account newA...' -- The exact meaning of the all-uppercase expression 'NOT REQUIRED' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. -- The document date (April 24, 2018) is 2193 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 3719 == Missing Reference: 'A-Z' is mentioned on line 605, but not defined == Missing Reference: '0-9' is mentioned on line 605, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS180-4' ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Downref: Normative reference to an Informational RFC: RFC 2985 ** Downref: Normative reference to an Informational RFC: RFC 2986 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 6844 (Obsoleted by RFC 8659) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7807 (Obsoleted by RFC 9457) == Outdated reference: A later version (-10) exists of draft-ietf-acme-caa-03 == Outdated reference: A later version (-08) exists of draft-ietf-acme-ip-01 -- Obsolete informational reference (is this intentional?): RFC 5785 (Obsoleted by RFC 8615) -- Obsolete informational reference (is this intentional?): RFC 7525 (Obsoleted by RFC 9325) Summary: 11 errors (**), 0 flaws (~~), 6 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACME Working Group R. Barnes 3 Internet-Draft Cisco 4 Intended status: Standards Track J. Hoffman-Andrews 5 Expires: October 26, 2018 EFF 6 D. McCarney 7 Let's Encrypt 8 J. Kasten 9 University of Michigan 10 April 24, 2018 12 Automatic Certificate Management Environment (ACME) 13 draft-ietf-acme-acme-12 15 Abstract 17 Certificates in PKI using X.509 (PKIX) are used for a number of 18 purposes, the most significant of which is the authentication of 19 domain names. Thus, certificate authorities in the Web PKI are 20 trusted to verify that an applicant for a certificate legitimately 21 represents the domain name(s) in the certificate. Today, this 22 verification is done through a collection of ad hoc mechanisms. This 23 document describes a protocol that a certification authority (CA) and 24 an applicant can use to automate the process of verification and 25 certificate issuance. The protocol also provides facilities for 26 other certificate management functions, such as certificate 27 revocation. 29 RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH: The source for 30 this draft is maintained in GitHub. Suggested changes should be 31 submitted as pull requests at https://github.com/ietf-wg-acme/acme 32 [1]. Instructions are on that page as well. Editorial changes can 33 be managed in GitHub, but any substantive change should be discussed 34 on the ACME mailing list (acme@ietf.org). 36 Status of This Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at https://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on October 26, 2018. 53 Copyright Notice 55 Copyright (c) 2018 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents 60 (https://trustee.ietf.org/license-info) in effect on the date of 61 publication of this document. Please review these documents 62 carefully, as they describe your rights and restrictions with respect 63 to this document. Code Components extracted from this document must 64 include Simplified BSD License text as described in Section 4.e of 65 the Trust Legal Provisions and are provided without warranty as 66 described in the Simplified BSD License. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 71 2. Deployment Model and Operator Experience . . . . . . . . . . 5 72 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 73 4. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 7 74 5. Character Encoding . . . . . . . . . . . . . . . . . . . . . 9 75 6. Message Transport . . . . . . . . . . . . . . . . . . . . . . 9 76 6.1. HTTPS Requests . . . . . . . . . . . . . . . . . . . . . 9 77 6.2. Request Authentication . . . . . . . . . . . . . . . . . 10 78 6.3. Request URL Integrity . . . . . . . . . . . . . . . . . . 12 79 6.3.1. "url" (URL) JWS Header Parameter . . . . . . . . . . 12 80 6.4. Replay protection . . . . . . . . . . . . . . . . . . . . 12 81 6.4.1. Replay-Nonce . . . . . . . . . . . . . . . . . . . . 13 82 6.4.2. "nonce" (Nonce) JWS Header Parameter . . . . . . . . 14 83 6.5. Rate Limits . . . . . . . . . . . . . . . . . . . . . . . 14 84 6.6. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 14 85 6.6.1. Subproblems . . . . . . . . . . . . . . . . . . . . . 16 86 7. Certificate Management . . . . . . . . . . . . . . . . . . . 17 87 7.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 17 88 7.1.1. Directory . . . . . . . . . . . . . . . . . . . . . . 20 89 7.1.2. Account Objects . . . . . . . . . . . . . . . . . . . 22 90 7.1.3. Order Objects . . . . . . . . . . . . . . . . . . . . 23 91 7.1.4. Authorization Objects . . . . . . . . . . . . . . . . 26 92 7.1.5. Challenge Objects . . . . . . . . . . . . . . . . . . 27 93 7.1.6. Status Changes . . . . . . . . . . . . . . . . . . . 27 94 7.2. Getting a Nonce . . . . . . . . . . . . . . . . . . . . . 30 95 7.3. Account Creation . . . . . . . . . . . . . . . . . . . . 31 96 7.3.1. Finding an Account URL Given a Key . . . . . . . . . 33 97 7.3.2. Account Update . . . . . . . . . . . . . . . . . . . 33 98 7.3.3. Account Information . . . . . . . . . . . . . . . . . 34 99 7.3.4. Changes of Terms of Service . . . . . . . . . . . . . 34 100 7.3.5. External Account Binding . . . . . . . . . . . . . . 35 101 7.3.6. Account Key Roll-over . . . . . . . . . . . . . . . . 37 102 7.3.7. Account Deactivation . . . . . . . . . . . . . . . . 39 103 7.4. Applying for Certificate Issuance . . . . . . . . . . . . 40 104 7.4.1. Pre-Authorization . . . . . . . . . . . . . . . . . . 44 105 7.4.2. Downloading the Certificate . . . . . . . . . . . . . 46 106 7.5. Identifier Authorization . . . . . . . . . . . . . . . . 47 107 7.5.1. Responding to Challenges . . . . . . . . . . . . . . 48 108 7.5.2. Deactivating an Authorization . . . . . . . . . . . . 50 109 7.6. Certificate Revocation . . . . . . . . . . . . . . . . . 51 110 8. Identifier Validation Challenges . . . . . . . . . . . . . . 53 111 8.1. Key Authorizations . . . . . . . . . . . . . . . . . . . 55 112 8.2. Retrying Challenges . . . . . . . . . . . . . . . . . . . 55 113 8.3. HTTP Challenge . . . . . . . . . . . . . . . . . . . . . 56 114 8.4. DNS Challenge . . . . . . . . . . . . . . . . . . . . . . 58 115 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60 116 9.1. MIME Type: application/pem-certificate-chain . . . . . . 60 117 9.2. Well-Known URI for the HTTP Challenge . . . . . . . . . . 61 118 9.3. Replay-Nonce HTTP Header . . . . . . . . . . . . . . . . 61 119 9.4. "url" JWS Header Parameter . . . . . . . . . . . . . . . 61 120 9.5. "nonce" JWS Header Parameter . . . . . . . . . . . . . . 62 121 9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) . . . . 62 122 9.7. New Registries . . . . . . . . . . . . . . . . . . . . . 62 123 9.7.1. Fields in Account Objects . . . . . . . . . . . . . . 63 124 9.7.2. Fields in Order Objects . . . . . . . . . . . . . . . 64 125 9.7.3. Fields in Authorization Objects . . . . . . . . . . . 65 126 9.7.4. Error Types . . . . . . . . . . . . . . . . . . . . . 66 127 9.7.5. Resource Types . . . . . . . . . . . . . . . . . . . 66 128 9.7.6. Fields in the "meta" Object within a Directory Object 67 129 9.7.7. Identifier Types . . . . . . . . . . . . . . . . . . 68 130 9.7.8. Validation Methods . . . . . . . . . . . . . . . . . 68 131 10. Security Considerations . . . . . . . . . . . . . . . . . . . 69 132 10.1. Threat Model . . . . . . . . . . . . . . . . . . . . . . 70 133 10.2. Integrity of Authorizations . . . . . . . . . . . . . . 71 134 10.3. Denial-of-Service Considerations . . . . . . . . . . . . 73 135 10.4. Server-Side Request Forgery . . . . . . . . . . . . . . 74 136 10.5. CA Policy Considerations . . . . . . . . . . . . . . . . 74 137 11. Operational Considerations . . . . . . . . . . . . . . . . . 75 138 11.1. Key Selection . . . . . . . . . . . . . . . . . . . . . 75 139 11.2. DNS security . . . . . . . . . . . . . . . . . . . . . . 76 140 11.3. Token Entropy . . . . . . . . . . . . . . . . . . . . . 76 141 11.4. Malformed Certificate Chains . . . . . . . . . . . . . . 77 142 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 77 143 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 78 144 13.1. Normative References . . . . . . . . . . . . . . . . . . 78 145 13.2. Informative References . . . . . . . . . . . . . . . . . 80 146 13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 81 147 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82 149 1. Introduction 151 Certificates [RFC5280] in the Web PKI are most commonly used to 152 authenticate domain names. Thus, certificate authorities in the Web 153 PKI are trusted to verify that an applicant for a certificate 154 legitimately represents the domain name(s) in the certificate. 156 Different types of certificates reflect different kinds of CA 157 verification of information about the certificate subject. "Domain 158 Validation" (DV) certificates are by far the most common type. For 159 DV validation, the CA merely verifies that the requester has 160 effective control of the web server and/or DNS server for the domain, 161 but does not explicitly attempt to verify their real-world identity. 162 (This is as opposed to "Organization Validation" (OV) and "Extended 163 Validation" (EV) certificates, where the process is intended to also 164 verify the real-world identity of the requester.) 166 Existing Web PKI certificate authorities tend to use a set of ad hoc 167 protocols for certificate issuance and identity verification. In the 168 case of DV certificates, a typical user experience is something like: 170 o Generate a PKCS#10 [RFC2986] Certificate Signing Request (CSR). 172 o Cut-and-paste the CSR into a CA web page. 174 o Prove ownership of the domain by one of the following methods: 176 * Put a CA-provided challenge at a specific place on the web 177 server. 179 * Put a CA-provided challenge in a DNS record corresponding to 180 the target domain. 182 * Receive a CA-provided challenge at a (hopefully) administrator- 183 controlled email address corresponding to the domain and then 184 respond to it on the CA's web page. 186 o Download the issued certificate and install it on their Web 187 Server. 189 With the exception of the CSR itself and the certificates that are 190 issued, these are all completely ad hoc procedures and are 191 accomplished by getting the human user to follow interactive natural- 192 language instructions from the CA rather than by machine-implemented 193 published protocols. In many cases, the instructions are difficult 194 to follow and cause significant confusion. Informal usability tests 195 by the authors indicate that webmasters often need 1-3 hours to 196 obtain and install a certificate for a domain. Even in the best 197 case, the lack of published, standardized mechanisms presents an 198 obstacle to the wide deployment of HTTPS and other PKIX-dependent 199 systems because it inhibits mechanization of tasks related to 200 certificate issuance, deployment, and revocation. 202 This document describes an extensible framework for automating the 203 issuance and domain validation procedure, thereby allowing servers 204 and infrastructural software to obtain certificates without user 205 interaction. Use of this protocol should radically simplify the 206 deployment of HTTPS and the practicality of PKIX authentication for 207 other protocols based on Transport Layer Security (TLS) [RFC5246]. 209 It should be noted that while the focus of this document is on 210 validating domain names for purposes of issuing certificates in the 211 Web PKI, ACME supports extensions for uses with other identifiers in 212 other PKI contexts. For example, as of this writing, there is 213 ongoing work to use ACME for issuance of WebPKI certificates 214 attesting to IP addresses [I-D.ietf-acme-ip] and STIR certificates 215 attesting to telephone numbers [I-D.ietf-acme-telephone]. 217 ACME can also be used to automate some aspects of certificate 218 management even where non-automated processes are still needed. For 219 example, the external account binding feature (see Section 7.3.5) can 220 allow an ACME account to use authorizations that have been granted to 221 an external, non-ACME account. This allows ACME to address issuance 222 scenarios that cannot yet be fully automated, such as the issuance of 223 Extended Validation certificates. 225 2. Deployment Model and Operator Experience 227 The guiding use case for ACME is obtaining certificates for websites 228 (HTTPS [RFC2818]). In this case, the user's web server is intended 229 to speak for one or more domains, and the process of certificate 230 issuance is intended to verify that this web server actually speaks 231 for the domain(s). 233 DV certificate validation commonly checks claims about properties 234 related to control of a domain name - properties that can be observed 235 by the certificate issuer in an interactive process that can be 236 conducted purely online. That means that under typical 237 circumstances, all steps in the request, verification, and issuance 238 process can be represented and performed by Internet protocols with 239 no out-of-band human intervention. 241 Prior to ACME, when deploying an HTTPS server, a server operator 242 typically gets a prompt to generate a self-signed certificate. If 243 the operator were instead deploying an HTTPS server using ACME, the 244 experience would be something like this: 246 o The operator's ACME client prompts the operator for the intended 247 domain name(s) that the web server is to stand for. 249 o The ACME client presents the operator with a list of CAs from 250 which it could get a certificate. (This list will change over 251 time based on the capabilities of CAs and updates to ACME 252 configuration.) The ACME client might prompt the operator for 253 payment information at this point. 255 o The operator selects a CA. 257 o In the background, the ACME client contacts the CA and requests 258 that it issue a certificate for the intended domain name(s). 260 o The CA verifies that the client controls the requested domain 261 name(s) by having the ACME client perform some action related to 262 the domain name(s). 264 o Once the CA is satisfied, it issues the certificate and the ACME 265 client automatically downloads and installs it, potentially 266 notifying the operator via email, SMS, etc. 268 o The ACME client periodically contacts the CA to get updated 269 certificates, stapled OCSP responses, or whatever else would be 270 required to keep the web server functional and its credentials up- 271 to-date. 273 In this way, it would be nearly as easy to deploy with a CA-issued 274 certificate as with a self-signed certificate. Furthermore, the 275 maintenance of that CA-issued certificate would require minimal 276 manual intervention. Such close integration of ACME with HTTPS 277 servers allows the immediate and automated deployment of certificates 278 as they are issued, sparing the human administrator from much of the 279 time-consuming work described in the previous section. 281 3. Terminology 283 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 284 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 285 document are to be interpreted as described in RFC 2119 [RFC2119]. 287 The two main roles in ACME are "client" and "server". The ACME 288 client uses the protocol to request certificate management actions, 289 such as issuance or revocation. An ACME client may run on a web 290 server, mail server, or some other server system which requires valid 291 TLS certificates. Or, it may run on a separate server that does not 292 consume the certificate, but is authorized to respond to a CA- 293 provided challenge. The ACME server runs at a certification 294 authority, and responds to client requests, performing the requested 295 actions if the client is authorized. 297 An ACME client is represented by an "account key pair". The client 298 uses the private key of this key pair to sign all messages sent to 299 the server. The server uses the public key to verify the 300 authenticity and integrity of messages from the client. 302 4. Protocol Overview 304 ACME allows a client to request certificate management actions using 305 a set of JavaScript Object Notation (JSON) messages carried over 306 HTTPS. Issuance using ACME resembles a traditional CA's issuance 307 process, in which a user creates an account, requests a certificate, 308 and proves control of the domain(s) in that certificate in order for 309 the CA to sign the requested certificate. 311 The first phase of ACME is for the client to request an account with 312 the ACME server. The client generates an asymmetric key pair and 313 requests a new account, optionally providing contact information, 314 agreeing to terms of service, and/or associating the account with an 315 existing account in another system. The creation request is signed 316 with the generated private key to prove that the client controls it. 318 Client Server 320 Contact Information 321 ToS Agreement 322 Additional Data 323 Signature -------> 325 <------- Account 327 Once an account is registered, there are four major steps the client 328 needs to take to get a certificate: 330 1. Submit an order for a certificate to be issued 332 2. Prove control of any identifiers requested in the certificate 334 3. Finalize the order by submitting a CSR 336 4. Await issuance and download the issued certificate 337 The client's order for a certificate describes the desired 338 identifiers plus a few additional fields that capture semantics that 339 are not supported in the CSR format. If the server is willing to 340 consider issuing such a certificate, it responds with a list of 341 requirements that the client must satisfy before the certificate will 342 be issued. 344 For example, in most cases, the server will require the client to 345 demonstrate that it controls the identifiers in the requested 346 certificate. Because there are many different ways to validate 347 possession of different types of identifiers, the server will choose 348 from an extensible set of challenges that are appropriate for the 349 identifier being claimed. The client responds with a set of 350 responses that tell the server which challenges the client has 351 completed. The server then validates that the client has completed 352 the challenges. 354 Once the validation process is complete and the server is satisfied 355 that the client has met its requirements, the client finalizes the 356 order by submitting a PKCS#10 Certificate Signing Request (CSR). The 357 server will issue the requested certificate and make it available to 358 the client. 360 Client Server 362 Order 363 Signature -------> 364 <------- Required Authorizations 366 Responses 367 Signature -------> 369 <~~~~~~~~Validation~~~~~~~~> 371 CSR 372 Signature -------> 374 <~~~~~~Await issuance~~~~~~> 376 <------- Certificate 378 To revoke a certificate, the client sends a signed revocation request 379 indicating the certificate to be revoked: 381 Client Server 383 Revocation request 384 Signature --------> 386 <-------- Result 388 Note that while ACME is defined with enough flexibility to handle 389 different types of identifiers in principle, the primary use case 390 addressed by this document is the case where domain names are used as 391 identifiers. For example, all of the identifier validation 392 challenges described in Section 8 below address validation of domain 393 names. The use of ACME for other identifiers will require further 394 specification in order to describe how these identifiers are encoded 395 in the protocol and what types of validation challenges the server 396 might require. 398 5. Character Encoding 400 All requests and responses sent via HTTP by ACME clients, ACME 401 servers, and validation servers as well as any inputs for digest 402 computations MUST be encoded using the UTF-8 [RFC3629] character set. 404 6. Message Transport 406 Communications between an ACME client and an ACME server are done 407 over HTTPS, using JSON Web Signature (JWS) [RFC7515] to provide some 408 additional security properties for messages sent from the client to 409 the server. HTTPS provides server authentication and 410 confidentiality. With some ACME-specific extensions, JWS provides 411 authentication of the client's request payloads, anti-replay 412 protection, and integrity for the HTTPS request URL. 414 6.1. HTTPS Requests 416 Each ACME function is accomplished by the client sending a sequence 417 of HTTPS requests to the server, carrying JSON messages 418 [RFC2818][RFC7159]. Use of HTTPS is REQUIRED. Each subsection of 419 Section 7 below describes the message formats used by the function 420 and the order in which messages are sent. 422 In most HTTPS transactions used by ACME, the ACME client is the HTTPS 423 client and the ACME server is the HTTPS server. The ACME server acts 424 as an HTTP and HTTPS client when validating challenges via HTTP. 426 ACME servers SHOULD follow the recommendations of [RFC7525] when 427 configuring their TLS implementations. ACME servers that support TLS 428 1.3 MAY allow clients to send early data (0-RTT). This is safe 429 because the ACME protocol itself includes anti-replay protections 430 (see Section 6.4). 432 ACME clients MUST send a User-Agent header, in accordance with 433 [RFC7231]. This header SHOULD include the name and version of the 434 ACME software in addition to the name and version of the underlying 435 HTTP client software. 437 ACME clients SHOULD send an Accept-Language header in accordance with 438 [RFC7231] to enable localization of error messages. 440 ACME servers that are intended to be generally accessible need to use 441 Cross-Origin Resource Sharing (CORS) in order to be accessible from 442 browser-based clients [W3C.CR-cors-20130129]. Such servers SHOULD 443 set the Access-Control-Allow-Origin header field to the value "*". 445 Binary fields in the JSON objects used by ACME are encoded using 446 base64url encoding described in [RFC4648] Section 5, according to the 447 profile specified in JSON Web Signature [RFC7515] Section 2. This 448 encoding uses a URL safe character set. Trailing '=' characters MUST 449 be stripped. 451 6.2. Request Authentication 453 All ACME requests with a non-empty body MUST encapsulate their 454 payload in a JSON Web Signature (JWS) [RFC7515] object, signed using 455 the account's private key unless otherwise specified. The server 456 MUST verify the JWS before processing the request. Encapsulating 457 request bodies in JWS provides authentication of requests. 459 JWS objects sent in ACME requests MUST meet the following additional 460 criteria: 462 o The JWS MUST be in the Flattened JSON Serialization [RFC7515] 464 o The JWS MUST NOT have the value "none" in its "alg" field 466 o The JWS MUST NOT have multiple signatures 468 o The JWS Unencoded Payload Option [RFC7797] MUST NOT be used 470 o The JWS Unprotected Header [RFC7515] MUST NOT be used 472 o The JWS MUST NOT have a Message Authentication Code (MAC)-based 473 algorithm in its "alg" field 475 o The JWS Payload MUST NOT be detached 476 o The JWS Protected Header MUST include the following fields: 478 * "alg" (Algorithm) 480 * "jwk" (JSON Web Key, for all requests not signed using an 481 existing account, e.g. newAccount) 483 * "kid" (Key ID, for all requests signed using an existing 484 account) 486 * "nonce" (defined in Section 6.4 below) 488 * "url" (defined in Section 6.3 below) 490 The "jwk" and "kid" fields are mutually exclusive. Servers MUST 491 reject requests that contain both. 493 For newAccount requests, and for revokeCert requests authenticated by 494 certificate key, there MUST be a "jwk" field. This field MUST 495 contain the public key corresponding to the private key used to sign 496 the JWS. 498 For all other requests, the request is signed using an existing 499 account and there MUST be a "kid" field. This field MUST contain the 500 account URL received by POSTing to the newAccount resource. 502 Note that authentication via signed JWS request bodies implies that 503 GET requests are not authenticated. Servers MUST NOT respond to GET 504 requests for resources that might be considered sensitive. Account 505 resources are the only sensitive resources defined in this 506 specification. 508 If the client sends a JWS signed with an algorithm that the server 509 does not support, then the server MUST return an error with status 510 code 400 (Bad Request) and type 511 "urn:ietf:params:acme:error:badSignatureAlgorithm". The problem 512 document returned with the error MUST include an "algorithms" field 513 with an array of supported "alg" values. 515 Because client requests in ACME carry JWS objects in the Flattened 516 JSON Serialization, they must have the "Content-Type" header field 517 set to "application/jose+json". If a request does not meet this 518 requirement, then the server MUST return a response with status code 519 415 (Unsupported Media Type). 521 6.3. Request URL Integrity 523 It is common in deployment for the entity terminating TLS for HTTPS 524 to be different from the entity operating the logical HTTPS server, 525 with a "request routing" layer in the middle. For example, an ACME 526 CA might have a content delivery network terminate TLS connections 527 from clients so that it can inspect client requests for denial-of- 528 service protection. 530 These intermediaries can also change values in the request that are 531 not signed in the HTTPS request, e.g., the request URL and headers. 532 ACME uses JWS to provide an integrity mechanism, which protects 533 against an intermediary changing the request URL to another ACME URL. 535 As noted in Section 6.2 above, all ACME request objects carry a "url" 536 header parameter in their protected header. This header parameter 537 encodes the URL to which the client is directing the request. On 538 receiving such an object in an HTTP request, the server MUST compare 539 the "url" header parameter to the request URL. If the two do not 540 match, then the server MUST reject the request as unauthorized. 542 Except for the directory resource, all ACME resources are addressed 543 with URLs provided to the client by the server. In requests sent to 544 these resources, the client MUST set the "url" header parameter to 545 the exact string provided by the server (rather than performing any 546 re-encoding on the URL). The server SHOULD perform the corresponding 547 string equality check, configuring each resource with the URL string 548 provided to clients and having the resource check that requests have 549 the same string in their "url" header parameter. 551 6.3.1. "url" (URL) JWS Header Parameter 553 The "url" header parameter specifies the URL [RFC3986] to which this 554 JWS object is directed. The "url" header parameter MUST be carried 555 in the protected header of the JWS. The value of the "url" header 556 parameter MUST be a string representing the URL. 558 6.4. Replay protection 560 In order to protect ACME resources from any possible replay attacks, 561 ACME requests have a mandatory anti-replay mechanism. This mechanism 562 is based on the server maintaining a list of nonces that it has 563 issued to clients, and requiring any signed request from the client 564 to carry such a nonce. 566 An ACME server provides nonces to clients using the Replay-Nonce 567 header field, as specified in Section 6.4.1 below. The server MUST 568 include a Replay-Nonce header field in every successful response to a 569 POST request and SHOULD provide it in error responses as well. 571 Every JWS sent by an ACME client MUST include, in its protected 572 header, the "nonce" header parameter, with contents as defined in 573 Section 6.4.2 below. As part of JWS verification, the ACME server 574 MUST verify that the value of the "nonce" header is a value that the 575 server previously provided in a Replay-Nonce header field. Once a 576 nonce value has appeared in an ACME request, the server MUST consider 577 it invalid, in the same way as a value it had never issued. 579 When a server rejects a request because its nonce value was 580 unacceptable (or not present), it MUST provide HTTP status code 400 581 (Bad Request), and indicate the ACME error type 582 "urn:ietf:params:acme:error:badNonce". An error response with the 583 "badNonce" error type MUST include a Replay-Nonce header with a fresh 584 nonce. On receiving such a response, a client SHOULD retry the 585 request using the new nonce. 587 The precise method used to generate and track nonces is up to the 588 server. For example, the server could generate a random 128-bit 589 value for each response, keep a list of issued nonces, and strike 590 nonces from this list as they are used. 592 6.4.1. Replay-Nonce 594 The "Replay-Nonce" header field includes a server-generated value 595 that the server can use to detect unauthorized replay in future 596 client requests. The server MUST generate the value provided in 597 Replay-Nonce in such a way that they are unique to each message, with 598 high probability. For instance, it is acceptable to generate Replay- 599 Nonces randomly. 601 The value of the Replay-Nonce field MUST be an octet string encoded 602 according to the base64url encoding described in Section 2 of 603 [RFC7515]. Clients MUST ignore invalid Replay-Nonce values. 605 base64url = [A-Z] / [a-z] / [0-9] / "-" / "_" 607 Replay-Nonce = *base64url 609 The Replay-Nonce header field SHOULD NOT be included in HTTP request 610 messages. 612 6.4.2. "nonce" (Nonce) JWS Header Parameter 614 The "nonce" header parameter provides a unique value that enables the 615 verifier of a JWS to recognize when replay has occurred. The "nonce" 616 header parameter MUST be carried in the protected header of the JWS. 618 The value of the "nonce" header parameter MUST be an octet string, 619 encoded according to the base64url encoding described in Section 2 of 620 [RFC7515]. If the value of a "nonce" header parameter is not valid 621 according to this encoding, then the verifier MUST reject the JWS as 622 malformed. 624 6.5. Rate Limits 626 Creation of resources can be rate limited by ACME servers to ensure 627 fair usage and prevent abuse. Once the rate limit is exceeded, the 628 server MUST respond with an error with the type 629 "urn:ietf:params:acme:error:rateLimited". Additionally, the server 630 SHOULD send a "Retry-After" header indicating when the current 631 request may succeed again. If multiple rate limits are in place, 632 that is the time where all rate limits allow access again for the 633 current request with exactly the same parameters. 635 In addition to the human-readable "detail" field of the error 636 response, the server MAY send one or multiple link relations in the 637 "Link" header pointing to documentation about the specific rate limit 638 that was hit, using the "help" link relation type. 640 6.6. Errors 642 Errors can be reported in ACME both at the HTTP layer and within 643 challenge objects as defined in Section 8. ACME servers can return 644 responses with an HTTP error response code (4XX or 5XX). For 645 example: If the client submits a request using a method not allowed 646 in this document, then the server MAY return status code 405 (Method 647 Not Allowed). 649 When the server responds with an error status, it SHOULD provide 650 additional information using a problem document [RFC7807]. To 651 facilitate automatic response to errors, this document defines the 652 following standard tokens for use in the "type" field (within the 653 "urn:ietf:params:acme:error:" namespace): 655 +-------------------------+-----------------------------------------+ 656 | Type | Description | 657 +-------------------------+-----------------------------------------+ 658 | accountDoesNotExist | The request specified an account that | 659 | | does not exist | 660 | | | 661 | badCSR | The CSR is unacceptable (e.g., due to a | 662 | | short key) | 663 | | | 664 | badNonce | The client sent an unacceptable anti- | 665 | | replay nonce | 666 | | | 667 | badRevocationReason | The revocation reason provided is not | 668 | | allowed by the server | 669 | | | 670 | badSignatureAlgorithm | The JWS was signed with an algorithm | 671 | | the server does not support | 672 | | | 673 | caa | Certification Authority Authorization | 674 | | (CAA) records forbid the CA from | 675 | | issuing | 676 | | | 677 | compound | Specific error conditions are indicated | 678 | | in the "subproblems" array. | 679 | | | 680 | connection | The server could not connect to | 681 | | validation target | 682 | | | 683 | dns | There was a problem with a DNS query | 684 | | | 685 | externalAccountRequired | The request must include a value for | 686 | | the "externalAccountBinding" field | 687 | | | 688 | incorrectResponse | Response received didn't match the | 689 | | challenge's requirements | 690 | | | 691 | invalidContact | A contact URL for an account was | 692 | | invalid | 693 | | | 694 | malformed | The request message was malformed | 695 | | | 696 | rateLimited | The request exceeds a rate limit | 697 | | | 698 | rejectedIdentifier | The server will not issue for the | 699 | | identifier | 700 | | | 701 | serverInternal | The server experienced an internal | 702 | | error | 703 | | | 704 | tls | The server received a TLS error during | 705 | | validation | 706 | | | 707 | unauthorized | The client lacks sufficient | 708 | | authorization | 709 | | | 710 | unsupportedContact | A contact URL for an account used an | 711 | | unsupported protocol scheme | 712 | | | 713 | unsupportedIdentifier | Identifier is not supported, but may be | 714 | | in future | 715 | | | 716 | userActionRequired | Visit the "instance" URL and take | 717 | | actions specified there | 718 +-------------------------+-----------------------------------------+ 720 This list is not exhaustive. The server MAY return errors whose 721 "type" field is set to a URI other than those defined above. Servers 722 MUST NOT use the ACME URN [RFC3553] namespace for errors other than 723 the standard types. Clients SHOULD display the "detail" field of all 724 errors. 726 In the remainder of this document, we use the tokens in the table 727 above to refer to error types, rather than the full URNs. For 728 example, an "error of type 'badCSR'" refers to an error document with 729 "type" value "urn:ietf:params:acme:error:badCSR". 731 6.6.1. Subproblems 733 Sometimes a CA may need to return multiple errors in response to a 734 request. Additionally, the CA may need to attribute errors to 735 specific identifiers. For instance, a new-order request may contain 736 multiple identifiers for which the CA cannot issue. In this 737 situation, an ACME problem document MAY contain the "subproblems" 738 field, containing a JSON array of problem documents, each of which 739 MAY contain an "identifier" field. If present, the "identifier" 740 field MUST contain an ACME identifier (Section 9.7.7). The 741 "identifier" field MUST NOT be present at the top level in ACME 742 problem documents. It can only be present in subproblems. 743 Subproblems need not all have the same type, and do not need to match 744 the top level type. 746 ACME clients may choose to use the "identifier" field of a subproblem 747 as a hint that an operation would succeed if that identifier were 748 omitted. For instance, if an order contains ten DNS identifiers, and 749 the new-order request returns a problem document with two 750 subproblems, referencing two of those identifiers, the ACME client 751 may choose to submit another order containing only the eight 752 identifiers not listed in the problem document. 754 HTTP/1.1 403 Forbidden 755 Content-Type: application/problem+json 757 { 758 "type": "urn:ietf:params:acme:error:malformed", 759 "detail": "Some of the identifiers requested were rejected", 760 "subproblems": [ 761 { 762 "type": "urn:ietf:params:acme:error:malformed", 763 "detail": "Invalid underscore in DNS name \"_example.com\"", 764 "identifier": { 765 "type": "dns", 766 "value": "_example.com" 767 } 768 }, 769 { 770 "type": "urn:ietf:params:acme:error:rejectedIdentifier", 771 "detail": "This CA will not issue for \"example.net\"", 772 "identifier": { 773 "type": "dns", 774 "value": "example.net" 775 } 776 } 777 ] 778 } 780 7. Certificate Management 782 In this section, we describe the certificate management functions 783 that ACME enables: 785 o Account Creation 787 o Ordering a Certificate 789 o Identifier Authorization 791 o Certificate Issuance 793 o Certificate Revocation 795 7.1. Resources 797 ACME is structured as a REST application with the following types of 798 resources: 800 o Account resources, representing information about an account 801 (Section 7.1.2, Section 7.3) 803 o Order resources, representing an account's requests to issue 804 certificates (Section 7.1.3) 806 o Authorization resources, representing an account's authorization 807 to act for an identifier (Section 7.1.4) 809 o Challenge resources, representing a challenge to prove control of 810 an identifier (Section 7.5, Section 8) 812 o Certificate resources, representing issued certificates 813 (Section 7.4.2) 815 o A "directory" resource (Section 7.1.1) 817 o A "newNonce" resource (Section 7.2) 819 o A "newAccount" resource (Section 7.3) 821 o A "newOrder" resource (Section 7.4) 823 o A "revokeCert" resource (Section 7.6) 825 o A "keyChange" resource (Section 7.3.6) 827 The server MUST provide "directory" and "newNonce" resources. 829 ACME uses different URLs for different management functions. Each 830 function is listed in a directory along with its corresponding URL, 831 so clients only need to be configured with the directory URL. These 832 URLs are connected by a few different link relations [RFC5988]. 834 The "up" link relation is used with challenge resources to indicate 835 the authorization resource to which a challenge belongs. It is also 836 used from certificate resources to indicate a resource from which the 837 client may fetch a chain of CA certificates that could be used to 838 validate the certificate in the original resource. 840 The "index" link relation is present on all resources other than the 841 directory and indicates the URL of the directory. 843 The following diagram illustrates the relations between resources on 844 an ACME server. For the most part, these relations are expressed by 845 URLs provided as strings in the resources' JSON representations. 846 Lines with labels in quotes indicate HTTP link relations. 848 directory 849 | 850 +--> newNonce 851 | 852 +----------+----------+-----+-----+------------+ 853 | | | | | 854 | | | | | 855 V V V V V 856 newAccount newAuthz newOrder revokeCert keyChange 857 | | | 858 | | | 859 V | V 860 account | order --+--> finalize 861 | | | 862 | | +--> cert 863 | V 864 +---> authorization 865 | ^ 866 | | "up" 867 V | 868 challenge 870 The following table illustrates a typical sequence of requests 871 required to establish a new account with the server, prove control of 872 an identifier, issue a certificate, and fetch an updated certificate 873 some time after issuance. The "->" is a mnemonic for a Location 874 header pointing to a created resource. 876 +-----------------------+--------------------------+----------------+ 877 | Action | Request | Response | 878 +-----------------------+--------------------------+----------------+ 879 | Get directory | GET directory | 200 | 880 | | | | 881 | Get nonce | HEAD newNonce | 200 | 882 | | | | 883 | Create account | POST newAccount | 201 -> account | 884 | | | | 885 | Submit order | POST newOrder | 201 -> order | 886 | | | | 887 | Fetch challenges | GET order | 200 | 888 | | authorizations | | 889 | | | | 890 | Respond to challenges | POST challenge urls | 200 | 891 | | | | 892 | Poll for status | GET order | 200 | 893 | | | | 894 | Finalize order | POST order finalize | 200 | 895 | | | | 896 | Poll for status | GET order | 200 | 897 | | | | 898 | Download certificate | GET order certificate | 200 | 899 +-----------------------+--------------------------+----------------+ 901 The remainder of this section provides the details of how these 902 resources are structured and how the ACME protocol makes use of them. 904 7.1.1. Directory 906 In order to help clients configure themselves with the right URLs for 907 each ACME operation, ACME servers provide a directory object. This 908 should be the only URL needed to configure clients. It is a JSON 909 object, whose field names are drawn from the following table and 910 whose values are the corresponding URLs. 912 +------------+--------------------+ 913 | Field | URL in value | 914 +------------+--------------------+ 915 | newNonce | New nonce | 916 | | | 917 | newAccount | New account | 918 | | | 919 | newOrder | New order | 920 | | | 921 | newAuthz | New authorization | 922 | | | 923 | revokeCert | Revoke certificate | 924 | | | 925 | keyChange | Key change | 926 +------------+--------------------+ 928 There is no constraint on the URL of the directory except that it 929 should be different from the other ACME server resources' URLs, and 930 that it should not clash with other services. For instance: 932 o a host which functions as both an ACME and a Web server may want 933 to keep the root path "/" for an HTML "front page", and place the 934 ACME directory under the path "/acme". 936 o a host which only functions as an ACME server could place the 937 directory under the path "/". 939 If the ACME server does not implement pre-authorization 940 (Section 7.4.1) it MUST omit the "newAuthz" field of the directory. 942 The object MAY additionally contain a field "meta". If present, it 943 MUST be a JSON object; each field in the object is an item of 944 metadata relating to the service provided by the ACME server. 946 The following metadata items are defined, all of which are OPTIONAL: 948 termsOfService (optional, string): A URL identifying the current 949 terms of service. 951 website (optional, string): An HTTP or HTTPS URL locating a website 952 providing more information about the ACME server. 954 caaIdentities (optional, array of string): Each string MUST be a 955 lowercase hostname which the ACME server recognizes as referring 956 to itself for the purposes of CAA record validation as defined in 957 [RFC6844]. This allows clients to determine the correct issuer 958 domain name to use when configuring CAA records. 960 externalAccountRequired (optional, boolean): If this field is 961 present and set to "true", then the CA requires that all new- 962 account requests include an "externalAccountBinding" field 963 associating the new account with an external account. 965 Clients access the directory by sending a GET request to the 966 directory URL. 968 HTTP/1.1 200 OK 969 Content-Type: application/json 971 { 972 "newNonce": "https://example.com/acme/new-nonce", 973 "newAccount": "https://example.com/acme/new-account", 974 "newOrder": "https://example.com/acme/new-order", 975 "newAuthz": "https://example.com/acme/new-authz", 976 "revokeCert": "https://example.com/acme/revoke-cert", 977 "keyChange": "https://example.com/acme/key-change", 978 "meta": { 979 "termsOfService": "https://example.com/acme/terms/2017-5-30", 980 "website": "https://www.example.com/", 981 "caaIdentities": ["example.com"], 982 "externalAccountRequired": false 983 } 984 } 986 7.1.2. Account Objects 988 An ACME account resource represents a set of metadata associated with 989 an account. Account resources have the following structure: 991 status (required, string): The status of this account. Possible 992 values are: "valid", "deactivated", and "revoked". The value 993 "deactivated" should be used to indicate client-initiated 994 deactivation whereas "revoked" should be used to indicate server- 995 initiated deactivation. 997 contact (optional, array of string): An array of URLs that the 998 server can use to contact the client for issues related to this 999 account. For example, the server may wish to notify the client 1000 about server-initiated revocation or certificate expiration. 1002 termsOfServiceAgreed (optional, boolean): Including this field in a 1003 new-account request, with a value of true, indicates the client's 1004 agreement with the terms of service. This field is not updateable 1005 by the client. 1007 orders (required, string): A URL from which a list of orders 1008 submitted by this account can be fetched via a GET request, as 1009 described in Section 7.1.2.1. 1011 { 1012 "status": "valid", 1013 "contact": [ 1014 "mailto:cert-admin@example.com", 1015 "mailto:admin@example.com" 1016 ], 1017 "termsOfServiceAgreed": true, 1018 "orders": "https://example.com/acme/acct/1/orders" 1019 } 1021 7.1.2.1. Orders List 1023 Each account object includes an "orders" URL from which a list of 1024 orders created by the account can be fetched via GET request. The 1025 result of the GET request MUST be a JSON object whose "orders" field 1026 is an array of URLs, each identifying an order belonging to the 1027 account. The server SHOULD include pending orders, and SHOULD NOT 1028 include orders that are invalid in the array of URLs. The server MAY 1029 return an incomplete list, along with a Link header with a "next" 1030 link relation indicating where further entries can be acquired. 1032 HTTP/1.1 200 OK 1033 Content-Type: application/json 1034 Link: ;rel="next" 1036 { 1037 "orders": [ 1038 "https://example.com/acme/acct/1/order/1", 1039 "https://example.com/acme/acct/1/order/2", 1040 /* 47 more URLs not shown for example brevity */ 1041 "https://example.com/acme/acct/1/order/50" 1042 ] 1043 } 1045 7.1.3. Order Objects 1047 An ACME order object represents a client's request for a certificate 1048 and is used to track the progress of that order through to issuance. 1049 Thus, the object contains information about the requested 1050 certificate, the authorizations that the server requires the client 1051 to complete, and any certificates that have resulted from this order. 1053 status (required, string): The status of this order. Possible 1054 values are: "pending", "ready", "processing", "valid", and 1055 "invalid". 1057 expires (optional, string): The timestamp after which the server 1058 will consider this order invalid, encoded in the format specified 1059 in RFC 3339 [RFC3339]. This field is REQUIRED for objects with 1060 "pending" or "valid" in the status field. 1062 identifiers (required, array of object): An array of identifier 1063 objects that the order pertains to. 1065 type (required, string): The type of identifier. 1067 value (required, string): The identifier itself. 1069 notBefore (optional, string): The requested value of the notBefore 1070 field in the certificate, in the date format defined in [RFC3339]. 1072 notAfter (optional, string): The requested value of the notAfter 1073 field in the certificate, in the date format defined in [RFC3339]. 1075 error (optional, object): The error that occurred while processing 1076 the order, if any. This field is structured as a problem document 1077 [RFC7807]. 1079 authorizations (required, array of string): For pending orders, the 1080 authorizations that the client needs to complete before the 1081 requested certificate can be issued (see Section 7.5). The 1082 authorizations required are dictated by server policy and there 1083 may not be a 1:1 relationship between the order identifiers and 1084 the authorizations required. For final orders (in the "valid" or 1085 "invalid" state), the authorizations that were completed. Each 1086 entry is a URL from which an authorization can be fetched with a 1087 GET request. 1089 finalize (required, string): A URL that a CSR must be POSTed to once 1090 all of the order's authorizations are satisfied to finalize the 1091 order. The result of a successful finalization will be the 1092 population of the certificate URL for the order. 1094 certificate (optional, string): A URL for the certificate that has 1095 been issued in response to this order. 1097 { 1098 "status": "valid", 1099 "expires": "2015-03-01T14:09:00Z", 1101 "identifiers": [ 1102 { "type": "dns", "value": "example.com" }, 1103 { "type": "dns", "value": "www.example.com" } 1104 ], 1106 "notBefore": "2016-01-01T00:00:00Z", 1107 "notAfter": "2016-01-08T00:00:00Z", 1109 "authorizations": [ 1110 "https://example.com/acme/authz/1234", 1111 "https://example.com/acme/authz/2345" 1112 ], 1114 "finalize": "https://example.com/acme/acct/1/order/1/finalize", 1116 "certificate": "https://example.com/acme/cert/1234" 1117 } 1119 Any identifier of type "dns" in a new-order request MAY have a 1120 wildcard domain name as its value. A wildcard domain name consists 1121 of a single asterisk character followed by a single full stop 1122 character ("*.") followed by a domain name as defined for use in the 1123 Subject Alternate Name Extension by RFC 5280 [RFC5280]. An 1124 authorization returned by the server for a wildcard domain name 1125 identifier MUST NOT include the asterisk and full stop ("*.") prefix 1126 in the authorization identifier value. The returned authorization 1127 MUST include the optional "wildcard" field, with a value of true. 1129 The elements of the "authorizations" and "identifiers" array are 1130 immutable once set. The server MUST NOT change the contents of 1131 either array after they are created. If a client observes a change 1132 in the contents of either array, then it SHOULD consider the order 1133 invalid. 1135 The "authorizations" array of the order SHOULD reflect all 1136 authorizations that the CA takes into account in deciding to issue, 1137 even if some authorizations were fulfilled in earlier orders or in 1138 pre-authorization transactions. For example, if a CA allows multiple 1139 orders to be fulfilled based on a single authorization transaction, 1140 then it SHOULD reflect that authorization in all of the orders. 1142 7.1.4. Authorization Objects 1144 An ACME authorization object represents a server's authorization for 1145 an account to represent an identifier. In addition to the 1146 identifier, an authorization includes several metadata fields, such 1147 as the status of the authorization (e.g., "pending", "valid", or 1148 "revoked") and which challenges were used to validate possession of 1149 the identifier. 1151 The structure of an ACME authorization resource is as follows: 1153 identifier (required, object): The identifier that the account is 1154 authorized to represent 1156 type (required, string): The type of identifier. 1158 value (required, string): The identifier itself. 1160 status (required, string): The status of this authorization. 1161 Possible values are: "pending", "valid", "invalid", "deactivated", 1162 "expired", and "revoked". 1164 expires (optional, string): The timestamp after which the server 1165 will consider this authorization invalid, encoded in the format 1166 specified in RFC 3339 [RFC3339]. This field is REQUIRED for 1167 objects with "valid" in the "status" field. 1169 challenges (required, array of objects): For pending authorizations, 1170 the challenges that the client can fulfill in order to prove 1171 possession of the identifier. For final authorizations (in the 1172 "valid" or "invalid" state), the challenges that were used. Each 1173 array entry is an object with parameters required to validate the 1174 challenge. A client should attempt to fulfill one of these 1175 challenges, and a server should consider any one of the challenges 1176 sufficient to make the authorization valid. 1178 wildcard (optional, boolean): For authorizations created as a result 1179 of a newOrder request containing a DNS identifier with a value 1180 that contained a wildcard prefix this field MUST be present, and 1181 true. 1183 The only type of identifier defined by this specification is a fully- 1184 qualified domain name (type: "dns"). If a domain name contains non- 1185 ASCII Unicode characters it MUST be encoded using the rules defined 1186 in [RFC3492]. Servers MUST verify any identifier values that begin 1187 with the ASCII Compatible Encoding prefix "xn--" as defined in 1188 [RFC5890] are properly encoded. Wildcard domain names (with "*" as 1189 the first label) MUST NOT be included in authorization objects. If 1190 an authorization object conveys authorization for the base domain of 1191 a newOrder DNS type identifier with a wildcard prefix then the 1192 optional authorizations "wildcard" field MUST be present with a value 1193 of true. 1195 Section 8 describes a set of challenges for domain name validation. 1197 { 1198 "status": "valid", 1199 "expires": "2015-03-01T14:09:00Z", 1201 "identifier": { 1202 "type": "dns", 1203 "value": "example.org" 1204 }, 1206 "challenges": [ 1207 { 1208 "url": "https://example.com/acme/authz/1234/0", 1209 "type": "http-01", 1210 "status": "valid", 1211 "token": "DGyRejmCefe7v4NfDGDKfA", 1212 "validated": "2014-12-01T12:05:00Z" 1213 } 1214 ], 1216 "wildcard": false 1217 } 1219 7.1.5. Challenge Objects 1221 An ACME challenge object represents a server's offer to validate a 1222 client's possession of an identifier in a specific way. Unlike the 1223 other objects listed above, there is not a single standard structure 1224 for a challenge object. The contents of a challenge object depend on 1225 the validation method being used. The general structure of challenge 1226 objects and an initial set of validation methods are described in 1227 Section 8. 1229 7.1.6. Status Changes 1231 Each ACME object type goes through a simple state machine over its 1232 lifetime. The "status" field of the object indicates which state the 1233 object is currently in. 1235 Challenge objects are created in the "pending" state. They 1236 transition to the "processing" state when the client responds to the 1237 challenge (see Section 7.5.1) and the server begins attempting to 1238 validate that the client has completed the challenge. Note that 1239 within the "processing" state, the server may attempt to validate the 1240 challenge multiple times (see Section 8.2). Likewise, client 1241 requests for retries do not cause a state change. If validation is 1242 successful, the challenge moves to the "valid" state; if there is an 1243 error, the challenge moves to the "invalid" state. 1245 pending 1246 | 1247 | Receive 1248 | response 1249 V 1250 processing <-+ 1251 | | | Server retry or 1252 | | | client retry request 1253 | +----+ 1254 | 1255 | 1256 Successful | Failed 1257 validation | validation 1258 +---------+---------+ 1259 | | 1260 V V 1261 valid invalid 1263 Authorization objects are created in the "pending" state. If one of 1264 the challenges listed in the authorization transitions to the "valid" 1265 state, then the authorization also changes to the "valid" state. If 1266 there is an error while the authorization is still pending, then the 1267 authorization transitions to the "invalid" state. Once the 1268 authorization is in the valid state, it can expire ("expired"), be 1269 deactivated by the client ("deactivated", see Section 7.5.2), or 1270 revoked by the server ("revoked"). 1272 pending --------------------+ 1273 | | 1274 | | 1275 Error | Challenge valid | 1276 +---------+---------+ | 1277 | | | 1278 V V | 1279 invalid valid | 1280 | | 1281 | | 1282 | | 1283 +--------------+--------------+ 1284 | | | 1285 | | | 1286 Server | Client | Time after | 1287 revoke | deactivate | "expires" | 1288 V V V 1289 revoked deactivated expired 1291 Order objects are created in the "pending" state. Once all of the 1292 authorizations listed in the order object are in the "valid" state, 1293 the order transitions to the "ready" state. The order moves to the 1294 "processing" state after the client submits a request to the order's 1295 "finalize" URL and the CA begins the issuance process for the 1296 certificate. Once the certificate is issued, the order enters the 1297 "valid" state. If an error occurs at any of these stages, the order 1298 moves to the "invalid" state. The order also moves to the "invalid" 1299 state if it expires, or one of its authorizations enters a final 1300 state other than "valid" ("expired", "revoked", "deactivated"). 1302 pending --------------+ 1303 | | 1304 | All authz | 1305 | "valid" | 1306 V | 1307 ready ---------------+ 1308 | | 1309 | Receive | 1310 | finalize | 1311 | request | 1312 V | 1313 processing ------------+ 1314 | | 1315 | Certificate | Error or 1316 | issued | Authorization failure 1317 V V 1318 valid invalid 1320 Account objects are created in the "valid" state, since no further 1321 action is required to create an account after a successful newAccount 1322 request. If the account is deactivated by the client or revoked by 1323 the server, it moves to the corresponding state. 1325 valid 1326 | 1327 | 1328 +-----------+-----------+ 1329 Client | Server | 1330 deactiv.| revoke | 1331 V V 1332 deactivated revoked 1334 Note that some of these states may not ever appear in a "status" 1335 field, depending on server behavior. For example, a server that 1336 issues synchronously will never show an order in the "processing" 1337 state. A server that deletes expired authorizations immediately will 1338 never show an authorization in the "expired" state. 1340 7.2. Getting a Nonce 1342 Before sending a POST request to the server, an ACME client needs to 1343 have a fresh anti-replay nonce to put in the "nonce" header of the 1344 JWS. In most cases, the client will have gotten a nonce from a 1345 previous request. However, the client might sometimes need to get a 1346 new nonce, e.g., on its first request to the server or if an existing 1347 nonce is no longer valid. 1349 To get a fresh nonce, the client sends a HEAD request to the new- 1350 nonce resource on the server. The server's response MUST include a 1351 Replay-Nonce header field containing a fresh nonce, and SHOULD have 1352 status code 200 (OK). The server SHOULD also respond to GET requests 1353 for this resource, returning an empty body (while still providing a 1354 Replay-Nonce header) with a 204 (No Content) status. 1356 HEAD /acme/new-nonce HTTP/1.1 1357 Host: example.com 1359 HTTP/1.1 200 OK 1360 Replay-Nonce: oFvnlFP1wIhRlYS2jTaXbA 1361 Cache-Control: no-store 1363 Proxy caching of responses from the new-nonce resource can cause 1364 clients receive the same nonce repeatedly, leading to badNonce 1365 errors. The server MUST include a Cache-Control header field with 1366 the "no-store" directive in responses for the new-nonce resource, in 1367 order to prevent caching of this resource. 1369 7.3. Account Creation 1371 A client creates a new account with the server by sending a POST 1372 request to the server's new-account URL. The body of the request is 1373 a stub account object optionally containing the "contact" and 1374 "termsOfServiceAgreed" fields. 1376 contact (optional, array of string): Same meaning as the 1377 corresponding server field defined in Section 7.1.2 1379 termsOfServiceAgreed (optional, boolean): Same meaning as the 1380 corresponding server field defined in Section 7.1.2 1382 onlyReturnExisting (optional, boolean): If this field is present 1383 with the value "true", then the server MUST NOT create a new 1384 account if one does not already exist. This allows a client to 1385 look up an account URL based on an account key (see 1386 Section 7.3.1). 1388 externalAccountBinding (optional, object): An optional field for 1389 binding the new account with an existing non-ACME account (see 1390 Section 7.3.5). 1392 POST /acme/new-account HTTP/1.1 1393 Host: example.com 1394 Content-Type: application/jose+json 1396 { 1397 "protected": base64url({ 1398 "alg": "ES256", 1399 "jwk": {...}, 1400 "nonce": "6S8IqOGY7eL2lsGoTZYifg", 1401 "url": "https://example.com/acme/new-account" 1402 }), 1403 "payload": base64url({ 1404 "termsOfServiceAgreed": true, 1405 "contact": [ 1406 "mailto:cert-admin@example.com", 1407 "mailto:admin@example.com" 1408 ] 1409 }), 1410 "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I" 1411 } 1413 The server MUST ignore any values provided in the "orders" fields in 1414 account bodies sent by the client, as well as any other fields that 1415 it does not recognize. If new fields are specified in the future, 1416 the specification of those fields MUST describe whether they can be 1417 provided by the client. 1419 In general, the server MUST ignore any fields in the request object 1420 that it does not recognize. In particular, it MUST NOT reflect 1421 unrecognized fields in the resulting account object. This allows 1422 clients to detect when servers do not support an extension field. 1424 The server SHOULD validate that the contact URLs in the "contact" 1425 field are valid and supported by the server. If the server validates 1426 contact URLs it MUST support the "mailto" scheme. Clients MUST NOT 1427 provide a "mailto" URL in the "contact" field that contains "hfields" 1428 [RFC6068], or more than one "addr-spec" in the "to" component. If a 1429 server encounters a "mailto" contact URL that does not meet these 1430 criteria, then it SHOULD reject it as invalid. 1432 If the server rejects a contact URL for using an unsupported scheme 1433 it MUST return an error of type "unsupportedContact", with a 1434 description describing the error and what types of contact URLs the 1435 server considers acceptable. If the server rejects a contact URL for 1436 using a supported scheme but an invalid value then the server MUST 1437 return an error of type "invalidContact". 1439 If the server wishes to present the client with terms under which the 1440 ACME service is to be used, it MUST indicate the URL where such terms 1441 can be accessed in the "termsOfService" subfield of the "meta" field 1442 in the directory object, and the server MUST reject new-account 1443 requests that do not have the "termsOfServiceAgreed" field set to 1444 "true". Clients SHOULD NOT automatically agree to terms by default. 1445 Rather, they SHOULD require some user interaction for agreement to 1446 terms. 1448 The server creates an account and stores the public key used to 1449 verify the JWS (i.e., the "jwk" element of the JWS header) to 1450 authenticate future requests from the account. The server returns 1451 this account object in a 201 (Created) response, with the account URL 1452 in a Location header field. The account URL is used as the "kid" 1453 value in the JWS authenticating subsequent requests by this account 1454 (See Section 6.2). 1456 HTTP/1.1 201 Created 1457 Content-Type: application/json 1458 Replay-Nonce: D8s4D2mLs8Vn-goWuPQeKA 1459 Location: https://example.com/acme/acct/1 1460 Link: ;rel="index" 1462 { 1463 "status": "valid", 1465 "contact": [ 1466 "mailto:cert-admin@example.com", 1467 "mailto:admin@example.com" 1468 ], 1470 "orders": "https://example.com/acme/acct/1/orders" 1471 } 1473 7.3.1. Finding an Account URL Given a Key 1475 If the server already has an account registered with the provided 1476 account key, then it MUST return a response with a 200 (OK) status 1477 code and provide the URL of that account in the Location header 1478 field. This allows a client that has an account key but not the 1479 corresponding account URL to recover the account URL. 1481 If a client wishes to find the URL for an existing account and does 1482 not want an account to be created if one does not already exist, then 1483 it SHOULD do so by sending a POST request to the new-account URL with 1484 a JWS whose payload has an "onlyReturnExisting" field set to "true" 1485 ({"onlyReturnExisting": true}). If a client sends such a request and 1486 an account does not exist, then the server MUST return an error 1487 response with status code 400 (Bad Request) and type 1488 "urn:ietf:params:acme:error:accountDoesNotExist". 1490 7.3.2. Account Update 1492 If the client wishes to update this information in the future, it 1493 sends a POST request with updated information to the account URL. 1494 The server MUST ignore any updates to the "orders" field or any other 1495 fields it does not recognize. If the server accepts the update, it 1496 MUST return a response with a 200 (OK) status code and the resulting 1497 account object. 1499 For example, to update the contact information in the above account, 1500 the client could send the following request: 1502 POST /acme/acct/1 HTTP/1.1 1503 Host: example.com 1504 Content-Type: application/jose+json 1506 { 1507 "protected": base64url({ 1508 "alg": "ES256", 1509 "kid": "https://example.com/acme/acct/1", 1510 "nonce": "ax5RnthDqp_Yf4_HZnFLmA", 1511 "url": "https://example.com/acme/acct/1" 1512 }), 1513 "payload": base64url({ 1514 "contact": [ 1515 "mailto:certificates@example.com", 1516 "mailto:admin@example.com" 1517 ] 1518 }), 1519 "signature": "hDXzvcj8T6fbFbmn...rDzXzzvzpRy64N0o" 1520 } 1522 7.3.3. Account Information 1524 Servers MUST NOT respond to GET requests for account resources as 1525 these requests are not authenticated. If a client wishes to query 1526 the server for information about its account (e.g., to examine the 1527 "contact" or "orders" fields), then it SHOULD do so by sending a POST 1528 request with an empty update. That is, it should send a JWS whose 1529 payload is an empty object ({}). 1531 7.3.4. Changes of Terms of Service 1533 As described above, a client can indicate its agreement with the CA's 1534 terms of service by setting the "termsOfServiceAgreed" field in its 1535 account object to "true". 1537 If the server has changed its terms of service since a client 1538 initially agreed, and the server is unwilling to process a request 1539 without explicit agreement to the new terms, then it MUST return an 1540 error response with status code 403 (Forbidden) and type 1541 "urn:ietf:params:acme:error:userActionRequired". This response MUST 1542 include a Link header with link relation "terms-of-service" and the 1543 latest terms-of-service URL. 1545 The problem document returned with the error MUST also include an 1546 "instance" field, indicating a URL that the client should direct a 1547 human user to visit in order for instructions on how to agree to the 1548 terms. 1550 HTTP/1.1 403 Forbidden 1551 Replay-Nonce: IXVHDyxIRGcTE0VSblhPzw 1552 Link: ;rel="terms-of-service" 1553 Content-Type: application/problem+json 1554 Content-Language: en 1556 { 1557 "type": "urn:ietf:params:acme:error:userActionRequired", 1558 "detail": "Terms of service have changed", 1559 "instance": "https://example.com/acme/agreement/?token=W8Ih3PswD-8" 1560 } 1562 7.3.5. External Account Binding 1564 The server MAY require a value for the "externalAccountBinding" field 1565 to be present in "newAccount" requests. This can be used to 1566 associate an ACME account with an existing account in a non-ACME 1567 system, such as a CA customer database. 1569 To enable ACME account binding, the CA operating the ACME server 1570 needs to provide the ACME client with a MAC key and a key identifier, 1571 using some mechanism outside of ACME. The key identifier MUST be an 1572 ASCII string. The MAC key SHOULD be provided in base64url-encoded 1573 form, to maximize compatibility between non-ACME provisioning systems 1574 and ACME clients. 1576 The ACME client then computes a binding JWS to indicate the external 1577 account holder's approval of the ACME account key. The payload of 1578 this JWS is the account key being registered, in JWK form. The 1579 protected header of the JWS MUST meet the following criteria: 1581 o The "alg" field MUST indicate a MAC-based algorithm 1583 o The "kid" field MUST contain the key identifier provided by the CA 1585 o The "nonce" field MUST NOT be present 1587 o The "url" field MUST be set to the same value as the outer JWS 1589 The "signature" field of the JWS will contain the MAC value computed 1590 with the MAC key provided by the CA. 1592 POST /acme/new-account HTTP/1.1 1593 Host: example.com 1594 Content-Type: application/jose+json 1596 { 1597 "protected": base64url({ 1598 "alg": "ES256", 1599 "jwk": /* account key */, 1600 "nonce": "K60BWPrMQG9SDxBDS_xtSw", 1601 "url": "https://example.com/acme/new-account" 1602 }), 1603 "payload": base64url({ 1604 "contact": ["mailto:example@anonymous.invalid"], 1605 "termsOfServiceAgreed": true, 1607 "externalAccountBinding": { 1608 "protected": base64url({ 1609 "alg": "HS256", 1610 "kid": /* key identifier from CA */, 1611 "url": "https://example.com/acme/new-account" 1612 }), 1613 "payload": base64url(/* same as in "jwk" above */), 1614 "signature": /* MAC using MAC key from CA */ 1615 } 1616 }), 1617 "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4" 1618 } 1620 If a CA requires that new-account requests contain an 1621 "externalAccountBinding" field, then it MUST provide the value "true" 1622 in the "externalAccountRequired" subfield of the "meta" field in the 1623 directory object. If the CA receives a new-account request without 1624 an "externalAccountBinding" field, then it SHOULD reply with an error 1625 of type "externalAccountRequired". 1627 When a CA receives a new-account request containing an 1628 "externalAccountBinding" field, it decides whether or not to verify 1629 the binding. If the CA does not verify the binding, then it MUST NOT 1630 reflect the "externalAccountBinding" field in the resulting account 1631 object (if any). To verify the account binding, the CA MUST take the 1632 following steps: 1634 1. Verify that the value of the field is a well-formed JWS 1636 2. Verify that the JWS protected field meets the above criteria 1638 3. Retrieve the MAC key corresponding to the key identifier in the 1639 "kid" field 1641 4. Verify that the MAC on the JWS verifies using that MAC key 1643 5. Verify that the payload of the JWS represents the same key as was 1644 used to verify the outer JWS (i.e., the "jwk" field of the outer 1645 JWS) 1647 If all of these checks pass and the CA creates a new account, then 1648 the CA may consider the new account associated with the external 1649 account corresponding to the MAC key and MUST reflect the value of 1650 the "externalAccountBinding" field in the resulting account object. 1651 If any of these checks fail, then the CA MUST reject the new-account 1652 request. 1654 7.3.6. Account Key Roll-over 1656 A client may wish to change the public key that is associated with an 1657 account in order to recover from a key compromise or proactively 1658 mitigate the impact of an unnoticed key compromise. 1660 To change the key associated with an account, the client first 1661 constructs a key-change object describing the change that it would 1662 like the server to make: 1664 account (required, string): The URL for the account being modified. 1665 The content of this field MUST be the exact string provided in the 1666 Location header field in response to the new-account request that 1667 created the account. 1669 newKey (required, JWK): The JWK representation of the new key 1671 The client then encapsulates the key-change object in an "inner" JWS, 1672 signed with the requested new account key (i.e., the key matching the 1673 "newKey" value). This JWS then becomes the payload for the "outer" 1674 JWS that is the body of the ACME request. 1676 The outer JWS MUST meet the normal requirements for an ACME JWS (see 1677 Section 6.2). The inner JWS MUST meet the normal requirements, with 1678 the following differences: 1680 o The inner JWS MUST have a "jwk" header parameter, containing the 1681 public key of the new key pair (i.e., the same value as the 1682 "newKey" field). 1684 o The inner JWS MUST have the same "url" header parameter as the 1685 outer JWS. 1687 o The inner JWS is NOT REQUIRED to have a "nonce" header parameter. 1688 The server MUST ignore any value provided for the "nonce" header 1689 parameter. 1691 This transaction has signatures from both the old and new keys so 1692 that the server can verify that the holders of the two keys both 1693 agree to the change. The signatures are nested to preserve the 1694 property that all signatures on POST messages are signed by exactly 1695 one key. 1697 POST /acme/key-change HTTP/1.1 1698 Host: example.com 1699 Content-Type: application/jose+json 1701 { 1702 "protected": base64url({ 1703 "alg": "ES256", 1704 "kid": "https://example.com/acme/acct/1", 1705 "nonce": "K60BWPrMQG9SDxBDS_xtSw", 1706 "url": "https://example.com/acme/key-change" 1707 }), 1708 "payload": base64url({ 1709 "protected": base64url({ 1710 "alg": "ES256", 1711 "jwk": /* new key */, 1712 "url": "https://example.com/acme/key-change" 1713 }), 1714 "payload": base64url({ 1715 "account": "https://example.com/acme/acct/1", 1716 "newKey": /* new key */ 1717 }), 1718 "signature": "Xe8B94RD30Azj2ea...8BmZIRtcSKPSd8gU" 1719 }), 1720 "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4" 1721 } 1723 On receiving key-change request, the server MUST perform the 1724 following steps in addition to the typical JWS validation: 1726 1. Validate the POST request belongs to a currently active account, 1727 as described in Section 6. 1729 2. Check that the payload of the JWS is a well-formed JWS object 1730 (the "inner JWS"). 1732 3. Check that the JWS protected header of the inner JWS has a "jwk" 1733 field. 1735 4. Check that the inner JWS verifies using the key in its "jwk" 1736 field. 1738 5. Check that the payload of the inner JWS is a well-formed key- 1739 change object (as described above). 1741 6. Check that the "url" parameters of the inner and outer JWSs are 1742 the same. 1744 7. Check that the "account" field of the key-change object contains 1745 the URL for the account matching the old key. 1747 8. Check that the "newKey" field of the key-change object also 1748 verifies the inner JWS. 1750 9. Check that no account exists whose account key is the same as the 1751 key in the "newKey" field. 1753 If all of these checks pass, then the server updates the 1754 corresponding account by replacing the old account key with the new 1755 public key and returns status code 200 (OK). Otherwise, the server 1756 responds with an error status code and a problem document describing 1757 the error. If there is an existing account with the new key 1758 provided, then the server SHOULD use status code 409 (Conflict) and 1759 provide the URL of that account in the Location header field. 1761 Note that changing the account key for an account SHOULD NOT have any 1762 other impact on the account. For example, the server MUST NOT 1763 invalidate pending orders or authorization transactions based on a 1764 change of account key. 1766 7.3.7. Account Deactivation 1768 A client can deactivate an account by posting a signed update to the 1769 server with a status field of "deactivated." Clients may wish to do 1770 this when the account key is compromised or decommissioned. 1772 POST /acme/acct/1 HTTP/1.1 1773 Host: example.com 1774 Content-Type: application/jose+json 1776 { 1777 "protected": base64url({ 1778 "alg": "ES256", 1779 "kid": "https://example.com/acme/acct/1", 1780 "nonce": "ntuJWWSic4WVNSqeUmshgg", 1781 "url": "https://example.com/acme/acct/1" 1782 }), 1783 "payload": base64url({ 1784 "status": "deactivated" 1785 }), 1786 "signature": "earzVLd3m5M4xJzR...bVTqn7R08AKOVf3Y" 1787 } 1789 The server MUST verify that the request is signed by the account key. 1790 If the server accepts the deactivation request, it replies with a 200 1791 (OK) status code and the current contents of the account object. 1793 Once an account is deactivated, the server MUST NOT accept further 1794 requests authorized by that account's key. The server SHOULD cancel 1795 any pending operations authorized by the account's key, such as 1796 certificate orders. A server may take a variety of actions in 1797 response to an account deactivation, e.g., deleting data related to 1798 that account or sending mail to the account's contacts. Servers 1799 SHOULD NOT revoke certificates issued by the deactivated account, 1800 since this could cause operational disruption for servers using these 1801 certificates. ACME does not provide a way to reactivate a 1802 deactivated account. 1804 7.4. Applying for Certificate Issuance 1806 The client requests certificate issuance by sending a POST request to 1807 the server's new-order resource. The body of the POST is a JWS 1808 object whose JSON payload is a subset of the order object defined in 1809 Section 7.1.3, containing the fields that describe the certificate to 1810 be issued: 1812 identifiers (required, array of object): An array of identifier 1813 objects that the client wishes to submit an order for. 1815 type (required, string): The type of identifier. 1817 value (required, string): The identifier itself. 1819 notBefore (optional, string): The requested value of the notBefore 1820 field in the certificate, in the date format defined in [RFC3339]. 1822 notAfter (optional, string): The requested value of the notAfter 1823 field in the certificate, in the date format defined in [RFC3339]. 1825 POST /acme/new-order HTTP/1.1 1826 Host: example.com 1827 Content-Type: application/jose+json 1829 { 1830 "protected": base64url({ 1831 "alg": "ES256", 1832 "kid": "https://example.com/acme/acct/1", 1833 "nonce": "5XJ1L3lEkMG7tR6pA00clA", 1834 "url": "https://example.com/acme/new-order" 1835 }), 1836 "payload": base64url({ 1837 "identifiers": [ 1838 { "type": "dns", "value": "example.com" } 1839 ], 1840 "notBefore": "2016-01-01T00:00:00Z", 1841 "notAfter": "2016-01-08T00:00:00Z" 1842 }), 1843 "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g" 1844 } 1846 The server MUST return an error if it cannot fulfill the request as 1847 specified, and MUST NOT issue a certificate with contents other than 1848 those requested. If the server requires the request to be modified 1849 in a certain way, it should indicate the required changes using an 1850 appropriate error type and description. 1852 If the server is willing to issue the requested certificate, it 1853 responds with a 201 (Created) response. The body of this response is 1854 an order object reflecting the client's request and any 1855 authorizations the client must complete before the certificate will 1856 be issued. 1858 HTTP/1.1 201 Created 1859 Replay-Nonce: MYAuvOpaoIiywTezizk5vw 1860 Location: https://example.com/acme/order/asdf 1862 { 1863 "status": "pending", 1864 "expires": "2016-01-01T00:00:00Z", 1866 "notBefore": "2016-01-01T00:00:00Z", 1867 "notAfter": "2016-01-08T00:00:00Z", 1869 "identifiers": [ 1870 { "type": "dns", "value": "example.com" }, 1871 { "type": "dns", "value": "www.example.com" } 1872 ], 1874 "authorizations": [ 1875 "https://example.com/acme/authz/1234", 1876 "https://example.com/acme/authz/2345" 1877 ], 1879 "finalize": "https://example.com/acme/order/asdf/finalize" 1880 } 1882 The order object returned by the server represents a promise that if 1883 the client fulfills the server's requirements before the "expires" 1884 time, then the server will be willing to finalize the order upon 1885 request and issue the requested certificate. In the order object, 1886 any authorization referenced in the "authorizations" array whose 1887 status is "pending" represents an authorization transaction that the 1888 client must complete before the server will issue the certificate 1889 (see Section 7.5). If the client fails to complete the required 1890 actions before the "expires" time, then the server SHOULD change the 1891 status of the order to "invalid" and MAY delete the order resource. 1892 Clients SHOULD NOT make any assumptions about the sort order of 1893 "identifiers" or "authorizations" elements in the returned order 1894 object. 1896 Once the client believes it has fulfilled the server's requirements, 1897 it should send a POST request to the order resource's finalize URL. 1898 The POST body MUST include a CSR: 1900 csr (required, string): A CSR encoding the parameters for the 1901 certificate being requested [RFC2986]. The CSR is sent in the 1902 base64url-encoded version of the DER format. (Note: Because this 1903 field uses base64url, and does not include headers, it is 1904 different from PEM.). 1906 POST /acme/order/asdf/finalize HTTP/1.1 1907 Host: example.com 1908 Content-Type: application/jose+json 1910 { 1911 "protected": base64url({ 1912 "alg": "ES256", 1913 "kid": "https://example.com/acme/acct/1", 1914 "nonce": "MSF2j2nawWHPxxkE3ZJtKQ", 1915 "url": "https://example.com/acme/order/asdf/finalize" 1916 }), 1917 "payload": base64url({ 1918 "csr": "MIIBPTCBxAIBADBFMQ...FS6aKdZeGsysoCo4H9P", 1919 }), 1920 "signature": "uOrUfIIk5RyQ...nw62Ay1cl6AB" 1921 } 1923 The CSR encodes the client's requests with regard to the content of 1924 the certificate to be issued. The CSR MUST indicate the exact same 1925 set of requested identifiers as the initial new-order request, either 1926 in the commonName portion of the requested subject name, or in an 1927 extensionRequest attribute [RFC2985] requesting a subjectAltName 1928 extension. 1930 A request to finalize an order will result in error if the order 1931 indicated does not have status "ready", if the CSR and order 1932 identifiers differ, or if the account is not authorized for the 1933 identifiers indicated in the CSR. 1935 A valid request to finalize an order will return the order to be 1936 finalized. The client should begin polling the order by sending a 1937 GET request to the order resource to obtain its current state. The 1938 status of the order will indicate what action the client should take: 1940 o "invalid": The certificate will not be issued. Consider this 1941 order process abandoned. 1943 o "pending": The server does not believe that the client has 1944 fulfilled the requirements. Check the "authorizations" array for 1945 entries that are still pending. 1947 o "ready": The server agrees that the requirements have been 1948 fulfilled, and is awaiting finalization. Submit a finalization 1949 request. 1951 o "processing": The certificate is being issued. Send a GET request 1952 after the time given in the "Retry-After" header field of the 1953 response, if any. 1955 o "valid": The server has issued the certificate and provisioned its 1956 URL to the "certificate" field of the order. Download the 1957 certificate. 1959 HTTP/1.1 200 OK 1960 Replay-Nonce: CGf81JWBsq8QyIgPCi9Q9X 1961 Location: https://example.com/acme/order/asdf 1963 { 1964 "status": "valid", 1965 "expires": "2016-01-01T00:00:00Z", 1967 "notBefore": "2016-01-01T00:00:00Z", 1968 "notAfter": "2016-01-08T00:00:00Z", 1970 "identifiers": [ 1971 { "type": "dns", "value": "example.com" }, 1972 { "type": "dns", "value": "www.example.com" } 1973 ], 1975 "authorizations": [ 1976 "https://example.com/acme/authz/1234", 1977 "https://example.com/acme/authz/2345" 1978 ], 1980 "finalize": "https://example.com/acme/order/asdf/finalize", 1982 "certificate": "https://example.com/acme/cert/asdf" 1983 } 1985 7.4.1. Pre-Authorization 1987 The order process described above presumes that authorization objects 1988 are created reactively, in response to a certificate order. Some 1989 servers may also wish to enable clients to obtain authorization for 1990 an identifier proactively, outside of the context of a specific 1991 issuance. For example, a client hosting virtual servers for a 1992 collection of names might wish to obtain authorization before any 1993 virtual servers are created and only create a certificate when a 1994 virtual server starts up. 1996 In some cases, a CA running an ACME server might have a completely 1997 external, non-ACME process for authorizing a client to issue 1998 certificates for an identifier. In these cases, the CA should 1999 provision its ACME server with authorization objects corresponding to 2000 these authorizations and reflect them as already valid in any orders 2001 submitted by the client. 2003 If a CA wishes to allow pre-authorization within ACME, it can offer a 2004 "new authorization" resource in its directory by adding the field 2005 "newAuthz" with a URL for the new authorization resource. 2007 To request authorization for an identifier, the client sends a POST 2008 request to the new-authorization resource specifying the identifier 2009 for which authorization is being requested. 2011 identifier (required, object): The identifier to appear in the 2012 resulting authorization object (see Section 7.1.4) 2014 POST /acme/new-authz HTTP/1.1 2015 Host: example.com 2016 Content-Type: application/jose+json 2018 { 2019 "protected": base64url({ 2020 "alg": "ES256", 2021 "kid": "https://example.com/acme/acct/1", 2022 "nonce": "uQpSjlRb4vQVCjVYAyyUWg", 2023 "url": "https://example.com/acme/new-authz" 2024 }), 2025 "payload": base64url({ 2026 "identifier": { 2027 "type": "dns", 2028 "value": "example.net" 2029 } 2030 }), 2031 "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" 2032 } 2034 Note that because the identifier in a pre-authorization request is 2035 the exact identifier to be included in the authorization object, pre- 2036 authorization cannot be used to authorize issuance with wildcard DNS 2037 identifiers. 2039 Before processing the authorization request, the server SHOULD 2040 determine whether it is willing to issue certificates for the 2041 identifier. For example, the server should check that the identifier 2042 is of a supported type. Servers might also check names against a 2043 blacklist of known high-value identifiers. If the server is 2044 unwilling to issue for the identifier, it SHOULD return a 403 2045 (Forbidden) error, with a problem document describing the reason for 2046 the rejection. 2048 If the server is willing to proceed, it builds a pending 2049 authorization object from the inputs submitted by the client: 2051 o "identifier" the identifier submitted by the client 2053 o "status" MUST be "pending" unless the server has out-of-band 2054 information about the client's authorization status 2056 o "challenges" as selected by the server's policy for this 2057 identifier 2059 The server allocates a new URL for this authorization, and returns a 2060 201 (Created) response, with the authorization URL in the Location 2061 header field, and the JSON authorization object in the body. The 2062 client then follows the process described in Section 7.5 to complete 2063 the authorization process. 2065 7.4.2. Downloading the Certificate 2067 To download the issued certificate, the client simply sends a GET 2068 request to the certificate URL. 2070 The default format of the certificate is application/pem-certificate- 2071 chain (see IANA Considerations). 2073 The server MAY provide one or more link relation header fields 2074 [RFC5988] with relation "alternate". Each such field SHOULD express 2075 an alternative certificate chain starting with the same end-entity 2076 certificate. This can be used to express paths to various trust 2077 anchors. Clients can fetch these alternates and use their own 2078 heuristics to decide which is optimal. 2080 GET /acme/cert/asdf HTTP/1.1 2081 Host: example.com 2082 Accept: application/pkix-cert 2084 HTTP/1.1 200 OK 2085 Content-Type: application/pem-certificate-chain 2086 Link: ;rel="index" 2088 -----BEGIN CERTIFICATE----- 2089 [End-entity certificate contents] 2090 -----END CERTIFICATE----- 2091 -----BEGIN CERTIFICATE----- 2092 [Issuer certificate contents] 2093 -----END CERTIFICATE----- 2094 -----BEGIN CERTIFICATE----- 2095 [Other certificate contents] 2096 -----END CERTIFICATE----- 2097 A certificate resource represents a single, immutable certificate. 2098 If the client wishes to obtain a renewed certificate, the client 2099 initiates a new order process to request one. 2101 Because certificate resources are immutable once issuance is 2102 complete, the server MAY enable the caching of the resource by adding 2103 Expires and Cache-Control headers specifying a point in time in the 2104 distant future. These headers have no relation to the certificate's 2105 period of validity. 2107 The ACME client MAY request other formats by including an Accept 2108 header in its request. For example, the client could use the media 2109 type "application/pkix-cert" [RFC2585] to request the end-entity 2110 certificate in DER format. Server support for alternate formats is 2111 OPTIONAL. For formats that can only express a single certificate, 2112 the server SHOULD provide one or more "Link: rel="up"" headers 2113 pointing to an issuer or issuers so that ACME clients can build a 2114 certificate chain as defined in TLS. 2116 7.5. Identifier Authorization 2118 The identifier authorization process establishes the authorization of 2119 an account to manage certificates for a given identifier. This 2120 process assures the server of two things: 2122 1. That the client controls the private key of the account key pair, 2123 and 2125 2. That the client controls the identifier in question. 2127 This process may be repeated to associate multiple identifiers to a 2128 key pair (e.g., to request certificates with multiple identifiers), 2129 or to associate multiple accounts with an identifier (e.g., to allow 2130 multiple entities to manage certificates). 2132 Authorization resources are created by the server in response to 2133 certificate orders or authorization requests submitted by an account 2134 key holder; their URLs are provided to the client in the responses to 2135 these requests. The authorization object is implicitly tied to the 2136 account key used to sign the request. 2138 When a client receives an order from the server it downloads the 2139 authorization resources by sending GET requests to the indicated 2140 URLs. If the client initiates authorization using a request to the 2141 new authorization resource, it will have already received the pending 2142 authorization object in the response to that request. 2144 GET /acme/authz/1234 HTTP/1.1 2145 Host: example.com 2147 HTTP/1.1 200 OK 2148 Content-Type: application/json 2149 Link: ;rel="index" 2151 { 2152 "status": "pending", 2153 "expires": "2018-03-03T14:09:00Z", 2155 "identifier": { 2156 "type": "dns", 2157 "value": "example.org" 2158 }, 2160 "challenges": [ 2161 { 2162 "type": "http-01", 2163 "url": "https://example.com/acme/authz/1234/0", 2164 "token": "DGyRejmCefe7v4NfDGDKfA" 2165 }, 2166 { 2167 "type": "dns-01", 2168 "url": "https://example.com/acme/authz/1234/2", 2169 "token": "DGyRejmCefe7v4NfDGDKfA" 2170 } 2171 ], 2173 "wildcard": false 2174 } 2176 7.5.1. Responding to Challenges 2178 To prove control of the identifier and receive authorization, the 2179 client needs to respond with information to complete the challenges. 2180 To do this, the client updates the authorization object received from 2181 the server by filling in any required information in the elements of 2182 the "challenges" dictionary. 2184 The client sends these updates back to the server in the form of a 2185 JSON object with contents as specified by the challenge type, carried 2186 in a POST request to the challenge URL (not authorization URL) once 2187 it is ready for the server to attempt validation. 2189 For example, if the client were to respond to the "http-01" challenge 2190 in the above authorization, it would send the following request: 2192 POST /acme/authz/1234/0 HTTP/1.1 2193 Host: example.com 2194 Content-Type: application/jose+json 2196 { 2197 "protected": base64url({ 2198 "alg": "ES256", 2199 "kid": "https://example.com/acme/acct/1", 2200 "nonce": "Q_s3MWoqT05TrdkM2MTDcw", 2201 "url": "https://example.com/acme/authz/1234/0" 2202 }), 2203 "payload": base64url({}), 2204 "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ" 2205 } 2207 The server updates the authorization document by updating its 2208 representation of the challenge with the response object provided by 2209 the client. The server MUST ignore any fields in the response object 2210 that are not specified as response fields for this type of challenge. 2211 The server provides a 200 (OK) response with the updated challenge 2212 object as its body. 2214 If the client's response is invalid for any reason or does not 2215 provide the server with appropriate information to validate the 2216 challenge, then the server MUST return an HTTP error. On receiving 2217 such an error, the client SHOULD undo any actions that have been 2218 taken to fulfill the challenge, e.g., removing files that have been 2219 provisioned to a web server. 2221 The server is said to "finalize" the authorization when it has 2222 completed one of the validations, by assigning the authorization a 2223 status of "valid" or "invalid", corresponding to whether it considers 2224 the account authorized for the identifier. If the final state is 2225 "valid", then the server MUST include an "expires" field. When 2226 finalizing an authorization, the server MAY remove challenges other 2227 than the one that was completed, and may modify the "expires" field. 2228 The server SHOULD NOT remove challenges with status "invalid". 2230 Usually, the validation process will take some time, so the client 2231 will need to poll the authorization resource to see when it is 2232 finalized. For challenges where the client can tell when the server 2233 has validated the challenge (e.g., by seeing an HTTP or DNS request 2234 from the server), the client SHOULD NOT begin polling until it has 2235 seen the validation request from the server. 2237 To check on the status of an authorization, the client sends a GET 2238 request to the authorization URL, and the server responds with the 2239 current authorization object. In responding to poll requests while 2240 the validation is still in progress, the server MUST return a 200 2241 (OK) response and MAY include a Retry-After header field to suggest a 2242 polling interval to the client. 2244 GET /acme/authz/1234 HTTP/1.1 2245 Host: example.com 2247 HTTP/1.1 200 OK 2248 Content-Type: application/json 2250 { 2251 "status": "valid", 2252 "expires": "2018-09-09T14:09:00Z", 2254 "identifier": { 2255 "type": "dns", 2256 "value": "example.org" 2257 }, 2259 "challenges": [ 2260 { 2261 "type": "http-01", 2262 "url": "https://example.com/acme/authz/1234/0", 2263 "status": "valid", 2264 "validated": "2014-12-01T12:05:00Z", 2265 "token": "IlirfxKKXAsHtmzK29Pj8A" 2266 } 2267 ], 2269 "wildcard": false 2270 } 2272 7.5.2. Deactivating an Authorization 2274 If a client wishes to relinquish its authorization to issue 2275 certificates for an identifier, then it may request that the server 2276 deactivates each authorization associated with it by sending POST 2277 requests with the static object {"status": "deactivated"} to each 2278 authorization URL. 2280 POST /acme/authz/1234 HTTP/1.1 2281 Host: example.com 2282 Content-Type: application/jose+json 2284 { 2285 "protected": base64url({ 2286 "alg": "ES256", 2287 "kid": "https://example.com/acme/acct/1", 2288 "nonce": "xWCM9lGbIyCgue8di6ueWQ", 2289 "url": "https://example.com/acme/authz/1234" 2290 }), 2291 "payload": base64url({ 2292 "status": "deactivated" 2293 }), 2294 "signature": "srX9Ji7Le9bjszhu...WTFdtujObzMtZcx4" 2295 } 2297 The server MUST verify that the request is signed by the account key 2298 corresponding to the account that owns the authorization. If the 2299 server accepts the deactivation, it should reply with a 200 (OK) 2300 status code and the updated contents of the authorization object. 2302 The server MUST NOT treat deactivated authorization objects as 2303 sufficient for issuing certificates. 2305 7.6. Certificate Revocation 2307 To request that a certificate be revoked, the client sends a POST 2308 request to the ACME server's revokeCert URL. The body of the POST is 2309 a JWS object whose JSON payload contains the certificate to be 2310 revoked: 2312 certificate (required, string): The certificate to be revoked, in 2313 the base64url-encoded version of the DER format. (Note: Because 2314 this field uses base64url, and does not include headers, it is 2315 different from PEM.) 2317 reason (optional, int): One of the revocation reasonCodes defined in 2318 Section 5.3.1 of [RFC5280] to be used when generating OCSP 2319 responses and CRLs. If this field is not set the server SHOULD 2320 omit the reasonCode CRL entry extension when generating OCSP 2321 responses and CRLs. The server MAY disallow a subset of 2322 reasonCodes from being used by the user. If a request contains a 2323 disallowed reasonCode the server MUST reject it with the error 2324 type "urn:ietf:params:acme:error:badRevocationReason". The 2325 problem document detail SHOULD indicate which reasonCodes are 2326 allowed. 2328 Revocation requests are different from other ACME requests in that 2329 they can be signed either with an account key pair or the key pair in 2330 the certificate. 2332 Example using an account key pair for the signature: 2334 POST /acme/revoke-cert HTTP/1.1 2335 Host: example.com 2336 Content-Type: application/jose+json 2338 { 2339 "protected": base64url({ 2340 "alg": "ES256", 2341 "kid": "https://example.com/acme/acct/1", 2342 "nonce": "JHb54aT_KTXBWQOzGYkt9A", 2343 "url": "https://example.com/acme/revoke-cert" 2344 }), 2345 "payload": base64url({ 2346 "certificate": "MIIEDTCCAvegAwIBAgIRAP8...", 2347 "reason": 4 2348 }), 2349 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2350 } 2352 Example using the certificate key pair for the signature: 2354 POST /acme/revoke-cert HTTP/1.1 2355 Host: example.com 2356 Content-Type: application/jose+json 2358 { 2359 "protected": base64url({ 2360 "alg": "RS256", 2361 "jwk": /* certificate's public key */, 2362 "nonce": "JHb54aT_KTXBWQOzGYkt9A", 2363 "url": "https://example.com/acme/revoke-cert" 2364 }), 2365 "payload": base64url({ 2366 "certificate": "MIIEDTCCAvegAwIBAgIRAP8...", 2367 "reason": 1 2368 }), 2369 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2370 } 2372 Before revoking a certificate, the server MUST verify that the key 2373 used to sign the request is authorized to revoke the certificate. 2374 The server MUST consider at least the following accounts authorized 2375 for a given certificate: 2377 o the account that issued the certificate. 2379 o an account that holds authorizations for all of the identifiers in 2380 the certificate. 2382 The server MUST also consider a revocation request valid if it is 2383 signed with the private key corresponding to the public key in the 2384 certificate. 2386 If the revocation succeeds, the server responds with status code 200 2387 (OK). If the revocation fails, the server returns an error. 2389 HTTP/1.1 200 OK 2390 Replay-Nonce: IXVHDyxIRGcTE0VSblhPzw 2391 Content-Length: 0 2393 --- or --- 2395 HTTP/1.1 403 Forbidden 2396 Replay-Nonce: IXVHDyxIRGcTE0VSblhPzw 2397 Content-Type: application/problem+json 2398 Content-Language: en 2400 { 2401 "type": "urn:ietf:params:acme:error:unauthorized", 2402 "detail": "No authorization provided for name example.net" 2403 } 2405 8. Identifier Validation Challenges 2407 There are few types of identifiers in the world for which there is a 2408 standardized mechanism to prove possession of a given identifier. In 2409 all practical cases, CAs rely on a variety of means to test whether 2410 an entity applying for a certificate with a given identifier actually 2411 controls that identifier. 2413 Challenges provide the server with assurance that an account holder 2414 is also the entity that controls an identifier. For each type of 2415 challenge, it must be the case that in order for an entity to 2416 successfully complete the challenge the entity must both: 2418 o Hold the private key of the account key pair used to respond to 2419 the challenge 2421 o Control the identifier in question 2422 Section 10 documents how the challenges defined in this document meet 2423 these requirements. New challenges will need to document how they 2424 do. 2426 ACME uses an extensible challenge/response framework for identifier 2427 validation. The server presents a set of challenges in the 2428 authorization object it sends to a client (as objects in the 2429 "challenges" array), and the client responds by sending a response 2430 object in a POST request to a challenge URL. 2432 This section describes an initial set of challenge types. The 2433 definition of a challenge type includes: 2435 1. Content of challenge objects 2437 2. Content of response objects 2439 3. How the server uses the challenge and response to verify control 2440 of an identifier 2442 Challenge objects all contain the following basic fields: 2444 type (required, string): The type of challenge encoded in the 2445 object. 2447 url (required, string): The URL to which a response can be posted. 2449 status (required, string): The status of this challenge. Possible 2450 values are: "pending", "processing", "valid", and "invalid". 2452 validated (optional, string): The time at which the server validated 2453 this challenge, encoded in the format specified in RFC 3339 2454 [RFC3339]. This field is REQUIRED if the "status" field is 2455 "valid". 2457 error (optional, object): Error that occurred while the server was 2458 validating the challenge, if any, structured as a problem document 2459 [RFC7807]. Multiple errors can be indicated by using subproblems 2460 Section 6.6.1. 2462 All additional fields are specified by the challenge type. If the 2463 server sets a challenge's "status" to "invalid", it SHOULD also 2464 include the "error" field to help the client diagnose why the 2465 challenge failed. 2467 Different challenges allow the server to obtain proof of different 2468 aspects of control over an identifier. In some challenges, like HTTP 2469 and DNS, the client directly proves its ability to do certain things 2470 related to the identifier. The choice of which challenges to offer 2471 to a client under which circumstances is a matter of server policy. 2473 The identifier validation challenges described in this section all 2474 relate to validation of domain names. If ACME is extended in the 2475 future to support other types of identifiers, there will need to be 2476 new challenge types, and they will need to specify which types of 2477 identifier they apply to. 2479 8.1. Key Authorizations 2481 All challenges defined in this document make use of a key 2482 authorization string. A key authorization is a string that expresses 2483 a domain holder's authorization for a specified key to satisfy a 2484 specified challenge, by concatenating the token for the challenge 2485 with a key fingerprint, separated by a "." character: 2487 keyAuthorization = token || '.' || base64url(JWK_Thumbprint(accountKey)) 2489 The "JWK_Thumbprint" step indicates the computation specified in 2490 [RFC7638], using the SHA-256 digest [FIPS180-4]. As noted in 2491 [RFC7518] any prepended zero octets in the fields of a JWK object 2492 MUST be stripped before doing the computation. 2494 As specified in the individual challenges below, the token for a 2495 challenge is a string comprised entirely of characters in the URL- 2496 safe base64 alphabet. The "||" operator indicates concatenation of 2497 strings. 2499 8.2. Retrying Challenges 2501 ACME challenges typically require the client to set up some network- 2502 accessible resource that the server can query in order to validate 2503 that the client controls an identifier. In practice it is not 2504 uncommon for the server's queries to fail while a resource is being 2505 set up, e.g., due to information propagating across a cluster or 2506 firewall rules not being in place. 2508 Clients SHOULD NOT respond to challenges until they believe that the 2509 server's queries will succeed. If a server's initial validation 2510 query fails, the server SHOULD retry the query after some time, in 2511 order to account for delay in setting up responses such as DNS 2512 records or HTTP resources. The precise retry schedule is up to the 2513 server, but server operators should keep in mind the operational 2514 scenarios that the schedule is trying to accommodate. Given that 2515 retries are intended to address things like propagation delays in 2516 HTTP or DNS provisioning, there should not usually be any reason to 2517 retry more often than every 5 or 10 seconds. While the server is 2518 still trying, the status of the challenge remains "processing"; it is 2519 only marked "invalid" once the server has given up. 2521 The server MUST provide information about its retry state to the 2522 client via the "error" field in the challenge and the Retry-After 2523 HTTP header field in response to requests to the challenge resource. 2524 The server MUST add an entry to the "error" field in the challenge 2525 after each failed validation query. The server SHOULD set the Retry- 2526 After header field to a time after the server's next validation 2527 query, since the status of the challenge will not change until that 2528 time. 2530 Clients can explicitly request a retry by re-sending their response 2531 to a challenge in a new POST request (with a new nonce, etc.). This 2532 allows clients to request a retry when the state has changed (e.g., 2533 after firewall rules have been updated). Servers SHOULD retry a 2534 request immediately on receiving such a POST request. In order to 2535 avoid denial-of-service attacks via client-initiated retries, servers 2536 SHOULD rate-limit such requests. 2538 8.3. HTTP Challenge 2540 With HTTP validation, the client in an ACME transaction proves its 2541 control over a domain name by proving that it can provision HTTP 2542 resources on a server accessible under that domain name. The ACME 2543 server challenges the client to provision a file at a specific path, 2544 with a specific string as its content. 2546 As a domain may resolve to multiple IPv4 and IPv6 addresses, the 2547 server will connect to at least one of the hosts found in the DNS A 2548 and AAAA records, at its discretion. Because many web servers 2549 allocate a default HTTPS virtual host to a particular low-privilege 2550 tenant user in a subtle and non-intuitive manner, the challenge must 2551 be completed over HTTP, not HTTPS. 2553 type (required, string): The string "http-01" 2555 token (required, string): A random value that uniquely identifies 2556 the challenge. This value MUST have at least 128 bits of entropy. 2557 It MUST NOT contain any characters outside the base64url alphabet, 2558 and MUST NOT include base64 padding characters ("="). 2560 GET /acme/authz/1234/0 HTTP/1.1 2561 Host: example.com 2563 HTTP/1.1 200 OK 2564 Content-Type: application/json 2566 { 2567 "type": "http-01", 2568 "url": "https://example.com/acme/authz/0", 2569 "status": "pending", 2570 "token": "LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0" 2571 } 2573 A client fulfills this challenge by constructing a key authorization 2574 from the "token" value provided in the challenge and the client's 2575 account key. The client then provisions the key authorization as a 2576 resource on the HTTP server for the domain in question. 2578 The path at which the resource is provisioned is comprised of the 2579 fixed prefix "/.well-known/acme-challenge/", followed by the "token" 2580 value in the challenge. The value of the resource MUST be the ASCII 2581 representation of the key authorization. 2583 GET /.well-known/acme-challenge/LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0 2584 Host: example.org 2586 HTTP/1.1 200 OK 2587 Content-Type: application/octet-stream 2589 LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0.9jg46WB3rR_AHD-EBXdN7cBkH1WOu0tA3M9fm21mqTI 2591 A client responds with an empty object ({}) to acknowledge that the 2592 challenge can be validated by the server. 2594 POST /acme/authz/1234/0 2595 Host: example.com 2596 Content-Type: application/jose+json 2598 { 2599 "protected": base64url({ 2600 "alg": "ES256", 2601 "kid": "https://example.com/acme/acct/1", 2602 "nonce": "JHb54aT_KTXBWQOzGYkt9A", 2603 "url": "https://example.com/acme/authz/1234/0" 2604 }), 2605 "payload": base64url({}), 2606 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2607 } 2608 On receiving a response, the server constructs and stores the key 2609 authorization from the challenge "token" value and the current client 2610 account key. 2612 Given a challenge/response pair, the server verifies the client's 2613 control of the domain by verifying that the resource was provisioned 2614 as expected. 2616 1. Construct a URL by populating the URL template [RFC6570] 2617 "http://{domain}/.well-known/acme-challenge/{token}", where: 2619 * the domain field is set to the domain name being verified; and 2621 * the token field is set to the token in the challenge. 2623 2. Verify that the resulting URL is well-formed. 2625 3. Dereference the URL using an HTTP GET request. This request MUST 2626 be sent to TCP port 80 on the HTTP server. 2628 4. Verify that the body of the response is well-formed key 2629 authorization. The server SHOULD ignore whitespace characters at 2630 the end of the body. 2632 5. Verify that key authorization provided by the HTTP server matches 2633 the key authorization stored by the server. 2635 The server SHOULD follow redirects when dereferencing the URL. 2637 If all of the above verifications succeed, then the validation is 2638 successful. If the request fails, or the body does not pass these 2639 checks, then it has failed. 2641 8.4. DNS Challenge 2643 When the identifier being validated is a domain name, the client can 2644 prove control of that domain by provisioning a TXT resource record 2645 containing a designated value for a specific validation domain name. 2647 type (required, string): The string "dns-01" 2649 token (required, string): A random value that uniquely identifies 2650 the challenge. This value MUST have at least 128 bits of entropy. 2651 It MUST NOT contain any characters outside the base64url alphabet, 2652 including padding characters ("="). 2654 GET /acme/authz/1234/2 HTTP/1.1 2655 Host: example.com 2657 HTTP/1.1 200 OK 2658 Content-Type: application/json 2660 { 2661 "type": "dns-01", 2662 "url": "https://example.com/acme/authz/1234/2", 2663 "status": "pending", 2664 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA" 2665 } 2667 A client fulfills this challenge by constructing a key authorization 2668 from the "token" value provided in the challenge and the client's 2669 account key. The client then computes the SHA-256 digest [FIPS180-4] 2670 of the key authorization. 2672 The record provisioned to the DNS contains the base64url encoding of 2673 this digest. The client constructs the validation domain name by 2674 prepending the label "_acme-challenge" to the domain name being 2675 validated, then provisions a TXT record with the digest value under 2676 that name. For example, if the domain name being validated is 2677 "example.org", then the client would provision the following DNS 2678 record: 2680 _acme-challenge.example.org. 300 IN TXT "gfj9Xq...Rg85nM" 2682 A client responds with an empty object ({}) to acknowledge that the 2683 challenge can be validated by the server. 2685 POST /acme/authz/1234/2 2686 Host: example.com 2687 Content-Type: application/jose+json 2689 { 2690 "protected": base64url({ 2691 "alg": "ES256", 2692 "kid": "https://example.com/acme/acct/1", 2693 "nonce": "JHb54aT_KTXBWQOzGYkt9A", 2694 "url": "https://example.com/acme/authz/1234/2" 2695 }), 2696 "payload": base64url({}), 2697 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2698 } 2699 On receiving a response, the server constructs and stores the key 2700 authorization from the challenge "token" value and the current client 2701 account key. 2703 To validate a DNS challenge, the server performs the following steps: 2705 1. Compute the SHA-256 digest [FIPS180-4] of the stored key 2706 authorization 2708 2. Query for TXT records for the validation domain name 2710 3. Verify that the contents of one of the TXT records match the 2711 digest value 2713 If all of the above verifications succeed, then the validation is 2714 successful. If no DNS record is found, or DNS record and response 2715 payload do not pass these checks, then the validation fails. 2717 9. IANA Considerations 2719 9.1. MIME Type: application/pem-certificate-chain 2721 The "Media Types" registry should be updated with the following 2722 additional value: 2724 MIME media type name: application 2726 MIME subtype name: pem-certificate-chain 2728 Required parameters: None 2730 Optional parameters: None 2732 Encoding considerations: None 2734 Security considerations: Carries a cryptographic certificate and its 2735 associated certificate chain 2737 Interoperability considerations: None 2739 Published specification: draft-ietf-acme-acme [[ RFC EDITOR: Please 2740 replace draft-ietf-acme-acme above with the RFC number assigned to 2741 this ]] 2743 Applications which use this media type: Any MIME-compliant transport 2745 Additional information: 2747 File contains one or more certificates encoded with the PEM textual 2748 encoding, according to RFC 7468 [RFC7468]. In order to provide easy 2749 interoperation with TLS, the first certificate MUST be an end-entity 2750 certificate. Each following certificate SHOULD directly certify the 2751 one preceding it. Because certificate validation requires that trust 2752 anchors be distributed independently, a certificate that specifies a 2753 trust anchor MAY be omitted from the chain, provided that supported 2754 peers are known to possess any omitted certificates. 2756 9.2. Well-Known URI for the HTTP Challenge 2758 The "Well-Known URIs" registry should be updated with the following 2759 additional value (using the template from [RFC5785]): 2761 URI suffix: acme-challenge 2763 Change controller: IETF 2765 Specification document(s): This document, Section Section 8.3 2767 Related information: N/A 2769 9.3. Replay-Nonce HTTP Header 2771 The "Message Headers" registry should be updated with the following 2772 additional value: 2774 +-------------------+----------+----------+---------------+ 2775 | Header Field Name | Protocol | Status | Reference | 2776 +-------------------+----------+----------+---------------+ 2777 | Replay-Nonce | http | standard | Section 6.4.1 | 2778 +-------------------+----------+----------+---------------+ 2780 9.4. "url" JWS Header Parameter 2782 The "JSON Web Signature and Encryption Header Parameters" registry 2783 should be updated with the following additional value: 2785 o Header Parameter Name: "url" 2787 o Header Parameter Description: URL 2789 o Header Parameter Usage Location(s): JWE, JWS 2791 o Change Controller: IESG 2793 o Specification Document(s): Section 6.3.1 of RFC XXXX 2795 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2796 to this document ]] 2798 9.5. "nonce" JWS Header Parameter 2800 The "JSON Web Signature and Encryption Header Parameters" registry 2801 should be updated with the following additional value: 2803 o Header Parameter Name: "nonce" 2805 o Header Parameter Description: Nonce 2807 o Header Parameter Usage Location(s): JWE, JWS 2809 o Change Controller: IESG 2811 o Specification Document(s): Section 6.4.2 of RFC XXXX 2813 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2814 to this document ]] 2816 9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) 2818 The "IETF URN Sub-namespace for Registered Protocol Parameter 2819 Identifiers" registry should be updated with the following additional 2820 value, following the template in [RFC3553]: 2822 Registry name: acme 2824 Specification: RFC XXXX 2826 Repository: URL-TBD 2828 Index value: No transformation needed. 2830 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2831 to this document, and replace URL-TBD with the URL assigned by IANA 2832 for registries of ACME parameters. ]] 2834 9.7. New Registries 2836 This document requests that IANA create the following new registries: 2838 1. ACME Account Object Fields (Section 9.7.1) 2840 2. ACME Order Object Fields (Section 9.7.2) 2842 3. ACME Authorization Object Fields (Section 9.7.3) 2843 4. ACME Error Types (Section 9.7.4) 2845 5. ACME Resource Types (Section 9.7.5) 2847 6. ACME Directory Metadata Fields (Section 9.7.6) 2849 7. ACME Identifier Types (Section 9.7.7) 2851 8. ACME Validation Methods (Section 9.7.8) 2853 All of these registries are under a heading of "Automated Certificate 2854 Management Environment (ACME) Protocol" and are administered under a 2855 Specification Required policy [RFC8126]. 2857 9.7.1. Fields in Account Objects 2859 This registry lists field names that are defined for use in ACME 2860 account objects. Fields marked as "configurable" may be included in 2861 a new-account request. 2863 Template: 2865 o Field name: The string to be used as a field name in the JSON 2866 object 2868 o Field type: The type of value to be provided, e.g., string, 2869 boolean, array of string 2871 o Client configurable: Boolean indicating whether the server should 2872 accept values provided by the client 2874 o Reference: Where this field is defined 2876 Initial contents: The fields and descriptions defined in 2877 Section 7.1.2. 2879 +------------------------+---------------+--------------+-----------+ 2880 | Field Name | Field Type | Configurable | Reference | 2881 +------------------------+---------------+--------------+-----------+ 2882 | status | string | false | RFC XXXX | 2883 | | | | | 2884 | contact | array of | true | RFC XXXX | 2885 | | string | | | 2886 | | | | | 2887 | externalAccountBinding | object | true | RFC XXXX | 2888 | | | | | 2889 | termsOfServiceAgreed | boolean | true | RFC XXXX | 2890 | | | | | 2891 | orders | string | false | RFC XXXX | 2892 +------------------------+---------------+--------------+-----------+ 2894 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2895 to this document ]] 2897 9.7.2. Fields in Order Objects 2899 This registry lists field names that are defined for use in ACME 2900 order objects. Fields marked as "configurable" may be included in a 2901 new-order request. 2903 Template: 2905 o Field name: The string to be used as a field name in the JSON 2906 object 2908 o Field type: The type of value to be provided, e.g., string, 2909 boolean, array of string 2911 o Client configurable: Boolean indicating whether the server should 2912 accept values provided by the client 2914 o Reference: Where this field is defined 2916 Initial contents: The fields and descriptions defined in 2917 Section 7.1.3. 2919 +----------------+-----------------+--------------+-----------+ 2920 | Field Name | Field Type | Configurable | Reference | 2921 +----------------+-----------------+--------------+-----------+ 2922 | status | string | false | RFC XXXX | 2923 | | | | | 2924 | expires | string | false | RFC XXXX | 2925 | | | | | 2926 | identifiers | array of object | true | RFC XXXX | 2927 | | | | | 2928 | notBefore | string | true | RFC XXXX | 2929 | | | | | 2930 | notAfter | string | true | RFC XXXX | 2931 | | | | | 2932 | authorizations | array of string | false | RFC XXXX | 2933 | | | | | 2934 | finalize | string | false | RFC XXXX | 2935 | | | | | 2936 | certificate | string | false | RFC XXXX | 2937 +----------------+-----------------+--------------+-----------+ 2939 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2940 to this document ]] 2942 9.7.3. Fields in Authorization Objects 2944 This registry lists field names that are defined for use in ACME 2945 authorization objects. Fields marked as "configurable" may be 2946 included in a new-authorization request. 2948 Template: 2950 o Field name: The string to be used as a field name in the JSON 2951 object 2953 o Field type: The type of value to be provided, e.g., string, 2954 boolean, array of string 2956 o Client configurable: Boolean indicating whether the server should 2957 accept values provided by the client 2959 o Reference: Where this field is defined 2961 Initial contents: The fields and descriptions defined in 2962 Section 7.1.4. 2964 +------------+-----------------+--------------+-----------+ 2965 | Field Name | Field Type | Configurable | Reference | 2966 +------------+-----------------+--------------+-----------+ 2967 | identifier | object | true | RFC XXXX | 2968 | | | | | 2969 | status | string | false | RFC XXXX | 2970 | | | | | 2971 | expires | string | false | RFC XXXX | 2972 | | | | | 2973 | challenges | array of object | false | RFC XXXX | 2974 | | | | | 2975 | wildcard | boolean | false | RFC XXXX | 2976 +------------+-----------------+--------------+-----------+ 2978 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2979 to this document ]] 2981 9.7.4. Error Types 2983 This registry lists values that are used within URN values that are 2984 provided in the "type" field of problem documents in ACME. 2986 Template: 2988 o Type: The label to be included in the URN for this error, 2989 following "urn:ietf:params:acme:error:" 2991 o Description: A human-readable description of the error 2993 o Reference: Where the error is defined 2995 Initial contents: The types and descriptions in the table in 2996 Section 6.6 above, with the Reference field set to point to this 2997 specification. 2999 9.7.5. Resource Types 3001 This registry lists the types of resources that ACME servers may list 3002 in their directory objects. 3004 Template: 3006 o Field name: The value to be used as a field name in the directory 3007 object 3009 o Resource type: The type of resource labeled by the field 3011 o Reference: Where the resource type is defined 3012 Initial contents: 3014 +------------+--------------------+-----------+ 3015 | Field Name | Resource Type | Reference | 3016 +------------+--------------------+-----------+ 3017 | newNonce | New nonce | RFC XXXX | 3018 | | | | 3019 | newAccount | New account | RFC XXXX | 3020 | | | | 3021 | newOrder | New order | RFC XXXX | 3022 | | | | 3023 | newAuthz | New authorization | RFC XXXX | 3024 | | | | 3025 | revokeCert | Revoke certificate | RFC XXXX | 3026 | | | | 3027 | keyChange | Key change | RFC XXXX | 3028 | | | | 3029 | meta | Metadata object | RFC XXXX | 3030 +------------+--------------------+-----------+ 3032 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 3033 to this document ]] 3035 9.7.6. Fields in the "meta" Object within a Directory Object 3037 This registry lists field names that are defined for use in the JSON 3038 object included in the "meta" field of an ACME directory object. 3040 Template: 3042 o Field name: The string to be used as a field name in the JSON 3043 object 3045 o Field type: The type of value to be provided, e.g., string, 3046 boolean, array of string 3048 o Reference: Where this field is defined 3050 Initial contents: The fields and descriptions defined in 3051 Section 7.1.2. 3053 +-------------------------+-----------------+-----------+ 3054 | Field Name | Field Type | Reference | 3055 +-------------------------+-----------------+-----------+ 3056 | termsOfService | string | RFC XXXX | 3057 | | | | 3058 | website | string | RFC XXXX | 3059 | | | | 3060 | caaIdentities | array of string | RFC XXXX | 3061 | | | | 3062 | externalAccountRequired | boolean | RFC XXXX | 3063 +-------------------------+-----------------+-----------+ 3065 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 3066 to this document ]] 3068 9.7.7. Identifier Types 3070 This registry lists the types of identifiers that can be present in 3071 ACME authorization objects. 3073 Template: 3075 o Label: The value to be put in the "type" field of the identifier 3076 object 3078 o Reference: Where the identifier type is defined 3080 Initial contents: 3082 +-------+-----------+ 3083 | Label | Reference | 3084 +-------+-----------+ 3085 | dns | RFC XXXX | 3086 +-------+-----------+ 3088 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 3089 to this document ]] 3091 9.7.8. Validation Methods 3093 This registry lists identifiers for the ways that CAs can validate 3094 control of identifiers. Each method's entry must specify whether it 3095 corresponds to an ACME challenge type. The "Identifier Type" field 3096 must be contained in the Label column of the ACME Identifier Types 3097 registry. 3099 Template: 3101 o Label: The identifier for this validation method 3103 o Identifier Type: The type of identifier that this method applies 3104 to 3106 o ACME: "Y" if the validation method corresponds to an ACME 3107 challenge type; "N" otherwise. 3109 o Reference: Where the validation method is defined 3111 Initial Contents 3113 +------------+-----------------+------+-----------+ 3114 | Label | Identifier Type | ACME | Reference | 3115 +------------+-----------------+------+-----------+ 3116 | http-01 | dns | Y | RFC XXXX | 3117 | | | | | 3118 | dns-01 | dns | Y | RFC XXXX | 3119 | | | | | 3120 | tls-sni-01 | RESERVED | N | RFC XXXX | 3121 | | | | | 3122 | tls-sni-02 | RESERVED | N | RFC XXXX | 3123 +------------+-----------------+------+-----------+ 3125 When evaluating a request for an assignment in this registry, the 3126 designated expert should ensure that the method being registered has 3127 a clear, interoperable definition and does not overlap with existing 3128 validation methods. That is, it should not be possible for a client 3129 and server to follow the same set of actions to fulfill two different 3130 validation methods. 3132 Validation methods do not have to be compatible with ACME in order to 3133 be registered. For example, a CA might wish to register a validation 3134 method in order to support its use with the ACME extensions to CAA 3135 [I-D.ietf-acme-caa]. 3137 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 3138 to this document ]] 3140 10. Security Considerations 3142 ACME is a protocol for managing certificates that attest to 3143 identifier/key bindings. Thus the foremost security goal of ACME is 3144 to ensure the integrity of this process, i.e., to ensure that the 3145 bindings attested by certificates are correct and that only 3146 authorized entities can manage certificates. ACME identifies clients 3147 by their account keys, so this overall goal breaks down into two more 3148 precise goals: 3150 1. Only an entity that controls an identifier can get an 3151 authorization for that identifier 3153 2. Once authorized, an account key's authorizations cannot be 3154 improperly used by another account 3156 In this section, we discuss the threat model that underlies ACME and 3157 the ways that ACME achieves these security goals within that threat 3158 model. We also discuss the denial-of-service risks that ACME servers 3159 face, and a few other miscellaneous considerations. 3161 10.1. Threat Model 3163 As a service on the Internet, ACME broadly exists within the Internet 3164 threat model [RFC3552]. In analyzing ACME, it is useful to think of 3165 an ACME server interacting with other Internet hosts along two 3166 "channels": 3168 o An ACME channel, over which the ACME HTTPS requests are exchanged 3170 o A validation channel, over which the ACME server performs 3171 additional requests to validate a client's control of an 3172 identifier 3174 +------------+ 3175 | ACME | ACME Channel 3176 | Client |--------------------+ 3177 +------------+ | 3178 V 3179 +------------+ 3180 | ACME | 3181 | Server | 3182 +------------+ 3183 +------------+ | 3184 | Validation |<-------------------+ 3185 | Server | Validation Channel 3186 +------------+ 3188 In practice, the risks to these channels are not entirely separate, 3189 but they are different in most cases. Each channel, for example, 3190 uses a different communications pattern: the ACME channel will 3191 comprise inbound HTTPS connections to the ACME server and the 3192 validation channel outbound HTTP or DNS requests. 3194 Broadly speaking, ACME aims to be secure against active and passive 3195 attackers on any individual channel. Some vulnerabilities arise 3196 (noted below) when an attacker can exploit both the ACME channel and 3197 one of the others. 3199 On the ACME channel, in addition to network layer attackers, we also 3200 need to account for man-in-the-middle (MitM) attacks at the 3201 application layer, and for abusive use of the protocol itself. 3202 Protection against application layer MitM addresses potential 3203 attackers such as Content Distribution Networks (CDNs) and 3204 middleboxes with a TLS MitM function. Preventing abusive use of ACME 3205 means ensuring that an attacker with access to the validation channel 3206 can't obtain illegitimate authorization by acting as an ACME client 3207 (legitimately, in terms of the protocol). 3209 10.2. Integrity of Authorizations 3211 ACME allows anyone to request challenges for an identifier by 3212 registering an account key and sending a new-order request using that 3213 account key. The integrity of the authorization process thus depends 3214 on the identifier validation challenges to ensure that the challenge 3215 can only be completed by someone who both (1) holds the private key 3216 of the account key pair, and (2) controls the identifier in question. 3218 Validation responses need to be bound to an account key pair in order 3219 to avoid situations where an ACME MitM can switch out a legitimate 3220 domain holder's account key for one of his choosing, e.g.: 3222 o Legitimate domain holder registers account key pair A 3224 o MitM registers account key pair B 3226 o Legitimate domain holder sends a new-order request signed using 3227 account key A 3229 o MitM suppresses the legitimate request but sends the same request 3230 signed using account key B 3232 o ACME server issues challenges and MitM forwards them to the 3233 legitimate domain holder 3235 o Legitimate domain holder provisions the validation response 3237 o ACME server performs validation query and sees the response 3238 provisioned by the legitimate domain holder 3240 o Because the challenges were issued in response to a message signed 3241 account key B, the ACME server grants authorization to account key 3242 B (the MitM) instead of account key A (the legitimate domain 3243 holder) 3245 All of the challenges above have a binding between the account 3246 private key and the validation query made by the server, via the key 3247 authorization. The key authorization reflects the account public 3248 key, is provided to the server in the validation response over the 3249 validation channel and signed afterwards by the corresponding private 3250 key in the challenge response over the ACME channel. 3252 The association of challenges to identifiers is typically done by 3253 requiring the client to perform some action that only someone who 3254 effectively controls the identifier can perform. For the challenges 3255 in this document, the actions are: 3257 o HTTP: Provision files under .well-known on a web server for the 3258 domain 3260 o DNS: Provision DNS resource records for the domain 3262 There are several ways that these assumptions can be violated, both 3263 by misconfiguration and by attacks. For example, on a web server 3264 that allows non-administrative users to write to .well-known, any 3265 user can claim to own the web server's hostname by responding to an 3266 HTTP challenge. Similarly, if a server that can be used for ACME 3267 validation is compromised by a malicious actor, then that malicious 3268 actor can use that access to obtain certificates via ACME. 3270 The use of hosting providers is a particular risk for ACME 3271 validation. If the owner of the domain has outsourced operation of 3272 DNS or web services to a hosting provider, there is nothing that can 3273 be done against tampering by the hosting provider. As far as the 3274 outside world is concerned, the zone or website provided by the 3275 hosting provider is the real thing. 3277 More limited forms of delegation can also lead to an unintended party 3278 gaining the ability to successfully complete a validation 3279 transaction. For example, suppose an ACME server follows HTTP 3280 redirects in HTTP validation and a website operator provisions a 3281 catch-all redirect rule that redirects requests for unknown resources 3282 to a different domain. Then the target of the redirect could use 3283 that to get a certificate through HTTP validation since the 3284 validation path will not be known to the primary server. 3286 The DNS is a common point of vulnerability for all of these 3287 challenges. An entity that can provision false DNS records for a 3288 domain can attack the DNS challenge directly and can provision false 3289 A/AAAA records to direct the ACME server to send its HTTP validation 3290 query to a remote server of the attacker's choosing. There are a few 3291 different mitigations that ACME servers can apply: 3293 o Always querying the DNS using a DNSSEC-validating resolver 3294 (enhancing security for zones that are DNSSEC-enabled) 3296 o Querying the DNS from multiple vantage points to address local 3297 attackers 3299 o Applying mitigations against DNS off-path attackers, e.g., adding 3300 entropy to requests [I-D.vixie-dnsext-dns0x20] or only using TCP 3302 Given these considerations, the ACME validation process makes it 3303 impossible for any attacker on the ACME channel or a passive attacker 3304 on the validation channel to hijack the authorization process to 3305 authorize a key of the attacker's choice. 3307 An attacker that can only see the ACME channel would need to convince 3308 the validation server to provide a response that would authorize the 3309 attacker's account key, but this is prevented by binding the 3310 validation response to the account key used to request challenges. A 3311 passive attacker on the validation channel can observe the correct 3312 validation response and even replay it, but that response can only be 3313 used with the account key for which it was generated. 3315 An active attacker on the validation channel can subvert the ACME 3316 process, by performing normal ACME transactions and providing a 3317 validation response for his own account key. The risks due to 3318 hosting providers noted above are a particular case. 3320 It is RECOMMENDED that the server perform DNS queries and make HTTP 3321 connections from various network perspectives, in order to make MitM 3322 attacks harder. 3324 10.3. Denial-of-Service Considerations 3326 As a protocol run over HTTPS, standard considerations for TCP-based 3327 and HTTP-based DoS mitigation also apply to ACME. 3329 At the application layer, ACME requires the server to perform a few 3330 potentially expensive operations. Identifier validation transactions 3331 require the ACME server to make outbound connections to potentially 3332 attacker-controlled servers, and certificate issuance can require 3333 interactions with cryptographic hardware. 3335 In addition, an attacker can also cause the ACME server to send 3336 validation requests to a domain of its choosing by submitting 3337 authorization requests for the victim domain. 3339 All of these attacks can be mitigated by the application of 3340 appropriate rate limits. Issues closer to the front end, like POST 3341 body validation, can be addressed using HTTP request limiting. For 3342 validation and certificate requests, there are other identifiers on 3343 which rate limits can be keyed. For example, the server might limit 3344 the rate at which any individual account key can issue certificates 3345 or the rate at which validation can be requested within a given 3346 subtree of the DNS. And in order to prevent attackers from 3347 circumventing these limits simply by minting new accounts, servers 3348 would need to limit the rate at which accounts can be registered. 3350 10.4. Server-Side Request Forgery 3352 Server-Side Request Forgery (SSRF) attacks can arise when an attacker 3353 can cause a server to perform HTTP requests to an attacker-chosen 3354 URL. In the ACME HTTP challenge validation process, the ACME server 3355 performs an HTTP GET request to a URL in which the attacker can 3356 choose the domain. This request is made before the server has 3357 verified that the client controls the domain, so any client can cause 3358 a query to any domain. 3360 Some server implementations include information from the validation 3361 server's response (in order to facilitate debugging). Such 3362 implementations enable an attacker to extract this information from 3363 any web server that is accessible to the ACME server, even if it is 3364 not accessible to the ACME client. 3366 It might seem that the risk of SSRF through this channel is limited 3367 by the fact that the attacker can only control the domain of the URL, 3368 not the path. However, if the attacker first sets the domain to one 3369 they control, then they can send the server an HTTP redirect (e.g., a 3370 302 response) which will cause the server to query an arbitrary URL. 3372 In order to further limit the SSRF risk, ACME server operators should 3373 ensure that validation queries can only be sent to servers on the 3374 public Internet, and not, say, web services within the server 3375 operator's internal network. Since the attacker could make requests 3376 to these public servers himself, he can't gain anything extra through 3377 an SSRF attack on ACME aside from a layer of anonymization. 3379 10.5. CA Policy Considerations 3381 The controls on issuance enabled by ACME are focused on validating 3382 that a certificate applicant controls the identifier he claims. 3383 Before issuing a certificate, however, there are many other checks 3384 that a CA might need to perform, for example: 3386 o Has the client agreed to a subscriber agreement? 3388 o Is the claimed identifier syntactically valid? 3390 o For domain names: 3392 * If the leftmost label is a '*', then have the appropriate 3393 checks been applied? 3395 * Is the name on the Public Suffix List? 3397 * Is the name a high-value name? 3399 * Is the name a known phishing domain? 3401 o Is the key in the CSR sufficiently strong? 3403 o Is the CSR signed with an acceptable algorithm? 3405 o Has issuance been authorized or forbidden by a Certificate 3406 Authority Authorization (CAA) record? [RFC6844] 3408 CAs that use ACME to automate issuance will need to ensure that their 3409 servers perform all necessary checks before issuing. 3411 CAs using ACME to allow clients to agree to terms of service should 3412 keep in mind that ACME clients can automate this agreement, possibly 3413 not involving a human user. 3415 11. Operational Considerations 3417 There are certain factors that arise in operational reality that 3418 operators of ACME-based CAs will need to keep in mind when 3419 configuring their services. For example: 3421 11.1. Key Selection 3423 ACME relies on two different classes of key pair: 3425 o Account key pairs, which are used to authenticate account holders 3427 o Certificate key pairs, which are used to sign and verify CSRs (and 3428 whose public keys are included in certificates) 3430 Compromise of the private key of an account key pair has more serious 3431 consequences than compromise of a private key corresponding to a 3432 certificate. While the compromise of a certificate key pair allows 3433 the attacker to impersonate the entities named in the certificate for 3434 the lifetime of the certificate, the compromise of an account key 3435 pair allows the attacker to take full control of the victim's ACME 3436 account, and take any action that the legitimate account holder could 3437 take within the scope of ACME: 3439 1. Issuing certificates using existing authorizations 3440 2. Revoking existing certificates 3442 3. Accessing and changing account information (e.g., contacts) 3444 4. Changing the account key pair for the account, locking out the 3445 legitimate account holder 3447 For this reason, it is RECOMMENDED that account key pairs be used for 3448 no other purpose besides ACME authentication. For example, the 3449 public key of an account key pair SHOULD NOT be included in a 3450 certificate. ACME clients and servers SHOULD verify that a CSR 3451 submitted in a finalize request does not contain a public key for any 3452 known account key pair. In particular, when a server receives a 3453 finalize request, it MUST verify that the public key in a CSR is not 3454 the same as the public key of the account key pair used to 3455 authenticate that request. 3457 11.2. DNS security 3459 As noted above, DNS forgery attacks against the ACME server can 3460 result in the server making incorrect decisions about domain control 3461 and thus mis-issuing certificates. Servers SHOULD perform DNS 3462 queries over TCP, which provides better resistance to some forgery 3463 attacks than DNS over UDP. 3465 An ACME-based CA will often need to make DNS queries, e.g., to 3466 validate control of DNS names. Because the security of such 3467 validations ultimately depends on the authenticity of DNS data, every 3468 possible precaution should be taken to secure DNS queries done by the 3469 CA. It is therefore RECOMMENDED that ACME-based CAs make all DNS 3470 queries via DNSSEC-validating stub or recursive resolvers. This 3471 provides additional protection to domains which choose to make use of 3472 DNSSEC. 3474 An ACME-based CA must use only a resolver if it trusts the resolver 3475 and every component of the network route by which it is accessed. It 3476 is therefore RECOMMENDED that ACME-based CAs operate their own 3477 DNSSEC-validating resolvers within their trusted network and use 3478 these resolvers both for both CAA record lookups and all record 3479 lookups in furtherance of a challenge scheme (A, AAAA, TXT, etc.). 3481 11.3. Token Entropy 3483 The http-01, and dns-01 validation methods mandate the usage of a 3484 random token value to uniquely identify the challenge. The value of 3485 the token is required to contain at least 128 bits of entropy for the 3486 following security properties. First, the ACME client should not be 3487 able to influence the ACME server's choice of token as this may allow 3488 an attacker to reuse a domain owner's previous challenge responses 3489 for a new validation request. Secondly, the entropy requirement 3490 prevents ACME clients from implementing a "naive" validation server 3491 that automatically replies to challenges without participating in the 3492 creation of the initial authorization request. 3494 11.4. Malformed Certificate Chains 3496 ACME provides certificate chains in the widely-used format known 3497 colloquially as PEM (though it may diverge from the actual Privacy 3498 Enhanced Mail specifications [RFC1421], as noted in [RFC7468]). Some 3499 current software will allow the configuration of a private key and a 3500 certificate in one PEM file, by concatenating the textual encodings 3501 of the two objects. In the context of ACME, such software might be 3502 vulnerable to "key replacement" attacks. A malicious ACME server 3503 could cause a client to use a private key of its choosing by 3504 including the key in the PEM file returned in response to a query for 3505 a certificate URL. 3507 When processing an file of type "application/pem-certificate-chain", 3508 a client SHOULD verify that the file contains only encoded 3509 certificates. If anything other than a certificate is found (i.e., 3510 if the string "-----BEGIN" is ever followed by anything other than 3511 "CERTIFICATE"), then the client MUST reject the file as invalid. 3513 12. Acknowledgements 3515 In addition to the editors listed on the front page, this document 3516 has benefited from contributions from a broad set of contributors, 3517 all the way back to its inception. 3519 o Peter Eckersley, EFF 3521 o Eric Rescorla, Mozilla 3523 o Seth Schoen, EFF 3525 o Alex Halderman, University of Michigan 3527 o Martin Thomson, Mozilla 3529 o Jakub Warmuz, University of Oxford 3531 o Sophie Herold, Hemio 3533 This document draws on many concepts established by Eric Rescorla's 3534 "Automated Certificate Issuance Protocol" draft. Martin Thomson 3535 provided helpful guidance in the use of HTTP. 3537 13. References 3539 13.1. Normative References 3541 [FIPS180-4] 3542 Department of Commerce, National., "NIST FIPS 180-4, 3543 Secure Hash Standard", March 2012, 3544 . 3547 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3548 Requirement Levels", BCP 14, RFC 2119, 3549 DOI 10.17487/RFC2119, March 1997, 3550 . 3552 [RFC2585] Housley, R. and P. Hoffman, "Internet X.509 Public Key 3553 Infrastructure Operational Protocols: FTP and HTTP", 3554 RFC 2585, DOI 10.17487/RFC2585, May 1999, 3555 . 3557 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 3558 DOI 10.17487/RFC2818, May 2000, 3559 . 3561 [RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object 3562 Classes and Attribute Types Version 2.0", RFC 2985, 3563 DOI 10.17487/RFC2985, November 2000, 3564 . 3566 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 3567 Request Syntax Specification Version 1.7", RFC 2986, 3568 DOI 10.17487/RFC2986, November 2000, 3569 . 3571 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 3572 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 3573 . 3575 [RFC3492] Costello, A., "Punycode: A Bootstring encoding of Unicode 3576 for Internationalized Domain Names in Applications 3577 (IDNA)", RFC 3492, DOI 10.17487/RFC3492, March 2003, 3578 . 3580 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3581 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 3582 2003, . 3584 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3585 Resource Identifier (URI): Generic Syntax", STD 66, 3586 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3587 . 3589 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 3590 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 3591 . 3593 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3594 (TLS) Protocol Version 1.2", RFC 5246, 3595 DOI 10.17487/RFC5246, August 2008, 3596 . 3598 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3599 Housley, R., and W. Polk, "Internet X.509 Public Key 3600 Infrastructure Certificate and Certificate Revocation List 3601 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3602 . 3604 [RFC5890] Klensin, J., "Internationalized Domain Names for 3605 Applications (IDNA): Definitions and Document Framework", 3606 RFC 5890, DOI 10.17487/RFC5890, August 2010, 3607 . 3609 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 3610 DOI 10.17487/RFC5988, October 2010, 3611 . 3613 [RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' 3614 URI Scheme", RFC 6068, DOI 10.17487/RFC6068, October 2010, 3615 . 3617 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 3618 and D. Orchard, "URI Template", RFC 6570, 3619 DOI 10.17487/RFC6570, March 2012, 3620 . 3622 [RFC6844] Hallam-Baker, P. and R. Stradling, "DNS Certification 3623 Authority Authorization (CAA) Resource Record", RFC 6844, 3624 DOI 10.17487/RFC6844, January 2013, 3625 . 3627 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3628 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3629 2014, . 3631 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3632 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 3633 DOI 10.17487/RFC7231, June 2014, 3634 . 3636 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 3637 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 3638 April 2015, . 3640 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 3641 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 3642 2015, . 3644 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 3645 DOI 10.17487/RFC7518, May 2015, 3646 . 3648 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 3649 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 3650 2015, . 3652 [RFC7797] Jones, M., "JSON Web Signature (JWS) Unencoded Payload 3653 Option", RFC 7797, DOI 10.17487/RFC7797, February 2016, 3654 . 3656 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 3657 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 3658 . 3660 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3661 Writing an IANA Considerations Section in RFCs", BCP 26, 3662 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3663 . 3665 13.2. Informative References 3667 [I-D.ietf-acme-caa] 3668 Landau, H., "CAA Record Extensions for Account URI and 3669 ACME Method Binding", draft-ietf-acme-caa-03 (work in 3670 progress), August 2017. 3672 [I-D.ietf-acme-ip] 3673 Shoemaker, R., "ACME IP Identifier Validation Extension", 3674 draft-ietf-acme-ip-01 (work in progress), September 2017. 3676 [I-D.ietf-acme-telephone] 3677 Peterson, J. and R. Barnes, "ACME Identifiers and 3678 Challenges for Telephone Numbers", draft-ietf-acme- 3679 telephone-01 (work in progress), October 2017. 3681 [I-D.vixie-dnsext-dns0x20] 3682 Vixie, P. and D. Dagon, "Use of Bit 0x20 in DNS Labels to 3683 Improve Transaction Identity", draft-vixie-dnsext- 3684 dns0x20-00 (work in progress), March 2008. 3686 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 3687 Mail: Part I: Message Encryption and Authentication 3688 Procedures", RFC 1421, DOI 10.17487/RFC1421, February 3689 1993, . 3691 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 3692 Text on Security Considerations", BCP 72, RFC 3552, 3693 DOI 10.17487/RFC3552, July 2003, 3694 . 3696 [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An 3697 IETF URN Sub-namespace for Registered Protocol 3698 Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June 3699 2003, . 3701 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 3702 Uniform Resource Identifiers (URIs)", RFC 5785, 3703 DOI 10.17487/RFC5785, April 2010, 3704 . 3706 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 3707 "Recommendations for Secure Use of Transport Layer 3708 Security (TLS) and Datagram Transport Layer Security 3709 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 3710 2015, . 3712 [W3C.CR-cors-20130129] 3713 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 3714 Web Consortium CR CR-cors-20130129, January 2013, 3715 . 3717 13.3. URIs 3719 [1] https://github.com/ietf-wg-acme/acme 3721 Authors' Addresses 3723 Richard Barnes 3724 Cisco 3726 Email: rlb@ipv.sx 3728 Jacob Hoffman-Andrews 3729 EFF 3731 Email: jsha@eff.org 3733 Daniel McCarney 3734 Let's Encrypt 3736 Email: cpu@letsencrypt.org 3738 James Kasten 3739 University of Michigan 3741 Email: jdkasten@umich.edu