idnits 2.17.1 draft-ietf-acme-acme-17.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 is 1 instance of too long lines in the document, the longest one being 5 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 927 has weird spacing: '...Account newA...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: ACME clients and servers MUST verify that a CSR submitted in a finalize request does not contain a public key for any known account key pair. In particular, when a server receives a finalize request, it MUST verify that the public key in a CSR is not the same as the public key of the account key pair used to authenticate that request. This assures that vulnerabilities in the protocols with which the certificate is used (e.g., signing oracles in TLS [JSS15]) do not result in compromise of the ACME account. Because ACME accounts are uniquely identified by their account key pair (see Section 7.3.1) the server MUST not allow account key pair reuse across multiple accounts. -- The document date (December 17, 2018) is 1957 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 4107 == Missing Reference: 'Order' is mentioned on line 375, but not defined == Missing Reference: 'Responses' is mentioned on line 379, but not defined == Missing Reference: 'CSR' is mentioned on line 384, but not defined -- Looks like a reference, but probably isn't: '2' on line 4109 -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS180-4' -- Possible downref: Non-RFC (?) normative reference: ref. 'JSS15' -- Possible downref: Non-RFC (?) normative reference: ref. 'REST' ** 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 5751 (Obsoleted by RFC 8551) ** 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-05 == Outdated reference: A later version (-08) exists of draft-ietf-acme-ip-04 -- 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: 12 errors (**), 0 flaws (~~), 8 warnings (==), 9 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: June 20, 2019 EFF 6 D. McCarney 7 Let's Encrypt 8 J. Kasten 9 University of Michigan 10 December 17, 2018 12 Automatic Certificate Management Environment (ACME) 13 draft-ietf-acme-acme-17 15 Abstract 17 Public Key Infrastructure X.509 (PKIX) certificates are used for a 18 number of purposes, the most significant of which is the 19 authentication of domain names. Thus, certification authorities 20 (CAs) in the Web PKI are trusted to verify that an applicant for a 21 certificate legitimately represents the domain name(s) in the 22 certificate. Today, this verification is done through a collection 23 of ad hoc mechanisms. This document describes a protocol that a CA 24 and 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 June 20, 2019. 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 . . . . . . . . . . . . . . . . . . . . . . . . . 7 73 4. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 7 74 5. Character Encoding . . . . . . . . . . . . . . . . . . . . . 10 75 6. Message Transport . . . . . . . . . . . . . . . . . . . . . . 10 76 6.1. HTTPS Requests . . . . . . . . . . . . . . . . . . . . . 10 77 6.2. Request Authentication . . . . . . . . . . . . . . . . . 11 78 6.3. GET and POST-as-GET Requests . . . . . . . . . . . . . . 12 79 6.4. Request URL Integrity . . . . . . . . . . . . . . . . . . 13 80 6.4.1. "url" (URL) JWS Header Parameter . . . . . . . . . . 14 81 6.5. Replay protection . . . . . . . . . . . . . . . . . . . . 14 82 6.5.1. Replay-Nonce . . . . . . . . . . . . . . . . . . . . 15 83 6.5.2. "nonce" (Nonce) JWS Header Parameter . . . . . . . . 15 84 6.6. Rate Limits . . . . . . . . . . . . . . . . . . . . . . . 15 85 6.7. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 16 86 6.7.1. Subproblems . . . . . . . . . . . . . . . . . . . . . 18 87 7. Certificate Management . . . . . . . . . . . . . . . . . . . 19 88 7.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 19 89 7.1.1. Directory . . . . . . . . . . . . . . . . . . . . . . 22 90 7.1.2. Account Objects . . . . . . . . . . . . . . . . . . . 24 91 7.1.3. Order Objects . . . . . . . . . . . . . . . . . . . . 25 92 7.1.4. Authorization Objects . . . . . . . . . . . . . . . . 28 93 7.1.5. Challenge Objects . . . . . . . . . . . . . . . . . . 30 94 7.1.6. Status Changes . . . . . . . . . . . . . . . . . . . 30 95 7.2. Getting a Nonce . . . . . . . . . . . . . . . . . . . . . 32 96 7.3. Account Management . . . . . . . . . . . . . . . . . . . 33 97 7.3.1. Finding an Account URL Given a Key . . . . . . . . . 35 98 7.3.2. Account Update . . . . . . . . . . . . . . . . . . . 36 99 7.3.3. Changes of Terms of Service . . . . . . . . . . . . . 36 100 7.3.4. External Account Binding . . . . . . . . . . . . . . 37 101 7.3.5. Account Key Roll-over . . . . . . . . . . . . . . . . 39 102 7.3.6. Account Deactivation . . . . . . . . . . . . . . . . 42 103 7.4. Applying for Certificate Issuance . . . . . . . . . . . . 43 104 7.4.1. Pre-Authorization . . . . . . . . . . . . . . . . . . 47 105 7.4.2. Downloading the Certificate . . . . . . . . . . . . . 49 106 7.5. Identifier Authorization . . . . . . . . . . . . . . . . 51 107 7.5.1. Responding to Challenges . . . . . . . . . . . . . . 53 108 7.5.2. Deactivating an Authorization . . . . . . . . . . . . 55 109 7.6. Certificate Revocation . . . . . . . . . . . . . . . . . 56 110 8. Identifier Validation Challenges . . . . . . . . . . . . . . 58 111 8.1. Key Authorizations . . . . . . . . . . . . . . . . . . . 60 112 8.2. Retrying Challenges . . . . . . . . . . . . . . . . . . . 60 113 8.3. HTTP Challenge . . . . . . . . . . . . . . . . . . . . . 61 114 8.4. DNS Challenge . . . . . . . . . . . . . . . . . . . . . . 64 115 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 65 116 9.1. MIME Type: application/pem-certificate-chain . . . . . . 65 117 9.2. Well-Known URI for the HTTP Challenge . . . . . . . . . . 67 118 9.3. Replay-Nonce HTTP Header . . . . . . . . . . . . . . . . 67 119 9.4. "url" JWS Header Parameter . . . . . . . . . . . . . . . 67 120 9.5. "nonce" JWS Header Parameter . . . . . . . . . . . . . . 68 121 9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) . . . . 68 122 9.7. New Registries . . . . . . . . . . . . . . . . . . . . . 68 123 9.7.1. Fields in Account Objects . . . . . . . . . . . . . . 69 124 9.7.2. Fields in Order Objects . . . . . . . . . . . . . . . 70 125 9.7.3. Fields in Authorization Objects . . . . . . . . . . . 71 126 9.7.4. Error Types . . . . . . . . . . . . . . . . . . . . . 72 127 9.7.5. Resource Types . . . . . . . . . . . . . . . . . . . 72 128 9.7.6. Fields in the "meta" Object within a Directory Object 73 129 9.7.7. Identifier Types . . . . . . . . . . . . . . . . . . 74 130 9.7.8. Validation Methods . . . . . . . . . . . . . . . . . 74 131 10. Security Considerations . . . . . . . . . . . . . . . . . . . 76 132 10.1. Threat Model . . . . . . . . . . . . . . . . . . . . . . 76 133 10.2. Integrity of Authorizations . . . . . . . . . . . . . . 78 134 10.3. Denial-of-Service Considerations . . . . . . . . . . . . 81 135 10.4. Server-Side Request Forgery . . . . . . . . . . . . . . 82 136 10.5. CA Policy Considerations . . . . . . . . . . . . . . . . 82 137 11. Operational Considerations . . . . . . . . . . . . . . . . . 84 138 11.1. Key Selection . . . . . . . . . . . . . . . . . . . . . 84 139 11.2. DNS security . . . . . . . . . . . . . . . . . . . . . . 85 140 11.3. Token Entropy . . . . . . . . . . . . . . . . . . . . . 85 141 11.4. Malformed Certificate Chains . . . . . . . . . . . . . . 86 142 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 86 143 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 87 144 13.1. Normative References . . . . . . . . . . . . . . . . . . 87 145 13.2. Informative References . . . . . . . . . . . . . . . . . 90 146 13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 91 147 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 92 149 1. Introduction 151 Certificates [RFC5280] in the Web PKI are most commonly used to 152 authenticate domain names. Thus, certification authorities (CAs) in 153 the Web 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. The 159 only validation the CA is required to perform in the DV issuance 160 process is to verify that the requester has effective control of the 161 domain [CABFBR]. The CA is not required to attempt to verify the 162 requester's real-world identity. (This is as opposed to 163 "Organization Validation" (OV) and "Extended Validation" (EV) 164 certificates, where the process is intended to also verify the real- 165 world identity of the requester.) 167 Existing Web PKI certificate authorities tend to use a set of ad hoc 168 protocols for certificate issuance and identity verification. In the 169 case of DV certificates, a typical user experience is something like: 171 o Generate a PKCS#10 [RFC2986] Certificate Signing Request (CSR). 173 o Cut-and-paste the CSR into a CA's web page. 175 o Prove ownership of the domain by one of the following methods: 177 * Put a CA-provided challenge at a specific place on the web 178 server. 180 * Put a CA-provided challenge in a DNS record corresponding to 181 the target domain. 183 * Receive a CA-provided challenge at a (hopefully) administrator- 184 controlled email address corresponding to the domain and then 185 respond to it on the CA's web page. 187 o Download the issued certificate and install it on their Web 188 Server. 190 With the exception of the CSR itself and the certificates that are 191 issued, these are all completely ad hoc procedures and are 192 accomplished by getting the human user to follow interactive natural- 193 language instructions from the CA rather than by machine-implemented 194 published protocols. In many cases, the instructions are difficult 195 to follow and cause significant frustration and confusion. Informal 196 usability tests by the authors indicate that webmasters often need 197 1-3 hours to obtain and install a certificate for a domain. Even in 198 the best case, the lack of published, standardized mechanisms 199 presents an obstacle to the wide deployment of HTTPS and other PKIX- 200 dependent systems because it inhibits mechanization of tasks related 201 to certificate issuance, deployment, and revocation. 203 This document describes an extensible framework for automating the 204 issuance and domain validation procedure, thereby allowing servers 205 and infrastructure software to obtain certificates without user 206 interaction. Use of this protocol should radically simplify the 207 deployment of HTTPS and the practicality of PKIX-based authentication 208 for other protocols based on Transport Layer Security (TLS) 209 [RFC5246]. 211 It should be noted that while the focus of this document is on 212 validating domain names for purposes of issuing certificates in the 213 Web PKI, ACME supports extensions for uses with other identifiers in 214 other PKI contexts. For example, as of this writing, there is 215 ongoing work to use ACME for issuance of Web PKI certificates 216 attesting to IP addresses [I-D.ietf-acme-ip] and STIR certificates 217 attesting to telephone numbers [I-D.ietf-acme-telephone]. 219 ACME can also be used to automate some aspects of certificate 220 management even where non-automated processes are still needed. For 221 example, the external account binding feature (see Section 7.3.4) can 222 allow an ACME account to use authorizations that have been granted to 223 an external, non-ACME account. This allows ACME to address issuance 224 scenarios that cannot yet be fully automated, such as the issuance of 225 Extended Validation certificates. 227 2. Deployment Model and Operator Experience 229 The guiding use case for ACME is obtaining certificates for websites 230 (HTTPS [RFC2818]). In this case, a web server is intended to speak 231 for one or more domains, and the process of certificate issuance is 232 intended to verify that this web server actually speaks for the 233 domain(s). 235 DV certificate validation commonly checks claims about properties 236 related to control of a domain name - properties that can be observed 237 by the certificate issuer in an interactive process that can be 238 conducted purely online. That means that under typical 239 circumstances, all steps in the request, verification, and issuance 240 process can be represented and performed by Internet protocols with 241 no out-of-band human intervention. 243 Prior to ACME, when deploying an HTTPS server, a server operator 244 typically gets a prompt to generate a self-signed certificate. If 245 the operator were instead deploying an HTTPS server using ACME, the 246 experience would be something like this: 248 o The operator's ACME client prompts the operator for the intended 249 domain name(s) that the web server is to stand for. 251 o The ACME client presents the operator with a list of CAs from 252 which it could get a certificate. (This list will change over 253 time based on the capabilities of CAs and updates to ACME 254 configuration.) The ACME client might prompt the operator for 255 payment information at this point. 257 o The operator selects a CA. 259 o In the background, the ACME client contacts the CA and requests 260 that it issue a certificate for the intended domain name(s). 262 o The CA verifies that the client controls the requested domain 263 name(s) by having the ACME client perform some action(s) that can 264 only be done with control of the domain name(s). For example, the 265 CA might require a client requesting example.com to provision DNS 266 record under example.com or an HTTP resource under 267 http://example.com. 269 o Once the CA is satisfied, it issues the certificate and the ACME 270 client automatically downloads and installs it, potentially 271 notifying the operator via email, SMS, etc. 273 o The ACME client periodically contacts the CA to get updated 274 certificates, stapled OCSP responses, or whatever else would be 275 required to keep the web server functional and its credentials up- 276 to-date. 278 In this way, it would be nearly as easy to deploy with a CA-issued 279 certificate as with a self-signed certificate. Furthermore, the 280 maintenance of that CA-issued certificate would require minimal 281 manual intervention. Such close integration of ACME with HTTPS 282 servers allows the immediate and automated deployment of certificates 283 as they are issued, sparing the human administrator from much of the 284 time-consuming work described in the previous section. 286 3. Terminology 288 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 289 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 290 "OPTIONAL" in this document are to be interpreted as described in BCP 291 14 [RFC2119] [RFC8174] when, and only when, they appear in all 292 capitals, as shown here. 294 The two main roles in ACME are "client" and "server". The ACME 295 client uses the protocol to request certificate management actions, 296 such as issuance or revocation. An ACME client may run on a web 297 server, mail server, or some other server system which requires valid 298 X.509 certificates. Or, it may run on a separate server that does 299 not consume the certificate, but is authorized to respond to a CA- 300 provided challenge. The ACME server runs at a certification 301 authority, and responds to client requests, performing the requested 302 actions if the client is authorized. 304 An ACME client authenticates to the server by means of an "account 305 key pair". The client uses the private key of this key pair to sign 306 all messages sent to the server. The server uses the public key to 307 verify the authenticity and integrity of messages from the client. 309 4. Protocol Overview 311 ACME allows a client to request certificate management actions using 312 a set of JavaScript Object Notation (JSON) messages carried over 313 HTTPS [RFC7159] [RFC2818]. Issuance using ACME resembles a 314 traditional CA's issuance process, in which a user creates an 315 account, requests a certificate, and proves control of the domain(s) 316 in that certificate in order for the CA to issue the requested 317 certificate. 319 The first phase of ACME is for the client to request an account with 320 the ACME server. The client generates an asymmetric key pair and 321 requests a new account, optionally providing contact information, 322 agreeing to terms of service, and/or associating the account with an 323 existing account in another system. The creation request is signed 324 with the generated private key to prove that the client controls it. 326 Client Server 328 [Contact Information] 329 [ToS Agreement] 330 [Additional Data] 331 Signature -------> 332 Account URL 333 <------- Account Object 335 [] Information covered by request signatures 337 Account Creation 339 Once an account is registered, there are four major steps the client 340 needs to take to get a certificate: 342 1. Submit an order for a certificate to be issued 344 2. Prove control of any identifiers requested in the certificate 346 3. Finalize the order by submitting a CSR 348 4. Await issuance and download the issued certificate 350 The client's order for a certificate describes the desired 351 identifiers plus a few additional fields that capture semantics that 352 are not supported in the CSR format. If the server is willing to 353 consider issuing such a certificate, it responds with a list of 354 requirements that the client must satisfy before the certificate will 355 be issued. 357 For example, in most cases, the server will require the client to 358 demonstrate that it controls the identifiers in the requested 359 certificate. Because there are many different ways to validate 360 possession of different types of identifiers, the server will choose 361 from an extensible set of challenges that are appropriate for the 362 identifier being claimed. The client responds with a set of 363 responses that tell the server which challenges the client has 364 completed. The server then validates that the client has completed 365 the challenges. 367 Once the validation process is complete and the server is satisfied 368 that the client has met its requirements, the client finalizes the 369 order by submitting a PKCS#10 Certificate Signing Request (CSR). The 370 server will issue the requested certificate and make it available to 371 the client. 373 Client Server 375 [Order] 376 Signature -------> 377 <------- Required Authorizations 379 [Responses] 380 Signature -------> 382 <~~~~~~~~Validation~~~~~~~~> 384 [CSR] 385 Signature -------> 386 <------- Acknowledgement 388 <~~~~~~Await issuance~~~~~~> 390 POST-as-GET request -------> 391 <------- Certificate 393 [] Information covered by request signatures 395 Certificate Issuance 397 To revoke a certificate, the client sends a signed revocation request 398 indicating the certificate to be revoked: 400 Client Server 402 [Revocation request] 403 Signature --------> 405 <-------- Result 407 [] Information covered by request signatures 409 Certificate Revocation 411 Note that while ACME is defined with enough flexibility to handle 412 different types of identifiers in principle, the primary use case 413 addressed by this document is the case where domain names are used as 414 identifiers. For example, all of the identifier validation 415 challenges described in Section 8 below address validation of domain 416 names. The use of ACME for other identifiers will require further 417 specification in order to describe how these identifiers are encoded 418 in the protocol and what types of validation challenges the server 419 might require. 421 5. Character Encoding 423 All requests and responses sent via HTTP by ACME clients, ACME 424 servers, and validation servers as well as any inputs for digest 425 computations MUST be encoded using the UTF-8 [RFC3629] character set. 426 Note that identifiers that appear in certificates may have their own 427 encoding considerations (e.g., DNS names containing non-ASCII 428 characters are expressed as A-labels rather than U-labels). Any such 429 encoding considerations are to be applied prior to the aforementioned 430 UTF-8 encoding. 432 6. Message Transport 434 Communications between an ACME client and an ACME server are done 435 over HTTPS, using JSON Web Signature (JWS) [RFC7515] to provide some 436 additional security properties for messages sent from the client to 437 the server. HTTPS provides server authentication and 438 confidentiality. With some ACME-specific extensions, JWS provides 439 authentication of the client's request payloads, anti-replay 440 protection, and integrity for the HTTPS request URL. 442 6.1. HTTPS Requests 444 Each ACME function is accomplished by the client sending a sequence 445 of HTTPS requests to the server, carrying JSON messages 446 [RFC2818][RFC7159]. Use of HTTPS is REQUIRED. Each subsection of 447 Section 7 below describes the message formats used by the function 448 and the order in which messages are sent. 450 In most HTTPS transactions used by ACME, the ACME client is the HTTPS 451 client and the ACME server is the HTTPS server. The ACME server acts 452 as a client when validating challenges: an HTTP client when 453 validating an 'http-01' challenge, a DNS client with 'dns-01', etc. 455 ACME servers SHOULD follow the recommendations of [RFC7525] when 456 configuring their TLS implementations. ACME servers that support TLS 457 1.3 MAY allow clients to send early data (0-RTT). This is safe 458 because the ACME protocol itself includes anti-replay protections 459 (see Section 6.5) in all cases where they are required. For this 460 reason, there are no restrictions on what ACME data can be carried in 461 0-RTT. 463 ACME clients MUST send a User-Agent header field, in accordance with 464 [RFC7231]. This header field SHOULD include the name and version of 465 the ACME software in addition to the name and version of the 466 underlying HTTP client software. 468 ACME clients SHOULD send an Accept-Language header field in 469 accordance with [RFC7231] to enable localization of error messages. 471 ACME servers that are intended to be generally accessible need to use 472 Cross-Origin Resource Sharing (CORS) in order to be accessible from 473 browser-based clients [W3C.REC-cors-20140116]. Such servers SHOULD 474 set the Access-Control-Allow-Origin header field to the value "*". 476 Binary fields in the JSON objects used by ACME are encoded using 477 base64url encoding described in [RFC4648] Section 5, according to the 478 profile specified in JSON Web Signature [RFC7515] Section 2. This 479 encoding uses a URL safe character set. Trailing '=' characters MUST 480 be stripped. Encoded values that include trailing '=' characters 481 MUST be rejected as improperly encoded. 483 6.2. Request Authentication 485 All ACME requests with a non-empty body MUST encapsulate their 486 payload in a JSON Web Signature (JWS) [RFC7515] object, signed using 487 the account's private key unless otherwise specified. The server 488 MUST verify the JWS before processing the request. Encapsulating 489 request bodies in JWS provides authentication of requests. 491 JWS objects sent in ACME requests MUST meet the following additional 492 criteria: 494 o The JWS MUST be in the Flattened JSON Serialization [RFC7515] 496 o The JWS MUST NOT have multiple signatures 498 o The JWS Unencoded Payload Option [RFC7797] MUST NOT be used 500 o The JWS Unprotected Header [RFC7515] MUST NOT be used 502 o The JWS Payload MUST NOT be detached 504 o The JWS Protected Header MUST include the following fields: 506 * "alg" (Algorithm) 508 + This field MUST NOT contain "none" or a Message 509 Authentication Code (MAC)-based algorithm (e.g. one in which 510 the algorithm registry description mentions MAC/HMAC). 512 * "nonce" (defined in Section 6.5 below) 514 * "url" (defined in Section 6.4 below) 515 * Either "jwk" (JSON Web Key) or "kid" (Key ID) as specified 516 below 518 An ACME server MUST implement the "ES256" signature algorithm 519 [RFC7518] and SHOULD implement the "EdDSA" signature algorithm using 520 the "Ed25519" variant (indicated by "crv") [RFC8037]. 522 The "jwk" and "kid" fields are mutually exclusive. Servers MUST 523 reject requests that contain both. 525 For newAccount requests, and for revokeCert requests authenticated by 526 a certificate key, there MUST be a "jwk" field. This field MUST 527 contain the public key corresponding to the private key used to sign 528 the JWS. 530 For all other requests, the request is signed using an existing 531 account and there MUST be a "kid" field. This field MUST contain the 532 account URL received by POSTing to the newAccount resource. 534 If the client sends a JWS signed with an algorithm that the server 535 does not support, then the server MUST return an error with status 536 code 400 (Bad Request) and type 537 "urn:ietf:params:acme:error:badSignatureAlgorithm". The problem 538 document returned with the error MUST include an "algorithms" field 539 with an array of supported "alg" values. See Section 6.7 for more 540 details on the structure of error responses. 542 Because client requests in ACME carry JWS objects in the Flattened 543 JSON Serialization, they must have the "Content-Type" header field 544 set to "application/jose+json". If a request does not meet this 545 requirement, then the server MUST return a response with status code 546 415 (Unsupported Media Type). 548 6.3. GET and POST-as-GET Requests 550 Note that authentication via signed JWS request bodies implies that 551 requests without an entity body are not authenticated, in particular 552 GET requests. Except for the cases described in this section, if the 553 server receives a GET request, it MUST return an error with status 554 code 405 "Method Not Allowed" and type "malformed". 556 If a client wishes to fetch a resource from the server (which would 557 otherwise be done with a GET), then it MUST send a POST request with 558 a JWS body as described above, where the payload of the JWS is a 559 zero-length octet string. In other words, the "payload" field of the 560 JWS object MUST be present and set to the empty string (""). 562 We will refer to these as "POST-as-GET" requests. On receiving a 563 request with a zero-length (and thus non-JSON) payload, the server 564 MUST authenticate the sender and verify any access control rules. 565 Otherwise, the server MUST treat this request as having the same 566 semantics as a GET request for the same resource. 568 The server MUST allow GET requests for the directory and newNonce 569 resources (see Section 7.1), in addition to POST-as-GET requests for 570 these resources. This enables clients to bootstrap into the ACME 571 authentication system. 573 6.4. Request URL Integrity 575 It is common in deployment for the entity terminating TLS for HTTPS 576 to be different from the entity operating the logical HTTPS server, 577 with a "request routing" layer in the middle. For example, an ACME 578 CA might have a content delivery network terminate TLS connections 579 from clients so that it can inspect client requests for denial-of- 580 service protection. 582 These intermediaries can also change values in the request that are 583 not signed in the HTTPS request, e.g., the request URL and header 584 fields. ACME uses JWS to provide an integrity mechanism, which 585 protects against an intermediary changing the request URL to another 586 ACME URL. 588 As noted in Section 6.2 above, all ACME request objects carry a "url" 589 header parameter in their protected header. This header parameter 590 encodes the URL to which the client is directing the request. On 591 receiving such an object in an HTTP request, the server MUST compare 592 the "url" header parameter to the request URL. If the two do not 593 match, then the server MUST reject the request as unauthorized. 595 Except for the directory resource, all ACME resources are addressed 596 with URLs provided to the client by the server. In requests sent to 597 these resources, the client MUST set the "url" header parameter to 598 the exact string provided by the server (rather than performing any 599 re-encoding on the URL). The server SHOULD perform the corresponding 600 string equality check, configuring each resource with the URL string 601 provided to clients and having the resource check that requests have 602 the same string in their "url" header parameter. The server MUST 603 reject the request as unauthorized if the string equality check 604 fails. 606 6.4.1. "url" (URL) JWS Header Parameter 608 The "url" header parameter specifies the URL [RFC3986] to which this 609 JWS object is directed. The "url" header parameter MUST be carried 610 in the protected header of the JWS. The value of the "url" header 611 parameter MUST be a string representing the target URL. 613 6.5. Replay protection 615 In order to protect ACME resources from any possible replay attacks, 616 ACME POST requests have a mandatory anti-replay mechanism. This 617 mechanism is based on the server maintaining a list of nonces that it 618 has issued, and requiring any signed request from the client to carry 619 such a nonce. 621 An ACME server provides nonces to clients using the HTTP Replay-Nonce 622 header field, as specified in Section 6.5.1 below. The server MUST 623 include a Replay-Nonce header field in every successful response to a 624 POST request and SHOULD provide it in error responses as well. 626 Every JWS sent by an ACME client MUST include, in its protected 627 header, the "nonce" header parameter, with contents as defined in 628 Section 6.5.2 below. As part of JWS verification, the ACME server 629 MUST verify that the value of the "nonce" header is a value that the 630 server previously provided in a Replay-Nonce header field. Once a 631 nonce value has appeared in an ACME request, the server MUST consider 632 it invalid, in the same way as a value it had never issued. 634 When a server rejects a request because its nonce value was 635 unacceptable (or not present), it MUST provide HTTP status code 400 636 (Bad Request), and indicate the ACME error type 637 "urn:ietf:params:acme:error:badNonce". An error response with the 638 "badNonce" error type MUST include a Replay-Nonce header with a fresh 639 nonce that the server will accept in a retry of the original query 640 (and possibly in other requests, according to the server's nonce 641 scoping policy). On receiving such a response, a client SHOULD retry 642 the request using the new nonce. 644 The precise method used to generate and track nonces is up to the 645 server. For example, the server could generate a random 128-bit 646 value for each response, keep a list of issued nonces, and strike 647 nonces from this list as they are used. 649 Other than the constraint above with regard to nonces issued in 650 "badNonce" responses, ACME does not constrain how servers scope 651 nonces. Clients MAY assume that nonces have broad scope, e.g., by 652 having a single pool of nonces used for all requests. However, when 653 retrying in response to a "badNonce" error, the client MUST use the 654 nonce provided in the error response. Servers should scope nonces 655 broadly enough that retries are not needed very often. 657 6.5.1. Replay-Nonce 659 The "Replay-Nonce" header field includes a server-generated value 660 that the server can use to detect unauthorized replay in future 661 client requests. The server MUST generate the value provided in 662 Replay-Nonce in such a way that they are unique to each message, with 663 high probability, and unpredictable to anyone besides the server. 664 For instance, it is acceptable to generate Replay-Nonces randomly. 666 The value of the Replay-Nonce field MUST be an octet string encoded 667 according to the base64url encoding described in Section 2 of 668 [RFC7515]. Clients MUST ignore invalid Replay-Nonce values. The 669 ABNF [RFC5234] for the Replay-Nonce header field follows: 671 base64url = ALPHA / DIGIT / "-" / "_" 673 Replay-Nonce = 1*base64url 675 The Replay-Nonce header field SHOULD NOT be included in HTTP request 676 messages. 678 6.5.2. "nonce" (Nonce) JWS Header Parameter 680 The "nonce" header parameter provides a unique value that enables the 681 verifier of a JWS to recognize when replay has occurred. The "nonce" 682 header parameter MUST be carried in the protected header of the JWS. 684 The value of the "nonce" header parameter MUST be an octet string, 685 encoded according to the base64url encoding described in Section 2 of 686 [RFC7515]. If the value of a "nonce" header parameter is not valid 687 according to this encoding, then the verifier MUST reject the JWS as 688 malformed. 690 6.6. Rate Limits 692 Creation of resources can be rate limited by ACME servers to ensure 693 fair usage and prevent abuse. Once the rate limit is exceeded, the 694 server MUST respond with an error with the type 695 "urn:ietf:params:acme:error:rateLimited". Additionally, the server 696 SHOULD send a "Retry-After" header [RFC7231] indicating when the 697 current request may succeed again. If multiple rate limits are in 698 place, that is the time where all rate limits allow access again for 699 the current request with exactly the same parameters. 701 In addition to the human-readable "detail" field of the error 702 response, the server MAY send one or multiple link relations in the 703 "Link" header [RFC8288] pointing to documentation about the specific 704 rate limit that was hit, using the "help" link relation type. 706 6.7. Errors 708 Errors can be reported in ACME both at the HTTP layer and within 709 challenge objects as defined in Section 8. ACME servers can return 710 responses with an HTTP error response code (4XX or 5XX). For 711 example: If the client submits a request using a method not allowed 712 in this document, then the server MAY return status code 405 (Method 713 Not Allowed). 715 When the server responds with an error status, it SHOULD provide 716 additional information using a problem document [RFC7807]. To 717 facilitate automatic response to errors, this document defines the 718 following standard tokens for use in the "type" field (within the 719 ACME URN namespace "urn:ietf:params:acme:error:"): 721 +-------------------------+-----------------------------------------+ 722 | Type | Description | 723 +-------------------------+-----------------------------------------+ 724 | accountDoesNotExist | The request specified an account that | 725 | | does not exist | 726 | | | 727 | alreadyRevoked | The request specified a certificate to | 728 | | be revoked that has already been | 729 | | revoked | 730 | | | 731 | badCSR | The CSR is unacceptable (e.g., due to a | 732 | | short key) | 733 | | | 734 | badNonce | The client sent an unacceptable anti- | 735 | | replay nonce | 736 | | | 737 | badRevocationReason | The revocation reason provided is not | 738 | | allowed by the server | 739 | | | 740 | badSignatureAlgorithm | The JWS was signed with an algorithm | 741 | | the server does not support | 742 | | | 743 | caa | Certification Authority Authorization | 744 | | (CAA) records forbid the CA from | 745 | | issuing | 746 | | | 747 | compound | Specific error conditions are indicated | 748 | | in the "subproblems" array. | 749 | | | 750 | connection | The server could not connect to | 751 | | validation target | 752 | | | 753 | dns | There was a problem with a DNS query | 754 | | during identifier validation | 755 | | | 756 | externalAccountRequired | The request must include a value for | 757 | | the "externalAccountBinding" field | 758 | | | 759 | incorrectResponse | Response received didn't match the | 760 | | challenge's requirements | 761 | | | 762 | invalidContact | A contact URL for an account was | 763 | | invalid | 764 | | | 765 | malformed | The request message was malformed | 766 | | | 767 | rateLimited | The request exceeds a rate limit | 768 | | | 769 | rejectedIdentifier | The server will not issue for the | 770 | | identifier | 771 | | | 772 | serverInternal | The server experienced an internal | 773 | | error | 774 | | | 775 | tls | The server received a TLS error during | 776 | | validation | 777 | | | 778 | unauthorized | The client lacks sufficient | 779 | | authorization | 780 | | | 781 | unsupportedContact | A contact URL for an account used an | 782 | | unsupported protocol scheme | 783 | | | 784 | unsupportedIdentifier | An identifier is of an unsupported type | 785 | | | 786 | userActionRequired | Visit the "instance" URL and take | 787 | | actions specified there | 788 +-------------------------+-----------------------------------------+ 790 This list is not exhaustive. The server MAY return errors whose 791 "type" field is set to a URI other than those defined above. Servers 792 MUST NOT use the ACME URN namespace for errors not listed in the 793 appropriate IANA registry (see Section 9.6). Clients SHOULD display 794 the "detail" field of all errors. 796 In the remainder of this document, we use the tokens in the table 797 above to refer to error types, rather than the full URNs. For 798 example, an "error of type 'badCSR'" refers to an error document with 799 "type" value "urn:ietf:params:acme:error:badCSR". 801 6.7.1. Subproblems 803 Sometimes a CA may need to return multiple errors in response to a 804 request. Additionally, the CA may need to attribute errors to 805 specific identifiers. For instance, a new-order request may contain 806 multiple identifiers for which the CA cannot issue. In this 807 situation, an ACME problem document MAY contain the "subproblems" 808 field, containing a JSON array of problem documents, each of which 809 MAY contain an "identifier" field. If present, the "identifier" 810 field MUST contain an ACME identifier (Section 9.7.7). The 811 "identifier" field MUST NOT be present at the top level in ACME 812 problem documents. It can only be present in subproblems. 813 Subproblems need not all have the same type, and do not need to match 814 the top level type. 816 ACME clients may choose to use the "identifier" field of a subproblem 817 as a hint that an operation would succeed if that identifier were 818 omitted. For instance, if an order contains ten DNS identifiers, and 819 the new-order request returns a problem document with two 820 subproblems, referencing two of those identifiers, the ACME client 821 may choose to submit another order containing only the eight 822 identifiers not listed in the problem document. 824 HTTP/1.1 403 Forbidden 825 Content-Type: application/problem+json 827 { 828 "type": "urn:ietf:params:acme:error:malformed", 829 "detail": "Some of the identifiers requested were rejected", 830 "subproblems": [ 831 { 832 "type": "urn:ietf:params:acme:error:malformed", 833 "detail": "Invalid underscore in DNS name \"_example.com\"", 834 "identifier": { 835 "type": "dns", 836 "value": "_example.com" 837 } 838 }, 839 { 840 "type": "urn:ietf:params:acme:error:rejectedIdentifier", 841 "detail": "This CA will not issue for \"example.net\"", 842 "identifier": { 843 "type": "dns", 844 "value": "example.net" 845 } 846 } 847 ] 848 } 850 7. Certificate Management 852 In this section, we describe the certificate management functions 853 that ACME enables: 855 o Account Creation 857 o Ordering a Certificate 859 o Identifier Authorization 861 o Certificate Issuance 863 o Certificate Revocation 865 7.1. Resources 867 ACME is structured as a REST [REST] application with the following 868 types of resources: 870 o Account resources, representing information about an account 871 (Section 7.1.2, Section 7.3) 873 o Order resources, representing an account's requests to issue 874 certificates (Section 7.1.3) 876 o Authorization resources, representing an account's authorization 877 to act for an identifier (Section 7.1.4) 879 o Challenge resources, representing a challenge to prove control of 880 an identifier (Section 7.5, Section 8) 882 o Certificate resources, representing issued certificates 883 (Section 7.4.2) 885 o A "directory" resource (Section 7.1.1) 887 o A "newNonce" resource (Section 7.2) 889 o A "newAccount" resource (Section 7.3) 891 o A "newOrder" resource (Section 7.4) 893 o A "revokeCert" resource (Section 7.6) 895 o A "keyChange" resource (Section 7.3.5) 897 The server MUST provide "directory" and "newNonce" resources. 899 ACME uses different URLs for different management functions. Each 900 function is listed in a directory along with its corresponding URL, 901 so clients only need to be configured with the directory URL. These 902 URLs are connected by a few different link relations [RFC5988]. 904 The "up" link relation is used with challenge resources to indicate 905 the authorization resource to which a challenge belongs. It is also 906 used, with some media types, from certificate resources to indicate a 907 resource from which the client may fetch a chain of CA certificates 908 that could be used to validate the certificate in the original 909 resource. 911 The "index" link relation is present on all resources other than the 912 directory and indicates the URL of the directory. 914 The following diagram illustrates the relations between resources on 915 an ACME server. For the most part, these relations are expressed by 916 URLs provided as strings in the resources' JSON representations. 917 Lines with labels in quotes indicate HTTP link relations. 919 directory 920 | 921 +--> newNonce 922 | 923 +----------+----------+-----+-----+------------+ 924 | | | | | 925 | | | | | 926 V V V V V 927 newAccount newAuthz newOrder revokeCert keyChange 928 | | | 929 | | | 930 V | V 931 account | order --+--> finalize 932 | | | 933 | | +--> cert 934 | V 935 +---> authorization 936 | ^ 937 | | "up" 938 V | 939 challenge 941 ACME Resources and Relationships 943 The following table illustrates a typical sequence of requests 944 required to establish a new account with the server, prove control of 945 an identifier, issue a certificate, and fetch an updated certificate 946 some time after issuance. The "->" is a mnemonic for a Location 947 header pointing to a created resource. 949 +-------------------+--------------------------------+--------------+ 950 | Action | Request | Response | 951 +-------------------+--------------------------------+--------------+ 952 | Get directory | GET directory | 200 | 953 | | | | 954 | Get nonce | HEAD newNonce | 200 | 955 | | | | 956 | Create account | POST newAccount | 201 -> | 957 | | | account | 958 | | | | 959 | Submit order | POST newOrder | 201 -> order | 960 | | | | 961 | Fetch challenges | POST-as-GET order's | 200 | 962 | | authorization urls | | 963 | | | | 964 | Respond to | POST authorization challenge | 200 | 965 | challenges | urls | | 966 | | | | 967 | Poll for status | POST-as-GET order | 200 | 968 | | | | 969 | Finalize order | POST order's finalize url | 200 | 970 | | | | 971 | Poll for status | POST-as-GET order | 200 | 972 | | | | 973 | Download | POST-as-GET order's | 200 | 974 | certificate | certificate url | | 975 +-------------------+--------------------------------+--------------+ 977 The remainder of this section provides the details of how these 978 resources are structured and how the ACME protocol makes use of them. 980 7.1.1. Directory 982 In order to help clients configure themselves with the right URLs for 983 each ACME operation, ACME servers provide a directory object. This 984 should be the only URL needed to configure clients. It is a JSON 985 object, whose field names are drawn from the resource registry 986 (Section 9.7.5) and whose values are the corresponding URLs. 988 +------------+--------------------+ 989 | Field | URL in value | 990 +------------+--------------------+ 991 | newNonce | New nonce | 992 | | | 993 | newAccount | New account | 994 | | | 995 | newOrder | New order | 996 | | | 997 | newAuthz | New authorization | 998 | | | 999 | revokeCert | Revoke certificate | 1000 | | | 1001 | keyChange | Key Change | 1002 +------------+--------------------+ 1004 There is no constraint on the URL of the directory except that it 1005 should be different from the other ACME server resources' URLs, and 1006 that it should not clash with other services. For instance: 1008 o a host which functions as both an ACME and a Web server may want 1009 to keep the root path "/" for an HTML "front page", and place the 1010 ACME directory under the path "/acme". 1012 o a host which only functions as an ACME server could place the 1013 directory under the path "/". 1015 If the ACME server does not implement pre-authorization 1016 (Section 7.4.1) it MUST omit the "newAuthz" field of the directory. 1018 The object MAY additionally contain a field "meta". If present, it 1019 MUST be a JSON object; each field in the object is an item of 1020 metadata relating to the service provided by the ACME server. 1022 The following metadata items are defined (Section 9.7.6), all of 1023 which are OPTIONAL: 1025 termsOfService (optional, string): A URL identifying the current 1026 terms of service. 1028 website (optional, string): An HTTP or HTTPS URL locating a website 1029 providing more information about the ACME server. 1031 caaIdentities (optional, array of string): The hostnames that the 1032 ACME server recognizes as referring to itself for the purposes of 1033 CAA record validation as defined in [RFC6844]. Each string MUST 1034 represent the same sequence of ASCII code points that the server 1035 will expect to see as the "Issuer Domain Name" in a CAA issue or 1036 issuewild property tag. This allows clients to determine the 1037 correct issuer domain name to use when configuring CAA records. 1039 externalAccountRequired (optional, boolean): If this field is 1040 present and set to "true", then the CA requires that all new- 1041 account requests include an "externalAccountBinding" field 1042 associating the new account with an external account. 1044 Clients access the directory by sending a GET request to the 1045 directory URL. 1047 HTTP/1.1 200 OK 1048 Content-Type: application/json 1050 { 1051 "newNonce": "https://example.com/acme/new-nonce", 1052 "newAccount": "https://example.com/acme/new-account", 1053 "newOrder": "https://example.com/acme/new-order", 1054 "newAuthz": "https://example.com/acme/new-authz", 1055 "revokeCert": "https://example.com/acme/revoke-cert", 1056 "keyChange": "https://example.com/acme/key-change", 1057 "meta": { 1058 "termsOfService": "https://example.com/acme/terms/2017-5-30", 1059 "website": "https://www.example.com/", 1060 "caaIdentities": ["example.com"], 1061 "externalAccountRequired": false 1062 } 1063 } 1065 7.1.2. Account Objects 1067 An ACME account resource represents a set of metadata associated with 1068 an account. Account resources have the following structure: 1070 status (required, string): The status of this account. Possible 1071 values are: "valid", "deactivated", and "revoked". The value 1072 "deactivated" should be used to indicate client-initiated 1073 deactivation whereas "revoked" should be used to indicate server- 1074 initiated deactivation. (See Section 7.1.6) 1076 contact (optional, array of string): An array of URLs that the 1077 server can use to contact the client for issues related to this 1078 account. For example, the server may wish to notify the client 1079 about server-initiated revocation or certificate expiration. For 1080 information on supported URL schemes, see Section 7.3 1082 termsOfServiceAgreed (optional, boolean): Including this field in a 1083 new-account request, with a value of true, indicates the client's 1084 agreement with the terms of service. This field is not updateable 1085 by the client. 1087 orders (required, string): A URL from which a list of orders 1088 submitted by this account can be fetched via a POST-as-GET 1089 request, as described in Section 7.1.2.1. 1091 { 1092 "status": "valid", 1093 "contact": [ 1094 "mailto:cert-admin@example.com", 1095 "mailto:admin@example.com" 1096 ], 1097 "termsOfServiceAgreed": true, 1098 "orders": "https://example.com/acme/acct/evOfKhNU60wg/orders" 1099 } 1101 7.1.2.1. Orders List 1103 Each account object includes an "orders" URL from which a list of 1104 orders created by the account can be fetched via POST-as-GET request. 1105 The result of the request MUST be a JSON object whose "orders" field 1106 is an array of URLs, each identifying an order belonging to the 1107 account. The server SHOULD include pending orders, and SHOULD NOT 1108 include orders that are invalid in the array of URLs. The server MAY 1109 return an incomplete list, along with a Link header field with a 1110 "next" link relation indicating where further entries can be 1111 acquired. 1113 HTTP/1.1 200 OK 1114 Content-Type: application/json 1115 Link: ;rel="next" 1117 { 1118 "orders": [ 1119 "https://example.com/acme/order/TOlocE8rfgo", 1120 "https://example.com/acme/order/4E16bbL5iSw", 1121 /* more URLs not shown for example brevity */ 1122 "https://example.com/acme/order/neBHYLfw0mg" 1123 ] 1124 } 1126 7.1.3. Order Objects 1128 An ACME order object represents a client's request for a certificate 1129 and is used to track the progress of that order through to issuance. 1130 Thus, the object contains information about the requested 1131 certificate, the authorizations that the server requires the client 1132 to complete, and any certificates that have resulted from this order. 1134 status (required, string): The status of this order. Possible 1135 values are: "pending", "ready", "processing", "valid", and 1136 "invalid". (See Section 7.1.6) 1138 expires (optional, string): The timestamp after which the server 1139 will consider this order invalid, encoded in the format specified 1140 in RFC 3339 [RFC3339]. This field is REQUIRED for objects with 1141 "pending" or "valid" in the status field. 1143 identifiers (required, array of object): An array of identifier 1144 objects that the order pertains to. 1146 type (required, string): The type of identifier. This document 1147 defines the "dns" identifier type. See the registry defined in 1148 Section 9.7.7 for any others. 1150 value (required, string): The identifier itself. 1152 notBefore (optional, string): The requested value of the notBefore 1153 field in the certificate, in the date format defined in [RFC3339]. 1155 notAfter (optional, string): The requested value of the notAfter 1156 field in the certificate, in the date format defined in [RFC3339]. 1158 error (optional, object): The error that occurred while processing 1159 the order, if any. This field is structured as a problem document 1160 [RFC7807]. 1162 authorizations (required, array of string): For pending orders, the 1163 authorizations that the client needs to complete before the 1164 requested certificate can be issued (see Section 7.5), including 1165 unexpired authorizations that the client has completed in the past 1166 for identifiers specified in the order. The authorizations 1167 required are dictated by server policy and there may not be a 1:1 1168 relationship between the order identifiers and the authorizations 1169 required. For final orders (in the "valid" or "invalid" state), 1170 the authorizations that were completed. Each entry is a URL from 1171 which an authorization can be fetched with a POST-as-GET request. 1173 finalize (required, string): A URL that a CSR must be POSTed to once 1174 all of the order's authorizations are satisfied to finalize the 1175 order. The result of a successful finalization will be the 1176 population of the certificate URL for the order. 1178 certificate (optional, string): A URL for the certificate that has 1179 been issued in response to this order. 1181 { 1182 "status": "valid", 1183 "expires": "2015-03-01T14:09:07.99Z", 1185 "identifiers": [ 1186 { "type": "dns", "value": "example.com" }, 1187 { "type": "dns", "value": "www.example.com" } 1188 ], 1190 "notBefore": "2016-01-01T00:00:00Z", 1191 "notAfter": "2016-01-08T00:00:00Z", 1193 "authorizations": [ 1194 "https://example.com/acme/authz/PAniVnsZcis", 1195 "https://example.com/acme/authz/r4HqLzrSrpI" 1196 ], 1198 "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize", 1200 "certificate": "https://example.com/acme/cert/jWCdfHVGY2M" 1201 } 1203 Any identifier of type "dns" in a new-order request MAY have a 1204 wildcard domain name as its value. A wildcard domain name consists 1205 of a single asterisk character followed by a single full stop 1206 character ("*.") followed by a domain name as defined for use in the 1207 Subject Alternate Name Extension by RFC 5280 [RFC5280]. An 1208 authorization returned by the server for a wildcard domain name 1209 identifier MUST NOT include the asterisk and full stop ("*.") prefix 1210 in the authorization identifier value. The returned authorization 1211 MUST include the optional "wildcard" field, with a value of true. 1213 The elements of the "authorizations" and "identifiers" array are 1214 immutable once set. The server MUST NOT change the contents of 1215 either array after they are created. If a client observes a change 1216 in the contents of either array, then it SHOULD consider the order 1217 invalid. 1219 The "authorizations" array of the order SHOULD reflect all 1220 authorizations that the CA takes into account in deciding to issue, 1221 even if some authorizations were fulfilled in earlier orders or in 1222 pre-authorization transactions. For example, if a CA allows multiple 1223 orders to be fulfilled based on a single authorization transaction, 1224 then it SHOULD reflect that authorization in all of the orders. 1226 Note that just because an authorization URL is listed in the 1227 "authorizations" array of an order object doesn't mean that the 1228 client is required to take action. There are several reasons that 1229 the referenced authorizations may already be valid: 1231 o The client completed the authorization as part of a previous order 1233 o The client previously pre-authorized the identifier (see 1234 Section 7.4.1) 1236 o The server granted the client authorization based on an external 1237 account 1239 Clients SHOULD check the "status" field of an order to determine 1240 whether they need to take any action. 1242 7.1.4. Authorization Objects 1244 An ACME authorization object represents a server's authorization for 1245 an account to represent an identifier. In addition to the 1246 identifier, an authorization includes several metadata fields, such 1247 as the status of the authorization (e.g., "pending", "valid", or 1248 "revoked") and which challenges were used to validate possession of 1249 the identifier. 1251 The structure of an ACME authorization resource is as follows: 1253 identifier (required, object): The identifier that the account is 1254 authorized to represent 1256 type (required, string): The type of identifier. (See below and 1257 Section 9.7.7) 1259 value (required, string): The identifier itself. 1261 status (required, string): The status of this authorization. 1262 Possible values are: "pending", "valid", "invalid", "deactivated", 1263 "expired", and "revoked". (See Section 7.1.6) 1265 expires (optional, string): The timestamp after which the server 1266 will consider this authorization invalid, encoded in the format 1267 specified in RFC 3339 [RFC3339]. This field is REQUIRED for 1268 objects with "valid" in the "status" field. 1270 challenges (required, array of objects): For pending authorizations, 1271 the challenges that the client can fulfill in order to prove 1272 possession of the identifier. For valid authorizations, the 1273 challenge that was validated. For invalid authorizations, the 1274 challenge that was attempted and failed. Each array entry is an 1275 object with parameters required to validate the challenge. A 1276 client should attempt to fulfill one of these challenges, and a 1277 server should consider any one of the challenges sufficient to 1278 make the authorization valid. 1280 wildcard (optional, boolean): For authorizations created as a result 1281 of a newOrder request containing a DNS identifier with a value 1282 that contained a wildcard prefix this field MUST be present, and 1283 true. 1285 The only type of identifier defined by this specification is a fully- 1286 qualified domain name (type: "dns"). The domain name MUST be encoded 1287 in the form in which it would appear in a certificate. That is, it 1288 MUST be encoded according to the rules in Section 7 of [RFC5280]. 1289 Servers MUST verify any identifier values that begin with the ASCII 1290 Compatible Encoding prefix "xn--" as defined in [RFC5890] are 1291 properly encoded. Wildcard domain names (with "*" as the first 1292 label) MUST NOT be included in authorization objects. If an 1293 authorization object conveys authorization for the base domain of a 1294 newOrder DNS type identifier with a wildcard prefix then the optional 1295 authorizations "wildcard" field MUST be present with a value of true. 1297 Section 8 describes a set of challenges for domain name validation. 1299 { 1300 "status": "valid", 1301 "expires": "2015-03-01T14:09:07.99Z", 1303 "identifier": { 1304 "type": "dns", 1305 "value": "example.org" 1306 }, 1308 "challenges": [ 1309 { 1310 "url": "https://example.com/acme/chall/prV_B7yEyA4", 1311 "type": "http-01", 1312 "status": "valid", 1313 "token": "DGyRejmCefe7v4NfDGDKfA", 1314 "validated": "2014-12-01T12:05:58.16Z" 1315 } 1316 ], 1318 "wildcard": false 1319 } 1321 7.1.5. Challenge Objects 1323 An ACME challenge object represents a server's offer to validate a 1324 client's possession of an identifier in a specific way. Unlike the 1325 other objects listed above, there is not a single standard structure 1326 for a challenge object. The contents of a challenge object depend on 1327 the validation method being used. The general structure of challenge 1328 objects and an initial set of validation methods are described in 1329 Section 8. 1331 7.1.6. Status Changes 1333 Each ACME object type goes through a simple state machine over its 1334 lifetime. The "status" field of the object indicates which state the 1335 object is currently in. 1337 Challenge objects are created in the "pending" state. They 1338 transition to the "processing" state when the client responds to the 1339 challenge (see Section 7.5.1) and the server begins attempting to 1340 validate that the client has completed the challenge. Note that 1341 within the "processing" state, the server may attempt to validate the 1342 challenge multiple times (see Section 8.2). Likewise, client 1343 requests for retries do not cause a state change. If validation is 1344 successful, the challenge moves to the "valid" state; if there is an 1345 error, the challenge moves to the "invalid" state. 1347 pending 1348 | 1349 | Receive 1350 | response 1351 V 1352 processing <-+ 1353 | | | Server retry or 1354 | | | client retry request 1355 | +----+ 1356 | 1357 | 1358 Successful | Failed 1359 validation | validation 1360 +---------+---------+ 1361 | | 1362 V V 1363 valid invalid 1365 State Transitions for Challenge Objects 1367 Authorization objects are created in the "pending" state. If one of 1368 the challenges listed in the authorization transitions to the "valid" 1369 state, then the authorization also changes to the "valid" state. If 1370 the client attempts to fulfill a challenge and fails, or if there is 1371 an error while the authorization is still pending, then the 1372 authorization transitions to the "invalid" state. Once the 1373 authorization is in the valid state, it can expire ("expired"), be 1374 deactivated by the client ("deactivated", see Section 7.5.2), or 1375 revoked by the server ("revoked"). 1377 pending --------------------+ 1378 | | 1379 Challenge failure | | 1380 or | | 1381 Error | Challenge valid | 1382 +---------+---------+ | 1383 | | | 1384 V V | 1385 invalid valid | 1386 | | 1387 | | 1388 | | 1389 +--------------+--------------+ 1390 | | | 1391 | | | 1392 Server | Client | Time after | 1393 revoke | deactivate | "expires" | 1394 V V V 1395 revoked deactivated expired 1397 State Transitions for Authorization Objects 1399 Order objects are created in the "pending" state. Once all of the 1400 authorizations listed in the order object are in the "valid" state, 1401 the order transitions to the "ready" state. The order moves to the 1402 "processing" state after the client submits a request to the order's 1403 "finalize" URL and the CA begins the issuance process for the 1404 certificate. Once the certificate is issued, the order enters the 1405 "valid" state. If an error occurs at any of these stages, the order 1406 moves to the "invalid" state. The order also moves to the "invalid" 1407 state if it expires, or one of its authorizations enters a final 1408 state other than "valid" ("expired", "revoked", "deactivated"). 1410 pending --------------+ 1411 | | 1412 | All authz | 1413 | "valid" | 1414 V | 1415 ready ---------------+ 1416 | | 1417 | Receive | 1418 | finalize | 1419 | request | 1420 V | 1421 processing ------------+ 1422 | | 1423 | Certificate | Error or 1424 | issued | Authorization failure 1425 V V 1426 valid invalid 1428 State Transitions for Order Objects 1430 Account objects are created in the "valid" state, since no further 1431 action is required to create an account after a successful newAccount 1432 request. If the account is deactivated by the client or revoked by 1433 the server, it moves to the corresponding state. 1435 valid 1436 | 1437 | 1438 +-----------+-----------+ 1439 Client | Server | 1440 deactiv.| revoke | 1441 V V 1442 deactivated revoked 1444 State Transitions for Account Objects 1446 Note that some of these states may not ever appear in a "status" 1447 field, depending on server behavior. For example, a server that 1448 issues synchronously will never show an order in the "processing" 1449 state. A server that deletes expired authorizations immediately will 1450 never show an authorization in the "expired" state. 1452 7.2. Getting a Nonce 1454 Before sending a POST request to the server, an ACME client needs to 1455 have a fresh anti-replay nonce to put in the "nonce" header of the 1456 JWS. In most cases, the client will have gotten a nonce from a 1457 previous request. However, the client might sometimes need to get a 1458 new nonce, e.g., on its first request to the server or if an existing 1459 nonce is no longer valid. 1461 To get a fresh nonce, the client sends a HEAD request to the new- 1462 nonce resource on the server. The server's response MUST include a 1463 Replay-Nonce header field containing a fresh nonce, and SHOULD have 1464 status code 200 (OK). The server MUST also respond to GET requests 1465 for this resource, returning an empty body (while still providing a 1466 Replay-Nonce header) with a 204 (No Content) status. 1468 HEAD /acme/new-nonce HTTP/1.1 1469 Host: example.com 1471 HTTP/1.1 200 OK 1472 Replay-Nonce: oFvnlFP1wIhRlYS2jTaXbA 1473 Cache-Control: no-store 1475 Proxy caching of responses from the new-nonce resource can cause 1476 clients receive the same nonce repeatedly, leading to badNonce 1477 errors. The server MUST include a Cache-Control header field with 1478 the "no-store" directive in responses for the new-nonce resource, in 1479 order to prevent caching of this resource. 1481 7.3. Account Management 1483 In this section, we describe how an ACME client can create an account 1484 on an ACME server, and perform some modifications to the account 1485 after it has been created. 1487 A client creates a new account with the server by sending a POST 1488 request to the server's new-account URL. The body of the request is 1489 a stub account object containing some subset of the following fields: 1491 contact (optional, array of string): Same meaning as the 1492 corresponding server field defined in Section 7.1.2 1494 termsOfServiceAgreed (optional, boolean): Same meaning as the 1495 corresponding server field defined in Section 7.1.2 1497 onlyReturnExisting (optional, boolean): If this field is present 1498 with the value "true", then the server MUST NOT create a new 1499 account if one does not already exist. This allows a client to 1500 look up an account URL based on an account key (see 1501 Section 7.3.1). 1503 externalAccountBinding (optional, object): An optional field for 1504 binding the new account with an existing non-ACME account (see 1505 Section 7.3.4). 1507 POST /acme/new-account HTTP/1.1 1508 Host: example.com 1509 Content-Type: application/jose+json 1511 { 1512 "protected": base64url({ 1513 "alg": "ES256", 1514 "jwk": {...}, 1515 "nonce": "6S8IqOGY7eL2lsGoTZYifg", 1516 "url": "https://example.com/acme/new-account" 1517 }), 1518 "payload": base64url({ 1519 "termsOfServiceAgreed": true, 1520 "contact": [ 1521 "mailto:cert-admin@example.com", 1522 "mailto:admin@example.com" 1523 ] 1524 }), 1525 "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I" 1526 } 1528 The server MUST ignore any values provided in the "orders" fields in 1529 account bodies sent by the client, as well as any other fields that 1530 it does not recognize. If new fields are specified in the future, 1531 the specification of those fields MUST describe whether they can be 1532 provided by the client. 1534 In general, the server MUST ignore any fields in the request object 1535 that it does not recognize. In particular, it MUST NOT reflect 1536 unrecognized fields in the resulting account object. This allows 1537 clients to detect when servers do not support an extension field. 1539 The server SHOULD validate that the contact URLs in the "contact" 1540 field are valid and supported by the server. If the server validates 1541 contact URLs it MUST support the "mailto" scheme. Clients MUST NOT 1542 provide a "mailto" URL in the "contact" field that contains "hfields" 1543 [RFC6068], or more than one "addr-spec" in the "to" component. If a 1544 server encounters a "mailto" contact URL that does not meet these 1545 criteria, then it SHOULD reject it as invalid. 1547 If the server rejects a contact URL for using an unsupported scheme 1548 it MUST return an error of type "unsupportedContact", with a 1549 description describing the error and what types of contact URLs the 1550 server considers acceptable. If the server rejects a contact URL for 1551 using a supported scheme but an invalid value then the server MUST 1552 return an error of type "invalidContact". 1554 If the server wishes to require the client to agree to terms under 1555 which the ACME service is to be used, it MUST indicate the URL where 1556 such terms can be accessed in the "termsOfService" subfield of the 1557 "meta" field in the directory object, and the server MUST reject new- 1558 account requests that do not have the "termsOfServiceAgreed" field 1559 set to "true". Clients SHOULD NOT automatically agree to terms by 1560 default. Rather, they SHOULD require some user interaction for 1561 agreement to terms. 1563 The server creates an account and stores the public key used to 1564 verify the JWS (i.e., the "jwk" element of the JWS header) to 1565 authenticate future requests from the account. The server returns 1566 this account object in a 201 (Created) response, with the account URL 1567 in a Location header field. The account URL is used as the "kid" 1568 value in the JWS authenticating subsequent requests by this account 1569 (see Section 6.2). The account URL is also used for requests for 1570 management actions on this account, as described below. 1572 HTTP/1.1 201 Created 1573 Content-Type: application/json 1574 Replay-Nonce: D8s4D2mLs8Vn-goWuPQeKA 1575 Location: https://example.com/acme/acct/evOfKhNU60wg 1576 Link: ;rel="index" 1578 { 1579 "status": "valid", 1581 "contact": [ 1582 "mailto:cert-admin@example.com", 1583 "mailto:admin@example.com" 1584 ], 1586 "orders": "https://example.com/acme/acct/evOfKhNU60wg/orders" 1587 } 1589 7.3.1. Finding an Account URL Given a Key 1591 If the server receives a newAccount request signed with a key for 1592 which it already has an account registered with the provided account 1593 key, then it MUST return a response with a 200 (OK) status code and 1594 provide the URL of that account in the Location header field. The 1595 body of this response represents the account object as it existed on 1596 the server before this request; any fields in the request object MUST 1597 be ignored. This allows a client that has an account key but not the 1598 corresponding account URL to recover the account URL. 1600 If a client wishes to find the URL for an existing account and does 1601 not want an account to be created if one does not already exist, then 1602 it SHOULD do so by sending a POST request to the new-account URL with 1603 a JWS whose payload has an "onlyReturnExisting" field set to "true" 1604 ({"onlyReturnExisting": true}). If a client sends such a request and 1605 an account does not exist, then the server MUST return an error 1606 response with status code 400 (Bad Request) and type 1607 "urn:ietf:params:acme:error:accountDoesNotExist". 1609 7.3.2. Account Update 1611 If the client wishes to update this information in the future, it 1612 sends a POST request with updated information to the account URL. 1613 The server MUST ignore any updates to the "orders" field, 1614 "termsOfServiceAgreed" field (see Section 7.3.3), the "status" field 1615 (except as allowed by Section 7.3.6), or any other fields it does not 1616 recognize. If the server accepts the update, it MUST return a 1617 response with a 200 (OK) status code and the resulting account 1618 object. 1620 For example, to update the contact information in the above account, 1621 the client could send the following request: 1623 POST /acme/acct/evOfKhNU60wg HTTP/1.1 1624 Host: example.com 1625 Content-Type: application/jose+json 1627 { 1628 "protected": base64url({ 1629 "alg": "ES256", 1630 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 1631 "nonce": "ax5RnthDqp_Yf4_HZnFLmA", 1632 "url": "https://example.com/acme/acct/evOfKhNU60wg" 1633 }), 1634 "payload": base64url({ 1635 "contact": [ 1636 "mailto:certificates@example.com", 1637 "mailto:admin@example.com" 1638 ] 1639 }), 1640 "signature": "hDXzvcj8T6fbFbmn...rDzXzzvzpRy64N0o" 1641 } 1643 7.3.3. Changes of Terms of Service 1645 As described above, a client can indicate its agreement with the CA's 1646 terms of service by setting the "termsOfServiceAgreed" field in its 1647 account object to "true". 1649 If the server has changed its terms of service since a client 1650 initially agreed, and the server is unwilling to process a request 1651 without explicit agreement to the new terms, then it MUST return an 1652 error response with status code 403 (Forbidden) and type 1653 "urn:ietf:params:acme:error:userActionRequired". This response MUST 1654 include a Link header field with link relation "terms-of-service" and 1655 the latest terms-of-service URL. 1657 The problem document returned with the error MUST also include an 1658 "instance" field, indicating a URL that the client should direct a 1659 human user to visit in order for instructions on how to agree to the 1660 terms. 1662 HTTP/1.1 403 Forbidden 1663 Replay-Nonce: T81bdZroZ2ITWSondpTmAw 1664 Link: ;rel="terms-of-service" 1665 Content-Type: application/problem+json 1666 Content-Language: en 1668 { 1669 "type": "urn:ietf:params:acme:error:userActionRequired", 1670 "detail": "Terms of service have changed", 1671 "instance": "https://example.com/acme/agreement/?token=W8Ih3PswD-8" 1672 } 1674 7.3.4. External Account Binding 1676 The server MAY require a value for the "externalAccountBinding" field 1677 to be present in "newAccount" requests. This can be used to 1678 associate an ACME account with an existing account in a non-ACME 1679 system, such as a CA customer database. 1681 To enable ACME account binding, the CA operating the ACME server 1682 needs to provide the ACME client with a MAC key and a key identifier, 1683 using some mechanism outside of ACME. The key identifier MUST be an 1684 ASCII string. The MAC key SHOULD be provided in base64url-encoded 1685 form, to maximize compatibility between non-ACME provisioning systems 1686 and ACME clients. 1688 The ACME client then computes a binding JWS to indicate the external 1689 account holder's approval of the ACME account key. The payload of 1690 this JWS is the ACME account key being registered, in JWK form. The 1691 protected header of the JWS MUST meet the following criteria: 1693 o The "alg" field MUST indicate a MAC-based algorithm 1695 o The "kid" field MUST contain the key identifier provided by the CA 1696 o The "nonce" field MUST NOT be present 1698 o The "url" field MUST be set to the same value as the outer JWS 1700 The "signature" field of the JWS will contain the MAC value computed 1701 with the MAC key provided by the CA. 1703 POST /acme/new-account HTTP/1.1 1704 Host: example.com 1705 Content-Type: application/jose+json 1707 { 1708 "protected": base64url({ 1709 "alg": "ES256", 1710 "jwk": /* account key */, 1711 "nonce": "K60BWPrMQG9SDxBDS_xtSw", 1712 "url": "https://example.com/acme/new-account" 1713 }), 1714 "payload": base64url({ 1715 "contact": ["mailto:example@anonymous.invalid"], 1716 "termsOfServiceAgreed": true, 1718 "externalAccountBinding": { 1719 "protected": base64url({ 1720 "alg": "HS256", 1721 "kid": /* key identifier from CA */, 1722 "url": "https://example.com/acme/new-account" 1723 }), 1724 "payload": base64url(/* same as in "jwk" above */), 1725 "signature": /* MAC using MAC key from CA */ 1726 } 1727 }), 1728 "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4" 1729 } 1731 If such a CA requires that new-account requests contain an 1732 "externalAccountBinding" field, then it MUST provide the value "true" 1733 in the "externalAccountRequired" subfield of the "meta" field in the 1734 directory object. If the CA receives a new-account request without 1735 an "externalAccountBinding" field, then it SHOULD reply with an error 1736 of type "externalAccountRequired". 1738 When a CA receives a new-account request containing an 1739 "externalAccountBinding" field, it decides whether or not to verify 1740 the binding. If the CA does not verify the binding, then it MUST NOT 1741 reflect the "externalAccountBinding" field in the resulting account 1742 object (if any). To verify the account binding, the CA MUST take the 1743 following steps: 1745 1. Verify that the value of the field is a well-formed JWS 1747 2. Verify that the JWS protected field meets the above criteria 1749 3. Retrieve the MAC key corresponding to the key identifier in the 1750 "kid" field 1752 4. Verify that the MAC on the JWS verifies using that MAC key 1754 5. Verify that the payload of the JWS represents the same key as was 1755 used to verify the outer JWS (i.e., the "jwk" field of the outer 1756 JWS) 1758 If all of these checks pass and the CA creates a new account, then 1759 the CA may consider the new account associated with the external 1760 account corresponding to the MAC key. The account object the CA 1761 returns MUST include an "externalAccountBinding" field with the same 1762 value as the field in the request. If any of these checks fail, then 1763 the CA MUST reject the new-account request. 1765 7.3.5. Account Key Roll-over 1767 A client may wish to change the public key that is associated with an 1768 account in order to recover from a key compromise or proactively 1769 mitigate the impact of an unnoticed key compromise. 1771 To change the key associated with an account, the client sends a 1772 request to the server containing signatures by both the old and new 1773 keys. The signature by the new key covers the account URL and the 1774 old key, signifying a request by the new key holder to take over the 1775 account from the old key holder. The signature by the old key covers 1776 this request and its signature, and indicates the old key holder's 1777 assent to the roll-over request. 1779 To create this request object, the client first constructs a key- 1780 change object describing the account to be updated and its account 1781 key: 1783 account (required, string): The URL for the account being modified. 1784 The content of this field MUST be the exact string provided in the 1785 Location header field in response to the new-account request that 1786 created the account. 1788 oldKey (required, JWK): The JWK representation of the old key 1790 The client then encapsulates the key-change object in an "inner" JWS, 1791 signed with the requested new account key. This "inner" JWS becomes 1792 the payload for the "outer" JWS that is the body of the ACME request. 1794 The outer JWS MUST meet the normal requirements for an ACME JWS (see 1795 Section 6.2). The inner JWS MUST meet the normal requirements, with 1796 the following differences: 1798 o The inner JWS MUST have a "jwk" header parameter, containing the 1799 public key of the new key pair. 1801 o The inner JWS MUST have the same "url" header parameter as the 1802 outer JWS. 1804 o The inner JWS MUST omit the "nonce" header parameter. 1806 This transaction has signatures from both the old and new keys so 1807 that the server can verify that the holders of the two keys both 1808 agree to the change. The signatures are nested to preserve the 1809 property that all signatures on POST messages are signed by exactly 1810 one key. The "inner" JWS effectively represents a request by the 1811 holder of the new key to take over the account form the holder of the 1812 old key. The "outer" JWS represents the current account holder's 1813 assent to this request. 1815 POST /acme/key-change HTTP/1.1 1816 Host: example.com 1817 Content-Type: application/jose+json 1819 { 1820 "protected": base64url({ 1821 "alg": "ES256", 1822 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 1823 "nonce": "S9XaOcxP5McpnTcWPIhYuB", 1824 "url": "https://example.com/acme/key-change" 1825 }), 1826 "payload": base64url({ 1827 "protected": base64url({ 1828 "alg": "ES256", 1829 "jwk": /* new key */, 1830 "url": "https://example.com/acme/key-change" 1831 }), 1832 "payload": base64url({ 1833 "account": "https://example.com/acme/acct/evOfKhNU60wg", 1834 "oldKey": /* old key */ 1835 }), 1836 "signature": "Xe8B94RD30Azj2ea...8BmZIRtcSKPSd8gU" 1837 }), 1838 "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4" 1839 } 1840 On receiving key-change request, the server MUST perform the 1841 following steps in addition to the typical JWS validation: 1843 1. Validate the POST request belongs to a currently active account, 1844 as described in Section 6. 1846 2. Check that the payload of the JWS is a well-formed JWS object 1847 (the "inner JWS"). 1849 3. Check that the JWS protected header of the inner JWS has a "jwk" 1850 field. 1852 4. Check that the inner JWS verifies using the key in its "jwk" 1853 field. 1855 5. Check that the payload of the inner JWS is a well-formed key- 1856 change object (as described above). 1858 6. Check that the "url" parameters of the inner and outer JWSs are 1859 the same. 1861 7. Check that the "account" field of the key-change object contains 1862 the URL for the account matching the old key (i.e., the "kid" 1863 field in the outer JWS). 1865 8. Check that the "oldKey" field of the key-change object is the 1866 same as the account key for the account in question. 1868 9. Check that no account exists whose account key is the same as the 1869 key in the "jwk" header parameter of the inner JWS. 1871 If all of these checks pass, then the server updates the 1872 corresponding account by replacing the old account key with the new 1873 public key and returns status code 200 (OK). Otherwise, the server 1874 responds with an error status code and a problem document describing 1875 the error. If there is an existing account with the new key 1876 provided, then the server SHOULD use status code 409 (Conflict) and 1877 provide the URL of that account in the Location header field. 1879 Note that changing the account key for an account SHOULD NOT have any 1880 other impact on the account. For example, the server MUST NOT 1881 invalidate pending orders or authorization transactions based on a 1882 change of account key. 1884 7.3.6. Account Deactivation 1886 A client can deactivate an account by posting a signed update to the 1887 account URL with a status field of "deactivated." Clients may wish 1888 to do this when the account key is compromised or decommissioned. A 1889 deactivated account can no longer request certificate issuance or 1890 access resources related to the account, such as orders or 1891 authorizations. If a server receives a POST or POST-as-GET from a 1892 deactivated account, it MUST return an error response with status 1893 code 401 (Unauthorized) and type 1894 "urn:ietf:params:acme:error:unauthorized". 1896 POST /acme/acct/evOfKhNU60wg HTTP/1.1 1897 Host: example.com 1898 Content-Type: application/jose+json 1900 { 1901 "protected": base64url({ 1902 "alg": "ES256", 1903 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 1904 "nonce": "ntuJWWSic4WVNSqeUmshgg", 1905 "url": "https://example.com/acme/acct/evOfKhNU60wg" 1906 }), 1907 "payload": base64url({ 1908 "status": "deactivated" 1909 }), 1910 "signature": "earzVLd3m5M4xJzR...bVTqn7R08AKOVf3Y" 1911 } 1913 The server MUST verify that the request is signed by the account key. 1914 If the server accepts the deactivation request, it replies with a 200 1915 (OK) status code and the current contents of the account object. 1917 Once an account is deactivated, the server MUST NOT accept further 1918 requests authorized by that account's key. The server SHOULD cancel 1919 any pending operations authorized by the account's key, such as 1920 certificate orders. A server may take a variety of actions in 1921 response to an account deactivation, e.g., deleting data related to 1922 that account or sending mail to the account's contacts. Servers 1923 SHOULD NOT revoke certificates issued by the deactivated account, 1924 since this could cause operational disruption for servers using these 1925 certificates. ACME does not provide a way to reactivate a 1926 deactivated account. 1928 7.4. Applying for Certificate Issuance 1930 The client begins the certificate issuance process by sending a POST 1931 request to the server's new-order resource. The body of the POST is 1932 a JWS object whose JSON payload is a subset of the order object 1933 defined in Section 7.1.3, containing the fields that describe the 1934 certificate to be issued: 1936 identifiers (required, array of object): An array of identifier 1937 objects that the client wishes to submit an order for. 1939 type (required, string): The type of identifier. 1941 value (required, string): The identifier itself. 1943 notBefore (optional, string): The requested value of the notBefore 1944 field in the certificate, in the date format defined in [RFC3339]. 1946 notAfter (optional, string): The requested value of the notAfter 1947 field in the certificate, in the date format defined in [RFC3339]. 1949 POST /acme/new-order HTTP/1.1 1950 Host: example.com 1951 Content-Type: application/jose+json 1953 { 1954 "protected": base64url({ 1955 "alg": "ES256", 1956 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 1957 "nonce": "5XJ1L3lEkMG7tR6pA00clA", 1958 "url": "https://example.com/acme/new-order" 1959 }), 1960 "payload": base64url({ 1961 "identifiers": [ 1962 { "type": "dns", "value": "example.com" } 1963 ], 1964 "notBefore": "2016-01-01T00:04:00+04:00", 1965 "notAfter": "2016-01-08T00:04:00+04:00" 1966 }), 1967 "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g" 1968 } 1970 The server MUST return an error if it cannot fulfill the request as 1971 specified, and MUST NOT issue a certificate with contents other than 1972 those requested. If the server requires the request to be modified 1973 in a certain way, it should indicate the required changes using an 1974 appropriate error type and description. 1976 If the server is willing to issue the requested certificate, it 1977 responds with a 201 (Created) response. The body of this response is 1978 an order object reflecting the client's request and any 1979 authorizations the client must complete before the certificate will 1980 be issued. 1982 HTTP/1.1 201 Created 1983 Replay-Nonce: MYAuvOpaoIiywTezizk5vw 1984 Location: https://example.com/acme/order/TOlocE8rfgo 1986 { 1987 "status": "pending", 1988 "expires": "2016-01-01T00:00:00Z", 1990 "notBefore": "2016-01-01T00:00:00Z", 1991 "notAfter": "2016-01-08T00:00:00Z", 1993 "identifiers": [ 1994 { "type": "dns", "value": "example.com" }, 1995 ], 1997 "authorizations": [ 1998 "https://example.com/acme/authz/PAniVnsZcis", 1999 ], 2001 "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize" 2002 } 2004 The order object returned by the server represents a promise that if 2005 the client fulfills the server's requirements before the "expires" 2006 time, then the server will be willing to finalize the order upon 2007 request and issue the requested certificate. In the order object, 2008 any authorization referenced in the "authorizations" array whose 2009 status is "pending" represents an authorization transaction that the 2010 client must complete before the server will issue the certificate 2011 (see Section 7.5). If the client fails to complete the required 2012 actions before the "expires" time, then the server SHOULD change the 2013 status of the order to "invalid" and MAY delete the order resource. 2014 Clients MUST NOT make any assumptions about the sort order of 2015 "identifiers" or "authorizations" elements in the returned order 2016 object. 2018 Once the client believes it has fulfilled the server's requirements, 2019 it should send a POST request to the order resource's finalize URL. 2020 The POST body MUST include a CSR: 2022 csr (required, string): A CSR encoding the parameters for the 2023 certificate being requested [RFC2986]. The CSR is sent in the 2024 base64url-encoded version of the DER format. (Note: Because this 2025 field uses base64url, and does not include headers, it is 2026 different from PEM.). 2028 POST /acme/order/TOlocE8rfgo/finalize HTTP/1.1 2029 Host: example.com 2030 Content-Type: application/jose+json 2032 { 2033 "protected": base64url({ 2034 "alg": "ES256", 2035 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2036 "nonce": "MSF2j2nawWHPxxkE3ZJtKQ", 2037 "url": "https://example.com/acme/order/TOlocE8rfgo/finalize" 2038 }), 2039 "payload": base64url({ 2040 "csr": "MIIBPTCBxAIBADBFMQ...FS6aKdZeGsysoCo4H9P", 2041 }), 2042 "signature": "uOrUfIIk5RyQ...nw62Ay1cl6AB" 2043 } 2045 The CSR encodes the client's requests with regard to the content of 2046 the certificate to be issued. The CSR MUST indicate the exact same 2047 set of requested identifiers as the initial new-order request. 2048 Identifiers of type "dns" MUST appear either in the commonName 2049 portion of the requested subject name, or in an extensionRequest 2050 attribute [RFC2985] requesting a subjectAltName extension, or both. 2051 (These identifiers may appear in any sort order.) Specifications 2052 that define new identifier types must specify where in the 2053 certificate signing request these identifiers can appear. 2055 A request to finalize an order will result in error if the CA is 2056 unwilling to issue a certificate corresponding to the submitted CSR. 2057 For example: 2059 o If the order indicated does not have status "ready" 2061 o If the CSR and order identifiers differ 2063 o If the account is not authorized for the identifiers indicated in 2064 the CSR 2066 o If the CSR requests extensions that the CA is not willing to 2067 include 2069 In such cases, the problem document returned by the server SHOULD use 2070 error code "badCSR", and describe specific reasons the CSR was 2071 rejected in its "details" field. After returning such an error, the 2072 server SHOULD leave the order in the "ready" state, to allow the 2073 client to submit a new finalize request with an amended CSR. 2075 A request to finalize an order will return the order to be finalized. 2076 The client should begin polling the order by sending a POST-as-GET 2077 request to the order resource to obtain its current state. The 2078 status of the order will indicate what action the client should take: 2080 o "invalid": The certificate will not be issued. Consider this 2081 order process abandoned. 2083 o "pending": The server does not believe that the client has 2084 fulfilled the requirements. Check the "authorizations" array for 2085 entries that are still pending. 2087 o "ready": The server agrees that the requirements have been 2088 fulfilled, and is awaiting finalization. Submit a finalization 2089 request. 2091 o "processing": The certificate is being issued. Send a POST-as-GET 2092 request after the time given in the "Retry-After" header field of 2093 the response, if any. 2095 o "valid": The server has issued the certificate and provisioned its 2096 URL to the "certificate" field of the order. Download the 2097 certificate. 2099 HTTP/1.1 200 OK 2100 Replay-Nonce: CGf81JWBsq8QyIgPCi9Q9X 2101 Location: https://example.com/acme/order/TOlocE8rfgo 2103 { 2104 "status": "valid", 2105 "expires": "2015-12-31T00:17:00.00-09:00", 2107 "notBefore": "2015-12-31T00:17:00.00-09:00", 2108 "notAfter": "2015-12-31T00:17:00.00-09:00", 2110 "identifiers": [ 2111 { "type": "dns", "value": "example.com" }, 2112 { "type": "dns", "value": "www.example.com" } 2113 ], 2115 "authorizations": [ 2116 "https://example.com/acme/authz/PAniVnsZcis", 2117 "https://example.com/acme/authz/r4HqLzrSrpI" 2118 ], 2120 "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize", 2122 "certificate": "https://example.com/acme/cert/mAt3xBGaobw" 2123 } 2125 7.4.1. Pre-Authorization 2127 The order process described above presumes that authorization objects 2128 are created reactively, in response to a certificate order. Some 2129 servers may also wish to enable clients to obtain authorization for 2130 an identifier proactively, outside of the context of a specific 2131 issuance. For example, a client hosting virtual servers for a 2132 collection of names might wish to obtain authorization before any 2133 virtual servers are created and only create a certificate when a 2134 virtual server starts up. 2136 In some cases, a CA running an ACME server might have a completely 2137 external, non-ACME process for authorizing a client to issue 2138 certificates for an identifier. In these cases, the CA should 2139 provision its ACME server with authorization objects corresponding to 2140 these authorizations and reflect them as already valid in any orders 2141 submitted by the client. 2143 If a CA wishes to allow pre-authorization within ACME, it can offer a 2144 "new authorization" resource in its directory by adding the field 2145 "newAuthz" with a URL for the new authorization resource. 2147 To request authorization for an identifier, the client sends a POST 2148 request to the new-authorization resource specifying the identifier 2149 for which authorization is being requested. 2151 identifier (required, object): The identifier to appear in the 2152 resulting authorization object (see Section 7.1.4) 2154 type (required, string): The type of identifier. 2156 value (required, string): The identifier itself. 2158 POST /acme/new-authz HTTP/1.1 2159 Host: example.com 2160 Content-Type: application/jose+json 2162 { 2163 "protected": base64url({ 2164 "alg": "ES256", 2165 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2166 "nonce": "uQpSjlRb4vQVCjVYAyyUWg", 2167 "url": "https://example.com/acme/new-authz" 2168 }), 2169 "payload": base64url({ 2170 "identifier": { 2171 "type": "dns", 2172 "value": "example.net" 2173 } 2174 }), 2175 "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" 2176 } 2178 Note that because the identifier in a pre-authorization request is 2179 the exact identifier to be included in the authorization object, pre- 2180 authorization cannot be used to authorize issuance with wildcard DNS 2181 identifiers. 2183 Before processing the authorization request, the server SHOULD 2184 determine whether it is willing to issue certificates for the 2185 identifier. For example, the server should check that the identifier 2186 is of a supported type. Servers might also check names against a 2187 blacklist of known high-value identifiers. If the server is 2188 unwilling to issue for the identifier, it SHOULD return a 403 2189 (Forbidden) error, with a problem document describing the reason for 2190 the rejection. 2192 If the server is willing to proceed, it builds a pending 2193 authorization object from the inputs submitted by the client: 2195 o "identifier" the identifier submitted by the client 2197 o "status" MUST be "pending" unless the server has out-of-band 2198 information about the client's authorization status 2200 o "challenges" as selected by the server's policy for this 2201 identifier 2203 The server allocates a new URL for this authorization, and returns a 2204 201 (Created) response, with the authorization URL in the Location 2205 header field, and the JSON authorization object in the body. The 2206 client then follows the process described in Section 7.5 to complete 2207 the authorization process. 2209 7.4.2. Downloading the Certificate 2211 To download the issued certificate, the client simply sends a POST- 2212 as-GET request to the certificate URL. 2214 The default format of the certificate is application/pem-certificate- 2215 chain (see Section 9). 2217 The server MAY provide one or more link relation header fields 2218 [RFC5988] with relation "alternate". Each such field SHOULD express 2219 an alternative certificate chain starting with the same end-entity 2220 certificate. This can be used to express paths to various trust 2221 anchors. Clients can fetch these alternates and use their own 2222 heuristics to decide which is optimal. 2224 POST /acme/cert/mAt3xBGaobw HTTP/1.1 2225 Host: example.com 2226 Content-Type: application/jose+json 2227 Accept: application/pem-certificate-chain 2229 { 2230 "protected": base64url({ 2231 "alg": "ES256", 2232 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2233 "nonce": "uQpSjlRb4vQVCjVYAyyUWg", 2234 "url": "https://example.com/acme/cert/mAt3xBGaobw" 2235 }), 2236 "payload": "", 2237 "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" 2238 } 2240 HTTP/1.1 200 OK 2241 Content-Type: application/pem-certificate-chain 2242 Link: ;rel="index" 2244 -----BEGIN CERTIFICATE----- 2245 [End-entity certificate contents] 2246 -----END CERTIFICATE----- 2247 -----BEGIN CERTIFICATE----- 2248 [Issuer certificate contents] 2249 -----END CERTIFICATE----- 2250 -----BEGIN CERTIFICATE----- 2251 [Other certificate contents] 2252 -----END CERTIFICATE----- 2254 A certificate resource represents a single, immutable certificate. 2255 If the client wishes to obtain a renewed certificate, the client 2256 initiates a new order process to request one. 2258 Because certificate resources are immutable once issuance is 2259 complete, the server MAY enable the caching of the resource by adding 2260 Expires and Cache-Control header fields specifying a point in time in 2261 the distant future. These header fields have no relation to the 2262 certificate's period of validity. 2264 The ACME client MAY request other formats by including an Accept 2265 header field [RFC7231] in its request. For example, the client could 2266 use the media type "application/pkix-cert" [RFC2585] or "application/ 2267 pkcs7-mime" [RFC5751] to request the end-entity certificate in DER 2268 format. Server support for alternate formats is OPTIONAL. For 2269 formats that can only express a single certificate, the server SHOULD 2270 provide one or more "Link: rel="up"" header fields pointing to an 2271 issuer or issuers so that ACME clients can build a certificate chain 2272 as defined in TLS (see Section 4.4.2 of [RFC8446]). 2274 7.5. Identifier Authorization 2276 The identifier authorization process establishes the authorization of 2277 an account to manage certificates for a given identifier. This 2278 process assures the server of two things: 2280 1. That the client controls the private key of the account key pair, 2281 and 2283 2. That the client controls the identifier in question. 2285 This process may be repeated to associate multiple identifiers to a 2286 key pair (e.g., to request certificates with multiple identifiers), 2287 or to associate multiple accounts with an identifier (e.g., to allow 2288 multiple entities to manage certificates). 2290 Authorization resources are created by the server in response to 2291 certificate orders or authorization requests submitted by an account 2292 key holder; their URLs are provided to the client in the responses to 2293 these requests. The authorization object is implicitly tied to the 2294 account key used to sign the request. 2296 When a client receives an order from the server in reply to a new 2297 order request, it downloads the authorization resources by sending 2298 POST-as-GET requests to the indicated URLs. If the client initiates 2299 authorization using a request to the new authorization resource, it 2300 will have already received the pending authorization object in the 2301 response to that request. 2303 POST /acme/authz/PAniVnsZcis HTTP/1.1 2304 Host: example.com 2305 Content-Type: application/jose+json 2307 { 2308 "protected": base64url({ 2309 "alg": "ES256", 2310 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2311 "nonce": "uQpSjlRb4vQVCjVYAyyUWg", 2312 "url": "https://example.com/acme/authz/1234" 2313 }), 2314 "payload": "", 2315 "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" 2316 } 2318 HTTP/1.1 200 OK 2319 Content-Type: application/json 2320 Link: ;rel="index" 2322 { 2323 "status": "pending", 2324 "expires": "2018-03-03T14:09:30Z", 2326 "identifier": { 2327 "type": "dns", 2328 "value": "example.org" 2329 }, 2331 "challenges": [ 2332 { 2333 "type": "http-01", 2334 "url": "https://example.com/acme/chall/prV_B7yEyA4", 2335 "token": "DGyRejmCefe7v4NfDGDKfA" 2336 }, 2337 { 2338 "type": "dns-01", 2339 "url": "https://example.com/acme/chall/Rg5dV14Gh1Q", 2340 "token": "DGyRejmCefe7v4NfDGDKfA" 2341 } 2342 ], 2344 "wildcard": false 2345 } 2347 7.5.1. Responding to Challenges 2349 To prove control of the identifier and receive authorization, the 2350 client needs to provision the required challenge response based on 2351 the challenge type and indicate to the server that it is ready for 2352 the challenge validation to be attempted. 2354 The client indicates to the server it is ready for the challenge 2355 validation by sending an empty JSON body ("{}"), carried in a POST 2356 request to the challenge URL (not authorization URL). 2358 For example, if the client were to respond to the "http-01" challenge 2359 in the above authorization, it would send the following request: 2361 POST /acme/chall/prV_B7yEyA4 HTTP/1.1 2362 Host: example.com 2363 Content-Type: application/jose+json 2365 { 2366 "protected": base64url({ 2367 "alg": "ES256", 2368 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2369 "nonce": "Q_s3MWoqT05TrdkM2MTDcw", 2370 "url": "https://example.com/acme/chall/prV_B7yEyA4" 2371 }), 2372 "payload": base64url({}), 2373 "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ" 2374 } 2376 The server updates the authorization document by updating its 2377 representation of the challenge with the response object provided by 2378 the client. The server MUST ignore any fields in the response object 2379 that are not specified as response fields for this type of challenge. 2380 The server provides a 200 (OK) response with the updated challenge 2381 object as its body. 2383 If the client's response is invalid for any reason or does not 2384 provide the server with appropriate information to validate the 2385 challenge, then the server MUST return an HTTP error. On receiving 2386 such an error, the client SHOULD undo any actions that have been 2387 taken to fulfill the challenge, e.g., removing files that have been 2388 provisioned to a web server. 2390 The server is said to "finalize" the authorization when it has 2391 completed one of the validations, by assigning the authorization a 2392 status of "valid" or "invalid", corresponding to whether it considers 2393 the account authorized for the identifier. If the final state is 2394 "valid", then the server MUST include an "expires" field. When 2395 finalizing an authorization, the server MAY remove challenges other 2396 than the one that was completed, and may modify the "expires" field. 2397 The server SHOULD NOT remove challenges with status "invalid". 2399 Usually, the validation process will take some time, so the client 2400 will need to poll the authorization resource to see when it is 2401 finalized. For challenges where the client can tell when the server 2402 has validated the challenge (e.g., by seeing an HTTP or DNS request 2403 from the server), the client SHOULD NOT begin polling until it has 2404 seen the validation request from the server. 2406 To check on the status of an authorization, the client sends a POST- 2407 as-GET request to the authorization URL, and the server responds with 2408 the current authorization object. In responding to poll requests 2409 while the validation is still in progress, the server MUST return a 2410 200 (OK) response and MAY include a Retry-After header field to 2411 suggest a polling interval to the client. 2413 POST /acme/authz/PAniVnsZcis HTTP/1.1 2414 Host: example.com 2415 Content-Type: application/jose+json 2417 { 2418 "protected": base64url({ 2419 "alg": "ES256", 2420 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2421 "nonce": "uQpSjlRb4vQVCjVYAyyUWg", 2422 "url": "https://example.com/acme/authz/PAniVnsZcis" 2423 }), 2424 "payload": "", 2425 "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" 2426 } 2428 HTTP/1.1 200 OK 2429 Content-Type: application/json 2431 { 2432 "status": "valid", 2433 "expires": "2018-09-09T14:09:01.13Z", 2435 "identifier": { 2436 "type": "dns", 2437 "value": "example.org" 2438 }, 2440 "challenges": [ 2441 { 2442 "type": "http-01", 2443 "url": "https://example.com/acme/chall/prV_B7yEyA4", 2444 "status": "valid", 2445 "validated": "2014-12-01T12:05:13.72Z", 2446 "token": "IlirfxKKXAsHtmzK29Pj8A" 2447 } 2448 ], 2450 "wildcard": false 2451 } 2453 7.5.2. Deactivating an Authorization 2455 If a client wishes to relinquish its authorization to issue 2456 certificates for an identifier, then it may request that the server 2457 deactivates each authorization associated with it by sending POST 2458 requests with the static object {"status": "deactivated"} to each 2459 authorization URL. 2461 POST /acme/authz/PAniVnsZcis HTTP/1.1 2462 Host: example.com 2463 Content-Type: application/jose+json 2465 { 2466 "protected": base64url({ 2467 "alg": "ES256", 2468 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2469 "nonce": "xWCM9lGbIyCgue8di6ueWQ", 2470 "url": "https://example.com/acme/authz/PAniVnsZcis" 2471 }), 2472 "payload": base64url({ 2473 "status": "deactivated" 2474 }), 2475 "signature": "srX9Ji7Le9bjszhu...WTFdtujObzMtZcx4" 2476 } 2478 The server MUST verify that the request is signed by the account key 2479 corresponding to the account that owns the authorization. If the 2480 server accepts the deactivation, it should reply with a 200 (OK) 2481 status code and the updated contents of the authorization object. 2483 The server MUST NOT treat deactivated authorization objects as 2484 sufficient for issuing certificates. 2486 7.6. Certificate Revocation 2488 To request that a certificate be revoked, the client sends a POST 2489 request to the ACME server's revokeCert URL. The body of the POST is 2490 a JWS object whose JSON payload contains the certificate to be 2491 revoked: 2493 certificate (required, string): The certificate to be revoked, in 2494 the base64url-encoded version of the DER format. (Note: Because 2495 this field uses base64url, and does not include headers, it is 2496 different from PEM.) 2498 reason (optional, int): One of the revocation reasonCodes defined in 2499 Section 5.3.1 of [RFC5280] to be used when generating OCSP 2500 responses and CRLs. If this field is not set the server SHOULD 2501 omit the reasonCode CRL entry extension when generating OCSP 2502 responses and CRLs. The server MAY disallow a subset of 2503 reasonCodes from being used by the user. If a request contains a 2504 disallowed reasonCode the server MUST reject it with the error 2505 type "urn:ietf:params:acme:error:badRevocationReason". The 2506 problem document detail SHOULD indicate which reasonCodes are 2507 allowed. 2509 Revocation requests are different from other ACME requests in that 2510 they can be signed either with an account key pair or the key pair in 2511 the certificate. 2513 Example using an account key pair for the signature: 2515 POST /acme/revoke-cert HTTP/1.1 2516 Host: example.com 2517 Content-Type: application/jose+json 2519 { 2520 "protected": base64url({ 2521 "alg": "ES256", 2522 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2523 "nonce": "JHb54aT_KTXBWQOzGYkt9A", 2524 "url": "https://example.com/acme/revoke-cert" 2525 }), 2526 "payload": base64url({ 2527 "certificate": "MIIEDTCCAvegAwIBAgIRAP8...", 2528 "reason": 4 2529 }), 2530 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2531 } 2533 Example using the certificate key pair for the signature: 2535 POST /acme/revoke-cert HTTP/1.1 2536 Host: example.com 2537 Content-Type: application/jose+json 2539 { 2540 "protected": base64url({ 2541 "alg": "RS256", 2542 "jwk": /* certificate's public key */, 2543 "nonce": "JHb54aT_KTXBWQOzGYkt9A", 2544 "url": "https://example.com/acme/revoke-cert" 2545 }), 2546 "payload": base64url({ 2547 "certificate": "MIIEDTCCAvegAwIBAgIRAP8...", 2548 "reason": 1 2549 }), 2550 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2551 } 2553 Before revoking a certificate, the server MUST verify that the key 2554 used to sign the request is authorized to revoke the certificate. 2555 The server MUST consider at least the following accounts authorized 2556 for a given certificate: 2558 o the account that issued the certificate. 2560 o an account that holds authorizations for all of the identifiers in 2561 the certificate. 2563 The server MUST also consider a revocation request valid if it is 2564 signed with the private key corresponding to the public key in the 2565 certificate. 2567 If the revocation succeeds, the server responds with status code 200 2568 (OK). If the revocation fails, the server returns an error. For 2569 example, if the certificate has already been revoked the server 2570 returns an error response with status code 400 (Bad Request) and type 2571 "urn:ietf:params:acme:error:alreadyRevoked". 2573 HTTP/1.1 200 OK 2574 Replay-Nonce: IXVHDyxIRGcTE0VSblhPzw 2575 Content-Length: 0 2577 --- or --- 2579 HTTP/1.1 403 Forbidden 2580 Replay-Nonce: IXVHDyxIRGcTE0VSblhPzw 2581 Content-Type: application/problem+json 2582 Content-Language: en 2584 { 2585 "type": "urn:ietf:params:acme:error:unauthorized", 2586 "detail": "No authorization provided for name example.net" 2587 } 2589 8. Identifier Validation Challenges 2591 There are few types of identifiers in the world for which there is a 2592 standardized mechanism to prove possession of a given identifier. In 2593 all practical cases, CAs rely on a variety of means to test whether 2594 an entity applying for a certificate with a given identifier actually 2595 controls that identifier. 2597 Challenges provide the server with assurance that an account holder 2598 is also the entity that controls an identifier. For each type of 2599 challenge, it must be the case that in order for an entity to 2600 successfully complete the challenge the entity must both: 2602 o Hold the private key of the account key pair used to respond to 2603 the challenge 2605 o Control the identifier in question 2606 Section 10 documents how the challenges defined in this document meet 2607 these requirements. New challenges will need to document how they 2608 do. 2610 ACME uses an extensible challenge/response framework for identifier 2611 validation. The server presents a set of challenges in the 2612 authorization object it sends to a client (as objects in the 2613 "challenges" array), and the client responds by sending a response 2614 object in a POST request to a challenge URL. 2616 This section describes an initial set of challenge types. The 2617 definition of a challenge type includes: 2619 1. Content of challenge objects 2621 2. Content of response objects 2623 3. How the server uses the challenge and response to verify control 2624 of an identifier 2626 Challenge objects all contain the following basic fields: 2628 type (required, string): The type of challenge encoded in the 2629 object. 2631 url (required, string): The URL to which a response can be posted. 2633 status (required, string): The status of this challenge. Possible 2634 values are: "pending", "processing", "valid", and "invalid". (See 2635 Section 7.1.6) 2637 validated (optional, string): The time at which the server validated 2638 this challenge, encoded in the format specified in RFC 3339 2639 [RFC3339]. This field is REQUIRED if the "status" field is 2640 "valid". 2642 error (optional, object): Error that occurred while the server was 2643 validating the challenge, if any, structured as a problem document 2644 [RFC7807]. Multiple errors can be indicated by using subproblems 2645 Section 6.7.1. A challenge object with an error MUST have status 2646 equal to "invalid". 2648 All additional fields are specified by the challenge type. If the 2649 server sets a challenge's "status" to "invalid", it SHOULD also 2650 include the "error" field to help the client diagnose why the 2651 challenge failed. 2653 Different challenges allow the server to obtain proof of different 2654 aspects of control over an identifier. In some challenges, like HTTP 2655 and DNS, the client directly proves its ability to do certain things 2656 related to the identifier. The choice of which challenges to offer 2657 to a client under which circumstances is a matter of server policy. 2659 The identifier validation challenges described in this section all 2660 relate to validation of domain names. If ACME is extended in the 2661 future to support other types of identifiers, there will need to be 2662 new challenge types, and they will need to specify which types of 2663 identifier they apply to. 2665 8.1. Key Authorizations 2667 All challenges defined in this document make use of a key 2668 authorization string. A key authorization is a string that 2669 concatinates the token for the challenge with a key fingerprint, 2670 separated by a "." character: 2672 keyAuthorization = token || '.' || base64url(Thumbprint(accountKey)) 2674 The "Thumbprint" step indicates the computation specified in 2675 [RFC7638], using the SHA-256 digest [FIPS180-4]. As noted in 2676 [RFC7518] any prepended zero octets in the fields of a JWK object 2677 MUST be stripped before doing the computation. 2679 As specified in the individual challenges below, the token for a 2680 challenge is a string comprised entirely of characters in the URL- 2681 safe base64 alphabet. The "||" operator indicates concatenation of 2682 strings. 2684 8.2. Retrying Challenges 2686 ACME challenges typically require the client to set up some network- 2687 accessible resource that the server can query in order to validate 2688 that the client controls an identifier. In practice it is not 2689 uncommon for the server's queries to fail while a resource is being 2690 set up, e.g., due to information propagating across a cluster or 2691 firewall rules not being in place. 2693 Clients SHOULD NOT respond to challenges until they believe that the 2694 server's queries will succeed. If a server's initial validation 2695 query fails, the server SHOULD retry the query after some time, in 2696 order to account for delay in setting up responses such as DNS 2697 records or HTTP resources. The precise retry schedule is up to the 2698 server, but server operators should keep in mind the operational 2699 scenarios that the schedule is trying to accommodate. Given that 2700 retries are intended to address things like propagation delays in 2701 HTTP or DNS provisioning, there should not usually be any reason to 2702 retry more often than every 5 or 10 seconds. While the server is 2703 still trying, the status of the challenge remains "processing"; it is 2704 only marked "invalid" once the server has given up. 2706 The server MUST provide information about its retry state to the 2707 client via the "error" field in the challenge and the Retry-After 2708 HTTP header field in response to requests to the challenge resource. 2709 The server MUST add an entry to the "error" field in the challenge 2710 after each failed validation query. The server SHOULD set the Retry- 2711 After header field to a time after the server's next validation 2712 query, since the status of the challenge will not change until that 2713 time. 2715 Clients can explicitly request a retry by re-sending their response 2716 to a challenge in a new POST request (with a new nonce, etc.). This 2717 allows clients to request a retry when the state has changed (e.g., 2718 after firewall rules have been updated). Servers SHOULD retry a 2719 request immediately on receiving such a POST request. In order to 2720 avoid denial-of-service attacks via client-initiated retries, servers 2721 SHOULD rate-limit such requests. 2723 8.3. HTTP Challenge 2725 With HTTP validation, the client in an ACME transaction proves its 2726 control over a domain name by proving that it can provision HTTP 2727 resources on a server accessible under that domain name. The ACME 2728 server challenges the client to provision a file at a specific path, 2729 with a specific string as its content. 2731 As a domain may resolve to multiple IPv4 and IPv6 addresses, the 2732 server will connect to at least one of the hosts found in the DNS A 2733 and AAAA records, at its discretion. Because many web servers 2734 allocate a default HTTPS virtual host to a particular low-privilege 2735 tenant user in a subtle and non-intuitive manner, the challenge must 2736 be completed over HTTP, not HTTPS. 2738 type (required, string): The string "http-01" 2740 token (required, string): A random value that uniquely identifies 2741 the challenge. This value MUST have at least 128 bits of entropy. 2742 It MUST NOT contain any characters outside the base64url alphabet, 2743 and MUST NOT include base64 padding characters ("="). See 2744 [RFC4086] for additional information on randomness requirements. 2746 { 2747 "type": "http-01", 2748 "url": "https://example.com/acme/chall/prV_B7yEyA4", 2749 "status": "pending", 2750 "token": "LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0" 2751 } 2753 A client fulfills this challenge by constructing a key authorization 2754 from the "token" value provided in the challenge and the client's 2755 account key. The client then provisions the key authorization as a 2756 resource on the HTTP server for the domain in question. 2758 The path at which the resource is provisioned is comprised of the 2759 fixed prefix "/.well-known/acme-challenge/", followed by the "token" 2760 value in the challenge. The value of the resource MUST be the ASCII 2761 representation of the key authorization. 2763 GET /.well-known/acme-challenge/LoqXcYV8...jxAjEuX0 2764 Host: example.org 2766 HTTP/1.1 200 OK 2767 Content-Type: application/octet-stream 2769 LoqXcYV8...jxAjEuX0.9jg46WB3...fm21mqTI 2771 (In the above, "..." indicates that the token and the JWK thumbprint 2772 in the key authorization have been truncated to fit on the page.) 2774 A client responds with an empty object ({}) to acknowledge that the 2775 challenge can be validated by the server. 2777 POST /acme/chall/prV_B7yEyA4 2778 Host: example.com 2779 Content-Type: application/jose+json 2781 { 2782 "protected": base64url({ 2783 "alg": "ES256", 2784 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2785 "nonce": "UQI1PoRi5OuXzxuX7V7wL0", 2786 "url": "https://example.com/acme/chall/prV_B7yEyA4" 2787 }), 2788 "payload": base64url({}), 2789 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2790 } 2791 On receiving a response, the server constructs and stores the key 2792 authorization from the challenge "token" value and the current client 2793 account key. 2795 Given a challenge/response pair, the server verifies the client's 2796 control of the domain by verifying that the resource was provisioned 2797 as expected. 2799 1. Construct a URL by populating the URL template [RFC6570] 2800 "http://{domain}/.well-known/acme-challenge/{token}", where: 2802 * the domain field is set to the domain name being verified; and 2804 * the token field is set to the token in the challenge. 2806 2. Verify that the resulting URL is well-formed. 2808 3. Dereference the URL using an HTTP GET request. This request MUST 2809 be sent to TCP port 80 on the HTTP server. 2811 4. Verify that the body of the response is a well-formed key 2812 authorization. The server SHOULD ignore whitespace characters at 2813 the end of the body. 2815 5. Verify that key authorization provided by the HTTP server matches 2816 the key authorization stored by the server. 2818 The server SHOULD follow redirects when dereferencing the URL. 2819 Clients might use redirects, for example, so that the response can be 2820 provided by a centralized certificate management server. See 2821 Section 10.2 for security considerations related to redirects. 2823 If all of the above verifications succeed, then the validation is 2824 successful. If the request fails, or the body does not pass these 2825 checks, then it has failed. 2827 The client SHOULD de-provision the resource provisioned for this 2828 challenge once the challenge is complete, i.e., once the "status" 2829 field of the challenge has the value "valid" or "invalid". 2831 Note that becuase the token appears both in the request sent by the 2832 ACME server and in the key authorization in the response, it is 2833 possible to build clients that copy the token from request to 2834 response. Clients should avoid this behavior, because it can lead to 2835 cross-site scripting vulnerabilities; instead, clients should be 2836 explicitly configured on a per-challenge basis. A client that does 2837 copy tokens from requests to responses MUST validate that the token 2838 in the request matches the token syntax above (e.g., that it includes 2839 only characters from the base64url alphabet). 2841 8.4. DNS Challenge 2843 When the identifier being validated is a domain name, the client can 2844 prove control of that domain by provisioning a TXT resource record 2845 containing a designated value for a specific validation domain name. 2847 type (required, string): The string "dns-01" 2849 token (required, string): A random value that uniquely identifies 2850 the challenge. This value MUST have at least 128 bits of entropy. 2851 It MUST NOT contain any characters outside the base64url alphabet, 2852 including padding characters ("="). See [RFC4086] for additional 2853 information on randomness requirements. 2855 { 2856 "type": "dns-01", 2857 "url": "https://example.com/acme/chall/Rg5dV14Gh1Q", 2858 "status": "pending", 2859 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA" 2860 } 2862 A client fulfills this challenge by constructing a key authorization 2863 from the "token" value provided in the challenge and the client's 2864 account key. The client then computes the SHA-256 digest [FIPS180-4] 2865 of the key authorization. 2867 The record provisioned to the DNS contains the base64url encoding of 2868 this digest. The client constructs the validation domain name by 2869 prepending the label "_acme-challenge" to the domain name being 2870 validated, then provisions a TXT record with the digest value under 2871 that name. For example, if the domain name being validated is 2872 "example.org", then the client would provision the following DNS 2873 record: 2875 _acme-challenge.example.org. 300 IN TXT "gfj9Xq...Rg85nM" 2877 A client responds with an empty object ({}) to acknowledge that the 2878 challenge can be validated by the server. 2880 POST /acme/chall/Rg5dV14Gh1Q 2881 Host: example.com 2882 Content-Type: application/jose+json 2884 { 2885 "protected": base64url({ 2886 "alg": "ES256", 2887 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2888 "nonce": "SS2sSl1PtspvFZ08kNtzKd", 2889 "url": "https://example.com/acme/chall/Rg5dV14Gh1Q" 2890 }), 2891 "payload": base64url({}), 2892 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2893 } 2895 On receiving a response, the server constructs and stores the key 2896 authorization from the challenge "token" value and the current client 2897 account key. 2899 To validate a DNS challenge, the server performs the following steps: 2901 1. Compute the SHA-256 digest [FIPS180-4] of the stored key 2902 authorization 2904 2. Query for TXT records for the validation domain name 2906 3. Verify that the contents of one of the TXT records match the 2907 digest value 2909 If all of the above verifications succeed, then the validation is 2910 successful. If no DNS record is found, or DNS record and response 2911 payload do not pass these checks, then the validation fails. 2913 The client SHOULD de-provision the resource record(s) provisioned for 2914 this challenge once the challenge is complete, i.e., once the 2915 "status" field of the challenge has the value "valid" or "invalid". 2917 9. IANA Considerations 2919 9.1. MIME Type: application/pem-certificate-chain 2921 A file of this type contains one or more certificates encoded with 2922 the PEM textual encoding, according to RFC 7468 [RFC7468]. The 2923 textual encoding of certificates in this file MUST use the strict 2924 encoding and MUST NOT include explanatory text. The ABNF for this 2925 format is as follows, where "stricttextualmsg" and "eol" are as 2926 defined in Section 3 of RFC 7468: 2928 certchain = stricttextualmsg *(eol stricttextualmsg) 2930 In order to provide easy interoperation with TLS, the first 2931 certificate MUST be an end-entity certificate. Each following 2932 certificate SHOULD directly certify the one preceding it. Because 2933 certificate validation requires that trust anchors be distributed 2934 independently, a certificate that represents a trust anchor MAY be 2935 omitted from the chain, provided that supported peers are known to 2936 possess any omitted certificates. 2938 The "Media Types" registry should be updated with the following 2939 additional value: 2941 MIME media type name: application 2943 MIME subtype name: pem-certificate-chain 2945 Required parameters: None 2947 Optional parameters: None 2949 Encoding considerations: 7bit 2951 Security considerations: Carries a cryptographic certificate and its 2952 associated certificate chain. This media type carries no active 2953 content. 2955 Interoperability considerations: None 2957 Published specification: draft-ietf-acme-acme [[ RFC EDITOR: Please 2958 replace draft-ietf-acme-acme above with the RFC number assigned to 2959 this ]] 2961 Applications which use this media type: ACME clients and servers, 2962 HTTP servers, other applications that need to be configured with a 2963 certificate chain 2965 Additional information: 2967 Deprecated alias names for this type: n/a Magic number(s): n/a File 2968 extension(s): .pem Macintosh file type code(s): n/a 2970 Person & email address to contact for further information: See 2971 Authors' Addresses section. 2973 Intended usage: COMMON 2975 Restrictions on usage: n/a 2976 Author: See Authors' Addresses section. 2978 Change controller: Internet Engineering Task Force iesg@ietf.org [2] 2980 9.2. Well-Known URI for the HTTP Challenge 2982 The "Well-Known URIs" registry should be updated with the following 2983 additional value (using the template from [RFC5785]): 2985 URI suffix: acme-challenge 2987 Change controller: IETF 2989 Specification document(s): This document, Section Section 8.3 2991 Related information: N/A 2993 9.3. Replay-Nonce HTTP Header 2995 The "Message Headers" registry should be updated with the following 2996 additional value: 2998 +------------------+----------+----------+--------------------------+ 2999 | Header Field | Protocol | Status | Reference | 3000 | Name | | | | 3001 +------------------+----------+----------+--------------------------+ 3002 | Replay-Nonce | http | standard | [[this-RFC, Section | 3003 | | | | 6.5.1] | 3004 +------------------+----------+----------+--------------------------+ 3006 9.4. "url" JWS Header Parameter 3008 The "JSON Web Signature and Encryption Header Parameters" registry 3009 should be updated with the following additional value: 3011 o Header Parameter Name: "url" 3013 o Header Parameter Description: URL 3015 o Header Parameter Usage Location(s): JWE, JWS 3017 o Change Controller: IESG 3019 o Specification Document(s): Section 6.4.1 of RFC XXXX 3021 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 3022 to this document ]] 3024 9.5. "nonce" JWS Header Parameter 3026 The "JSON Web Signature and Encryption Header Parameters" registry 3027 should be updated with the following additional value: 3029 o Header Parameter Name: "nonce" 3031 o Header Parameter Description: Nonce 3033 o Header Parameter Usage Location(s): JWE, JWS 3035 o Change Controller: IESG 3037 o Specification Document(s): Section 6.5.2 of RFC XXXX 3039 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 3040 to this document ]] 3042 9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) 3044 The "IETF URN Sub-namespace for Registered Protocol Parameter 3045 Identifiers" registry should be updated with the following additional 3046 value, following the template in [RFC3553]: 3048 Registry name: acme 3050 Specification: RFC XXXX 3052 Repository: URL-TBD 3054 Index value: No transformation needed. 3056 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 3057 to this document, and replace URL-TBD with the URL assigned by IANA 3058 for registries of ACME parameters. ]] 3060 9.7. New Registries 3062 This document requests that IANA create the following new registries: 3064 1. ACME Account Object Fields (Section 9.7.1) 3066 2. ACME Order Object Fields (Section 9.7.2) 3068 3. ACME Authorization Object Fields (Section 9.7.3) 3070 4. ACME Error Types (Section 9.7.4) 3071 5. ACME Resource Types (Section 9.7.5) 3073 6. ACME Directory Metadata Fields (Section 9.7.6) 3075 7. ACME Identifier Types (Section 9.7.7) 3077 8. ACME Validation Methods (Section 9.7.8) 3079 All of these registries are under a heading of "Automated Certificate 3080 Management Environment (ACME) Protocol" and are administered under a 3081 Specification Required policy [RFC8126]. 3083 9.7.1. Fields in Account Objects 3085 This registry lists field names that are defined for use in ACME 3086 account objects. Fields marked as "configurable" may be included in 3087 a new-account request. 3089 Template: 3091 o Field name: The string to be used as a field name in the JSON 3092 object 3094 o Field type: The type of value to be provided, e.g., string, 3095 boolean, array of string 3097 o Requests: Either the value "none" or a list of types of requests 3098 where the field is allowed in a request object, taken from the 3099 following values: 3101 * "new" - Requests to the "newAccount" URL 3103 * "account" - Requests to an account URL 3105 o Reference: Where this field is defined 3107 Initial contents: The fields and descriptions defined in 3108 Section 7.1.2. 3110 +------------------------+---------------+--------------+-----------+ 3111 | Field Name | Field Type | Requests | Reference | 3112 +------------------------+---------------+--------------+-----------+ 3113 | status | string | new, account | RFC XXXX | 3114 | | | | | 3115 | contact | array of | new, account | RFC XXXX | 3116 | | string | | | 3117 | | | | | 3118 | externalAccountBinding | object | new | RFC XXXX | 3119 | | | | | 3120 | termsOfServiceAgreed | boolean | new | RFC XXXX | 3121 | | | | | 3122 | orders | string | none | RFC XXXX | 3123 +------------------------+---------------+--------------+-----------+ 3125 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 3126 to this document ]] 3128 9.7.2. Fields in Order Objects 3130 This registry lists field names that are defined for use in ACME 3131 order objects. Fields marked as "configurable" may be included in a 3132 new-order request. 3134 Template: 3136 o Field name: The string to be used as a field name in the JSON 3137 object 3139 o Field type: The type of value to be provided, e.g., string, 3140 boolean, array of string 3142 o Client configurable: Boolean indicating whether the server should 3143 accept values provided by the client 3145 o Reference: Where this field is defined 3147 Initial contents: The fields and descriptions defined in 3148 Section 7.1.3. 3150 +----------------+-----------------+--------------+-----------+ 3151 | Field Name | Field Type | Configurable | Reference | 3152 +----------------+-----------------+--------------+-----------+ 3153 | status | string | false | RFC XXXX | 3154 | | | | | 3155 | expires | string | false | RFC XXXX | 3156 | | | | | 3157 | identifiers | array of object | true | RFC XXXX | 3158 | | | | | 3159 | notBefore | string | true | RFC XXXX | 3160 | | | | | 3161 | notAfter | string | true | RFC XXXX | 3162 | | | | | 3163 | authorizations | array of string | false | RFC XXXX | 3164 | | | | | 3165 | finalize | string | false | RFC XXXX | 3166 | | | | | 3167 | certificate | string | false | RFC XXXX | 3168 +----------------+-----------------+--------------+-----------+ 3170 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 3171 to this document ]] 3173 9.7.3. Fields in Authorization Objects 3175 This registry lists field names that are defined for use in ACME 3176 authorization objects. Fields marked as "configurable" may be 3177 included in a new-authorization request. 3179 Template: 3181 o Field name: The string to be used as a field name in the JSON 3182 object 3184 o Field type: The type of value to be provided, e.g., string, 3185 boolean, array of string 3187 o Client configurable: Boolean indicating whether the server should 3188 accept values provided by the client 3190 o Reference: Where this field is defined 3192 Initial contents: The fields and descriptions defined in 3193 Section 7.1.4. 3195 +------------+-----------------+--------------+-----------+ 3196 | Field Name | Field Type | Configurable | Reference | 3197 +------------+-----------------+--------------+-----------+ 3198 | identifier | object | true | RFC XXXX | 3199 | | | | | 3200 | status | string | false | RFC XXXX | 3201 | | | | | 3202 | expires | string | false | RFC XXXX | 3203 | | | | | 3204 | challenges | array of object | false | RFC XXXX | 3205 | | | | | 3206 | wildcard | boolean | false | RFC XXXX | 3207 +------------+-----------------+--------------+-----------+ 3209 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 3210 to this document ]] 3212 9.7.4. Error Types 3214 This registry lists values that are used within URN values that are 3215 provided in the "type" field of problem documents in ACME. 3217 Template: 3219 o Type: The label to be included in the URN for this error, 3220 following "urn:ietf:params:acme:error:" 3222 o Description: A human-readable description of the error 3224 o Reference: Where the error is defined 3226 Initial contents: The types and descriptions in the table in 3227 Section 6.7 above, with the Reference field set to point to this 3228 specification. 3230 9.7.5. Resource Types 3232 This registry lists the types of resources that ACME servers may list 3233 in their directory objects. 3235 Template: 3237 o Field name: The value to be used as a field name in the directory 3238 object 3240 o Resource type: The type of resource labeled by the field 3242 o Reference: Where the resource type is defined 3243 Initial contents: 3245 +------------+--------------------+-----------+ 3246 | Field Name | Resource Type | Reference | 3247 +------------+--------------------+-----------+ 3248 | newNonce | New nonce | RFC XXXX | 3249 | | | | 3250 | newAccount | New account | RFC XXXX | 3251 | | | | 3252 | newOrder | New order | RFC XXXX | 3253 | | | | 3254 | newAuthz | New authorization | RFC XXXX | 3255 | | | | 3256 | revokeCert | Revoke certificate | RFC XXXX | 3257 | | | | 3258 | keyChange | Key change | RFC XXXX | 3259 | | | | 3260 | meta | Metadata object | RFC XXXX | 3261 +------------+--------------------+-----------+ 3263 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 3264 to this document ]] 3266 9.7.6. Fields in the "meta" Object within a Directory Object 3268 This registry lists field names that are defined for use in the JSON 3269 object included in the "meta" field of an ACME directory object. 3271 Template: 3273 o Field name: The string to be used as a field name in the JSON 3274 object 3276 o Field type: The type of value to be provided, e.g., string, 3277 boolean, array of string 3279 o Reference: Where this field is defined 3281 Initial contents: The fields and descriptions defined in 3282 Section 7.1.1. 3284 +-------------------------+-----------------+-----------+ 3285 | Field Name | Field Type | Reference | 3286 +-------------------------+-----------------+-----------+ 3287 | termsOfService | string | RFC XXXX | 3288 | | | | 3289 | website | string | RFC XXXX | 3290 | | | | 3291 | caaIdentities | array of string | RFC XXXX | 3292 | | | | 3293 | externalAccountRequired | boolean | RFC XXXX | 3294 +-------------------------+-----------------+-----------+ 3296 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 3297 to this document ]] 3299 9.7.7. Identifier Types 3301 This registry lists the types of identifiers that can be present in 3302 ACME authorization objects. 3304 Template: 3306 o Label: The value to be put in the "type" field of the identifier 3307 object 3309 o Reference: Where the identifier type is defined 3311 Initial contents: 3313 +-------+-----------+ 3314 | Label | Reference | 3315 +-------+-----------+ 3316 | dns | RFC XXXX | 3317 +-------+-----------+ 3319 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 3320 to this document ]] 3322 9.7.8. Validation Methods 3324 This registry lists identifiers for the ways that CAs can validate 3325 control of identifiers. Each method's entry must specify whether it 3326 corresponds to an ACME challenge type. The "Identifier Type" field 3327 must be contained in the Label column of the ACME Identifier Types 3328 registry. 3330 Template: 3332 o Label: The identifier for this validation method 3334 o Identifier Type: The type of identifier that this method applies 3335 to 3337 o ACME: "Y" if the validation method corresponds to an ACME 3338 challenge type; "N" otherwise 3340 o Reference: Where the validation method is defined 3342 This registry may also contain reserved entries (e.g., to avoid 3343 collisions). Such entries should have the "ACME" field set to "N" 3344 and the "Identifier Type" set to "RESERVED". 3346 Initial Contents 3348 +------------+-----------------+------+-----------+ 3349 | Label | Identifier Type | ACME | Reference | 3350 +------------+-----------------+------+-----------+ 3351 | http-01 | dns | Y | RFC XXXX | 3352 | | | | | 3353 | dns-01 | dns | Y | RFC XXXX | 3354 | | | | | 3355 | tls-sni-01 | RESERVED | N | RFC XXXX | 3356 | | | | | 3357 | tls-sni-02 | RESERVED | N | RFC XXXX | 3358 +------------+-----------------+------+-----------+ 3360 When evaluating a request for an assignment in this registry, the 3361 designated expert should ensure that the method being registered has 3362 a clear, interoperable definition and does not overlap with existing 3363 validation methods. That is, it should not be possible for a client 3364 and server to follow the same set of actions to fulfill two different 3365 validation methods. 3367 The values "tls-sni-01" and "tls-sni-02" are reserved because they 3368 were used in pre-RFC versions of this specification to denote 3369 validation methods that were removed because they were found not to 3370 be secure in some cases. 3372 Validation methods do not have to be compatible with ACME in order to 3373 be registered. For example, a CA might wish to register a validation 3374 method in order to support its use with the ACME extensions to CAA 3375 [I-D.ietf-acme-caa]. 3377 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 3378 to this document ]] 3380 10. Security Considerations 3382 ACME is a protocol for managing certificates that attest to 3383 identifier/key bindings. Thus the foremost security goal of ACME is 3384 to ensure the integrity of this process, i.e., to ensure that the 3385 bindings attested by certificates are correct and that only 3386 authorized entities can manage certificates. ACME identifies clients 3387 by their account keys, so this overall goal breaks down into two more 3388 precise goals: 3390 1. Only an entity that controls an identifier can get an 3391 authorization for that identifier 3393 2. Once authorized, an account key's authorizations cannot be 3394 improperly used by another account 3396 In this section, we discuss the threat model that underlies ACME and 3397 the ways that ACME achieves these security goals within that threat 3398 model. We also discuss the denial-of-service risks that ACME servers 3399 face, and a few other miscellaneous considerations. 3401 10.1. Threat Model 3403 As a service on the Internet, ACME broadly exists within the Internet 3404 threat model [RFC3552]. In analyzing ACME, it is useful to think of 3405 an ACME server interacting with other Internet hosts along two 3406 "channels": 3408 o An ACME channel, over which the ACME HTTPS requests are exchanged 3410 o A validation channel, over which the ACME server performs 3411 additional requests to validate a client's control of an 3412 identifier 3414 +------------+ 3415 | ACME | ACME Channel 3416 | Client |--------------------+ 3417 +------------+ | 3418 V 3419 +------------+ 3420 | ACME | 3421 | Server | 3422 +------------+ 3423 +------------+ | 3424 | Validation |<-------------------+ 3425 | Server | Validation Channel 3426 +------------+ 3428 Communications Channels Used by ACME 3430 In practice, the risks to these channels are not entirely separate, 3431 but they are different in most cases. Each channel, for example, 3432 uses a different communications pattern: the ACME channel will 3433 comprise inbound HTTPS connections to the ACME server and the 3434 validation channel outbound HTTP or DNS requests. 3436 Broadly speaking, ACME aims to be secure against active and passive 3437 attackers on any individual channel. Some vulnerabilities arise 3438 (noted below) when an attacker can exploit both the ACME channel and 3439 one of the others. 3441 On the ACME channel, in addition to network layer attackers, we also 3442 need to account for man-in-the-middle (MitM) attacks at the 3443 application layer, and for abusive use of the protocol itself. 3444 Protection against application layer MitM addresses potential 3445 attackers such as Content Distribution Networks (CDNs) and 3446 middleboxes with a TLS MitM function. Preventing abusive use of ACME 3447 means ensuring that an attacker with access to the validation channel 3448 can't obtain illegitimate authorization by acting as an ACME client 3449 (legitimately, in terms of the protocol). 3451 ACME does not protect against other types of abuse by a MitM on the 3452 ACME channel. For example, such an attacker could send a bogus 3453 "badSignatureAlgorithm" error response to downgrade a client to the 3454 lowest-quality signature algorithm that the server supports. A MitM 3455 that is present on all connections (such as a CDN), can cause denial- 3456 of-service conditions in a variety of ways. 3458 10.2. Integrity of Authorizations 3460 ACME allows anyone to request challenges for an identifier by 3461 registering an account key and sending a new-order request using that 3462 account key. The integrity of the authorization process thus depends 3463 on the identifier validation challenges to ensure that the challenge 3464 can only be completed by someone who both (1) holds the private key 3465 of the account key pair, and (2) controls the identifier in question. 3467 Validation responses need to be bound to an account key pair in order 3468 to avoid situations where a MitM on ACME HTTPS requests can switch 3469 out a legitimate domain holder's account key for one of his choosing. 3470 Such MitMs can arise, for example, if a CA uses a CDN or third-party 3471 reverse proxy in front of its ACME interface. An attack by such an 3472 MitM could have the following form: 3474 o Legitimate domain holder registers account key pair A 3476 o MitM registers account key pair B 3478 o Legitimate domain holder sends a new-order request signed using 3479 account key A 3481 o MitM suppresses the legitimate request but sends the same request 3482 signed using account key B 3484 o ACME server issues challenges and MitM forwards them to the 3485 legitimate domain holder 3487 o Legitimate domain holder provisions the validation response 3489 o ACME server performs validation query and sees the response 3490 provisioned by the legitimate domain holder 3492 o Because the challenges were issued in response to a message signed 3493 account key B, the ACME server grants authorization to account key 3494 B (the MitM) instead of account key A (the legitimate domain 3495 holder) 3497 Domain ACME 3498 Holder MitM Server 3499 | | | 3500 | newAccount(A) | | 3501 |--------------------->|--------------------->| 3502 | | | 3503 | | newAccount(B) | 3504 | |--------------------->| 3505 | newOrder(domain, A) | | 3506 |--------------------->| | 3507 | | newOrder(domain, B) | 3508 | |--------------------->| 3509 | | | 3510 | authz, challenges | authz, challenges | 3511 |<---------------------|<---------------------| 3512 | | | 3513 | response(chall, A) | response(chall, B) | 3514 |--------------------->|--------------------->| 3515 | | | 3516 | validation request | | 3517 |<--------------------------------------------| 3518 | | | 3519 | validation response | | 3520 |-------------------------------------------->| 3521 | | | 3522 | | | Considers challenge 3523 | | | fulfilled by B. 3524 | | | 3526 Man-in-the-Middle Attack Exploiting a Validation Method without 3527 Account Key Binding 3529 All of the challenges defined in this document have a binding between 3530 the account private key and the validation query made by the server, 3531 via the key authorization. The key authorization reflects the 3532 account public key and is provided to the server in the validation 3533 response over the validation channel. 3535 The association of challenges to identifiers is typically done by 3536 requiring the client to perform some action that only someone who 3537 effectively controls the identifier can perform. For the challenges 3538 in this document, the actions are: 3540 o HTTP: Provision files under .well-known on a web server for the 3541 domain 3543 o DNS: Provision DNS resource records for the domain 3544 There are several ways that these assumptions can be violated, both 3545 by misconfiguration and by attacks. For example, on a web server 3546 that allows non-administrative users to write to .well-known, any 3547 user can claim to own the web server's hostname by responding to an 3548 HTTP challenge. Similarly, if a server that can be used for ACME 3549 validation is compromised by a malicious actor, then that malicious 3550 actor can use that access to obtain certificates via ACME. 3552 The use of hosting providers is a particular risk for ACME 3553 validation. If the owner of the domain has outsourced operation of 3554 DNS or web services to a hosting provider, there is nothing that can 3555 be done against tampering by the hosting provider. As far as the 3556 outside world is concerned, the zone or website provided by the 3557 hosting provider is the real thing. 3559 More limited forms of delegation can also lead to an unintended party 3560 gaining the ability to successfully complete a validation 3561 transaction. For example, suppose an ACME server follows HTTP 3562 redirects in HTTP validation and a website operator provisions a 3563 catch-all redirect rule that redirects requests for unknown resources 3564 to a different domain. Then the target of the redirect could use 3565 that to get a certificate through HTTP validation since the 3566 validation path will not be known to the primary server. 3568 The DNS is a common point of vulnerability for all of these 3569 challenges. An entity that can provision false DNS records for a 3570 domain can attack the DNS challenge directly and can provision false 3571 A/AAAA records to direct the ACME server to send its HTTP validation 3572 query to a remote server of the attacker's choosing. There are a few 3573 different mitigations that ACME servers can apply: 3575 o Always querying the DNS using a DNSSEC-validating resolver 3576 (enhancing security for zones that are DNSSEC-enabled) 3578 o Querying the DNS from multiple vantage points to address local 3579 attackers 3581 o Applying mitigations against DNS off-path attackers, e.g., adding 3582 entropy to requests [I-D.vixie-dnsext-dns0x20] or only using TCP 3584 Given these considerations, the ACME validation process makes it 3585 impossible for any attacker on the ACME channel or a passive attacker 3586 on the validation channel to hijack the authorization process to 3587 authorize a key of the attacker's choice. 3589 An attacker that can only see the ACME channel would need to convince 3590 the validation server to provide a response that would authorize the 3591 attacker's account key, but this is prevented by binding the 3592 validation response to the account key used to request challenges. A 3593 passive attacker on the validation channel can observe the correct 3594 validation response and even replay it, but that response can only be 3595 used with the account key for which it was generated. 3597 An active attacker on the validation channel can subvert the ACME 3598 process, by performing normal ACME transactions and providing a 3599 validation response for his own account key. The risks due to 3600 hosting providers noted above are a particular case. 3602 Attackers can also exploit vulnerabilities in Internet routing 3603 protocols to gain access to the validation channel (see, e.g., 3604 [RFC7132]). In order to make such attacks more difficult, it is 3605 RECOMMENDED that the server perform DNS queries and make HTTP 3606 connections from multiple points in the network. Since routing 3607 attacks are often localized or dependent on the position of the 3608 attacker, forcing the attacker to attack multiple points (the 3609 server's validation vantage points) or a specific point (the DNS / 3610 HTTP server) makes it more difficult to subvert ACME validation using 3611 attacks on routing. 3613 10.3. Denial-of-Service Considerations 3615 As a protocol run over HTTPS, standard considerations for TCP-based 3616 and HTTP-based DoS mitigation also apply to ACME. 3618 At the application layer, ACME requires the server to perform a few 3619 potentially expensive operations. Identifier validation transactions 3620 require the ACME server to make outbound connections to potentially 3621 attacker-controlled servers, and certificate issuance can require 3622 interactions with cryptographic hardware. 3624 In addition, an attacker can also cause the ACME server to send 3625 validation requests to a domain of its choosing by submitting 3626 authorization requests for the victim domain. 3628 All of these attacks can be mitigated by the application of 3629 appropriate rate limits. Issues closer to the front end, like POST 3630 body validation, can be addressed using HTTP request limiting. For 3631 validation and certificate requests, there are other identifiers on 3632 which rate limits can be keyed. For example, the server might limit 3633 the rate at which any individual account key can issue certificates 3634 or the rate at which validation can be requested within a given 3635 subtree of the DNS. And in order to prevent attackers from 3636 circumventing these limits simply by minting new accounts, servers 3637 would need to limit the rate at which accounts can be registered. 3639 10.4. Server-Side Request Forgery 3641 Server-Side Request Forgery (SSRF) attacks can arise when an attacker 3642 can cause a server to perform HTTP requests to an attacker-chosen 3643 URL. In the ACME HTTP challenge validation process, the ACME server 3644 performs an HTTP GET request to a URL in which the attacker can 3645 choose the domain. This request is made before the server has 3646 verified that the client controls the domain, so any client can cause 3647 a query to any domain. 3649 Some ACME server implementations include information from the 3650 validation server's response (in order to facilitate debugging). 3651 Such implementations enable an attacker to extract this information 3652 from any web server that is accessible to the ACME server, even if it 3653 is not accessible to the ACME client. For example, the ACME server 3654 might be able to access servers behind a firewall that would prevent 3655 access by the ACME client. 3657 It might seem that the risk of SSRF through this channel is limited 3658 by the fact that the attacker can only control the domain of the URL, 3659 not the path. However, if the attacker first sets the domain to one 3660 they control, then they can send the server an HTTP redirect (e.g., a 3661 302 response) which will cause the server to query an arbitrary URL. 3663 In order to further limit the SSRF risk, ACME server operators should 3664 ensure that validation queries can only be sent to servers on the 3665 public Internet, and not, say, web services within the server 3666 operator's internal network. Since the attacker could make requests 3667 to these public servers himself, he can't gain anything extra through 3668 an SSRF attack on ACME aside from a layer of anonymization. 3670 10.5. CA Policy Considerations 3672 The controls on issuance enabled by ACME are focused on validating 3673 that a certificate applicant controls the identifier he claims. 3674 Before issuing a certificate, however, there are many other checks 3675 that a CA might need to perform, for example: 3677 o Has the client agreed to a subscriber agreement? 3679 o Is the claimed identifier syntactically valid? 3681 o For domain names: 3683 * If the leftmost label is a '*', then have the appropriate 3684 checks been applied? 3686 * Is the name on the Public Suffix List? 3687 * Is the name a high-value name? 3689 * Is the name a known phishing domain? 3691 o Is the key in the CSR sufficiently strong? 3693 o Is the CSR signed with an acceptable algorithm? 3695 o Has issuance been authorized or forbidden by a Certificate 3696 Authority Authorization (CAA) record? [RFC6844] 3698 CAs that use ACME to automate issuance will need to ensure that their 3699 servers perform all necessary checks before issuing. 3701 CAs using ACME to allow clients to agree to terms of service should 3702 keep in mind that ACME clients can automate this agreement, possibly 3703 not involving a human user. 3705 ACME does not specify how the server constructs the URLs that it uses 3706 to address resources. If the server operator uses URLs that are 3707 predictable to third parties, this can leak information about what 3708 URLs exist on the server, since an attacker can probe for whether 3709 POST-as-GET request to the URL returns "Not Found" or "Unauthorized". 3711 For example, suppose that the CA uses highly structured URLs with 3712 guessable fields: 3714 o Accounts: https://example.com/:accountID 3716 o Orders: https://example.com/:accountID/:domainName 3718 o Authorizations: https://example.com/:accountID/:domainName 3720 o Certificates: https://example.com/:accountID/:domainName 3722 Under that scheme, an attacker could probe for which domain names are 3723 associated with which accounts, which may allow correlation of 3724 ownership between domain names, if the CA does not otherwise permit 3725 it. 3727 To avoid leaking these correlations, CAs SHOULD assign URLs with an 3728 unpredictable component. For example, a CA might assign URLs for 3729 each resource type from an independent namespace, using unpredictable 3730 IDs for each resource: 3732 o Accounts: https://example.com/acct/:accountID 3734 o Orders: https://example.com/order/:orderID 3735 o Authorizations: https://example.com/authz/:authorizationID 3737 o Certificates: https://example.com/cert/:certID 3739 Such a scheme would leak only the type of resource, hiding the 3740 additional correlations revealed in the example above. 3742 11. Operational Considerations 3744 There are certain factors that arise in operational reality that 3745 operators of ACME-based CAs will need to keep in mind when 3746 configuring their services. For example: 3748 11.1. Key Selection 3750 ACME relies on two different classes of key pair: 3752 o Account key pairs, which are used to authenticate account holders 3754 o Certificate key pairs, which are used to sign and verify CSRs (and 3755 whose public keys are included in certificates) 3757 Compromise of the private key of an account key pair has more serious 3758 consequences than compromise of a private key corresponding to a 3759 certificate. While the compromise of a certificate key pair allows 3760 the attacker to impersonate the entities named in the certificate for 3761 the lifetime of the certificate, the compromise of an account key 3762 pair allows the attacker to take full control of the victim's ACME 3763 account, and take any action that the legitimate account holder could 3764 take within the scope of ACME: 3766 1. Issuing certificates using existing authorizations 3768 2. Revoking existing certificates 3770 3. Accessing and changing account information (e.g., contacts) 3772 4. Changing the account key pair for the account, locking out the 3773 legitimate account holder 3775 For this reason, it is RECOMMENDED that each account key pair be used 3776 only for authentication of a single ACME account. For example, the 3777 public key of an account key pair MUST NOT be included in a 3778 certificate. If an ACME client receives a request from a user for 3779 account creation or key roll-over using an account key that the 3780 client knows to be used elsewhere, then the client MUST return an 3781 error. Clients that manage account keys on behalf of users SHOULD 3782 generate a fresh account key for every account creation or roll-over 3783 operation. Note that given the requirements of Section 7.3.1, 3784 servers will not create accounts with reused keys anyway. 3786 ACME clients and servers MUST verify that a CSR submitted in a 3787 finalize request does not contain a public key for any known account 3788 key pair. In particular, when a server receives a finalize request, 3789 it MUST verify that the public key in a CSR is not the same as the 3790 public key of the account key pair used to authenticate that request. 3791 This assures that vulnerabilities in the protocols with which the 3792 certificate is used (e.g., signing oracles in TLS [JSS15]) do not 3793 result in compromise of the ACME account. Because ACME accounts are 3794 uniquely identified by their account key pair (see Section 7.3.1) the 3795 server MUST not allow account key pair reuse across multiple 3796 accounts. 3798 11.2. DNS security 3800 As noted above, DNS forgery attacks against the ACME server can 3801 result in the server making incorrect decisions about domain control 3802 and thus mis-issuing certificates. Servers SHOULD perform DNS 3803 queries over TCP, which provides better resistance to some forgery 3804 attacks than DNS over UDP. 3806 An ACME-based CA will often need to make DNS queries, e.g., to 3807 validate control of DNS names. Because the security of such 3808 validations ultimately depends on the authenticity of DNS data, every 3809 possible precaution should be taken to secure DNS queries done by the 3810 CA. It is therefore RECOMMENDED that ACME-based CAs make all DNS 3811 queries via DNSSEC-validating stub or recursive resolvers. This 3812 provides additional protection to domains which choose to make use of 3813 DNSSEC. 3815 An ACME-based CA must use only a resolver if it trusts the resolver 3816 and every component of the network route by which it is accessed. It 3817 is therefore RECOMMENDED that ACME-based CAs operate their own 3818 DNSSEC-validating resolvers within their trusted network and use 3819 these resolvers both for both CAA record lookups and all record 3820 lookups in furtherance of a challenge scheme (A, AAAA, TXT, etc.). 3822 11.3. Token Entropy 3824 The http-01 and dns-01 validation methods mandate the usage of a 3825 random token value to uniquely identify the challenge. The value of 3826 the token is required to contain at least 128 bits of entropy for the 3827 following security properties. First, the ACME client should not be 3828 able to influence the ACME server's choice of token as this may allow 3829 an attacker to reuse a domain owner's previous challenge responses 3830 for a new validation request. Secondly, the entropy requirement 3831 makes it more difficult for ACME clients to implement a "naive" 3832 validation server that automatically replies to challenges without 3833 being configured per-challenge. 3835 11.4. Malformed Certificate Chains 3837 ACME provides certificate chains in the widely-used format known 3838 colloquially as PEM (though it may diverge from the actual Privacy 3839 Enhanced Mail specifications [RFC1421], as noted in [RFC7468]). Some 3840 current software will allow the configuration of a private key and a 3841 certificate in one PEM file, by concatenating the textual encodings 3842 of the two objects. In the context of ACME, such software might be 3843 vulnerable to "key replacement" attacks. A malicious ACME server 3844 could cause a client to use a private key of its choosing by 3845 including the key in the PEM file returned in response to a query for 3846 a certificate URL. 3848 When processing a file of type "application/pem-certificate-chain", a 3849 client SHOULD verify that the file contains only encoded 3850 certificates. If anything other than a certificate is found (i.e., 3851 if the string "-----BEGIN" is ever followed by anything other than 3852 "CERTIFICATE"), then the client MUST reject the file as invalid. 3854 12. Acknowledgements 3856 In addition to the editors listed on the front page, this document 3857 has benefited from contributions from a broad set of contributors, 3858 all the way back to its inception. 3860 o Andrew Ayer, SSLMate 3862 o Karthik Bhargavan, INRIA 3864 o Peter Eckersley, EFF 3866 o Alex Halderman, University of Michigan 3868 o Sophie Herold, Hemio 3870 o Eric Rescorla, Mozilla 3872 o Seth Schoen, EFF 3874 o Martin Thomson, Mozilla 3876 o Jakub Warmuz, University of Oxford 3877 This document draws on many concepts established by Eric Rescorla's 3878 "Automated Certificate Issuance Protocol" draft. Martin Thomson 3879 provided helpful guidance in the use of HTTP. 3881 13. References 3883 13.1. Normative References 3885 [FIPS180-4] 3886 Department of Commerce, National., "NIST FIPS 180-4, 3887 Secure Hash Standard", March 2012, 3888 . 3891 [JSS15] Somorovsky, J., "On the Security of TLS 1.3 and QUIC 3892 Against Weaknesses in PKCS#1 v1.5 Encryption", n.d., 3893 . 3895 [REST] Fielding, R., "Architectural Styles and the Design of 3896 Network-based Software Architectures", 2000, 3897 . 3900 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3901 Requirement Levels", BCP 14, RFC 2119, 3902 DOI 10.17487/RFC2119, March 1997, 3903 . 3905 [RFC2585] Housley, R. and P. Hoffman, "Internet X.509 Public Key 3906 Infrastructure Operational Protocols: FTP and HTTP", 3907 RFC 2585, DOI 10.17487/RFC2585, May 1999, 3908 . 3910 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 3911 DOI 10.17487/RFC2818, May 2000, 3912 . 3914 [RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object 3915 Classes and Attribute Types Version 2.0", RFC 2985, 3916 DOI 10.17487/RFC2985, November 2000, 3917 . 3919 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 3920 Request Syntax Specification Version 1.7", RFC 2986, 3921 DOI 10.17487/RFC2986, November 2000, 3922 . 3924 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 3925 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 3926 . 3928 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3929 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 3930 2003, . 3932 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3933 Resource Identifier (URI): Generic Syntax", STD 66, 3934 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3935 . 3937 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 3938 "Randomness Requirements for Security", BCP 106, RFC 4086, 3939 DOI 10.17487/RFC4086, June 2005, 3940 . 3942 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 3943 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 3944 . 3946 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 3947 Specifications: ABNF", STD 68, RFC 5234, 3948 DOI 10.17487/RFC5234, January 2008, 3949 . 3951 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3952 (TLS) Protocol Version 1.2", RFC 5246, 3953 DOI 10.17487/RFC5246, August 2008, 3954 . 3956 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3957 Housley, R., and W. Polk, "Internet X.509 Public Key 3958 Infrastructure Certificate and Certificate Revocation List 3959 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3960 . 3962 [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet 3963 Mail Extensions (S/MIME) Version 3.2 Message 3964 Specification", RFC 5751, DOI 10.17487/RFC5751, January 3965 2010, . 3967 [RFC5890] Klensin, J., "Internationalized Domain Names for 3968 Applications (IDNA): Definitions and Document Framework", 3969 RFC 5890, DOI 10.17487/RFC5890, August 2010, 3970 . 3972 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 3973 DOI 10.17487/RFC5988, October 2010, 3974 . 3976 [RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' 3977 URI Scheme", RFC 6068, DOI 10.17487/RFC6068, October 2010, 3978 . 3980 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 3981 and D. Orchard, "URI Template", RFC 6570, 3982 DOI 10.17487/RFC6570, March 2012, 3983 . 3985 [RFC6844] Hallam-Baker, P. and R. Stradling, "DNS Certification 3986 Authority Authorization (CAA) Resource Record", RFC 6844, 3987 DOI 10.17487/RFC6844, January 2013, 3988 . 3990 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3991 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3992 2014, . 3994 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3995 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 3996 DOI 10.17487/RFC7231, June 2014, 3997 . 3999 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 4000 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 4001 April 2015, . 4003 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 4004 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 4005 2015, . 4007 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 4008 DOI 10.17487/RFC7518, May 2015, 4009 . 4011 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 4012 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 4013 2015, . 4015 [RFC7797] Jones, M., "JSON Web Signature (JWS) Unencoded Payload 4016 Option", RFC 7797, DOI 10.17487/RFC7797, February 2016, 4017 . 4019 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 4020 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 4021 . 4023 [RFC8037] Liusvaara, I., "CFRG Elliptic Curve Diffie-Hellman (ECDH) 4024 and Signatures in JSON Object Signing and Encryption 4025 (JOSE)", RFC 8037, DOI 10.17487/RFC8037, January 2017, 4026 . 4028 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 4029 Writing an IANA Considerations Section in RFCs", BCP 26, 4030 RFC 8126, DOI 10.17487/RFC8126, June 2017, 4031 . 4033 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4034 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4035 May 2017, . 4037 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 4038 DOI 10.17487/RFC8288, October 2017, 4039 . 4041 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 4042 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 4043 . 4045 13.2. Informative References 4047 [CABFBR] CA/Browser Forum, ., "CA/Browser Forum Baseline 4048 Requirements", September 2018, 4049 . 4051 [I-D.ietf-acme-caa] 4052 Landau, H., "CAA Record Extensions for Account URI and 4053 ACME Method Binding", draft-ietf-acme-caa-05 (work in 4054 progress), June 2018. 4056 [I-D.ietf-acme-ip] 4057 Shoemaker, R., "ACME IP Identifier Validation Extension", 4058 draft-ietf-acme-ip-04 (work in progress), July 2018. 4060 [I-D.ietf-acme-telephone] 4061 Peterson, J. and R. Barnes, "ACME Identifiers and 4062 Challenges for Telephone Numbers", draft-ietf-acme- 4063 telephone-01 (work in progress), October 2017. 4065 [I-D.vixie-dnsext-dns0x20] 4066 Vixie, P. and D. Dagon, "Use of Bit 0x20 in DNS Labels to 4067 Improve Transaction Identity", draft-vixie-dnsext- 4068 dns0x20-00 (work in progress), March 2008. 4070 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 4071 Mail: Part I: Message Encryption and Authentication 4072 Procedures", RFC 1421, DOI 10.17487/RFC1421, February 4073 1993, . 4075 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 4076 Text on Security Considerations", BCP 72, RFC 3552, 4077 DOI 10.17487/RFC3552, July 2003, 4078 . 4080 [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An 4081 IETF URN Sub-namespace for Registered Protocol 4082 Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June 4083 2003, . 4085 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 4086 Uniform Resource Identifiers (URIs)", RFC 5785, 4087 DOI 10.17487/RFC5785, April 2010, 4088 . 4090 [RFC7132] Kent, S. and A. Chi, "Threat Model for BGP Path Security", 4091 RFC 7132, DOI 10.17487/RFC7132, February 2014, 4092 . 4094 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 4095 "Recommendations for Secure Use of Transport Layer 4096 Security (TLS) and Datagram Transport Layer Security 4097 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 4098 2015, . 4100 [W3C.REC-cors-20140116] 4101 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 4102 Web Consortium Recommendation REC-cors-20140116, January 4103 2014, . 4105 13.3. URIs 4107 [1] https://github.com/ietf-wg-acme/acme 4109 [2] mailto:iesg@ietf.org 4111 Authors' Addresses 4113 Richard Barnes 4114 Cisco 4116 Email: rlb@ipv.sx 4118 Jacob Hoffman-Andrews 4119 EFF 4121 Email: jsha@eff.org 4123 Daniel McCarney 4124 Let's Encrypt 4126 Email: cpu@letsencrypt.org 4128 James Kasten 4129 University of Michigan 4131 Email: jdkasten@umich.edu