idnits 2.17.1 draft-ietf-acme-acme-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 15 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 758 has weird spacing: '...account new-a...' -- The exact meaning of the all-uppercase expression 'NOT REQUIRED' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. -- The document date (October 30, 2017) is 2342 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) == Missing Reference: 'A-Z' is mentioned on line 571, but not defined == Missing Reference: '0-9' is mentioned on line 571, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS180-4' ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Downref: Normative reference to an Informational RFC: RFC 2985 ** Downref: Normative reference to an Informational RFC: RFC 2986 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 6844 (Obsoleted by RFC 8659) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7807 (Obsoleted by RFC 9457) == Outdated reference: A later version (-10) exists of draft-ietf-acme-caa-03 == Outdated reference: A later version (-08) exists of draft-ietf-acme-ip-01 == Outdated reference: A later version (-01) exists of draft-ietf-acme-telephone-00 -- 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: 10 errors (**), 0 flaws (~~), 7 warnings (==), 6 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: May 3, 2018 EFF 6 J. Kasten 7 University of Michigan 8 October 30, 2017 10 Automatic Certificate Management Environment (ACME) 11 draft-ietf-acme-acme-08 13 Abstract 15 Certificates in PKI using X.509 (PKIX) are used for a number of 16 purposes, the most significant of which is the authentication of 17 domain names. Thus, certificate authorities in the Web PKI are 18 trusted to verify that an applicant for a certificate legitimately 19 represents the domain name(s) in the certificate. Today, this 20 verification is done through a collection of ad hoc mechanisms. This 21 document describes a protocol that a certification authority (CA) and 22 an applicant can use to automate the process of verification and 23 certificate issuance. The protocol also provides facilities for 24 other certificate management functions, such as certificate 25 revocation. 27 DISCLAIMER: This is a work in progress draft of ACME and has not yet 28 had a thorough security analysis. 30 RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH: The source for 31 this draft is maintained in GitHub. Suggested changes should be 32 submitted as pull requests at https://github.com/ietf-wg-acme/acme . 33 Instructions are on that page as well. Editorial changes can be 34 managed in GitHub, but any substantive change should be discussed on 35 the ACME mailing list (acme@ietf.org). 37 Status of This Memo 39 This Internet-Draft is submitted in full conformance with the 40 provisions of BCP 78 and BCP 79. 42 Internet-Drafts are working documents of the Internet Engineering 43 Task Force (IETF). Note that other groups may also distribute 44 working documents as Internet-Drafts. The list of current Internet- 45 Drafts is at http://datatracker.ietf.org/drafts/current/. 47 Internet-Drafts are draft documents valid for a maximum of six months 48 and may be updated, replaced, or obsoleted by other documents at any 49 time. It is inappropriate to use Internet-Drafts as reference 50 material or to cite them other than as "work in progress." 52 This Internet-Draft will expire on May 3, 2018. 54 Copyright Notice 56 Copyright (c) 2017 IETF Trust and the persons identified as the 57 document authors. All rights reserved. 59 This document is subject to BCP 78 and the IETF Trust's Legal 60 Provisions Relating to IETF Documents 61 (http://trustee.ietf.org/license-info) in effect on the date of 62 publication of this document. Please review these documents 63 carefully, as they describe your rights and restrictions with respect 64 to this document. Code Components extracted from this document must 65 include Simplified BSD License text as described in Section 4.e of 66 the Trust Legal Provisions and are provided without warranty as 67 described in the Simplified BSD License. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 72 2. Deployment Model and Operator Experience . . . . . . . . . . 5 73 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 74 4. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 7 75 5. Character Encoding . . . . . . . . . . . . . . . . . . . . . 8 76 6. Message Transport . . . . . . . . . . . . . . . . . . . . . . 9 77 6.1. HTTPS Requests . . . . . . . . . . . . . . . . . . . . . 9 78 6.2. Request Authentication . . . . . . . . . . . . . . . . . 10 79 6.3. Request URL Integrity . . . . . . . . . . . . . . . . . . 11 80 6.3.1. "url" (URL) JWS header parameter . . . . . . . . . . 11 81 6.4. Replay protection . . . . . . . . . . . . . . . . . . . . 12 82 6.4.1. Replay-Nonce . . . . . . . . . . . . . . . . . . . . 12 83 6.4.2. "nonce" (Nonce) JWS header parameter . . . . . . . . 13 84 6.5. Rate limits . . . . . . . . . . . . . . . . . . . . . . . 13 85 6.6. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 13 86 7. Certificate Management . . . . . . . . . . . . . . . . . . . 15 87 7.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 15 88 7.1.1. Directory . . . . . . . . . . . . . . . . . . . . . . 18 89 7.1.2. Account Objects . . . . . . . . . . . . . . . . . . . 19 90 7.1.3. Order Objects . . . . . . . . . . . . . . . . . . . . 20 91 7.1.4. Authorization Objects . . . . . . . . . . . . . . . . 22 92 7.2. Getting a Nonce . . . . . . . . . . . . . . . . . . . . . 23 93 7.3. Account Creation . . . . . . . . . . . . . . . . . . . . 24 94 7.3.1. Finding an Account URL Given a Key . . . . . . . . . 26 95 7.3.2. Account Update . . . . . . . . . . . . . . . . . . . 27 96 7.3.3. Account Information . . . . . . . . . . . . . . . . . 27 97 7.3.4. Changes of Terms of Service . . . . . . . . . . . . . 27 98 7.3.5. External Account Binding . . . . . . . . . . . . . . 28 99 7.3.6. Account Key Roll-over . . . . . . . . . . . . . . . . 30 100 7.3.7. Account Deactivation . . . . . . . . . . . . . . . . 32 101 7.4. Applying for Certificate Issuance . . . . . . . . . . . . 33 102 7.4.1. Pre-Authorization . . . . . . . . . . . . . . . . . . 36 103 7.4.2. Downloading the Certificate . . . . . . . . . . . . . 38 104 7.5. Identifier Authorization . . . . . . . . . . . . . . . . 39 105 7.5.1. Responding to Challenges . . . . . . . . . . . . . . 40 106 7.5.2. Deactivating an Authorization . . . . . . . . . . . . 42 107 7.6. Certificate Revocation . . . . . . . . . . . . . . . . . 43 108 8. Identifier Validation Challenges . . . . . . . . . . . . . . 45 109 8.1. Key Authorizations . . . . . . . . . . . . . . . . . . . 47 110 8.2. Retrying Challenges . . . . . . . . . . . . . . . . . . . 47 111 8.3. HTTP Challenge . . . . . . . . . . . . . . . . . . . . . 48 112 8.4. TLS with Server Name Indication (TLS SNI) Challenge . . . 50 113 8.5. DNS Challenge . . . . . . . . . . . . . . . . . . . . . . 52 114 8.6. Out-of-Band Challenge . . . . . . . . . . . . . . . . . . 54 115 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55 116 9.1. MIME Type: application/pem-certificate-chain . . . . . . 55 117 9.2. Well-Known URI for the HTTP Challenge . . . . . . . . . . 56 118 9.3. Replay-Nonce HTTP Header . . . . . . . . . . . . . . . . 56 119 9.4. "url" JWS Header Parameter . . . . . . . . . . . . . . . 56 120 9.5. "nonce" JWS Header Parameter . . . . . . . . . . . . . . 57 121 9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) . . . . 57 122 9.7. New Registries . . . . . . . . . . . . . . . . . . . . . 57 123 9.7.1. Fields in Account Objects . . . . . . . . . . . . . . 58 124 9.7.2. Fields in Order Objects . . . . . . . . . . . . . . . 59 125 9.7.3. Error Types . . . . . . . . . . . . . . . . . . . . . 60 126 9.7.4. Resource Types . . . . . . . . . . . . . . . . . . . 60 127 9.7.5. Identifier Types . . . . . . . . . . . . . . . . . . 61 128 9.7.6. Validation Methods . . . . . . . . . . . . . . . . . 61 129 10. Security Considerations . . . . . . . . . . . . . . . . . . . 63 130 10.1. Threat model . . . . . . . . . . . . . . . . . . . . . . 63 131 10.2. Integrity of Authorizations . . . . . . . . . . . . . . 64 132 10.3. Denial-of-Service Considerations . . . . . . . . . . . . 66 133 10.4. Server-Side Request Forgery . . . . . . . . . . . . . . 67 134 10.5. CA Policy Considerations . . . . . . . . . . . . . . . . 68 135 11. Operational Considerations . . . . . . . . . . . . . . . . . 68 136 11.1. DNS security . . . . . . . . . . . . . . . . . . . . . . 69 137 11.2. Default Virtual Hosts . . . . . . . . . . . . . . . . . 69 138 11.3. Token Entropy . . . . . . . . . . . . . . . . . . . . . 70 139 11.4. Malformed Certificate Chains . . . . . . . . . . . . . . 70 140 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 71 141 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 71 142 13.1. Normative References . . . . . . . . . . . . . . . . . . 71 143 13.2. Informative References . . . . . . . . . . . . . . . . . 74 144 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 75 146 1. Introduction 148 Certificates [RFC5280] in the Web PKI are most commonly used to 149 authenticate domain names. Thus, certificate authorities in the Web 150 PKI are trusted to verify that an applicant for a certificate 151 legitimately represents the domain name(s) in the certificate. 153 Different types of certificates reflect different kinds of CA 154 verification of information about the certificate subject. "Domain 155 Validation" (DV) certificates are by far the most common type. For 156 DV validation, the CA merely verifies that the requester has 157 effective control of the web server and/or DNS server for the domain, 158 but does not explicitly attempt to verify their real-world identity. 159 (This is as opposed to "Organization Validation" (OV) and "Extended 160 Validation" (EV) certificates, where the process is intended to also 161 verify the real-world identity of the requester.) 163 Existing Web PKI certificate authorities tend to run on a set of ad 164 hoc protocols for certificate issuance and identity verification. In 165 the case of DV certificates, a typical user experience is something 166 like: 168 o Generate a PKCS#10 [RFC2986] Certificate Signing Request (CSR). 170 o Cut-and-paste the CSR into a CA web page. 172 o Prove ownership of the domain by one of the following methods: 174 * Put a CA-provided challenge at a specific place on the web 175 server. 177 * Put a CA-provided challenge at a DNS location corresponding to 178 the target domain. 180 * Receive CA challenge at a (hopefully) administrator-controlled 181 email address corresponding to the domain and then respond to 182 it on the CA's web page. 184 o Download the issued certificate and install it on their Web 185 Server. 187 With the exception of the CSR itself and the certificates that are 188 issued, these are all completely ad hoc procedures and are 189 accomplished by getting the human user to follow interactive natural- 190 language instructions from the CA rather than by machine-implemented 191 published protocols. In many cases, the instructions are difficult 192 to follow and cause significant confusion. Informal usability tests 193 by the authors indicate that webmasters often need 1-3 hours to 194 obtain and install a certificate for a domain. Even in the best 195 case, the lack of published, standardized mechanisms presents an 196 obstacle to the wide deployment of HTTPS and other PKIX-dependent 197 systems because it inhibits mechanization of tasks related to 198 certificate issuance, deployment, and revocation. 200 This document describes an extensible framework for automating the 201 issuance and domain validation procedure, thereby allowing servers 202 and infrastructural software to obtain certificates without user 203 interaction. Use of this protocol should radically simplify the 204 deployment of HTTPS and the practicality of PKIX authentication for 205 other protocols based on Transport Layer Security (TLS) [RFC5246]. 207 It should be noted that while the focus of this document is on 208 validating domain names for purposes of issuing certificates in the 209 Web PKI, ACME supports extensions for uses with other identifiers in 210 other PKI contexts. For example, as of this writing, there is 211 ongoing work to use ACME for issuance of WebPKI certificates 212 attesting to IP addresses [I-D.ietf-acme-ip] and STIR certificates 213 attesting to telephone numbers [I-D.ietf-acme-telephone]. 215 2. Deployment Model and Operator Experience 217 The guiding use case for ACME is obtaining certificates for websites 218 (HTTPS [RFC2818]). In this case, the user's web server is intended 219 to speak for one or more domains, and the process of certificate 220 issuance is intended to verify that this web server actually speaks 221 for the domain(s). 223 DV certificate validation commonly checks claims about properties 224 related to control of a domain name - properties that can be observed 225 by the certificate issuer in an interactive process that can be 226 conducted purely online. That means that under typical 227 circumstances, all steps in the request, verification, and issuance 228 process can be represented and performed by Internet protocols with 229 no out-of-band human intervention. 231 Prior to ACME, when deploying an HTTPS server, an operator typically 232 gets a prompt to generate a self-signed certificate. If the operator 233 were instead deploying an HTTPS server using ACME, the experience 234 would be something like this: 236 o The ACME client prompts the operator for the intended domain 237 name(s) that the web server is to stand for. 239 o The ACME client presents the operator with a list of CAs from 240 which it could get a certificate. (This list will change over 241 time based on the capabilities of CAs and updates to ACME 242 configuration.) The ACME client might prompt the operator for 243 payment information at this point. 245 o The operator selects a CA. 247 o In the background, the ACME client contacts the CA and requests 248 that it issue a certificate for the intended domain name(s). 250 o The CA verifies that the client controls the requested domain 251 name(s). 253 o Once the CA is satisfied, the certificate is issued and the ACME 254 client automatically downloads and installs it, potentially 255 notifying the operator via email, SMS, etc. 257 o The ACME client periodically contacts the CA to get updated 258 certificates, stapled OCSP responses, or whatever else would be 259 required to keep the web server functional and its credentials up- 260 to-date. 262 In this way, it would be nearly as easy to deploy with a CA-issued 263 certificate as with a self-signed certificate. Furthermore, the 264 maintenance of that CA-issued certificate would require minimal 265 manual intervention. Such close integration of ACME with HTTPS 266 servers allows the immediate and automated deployment of certificates 267 as they are issued, sparing the human administrator from much of the 268 time-consuming work described in the previous section. 270 3. Terminology 272 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 273 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 274 document are to be interpreted as described in RFC 2119 [RFC2119]. 276 The two main roles in ACME are "client" and "server". The ACME 277 client uses the protocol to request certificate management actions, 278 such as issuance or revocation. An ACME client may run on a web 279 server, mail server, or some other server system which requires valid 280 TLS certificates. Or, it may run on a separate server that does not 281 consume the certificate, but is authorized to respond to a CA- 282 provided challenge. The ACME server runs at a certification 283 authority, and responds to client requests, performing the requested 284 actions if the client is authorized. 286 An ACME client is represented by an "account key pair". The client 287 uses the private key of this key pair to sign all messages sent to 288 the server. The server uses the public key to verify the 289 authenticity and integrity of messages from the client. 291 4. Protocol Overview 293 ACME allows a client to request certificate management actions using 294 a set of JavaScript Object Notation (JSON) messages carried over 295 HTTPS. In many ways, ACME functions much like a traditional CA, in 296 which a user creates an account, requests a certificate, and proves 297 control of the domains in that certificate in order for the CA to 298 sign the requested certificate. 300 The first phase of ACME is for the client to request an account with 301 the ACME server. The client generates an asymmetric key pair and 302 requests a new account, optionally providing contact information, 303 agreeing to terms of service, and/or associating the account with an 304 existing account in another system. The creation request is signed 305 with the generated private key to prove that the client controls it. 307 Client Server 309 Contact Information 310 ToS Agreement 311 Additional Data 312 Signature -------> 314 <------- Account 316 Once an account is registered, there are three major steps the client 317 needs to take to get a certificate: 319 1. Submit an order for a certificate to be issued 321 2. Prove control of any identifiers requested in the certificate 323 3. Await issuance and download the issued certificate 325 The client's order for a certificate describes the desired 326 certificate using a PKCS#10 Certificate Signing Request (CSR) plus a 327 few additional fields that capture semantics that are not supported 328 in the CSR format. If the server is willing to consider issuing such 329 a certificate, it responds with a list of requirements that the 330 client must satisfy before the certificate will be issued. 332 For example, in most cases, the server will require the client to 333 demonstrate that it controls the identifiers in the requested 334 certificate. Because there are many different ways to validate 335 possession of different types of identifiers, the server will choose 336 from an extensible set of challenges that are appropriate for the 337 identifier being claimed. The client responds with a set of 338 responses that tell the server which challenges the client has 339 completed. The server then validates the challenges to check that 340 the client has accomplished them. 342 Once the validation process is complete and the server is satisfied 343 that the client has met its requirements, the server will issue the 344 requested certificate and make it available to the client. 346 Order 347 Signature -------> 348 Required 349 <------- Authorizations 351 Responses 352 Signature -------> 354 <~~~~~~~~Validation~~~~~~~~> 356 <------- Certificate 358 To revoke a certificate, the client sends a signed revocation request 359 indicating the certificate to be revoked: 361 Client Server 363 Revocation request 364 Signature --------> 366 <-------- Result 368 Note that while ACME is defined with enough flexibility to handle 369 different types of identifiers in principle, the primary use case 370 addressed by this document is the case where domain names are used as 371 identifiers. For example, all of the identifier validation 372 challenges described in Section 8 below address validation of domain 373 names. The use of ACME for other identifiers will require further 374 specification in order to describe how these identifiers are encoded 375 in the protocol and what types of validation challenges the server 376 might require. 378 5. Character Encoding 380 All requests and responses sent via HTTP by ACME clients, ACME 381 servers, and validation servers as well as any inputs for digest 382 computations MUST be encoded using the UTF-8 [RFC3629] character set. 384 6. Message Transport 386 Communications between an ACME client and an ACME server are done 387 over HTTPS, using JSON Web Signature (JWS) [RFC7515] to provide some 388 additional security properties for messages sent from the client to 389 the server. HTTPS provides server authentication and 390 confidentiality. With some ACME-specific extensions, JWS provides 391 authentication of the client's request payloads, anti-replay 392 protection, and integrity for the HTTPS request URL. 394 6.1. HTTPS Requests 396 Each ACME function is accomplished by the client sending a sequence 397 of HTTPS requests to the server, carrying JSON messages 398 [RFC2818][RFC7159]. Use of HTTPS is REQUIRED. Each subsection of 399 Section 7 below describes the message formats used by the function 400 and the order in which messages are sent. 402 In most HTTPS transactions used by ACME, the ACME client is the HTTPS 403 client and the ACME server is the HTTPS server. The ACME server acts 404 as an HTTP and HTTPS client when validating challenges via HTTP. 406 ACME servers SHOULD follow the recommendations of [RFC7525] when 407 configuring their TLS implementations. ACME servers that support TLS 408 1.3 MAY allow clients to send early data (0xRTT). This is safe 409 because the ACME protocol itself includes anti-replay protections. 411 ACME clients SHOULD send a User-Agent header in accordance with 412 [RFC7231], including the name and version of the ACME software in 413 addition to the name and version of the underlying HTTP client 414 software. 416 ACME clients SHOULD send an Accept-Language header in accordance with 417 [RFC7231] to enable localization of error messages. 419 ACME servers that are intended to be generally accessible need to use 420 Cross-Origin Resource Sharing (CORS) in order to be accessible from 421 browser-based clients [W3C.CR-cors-20130129]. Such servers SHOULD 422 set the Access-Control-Allow-Origin header field to the value "*". 424 Binary fields in the JSON objects used by ACME are encoded using 425 base64url encoding described in [RFC4648] Section 5, according to the 426 profile specified in JSON Web Signature [RFC7515] Section 2. This 427 encoding uses a URL safe character set. Trailing '=' characters MUST 428 be stripped. 430 6.2. Request Authentication 432 All ACME requests with a non-empty body MUST encapsulate their 433 payload in a JSON Web Signature (JWS) [RFC7515] object, signed using 434 the account's private key unless otherwise specified. The server 435 MUST verify the JWS before processing the request. Encapsulating 436 request bodies in JWS provides authentication of requests. 438 JWS objects sent in ACME requests MUST meet the following additional 439 criteria: 441 o The JWS MUST NOT have the value "none" in its "alg" field 443 o The JWS MUST NOT have a Message Authentication Code (MAC)-based 444 algorithm in its "alg" field 446 o The JWS Protected Header MUST include the following fields: 448 * "alg" (Algorithm) 450 * "jwk" (JSON Web Key, only for requests to new-account and 451 revoke-cert resources) 453 * "kid" (Key ID, for all other requests) 455 * "nonce" (defined in Section 6.4 below) 457 * "url" (defined in Section 6.3 below) 459 The "jwk" and "kid" fields are mutually exclusive. Servers MUST 460 reject requests that contain both. 462 For new-account requests, and for revoke-cert requests authenticated 463 by certificate key, there MUST be a "jwk" field. 465 For all other requests, there MUST be a "kid" field. This field must 466 contain the account URL received by POSTing to the new-account 467 resource. 469 Note that authentication via signed JWS request bodies implies that 470 GET requests are not authenticated. Servers MUST NOT respond to GET 471 requests for resources that might be considered sensitive. Account 472 resources are the only sensitive resources defined in this 473 specification. 475 If the client sends a JWS signed with an algorithm that the server 476 does not support, then the server MUST return an error with status 477 code 400 (Bad Request) and type 478 "urn:ietf:params:acme:error:badSignatureAlgorithm". The problem 479 document returned with the error MUST include an "algorithms" field 480 with an array of supported "alg" values. 482 In the examples below, JWS objects are shown in the JSON or flattened 483 JSON serialization, with the protected header and payload expressed 484 as base64url(content) instead of the actual base64-encoded value, so 485 that the content is readable. 487 6.3. Request URL Integrity 489 It is common in deployment for the entity terminating TLS for HTTPS 490 to be different from the entity operating the logical HTTPS server, 491 with a "request routing" layer in the middle. For example, an ACME 492 CA might have a content delivery network terminate TLS connections 493 from clients so that it can inspect client requests for denial-of- 494 service protection. 496 These intermediaries can also change values in the request that are 497 not signed in the HTTPS request, e.g., the request URL and headers. 498 ACME uses JWS to provide an integrity mechanism, which protects 499 against an intermediary changing the request URL to another ACME URL. 501 As noted in Section 6.2 above, all ACME request objects carry a "url" 502 header parameter in their protected header. This header parameter 503 encodes the URL to which the client is directing the request. On 504 receiving such an object in an HTTP request, the server MUST compare 505 the "url" header parameter to the request URL. If the two do not 506 match, then the server MUST reject the request as unauthorized. 508 Except for the directory resource, all ACME resources are addressed 509 with URLs provided to the client by the server. For these resources, 510 the client MUST set the "url" header parameter to the exact string 511 provided by the server (rather than performing any re-encoding on the 512 URL). The server SHOULD perform the corresponding string equality 513 check, configuring each resource with the URL string provided to 514 clients and having the resource check that requests have the same 515 string in their "url" header parameter. 517 6.3.1. "url" (URL) JWS header parameter 519 The "url" header parameter specifies the URL [RFC3986] to which this 520 JWS object is directed. The "url" header parameter MUST be carried 521 in the protected header of the JWS. The value of the "url" header 522 parameter MUST be a string representing the URL. 524 6.4. Replay protection 526 In order to protect ACME resources from any possible replay attacks, 527 ACME requests have a mandatory anti-replay mechanism. This mechanism 528 is based on the server maintaining a list of nonces that it has 529 issued to clients, and requiring any signed request from the client 530 to carry such a nonce. 532 An ACME server provides nonces to clients using the Replay-Nonce 533 header field, as specified in Section 6.4.1 below. The server MUST 534 include a Replay-Nonce header field in every successful response to a 535 POST request and SHOULD provide it in error responses as well. 537 Every JWS sent by an ACME client MUST include, in its protected 538 header, the "nonce" header parameter, with contents as defined in 539 Section 6.4.2 below. As part of JWS verification, the ACME server 540 MUST verify that the value of the "nonce" header is a value that the 541 server previously provided in a Replay-Nonce header field. Once a 542 nonce value has appeared in an ACME request, the server MUST consider 543 it invalid, in the same way as a value it had never issued. 545 When a server rejects a request because its nonce value was 546 unacceptable (or not present), it MUST provide HTTP status code 400 547 (Bad Request), and indicate the ACME error type 548 "urn:ietf:params:acme:error:badNonce". An error response with the 549 "badNonce" error type MUST include a Replay-Nonce header with a fresh 550 nonce. On receiving such a response, a client SHOULD retry the 551 request using the new nonce. 553 The precise method used to generate and track nonces is up to the 554 server. For example, the server could generate a random 128-bit 555 value for each response, keep a list of issued nonces, and strike 556 nonces from this list as they are used. 558 6.4.1. Replay-Nonce 560 The "Replay-Nonce" header field includes a server-generated value 561 that the server can use to detect unauthorized replay in future 562 client requests. The server MUST generate the value provided in 563 Replay-Nonce in such a way that they are unique to each message, with 564 high probability. For instance, it is acceptable to generate Replay- 565 Nonces randomly. 567 The value of the Replay-Nonce field MUST be an octet string encoded 568 according to the base64url encoding described in Section 2 of 569 [RFC7515]. Clients MUST ignore invalid Replay-Nonce values. 571 base64url = [A-Z] / [a-z] / [0-9] / "-" / "_" 573 Replay-Nonce = *base64url 575 The Replay-Nonce header field SHOULD NOT be included in HTTP request 576 messages. 578 6.4.2. "nonce" (Nonce) JWS header parameter 580 The "nonce" header parameter provides a unique value that enables the 581 verifier of a JWS to recognize when replay has occurred. The "nonce" 582 header parameter MUST be carried in the protected header of the JWS. 584 The value of the "nonce" header parameter MUST be an octet string, 585 encoded according to the base64url encoding described in Section 2 of 586 [RFC7515]. If the value of a "nonce" header parameter is not valid 587 according to this encoding, then the verifier MUST reject the JWS as 588 malformed. 590 6.5. Rate limits 592 Creation of resources can be rate limited to ensure fair usage and 593 prevent abuse. Once the rate limit is exceeded, the server MUST 594 respond with an error with the type 595 "urn:ietf:params:acme:error:rateLimited". Additionally, the server 596 SHOULD send a "Retry-After" header indicating when the current 597 request may succeed again. If multiple rate limits are in place, 598 that is the time where all rate limits allow access again for the 599 current request with exactly the same parameters. 601 In addition to the human-readable "detail" field of the error 602 response, the server MAY send one or multiple tokens in the "Link" 603 header pointing to documentation about the specific hit rate limits 604 using the "urn:ietf:params:acme:documentation" relation. 606 6.6. Errors 608 Errors can be reported in ACME both at the HTTP layer and within 609 challenge objects as defined in Section 8. ACME servers can return 610 responses with an HTTP error response code (4XX or 5XX). For 611 example: If the client submits a request using a method not allowed 612 in this document, then the server MAY return status code 405 (Method 613 Not Allowed). 615 When the server responds with an error status, it SHOULD provide 616 additional information using a problem document [RFC7807]. To 617 facilitate automatic response to errors, this document defines the 618 following standard tokens for use in the "type" field (within the 619 "urn:ietf:params:acme:error:" namespace): 621 +-----------------------+-------------------------------------------+ 622 | Type | Description | 623 +-----------------------+-------------------------------------------+ 624 | badCSR | The CSR is unacceptable (e.g., due to a | 625 | | short key) | 626 | | | 627 | badNonce | The client sent an unacceptable anti- | 628 | | replay nonce | 629 | | | 630 | badSignatureAlgorithm | The JWS was signed with an algorithm the | 631 | | server does not support | 632 | | | 633 | invalidContact | A contact URL for an account was invalid | 634 | | | 635 | unsupportedContact | A contact URL for an account used an | 636 | | unsupported protocol scheme | 637 | | | 638 | accountDoesNotExist | The request specified an account that | 639 | | does not exist | 640 | | | 641 | malformed | The request message was malformed | 642 | | | 643 | rateLimited | The request exceeds a rate limit | 644 | | | 645 | rejectedIdentifier | The server will not issue for the | 646 | | identifier | 647 | | | 648 | serverInternal | The server experienced an internal error | 649 | | | 650 | unauthorized | The client lacks sufficient authorization | 651 | | | 652 | unsupportedIdentifier | Identifier is not supported, but may be | 653 | | in future | 654 | | | 655 | userActionRequired | Visit the "instance" URL and take actions | 656 | | specified there | 657 | | | 658 | badRevocationReason | The revocation reason provided is not | 659 | | allowed by the server | 660 | | | 661 | caa | Certification Authority Authorization | 662 | | (CAA) records forbid the CA from issuing | 663 | | | 664 | dns | There was a problem with a DNS query | 665 | | | 666 | connection | The server could not connect to | 667 | | validation target | 668 | | | 669 | tls | The server received a TLS error during | 670 | | validation | 671 | | | 672 | incorrectResponse | Response received didn't match the | 673 | | challenge's requirements | 674 +-----------------------+-------------------------------------------+ 676 This list is not exhaustive. The server MAY return errors whose 677 "type" field is set to a URI other than those defined above. Servers 678 MUST NOT use the ACME URN [RFC3553] namespace for errors other than 679 the standard types. Clients SHOULD display the "detail" field of all 680 errors. 682 7. Certificate Management 684 In this section, we describe the certificate management functions 685 that ACME enables: 687 o Account Creation 689 o Ordering a Certificate 691 o Identifier Authorization 693 o Certificate Issuance 695 o Certificate Revocation 697 7.1. Resources 699 ACME is structured as a REST application with the following types of 700 resources: 702 o Account resources, representing information about an account 703 (Section 7.1.2, Section 7.3) 705 o Order resources, representing an account's requests to issue 706 certificates (Section 7.1.3) 708 o Authorization resources, representing an account's authorization 709 to act for an identifier (Section 7.1.4) 711 o Challenge resources, representing a challenge to prove control of 712 an identifier (Section 7.5, Section 8) 714 o Certificate resources, representing issued certificates 715 (Section 7.4.2) 717 o A "directory" resource (Section 7.1.1) 719 o A "new-nonce" resource (Section 7.2) 721 o A "new-account" resource (Section 7.3) 723 o A "new-order" resource (Section 7.4) 725 o A "revoke-cert" resource (Section 7.6) 727 o A "key-change" resource (Section 7.3.6) 729 The server MUST provide "directory" and "new-nonce" resources. 731 ACME uses different URLs for different management functions. Each 732 function is listed in a directory along with its corresponding URL, 733 so clients only need to be configured with the directory URL. These 734 URLs are connected by a few different link relations [RFC5988]. 736 The "up" link relation is used with challenge resources to indicate 737 the authorization resource to which a challenge belongs. It is also 738 used from certificate resources to indicate a resource from which the 739 client may fetch a chain of CA certificates that could be used to 740 validate the certificate in the original resource. 742 The "index" link relation is present on all resources other than the 743 directory and indicates the URL of the directory. 745 The following diagram illustrates the relations between resources on 746 an ACME server. For the most part, these relations are expressed by 747 URLs provided as strings in the resources' JSON representations. 748 Lines with labels in quotes indicate HTTP link relations. 750 directory 751 | 752 |--> new-nonce 753 | 754 ----------------------------------+ 755 | | | | 756 | | | | 757 V V V V 758 new-account new-authz new-order revoke-cert 759 | | | 760 | | | 761 V | V 762 account | order -----> cert 763 | | 764 | | 765 | V 766 +------> authz 767 | ^ 768 | | "up" 769 V | 770 challenge 772 The following table illustrates a typical sequence of requests 773 required to establish a new account with the server, prove control of 774 an identifier, issue a certificate, and fetch an updated certificate 775 some time after issuance. The "->" is a mnemonic for a Location 776 header pointing to a created resource. 778 +----------------------+------------------+----------------+ 779 | Action | Request | Response | 780 +----------------------+------------------+----------------+ 781 | Get a nonce | HEAD new-nonce | 204 | 782 | | | | 783 | Create account | POST new-account | 201 -> account | 784 | | | | 785 | Submit an order | POST new-order | 201 -> order | 786 | | | | 787 | Fetch challenges | GET authz | 200 | 788 | | | | 789 | Respond to challenge | POST challenge | 200 | 790 | | | | 791 | Poll for status | GET authz | 200 | 792 | | | | 793 | Check for new cert | GET cert | 200 | 794 +----------------------+------------------+----------------+ 796 The remainder of this section provides the details of how these 797 resources are structured and how the ACME protocol makes use of them. 799 7.1.1. Directory 801 In order to help clients configure themselves with the right URLs for 802 each ACME operation, ACME servers provide a directory object. This 803 should be the only URL needed to configure clients. It is a JSON 804 object, whose fields names are drawn from the following table and 805 whose values are the corresponding URLs. 807 +-------------+--------------------+ 808 | Field | URL in value | 809 +-------------+--------------------+ 810 | new-nonce | New nonce | 811 | | | 812 | new-account | New account | 813 | | | 814 | new-order | New order | 815 | | | 816 | new-authz | New authorization | 817 | | | 818 | revoke-cert | Revoke certificate | 819 | | | 820 | key-change | Key change | 821 +-------------+--------------------+ 823 There is no constraint on the actual URL of the directory except that 824 it should be different from the other ACME server resources' URLs, 825 and that it should not clash with other services. For instance: 827 o a host which functions as both an ACME and a Web server may want 828 to keep the root path "/" for an HTML "front page", and place the 829 ACME directory under the path "/acme". 831 o a host which only functions as an ACME server could place the 832 directory under the path "/". 834 The object MAY additionally contain a field "meta". If present, it 835 MUST be a JSON object; each field in the object is an item of 836 metadata relating to the service provided by the ACME server. 838 The following metadata items are defined, all of which are OPTIONAL: 840 "terms-of-service" (optional, string): A URL identifying the current 841 terms of service. 843 "website" (optional, string): An HTTP or HTTPS URL locating a 844 website providing more information about the ACME server. 846 "caa-identities" (optional, array of string): Each string MUST be a 847 lowercase hostname which the ACME server recognizes as referring 848 to itself for the purposes of CAA record validation as defined in 849 [RFC6844]. This allows clients to determine the correct issuer 850 domain name to use when configuring CAA records. 852 Clients access the directory by sending a GET request to the 853 directory URL. 855 HTTP/1.1 200 OK 856 Content-Type: application/json 858 { 859 "new-nonce": "https://example.com/acme/new-nonce", 860 "new-account": "https://example.com/acme/new-account", 861 "new-order": "https://example.com/acme/new-order", 862 "new-authz": "https://example.com/acme/new-authz", 863 "revoke-cert": "https://example.com/acme/revoke-cert", 864 "key-change": "https://example.com/acme/key-change", 865 "meta": { 866 "terms-of-service": "https://example.com/acme/terms/2017-5-30", 867 "website": "https://www.example.com/", 868 "caa-identities": ["example.com"] 869 } 870 } 872 7.1.2. Account Objects 874 An ACME account resource represents a set of metadata associated with 875 an account. Account resources have the following structure: 877 status (required, string): The status of this account. Possible 878 values are: "valid", "deactivated", and "revoked". The value 879 "deactivated" should be used to indicate client-initiated 880 deactivation whereas "revoked" should be used to indicate server- 881 initiated deactivation. 883 contact (optional, array of string): An array of URLs that the 884 server can use to contact the client for issues related to this 885 account. For example, the server may wish to notify the client 886 about server-initiated revocation or certificate expiration. 888 terms-of-service-agreed (optional, boolean): Including this field in 889 a new-account request, with a value of true, indicates the 890 client's agreement with the terms of service. This field is not 891 updateable by the client. 893 orders (required, string): A URL from which a list of orders 894 submitted by this account can be fetched via a GET request, as 895 described in Section 7.1.2.1. 897 { 898 "status": "valid", 899 "contact": [ 900 "mailto:cert-admin@example.com", 901 "tel:+12025551212" 902 ], 903 "terms-of-service-agreed": true, 904 "orders": "https://example.com/acme/acct/1/orders" 905 } 907 7.1.2.1. Orders List 909 Each account object includes an "orders" URL from which a list of 910 orders created by the account can be fetched via GET request. The 911 result of the GET request MUST be a JSON object whose "orders" field 912 is an array of URLs, each identifying an order belonging to the 913 account. The server SHOULD include pending orders, and SHOULD NOT 914 include orders that are invalid in the array of URLs. The server MAY 915 return an incomplete list, along with a Link header with a "next" 916 link relation indicating where further entries can be acquired. 918 HTTP/1.1 200 OK 919 Content-Type: application/json 920 Link: href="/acme/acct/1/orders?cursor=2", rel="next" 922 { 923 "orders": [ 924 "https://example.com/acme/acct/1/order/1", 925 "https://example.com/acme/acct/1/order/2", 926 /* 47 more URLs not shown for example brevity */ 927 "https://example.com/acme/acct/1/order/50" 928 ] 929 } 931 7.1.3. Order Objects 933 An ACME order object represents a client's request for a certificate 934 and is used to track the progress of that order through to issuance. 935 Thus, the object contains information about the requested 936 certificate, the authorizations that the server requires the client 937 to complete, and any certificates that have resulted from this order. 939 status (required, string): The status of this order. Possible 940 values are: "pending", "processing", "valid", and "invalid". 942 expires (optional, string): The timestamp after which the server 943 will consider this order invalid, encoded in the format specified 944 in RFC 3339 [RFC3339]. This field is REQUIRED for objects with 945 "pending" or "valid" in the status field. 947 csr (required, string): A CSR encoding the parameters for the 948 certificate being requested [RFC2986]. The CSR is sent in the 949 base64url-encoded version of the DER format. (Note: Because this 950 field uses base64url, and does not include headers, it is 951 different from PEM.) 953 notBefore (optional, string): The requested value of the notBefore 954 field in the certificate, in the date format defined in [RFC3339]. 956 notAfter (optional, string): The requested value of the notAfter 957 field in the certificate, in the date format defined in [RFC3339]. 959 error (optional, object): The error that occurred while processing 960 the order, if any. This field is structured as a problem document 961 [RFC7807]. 963 authorizations (required, array of string): For pending orders, the 964 authorizations that the client needs to complete before the 965 requested certificate can be issued (see Section 7.5). For final 966 orders, the authorizations that were completed. Each entry is a 967 URL from which an authorization can be fetched with a GET request. 969 certificate (optional, string): A URL for the certificate that has 970 been issued in response to this order. 972 { 973 "status": "pending", 974 "expires": "2015-03-01T14:09:00Z", 976 "csr": "jcRf4uXra7FGYW5ZMewvV...rhlnznwy8YbpMGqwidEXfE", 977 "notBefore": "2016-01-01T00:00:00Z", 978 "notAfter": "2016-01-08T00:00:00Z", 980 "authorizations": [ 981 "https://example.com/acme/authz/1234", 982 "https://example.com/acme/authz/2345" 983 ], 985 "certificate": "https://example.com/acme/cert/1234" 986 } 988 The elements of the "authorizations" array are immutable once set. 989 The server MUST NOT change the contents of the "authorizations" array 990 after it is created. If a client observes a change in the contents 991 of the "authorizations" array, then it SHOULD consider the order 992 invalid. 994 The "authorizations" array in the challenge SHOULD reflect all 995 authorizations that the CA takes into account in deciding to issue, 996 even if some authorizations were fulfilled in earlier orders or in 997 pre-authorization transactions. For example, if a CA allows multiple 998 orders to be fulfilled based on a single authorization transaction, 999 then it SHOULD reflect that authorization in all of the orders. 1001 7.1.4. Authorization Objects 1003 An ACME authorization object represents a server's authorization for 1004 an account to represent an identifier. In addition to the 1005 identifier, an authorization includes several metadata fields, such 1006 as the status of the authorization (e.g., "pending", "valid", or 1007 "revoked") and which challenges were used to validate possession of 1008 the identifier. 1010 The structure of an ACME authorization resource is as follows: 1012 identifier (required, object): The identifier that the account is 1013 authorized to represent 1015 type (required, string): The type of identifier. 1017 value (required, string): The identifier itself. 1019 status (required, string): The status of this authorization. 1020 Possible values are: "pending", "processing", "valid", "invalid" 1021 and "revoked". 1023 expires (optional, string): The timestamp after which the server 1024 will consider this authorization invalid, encoded in the format 1025 specified in RFC 3339 [RFC3339]. This field is REQUIRED for 1026 objects with "valid" in the "status" field. 1028 scope (optional, string): If this field is present, then it MUST 1029 contain a URL for an order resource, such that this authorization 1030 is only valid for that resource. If this field is absent, then 1031 the CA MUST consider this authorization valid for all orders until 1032 the authorization expires. 1034 challenges (required, array of objects): For pending authorizations, 1035 the challenges that the client can fulfill in order to prove 1036 possession of the identifier. For final authorizations, the 1037 challenges that were used. Each array entry is an object with 1038 parameters required to validate the challenge. A client should 1039 attempt to fulfill one of these challenges, and a server should 1040 consider any one of the challenges sufficient to make the 1041 authorization valid. For final authorizations, it contains the 1042 challenges that were successfully completed. 1044 The only type of identifier defined by this specification is a fully- 1045 qualified domain name (type: "dns"). If a domain name contains non- 1046 ASCII Unicode characters it MUST be encoded using the rules defined 1047 in [RFC3492]. Servers MUST verify any identifier values that begin 1048 with the ASCII Compatible Encoding prefix "xn-" as defined in 1049 [RFC5890] are properly encoded. Wildcard domain names (with "*" as 1050 the first label) MUST NOT be included in authorization objects. 1052 Section 8 describes a set of challenges for domain name validation. 1054 { 1055 "status": "valid", 1056 "expires": "2015-03-01T14:09:00Z", 1058 "identifier": { 1059 "type": "dns", 1060 "value": "example.org" 1061 }, 1063 "challenges": [ 1064 { 1065 "url": "https://example.com/authz/1234/0", 1066 "type": "http-01", 1067 "status": "valid", 1068 "token": "DGyRejmCefe7v4NfDGDKfA" 1069 "validated": "2014-12-01T12:05:00Z", 1070 "keyAuthorization": "SXQe-2XODaDxNR...vb29HhjjLPSggwiE" 1071 } 1072 ] 1073 } 1075 7.2. Getting a Nonce 1077 Before sending a POST request to the server, an ACME client needs to 1078 have a fresh anti-replay nonce to put in the "nonce" header of the 1079 JWS. In most cases, the client will have gotten a nonce from a 1080 previous request. However, the client might sometimes need to get a 1081 new nonce, e.g., on its first request to the server or if an existing 1082 nonce is no longer valid. 1084 To get a fresh nonce, the client sends a HEAD request to the new- 1085 nonce resource on the server. The server's response MUST include a 1086 Replay-Nonce header field containing a fresh nonce, and SHOULD have 1087 status code 204 (No Content). The server SHOULD also respond to GET 1088 requests for this resource, returning an empty body (while still 1089 providing a Replay-Nonce header) with a 204 (No Content) status. 1091 HEAD /acme/new-nonce HTTP/1.1 1092 Host: example.com 1094 HTTP/1.1 204 No Content 1095 Replay-Nonce: oFvnlFP1wIhRlYS2jTaXbA 1096 Cache-Control: no-store 1098 Proxy caching of responses from the new-nonce resource can cause 1099 clients receive the same nonce repeatedly, leading to badNonce 1100 errors. The server MUST include a Cache-Control header field with 1101 the "no-store" directive in responses for the new-nonce resource, in 1102 order to prevent caching of this resource. 1104 7.3. Account Creation 1106 A client creates a new account with the server by sending a POST 1107 request to the server's new-account URL. The body of the request is 1108 a stub account object containing the "contact" field and optionally 1109 the "terms-of-service-agreed" field. 1111 contact (optional, array of string): Same meaning as the 1112 corresponding server field defined in Section 7.1.2 1114 terms-of-service-agreed (optional, boolean): Same meaning as the 1115 corresponding server field defined in Section 7.1.2 1117 only-return-existing (optional, boolean): If this field is present 1118 with the value "true", then the server MUST NOT create a new 1119 account if one does not already exist. This allows a client to 1120 look up an account URL based on an account key (see 1121 Section 7.3.1). 1123 POST /acme/new-account HTTP/1.1 1124 Host: example.com 1125 Content-Type: application/jose+json 1127 { 1128 "protected": base64url({ 1129 "alg": "ES256", 1130 "jwk": {...}, 1131 "nonce": "6S8IqOGY7eL2lsGoTZYifg", 1132 "url": "https://example.com/acme/new-account" 1133 }), 1134 "payload": base64url({ 1135 "terms-of-service-agreed": true, 1136 "contact": [ 1137 "mailto:cert-admin@example.com", 1138 "tel:+12025551212" 1139 ] 1140 }), 1141 "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I" 1142 } 1144 The server MUST ignore any values provided in the "orders" fields in 1145 account bodies sent by the client, as well as any other fields that 1146 it does not recognize. If new fields are specified in the future, 1147 the specification of those fields MUST describe whether they can be 1148 provided by the client. 1150 In general, the server MUST ignore any fields in the request object 1151 that it does not recognize. In particular, it MUST NOT reflect 1152 unrecognized fields in the resulting account object. This allows 1153 clients to detect when servers do not support an extension field. 1155 The server SHOULD validate that the contact URLs in the "contact" 1156 field are valid and supported by the server. If the server validates 1157 contact URLs it MUST support the "mailto" scheme. Clients MUST NOT 1158 provide a "mailto" URL in the "contact" field that contains "hfields" 1159 [RFC6068], or more than one "addr-spec" in the "to" component. If a 1160 server encounters a "mailto" contact URL that does not meet these 1161 criteria, then it SHOULD reject it as invalid. 1163 If the server rejects a contact URL for using an unsupported scheme 1164 it MUST return an error of type "unsupportedContact", with a 1165 description describing the error and what types of contact URLs the 1166 server considers acceptable. If the server rejects a contact URL for 1167 using a supported scheme but an invalid value then the server MUST 1168 return an error of type "invalidContact". 1170 If the server wishes to present the client with terms under which the 1171 ACME service is to be used, it MUST indicate the URL where such terms 1172 can be accessed in the "terms-of-service" subfield of the "meta" 1173 field in the directory object, and the server MUST reject new-account 1174 requests that do not have the "terms-of-service-agreed" set to 1175 "true". Clients SHOULD NOT automatically agree to terms by default. 1176 Rather, they SHOULD require some user interaction for agreement to 1177 terms. 1179 The server creates an account and stores the public key used to 1180 verify the JWS (i.e., the "jwk" element of the JWS header) to 1181 authenticate future requests from the account. The server returns 1182 this account object in a 201 (Created) response, with the account URL 1183 in a Location header field. 1185 HTTP/1.1 201 Created 1186 Content-Type: application/json 1187 Replay-Nonce: D8s4D2mLs8Vn-goWuPQeKA 1188 Location: https://example.com/acme/acct/1 1189 Link: ;rel="index" 1191 { 1192 "status": "valid", 1194 "contact": [ 1195 "mailto:cert-admin@example.com", 1196 "tel:+12025551212" 1197 ] 1198 } 1200 7.3.1. Finding an Account URL Given a Key 1202 If the server already has an account registered with the provided 1203 account key, then it MUST return a response with a 200 (OK) status 1204 code and provide the URL of that account in the Location header 1205 field. This allows a client that has an account key but not the 1206 corresponding account URL to recover the account URL. 1208 If a client wishes to find the URL for an existing account and does 1209 not want an account to be created if one does not already exist, then 1210 it SHOULD do so by sending a POST request to the new-account URL with 1211 a JWS whose payload has an "only-return-existing" field set to "true" 1212 ({"only-return-existing": true}). If a client sends such a request 1213 and an account does not exist, then the server MUST return an error 1214 response with status code 400 (Bad Request) and type 1215 "urn:ietf:params:acme:error:accountDoesNotExist". 1217 7.3.2. Account Update 1219 If the client wishes to update this information in the future, it 1220 sends a POST request with updated information to the account URL. 1221 The server MUST ignore any updates to "order" fields or any other 1222 fields it does not recognize. If the server accepts the update, it 1223 MUST return a response with a 200 (OK) status code and the resulting 1224 account object. 1226 For example, to update the contact information in the above account, 1227 the client could send the following request: 1229 POST /acme/acct/1 HTTP/1.1 1230 Host: example.com 1231 Content-Type: application/jose+json 1233 { 1234 "protected": base64url({ 1235 "alg": "ES256", 1236 "kid": "https://example.com/acme/acct/1", 1237 "nonce": "ax5RnthDqp_Yf4_HZnFLmA", 1238 "url": "https://example.com/acme/acct/1" 1239 }), 1240 "payload": base64url({ 1241 "contact": [ 1242 "mailto:certificates@example.com", 1243 "tel:+12125551212" 1244 ] 1245 }), 1246 "signature": "hDXzvcj8T6fbFbmn...rDzXzzvzpRy64N0o" 1247 } 1249 7.3.3. Account Information 1251 Servers SHOULD NOT respond to GET requests for account resources as 1252 these requests are not authenticated. If a client wishes to query 1253 the server for information about its account (e.g., to examine the 1254 "contact" or "certificates" fields), then it SHOULD do so by sending 1255 a POST request with an empty update. That is, it should send a JWS 1256 whose payload is an empty object ({}). 1258 7.3.4. Changes of Terms of Service 1260 As described above, a client can indicate its agreement with the CA's 1261 terms of service by setting the "terms-of-service-agreed" field in 1262 its account object to "true". 1264 If the server has changed its terms of service since a client 1265 initially agreed, and the server is unwilling to process a request 1266 without explicit agreement to the new terms, then it MUST return an 1267 error response with status code 403 (Forbidden) and type 1268 "urn:ietf:params:acme:error:userActionRequired". This response MUST 1269 include a Link header with link relation "terms-of-service" and the 1270 latest terms-of-service URL. 1272 The problem document returned with the error MUST also include an 1273 "instance" field, indicating a URL that the client should direct a 1274 human user to visit in order for instructions on how to agree to the 1275 terms. 1277 HTTP/1.1 403 Forbidden 1278 Replay-Nonce: IXVHDyxIRGcTE0VSblhPzw 1279 Link: ;rel="terms-of-service" 1280 Content-Type: application/problem+json 1281 Content-Language: en 1283 { 1284 "type": "urn:ietf:params:acme:error:userActionRequired", 1285 "detail": "Terms of service have changed", 1286 "instance": "http://example.com/agreement/?token=W8Ih3PswD-8" 1287 } 1289 7.3.5. External Account Binding 1291 The server MAY require a value to be present for the "external- 1292 account-binding" field. This can be used to an ACME account with an 1293 existing account in a non-ACME system, such as a CA customer 1294 database. 1296 To enable ACME account binding, a CA needs to provision the ACME 1297 client with a MAC key and a key identifier. The key identifier MUST 1298 be an ASCII string. The MAC key SHOULD be provided in base64url- 1299 encoded form, to maximize compatibility between provisioning systems 1300 and ACME clients. 1302 The ACME client then computes a binding JWS to indicate the external 1303 account's approval of the ACME account key. The payload of this JWS 1304 is the account key being registered, in JWK form. The protected 1305 header of the JWS MUST meet the following criteria: 1307 o The "alg" field MUST indicate a MAC-based algorithm 1309 o The "kid" field MUST contain the key identifier provided by the CA 1311 o The "nonce" field MUST NOT be present 1312 o The "url" field MUST be set to the same value as the outer JWS 1314 The "signature" field of the JWS will contain the MAC value computed 1315 with the MAC key provided by the CA. 1317 POST /acme/new-account HTTP/1.1 1318 Host: example.com 1319 Content-Type: application/jose+json 1321 { 1322 "protected": base64url({ 1323 "alg": "ES256", 1324 "jwk": /* account key */, 1325 "nonce": "K60BWPrMQG9SDxBDS_xtSw", 1326 "url": "https://example.com/acme/new-account" 1327 }), 1328 "payload": base64url({ 1329 "contact": ["mailto:example@anonymous.invalid"], 1330 "terms-of-service-agreed": true, 1332 "external-account-binding": { 1333 "protected": base64url({ 1334 "alg": "HS256", 1335 "kid": /* key identifier from CA */, 1336 "url": "https://example.com/acme/new-account" 1337 }), 1338 "payload": base64url(/* same as in "jwk" above */), 1339 "signature": /* MAC using MAC key from CA */ 1340 } 1341 }), 1342 "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4" 1343 } 1345 When a CA receives a new-account request containing an "external- 1346 account-binding" field, it decides whether or not to verify the 1347 binding. If the CA does not verify the binding, then it MUST NOT 1348 reflect the "external-account-binding" field in the resulting account 1349 object (if any). To verify the account binding, the CA MUST take the 1350 following steps: 1352 1. Verify that the value of the field is a well-formed JWS 1354 2. Verify that the JWS protected meets the above criteria 1356 3. Retrieve the MAC key corresponding to the key identifier in the 1357 "kid" field 1359 4. Verify that the MAC on the JWS verifies using that MAC key 1360 5. Verify that the payload of the JWS represents the same key as was 1361 used to verify the outer JWS (i.e., the "jwk" field of the outer 1362 JWS) 1364 If all of these checks pass and the CA creates a new account, then 1365 the CA may consider the new account associated with the external 1366 account corresponding to the MAC key and MUST reflect value of the 1367 "external-account-binding" field in the resulting account object. If 1368 any of these checks fail, then the CA MUST reject the new-account 1369 request. 1371 7.3.6. Account Key Roll-over 1373 A client may wish to change the public key that is associated with an 1374 account in order to recover from a key compromise or proactively 1375 mitigate the impact of an unnoticed key compromise. 1377 To change the key associated with an account, the client first 1378 constructs a key-change object describing the change that it would 1379 like the server to make: 1381 account (required, string): The URL for account being modified. The 1382 content of this field MUST be the exact string provided in the 1383 Location header field in response to the new-account request that 1384 created the account. 1386 newKey (required, JWK): The JWK representation of the new key 1388 The client then encapsulates the key-change object in a JWS, signed 1389 with the requested new account key (i.e., the key matching the 1390 "newKey" value). 1392 The outer JWS MUST meet the normal requirements for an ACME JWS (see 1393 Section 6.2). The inner JWS MUST meet the normal requirements, with 1394 the following exceptions: 1396 o The inner JWS MUST have the same "url" header parameter as the 1397 outer JWS. 1399 o The inner JWS is NOT REQUIRED to have a "nonce" header parameter. 1400 The server MUST ignore any value provided for the "nonce" header 1401 parameter. 1403 This transaction has signatures from both the old and new keys so 1404 that the server can verify that the holders of the two keys both 1405 agree to the change. The signatures are nested to preserve the 1406 property that all signatures on POST messages are signed by exactly 1407 one key. 1409 POST /acme/key-change HTTP/1.1 1410 Host: example.com 1411 Content-Type: application/jose+json 1413 { 1414 "protected": base64url({ 1415 "alg": "ES256", 1416 "kid": "https://example.com/acme/acct/1", 1417 "nonce": "K60BWPrMQG9SDxBDS_xtSw", 1418 "url": "https://example.com/acme/key-change" 1419 }), 1420 "payload": base64url({ 1421 "protected": base64url({ 1422 "alg": "ES256", 1423 "jwk": /* new key */, 1424 "url": "https://example.com/acme/key-change" 1425 }), 1426 "payload": base64url({ 1427 "account": "https://example.com/acme/acct/1", 1428 "newKey": /* new key */ 1429 }), 1430 "signature": "Xe8B94RD30Azj2ea...8BmZIRtcSKPSd8gU" 1431 }), 1432 "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4" 1433 } 1435 On receiving key-change request, the server MUST perform the 1436 following steps in addition to the typical JWS validation: 1438 1. Validate the POST request belongs to a currently active account, 1439 as described in Section 6. 1441 2. Check that the payload of the JWS is a well-formed JWS object 1442 (the "inner JWS"). 1444 3. Check that the JWS protected header of the inner JWS has a "jwk" 1445 field. 1447 4. Check that the inner JWS verifies using the key in its "jwk" 1448 field. 1450 5. Check that the payload of the inner JWS is a well-formed key- 1451 change object (as described above). 1453 6. Check that the "url" parameters of the inner and outer JWSs are 1454 the same. 1456 7. Check that the "account" field of the key-change object contains 1457 the URL for the account matching the old key 1459 8. Check that the "newKey" field of the key-change object also 1460 verifies the inner JWS. 1462 9. Check that no account exists whose account key is the same as the 1463 key in the "newKey" field. 1465 If all of these checks pass, then the server updates the 1466 corresponding account by replacing the old account key with the new 1467 public key and returns status code 200 (OK). Otherwise, the server 1468 responds with an error status code and a problem document describing 1469 the error. If there is an existing account with the new key 1470 provided, then the server SHOULD use status code 409 (Conflict) and 1471 provide the URL of that account in the Location header field. 1473 Note that changing the account key for an account SHOULD NOT have any 1474 other impact on the account. For example, the server MUST NOT 1475 invalidate pending orders or authorization transactions based on a 1476 change of account key. 1478 7.3.7. Account Deactivation 1480 A client can deactivate an account by posting a signed update to the 1481 server with a status field of "deactivated." Clients may wish to do 1482 this when the account key is compromised or decommissioned. 1484 POST /acme/acct/1 HTTP/1.1 1485 Host: example.com 1486 Content-Type: application/jose+json 1488 { 1489 "protected": base64url({ 1490 "alg": "ES256", 1491 "kid": "https://example.com/acme/acct/1", 1492 "nonce": "ntuJWWSic4WVNSqeUmshgg", 1493 "url": "https://example.com/acme/acct/1" 1494 }), 1495 "payload": base64url({ 1496 "status": "deactivated" 1497 }), 1498 "signature": "earzVLd3m5M4xJzR...bVTqn7R08AKOVf3Y" 1499 } 1501 The server MUST verify that the request is signed by the account key. 1502 If the server accepts the deactivation request, it replies with a 200 1503 (OK) status code and the current contents of the account object. 1505 Once an account is deactivated, the server MUST NOT accept further 1506 requests authorized by that account's key. The server SHOULD cancel 1507 any pending operations authorized by the account's key, such as 1508 certificate orders. A server may take a variety of actions in 1509 response to an account deactivation, e.g., deleting data related to 1510 that account or sending mail to the account's contacts. Servers 1511 SHOULD NOT revoke certificates issued by the deactivated account, 1512 since this could cause operational disruption for servers using these 1513 certificates. ACME does not provide a way to reactivate a 1514 deactivated account. 1516 7.4. Applying for Certificate Issuance 1518 The client requests certificate issuance by sending a POST request to 1519 the server's new-order resource. The body of the POST is a JWS 1520 object whose JSON payload is a subset of the order object defined in 1521 Section 7.1.3, containing the fields that describe the certificate to 1522 be issued: 1524 csr (required, string): A CSR encoding the parameters for the 1525 certificate being requested [RFC2986]. The CSR is sent in the 1526 base64url-encoded version of the DER format. (Note: Because this 1527 field uses base64url, and does not include headers, it is 1528 different from PEM.) 1530 notBefore (optional, string): The requested value of the notBefore 1531 field in the certificate, in the date format defined in [RFC3339] 1533 notAfter (optional, string): The requested value of the notAfter 1534 field in the certificate, in the date format defined in [RFC3339] 1536 POST /acme/new-order HTTP/1.1 1537 Host: example.com 1538 Content-Type: application/jose+json 1540 { 1541 "protected": base64url({ 1542 "alg": "ES256", 1543 "kid": "https://example.com/acme/acct/1", 1544 "nonce": "5XJ1L3lEkMG7tR6pA00clA", 1545 "url": "https://example.com/acme/new-order" 1546 }), 1547 "payload": base64url({ 1548 "csr": "5jNudRx6Ye4HzKEqT5...FS6aKdZeGsysoCo4H9P", 1549 "notBefore": "2016-01-01T00:00:00Z", 1550 "notAfter": "2016-01-08T00:00:00Z" 1551 }), 1552 "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g" 1553 } 1555 The CSR encodes the client's requests with regard to the content of 1556 the certificate to be issued. The CSR MUST indicate the requested 1557 identifiers, either in the commonName portion of the requested 1558 subject name, or in an extensionRequest attribute [RFC2985] 1559 requesting a subjectAltName extension. 1561 The server MUST return an error if it cannot fulfill the request as 1562 specified, and MUST NOT issue a certificate with contents other than 1563 those requested. If the server requires the request to be modified 1564 in a certain way, it should indicate the required changes using an 1565 appropriate error type and description. 1567 If the server is willing to issue the requested certificate, it 1568 responds with a 201 (Created) response. The body of this response is 1569 an order object reflecting the client's request and any 1570 authorizations the client must complete before the certificate will 1571 be issued. 1573 HTTP/1.1 201 Created 1574 Replay-Nonce: MYAuvOpaoIiywTezizk5vw 1575 Location: https://example.com/acme/order/asdf 1577 { 1578 "status": "pending", 1579 "expires": "2016-01-01T00:00:00Z", 1581 "csr": "jcRf4uXra7FGYW5ZMewvV...rhlnznwy8YbpMGqwidEXfE", 1582 "notBefore": "2016-01-01T00:00:00Z", 1583 "notAfter": "2016-01-08T00:00:00Z", 1585 "authorizations": [ 1586 "https://example.com/acme/authz/1234", 1587 "https://example.com/acme/authz/2345" 1588 ] 1589 } 1591 The order object returned by the server represents a promise that if 1592 the client fulfills the server's requirements before the "expires" 1593 time, then the server will issue the requested certificate. In the 1594 order object, any authorization referenced in the "authorizations" 1595 array whose status is "pending" represents an authorization 1596 transaction that the client must complete before the server will 1597 issue the certificate (see Section 7.5). If the client fails to 1598 complete the required actions before the "expires" time, then the 1599 server SHOULD change the status of the order to "invalid" and MAY 1600 delete the order resource. 1602 The server MUST begin the issuance process for the requested 1603 certificate and update the order resource with a URL for the 1604 certificate once the client has fulfilled the server's requirements. 1605 If the client has already satisfied the server's requirements at the 1606 time of this request (e.g., by obtaining authorization for all of the 1607 identifiers in the certificate in previous transactions), then the 1608 server MUST proactively issue the requested certificate and provide a 1609 URL for it in the "certificate" field of the order. The server MUST, 1610 however, still list the completed authorizations in the 1611 "authorizations" array. 1613 Once the client believes it has fulfilled the server's requirements, 1614 it should send a GET request to the order resource to obtain its 1615 current state. The status of the order will indicate what action the 1616 client should take: 1618 o "invalid": The certificate will not be issued. Consider this 1619 order process abandoned. 1621 o "pending": The server does not believe that the client has 1622 fulfilled the requirements. Check the "authorizations" array for 1623 entries that are still pending. 1625 o "processing": The server agrees that the requirements have been 1626 fulfilled, and is in the process of generating the certificate. 1627 Retry after the time given in the "Retry-After" header field of 1628 the response, if any. 1630 o "valid": The server has issued the certificate and provisioned its 1631 URL to the "certificate" field of the order. 1633 7.4.1. Pre-Authorization 1635 The order process described above presumes that authorization objects 1636 are created reactively, in response to a certificate order. Some 1637 servers may also wish to enable clients to obtain authorization for 1638 an identifier proactively, outside of the context of a specific 1639 issuance. For example, a client hosting virtual servers for a 1640 collection of names might wish to obtain authorization before any 1641 virtual servers are created and only create a certificate when a 1642 virtual server starts up. 1644 In some cases, a CA running an ACME server might have a completely 1645 external, non-ACME process for authorizing a client to issue for an 1646 identifier. In these case, the CA should provision its ACME server 1647 with authorization objects corresponding to these authorizations and 1648 reflect them as already valid in any orders submitted by the client. 1650 If a CA wishes to allow pre-authorization within ACME, it can offer a 1651 "new authorization" resource in its directory by adding the field 1652 "new-authz" with a URL for the new authorization resource. 1654 To request authorization for an identifier, the client sends a POST 1655 request to the new-authorization resource specifying the identifier 1656 for which authorization is being requested and how the server should 1657 behave with respect to existing authorizations for this identifier. 1659 identifier (required, object): The identifier that the account is 1660 authorized to represent: 1662 type (required, string): The type of identifier. 1664 value (required, string): The identifier itself. 1666 POST /acme/new-authz HTTP/1.1 1667 Host: example.com 1668 Content-Type: application/jose+json 1670 { 1671 "protected": base64url({ 1672 "alg": "ES256", 1673 "kid": "https://example.com/acme/acct/1", 1674 "nonce": "uQpSjlRb4vQVCjVYAyyUWg", 1675 "url": "https://example.com/acme/new-authz" 1676 }), 1677 "payload": base64url({ 1678 "identifier": { 1679 "type": "dns", 1680 "value": "example.net" 1681 } 1682 }), 1683 "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" 1684 } 1686 Before processing the authorization request, the server SHOULD 1687 determine whether it is willing to issue certificates for the 1688 identifier. For example, the server should check that the identifier 1689 is of a supported type. Servers might also check names against a 1690 blacklist of known high-value identifiers. If the server is 1691 unwilling to issue for the identifier, it SHOULD return a 403 1692 (Forbidden) error, with a problem document describing the reason for 1693 the rejection. 1695 If the server is willing to proceed, it builds a pending 1696 authorization object from the inputs submitted by the client. 1698 o "identifier" the identifier submitted by the client 1700 o "status" MUST be "pending" unless the server has out-of-band 1701 information about the client's authorization status 1703 o "challenges" as selected by the server's policy for this 1704 identifier 1706 The server allocates a new URL for this authorization, and returns a 1707 201 (Created) response, with the authorization URL in the Location 1708 header field, and the JSON authorization object in the body. The 1709 client then follows the process described in Section 7.5 to complete 1710 the authorization process. 1712 7.4.2. Downloading the Certificate 1714 To download the issued certificate, the client simply sends a GET 1715 request to the certificate URL. 1717 The default format of the certificate is application/pem-certificate- 1718 chain (see IANA Considerations). 1720 The server MAY provide one or more link relation header fields 1721 [RFC5988] with relation "alternate". Each such field SHOULD express 1722 an alternative certificate chain starting with the same end-entity 1723 certificate. This can be used to express paths to various trust 1724 anchors. Clients can fetch these alternates and use their own 1725 heuristics to decide which is optimal. 1727 GET /acme/cert/asdf HTTP/1.1 1728 Host: example.com 1729 Accept: application/pkix-cert 1731 HTTP/1.1 200 OK 1732 Content-Type: application/pem-certificate-chain 1733 Link: ;rel="index" 1735 -----BEGIN CERTIFICATE----- 1736 [End-entity certificate contents] 1737 -----END CERTIFICATE----- 1738 -----BEGIN CERTIFICATE----- 1739 [Issuer certificate contents] 1740 -----END CERTIFICATE----- 1741 -----BEGIN CERTIFICATE----- 1742 [Other certificate contents] 1743 -----END CERTIFICATE----- 1745 A certificate resource represents a single, immutable certificate. 1746 If the client wishes to obtain a renewed certificate, the client 1747 initiates a new order process to request one. 1749 Because certificate resources are immutable once issuance is 1750 complete, the server MAY enable the caching of the resource by adding 1751 Expires and Cache-Control headers specifying a point in time in the 1752 distant future. These headers have no relation to the certificate's 1753 period of validity. 1755 The ACME client MAY request other formats by including an Accept 1756 header in its request. For example, the client could use the media 1757 type "application/pkix-cert" [RFC2585] to request the end-entity 1758 certificate in DER format. Server support for alternate formats is 1759 OPTIONAL. For formats that can only express a single certificate, 1760 the server SHOULD provide one or more "Link: rel="up"" headers 1761 pointing to an issuer or issuers so that ACME clients can build a 1762 certificate chain as defined in TLS. 1764 7.5. Identifier Authorization 1766 The identifier authorization process establishes the authorization of 1767 an account to manage certificates for a given identifier. This 1768 process assures the server of two things: 1770 1. That the client controls the private key of the account key pair, 1771 and 1773 2. That the client controls the identifier in question. 1775 This process may be repeated to associate multiple identifiers to a 1776 key pair (e.g., to request certificates with multiple identifiers), 1777 or to associate multiple accounts with an identifier (e.g., to allow 1778 multiple entities to manage certificates). The server may declare 1779 that an authorization is only valid for a specific order by setting 1780 the "scope" field of the authorization to the URL for that order. 1782 Authorization resources are created by the server in response to 1783 certificate orders or authorization requests submitted by an account 1784 key holder; their URLs are provided to the client in the responses to 1785 these requests. The authorization object is implicitly tied to the 1786 account key used to sign the request. 1788 When a client receives an order from the server it downloads the 1789 authorization resources by sending GET requests to the indicated 1790 URLs. If the client initiates authorization using a request to the 1791 new authorization resource, it will have already received the pending 1792 authorization object in the response to that request. 1794 GET /acme/authz/1234 HTTP/1.1 1795 Host: example.com 1797 HTTP/1.1 200 OK 1798 Content-Type: application/json 1799 Link: ;rel="index" 1801 { 1802 "status": "pending", 1803 "expires": "2018-03-03T14:09:00Z", 1805 "identifier": { 1806 "type": "dns", 1807 "value": "example.org" 1808 }, 1810 "challenges": [ 1811 { 1812 "type": "http-01", 1813 "url": "https://example.com/authz/1234/0", 1814 "token": "DGyRejmCefe7v4NfDGDKfA" 1815 }, 1816 { 1817 "type": "tls-sni-02", 1818 "url": "https://example.com/authz/1234/1", 1819 "token": "DGyRejmCefe7v4NfDGDKfA" 1820 }, 1821 { 1822 "type": "dns-01", 1823 "url": "https://example.com/authz/1234/2", 1824 "token": "DGyRejmCefe7v4NfDGDKfA" 1825 } 1826 ] 1827 } 1829 7.5.1. Responding to Challenges 1831 To prove control of the identifier and receive authorization, the 1832 client needs to respond with information to complete the challenges. 1833 To do this, the client updates the authorization object received from 1834 the server by filling in any required information in the elements of 1835 the "challenges" dictionary. 1837 The client sends these updates back to the server in the form of a 1838 JSON object with the response fields required by the challenge type, 1839 carried in a POST request to the challenge URL (not authorization 1840 URL) once it is ready for the server to attempt validation. 1842 For example, if the client were to respond to the "http-01" challenge 1843 in the above authorization, it would send the following request: 1845 POST /acme/authz/1234/0 HTTP/1.1 1846 Host: example.com 1847 Content-Type: application/jose+json 1849 { 1850 "protected": base64url({ 1851 "alg": "ES256", 1852 "kid": "https://example.com/acme/acct/1", 1853 "nonce": "Q_s3MWoqT05TrdkM2MTDcw", 1854 "url": "https://example.com/acme/authz/1234/0" 1855 }), 1856 "payload": base64url({ 1857 "keyAuthorization": "IlirfxKKXA...vb29HhjjLPSggwiE" 1858 }), 1859 "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ" 1860 } 1862 The server updates the authorization document by updating its 1863 representation of the challenge with the response fields provided by 1864 the client. The server MUST ignore any fields in the response object 1865 that are not specified as response fields for this type of challenge. 1866 The server provides a 200 (OK) response with the updated challenge 1867 object as its body. 1869 If the client's response is invalid for any reason or does not 1870 provide the server with appropriate information to validate the 1871 challenge, then the server MUST return an HTTP error. On receiving 1872 such an error, the client SHOULD undo any actions that have been 1873 taken to fulfill the challenge, e.g., removing files that have been 1874 provisioned to a web server. 1876 The server is said to "finalize" the authorization when it has 1877 completed one of the validations, by assigning the authorization a 1878 status of "valid" or "invalid", corresponding to whether it considers 1879 the account authorized for the identifier. If the final state is 1880 "valid", then the server MUST include an "expires" field. When 1881 finalizing an authorization, the server MAY remove challenges other 1882 than the one that was completed, and may modify the "expires" field. 1883 The server SHOULD NOT remove challenges with status "invalid". 1885 Usually, the validation process will take some time, so the client 1886 will need to poll the authorization resource to see when it is 1887 finalized. For challenges where the client can tell when the server 1888 has validated the challenge (e.g., by seeing an HTTP or DNS request 1889 from the server), the client SHOULD NOT begin polling until it has 1890 seen the validation request from the server. 1892 To check on the status of an authorization, the client sends a GET 1893 request to the authorization URL, and the server responds with the 1894 current authorization object. In responding to poll requests while 1895 the validation is still in progress, the server MUST return a 200 1896 (OK) response and MAY include a Retry-After header field to suggest a 1897 polling interval to the client. 1899 GET /acme/authz/1234 HTTP/1.1 1900 Host: example.com 1902 HTTP/1.1 200 OK 1904 { 1905 "status": "valid", 1906 "expires": "2018-09-09T14:09:00Z", 1908 "identifier": { 1909 "type": "dns", 1910 "value": "example.org" 1911 }, 1913 "challenges": [ 1914 { 1915 "type": "http-01" 1916 "url": "https://example.com/authz/1234/0", 1917 "status": "valid", 1918 "validated": "2014-12-01T12:05:00Z", 1919 "token": "IlirfxKKXAsHtmzK29Pj8A", 1920 "keyAuthorization": "IlirfxKKXA...vb29HhjjLPSggwiE" 1921 } 1922 ] 1923 } 1925 7.5.2. Deactivating an Authorization 1927 If a client wishes to relinquish its authorization to issue 1928 certificates for an identifier, then it may request that the server 1929 deactivates each authorization associated with it by sending POST 1930 requests with the static object {"status": "deactivated"} to each 1931 authorization URL. 1933 POST /acme/authz/1234 HTTP/1.1 1934 Host: example.com 1935 Content-Type: application/jose+json 1937 { 1938 "protected": base64url({ 1939 "alg": "ES256", 1940 "kid": "https://example.com/acme/acct/1", 1941 "nonce": "xWCM9lGbIyCgue8di6ueWQ", 1942 "url": "https://example.com/acme/authz/1234" 1943 }), 1944 "payload": base64url({ 1945 "status": "deactivated" 1946 }), 1947 "signature": "srX9Ji7Le9bjszhu...WTFdtujObzMtZcx4" 1948 } 1950 The server MUST verify that the request is signed by the account key 1951 corresponding to the account that owns the authorization. If the 1952 server accepts the deactivation, it should reply with a 200 (OK) 1953 status code and the updated contents of the authorization object. 1955 The server MUST NOT treat deactivated authorization objects as 1956 sufficient for issuing certificates. 1958 7.6. Certificate Revocation 1960 To request that a certificate be revoked, the client sends a POST 1961 request to the ACME server's revoke-cert URL. The body of the POST 1962 is a JWS object whose JSON payload contains the certificate to be 1963 revoked: 1965 certificate (required, string): The certificate to be revoked, in 1966 the base64url-encoded version of the DER format. (Note: Because 1967 this field uses base64url, and does not include headers, it is 1968 different from PEM.) 1970 reason (optional, int): One of the revocation reasonCodes defined in 1971 Section 5.3.1 of [RFC5280] to be used when generating OCSP 1972 responses and CRLs. If this field is not set the server SHOULD 1973 use the unspecified (0) reasonCode value when generating OCSP 1974 responses and CRLs. The server MAY disallow a subset of 1975 reasonCodes from being used by the user. If a request contains a 1976 disallowed reasonCode the server MUST reject it with the error 1977 type "urn:ietf:params:acme:error:badRevocationReason". The 1978 problem document detail SHOULD indicate which reasonCodes are 1979 allowed. 1981 POST /acme/revoke-cert HTTP/1.1 1982 Host: example.com 1983 Content-Type: application/jose+json 1985 { 1986 "protected": base64url({ 1987 "alg": "ES256", 1988 "jwk": /* account key */, 1989 "nonce": "JHb54aT_KTXBWQOzGYkt9A", 1990 "url": "https://example.com/acme/revoke-cert" 1991 }), 1992 "payload": base64url({ 1993 "certificate": "MIIEDTCCAvegAwIBAgIRAP8...", 1994 "reason": 1 1995 }), 1996 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 1997 } 1999 Revocation requests are different from other ACME requests in that 2000 they can be signed either with an account key pair or the key pair in 2001 the certificate. Before revoking a certificate, the server MUST 2002 verify that the key used to sign the request is authorized to revoke 2003 the certificate. The server MUST consider at least the following 2004 accounts authorized for a given certificate: 2006 o the account that issued the certificate. 2008 o an account that holds authorizations for all of the identifiers in 2009 the certificate. 2011 The server MUST also consider a revocation request valid if it is 2012 signed with the private key corresponding to the public key in the 2013 certificate. 2015 If the revocation succeeds, the server responds with status code 200 2016 (OK). If the revocation fails, the server returns an error. 2018 HTTP/1.1 200 OK 2019 Replay-Nonce: IXVHDyxIRGcTE0VSblhPzw 2020 Content-Length: 0 2022 --- or --- 2024 HTTP/1.1 403 Forbidden 2025 Replay-Nonce: IXVHDyxIRGcTE0VSblhPzw 2026 Content-Type: application/problem+json 2027 Content-Language: en 2029 { 2030 "type": "urn:ietf:params:acme:error:unauthorized", 2031 "detail": "No authorization provided for name example.net", 2032 "instance": "http://example.com/doc/unauthorized" 2033 } 2035 8. Identifier Validation Challenges 2037 There are few types of identifiers in the world for which there is a 2038 standardized mechanism to prove possession of a given identifier. In 2039 all practical cases, CAs rely on a variety of means to test whether 2040 an entity applying for a certificate with a given identifier actually 2041 controls that identifier. 2043 Challenges provide the server with assurance that an account holder 2044 is also the entity that controls an identifier. For each type of 2045 challenge, it must be the case that in order for an entity to 2046 successfully complete the challenge the entity must both: 2048 o Hold the private key of the account key pair used to respond to 2049 the challenge 2051 o Control the identifier in question 2053 Section 10 documents how the challenges defined in this document meet 2054 these requirements. New challenges will need to document how they 2055 do. 2057 ACME uses an extensible challenge/response framework for identifier 2058 validation. The server presents a set of challenges in the 2059 authorization object it sends to a client (as objects in the 2060 "challenges" array), and the client responds by sending a response 2061 object in a POST request to a challenge URL. 2063 This section describes an initial set of challenge types. Each 2064 challenge must describe: 2066 1. Content of challenge objects 2068 2. Content of response objects 2070 3. How the server uses the challenge and response to verify control 2071 of an identifier 2073 Challenge objects all contain the following basic fields: 2075 type (required, string): The type of challenge encoded in the 2076 object. 2078 url (required, string): The URL to which a response can be posted. 2080 status (required, string): The status of this authorization. 2081 Possible values are: "pending", "valid", and "invalid". 2083 validated (optional, string): The time at which this challenge was 2084 completed by the server, encoded in the format specified in RFC 2085 3339 [RFC3339]. This field is REQUIRED if the "status" field is 2086 "valid". 2088 errors (optional, array of object): Errors that occurred while the 2089 server was validating the challenge, if any, structured as problem 2090 documents [RFC7807]. The server MUST NOT modify the array except 2091 by appending entries onto the end. The server can limit the size 2092 of this object by limiting the number of times it will retry a 2093 challenge. 2095 All additional fields are specified by the challenge type. If the 2096 server sets a challenge's "status" to "invalid", it SHOULD also 2097 include the "error" field to help the client diagnose why the 2098 challenge failed. 2100 Different challenges allow the server to obtain proof of different 2101 aspects of control over an identifier. In some challenges, like 2102 HTTP, TLS SNI, and DNS, the client directly proves its ability to do 2103 certain things related to the identifier. The choice of which 2104 challenges to offer to a client under which circumstances is a matter 2105 of server policy. 2107 The identifier validation challenges described in this section all 2108 relate to validation of domain names. If ACME is extended in the 2109 future to support other types of identifiers, there will need to be 2110 new challenge types, and they will need to specify which types of 2111 identifier they apply to. 2113 8.1. Key Authorizations 2115 Several of the challenges in this document make use of a key 2116 authorization string. A key authorization is a string that expresses 2117 a domain holder's authorization for a specified key to satisfy a 2118 specified challenge, by concatenating the token for the challenge 2119 with a key fingerprint, separated by a "." character: 2121 key-authz = token || '.' || base64url(JWK_Thumbprint(accountKey)) 2123 The "JWK_Thumbprint" step indicates the computation specified in 2124 [RFC7638], using the SHA-256 digest [FIPS180-4]. As noted in JWA 2125 [RFC7518] any prepended zero octets in the JWK object MUST be 2126 stripped before doing the computation. 2128 As specified in the individual challenges below, the token for a 2129 challenge is a string comprised entirely of characters in the URL- 2130 safe base64 alphabet. The "||" operator indicates concatenation of 2131 strings. 2133 8.2. Retrying Challenges 2135 ACME challenges typically require the client to set up some network- 2136 accessible resource that the server can query in order to validate 2137 that the client controls an identifier. In practice it is not 2138 uncommon for the server's queries to fail while a resource is being 2139 set up, e.g., due to information propagating across a cluster or 2140 firewall rules not being in place. 2142 Clients SHOULD NOT respond to challenges until they believe that the 2143 server's queries will succeed. If a server's initial validation 2144 query fails, the server SHOULD retry the query after some time. 2145 While the server is still trying, the status of the challenge remains 2146 "pending"; it is only marked "invalid" once the server has given up. 2148 The server MUST provide information about its retry state to the 2149 client via the "errors" field in the challenge and the Retry-After 2150 HTTP header field in response to requests to the challenge resource. 2151 The server MUST add an entry to the "errors" field in the challenge 2152 after each failed validation query. The server SHOULD set the Retry- 2153 After header field to a time after the server's next validation 2154 query, since the status of the challenge will not change until that 2155 time. 2157 Clients can explicitly request a retry by re-sending their response 2158 to a challenge in a new POST request (with a new nonce, etc.). This 2159 allows clients to request a retry when the state has changed (e.g., 2160 after firewall rules have been updated). Servers SHOULD retry a 2161 request immediately on receiving such a POST request. In order to 2162 avoid denial-of-service attacks via client-initiated retries, servers 2163 SHOULD rate-limit such requests. 2165 8.3. HTTP Challenge 2167 With HTTP validation, the client in an ACME transaction proves its 2168 control over a domain name by proving that for that domain name it 2169 can provision resources to be returned by an HTTP server. The ACME 2170 server challenges the client to provision a file at a specific path, 2171 with a specific string as its content. 2173 As a domain may resolve to multiple IPv4 and IPv6 addresses, the 2174 server will connect to at least one of the hosts found in the DNS A 2175 and AAAA records, at its discretion. Because many web servers 2176 allocate a default HTTPS virtual host to a particular low-privilege 2177 tenant user in a subtle and non-intuitive manner, the challenge must 2178 be completed over HTTP, not HTTPS. 2180 type (required, string): The string "http-01" 2182 token (required, string): A random value that uniquely identifies 2183 the challenge. This value MUST have at least 128 bits of entropy. 2184 It MUST NOT contain any characters outside the base64url alphabet, 2185 including padding characters ("="). 2187 GET /acme/authz/1234/0 HTTP/1.1 2188 Host: example.com 2190 HTTP/1.1 200 OK 2191 { 2192 "type": "http-01", 2193 "url": "https://example.com/acme/authz/0", 2194 "status": "pending", 2195 "token": "LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0" 2196 } 2198 A client responds to this challenge by constructing a key 2199 authorization from the "token" value provided in the challenge and 2200 the client's account key. The client then provisions the key 2201 authorization as a resource on the HTTP server for the domain in 2202 question. 2204 The path at which the resource is provisioned is comprised of the 2205 fixed prefix "/.well-known/acme-challenge/", followed by the "token" 2206 value in the challenge. The value of the resource MUST be the ASCII 2207 representation of the key authorization. 2209 GET /.well-known/acme-challenge/LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0 2210 Host: example.org 2212 HTTP/1.1 200 OK 2213 LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0.9jg46WB3rR_AHD-EBXdN7cBkH1WOu0tA3M9fm21mqTI 2215 The client's response to this challenge indicates its agreement to 2216 this challenge by sending the server the key authorization covering 2217 the challenge's token and the client's account key. 2219 keyAuthorization (required, string): The key authorization for this 2220 challenge. This value MUST match the token from the challenge and 2221 the client's account key. 2223 POST /acme/authz/1234/0 2224 Host: example.com 2225 Content-Type: application/jose+json 2227 { 2228 "protected": base64url({ 2229 "alg": "ES256", 2230 "kid": "https://example.com/acme/acct/1", 2231 "nonce": "JHb54aT_KTXBWQOzGYkt9A", 2232 "url": "https://example.com/acme/authz/1234/0" 2233 }), 2234 "payload": base64url({ 2235 "keyAuthorization": "evaGxfADs...62jcerQ" 2236 }), 2237 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2238 } 2240 On receiving a response, the server MUST verify that the key 2241 authorization in the response matches the "token" value in the 2242 challenge and the client's account key. If they do not match, then 2243 the server MUST return an HTTP error in response to the POST request 2244 in which the client sent the challenge. 2246 Given a challenge/response pair, the server verifies the client's 2247 control of the domain by verifying that the resource was provisioned 2248 as expected. 2250 1. Construct a URL by populating the URL template [RFC6570] 2251 "http://{domain}/.well-known/acme-challenge/{token}", where: * 2252 the domain field is set to the domain name being verified; and * 2253 the token field is set to the token in the challenge. 2255 2. Verify that the resulting URL is well-formed. 2257 3. Dereference the URL using an HTTP GET request. This request MUST 2258 be sent to TCP port 80 on the HTTP server. 2260 4. Verify that the body of the response is well-formed key 2261 authorization. The server SHOULD ignore whitespace characters at 2262 the end of the body. 2264 5. Verify that key authorization provided by the HTTP server matches 2265 the key authorization provided by the client in its response to 2266 the challenge. 2268 The server SHOULD follow redirects when dereferencing the URL. 2270 If all of the above verifications succeed, then the validation is 2271 successful. If the request fails, or the body does not pass these 2272 checks, then it has failed. 2274 8.4. TLS with Server Name Indication (TLS SNI) Challenge 2276 The TLS with Server Name Indication (TLS SNI) validation method 2277 proves control over a domain name by requiring the client to 2278 configure a TLS server referenced by the DNS A and AAAA resource 2279 records for the domain name to respond to specific connection 2280 attempts utilizing the Server Name Indication extension [RFC6066]. 2281 The server verifies the client's challenge by accessing the TLS 2282 server and verifying a particular certificate is presented. 2284 type (required, string): The string "tls-sni-02" 2286 token (required, string): A random value that uniquely identifies 2287 the challenge. This value MUST have at least 128 bits of entropy. 2288 It MUST NOT contain any characters outside the base64url alphabet, 2289 including padding characters ("="). 2291 GET /acme/authz/1234/1 HTTP/1.1 2292 Host: example.com 2294 HTTP/1.1 200 OK 2295 { 2296 "type": "tls-sni-02", 2297 "url": "https://example.com/acme/authz/1234/1", 2298 "status": "pending", 2299 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA" 2300 } 2302 A client responds to this challenge by constructing a self-signed 2303 certificate which the client MUST provision at the domain name 2304 concerned in order to pass the challenge. 2306 The certificate may be constructed arbitrarily, except that each 2307 certificate MUST have exactly two subjectAlternativeNames, SAN A and 2308 SAN B. Both MUST be dNSNames [RFC5280]. 2310 SAN A MUST be constructed as follows: compute the SHA-256 digest 2311 [FIPS180-4] of the challenge token and encode it in lowercase 2312 hexadecimal form. The dNSName is "x.y.token.acme.invalid", where x 2313 is the first half of the hexadecimal representation and y is the 2314 second half. 2316 SAN B MUST be constructed as follows: compute the SHA-256 digest of 2317 the key authorization and encode it in lowercase hexadecimal form. 2318 The dNSName is "x.y.ka.acme.invalid" where x is the first half of the 2319 hexadecimal representation and y is the second half. 2321 The client MUST ensure that the certificate is served to TLS 2322 connections specifying a Server Name Indication (SNI) value of SAN A. 2324 The response to the TLS-SNI challenge simply acknowledges that the 2325 client is ready to fulfill this challenge. 2327 keyAuthorization (required, string): The key authorization for this 2328 challenge. This value MUST match the token from the challenge and 2329 the client's account key. 2331 POST /acme/authz/1234/1 2332 Host: example.com 2333 Content-Type: application/jose+json 2335 { 2336 "protected": base64url({ 2337 "alg": "ES256", 2338 "kid": "https://example.com/acme/acct/1", 2339 "nonce": "JHb54aT_KTXBWQOzGYkt9A", 2340 "url": "https://example.com/acme/authz/1234/1" 2341 }), 2342 "payload": base64url({ 2343 "keyAuthorization": "evaGxfADs...62jcerQ" 2344 }), 2345 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2346 } 2348 On receiving a response, the server MUST verify that the key 2349 authorization in the response matches the "token" value in the 2350 challenge and the client's account key. If they do not match, then 2351 the server MUST return an HTTP error in response to the POST request 2352 in which the client sent the challenge. 2354 Given a challenge/response pair, the ACME server verifies the 2355 client's control of the domain by verifying that the TLS server was 2356 configured appropriately, using these steps: 2358 1. Compute SAN A and SAN B in the same way as the client. 2360 2. Open a TLS connection to the domain name being validated, 2361 presenting SAN A in the SNI field. This connection MUST be sent 2362 to TCP port 443 on the TLS server. In the ClientHello initiating 2363 the TLS handshake, the server MUST include a server_name 2364 extension (i.e., SNI) containing SAN A. The server SHOULD ensure 2365 that it does not reveal SAN B in any way when making the TLS 2366 connection, such that the presentation of SAN B in the returned 2367 certificate proves association with the client. 2369 3. Verify that the certificate contains a subjectAltName extension 2370 containing dNSName entries of SAN A and SAN B and no other 2371 entries. The comparison MUST be insensitive to case and ordering 2372 of names. 2374 If all of the above verifications succeed, then the validation is 2375 successful. Otherwise, the validation fails. 2377 8.5. DNS Challenge 2379 When the identifier being validated is a domain name, the client can 2380 prove control of that domain by provisioning a TXT resource record 2381 containing a designated value for a specific validation domain name. 2383 type (required, string): The string "dns-01" 2385 token (required, string): A random value that uniquely identifies 2386 the challenge. This value MUST have at least 128 bits of entropy. 2387 It MUST NOT contain any characters outside the base64url alphabet, 2388 including padding characters ("="). 2390 GET /acme/authz/1234/2 HTTP/1.1 2391 Host: example.com 2393 HTTP/1.1 200 OK 2394 { 2395 "type": "dns-01", 2396 "url": "https://example.com/acme/authz/1234/2", 2397 "status": "pending", 2398 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA" 2399 } 2400 A client responds to this challenge by constructing a key 2401 authorization from the "token" value provided in the challenge and 2402 the client's account key. The client then computes the SHA-256 2403 digest [FIPS180-4] of the key authorization. 2405 The record provisioned to the DNS is the base64url encoding of this 2406 digest. The client constructs the validation domain name by 2407 prepending the label "_acme-challenge" to the domain name being 2408 validated, then provisions a TXT record with the digest value under 2409 that name. For example, if the domain name being validated is 2410 "example.org", then the client would provision the following DNS 2411 record: 2413 _acme-challenge.example.org. 300 IN TXT "gfj9Xq...Rg85nM" 2415 The response to the DNS challenge provides the computed key 2416 authorization to acknowledge that the client is ready to fulfill this 2417 challenge. 2419 keyAuthorization (required, string): The key authorization for this 2420 challenge. This value MUST match the token from the challenge and 2421 the client's account key. 2423 POST /acme/authz/1234/2 2424 Host: example.com 2425 Content-Type: application/jose+json 2427 { 2428 "protected": base64url({ 2429 "alg": "ES256", 2430 "kid": "https://example.com/acme/acct/1", 2431 "nonce": "JHb54aT_KTXBWQOzGYkt9A", 2432 "url": "https://example.com/acme/authz/1234/2" 2433 }), 2434 "payload": base64url({ 2435 "keyAuthorization": "evaGxfADs...62jcerQ" 2436 }), 2437 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2438 } 2440 On receiving a response, the server MUST verify that the key 2441 authorization in the response matches the "token" value in the 2442 challenge and the client's account key. If they do not match, then 2443 the server MUST return an HTTP error in response to the POST request 2444 in which the client sent the challenge. 2446 To validate a DNS challenge, the server performs the following steps: 2448 1. Compute the SHA-256 digest [FIPS180-4] of the key authorization 2450 2. Query for TXT records for the validation domain name 2452 3. Verify that the contents of one of the TXT records match the 2453 digest value 2455 If all of the above verifications succeed, then the validation is 2456 successful. If no DNS record is found, or DNS record and response 2457 payload do not pass these checks, then the validation fails. 2459 8.6. Out-of-Band Challenge 2461 There may be cases where a server cannot perform automated validation 2462 of an identifier, for example, if validation requires some manual 2463 steps. In such cases, the server may provide an "out of band" (OOB) 2464 challenge to request that the client perform some action outside of 2465 ACME in order to validate possession of the identifier. 2467 The OOB challenge requests that the client have a human user visit a 2468 web page to receive instructions on how to validate possession of the 2469 identifier, by providing a URL for that web page. 2471 type (required, string): The string "oob-01" 2473 href (required, string): The URL to be visited. The scheme of this 2474 URL MUST be "http" or "https". Note that this field is distinct 2475 from the "url" field of the challenge, which identifies the 2476 challenge itself. 2478 GET /acme/authz/1234/3 HTTP/1.1 2479 Host: example.com 2481 HTTP/1.1 200 OK 2482 { 2483 "type": "oob-01", 2484 "url": "https://example.com/acme/authz/1234/3", 2485 "status": "pending", 2486 "href": "https://example.com/validate/evaGxfADs6pSRb2LAv9IZ" 2487 } 2489 A client responds to this challenge by presenting the indicated URL 2490 for a human user to navigate to. If the user chooses to complete 2491 this challenge (by visiting the website and completing its 2492 instructions), the client indicates this by sending a simple 2493 acknowledgement response to the server. 2495 type (required, string): The string "oob-01" 2496 POST /acme/authz/1234/3 2497 Host: example.com 2498 Content-Type: application/jose+json 2500 { 2501 "protected": base64url({ 2502 "alg": "ES256", 2503 "kid": "https://example.com/acme/acct/1", 2504 "nonce": "JHb54aT_KTXBWQOzGYkt9A", 2505 "url": "https://example.com/acme/authz/1234/3" 2506 }), 2507 "payload": base64url({ 2508 "type": "oob-01" 2509 }), 2510 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2511 } 2513 On receiving a response, the server MUST verify that the value of the 2514 "type" field is "oob-01". Otherwise, the steps the server takes to 2515 validate identifier possession are determined by the server's local 2516 policy. 2518 9. IANA Considerations 2520 9.1. MIME Type: application/pem-certificate-chain 2522 The "Media Types" registry should be updated with the following 2523 additional value: 2525 MIME media type name: application 2527 MIME subtype name: pem-certificate-chain 2529 Required parameters: None 2531 Optional parameters: None 2533 Encoding considerations: None 2535 Security considerations: Carries a cryptographic certificate and its 2536 associated certificate chain 2538 Interoperability considerations: None 2540 Published specification: draft-ietf-acme-acme [[ RFC EDITOR: Please 2541 replace draft-ietf-acme-acme above with the RFC number assigned to 2542 this ]] 2543 Applications which use this media type: Any MIME-compliant transport 2545 Additional information: 2547 File should contain one or more certificates encoded as PEM according 2548 to RFC 7468 [RFC7468]. In order to provide easy interoperation with 2549 TLS, the first certificate MUST be an end-entity certificate. Each 2550 following certificate SHOULD directly certify one preceding it. 2551 Because certificate validation requires that trust anchors be 2552 distributed independently, a certificate that specifies a trust 2553 anchor MAY be omitted from the chain, provided that supported peers 2554 are known to possess any omitted certificates. 2556 9.2. Well-Known URI for the HTTP Challenge 2558 The "Well-Known URIs" registry should be updated with the following 2559 additional value (using the template from [RFC5785]): 2561 URI suffix: acme-challenge 2563 Change controller: IETF 2565 Specification document(s): This document, Section Section 8.3 2567 Related information: N/A 2569 9.3. Replay-Nonce HTTP Header 2571 The "Message Headers" registry should be updated with the following 2572 additional value: 2574 +-------------------+----------+----------+---------------+ 2575 | Header Field Name | Protocol | Status | Reference | 2576 +-------------------+----------+----------+---------------+ 2577 | Replay-Nonce | http | standard | Section 6.4.1 | 2578 +-------------------+----------+----------+---------------+ 2580 9.4. "url" JWS Header Parameter 2582 The "JSON Web Signature and Encryption Header Parameters" registry 2583 should be updated with the following additional value: 2585 o Header Parameter Name: "url" 2587 o Header Parameter Description: URL 2589 o Header Parameter Usage Location(s): JWE, JWS 2590 o Change Controller: IESG 2592 o Specification Document(s): Section 6.3.1 of RFC XXXX 2594 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2595 to this document ]] 2597 9.5. "nonce" JWS Header Parameter 2599 The "JSON Web Signature and Encryption Header Parameters" registry 2600 should be updated with the following additional value: 2602 o Header Parameter Name: "nonce" 2604 o Header Parameter Description: Nonce 2606 o Header Parameter Usage Location(s): JWE, JWS 2608 o Change Controller: IESG 2610 o Specification Document(s): Section 6.4.2 of RFC XXXX 2612 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2613 to this document ]] 2615 9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) 2617 The "IETF URN Sub-namespace for Registered Protocol Parameter 2618 Identifiers" registry should be updated with the following additional 2619 value, following the template in [RFC3553]: 2621 Registry name: acme 2623 Specification: RFC XXXX 2625 Repository: URL-TBD 2627 Index value: No transformation needed. 2629 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2630 to this document, and replace URL-TBD with the URL assigned by IANA 2631 for registries of ACME parameters. ]] 2633 9.7. New Registries 2635 This document requests that IANA create the following new registries: 2637 1. ACME Account Object Fields (Section 9.7.1) 2638 2. ACME Order Object Fields (Section 9.7.2) 2640 3. ACME Error Types (Section 9.7.3) 2642 4. ACME Resource Types (Section 9.7.4) 2644 5. ACME Identifier Types (Section 9.7.5) 2646 6. ACME Validation Methods (Section 9.7.6) 2648 All of these registries are under a heading of "Automated Certificate 2649 Management Environment (ACME) Protocol" and are administered under a 2650 Specification Required policy [RFC8126]. 2652 9.7.1. Fields in Account Objects 2654 This registry lists field names that are defined for use in ACME 2655 account objects. Fields marked as "configurable" may be included in 2656 a new-account request. 2658 Template: 2660 o Field name: The string to be used as a field name in the JSON 2661 object 2663 o Field type: The type of value to be provided, e.g., string, 2664 boolean, array of string 2666 o Client configurable: Boolean indicating whether the server should 2667 accept values provided by the client 2669 o Reference: Where this field is defined 2671 Initial contents: The fields and descriptions defined in 2672 Section 7.1.2. 2674 +--------------------------+-------------+--------------+-----------+ 2675 | Field Name | Field Type | Configurable | Reference | 2676 +--------------------------+-------------+--------------+-----------+ 2677 | status | string | false | RFC XXXX | 2678 | | | | | 2679 | contact | array of | true | RFC XXXX | 2680 | | string | | | 2681 | | | | | 2682 | external-account-binding | object | true | RFC XXXX | 2683 | | | | | 2684 | terms-of-service-agreed | boolean | true | RFC XXXX | 2685 | | | | | 2686 | orders | array of | false | RFC XXXX | 2687 | | string | | | 2688 +--------------------------+-------------+--------------+-----------+ 2690 9.7.2. Fields in Order Objects 2692 This registry lists field names that are defined for use in ACME 2693 order objects. Fields marked as "configurable" may be included in a 2694 new-order request. 2696 Template: 2698 o Field name: The string to be used as a field name in the JSON 2699 object 2701 o Field type: The type of value to be provided, e.g., string, 2702 boolean, array of string 2704 o Client configurable: Boolean indicating whether the server should 2705 accept values provided by the client 2707 o Reference: Where this field is defined 2709 Initial contents: The fields and descriptions defined in 2710 Section 7.1.3. 2712 +----------------+-----------------+--------------+-----------+ 2713 | Field Name | Field Type | Configurable | Reference | 2714 +----------------+-----------------+--------------+-----------+ 2715 | status | string | false | RFC XXXX | 2716 | | | | | 2717 | expires | string | false | RFC XXXX | 2718 | | | | | 2719 | csr | string | true | RFC XXXX | 2720 | | | | | 2721 | notBefore | string | true | RFC XXXX | 2722 | | | | | 2723 | notAfter | string | true | RFC XXXX | 2724 | | | | | 2725 | authorizations | array of string | false | RFC XXXX | 2726 | | | | | 2727 | certificate | string | false | RFC XXXX | 2728 +----------------+-----------------+--------------+-----------+ 2730 9.7.3. Error Types 2732 This registry lists values that are used within URN values that are 2733 provided in the "type" field of problem documents in ACME. 2735 Template: 2737 o Type: The label to be included in the URN for this error, 2738 following "urn:ietf:params:acme:error:" 2740 o Description: A human-readable description of the error 2742 o Reference: Where the error is defined 2744 Initial contents: The types and descriptions in the table in 2745 Section 6.6 above, with the Reference field set to point to this 2746 specification. 2748 9.7.4. Resource Types 2750 This registry lists the types of resources that ACME servers may list 2751 in their directory objects. 2753 Template: 2755 o Field name: The value to be used as a field name in the directory 2756 object 2758 o Resource type: The type of resource labeled by the field 2759 o Reference: Where the resource type is defined 2761 Initial contents: 2763 +-------------+--------------------+-----------+ 2764 | Field Name | Resource Type | Reference | 2765 +-------------+--------------------+-----------+ 2766 | new-account | New account | RFC XXXX | 2767 | | | | 2768 | new-order | New order | RFC XXXX | 2769 | | | | 2770 | revoke-cert | Revoke certificate | RFC XXXX | 2771 | | | | 2772 | key-change | Key change | RFC XXXX | 2773 +-------------+--------------------+-----------+ 2775 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2776 to this document ]] 2778 9.7.5. Identifier Types 2780 This registry lists the types of identifiers that can be present in 2781 ACME authorization objects. 2783 Template: 2785 o Label: The value to be put in the "type" field of the identifier 2786 object 2788 o Reference: Where the identifier type is defined 2790 Initial contents: 2792 +-------+-----------+ 2793 | Label | Reference | 2794 +-------+-----------+ 2795 | dns | RFC XXXX | 2796 +-------+-----------+ 2798 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2799 to this document ]] 2801 9.7.6. Validation Methods 2803 This registry lists identifiers for the ways that CAs can validate 2804 control of identifiers. Each method's entry must specify whether it 2805 corresponds to an ACME challenge type. The "Identifier Type" field 2806 must be contained in the Label column of the ACME Identifier Types 2807 registry. 2809 Template: 2811 o Label: The identifier for this validation method 2813 o Identifier Type: The type of identifier that this method applies 2814 to 2816 o ACME: "Y" if the validation method corresponds to an ACME 2817 challenge type; "N" otherwise. 2819 o Reference: Where the validation method is defined 2821 Initial Contents 2823 +------------+-----------------+------+-----------+ 2824 | Label | Identifier Type | ACME | Reference | 2825 +------------+-----------------+------+-----------+ 2826 | http-01 | dns | Y | RFC XXXX | 2827 | | | | | 2828 | tls-sni-02 | dns | Y | RFC XXXX | 2829 | | | | | 2830 | dns-01 | dns | Y | RFC XXXX | 2831 | | | | | 2832 | oob-01 | dns | Y | RFC XXXX | 2833 +------------+-----------------+------+-----------+ 2835 When evaluating a request for an assignment in this registry, the 2836 designated expert should ensure that the method being registered has 2837 a clear, interoperable definition and does not overlap with existing 2838 validation methods. That is, it should not be possible for a client 2839 and server to follow take the same set of actions to fulfill two 2840 different validation mechanisms. 2842 Validation methods do not have to be compatible with ACME in order to 2843 be registered. For example, a CA might wish to register a validation 2844 method in order to support its use with the ACME extensions to CAA 2845 [I-D.ietf-acme-caa]. 2847 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2848 to this document ]] 2850 10. Security Considerations 2852 ACME is a protocol for managing certificates that attest to 2853 identifier/key bindings. Thus the foremost security goal of ACME is 2854 to ensure the integrity of this process, i.e., to ensure that the 2855 bindings attested by certificates are correct and that only 2856 authorized entities can manage certificates. ACME identifies clients 2857 by their account keys, so this overall goal breaks down into two more 2858 precise goals: 2860 1. Only an entity that controls an identifier can get an 2861 authorization for that identifier 2863 2. Once authorized, an account key's authorizations cannot be 2864 improperly used by another account 2866 In this section, we discuss the threat model that underlies ACME and 2867 the ways that ACME achieves these security goals within that threat 2868 model. We also discuss the denial-of-service risks that ACME servers 2869 face, and a few other miscellaneous considerations. 2871 10.1. Threat model 2873 As a service on the Internet, ACME broadly exists within the Internet 2874 threat model [RFC3552]. In analyzing ACME, it is useful to think of 2875 an ACME server interacting with other Internet hosts along two 2876 "channels": 2878 o An ACME channel, over which the ACME HTTPS requests are exchanged 2880 o A validation channel, over which the ACME server performs 2881 additional requests to validate a client's control of an 2882 identifier 2884 +------------+ 2885 | ACME | ACME Channel 2886 | Client |--------------------+ 2887 +------------+ | 2888 V 2889 +------------+ 2890 | ACME | 2891 | Server | 2892 +------------+ 2893 +------------+ | 2894 | Validation |<-------------------+ 2895 | Server | Validation Channel 2896 +------------+ 2897 In practice, the risks to these channels are not entirely separate, 2898 but they are different in most cases. Each channel, for example, 2899 uses a different communications pattern: the ACME channel will 2900 comprise inbound HTTPS connections to the ACME server and the 2901 validation channel outbound HTTP or DNS requests. 2903 Broadly speaking, ACME aims to be secure against active and passive 2904 attackers on any individual channel. Some vulnerabilities arise 2905 (noted below) when an attacker can exploit both the ACME channel and 2906 one of the others. 2908 On the ACME channel, in addition to network layer attackers, we also 2909 need to account for man-in-the-middle (MitM) attacks at the 2910 application layer, and for abusive use of the protocol itself. 2911 Protection against application layer MitM addresses potential 2912 attackers such as Content Distribution Networks (CDNs) and 2913 middleboxes with a TLS MitM function. Preventing abusive use of ACME 2914 means ensuring that an attacker with access to the validation channel 2915 can't obtain illegitimate authorization by acting as an ACME client 2916 (legitimately, in terms of the protocol). 2918 10.2. Integrity of Authorizations 2920 ACME allows anyone to request challenges for an identifier by 2921 registering an account key and sending a new-order request using that 2922 account key. The integrity of the authorization process thus depends 2923 on the identifier validation challenges to ensure that the challenge 2924 can only be completed by someone who both (1) holds the private key 2925 of the account key pair, and (2) controls the identifier in question. 2927 Validation responses need to be bound to an account key pair in order 2928 to avoid situations where an ACME MitM can switch out a legitimate 2929 domain holder's account key for one of his choosing, e.g.: 2931 o Legitimate domain holder registers account key pair A 2933 o MitM registers account key pair B 2935 o Legitimate domain holder sends a new-order request signed using 2936 account key A 2938 o MitM suppresses the legitimate request but sends the same request 2939 signed using account key B 2941 o ACME server issues challenges and MitM forwards them to the 2942 legitimate domain holder 2944 o Legitimate domain holder provisions the validation response 2945 o ACME server performs validation query and sees the response 2946 provisioned by the legitimate domain holder 2948 o Because the challenges were issued in response to a message signed 2949 account key B, the ACME server grants authorization to account key 2950 B (the MitM) instead of account key A (the legitimate domain 2951 holder) 2953 All of the challenges above have a binding between the account 2954 private key and the validation query made by the server, via the key 2955 authorization. The key authorization reflects the account public 2956 key, is provided to the server in the validation response over the 2957 validation channel and signed afterwards by the corresponding private 2958 key in the challenge response over the ACME channel. 2960 The association of challenges to identifiers is typically done by 2961 requiring the client to perform some action that only someone who 2962 effectively controls the identifier can perform. For the challenges 2963 in this document, the actions are: 2965 o HTTP: Provision files under .well-known on a web server for the 2966 domain 2968 o TLS SNI: Configure a TLS server for the domain 2970 o DNS: Provision DNS resource records for the domain 2972 There are several ways that these assumptions can be violated, both 2973 by misconfiguration and by attacks. For example, on a web server 2974 that allows non-administrative users to write to .well-known, any 2975 user can claim to own the web server's hostname by responding to an 2976 HTTP challenge, and likewise for TLS configuration and TLS SNI. 2977 Similarly, if a server that can be used for ACME validation is 2978 compromised by a malicious actor, then that malicious actor can use 2979 that access to obtain certificates via ACME. 2981 The use of hosting providers is a particular risk for ACME 2982 validation. If the owner of the domain has outsourced operation of 2983 DNS or web services to a hosting provider, there is nothing that can 2984 be done against tampering by the hosting provider. As far as the 2985 outside world is concerned, the zone or website provided by the 2986 hosting provider is the real thing. 2988 More limited forms of delegation can also lead to an unintended party 2989 gaining the ability to successfully complete a validation 2990 transaction. For example, suppose an ACME server follows HTTP 2991 redirects in HTTP validation and a website operator provisions a 2992 catch-all redirect rule that redirects requests for unknown resources 2993 to a different domain. Then the target of the redirect could use 2994 that to get a certificate through HTTP validation since the 2995 validation path will not be known to the primary server. 2997 The DNS is a common point of vulnerability for all of these 2998 challenges. An entity that can provision false DNS records for a 2999 domain can attack the DNS challenge directly and can provision false 3000 A/AAAA records to direct the ACME server to send its TLS SNI or HTTP 3001 validation query to a remote server of the attacker's choosing. 3002 There are a few different mitigations that ACME servers can apply: 3004 o Always querying the DNS using a DNSSEC-validating resolver 3005 (enhancing security for zones that are DNSSEC-enabled) 3007 o Querying the DNS from multiple vantage points to address local 3008 attackers 3010 o Applying mitigations against DNS off-path attackers, e.g., adding 3011 entropy to requests [I-D.vixie-dnsext-dns0x20] or only using TCP 3013 Given these considerations, the ACME validation process makes it 3014 impossible for any attacker on the ACME channel or a passive attacker 3015 on the validation channel to hijack the authorization process to 3016 authorize a key of the attacker's choice. 3018 An attacker that can only see the ACME channel would need to convince 3019 the validation server to provide a response that would authorize the 3020 attacker's account key, but this is prevented by binding the 3021 validation response to the account key used to request challenges. A 3022 passive attacker on the validation channel can observe the correct 3023 validation response and even replay it, but that response can only be 3024 used with the account key for which it was generated. 3026 An active attacker on the validation channel can subvert the ACME 3027 process, by performing normal ACME transactions and providing a 3028 validation response for his own account key. The risks due to 3029 hosting providers noted above are a particular case. 3031 It is RECOMMENDED that the server perform DNS queries and make HTTP 3032 and TLS connections from various network perspectives, in order to 3033 make MitM attacks harder. 3035 10.3. Denial-of-Service Considerations 3037 As a protocol run over HTTPS, standard considerations for TCP-based 3038 and HTTP-based DoS mitigation also apply to ACME. 3040 At the application layer, ACME requires the server to perform a few 3041 potentially expensive operations. Identifier validation transactions 3042 require the ACME server to make outbound connections to potentially 3043 attacker-controlled servers, and certificate issuance can require 3044 interactions with cryptographic hardware. 3046 In addition, an attacker can also cause the ACME server to send 3047 validation requests to a domain of its choosing by submitting 3048 authorization requests for the victim domain. 3050 All of these attacks can be mitigated by the application of 3051 appropriate rate limits. Issues closer to the front end, like POST 3052 body validation, can be addressed using HTTP request limiting. For 3053 validation and certificate requests, there are other identifiers on 3054 which rate limits can be keyed. For example, the server might limit 3055 the rate at which any individual account key can issue certificates 3056 or the rate at which validation can be requested within a given 3057 subtree of the DNS. And in order to prevent attackers from 3058 circumventing these limits simply by minting new accounts, servers 3059 would need to limit the rate at which accounts can be registered. 3061 10.4. Server-Side Request Forgery 3063 Server-Side Request Forgery (SSRF) attacks can arise when an attacker 3064 can cause a server to perform HTTP requests to an attacker-chosen 3065 URL. In the ACME HTTP challenge validation process, the ACME server 3066 performs an HTTP GET request to a URL in which the attacker can 3067 choose the domain. This request is made before the server has 3068 verified that the client controls the domain, so any client can cause 3069 a query to any domain. 3071 Some server implementations include information from the validation 3072 server's response (in order to facilitate debugging). Such 3073 implementations enable an attacker to extract this information from 3074 any web server that is accessible to the ACME server, even if it is 3075 not accessible to the ACME client. 3077 It might seem that the risk of SSRF through this channel is limited 3078 by the fact that the attacker can only control the domain of the URL, 3079 not the path. However, if the attacker first sets the domain to one 3080 they control, then they can send the server an HTTP redirect (e.g., a 3081 302 response) which will cause the server to query an arbitrary URL. 3083 In order to further limit the SSRF risk, ACME server operators should 3084 ensure that validation queries can only be sent to servers on the 3085 public Internet, and not, say, web services within the server 3086 operator's internal network. Since the attacker could make requests 3087 to these public servers himself, he can't gain anything extra through 3088 an SSRF attack on ACME aside from a layer of anonymization. 3090 10.5. CA Policy Considerations 3092 The controls on issuance enabled by ACME are focused on validating 3093 that a certificate applicant controls the identifier he claims. 3094 Before issuing a certificate, however, there are many other checks 3095 that a CA might need to perform, for example: 3097 o Has the client agreed to a subscriber agreement? 3099 o Is the claimed identifier syntactically valid? 3101 o For domain names: 3103 * If the leftmost label is a '*', then have the appropriate 3104 checks been applied? 3106 * Is the name on the Public Suffix List? 3108 * Is the name a high-value name? 3110 * Is the name a known phishing domain? 3112 o Is the key in the CSR sufficiently strong? 3114 o Is the CSR signed with an acceptable algorithm? 3116 o Has issuance been authorized or forbidden by a Certificate 3117 Authority Authorization (CAA) record? [RFC6844] 3119 CAs that use ACME to automate issuance will need to ensure that their 3120 servers perform all necessary checks before issuing. 3122 CAs using ACME to allow clients to agree to terms of service should 3123 keep in mind that ACME clients can automate this agreement, possibly 3124 not involving a human user. If a CA wishes to have stronger evidence 3125 of user consent, it may present an out-of-band requirement or 3126 challenge to require human involvement. 3128 11. Operational Considerations 3130 There are certain factors that arise in operational reality that 3131 operators of ACME-based CAs will need to keep in mind when 3132 configuring their services. For example: 3134 11.1. DNS security 3136 As noted above, DNS forgery attacks against the ACME server can 3137 result in the server making incorrect decisions about domain control 3138 and thus mis-issuing certificates. Servers SHOULD perform DNS 3139 queries over TCP, which provides better resistance to some forgery 3140 attacks than DNS over UDP. 3142 An ACME-based CA will often need to make DNS queries, e.g., to 3143 validate control of DNS names. Because the security of such 3144 validations ultimately depends on the authenticity of DNS data, every 3145 possible precaution should be taken to secure DNS queries done by the 3146 CA. It is therefore RECOMMENDED that ACME-based CAs make all DNS 3147 queries via DNSSEC-validating stub or recursive resolvers. This 3148 provides additional protection to domains which choose to make use of 3149 DNSSEC. 3151 An ACME-based CA must use only a resolver if it trusts the resolver 3152 and every component of the network route by which it is accessed. It 3153 is therefore RECOMMENDED that ACME-based CAs operate their own 3154 DNSSEC-validating resolvers within their trusted network and use 3155 these resolvers both for both CAA record lookups and all record 3156 lookups in furtherance of a challenge scheme (A, AAAA, TXT, etc.). 3158 11.2. Default Virtual Hosts 3160 In many cases, TLS-based services are deployed on hosted platforms 3161 that use the Server Name Indication (SNI) TLS extension to 3162 distinguish between different hosted services or "virtual hosts". 3163 When a client initiates a TLS connection with an SNI value indicating 3164 a provisioned host, the hosting platform routes the connection to 3165 that host. 3167 When a connection comes in with an unknown SNI value, one might 3168 expect the hosting platform to terminate the TLS connection. 3169 However, some hosting platforms will choose a virtual host to be the 3170 "default", and route connections with unknown SNI values to that 3171 host. 3173 In such cases, the owner of the default virtual host can complete a 3174 TLS-based challenge (e.g., "tls-sni-02") for any domain with an A 3175 record that points to the hosting platform. This could result in 3176 mis-issuance in cases where there are multiple hosts with different 3177 owners resident on the hosting platform. 3179 A CA that accepts TLS-based proof of domain control should attempt to 3180 check whether a domain is hosted on a domain with a default virtual 3181 host before allowing an authorization request for this host to use a 3182 TLS-based challenge. Typically, systems with default virtual hosts 3183 do not allow the holder of the default virtual host to control what 3184 certificates are presented on a request-by-request basis. Rather, 3185 the default virtual host can configure which certificate is presented 3186 in TLS on a fairly static basis, so that the certificate presented 3187 should be stable over small intervals. 3189 A CA can detect such a bounded default vhost by initiating TLS 3190 connections to the host with random SNI values within the namespace 3191 used for the TLS-based challenge (the "acme.invalid" namespace for 3192 "tls-sni-02"). If it receives the same certificate on two different 3193 connections, then it is very likely that the server is in a default 3194 virtual host configuration. Conversely, if the TLS server returns an 3195 unrecognized_name alert, then this is an indication that the server 3196 is not in a default virtual host configuration. 3198 11.3. Token Entropy 3200 The http-01, tls-sni-02 and dns-01 validation methods mandate the 3201 usage of a random token value to uniquely identify the challenge. 3202 The value of the token is required to contain at least 128 bits of 3203 entropy for the following security properties. First, the ACME 3204 client should not be able to influence the ACME server's choice of 3205 token as this may allow an attacker to reuse a domain owner's 3206 previous challenge responses for a new validation request. Secondly, 3207 the entropy requirement prevents ACME clients from implementing a 3208 "naive" validation server that automatically replies to challenges 3209 without participating in the creation of the initial authorization 3210 request. 3212 11.4. Malformed Certificate Chains 3214 ACME provides certificate chains in the widely-used format known 3215 colloquially as PEM (though it may diverge from the actual Privacy 3216 Enhanced Mail specifications [RFC1421], as noted in [RFC7468]). Some 3217 current software will allow the configuration of a private key and a 3218 certificate in one PEM file, by concatenating the textual encodings 3219 of the two objects. In the context of ACME, such software might be 3220 vulnerable to "key replacement" attacks. A malicious ACME server 3221 could cause a client to use a private key of its choosing by 3222 including the key in the PEM file returned in response to a query for 3223 a certificate URL. 3225 When processing an file of type "application/pem-certificate-chain", 3226 a client SHOULD verify that the file contains only encoded 3227 certificates. If anything other than a certificate is found (i.e., 3228 if the string "---BEGIN" is ever followed by anything other than 3229 "CERTIFICATE"), then the client MUST reject the file as invalid. 3231 12. Acknowledgements 3233 In addition to the editors listed on the front page, this document 3234 has benefited from contributions from a broad set of contributors, 3235 all the way back to its inception. 3237 o Peter Eckersley, EFF 3239 o Eric Rescorla, Mozilla 3241 o Seth Schoen, EFF 3243 o Alex Halderman, University of Michigan 3245 o Martin Thomson, Mozilla 3247 o Jakub Warmuz, University of Oxford 3249 This document draws on many concepts established by Eric Rescorla's 3250 "Automated Certificate Issuance Protocol" draft. Martin Thomson 3251 provided helpful guidance in the use of HTTP. 3253 13. References 3255 13.1. Normative References 3257 [FIPS180-4] 3258 Department of Commerce, National., "NIST FIPS 180-4, 3259 Secure Hash Standard", March 2012, 3260 . 3263 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3264 Requirement Levels", BCP 14, RFC 2119, 3265 DOI 10.17487/RFC2119, March 1997, . 3268 [RFC2585] Housley, R. and P. Hoffman, "Internet X.509 Public Key 3269 Infrastructure Operational Protocols: FTP and HTTP", 3270 RFC 2585, DOI 10.17487/RFC2585, May 1999, 3271 . 3273 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 3274 DOI 10.17487/RFC2818, May 2000, . 3277 [RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object 3278 Classes and Attribute Types Version 2.0", RFC 2985, 3279 DOI 10.17487/RFC2985, November 2000, . 3282 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 3283 Request Syntax Specification Version 1.7", RFC 2986, 3284 DOI 10.17487/RFC2986, November 2000, . 3287 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 3288 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 3289 . 3291 [RFC3492] Costello, A., "Punycode: A Bootstring encoding of Unicode 3292 for Internationalized Domain Names in Applications 3293 (IDNA)", RFC 3492, DOI 10.17487/RFC3492, March 2003, 3294 . 3296 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3297 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 3298 2003, . 3300 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3301 Resource Identifier (URI): Generic Syntax", STD 66, 3302 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3303 . 3305 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 3306 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 3307 . 3309 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3310 (TLS) Protocol Version 1.2", RFC 5246, 3311 DOI 10.17487/RFC5246, August 2008, . 3314 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3315 Housley, R., and W. Polk, "Internet X.509 Public Key 3316 Infrastructure Certificate and Certificate Revocation List 3317 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3318 . 3320 [RFC5890] Klensin, J., "Internationalized Domain Names for 3321 Applications (IDNA): Definitions and Document Framework", 3322 RFC 5890, DOI 10.17487/RFC5890, August 2010, 3323 . 3325 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 3326 DOI 10.17487/RFC5988, October 2010, . 3329 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 3330 Extensions: Extension Definitions", RFC 6066, 3331 DOI 10.17487/RFC6066, January 2011, . 3334 [RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' 3335 URI Scheme", RFC 6068, DOI 10.17487/RFC6068, October 2010, 3336 . 3338 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 3339 and D. Orchard, "URI Template", RFC 6570, 3340 DOI 10.17487/RFC6570, March 2012, . 3343 [RFC6844] Hallam-Baker, P. and R. Stradling, "DNS Certification 3344 Authority Authorization (CAA) Resource Record", RFC 6844, 3345 DOI 10.17487/RFC6844, January 2013, . 3348 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3349 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3350 2014, . 3352 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3353 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 3354 DOI 10.17487/RFC7231, June 2014, . 3357 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 3358 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 3359 April 2015, . 3361 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 3362 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 3363 2015, . 3365 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 3366 DOI 10.17487/RFC7518, May 2015, . 3369 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 3370 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 3371 2015, . 3373 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 3374 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 3375 . 3377 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3378 Writing an IANA Considerations Section in RFCs", BCP 26, 3379 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3380 . 3382 13.2. Informative References 3384 [I-D.ietf-acme-caa] 3385 Landau, H., "CAA Record Extensions for Account URI and 3386 ACME Method Binding", draft-ietf-acme-caa-03 (work in 3387 progress), August 2017. 3389 [I-D.ietf-acme-ip] 3390 Shoemaker, R., "ACME IP Identifier Validation Extension", 3391 draft-ietf-acme-ip-01 (work in progress), September 2017. 3393 [I-D.ietf-acme-telephone] 3394 Peterson, J. and R. Barnes, "ACME Identifiers and 3395 Challenges for Telephone Numbers", draft-ietf-acme- 3396 telephone-00 (work in progress), July 2017. 3398 [I-D.vixie-dnsext-dns0x20] 3399 Vixie, P. and D. Dagon, "Use of Bit 0x20 in DNS Labels to 3400 Improve Transaction Identity", draft-vixie-dnsext- 3401 dns0x20-00 (work in progress), March 2008. 3403 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 3404 Mail: Part I: Message Encryption and Authentication 3405 Procedures", RFC 1421, DOI 10.17487/RFC1421, February 3406 1993, . 3408 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 3409 Text on Security Considerations", BCP 72, RFC 3552, 3410 DOI 10.17487/RFC3552, July 2003, . 3413 [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An 3414 IETF URN Sub-namespace for Registered Protocol 3415 Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June 3416 2003, . 3418 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 3419 Uniform Resource Identifiers (URIs)", RFC 5785, 3420 DOI 10.17487/RFC5785, April 2010, . 3423 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 3424 "Recommendations for Secure Use of Transport Layer 3425 Security (TLS) and Datagram Transport Layer Security 3426 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 3427 2015, . 3429 [W3C.CR-cors-20130129] 3430 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 3431 Web Consortium CR CR-cors-20130129, January 2013, 3432 . 3434 Authors' Addresses 3436 Richard Barnes 3437 Cisco 3439 Email: rlb@ipv.sx 3441 Jacob Hoffman-Andrews 3442 EFF 3444 Email: jsha@eff.org 3446 James Kasten 3447 University of Michigan 3449 Email: jdkasten@umich.edu