idnits 2.17.1 draft-ietf-acme-acme-02.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 677 has weird spacing: '...ew-cert rev...' -- The document date (March 21, 2016) is 2957 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 531, but not defined == Missing Reference: '0-9' is mentioned on line 531, but not defined ** Obsolete normative reference: RFC 2314 (Obsoleted by RFC 2986) ** 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 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 6844 (Obsoleted by RFC 8659) ** Obsolete normative reference: RFC 6962 (Obsoleted by RFC 9162) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 11 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Barnes 3 Internet-Draft Mozilla 4 Intended status: Standards Track J. Hoffman-Andrews 5 Expires: September 22, 2016 EFF 6 J. Kasten 7 University of Michigan 8 March 21, 2016 10 Automatic Certificate Management Environment (ACME) 11 draft-ietf-acme-acme-02 13 Abstract 15 Certificates in the Web's X.509 PKI (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 certificate 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 September 22, 2016. 54 Copyright Notice 56 Copyright (c) 2016 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 72 2. Deployment Model and Operator Experience . . . . . . . . . . 4 73 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 74 4. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 6 75 5. Message Transport . . . . . . . . . . . . . . . . . . . . . . 9 76 5.1. HTTPS Requests . . . . . . . . . . . . . . . . . . . . . 9 77 5.2. Request Authentication . . . . . . . . . . . . . . . . . 9 78 5.3. Request URI Type Integrity . . . . . . . . . . . . . . . 10 79 5.4. Replay protection . . . . . . . . . . . . . . . . . . . . 11 80 5.4.1. Replay-Nonce . . . . . . . . . . . . . . . . . . . . 12 81 5.4.2. "nonce" (Nonce) JWS header parameter . . . . . . . . 12 82 5.5. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 12 83 6. Certificate Management . . . . . . . . . . . . . . . . . . . 14 84 6.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 14 85 6.1.1. Registration Objects . . . . . . . . . . . . . . . . 16 86 6.1.2. Authorization Objects . . . . . . . . . . . . . . . . 17 87 6.2. Directory . . . . . . . . . . . . . . . . . . . . . . . . 18 88 6.3. Registration . . . . . . . . . . . . . . . . . . . . . . 20 89 6.3.1. Account Key Roll-over . . . . . . . . . . . . . . . . 22 90 6.3.2. Deleting an Account . . . . . . . . . . . . . . . . . 23 91 6.4. Identifier Authorization . . . . . . . . . . . . . . . . 24 92 6.4.1. Responding to Challenges . . . . . . . . . . . . . . 26 93 6.4.2. Deleting an Authorization . . . . . . . . . . . . . . 28 94 6.5. Certificate Issuance . . . . . . . . . . . . . . . . . . 29 95 6.6. Certificate Revocation . . . . . . . . . . . . . . . . . 32 96 7. Identifier Validation Challenges . . . . . . . . . . . . . . 33 97 7.1. Key Authorizations . . . . . . . . . . . . . . . . . . . 35 98 7.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . 35 99 7.3. TLS with Server Name Indication (TLS SNI) . . . . . . . . 38 100 7.4. DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 101 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 102 9. Well-Known URI for the HTTP Challenge . . . . . . . . . . . . 41 103 9.1. Replay-Nonce HTTP Header . . . . . . . . . . . . . . . . 41 104 9.2. "nonce" JWS Header Parameter . . . . . . . . . . . . . . 41 105 9.3. URN Sub-namespace for ACME (urn:ietf:params:acme) . . . . 42 106 9.4. New Registries . . . . . . . . . . . . . . . . . . . . . 42 107 9.4.1. Error Codes . . . . . . . . . . . . . . . . . . . . . 42 108 9.4.2. Identifier Types . . . . . . . . . . . . . . . . . . 43 109 9.4.3. Challenge Types . . . . . . . . . . . . . . . . . . . 43 110 10. Security Considerations . . . . . . . . . . . . . . . . . . . 44 111 10.1. Threat model . . . . . . . . . . . . . . . . . . . . . . 44 112 10.2. Integrity of Authorizations . . . . . . . . . . . . . . 45 113 10.3. Denial-of-Service Considerations . . . . . . . . . . . . 48 114 10.4. CA Policy Considerations . . . . . . . . . . . . . . . . 49 115 11. Operational Considerations . . . . . . . . . . . . . . . . . 49 116 11.1. Default Virtual Hosts . . . . . . . . . . . . . . . . . 49 117 11.2. Use of DNSSEC Resolvers . . . . . . . . . . . . . . . . 50 118 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 50 119 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 51 120 13.1. Normative References . . . . . . . . . . . . . . . . . . 51 121 13.2. Informative References . . . . . . . . . . . . . . . . . 53 122 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 54 124 1. Introduction 126 Certificates in the Web PKI [RFC5280] are most commonly used to 127 authenticate domain names. Thus, certificate authorities in the Web 128 PKI are trusted to verify that an applicant for a certificate 129 legitimately represents the domain name(s) in the certificate. 131 Existing Web PKI certificate authorities tend to run on a set of ad 132 hoc protocols for certificate issuance and identity verification. A 133 typical user experience is something like: 135 o Generate a PKCS#10 [RFC2314] Certificate Signing Request (CSR). 137 o Cut-and-paste the CSR into a CA web page. 139 o Prove ownership of the domain by one of the following methods: 141 * Put a CA-provided challenge at a specific place on the web 142 server. 144 * Put a CA-provided challenge at a DNS location corresponding to 145 the target domain. 147 * Receive CA challenge at a (hopefully) administrator-controlled 148 e-mail address corresponding to the domain and then respond to 149 it on the CA's web page. 151 o Download the issued certificate and install it on their Web 152 Server. 154 With the exception of the CSR itself and the certificates that are 155 issued, these are all completely ad hoc procedures and are 156 accomplished by getting the human user to follow interactive natural- 157 language instructions from the CA rather than by machine-implemented 158 published protocols. In many cases, the instructions are difficult 159 to follow and cause significant confusion. Informal usability tests 160 by the authors indicate that webmasters often need 1-3 hours to 161 obtain and install a certificate for a domain. Even in the best 162 case, the lack of published, standardized mechanisms presents an 163 obstacle to the wide deployment of HTTPS and other PKIX-dependent 164 systems because it inhibits mechanization of tasks related to 165 certificate issuance, deployment, and revocation. 167 This document describes an extensible framework for automating the 168 issuance and domain validation procedure, thereby allowing servers 169 and infrastructural software to obtain certificates without user 170 interaction. Use of this protocol should radically simplify the 171 deployment of HTTPS and the practicality of PKIX authentication for 172 other protocols based on TLS [RFC5246]. 174 2. Deployment Model and Operator Experience 176 The major guiding use case for ACME is obtaining certificates for Web 177 sites (HTTPS [RFC2818]). In that case, the server is intended to 178 speak for one or more domains, and the process of certificate 179 issuance is intended to verify that the server actually speaks for 180 the domain(s). 182 Different types of certificates reflect different kinds of CA 183 verification of information about the certificate subject. "Domain 184 Validation" (DV) certificates are by far the most common type. For 185 DV validation, the CA merely verifies that the requester has 186 effective control of the web server and/or DNS server for the domain, 187 but does not explicitly attempt to verify their real-world identity. 188 (This is as opposed to "Organization Validation" (OV) and "Extended 189 Validation" (EV) certificates, where the process is intended to also 190 verify the real-world identity of the requester.) 191 DV certificate validation commonly checks claims about properties 192 related to control of a domain name - properties that can be observed 193 by the issuing authority in an interactive process that can be 194 conducted purely online. That means that under typical 195 circumstances, all steps in the request, verification, and issuance 196 process can be represented and performed by Internet protocols with 197 no out-of-band human intervention. 199 When deploying a current HTTPS server, an operator generally gets a 200 prompt to generate a self-signed certificate. When an operator 201 deploys an ACME-compatible web server, the experience would be 202 something like this: 204 o The ACME client prompts the operator for the intended domain 205 name(s) that the web server is to stand for. 207 o The ACME client presents the operator with a list of CAs from 208 which it could get a certificate. (This list will change over 209 time based on the capabilities of CAs and updates to ACME 210 configuration.) The ACME client might prompt the operator for 211 payment information at this point. 213 o The operator selects a CA. 215 o In the background, the ACME client contacts the CA and requests 216 that a certificate be issued for the intended domain name(s). 218 o Once the CA is satisfied, the certificate is issued and the ACME 219 client automatically downloads and installs it, potentially 220 notifying the operator via e-mail, SMS, etc. 222 o The ACME client periodically contacts the CA to get updated 223 certificates, stapled OCSP responses, or whatever else would be 224 required to keep the server functional and its credentials up-to- 225 date. 227 The overall idea is that it's nearly as easy to deploy with a CA- 228 issued certificate as a self-signed certificate, and that once the 229 operator has done so, the process is self-sustaining with minimal 230 manual intervention. Close integration of ACME with HTTPS servers, 231 for example, can allow the immediate and automated deployment of 232 certificates as they are issued, optionally sparing the human 233 administrator from additional configuration work. 235 3. Terminology 237 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 238 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 239 document are to be interpreted as described in RFC 2119 [RFC2119]. 241 The two main roles in ACME are "client" and "server". The ACME 242 client uses the protocol to request certificate management actions, 243 such as issuance or revocation. An ACME client therefore typically 244 runs on a web server, mail server, or some other server system which 245 requires valid TLS certificates. The ACME server runs at a 246 certificate authority, and responds to client requests, performing 247 the requested actions if the client is authorized. 249 An ACME client is represented by an "account key pair". The client 250 uses the private key of this key pair to sign all messages sent to 251 the server. The server uses the public key to verify the 252 authenticity and integrity of messages from the client. 254 4. Protocol Overview 256 ACME allows a client to request certificate management actions using 257 a set of JSON messages carried over HTTPS. In some ways, ACME 258 functions much like a traditional CA, in which a user creates an 259 account, adds identifiers to that account (proving control of the 260 domains), and requests certificate issuance for those domains while 261 logged in to the account. 263 In ACME, the account is represented by an account key pair. The "add 264 a domain" function is accomplished by authorizing the key pair for a 265 given domain. Certificate issuance and revocation are authorized by 266 a signature with the key pair. 268 The first phase of ACME is for the client to register with the ACME 269 server. The client generates an asymmetric key pair and associates 270 this key pair with a set of contact information by signing the 271 contact information. The server acknowledges the registration by 272 replying with a registration object echoing the client's input. 274 Client Server 276 Contact Information 277 Signature -------> 279 <------- Registration 281 Before a client can issue certificates, it must establish an 282 authorization with the server for an account key pair to act for the 283 identifier(s) that it wishes to include in the certificate. To do 284 this, the client must demonstrate to the server both (1) that it 285 holds the private key of the account key pair, and (2) that it has 286 authority over the identifier being claimed. 288 Proof of possession of the account key is built into the ACME 289 protocol. All messages from the client to the server are signed by 290 the client, and the server verifies them using the public key of the 291 account key pair. 293 To verify that the client controls the identifier being claimed, the 294 server issues the client a set of challenges. Because there are many 295 different ways to validate possession of different types of 296 identifiers, the server will choose from an extensible set of 297 challenges that are appropriate for the identifier being claimed. 298 The client responds with a set of responses that tell the server 299 which challenges the client has completed. The server then validates 300 the challenges to check that the client has accomplished the 301 challenge. 303 For example, if the client requests a domain name, the server might 304 challenge the client to provision a record in the DNS under that 305 name, or to provision a file on a web server referenced by an A or 306 AAAA record under that name. The server would then query the DNS for 307 the record in question, or send an HTTP request for the file. If the 308 client provisioned the DNS or the web server as expected, then the 309 server considers the client authorized for the domain name. 311 Client Server 313 Identifier 314 Signature -------> 316 <------- Challenges 318 Responses 319 Signature -------> 321 <------- Updated Challenge 323 <~~~~~~~~Validation~~~~~~~~> 325 Poll -------> 327 <------- Authorization 329 Once the client has authorized an account key pair for an identifier, 330 it can use the key pair to authorize the issuance of certificates for 331 the identifier. To do this, the client sends a PKCS#10 Certificate 332 Signing Request (CSR) to the server (indicating the identifier(s) to 333 be included in the issued certificate) and a signature over the CSR 334 by the private key of the account key pair. 336 Note that as a result, the CSR is signed twice: One by the private 337 key corresponding to the public key in the CSR, and once by the 338 private key of the account key pair. The former signature indicates 339 that the holder of the key in the CSR is willing to act for the 340 indicated identifiers, and the latter signature indicates to the 341 server that the issuance of the certificate is authorized by the 342 client (i.e., the domain holder). 344 If the server agrees to issue the certificate, then it creates the 345 certificate and provides it in its response. The certificate is 346 assigned a URI, which the client can use to fetch updated versions of 347 the certificate. 349 Client Server 351 CSR 352 Signature --------> 354 <-------- Certificate 356 To revoke a certificate, the client simply sends a revocation request 357 indicating the certificate to be revoked, signed with an authorized 358 key pair. The server indicates whether the request has succeeded. 360 Client Server 362 Revocation request 363 Signature --------> 365 <-------- Result 367 Note that while ACME is defined with enough flexibility to handle 368 different types of identifiers in principle, the primary use case 369 addressed by this document is the case where domain names are used as 370 identifiers. For example, all of the identifier validation 371 challenges described in Section 7 below address validation of domain 372 names. The use of ACME for other protocols will require further 373 specification, in order to describe how these identifiers are encoded 374 in the protocol, and what types of validation challenges the server 375 might require. 377 5. Message Transport 379 ACME uses a combination of HTTPS and JWS to create a messaging layer 380 with a few important security properties. 382 Communications between an ACME client and an ACME server are done 383 over HTTPS, using JWS to provide som additional security properties 384 for messages sent from the client to the server. HTTPS provides 385 server authentication and confidentiality. With some ACME-specific 386 extensions, JWS provides authentication of the client's request 387 payloads, anti-replay protection, and a degree of integrity for the 388 HTTPS request URI. 390 5.1. HTTPS Requests 392 Each ACME function is accomplished by the client sending a sequence 393 of HTTPS requests to the server, carrying JSON messages 394 [RFC2818][RFC7159]. Use of HTTPS is REQUIRED. Clients SHOULD 395 support HTTP public key pinning [RFC7469], and servers SHOULD emit 396 pinning headers. Each subsection of Section 6 below describes the 397 message formats used by the function, and the order in which messages 398 are sent. 400 In all HTTPS transactions used by ACME, the ACME client is the HTTPS 401 client and the ACME server is the HTTPS server. 403 ACME servers that are intended to be generally accessible need to use 404 Cross-Origin Resource Sharing (CORS) in order to be accessible from 405 browser-based clients [W3C.CR-cors-20130129]. Such servers SHOULD 406 set the Access-Control-Allow-Origin header field to the value "*". 408 Binary fields in the JSON objects used by ACME are encoded using 409 base64url encoding described in [RFC4648] Section 5, according to the 410 profile specified in JSON Web Signature [RFC7515] Section 2. This 411 encoding uses a URL safe character set. Trailing '=' characters MUST 412 be stripped. 414 5.2. Request Authentication 416 All ACME requests with a non-empty body MUST encapsulate the body in 417 a JWS object, signed using the account key pair. The server MUST 418 verify the JWS before processing the request. (For readability, 419 however, the examples below omit this encapsulation.) Encapsulating 420 request bodies in JWS provides a simple authentication of requests by 421 way of key continuity. 423 JWS objects sent in ACME requests MUST meet the following additional 424 criteria: 426 o The JWS MUST use the Flattened JSON Serialization 428 o The JWS MUST be encoded using UTF-8 430 o The JWS Header or Protected Header MUST include "alg" and "jwk" 431 fields 433 o The JWS MUST NOT have the value "none" in its "alg" field 435 o The JWS Protected Header MUST include the "nonce" field (defined 436 below) 438 Note that this implies that GET requests are not authenticated. 439 Servers MUST NOT respond to GET requests for resources that might be 440 considered sensitive. 442 5.3. Request URI Type Integrity 444 It is common in deployment the entity terminating TLS for HTTPS to be 445 different from the entity operating the logical HTTPS server, with a 446 "request routing" layer in the middle. For example, an ACME CA might 447 have a content delivery network terminate TLS connections from 448 clients so that it can inspect client requests for denial-of-service 449 protection. 451 These intermediaries can also change values in the request that are 452 not signed in the HTTPS request, e.g., the request URI and headers. 453 ACME uses JWS to provides a limited integrity mechanism, which 454 protects against an intermediary changing the request URI to anothe 455 ACME URI of a different type. (It does not protect against changing 456 between URIs of the same type, e.g., from one authorization URI to 457 another). 459 An ACME request carries a JSON dictionary that provides the details 460 of the client's request to the server. Each request object MUST have 461 a "resource" field that indicates what type of resource the request 462 is addressed to, as defined in the below table: 464 +--------------------+------------------+ 465 | Resource type | "resource" value | 466 +--------------------+------------------+ 467 | New registration | new-reg | 468 | | | 469 | New authorization | new-authz | 470 | | | 471 | New certificate | new-cert | 472 | | | 473 | Revoke certificate | revoke-cert | 474 | | | 475 | Registration | reg | 476 | | | 477 | Authorization | authz | 478 | | | 479 | Challenge | challenge | 480 | | | 481 | Certificate | cert | 482 +--------------------+------------------+ 484 Other fields in ACME request bodies are described below. 486 5.4. Replay protection 488 In order to protect ACME resources from any possible replay attacks, 489 ACME requests have a mandatory anti-replay mechanism. This mechanism 490 is based on the server maintaining a list of nonces that it has 491 issued to clients, and requiring any signed request from the client 492 to carry such a nonce. 494 An ACME server MUST include a Replay-Nonce header field in each 495 successful response it provides to a client, with contents as 496 specified below. In particular, the ACME server MUST provide a 497 Replay-Nonce header field in response to a HEAD request for any valid 498 resource. (This allows clients to easily obtain a fresh nonce.) It 499 MAY also provide nonces in error responses. 501 Every JWS sent by an ACME client MUST include, in its protected 502 header, the "nonce" header parameter, with contents as defined below. 503 As part of JWS verification, the ACME server MUST verify that the 504 value of the "nonce" header is a value that the server previously 505 provided in a Replay-Nonce header field. Once a nonce value has 506 appeared in an ACME request, the server MUST consider it invalid, in 507 the same way as a value it had never issued. 509 When a server rejects a request because its nonce value was 510 unacceptable (or not present), it SHOULD provide HTTP status code 400 511 (Bad Request), and indicate the ACME error code 512 "urn:ietf:params:acme:error:badNonce". 514 The precise method used to generate and track nonces is up to the 515 server. For example, the server could generate a random 128-bit 516 value for each response, keep a list of issued nonces, and strike 517 nonces from this list as they are used. 519 5.4.1. Replay-Nonce 521 The "Replay-Nonce" header field includes a server-generated value 522 that the server can use to detect unauthorized replay in future 523 client requests. The server should generate the value provided in 524 Replay-Nonce in such a way that they are unique to each message, with 525 high probability. 527 The value of the Replay-Nonce field MUST be an octet string encoded 528 according to the base64url encoding described in Section 2 of 529 [RFC7515]. Clients MUST ignore invalid Replay-Nonce values. 531 base64url = [A-Z] / [a-z] / [0-9] / "-" / "_" 533 Replay-Nonce = *base64url 535 The Replay-Nonce header field SHOULD NOT be included in HTTP request 536 messages. 538 5.4.2. "nonce" (Nonce) JWS header parameter 540 The "nonce" header parameter provides a unique value that enables the 541 verifier of a JWS to recognize when replay has occurred. The "nonce" 542 header parameter MUST be carried in the protected header of the JWS. 544 The value of the "nonce" header parameter MUST be an octet string, 545 encoded according to the base64url encoding described in Section 2 of 546 [RFC7515]. If the value of a "nonce" header parameter is not valid 547 according to this encoding, then the verifier MUST reject the JWS as 548 malformed. 550 5.5. Errors 552 Errors can be reported in ACME both at the HTTP layer and within ACME 553 payloads. ACME servers can return responses with an HTTP error 554 response code (4XX or 5XX). For example: If the client submits a 555 request using a method not allowed in this document, then the server 556 MAY return status code 405 (Method Not Allowed). 558 When the server responds with an error status, it SHOULD provide 559 additional information using problem document 560 [I-D.ietf-appsawg-http-problem]. To facilitate automatic response to 561 errors, this document defines the following standard tokens for use 562 in the "type" field (within the "urn:ietf:params:acme:error:" 563 namespace): 565 +----------------+--------------------------------------------------+ 566 | Code | Description | 567 +----------------+--------------------------------------------------+ 568 | badCSR | The CSR is unacceptable (e.g., due to a short | 569 | | key) | 570 | | | 571 | badNonce | The client sent an unacceptable anti-replay | 572 | | nonce | 573 | | | 574 | connection | The server could not connect to the client for | 575 | | validation | 576 | | | 577 | dnssec | The server could not validate a DNSSEC signed | 578 | | domain | 579 | | | 580 | malformed | The request message was malformed | 581 | | | 582 | serverInternal | The server experienced an internal error | 583 | | | 584 | tls | The server experienced a TLS error during | 585 | | validation | 586 | | | 587 | unauthorized | The client lacks sufficient authorization | 588 | | | 589 | unknownHost | The server could not resolve a domain name | 590 | | | 591 | rateLimited | The request exceeds a rate limit | 592 | | | 593 | invalidContact | The provided contact URI for a registration was | 594 | | invalid | 595 +----------------+--------------------------------------------------+ 597 This list is not exhaustive. The server MAY return errors whose 598 "type" field is set to a URI other than those defined above. Servers 599 MUST NOT use the ACME URN namespace for errors other than the 600 standard types. Clients SHOULD display the "detail" field of such 601 errors. 603 Authorization and challenge objects can also contain error 604 information to indicate why the server was unable to validate 605 authorization. 607 6. Certificate Management 609 In this section, we describe the certificate management functions 610 that ACME enables: 612 o Account Key Registration 614 o Account Key Authorization 616 o Certificate Issuance 618 o Certificate Renewal 620 o Certificate Revocation 622 6.1. Resources 624 ACME is structured as a REST application with a few types of 625 resources: 627 o Registration resources, representing information about an account 629 o Authorization resources, representing an account's authorization 630 to act for an identifier 632 o Challenge resources, representing a challenge to prove control of 633 an identifier 635 o Certificate resources, representing issued certificates 637 o A "directory" resource 639 o A "new-registration" resource 641 o A "new-authorization" resource 643 o A "new-certificate" resource 645 o A "revoke-certificate" resource 647 For the "new-X" resources above, the server MUST have exactly one 648 resource for each function. This resource may be addressed by 649 multiple URIs, but all must provide equivalent functionality. 651 ACME uses different URIs for different management functions. Each 652 function is listed in a directory along with its corresponding URI, 653 so clients only need to be configured with the directory URI. These 654 URIs are connected by a few different link relations [RFC5988]. 656 The "up" link relation is used with challenge resources to indicate 657 the authorization resource to which a challenge belongs. It is also 658 used from certificate resources to indicate a resource from which the 659 client may fetch a chain of CA certificates that could be used to 660 validate the certificate in the original resource. 662 The "directory" link relation is present on all resources other than 663 the directory and indicates the directory URL. 665 The following diagram illustrates the relations between resources on 666 an ACME server. The solid lines indicate link relations, and the 667 dotted lines correspond to relationships expressed in other ways, 668 e.g., the Location header in a 201 (Created) response. 670 directory 671 . 672 . 673 .................................................... 674 . . . . 675 . . . . 676 V "next" V "next" V V 677 new-reg ---+----> new-authz ---+----> new-cert revoke-cert 678 . | . | . ^ 679 . | . | . | "revoke" 680 V | V | V | 681 reg* ----+ authz -----+ cert-----------+ 682 . ^ | 683 . | "up" | "up" 684 V | V 685 challenge cert-chain 687 The following table illustrates a typical sequence of requests 688 required to establish a new account with the server, prove control of 689 an identifier, issue a certificate, and fetch an updated certificate 690 some time after issuance. The "->" is a mnemonic for a Location 691 header pointing to a created resource. 693 +--------------------+----------------+--------------+ 694 | Action | Request | Response | 695 +--------------------+----------------+--------------+ 696 | Register | POST new-reg | 201 -> reg | 697 | | | | 698 | Request challenges | POST new-authz | 201 -> authz | 699 | | | | 700 | Answer challenges | POST challenge | 200 | 701 | | | | 702 | Poll for status | GET authz | 200 | 703 | | | | 704 | Request issuance | POST new-cert | 201 -> cert | 705 | | | | 706 | Check for new cert | GET cert | 200 | 707 +--------------------+----------------+--------------+ 709 The remainder of this section provides the details of how these 710 resources are structured and how the ACME protocol makes use of them. 712 6.1.1. Registration Objects 714 An ACME registration resource represents a set of metadata associated 715 to an account key pair. Registration resources have the following 716 structure: 718 key (required, dictionary): The public key of the account key pair, 719 encoded as a JSON Web Key object [RFC7517]. 721 contact (optional, array of string): An array of URIs that the 722 server can use to contact the client for issues related to this 723 authorization. For example, the server may wish to notify the 724 client about server-initiated revocation. 726 agreement (optional, string): A URI referring to a subscriber 727 agreement or terms of service provided by the server (see below). 728 Including this field indicates the client's agreement with the 729 referenced terms. 731 authorizations (required, string): A URI from which a list of 732 authorizations granted to this account can be fetched via a GET 733 request. The result of the GET request MUST be a JSON object 734 whose "authorizations" field is an array of strings, where each 735 string is the URI of an authorization belonging to this 736 registration. The server SHOULD include pending authorizations, 737 and SHOULD NOT include authorizations that are invalid or expired. 738 The server MAY return an incomplete list, along with a Link header 739 with link relation "next" indicating a URL to retrieve further 740 entries. 742 certificates (required, string): A URI from which a list of 743 certificates issued for this account can be fetched via a GET 744 request. The result of the GET request MUST be a JSON object 745 whose "certificates" field is an array of strings, where each 746 string is the URI of a certificate. The server SHOULD NOT include 747 expired or revoked certificates. The server MAY return an 748 incomplete list, along with a Link header with link relation 749 "next" indicating a URL to retrieve further entries. 751 { 752 "resource": "new-reg", 753 "contact": [ 754 "mailto:cert-admin@example.com", 755 "tel:+12025551212" 756 ], 757 "agreement": "https://example.com/acme/terms", 758 "authorizations": "https://example.com/acme/reg/1/authz", 759 "certificates": "https://example.com/acme/reg/1/cert", 760 } 762 6.1.2. Authorization Objects 764 An ACME authorization object represents server's authorization for an 765 account to represent an identifier. In addition to the identifier, 766 an authorization includes several metadata fields, such as the status 767 of the authorization (e.g., "pending", "valid", or "revoked") and 768 which challenges were used to validate possession of the identifier. 770 The structure of an ACME authorization resource is as follows: 772 identifier (required, dictionary of string): The identifier that the 773 account is authorized to represent 775 type (required, string): The type of identifier. 777 value (required, string): The identifier itself. 779 status (required, string): The status of this authorization. 780 Possible values are: "unknown", "pending", "processing", "valid", 781 "invalid" and "revoked". If this field is missing, then the 782 default value is "pending". 784 expires (optional, string): The timestamp after which the server 785 will consider this authorization invalid, encoded in the format 786 specified in RFC 3339 [RFC3339]. This field is REQUIRED for 787 objects with "valid" in the "status field. 789 challenges (required, array): The challenges that the client needs 790 to fulfill in order to prove possession of the identifier (for 791 pending authorizations). For final authorizations, the challenges 792 that were used. Each array entry is a dictionary with parameters 793 required to validate the challenge, as specified in Section 7. 795 combinations (optional, array of arrays of integers): A collection 796 of sets of challenges, each of which would be sufficient to prove 797 possession of the identifier. Clients complete a set of 798 challenges that covers at least one set in this array. Challenges 799 are identified by their indices in the challenges array. If no 800 "combinations" element is included in an authorization object, the 801 client completes all challenges. 803 The only type of identifier defined by this specification is a fully- 804 qualified domain name (type: "dns"). The value of the identifier 805 MUST be the ASCII representation of the domain name. Wildcard domain 806 names (with "*" as the first label) MUST NOT be included in 807 authorization requests. See Section 6.5 below for more information 808 about wildcard domains. 810 { 811 "status": "valid", 812 "expires": "2015-03-01T14:09:00Z", 814 "identifier": { 815 "type": "dns", 816 "value": "example.org" 817 }, 819 "challenges": [ 820 { 821 "type": "http-01", 822 "status": "valid", 823 "validated": "2014-12-01T12:05:00Z", 824 "keyAuthorization": "SXQe-2XODaDxNR...vb29HhjjLPSggwiE" 825 } 826 ], 827 } 829 6.2. Directory 831 In order to help clients configure themselves with the right URIs for 832 each ACME operation, ACME servers provide a directory object. This 833 should be the only URL needed to configure clients. It is a JSON 834 dictionary, whose keys are the "resource" values listed in 835 Section 5.1, and whose values are the URIs used to accomplish the 836 corresponding function. 838 There is no constraint on the actual URI of the directory except that 839 it should be different from the other ACME server resources' URIs, 840 and that it should not clash with other services. For instance: 842 o a host which function as both an ACME and Web server may want to 843 keep the root path "/" for an HTML "front page", and and place the 844 ACME directory under path "/acme". 846 o a host which only functions as an ACME server could place the 847 directory under path "/". 849 The dictionary MAY additionally contain a key "meta". If present, it 850 MUST be a JSON dictionary; each item in the dictionary is an item of 851 metadata relating to the service provided by the ACME server. 853 The following metadata items are defined, all of which are OPTIONAL: 855 "terms-of-service" (optional, string): A URI identifying the current 856 terms of service. 858 "website" (optional, string)): An HTTP or HTTPS URL locating a 859 website providing more information about the ACME server. 861 "caa-identities" (optional, array of string): Each string MUST be a 862 lowercase hostname which the ACME server recognises as referring 863 to itself for the purposes of CAA record validation as defined in 864 [RFC6844]. This allows clients to determine the correct issuer 865 domain name to use when configuring CAA record. 867 Clients access the directory by sending a GET request to the 868 directory URI. 870 HTTP/1.1 200 OK 871 Content-Type: application/json 873 { 874 "new-reg": "https://example.com/acme/new-reg", 875 "new-authz": "https://example.com/acme/new-authz", 876 "new-cert": "https://example.com/acme/new-cert", 877 "revoke-cert": "https://example.com/acme/revoke-cert", 878 "meta": { 879 "terms-of-service": "https://example.com/acme/terms", 880 "website": "https://www.example.com/", 881 "caa-identities": ["example.com"] 882 } 883 } 885 6.3. Registration 887 A client creates a new account with the server by sending a POST 888 request to the server's new-registration URI. The body of the 889 request is a stub registration object containing only the "contact" 890 field (along with the required "resource" field). 892 POST /acme/new-registration HTTP/1.1 893 Host: example.com 895 { 896 "resource": "new-reg", 897 "contact": [ 898 "mailto:cert-admin@example.com", 899 "tel:+12025551212" 900 ], 901 } 902 /* Signed as JWS */ 904 The server MUST ignore any values provided in the "key", 905 "authorizations", and "certificates" fields in registration bodies 906 sent by the client, as well as any other fields that it does not 907 recognize. If new fields are specified in the future, the 908 specification of those fields MUST describe whether they may be 909 provided by the client. 911 The server creates a registration object with the included contact 912 information. The "key" element of the registration is set to the 913 public key used to verify the JWS (i.e., the "jwk" element of the JWS 914 header). The server returns this registration object in a 201 915 (Created) response, with the registration URI in a Location header 916 field. The server SHOULD also indicate its new-authorization URI 917 using the "next" link relation. 919 If the server already has a registration object with the provided 920 account key, then it MUST return a 409 (Conflict) response and 921 provide the URI of that registration in a Location header field. 922 This allows a client that has an account key but not the 923 corresponding registration URI to recover the registration URI. 925 If the server wishes to present the client with terms under which the 926 ACME service is to be used, it MUST indicate the URI where such terms 927 can be accessed in a Link header with link relation "terms-of- 928 service". As noted above, the client may indicate its agreement with 929 these terms by updating its registration to include the "agreement" 930 field, with the terms URI as its value. When these terms change in a 931 way that requires an agreement update, the server MUST use a 932 different URI in the Link header. 934 HTTP/1.1 201 Created 935 Content-Type: application/json 936 Location: https://example.com/acme/reg/asdf 937 Link: ;rel="next" 938 Link: ;rel="terms-of-service" 939 Link: ;rel="directory" 941 { 942 "key": { /* JWK from JWS header */ }, 944 "contact": [ 945 "mailto:cert-admin@example.com", 946 "tel:+12025551212" 947 ] 948 } 950 If the client wishes to update this information in the future, it 951 sends a POST request with updated information to the registration 952 URI. The server MUST ignore any updates to the "key", 953 "authorizations, or "certificates" fields, and MUST verify that the 954 request is signed with the private key corresponding to the "key" 955 field of the request before updating the registration. 957 For example, to update the contact information in the above 958 registration, the client could send the following request: 960 POST /acme/reg/asdf HTTP/1.1 961 Host: example.com 963 { 964 "resource": "reg", 965 "contact": [ 966 "mailto:certificates@example.com", 967 "tel:+12125551212" 968 ], 969 } 970 /* Signed as JWS */ 972 Servers SHOULD NOT respond to GET requests for registration resources 973 as these requests are not authenticated. If a client wishes to query 974 the server for information about its account (e.g., to examine the 975 "contact" or "certificates" fields), then it SHOULD do so by sending 976 a POST request with an empty update. That is, it should send a JWS 977 whose payload is trivial ({"resource":"reg"}). In this case the 978 server reply MUST contain the same link headers sent for a new 979 registration, to allow a client to retrieve the "new-authorization" 980 and "terms-of-service" URI 982 6.3.1. Account Key Roll-over 984 A client may wish to change the public key that is associated with a 985 registration, e.g., in order to mitigate the risk of key compromise. 986 To do this, the client first constructs a JSON object representing a 987 request to update the registration: 989 resource (required, string): The string "reg", indicating an update 990 to the registration. 992 oldKey (required, string): The JWK thumbprint of the old key 993 [RFC7638], base64url-encoded 995 { 996 "resource": "reg", 997 "oldKey": "D7J9RL1f-RWUl68JP-gW1KSl2TkIrJB7hK6rLFFeYMU" 998 } 1000 The client signs this object with the new key pair and encodes the 1001 object and signature as a JWS. The client then sends this JWS to the 1002 server in the "newKey" field of a request to update the registration. 1004 POST /acme/reg/asdf HTTP/1.1 1005 Host: example.com 1007 { 1008 "resource": "reg", 1009 "newKey": /* JSON object signed as JWS with new key */ 1010 } 1011 /* Signed as JWS with original key */ 1013 On receiving a request to the registration URL with the "newKey" 1014 attribute set, the server MUST perform the following steps: 1016 1. Check that the contents of the "newKey" attribute are a valid JWS 1018 2. Check that the "newKey" JWS verifies using the key in the "jwk" 1019 header parameter of the JWS 1021 3. Check that the payload of the JWS is a valid JSON object 1023 4. Check that the "resource" field of the object has the value "reg" 1025 5. Check that the "oldKey" field of the object contains the JWK 1026 thumbprint of the account key for this registration 1028 If all of these checks pass, then the server updates the registration 1029 by replacing the old account key with the public key carried in the 1030 "jwk" header parameter of the "newKey" JWS object. 1032 If the update was successful, then the server sends a response with 1033 status code 200 (OK) and the updated registration object as its body. 1034 If the update was not successful, then the server responds with an 1035 error status code and a problem document describing the error. 1037 6.3.2. Deleting an Account 1039 If a client no longer wishes to have an account key registered with 1040 the server, it may request that the server delete its account by 1041 sending a POST request to the account URI containing the "delete" 1042 field. 1044 delete (required, boolean): The boolean value "true". 1046 The request object MUST contain the "resource" field as required 1047 above (with the value "reg"). It MUST NOT contain any fields besides 1048 "resource" and "delete". 1050 Note that although this object is very simple, the risk of replay or 1051 fraudulent generation via signing oracles is mitigated by the need 1052 for an anti-replay token in the protected header of the JWS. 1054 POST /acme/reg/asdf HTTP/1.1 1055 Host: example.com 1057 { 1058 "resource": "reg", 1059 "delete": true, 1060 } 1061 /* Signed as JWS */ 1063 On receiving a POST to an account URI containing a "delete" field, 1064 the server MUST verify that no other fields were sent in the object 1065 (other than "resource"), and it MUST verify that the value of the 1066 "delete" field is "true" (as a boolean, not a string). If either of 1067 these checks fails, then the server MUST reject the request with 1068 status code 400 (Bad Request). 1070 If the server accepts the deletion request, then it MUST delete the 1071 account and all related objects and send a response with a 200 (OK) 1072 status code and an empty body. The server SHOULD delete any 1073 authorization objects related to the deleted account, since they can 1074 no longer be used. The server SHOULD NOT delete certificate objects 1075 related to the account, since certificates issued under the account 1076 continue to be valid until they expire or are revoked. 1078 6.4. Identifier Authorization 1080 The identifier authorization process establishes the authorization of 1081 an account to manage certificates for a given identifier. This 1082 process must assure the server of two things: First, that the client 1083 controls the private key of the account key pair, and second, that 1084 the client holds the identifier in question. This process may be 1085 repeated to associate multiple identifiers to a key pair (e.g., to 1086 request certificates with multiple identifiers), or to associate 1087 multiple accounts with an identifier (e.g., to allow multiple 1088 entities to manage certificates). 1090 As illustrated by the figure in the overview section above, the 1091 authorization process proceeds in two phases. The client first 1092 requests a new authorization, and the server issues challenges, then 1093 the client responds to those challenges and the server validates the 1094 client's responses. 1096 To begin the key authorization process, the client sends a POST 1097 request to the server's new-authorization resource. The body of the 1098 POST request MUST contain a JWS object, whose payload is a partial 1099 authorization object. This JWS object MUST contain only the 1100 "identifier" field, so that the server knows what identifier is being 1101 authorized. The server MUST ignore any other fields present in the 1102 client's request object. 1104 The authorization object is implicitly tied to the account key used 1105 to sign the request. Once created, the authorization may only be 1106 updated by that account. 1108 POST /acme/new-authorization HTTP/1.1 1109 Host: example.com 1111 { 1112 "resource": "new-authz", 1113 "identifier": { 1114 "type": "dns", 1115 "value": "example.org" 1116 } 1117 } 1118 /* Signed as JWS */ 1120 Before processing the authorization further, the server SHOULD 1121 determine whether it is willing to issue certificates for the 1122 identifier. For example, the server should check that the identifier 1123 is of a supported type. Servers might also check names against a 1124 blacklist of known high-value identifiers. If the server is 1125 unwilling to issue for the identifier, it SHOULD return a 403 1126 (Forbidden) error, with a problem document describing the reason for 1127 the rejection. 1129 If the server is willing to proceed, it builds a pending 1130 authorization object from the initial authorization object submitted 1131 by the client. 1133 o "identifier" the identifier submitted by the client 1135 o "status": MUST be "pending" unless the server has out-of-band 1136 information about the client's authorization status 1138 o "challenges" and "combinations": As selected by the server's 1139 policy for this identifier 1141 The server allocates a new URI for this authorization, and returns a 1142 201 (Created) response, with the authorization URI in a Location 1143 header field, and the JSON authorization object in the body. 1145 HTTP/1.1 201 Created 1146 Content-Type: application/json 1147 Location: https://example.com/authz/asdf 1148 Link: ;rel="next" 1149 Link: ;rel="directory" 1151 { 1152 "status": "pending", 1154 "identifier": { 1155 "type": "dns", 1156 "value": "example.org" 1157 }, 1159 "challenges": [ 1160 { 1161 "type": "http-01", 1162 "uri": "https://example.com/authz/asdf/0", 1163 "token": "IlirfxKKXAsHtmzK29Pj8A" 1164 }, 1165 { 1166 "type": "dns-01", 1167 "uri": "https://example.com/authz/asdf/1", 1168 "token": "DGyRejmCefe7v4NfDGDKfA" 1169 } 1170 }, 1172 "combinations": [[0], [1]] 1173 } 1175 6.4.1. Responding to Challenges 1177 To prove control of the identifer and receive authorization, the 1178 client needs to respond with information to complete the challenges. 1179 To do this, the client updates the authorization object received from 1180 the server by filling in any required information in the elements of 1181 the "challenges" dictionary. (This is also the stage where the 1182 client should perform any actions required by the challenge.) 1184 The client sends these updates back to the server in the form of a 1185 JSON object with the response fields required by the challenge type, 1186 carried in a POST request to the challenge URI (not authorization URI 1187 or the new-authorization URI). This allows the client to send 1188 information only for challenges it is responding to. 1190 For example, if the client were to respond to the "http-01" challenge 1191 in the above authorization, it would send the following request: 1193 POST /acme/authz/asdf/0 HTTP/1.1 1194 Host: example.com 1196 { 1197 "resource": "challenge", 1198 "type": "http-01", 1199 "keyAuthorization": "IlirfxKKXA...vb29HhjjLPSggwiE" 1200 } 1201 /* Signed as JWS */ 1203 The server updates the authorization document by updating its 1204 representation of the challenge with the response fields provided by 1205 the client. The server MUST ignore any fields in the response object 1206 that are not specified as response fields for this type of challenge. 1207 The server provides a 200 (OK) response with the updated challenge 1208 object as its body. 1210 If the client's response is invalid for some reason, or does not 1211 provide the server with appropriate information to validate the 1212 challenge, then the server MUST return an HTTP error. On receiving 1213 such an error, the client SHOULD undo any actions that have been 1214 taken to fulfill the challenge, e.g., removing files that have been 1215 provisioned to a web server. 1217 Presumably, the client's responses provide the server with enough 1218 information to validate one or more challenges. The server is said 1219 to "finalize" the authorization when it has completed all the 1220 validations it is going to complete, and assigns the authorization a 1221 status of "valid" or "invalid", corresponding to whether it considers 1222 the account authorized for the identifier. If the final state is 1223 "valid", the server MUST add an "expires" field to the authorization. 1224 When finalizing an authorization, the server MAY remove the 1225 "combinations" field (if present) or remove any challenges still 1226 pending. The server SHOULD NOT remove challenges with status 1227 "invalid". 1229 Usually, the validation process will take some time, so the client 1230 will need to poll the authorization resource to see when it is 1231 finalized. For challenges where the client can tell when the server 1232 has validated the challenge (e.g., by seeing an HTTP or DNS request 1233 from the server), the client SHOULD NOT begin polling until it has 1234 seen the validation request from the server. 1236 To check on the status of an authorization, the client sends a GET 1237 request to the authorization URI, and the server responds with the 1238 current authorization object. In responding to poll requests while 1239 the validation is still in progress, the server MUST return a 202 1240 (Accepted) response, and MAY include a Retry-After header field to 1241 suggest a polling interval to the client. 1243 GET /acme/authz/asdf HTTP/1.1 1244 Host: example.com 1246 HTTP/1.1 200 OK 1248 { 1249 "status": "valid", 1250 "expires": "2015-03-01T14:09:00Z", 1252 "identifier": { 1253 "type": "dns", 1254 "value": "example.org" 1255 }, 1257 "challenges": [ 1258 { 1259 "type": "http-01" 1260 "status": "valid", 1261 "validated": "2014-12-01T12:05:00Z", 1262 "token": "IlirfxKKXAsHtmzK29Pj8A", 1263 "keyAuthorization": "IlirfxKKXA...vb29HhjjLPSggwiE" 1264 } 1265 ] 1266 } 1268 6.4.2. Deleting an Authorization 1270 If a client wishes to relinquish its authorization to issue 1271 certificates for an identifier, then it may request that the server 1272 delete the authorization. The client makes this request by sending a 1273 POST request to the authorization URI containing a payload in the 1274 same format as in Section 6.3.2. The only difference is that the 1275 value of the "resource" field is "authz". 1277 POST /acme/authz/asdf HTTP/1.1 1278 Host: example.com 1280 { 1281 "resource": "authz", 1282 "delete": true, 1283 } 1284 /* Signed as JWS */ 1286 The server MUST perform the same validity checks as in Section 6.3.2 1287 and reject the request if they fail. If the server deletes the 1288 account then it MUST send a response with a 200 (OK) status code and 1289 an empty body. 1291 6.5. Certificate Issuance 1293 The holder of an account key pair authorized for one or more 1294 identifiers may use ACME to request that a certificate be issued for 1295 any subset of those identifiers. The client makes this request by 1296 sending a POST request to the server's new-certificate resource. The 1297 body of the POST is a JWS object whose JSON payload contains a 1298 Certificate Signing Request (CSR) [RFC2986]. The CSR encodes the 1299 parameters of the requested certificate; authority to issue is 1300 demonstrated by the JWS signature by an account key, from which the 1301 server can look up related authorizations. Some attributes which 1302 cannot be reflected in a CSR are placed directly in the certificate 1303 request. 1305 csr (required, string): A CSR encoding the parameters for the 1306 certificate being requested. The CSR is sent in the Base64url- 1307 encoded version of the DER format. (Note: This field uses the 1308 same modified Base64 encoding rules used elsewhere in this 1309 document, so it is different from PEM.) 1311 notBefore (optional, string): The requested value of the notBefore 1312 field in the certificate, in the date format defined in [RFC3339] 1314 notAfter (optional, string): The requested value of the notAfter 1315 field in the certificate, in the date format defined in [RFC3339] 1317 POST /acme/new-cert HTTP/1.1 1318 Host: example.com 1319 Accept: application/pkix-cert 1321 { 1322 "resource": "new-cert", 1323 "csr": "5jNudRx6Ye4HzKEqT5...FS6aKdZeGsysoCo4H9P", 1324 "notBefore": "2016-01-01T00:00:00Z", 1325 "notAfter": "2016-01-08T00:00:00Z" 1326 } 1327 /* Signed as JWS */ 1329 The CSR encodes the client's requests with regard to the content of 1330 the certificate to be issued. The CSR MUST indicate the requested 1331 identifiers, either in the commonName portion of the requested 1332 subject name, or in an extensionRequest attribute [RFC2985] 1333 requesting a subjectAltName extension. 1335 The values provided in the CSR are only a request, and are not 1336 guaranteed. The server SHOULD return an error if it cannot fulfil 1337 the request as specified, but MAY issue a certificate with contents 1338 other than those requested, according to its local policy (e.g., 1339 removing identifiers for which the client is not authorized). 1341 It is up to the server's local policy to decide which names are 1342 acceptable in a certificate, given the authorizations that the server 1343 associates with the client's account key. A server MAY consider a 1344 client authorized for a wildcard domain if it is authorized for the 1345 underlying domain name (without the "*" label). Servers SHOULD NOT 1346 extend authorization across identifier types. For example, if a 1347 client is authorized for "example.com", then the server should not 1348 allow the client to issue a certificate with an iPAddress 1349 subjectAltName, even if it contains an IP address to which 1350 example.com resolves. 1352 If the CA decides to issue a certificate, then the server creates a 1353 new certificate resource and returns a URI for it in the Location 1354 header field of a 201 (Created) response. 1356 HTTP/1.1 201 Created 1357 Location: https://example.com/acme/cert/asdf 1359 If the certificate is available at the time of the response, it is 1360 provided in the body of the response. If the CA has not yet issued 1361 the certificate, the body of this response will be empty. The client 1362 should then send a GET request to the certificate URI to poll for the 1363 certificate. As long as the certificate is unavailable, the server 1364 MUST provide a 202 (Accepted) response and include a Retry-After 1365 header to indicate when the server believes the certificate will be 1366 issued (as in the example above). 1368 GET /acme/cert/asdf HTTP/1.1 1369 Host: example.com 1370 Accept: application/pkix-cert 1372 HTTP/1.1 202 Accepted 1373 Retry-After: 120 1375 The default format of the certificate is DER (application/pkix-cert). 1376 The client may request other formats by including an Accept header in 1377 its request. 1379 The server provides metadata about the certificate in HTTP headers. 1380 In particular, the server MUST include a Link relation header field 1381 [RFC5988] with relation "up" to provide a certificate under which 1382 this certificate was issued, and one with relation "author" to 1383 indicate the registration under which this certificate was issued. 1385 The server MAY include an Expires header as a hint to the client 1386 about when to renew the certificate. (Of course, the real expiration 1387 of the certificate is controlled by the notAfter time in the 1388 certificate itself.) 1390 If the CA participates in Certificate Transparency (CT) [RFC6962], 1391 then they may want to provide the client with a Signed Certificate 1392 Timestamp (SCT) that can be used to prove that a certificate was 1393 submitted to a CT log. An SCT can be included as an extension in the 1394 certificate or as an extension to OCSP responses for the certificate. 1395 The server can also provide the client with direct access to an SCT 1396 for a certificate using a Link relation header field with relation 1397 "ct-sct". 1399 GET /acme/cert/asdf HTTP/1.1 1400 Host: example.com 1401 Accept: application/pkix-cert 1403 HTTP/1.1 200 OK 1404 Content-Type: application/pkix-cert 1405 Link: ;rel="up";title="issuer" 1406 Link: ;rel="revoke" 1407 Link: ;rel="author" 1408 Link: ;rel="ct-sct" 1409 Link: ;rel="directory" 1410 Location: https://example.com/acme/cert/asdf 1411 Content-Location: https://example.com/acme/cert-seq/12345 1413 [DER-encoded certificate] 1415 A certificate resource always represents the most recent certificate 1416 issued for the name/key binding expressed in the CSR. If the CA 1417 allows a certificate to be renewed, then it publishes renewed 1418 versions of the certificate through the same certificate URI. 1420 Clients retrieve renewed versions of the certificate using a GET 1421 query to the certificate URI, which the server should then return in 1422 a 200 (OK) response. The server SHOULD provide a stable URI for each 1423 specific certificate in the Content-Location header field, as shown 1424 above. Requests to stable certificate URIs MUST always result in the 1425 same certificate. 1427 To avoid unnecessary renewals, the CA may choose not to issue a 1428 renewed certificate until it receives such a request (if it even 1429 allows renewal at all). In such cases, if the CA requires some time 1430 to generate the new certificate, the CA MUST return a 202 (Accepted) 1431 response, with a Retry-After header field that indicates when the new 1432 certificate will be available. The CA MAY include the current (non- 1433 renewed) certificate as the body of the response. 1435 Likewise, in order to prevent unnecessary renewal due to queries by 1436 parties other than the account key holder, certificate URIs should be 1437 structured as capability URLs [W3C.WD-capability-urls-20140218]. 1439 From the client's perspective, there is no difference between a 1440 certificate URI that allows renewal and one that does not. If the 1441 client wishes to obtain a renewed certificate, and a GET request to 1442 the certificate URI does not yield one, then the client may initiate 1443 a new-certificate transaction to request one. 1445 6.6. Certificate Revocation 1447 To request that a certificate be revoked, the client sends a POST 1448 request to the ACME server's revoke-cert URI. The body of the POST 1449 is a JWS object whose JSON payload contains the certificate to be 1450 revoked: 1452 certificate (required, string): The certificate to be revoked, in 1453 the base64url-encoded version of the DER format. (Note: This 1454 field uses the same modified Base64 encoding rules used elsewhere 1455 in this document, so it is different from PEM.) 1457 POST /acme/revoke-cert HTTP/1.1 1458 Host: example.com 1460 { 1461 "resource": "revoke-cert", 1462 "certificate": "MIIEDTCCAvegAwIBAgIRAP8..." 1463 } 1464 /* Signed as JWS */ 1466 Revocation requests are different from other ACME request in that 1467 they can be signed either with an account key pair or the key pair in 1468 the certificate. Before revoking a certificate, the server MUST 1469 verify that the key used to sign the request is authorized to revoke 1470 the certificate. The server SHOULD consider at least the following 1471 keys authorized for a given certificate: 1473 o the public key in the certificate. 1475 o an account key that is authorized to act for all of the 1476 identifier(s) in the certificate. 1478 If the revocation succeeds, the server responds with status code 200 1479 (OK). If the revocation fails, the server returns an error. 1481 HTTP/1.1 200 OK 1482 Content-Length: 0 1484 --- or --- 1486 HTTP/1.1 403 Forbidden 1487 Content-Type: application/problem+json 1488 Content-Language: en 1490 { 1491 "type": "urn:ietf:params:acme:error:unauthorized" 1492 "detail": "No authorization provided for name example.net" 1493 "instance": "http://example.com/doc/unauthorized" 1494 } 1496 7. Identifier Validation Challenges 1498 There are few types of identifiers in the world for which there is a 1499 standardized mechanism to prove possession of a given identifier. In 1500 all practical cases, CAs rely on a variety of means to test whether 1501 an entity applying for a certificate with a given identifier actually 1502 controls that identifier. 1504 Challenges provide the server with assurance that an account key 1505 holder is also the entity that controls an identifier. For each type 1506 of challenge, it must be the case that in order for an entity to 1507 successfully complete the challenge the entity must both: 1509 o Hold the private key of the account key pair used to respond to 1510 the challenge 1512 o Control the identifier in question 1514 Section 10 documents how the challenges defined in this document meet 1515 these requirements. New challenges will need to document how they 1516 do. 1518 ACME uses an extensible challenge/response framework for identifier 1519 validation. The server presents a set of challenge in the 1520 authorization object it sends to a client (as objects in the 1521 "challenges" array), and the client responds by sending a response 1522 object in a POST request to a challenge URI. 1524 This section describes an initial set of challenge types. Each 1525 challenge must describe: 1527 1. Content of challenge objects 1529 2. Content of response objects 1531 3. How the server uses the challenge and response to verify control 1532 of an identifier 1534 Challenge objects all contain the following basic fields: 1536 type (required, string): The type of challenge encoded in the 1537 object. 1539 uri (required, string): The URI to which a response can be posted. 1541 status (required, string): The status of this authorization. 1542 Possible values are: "pending", "valid", and "invalid". If this 1543 field is missing, then the default value is "pending". 1545 validated (optional, string): The time at which this challenge was 1546 completed by the server, encoded in the format specified in RFC 1547 3339 [RFC3339]. This field is REQUIRED if the "status" field is 1548 "valid". 1550 error (optional, dictionary of string): The error that occurred 1551 while the server was validating the challenge, if any. This field 1552 is structured as a problem document 1553 [I-D.ietf-appsawg-http-problem]. 1555 All additional fields are specified by the challenge type. If the 1556 server sets a challenge's "status" to "invalid", it SHOULD also 1557 include the "error" field to help the client diagnose why they failed 1558 the challenge. 1560 Different challenges allow the server to obtain proof of different 1561 aspects of control over an identifier. In some challenges, like HTTP 1562 and TLS SNI, the client directly proves its ability to do certain 1563 things related to the identifier. The choice of which challenges to 1564 offer to a client under which circumstances is a matter of server 1565 policy. 1567 The identifier validation challenges described in this section all 1568 relate to validation of domain names. If ACME is extended in the 1569 future to support other types of identifier, there will need to be 1570 new challenge types, and they will need to specify which types of 1571 identifier they apply to. 1573 [[ Editor's Note: In pre-RFC versions of this specification, 1574 challenges are labeled by type, and with the version of the draft in 1575 which they were introduced. For example, if an HTTP challenge were 1576 introduced in version -03 and a breaking change made in version -05, 1577 then there would be a challenge labeled "http-03" and one labeled 1578 "http-05" - but not one labeled "http-04", since challenge in version 1579 -04 was compatible with one in version -04. ]] 1581 [[ Editor's Note: Operators SHOULD NOT issue "combinations" arrays in 1582 authorization objects that require the client to perform multiple 1583 challenges over the same type, e.g., ["http-03", "http-05"]. 1584 Challenges within a type are testing the same capability of the 1585 domain owner, and it may not be possible to satisfy both at once. ]] 1587 7.1. Key Authorizations 1589 Several of the challenges in this document makes use of a key 1590 authorization string. A key authorization is a string that expresses 1591 a domain holder's authorization for a specified key to satisfy a 1592 specified challenge, by concatenating the token for the challenge 1593 with a key fingerprint, separated by a "." character: 1595 key-authz = token || '.' || base64url(JWK\_Thumbprint(accountKey)) 1597 The "JWK_Thumbprint" step indicates the computation specified in 1598 [RFC7638], using the SHA-256 digest. As specified in the individual 1599 challenges below, the token for a challenge is a JSON string 1600 comprised entirely of characters in the URL-safe Base64 alphabet. 1601 The "||" operator indicates concatenation of strings. 1603 In computations involving key authorizations, such as the digest 1604 computations required for the DNS and TLS SNI challenges, the key 1605 authorization string MUST be represented in UTF-8 form (or, 1606 equivalently, ASCII). 1608 An example of how to compute a JWK thumbprint can be found in 1609 Section 3.1 of [RFC7638]. Note that some cryptographic libraries 1610 prepend a zero octet to the representation of the RSA public key 1611 parameters N and E, in order to avoid ambiguity with regard to the 1612 sign of the number. As noted in JWA [RFC7518], a JWK object MUST NOT 1613 include this zero octet. That is, any initial zero octets MUST be 1614 stripped before the values are base64url-encoded. 1616 7.2. HTTP 1618 With HTTP validation, the client in an ACME transaction proves its 1619 control over a domain name by proving that it can provision resources 1620 on an HTTP server that responds for that domain name. The ACME 1621 server challenges the client to provision a file at a specific path, 1622 with a specific string as its content. 1624 As a domain may resolve to multiple IPv4 and IPv6 addresses, the 1625 server will connect to at least one of the hosts found in A and AAAA 1626 records. Because many web servers allocate a default HTTPS virtual 1627 host to a particular low-privilege tenant user in a subtle and non- 1628 intuitive manner, the challenge must be completed over HTTP, not 1629 HTTPS. 1631 type (required, string): The string "http-01" 1633 token (required, string): A random value that uniquely identifies 1634 the challenge. This value MUST have at least 128 bits of entropy, 1635 in order to prevent an attacker from guessing it. It MUST NOT 1636 contain any characters outside the URL-safe Base64 alphabet and 1637 MUST NOT contain any padding characters ("="). 1639 { 1640 "type": "http-01", 1641 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA", 1642 } 1644 A client responds to this challenge by constructing a key 1645 authorization from the "token" value provided in the challenge and 1646 the client's account key. The client then provisions the key 1647 authorization as a resource on the HTTP server for the domain in 1648 question. 1650 The path at which the resource is provisioned is comprised of the 1651 fixed prefix ".well-known/acme-challenge/", followed by the "token" 1652 value in the challenge. The value of the resource MUST be the ASCII 1653 representation of the key authorization. 1655 .well-known/acme-challenge/evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA 1657 The client's response to this challenge indicates its agreement to 1658 this challenge by sending the server the key authorization covering 1659 the challenge's token and the client's account key. In addition, the 1660 client MAY advise the server at which IP the challenge is 1661 provisioned. 1663 keyAuthorization (required, string): The key authorization for this 1664 challenge. This value MUST match the token from the challenge and 1665 the client's account key. 1667 address (optional, string): An IPv4 or IPv6 address, in dotted 1668 decimal form or [RFC4291] form, respectively. If given, this 1669 address MUST be included in the set of IP addresses to which the 1670 domain name resolves when the server attempts validation. If 1671 given, the server SHOULD connect to that specific IP address 1672 instead of arbitrarily choosing an IP from the set of A and AAAA 1673 records to which the domain name resolves. 1675 { 1676 "keyAuthorization": "evaGxfADs...62jcerQ" 1677 } 1678 /* Signed as JWS */ 1680 On receiving a response, the server MUST verify that the key 1681 authorization in the response matches the "token" value in the 1682 challenge and the client's account key. If they do not match, then 1683 the server MUST return an HTTP error in response to the POST request 1684 in which the client sent the challenge. 1686 Given a challenge/response pair, the server verifies the client's 1687 control of the domain by verifying that the resource was provisioned 1688 as expected. 1690 1. Form a URI by populating the URI template [RFC6570] 1691 "http://{domain}/.well-known/acme-challenge/{token}", where: 1693 * the domain field is set to the domain name being verified; and 1695 * the token field is set to the token in the challenge. 1697 2. Verify that the resulting URI is well-formed. 1699 3. If the client has supplied an address to use, verify that the 1700 address is included in the A or AAAA records to which the domain 1701 name resolves. If the address is not included in the result, the 1702 validation fails. 1704 4. Dereference the URI using an HTTP GET request. If an address was 1705 supplied by the client, use that address to establish the HTTP 1706 connection. 1708 5. Verify that the body of the response is well-formed key 1709 authorization. The server SHOULD ignore whitespace characters at 1710 the end of the body. 1712 6. Verify that key authorization provided by the server matches the 1713 token for this challenge and the client's account key. 1715 If all of the above verifications succeed, then the validation is 1716 successful. If the request fails, or the body does not pass these 1717 checks, then it has failed. 1719 7.3. TLS with Server Name Indication (TLS SNI) 1721 The TLS with Server Name Indication (TLS SNI) validation method 1722 proves control over a domain name by requiring the client to 1723 configure a TLS server referenced by an A/AAAA record under the 1724 domain name to respond to specific connection attempts utilizing the 1725 Server Name Indication extension [RFC6066]. The server verifies the 1726 client's challenge by accessing the reconfigured server and verifying 1727 a particular challenge certificate is presented. 1729 type (required, string): The string "tls-sni-02" 1731 token (required, string): A random value that uniquely identifies 1732 the challenge. This value MUST have at least 128 bits of entropy, 1733 in order to prevent an attacker from guessing it. It MUST NOT 1734 contain any characters outside the URL-safe Base64 alphabet and 1735 MUST NOT contain any padding characters ("="). 1737 { 1738 "type": "tls-sni-02", 1739 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA" 1740 } 1742 A client responds to this challenge by constructing a self-signed 1743 certificate which the client MUST provision at the domain name 1744 concerned in order to pass the challenge. 1746 The certificate may be constructed arbitrarily, except that each 1747 certificate MUST have exactly two subjectAlternativeNames, SAN A and 1748 SAN B. Both MUST be dNSNames. 1750 SAN A MUST be constructed as follows: compute the SHA-256 digest of 1751 the UTF-8-encoded challenge token and encode it in lowercase 1752 hexadecimal form. The dNSName is "x.y.token.acme.invalid", where x 1753 is the first half of the hexadecimal representation and y is the 1754 second half. 1756 SAN B MUST be constructed as follows: compute the SHA-256 digest of 1757 the UTF-8 encoded key authorization and encode it in lowercase 1758 hexadecimal form. The dNSName is "x.y.ka.acme.invalid" where x is 1759 the first half of the hexadecimal representation and y is the second 1760 half. 1762 The client MUST ensure that the certificate is served to TLS 1763 connections specifying a Server Name Indication (SNI) value of SAN A. 1765 The response to the TLS-SNI challenge simply acknowledges that the 1766 client is ready to fulfill this challenge. 1768 keyAuthorization (required, string): The key authorization for this 1769 challenge. This value MUST match the token from the challenge and 1770 the client's account key. 1772 { 1773 "keyAuthorization": "evaGxfADs...62jcerQ", 1774 } 1775 /* Signed as JWS */ 1777 On receiving a response, the server MUST verify that the key 1778 authorization in the response matches the "token" value in the 1779 challenge and the client's account key. If they do not match, then 1780 the server MUST return an HTTP error in response to the POST request 1781 in which the client sent the challenge. 1783 Given a challenge/response pair, the ACME server verifies the 1784 client's control of the domain by verifying that the TLS server was 1785 configured appropriately, using these steps: 1787 1. Compute SAN A and SAN B in the same way as the client. 1789 2. Open a TLS connection to the domain name being validated on the 1790 requested port, presenting SAN A in the SNI field. In the 1791 ClientHello initiating the TLS handshake, the server MUST include 1792 a server_name extension (i.e., SNI) containing SAN A. The server 1793 SHOULD ensure that it does not reveal SAN B in any way when 1794 making the TLS connection, such that the presentation of SAN B in 1795 the returned certificate proves association with the client. 1797 3. Verify that the certificate contains a subjectAltName extension 1798 containing dNSName entries of SAN A and SAN B and no other 1799 entries. The comparison MUST be insensitive to case and ordering 1800 of names. 1802 It is RECOMMENDED that the ACME server validation TLS connections 1803 from multiple vantage points to reduce the risk of DNS hijacking 1804 attacks. 1806 If all of the above verifications succeed, then the validation is 1807 successful. Otherwise, the validation fails. 1809 7.4. DNS 1811 When the identifier being validated is a domain name, the client can 1812 prove control of that domain by provisioning a resource record under 1813 it. The DNS challenge requires the client to provision a TXT record 1814 containing a designated value under a specific validation domain 1815 name. 1817 type (required, string): The string "dns-01" 1819 token (required, string): A random value that uniquely identifies 1820 the challenge. This value MUST have at least 128 bits of entropy, 1821 in order to prevent an attacker from guessing it. It MUST NOT 1822 contain any characters outside the URL-safe Base64 alphabet and 1823 MUST NOT contain any padding characters ("="). 1825 { 1826 "type": "dns-01", 1827 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA" 1828 } 1830 A client responds to this challenge by constructing a key 1831 authorization from the "token" value provided in the challenge and 1832 the client's account key. The client then computes the SHA-256 1833 digest of the key authorization. 1835 The record provisioned to the DNS is the base64url encoding of this 1836 digest. The client constructs the validation domain name by 1837 prepending the label "_acme-challenge" to the domain name being 1838 validated, then provisions a TXT record with the digest value under 1839 that name. For example, if the domain name being validated is 1840 "example.com", then the client would provision the following DNS 1841 record: 1843 _acme-challenge.example.com. 300 IN TXT "gfj9Xq...Rg85nM" 1845 The response to the DNS challenge provides the computed key 1846 authorization to acknowledge that the client is ready to fulfill this 1847 challenge. 1849 keyAuthorization (required, string): The key authorization for this 1850 challenge. This value MUST match the token from the challenge and 1851 the client's account key. 1853 { 1854 "keyAuthorization": "evaGxfADs...62jcerQ", 1855 } 1856 /* Signed as JWS */ 1858 On receiving a response, the server MUST verify that the key 1859 authorization in the response matches the "token" value in the 1860 challenge and the client's account key. If they do not match, then 1861 the server MUST return an HTTP error in response to the POST request 1862 in which the client sent the challenge. 1864 To validate a DNS challenge, the server performs the following steps: 1866 1. Compute the SHA-256 digest of the key authorization 1868 2. Query for TXT records under the validation domain name 1870 3. Verify that the contents of one of the TXT records matches the 1871 digest value 1873 If all of the above verifications succeed, then the validation is 1874 successful. If no DNS record is found, or DNS record and response 1875 payload do not pass these checks, then the validation fails. 1877 8. IANA Considerations 1879 [[ Editor's Note: Should we create a registry for tokens that go into 1880 the various JSON objects used by this protocol, i.e., the field names 1881 in the JSON objects? ]] 1883 9. Well-Known URI for the HTTP Challenge 1885 The "Well-Known URIs" registry should be updated with the following 1886 additional value (using the template from [RFC5785]): 1888 URI suffix: acme-challenge 1890 Change controller: IETF 1892 Specification document(s): This document, Section Section 7.2 1894 Related information: N/A 1896 9.1. Replay-Nonce HTTP Header 1898 The "Message Headers" registry should be updated with the following 1899 additional value: 1901 | Header Field Name | Protocol | Status | Reference | 1902 +:------------+:------+:------+:-----------+ | Replay-Nonce | http | 1903 standard | Section 5.4.1 | 1905 9.2. "nonce" JWS Header Parameter 1907 The "JSON Web Signature and Encryption Header Parameters" registry 1908 should be updated with the following additional value: 1910 o Header Parameter Name: "nonce" 1912 o Header Parameter Description: Nonce 1913 o Header Parameter Usage Location(s): JWE, JWS 1915 o Change Controller: IESG 1917 o Specification Document(s): Section 5.4.2 of RFC XXXX 1919 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 1920 to this document ]] 1922 9.3. URN Sub-namespace for ACME (urn:ietf:params:acme) 1924 The "IETF URN Sub-namespace for Registered Protocol Parameter 1925 Identifiers" registry should be updated with the following additional 1926 value, following the template in [RFC3553]: 1928 Registry name: acme 1930 Specification: RFC XXXX 1932 Repository: URL-TBD 1934 Index value: No transformation needed. The 1936 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 1937 to this document, and replace URL-TBD with the URL assigned by IANA 1938 for registries of ACME parameters. ]] 1940 9.4. New Registries 1942 This document requests that IANA create three new registries: 1944 1. ACME Error Codes 1946 2. ACME Identifier Types 1948 3. ACME Challenge Types 1950 All of these registries should be administered under a Specification 1951 Required policy [RFC5226]. 1953 9.4.1. Error Codes 1955 This registry lists values that are used within URN values that are 1956 provided in the "type" field of problem documents in ACME. 1958 Template: 1960 o Code: The label to be included in the URN for this error, 1961 following "urn:ietf:params:acme:" 1963 o Description: A human-readable description of the error 1965 o Reference: Where the error is defined 1967 Initial contents: The codes and descriptions in the table in 1968 Section 5.5 above, with the Reference field set to point to this 1969 specification. 1971 9.4.2. Identifier Types 1973 This registry lists the types of identifiers that ACME clients may 1974 request authorization to issue in certificates. 1976 Template: 1978 o Label: The value to be put in the "type" field of the identifier 1979 object 1981 o Reference: Where the identifier type is defined 1983 Initial contents: 1985 +-------+-----------+ 1986 | Label | Reference | 1987 +-------+-----------+ 1988 | dns | RFC XXXX | 1989 +-------+-----------+ 1991 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 1992 to this document ]] 1994 9.4.3. Challenge Types 1996 This registry lists the ways that ACME servers can offer to validate 1997 control of an identifier. The "Identifier Type" field in template 1998 MUST be contained in the Label column of the ACME Identifier Types 1999 registry. 2001 Template: 2003 o Label: The value to be put in the "type" field of challenge 2004 objects using this validation mechanism 2006 o Identifier Type: The type of identifier that this mechanism 2007 applies to 2009 o Reference: Where the challenge type is defined 2011 Initial Contents 2013 +---------+-----------------+-----------+ 2014 | Label | Identifier Type | Reference | 2015 +---------+-----------------+-----------+ 2016 | http | dns | RFC XXXX | 2017 | | | | 2018 | tls-sni | dns | RFC XXXX | 2019 | | | | 2020 | dns | dns | RFC XXXX | 2021 +---------+-----------------+-----------+ 2023 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2024 to this document ]] 2026 10. Security Considerations 2028 ACME is a protocol for managing certificates that attest to 2029 identifier/key bindings. Thus the foremost security goal of ACME is 2030 to ensure the integrity of this process, i.e., to ensure that the 2031 bindings attested by certificates are correct, and that only 2032 authorized entities can manage certificates. ACME identifies clients 2033 by their account keys, so this overall goal breaks down into two more 2034 precise goals: 2036 1. Only an entity that controls an identifier can get an account key 2037 authorized for that identifier 2039 2. Once authorized, an account key's authorizations cannot be 2040 improperly transferred to another account key 2042 In this section, we discuss the threat model that underlies ACME and 2043 the ways that ACME achieves these security goals within that threat 2044 model. We also discuss the denial-of-service risks that ACME servers 2045 face, and a few other miscellaneous considerations. 2047 10.1. Threat model 2049 As a service on the Internet, ACME broadly exists within the Internet 2050 threat model [RFC3552]. In analyzing ACME, it is useful to think of 2051 an ACME server interacting with other Internet hosts along three 2052 "channels": 2054 o An ACME channel, over which the ACME HTTPS requests are exchanged 2055 o A validation channel, over which the ACME server performs 2056 additional requests to validate a client's control of an 2057 identifier 2059 o A contact channel, over which the ACME server sends messages to 2060 the registered contacts for ACME clients 2062 +------------+ 2063 | ACME | ACME Channel 2064 | Client |--------------------+ 2065 +------------+ | 2066 ^ V 2067 | Contact Channel +------------+ 2068 +--------------------| ACME | 2069 | Server | 2070 +------------+ 2071 +------------+ | 2072 | Validation |<-------------------+ 2073 | Server | Validation Channel 2074 +------------+ 2076 In practice, the risks to these channels are not entirely separate, 2077 but they are different in most cases. Each of the three channels, 2078 for example, uses a different communications pattern: the ACME 2079 channel will comprise inbound HTTPS connections to the ACME server, 2080 the validation channel outbound HTTP or DNS requests, and the contact 2081 channel will use channels such as email and PSTN. 2083 Broadly speaking, ACME aims to be secure against active and passive 2084 attackers on any individual channel. Some vulnerabilities arise 2085 (noted below), when an attacker can exploit both the ACME channel and 2086 one of the others. 2088 On the ACME channel, in addition to network-layer attackers, we also 2089 need to account for application-layer man in the middle attacks, and 2090 for abusive use of the protocol itself. Protection against 2091 application-layer MitM addresses potential attackers such as Content 2092 Distribution Networks (CDNs) and middleboxes with a TLS MitM 2093 function. Preventing abusive use of ACME means ensuring that an 2094 attacker with access to the validation or contact channels can't 2095 obtain illegitimate authorization by acting as an ACME client 2096 (legitimately, in terms of the protocol). 2098 10.2. Integrity of Authorizations 2100 ACME allows anyone to request challenges for an identifier by 2101 registering an account key and sending a new-authorization request 2102 under that account key. The integrity of the authorization process 2103 thus depends on the identifier validation challenges to ensure that 2104 the challenge can only be completed by someone who both (1) holds the 2105 private key of the account key pair, and (2) controls the identifier 2106 in question. 2108 Validation responses need to be bound to an account key pair in order 2109 to avoid situations where an ACME MitM can switch out a legitimate 2110 domain holder's account key for one of his choosing, e.g.: 2112 o Legitimate domain holder registers account key pair A 2114 o MitM registers account key pair B 2116 o Legitimate domain holder sends a new-authorization request signed 2117 under account key A 2119 o MitM suppresses the legitimate request, but sends the same request 2120 signed under account key B 2122 o ACME server issues challenges and MitM forwards them to the 2123 legitimate domain holder 2125 o Legitimate domain holder provisions the validation response 2127 o ACME server performs validation query and sees the response 2128 provisioned by the legitimate domain holder 2130 o Because the challenges were issued in response to a message signed 2131 account key B, the ACME server grants authorization to account key 2132 B (the MitM) instead of account key A (the legitimate domain 2133 holder) 2135 All of the challenges above that require an out-of-band query by the 2136 server have a binding to the account private key, such that only the 2137 account private key holder can successfully respond to the validation 2138 query: 2140 o HTTP: The value provided in the validation request is signed by 2141 the account private key. 2143 o TLS SNI: The validation TLS request uses the account key pair as 2144 the server's key pair. 2146 o DNS: The MAC covers the account key, and the MAC key is derived 2147 from an ECDH public key signed with the account private key. 2149 The association of challenges to identifiers is typically done by 2150 requiring the client to perform some action that only someone who 2151 effectively controls the identifier can perform. For the challenges 2152 in this document, the actions are: 2154 o HTTP: Provision files under .well-known on a web server for the 2155 domain 2157 o TLS SNI: Configure a TLS server for the domain 2159 o DNS: Provision DNS resource records for the domain 2161 There are several ways that these assumptions can be violated, both 2162 by misconfiguration and by attack. For example, on a web server that 2163 allows non-administrative users to write to .well-known, any user can 2164 claim to own the server's hostname by responding to an HTTP 2165 challenge, and likewise for TLS configuration and TLS SNI. 2167 The use of hosting providers is a particular risk for ACME 2168 validation. If the owner of the domain has outsourced operation of 2169 DNS or web services to a hosting provider, there is nothing that can 2170 be done against tampering by the hosting provider. As far as the 2171 outside world is concerned, the zone or web site provided by the 2172 hosting provider is the real thing. 2174 More limited forms of delegation can also lead to an unintended party 2175 gaining the ability to successfully complete a validation 2176 transaction. For example, suppose an ACME server follows HTTP 2177 redirects in HTTP validation and a web site operator provisions a 2178 catch-all redirect rule that redirects requests for unknown resources 2179 to different domain. Then the target of the redirect could use that 2180 to get a certificate through HTTP validation, since the validation 2181 path will not be known to the primary server. 2183 The DNS is a common point of vulnerability for all of these 2184 challenges. An entity that can provision false DNS records for a 2185 domain can attack the DNS challenge directly, and can provision false 2186 A/AAAA records to direct the ACME server to send its TLS SNI or HTTP 2187 validation query to a server of the attacker's choosing. There are a 2188 few different mitigations that ACME servers can apply: 2190 o Always querying the DNS using a DNSSEC-validating resolver 2191 (enhancing security for zones that are DNSSEC-enabled) 2193 o Querying the DNS from multiple vantage points to address local 2194 attackers 2196 o Applying mitigations against DNS off-path attackers, e.g., adding 2197 entropy to requests [I-D.vixie-dnsext-dns0x20] or only using TCP 2199 Given these considerations, the ACME validation process makes it 2200 impossible for any attacker on the ACME channel, or a passive 2201 attacker on the validation channel to hijack the authorization 2202 process to authorize a key of the attacker's choice. 2204 An attacker that can only see the ACME channel would need to convince 2205 the validation server to provide a response that would authorize the 2206 attacker's account key, but this is prevented by binding the 2207 validation response to the account key used to request challenges. A 2208 passive attacker on the validation channel can observe the correct 2209 validation response and even replay it, but that response can only be 2210 used with the account key for which it was generated. 2212 An active attacker on the validation channel can subvert the ACME 2213 process, by performing normal ACME transactions and providing a 2214 validation response for his own account key. The risks due to 2215 hosting providers noted above are a particular case. For identifiers 2216 where the server already has some public key associated with the 2217 domain this attack can be prevented by requiring the client to prove 2218 control of the corresponding private key. 2220 10.3. Denial-of-Service Considerations 2222 As a protocol run over HTTPS, standard considerations for TCP-based 2223 and HTTP-based DoS mitigation also apply to ACME. 2225 At the application layer, ACME requires the server to perform a few 2226 potentially expensive operations. Identifier validation transactions 2227 require the ACME server to make outbound connections to potentially 2228 attacker-controlled servers, and certificate issuance can require 2229 interactions with cryptographic hardware. 2231 In addition, an attacker can also cause the ACME server to send 2232 validation requests to a domain of its choosing by submitting 2233 authorization requests for the victim domain. 2235 All of these attacks can be mitigated by the application of 2236 appropriate rate limits. Issues closer to the front end, like POST 2237 body validation, can be addressed using HTTP request limiting. For 2238 validation and certificate requests, there are other identifiers on 2239 which rate limits can be keyed. For example, the server might limit 2240 the rate at which any individual account key can issue certificates, 2241 or the rate at which validation can be requested within a given 2242 subtree of the DNS. 2244 10.4. CA Policy Considerations 2246 The controls on issuance enabled by ACME are focused on validating 2247 that a certificate applicant controls the identifier he claims. 2248 Before issuing a certificate, however, there are many other checks 2249 that a CA might need to perform, for example: 2251 o Has the client agreed to a subscriber agreement? 2253 o Is the claimed identifier syntactically valid? 2255 o For domain names: 2257 * If the leftmost label is a '*', then have the appropriate 2258 checks been applied? 2260 * Is the name on the Public Suffix List? 2262 * Is the name a high-value name? 2264 * Is the name a known phishing domain? 2266 o Is the key in the CSR sufficiently strong? 2268 o Is the CSR signed with an acceptable algorithm? 2270 CAs that use ACME to automate issuance will need to ensure that their 2271 servers perform all necessary checks before issuing. 2273 11. Operational Considerations 2275 There are certain factors that arise in operational reality that 2276 operators of ACME-based CAs will need to keep in mind when 2277 configuring their services. For example: 2279 o It is advisable to perform DNS queries via TCP to mitigate DNS 2280 forgery attacks over UDP 2282 [[ TODO: Other operational considerations ]] 2284 11.1. Default Virtual Hosts 2286 In many cases, TLS-based services are deployed on hosted platforms 2287 that use the Server Name Indication (SNI) TLS extension to 2288 distinguish between different hosted services or "virtual hosts". 2289 When a client initiates a TLS connection with an SNI value indicating 2290 a provisioned host, the hosting platform routes the connection to 2291 that host. 2293 When a connection come in with an unknown SNI value, one might expect 2294 the hosting platform to terminate the TLS connection. However, some 2295 hosting platforms will choose a virtual host to be the "default", and 2296 route connections with unknown SNI values to that host. 2298 In such cases, the owner of the default virtual host can complete a 2299 TLS-based challenge (e.g., "tls-sni-02") for any domain with an A 2300 record that points to the hosting platform. This could result in 2301 mis-issuance in cases where there are multiple hosts with different 2302 owners resident on the hosting platform. 2304 A CA that accepts TLS-based proof of domain control should attempt to 2305 check whether a domain is hosted on a domain with a default virtual 2306 host before allowing an authorization request for this host to use a 2307 TLS-based challenge. A default virtual host can be detected by 2308 initiating TLS connections to the host with random SNI values within 2309 the namespace used for the TLS-based challenge (the "acme.invalid" 2310 namespace for "tls-sni-02"). 2312 11.2. Use of DNSSEC Resolvers 2314 An ACME-based CA will often need to make DNS queries, e.g., to 2315 validate control of DNS names. Because the security of such 2316 validations ultimately depends on the authenticity of DNS data, every 2317 possible precaution should be taken to secure DNS queries done by the 2318 CA. It is therefore RECOMMENDED that ACME-based CAs make all DNS 2319 queries via DNSSEC-validating stub or recursive resolvers. This 2320 provides additional protection to domains which choose to make use of 2321 DNSSEC. 2323 An ACME-based CA must use only a resolver if it trusts the resolver 2324 and every component of the network route by which it is accessed. It 2325 is therefore RECOMMENDED that ACME-based CAs operate their own 2326 DNSSEC-validating resolvers within their trusted network and use 2327 these resolvers both for both CAA record lookups and all record 2328 lookups in furtherance of a challenge scheme (A, AAAA, TXT, etc.). 2330 12. Acknowledgements 2332 In addition to the editors listed on the front page, this document 2333 has benefited from contributions from a broad set of contributors, 2334 all the way back to its inception. 2336 o Peter Eckersley, EFF 2338 o Eric Rescorla, Mozilla 2340 o Seth Schoen, EFF 2341 o Alex Halderman, University of Michigan 2343 o Martin Thomson, Mozilla 2345 o Jakub Warmuz, University of Oxford 2347 This document draws on many concepts established by Eric Rescorla's 2348 "Automated Certificate Issuance Protocol" draft. Martin Thomson 2349 provided helpful guidance in the use of HTTP. 2351 13. References 2353 13.1. Normative References 2355 [I-D.ietf-appsawg-http-problem] 2356 mnot, m. and E. Wilde, "Problem Details for HTTP APIs", 2357 draft-ietf-appsawg-http-problem-03 (work in progress), 2358 January 2016. 2360 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2361 Requirement Levels", BCP 14, RFC 2119, 2362 DOI 10.17487/RFC2119, March 1997, 2363 . 2365 [RFC2314] Kaliski, B., "PKCS #10: Certification Request Syntax 2366 Version 1.5", RFC 2314, DOI 10.17487/RFC2314, March 1998, 2367 . 2369 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 2370 DOI 10.17487/RFC2818, May 2000, 2371 . 2373 [RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object 2374 Classes and Attribute Types Version 2.0", RFC 2985, 2375 DOI 10.17487/RFC2985, November 2000, 2376 . 2378 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 2379 Request Syntax Specification Version 1.7", RFC 2986, 2380 DOI 10.17487/RFC2986, November 2000, 2381 . 2383 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 2384 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 2385 . 2387 [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An 2388 IETF URN Sub-namespace for Registered Protocol 2389 Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June 2390 2003, . 2392 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 2393 Architecture", RFC 4291, DOI 10.17487/RFC4291, February 2394 2006, . 2396 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2397 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 2398 . 2400 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2401 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2402 DOI 10.17487/RFC5226, May 2008, 2403 . 2405 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2406 (TLS) Protocol Version 1.2", RFC 5246, 2407 DOI 10.17487/RFC5246, August 2008, 2408 . 2410 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2411 Housley, R., and W. Polk, "Internet X.509 Public Key 2412 Infrastructure Certificate and Certificate Revocation List 2413 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2414 . 2416 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 2417 Uniform Resource Identifiers (URIs)", RFC 5785, 2418 DOI 10.17487/RFC5785, April 2010, 2419 . 2421 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 2422 DOI 10.17487/RFC5988, October 2010, 2423 . 2425 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 2426 Extensions: Extension Definitions", RFC 6066, 2427 DOI 10.17487/RFC6066, January 2011, 2428 . 2430 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 2431 and D. Orchard, "URI Template", RFC 6570, 2432 DOI 10.17487/RFC6570, March 2012, 2433 . 2435 [RFC6844] Hallam-Baker, P. and R. Stradling, "DNS Certification 2436 Authority Authorization (CAA) Resource Record", RFC 6844, 2437 DOI 10.17487/RFC6844, January 2013, 2438 . 2440 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 2441 Transparency", RFC 6962, DOI 10.17487/RFC6962, June 2013, 2442 . 2444 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2445 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2446 2014, . 2448 [RFC7469] Evans, C., Palmer, C., and R. Sleevi, "Public Key Pinning 2449 Extension for HTTP", RFC 7469, DOI 10.17487/RFC7469, April 2450 2015, . 2452 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2453 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2454 2015, . 2456 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 2457 DOI 10.17487/RFC7517, May 2015, 2458 . 2460 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 2461 DOI 10.17487/RFC7518, May 2015, 2462 . 2464 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 2465 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 2466 2015, . 2468 13.2. Informative References 2470 [I-D.vixie-dnsext-dns0x20] 2471 Vixie, P. and D. Dagon, "Use of Bit 0x20 in DNS Labels to 2472 Improve Transaction Identity", draft-vixie-dnsext- 2473 dns0x20-00 (work in progress), March 2008. 2475 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 2476 Text on Security Considerations", BCP 72, RFC 3552, 2477 DOI 10.17487/RFC3552, July 2003, 2478 . 2480 [W3C.CR-cors-20130129] 2481 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 2482 Web Consortium CR CR-cors-20130129, January 2013, 2483 . 2485 [W3C.WD-capability-urls-20140218] 2486 Tennison, J., "Good Practices for Capability URLs", World 2487 Wide Web Consortium WD WD-capability-urls-20140218, 2488 February 2014, 2489 . 2491 Authors' Addresses 2493 Richard Barnes 2494 Mozilla 2496 Email: rlb@ipv.sx 2498 Jacob Hoffman-Andrews 2499 EFF 2501 Email: jsha@eff.org 2503 James Kasten 2504 University of Michigan 2506 Email: jdkasten@umich.edu