idnits 2.17.1 draft-barnes-acme-04.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 779 has weird spacing: '...ew-cert rev...' -- The exact meaning of the all-uppercase expression 'NOT REQUIRED' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. -- The document date (July 21, 2015) is 3202 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 647, but not defined == Missing Reference: '0-9' is mentioned on line 647, but not defined -- Looks like a reference, but probably isn't: '0' on line 1274 -- Looks like a reference, but probably isn't: '2' on line 1275 -- Looks like a reference, but probably isn't: '1' on line 1275 == Unused Reference: 'RFC3986' is defined on line 2441, but no explicit reference was found in the text == Unused Reference: 'RFC4514' is defined on line 2445, but no explicit reference was found in the text == Unused Reference: 'RFC4648' is defined on line 2449, but no explicit reference was found in the text == Unused Reference: 'RFC5226' is defined on line 2452, but no explicit reference was found in the text == Unused Reference: 'RFC5280' is defined on line 2459, but no explicit reference was found in the text == Unused Reference: 'RFC7518' is defined on line 2487, but no explicit reference was found in the text == Outdated reference: A later version (-03) exists of draft-ietf-appsawg-http-problem-00 ** Obsolete normative reference: RFC 2314 (Obsoleted by RFC 2986) ** 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) ** Downref: Normative reference to an Informational RFC: RFC 5753 ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'SEC1' -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 8 errors (**), 0 flaws (~~), 11 warnings (==), 8 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: January 22, 2016 EFF 6 J. Kasten 7 University of Michigan 8 July 21, 2015 10 Automatic Certificate Management Environment (ACME) 11 draft-barnes-acme-04 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 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on January 22, 2016. 44 Copyright Notice 46 Copyright (c) 2015 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Deployment Model and Operator Experience . . . . . . . . . . 4 63 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 4. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 6 65 5. Protocol Elements . . . . . . . . . . . . . . . . . . . . . . 9 66 5.1. HTTPS Requests . . . . . . . . . . . . . . . . . . . . . 9 67 5.2. Registration Objects . . . . . . . . . . . . . . . . . . 10 68 5.3. Authorization Objects . . . . . . . . . . . . . . . . . . 11 69 5.4. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 13 70 5.5. Replay protection . . . . . . . . . . . . . . . . . . . . 14 71 5.5.1. Replay-Nonce . . . . . . . . . . . . . . . . . . . . 14 72 5.5.2. "nonce" (Nonce) JWS header parameter . . . . . . . . 15 73 5.6. Key Agreement . . . . . . . . . . . . . . . . . . . . . . 15 74 6. Certificate Management . . . . . . . . . . . . . . . . . . . 16 75 6.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 16 76 6.2. Directory . . . . . . . . . . . . . . . . . . . . . . . . 18 77 6.3. Registration . . . . . . . . . . . . . . . . . . . . . . 18 78 6.3.1. Recovery Keys . . . . . . . . . . . . . . . . . . . . 20 79 6.4. Account Recovery . . . . . . . . . . . . . . . . . . . . 22 80 6.4.1. MAC-Based Recovery . . . . . . . . . . . . . . . . . 23 81 6.4.2. Contact-Based Recovery . . . . . . . . . . . . . . . 25 82 6.5. Identifier Authorization . . . . . . . . . . . . . . . . 27 83 6.6. Certificate Issuance . . . . . . . . . . . . . . . . . . 31 84 6.7. Certificate Revocation . . . . . . . . . . . . . . . . . 34 85 7. Identifier Validation Challenges . . . . . . . . . . . . . . 35 86 7.1. Simple HTTP . . . . . . . . . . . . . . . . . . . . . . . 37 87 7.2. Domain Validation with Server Name Indication (DVSNI) . . 39 88 7.3. Proof of Possession of a Prior Key . . . . . . . . . . . 41 89 7.4. DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 90 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 91 9. Security Considerations . . . . . . . . . . . . . . . . . . . 46 92 9.1. Threat model . . . . . . . . . . . . . . . . . . . . . . 47 93 9.2. Integrity of Authorizations . . . . . . . . . . . . . . . 48 94 9.3. Preventing Authorization Hijacking . . . . . . . . . . . 50 95 9.4. Denial-of-Service Considerations . . . . . . . . . . . . 52 96 9.5. CA Policy Considerations . . . . . . . . . . . . . . . . 52 98 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 53 99 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 100 11.1. Normative References . . . . . . . . . . . . . . . . . . 53 101 11.2. Informative References . . . . . . . . . . . . . . . . . 55 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55 104 1. Introduction 106 Certificates in the Web PKI are most commonly used to authenticate 107 domain names. Thus, certificate authorities in the Web PKI are 108 trusted to verify that an applicant for a certificate legitimately 109 represents the domain name(s) in the certificate. 111 Existing Web PKI certificate authorities tend to run on a set of ad 112 hoc protocols for certificate issuance and identity verification. A 113 typical user experience is something like: 115 o Generate a PKCS#10 [RFC2314] Certificate Signing Request (CSR). 117 o Cut-and-paste the CSR into a CA web page. 119 o Prove ownership of the domain by one of the following methods: 121 * Put a CA-provided challenge at a specific place on the web 122 server. 124 * Put a CA-provided challenge at a DNS location corresponding to 125 the target domain. 127 * Receive CA challenge at a (hopefully) administrator-controlled 128 e-mail address corresponding to the domain and then respond to 129 it on the CA's web page. 131 o Download the issued certificate and install it on their Web 132 Server. 134 With the exception of the CSR itself and the certificates that are 135 issued, these are all completely ad hoc procedures and are 136 accomplished by getting the human user to follow interactive natural- 137 language instructions from the CA rather than by machine-implemented 138 published protocols. In many cases, the instructions are difficult 139 to follow and cause significant confusion. Informal usability tests 140 by the authors indicate that webmasters often need 1-3 hours to 141 obtain and install a certificate for a domain. Even in the best 142 case, the lack of published, standardized mechanisms presents an 143 obstacle to the wide deployment of HTTPS and other PKIX-dependent 144 systems because it inhibits mechanization of tasks related to 145 certificate issuance, deployment, and revocation. 147 This document describes an extensible framework for automating the 148 issuance and domain validation procedure, thereby allowing servers 149 and infrastructural software to obtain certificates without user 150 interaction. Use of this protocol should radically simplify the 151 deployment of HTTPS and the practicality of PKIX authentication for 152 other protocols based on TLS [RFC5246]. 154 2. Deployment Model and Operator Experience 156 The major guiding use case for ACME is obtaining certificates for Web 157 sites (HTTPS [RFC2818]). In that case, the server is intended to 158 speak for one or more domains, and the process of certificate 159 issuance is intended to verify that the server actually speaks for 160 the domain. 162 Different types of certificates reflect different kinds of CA 163 verification of information about the certificate subject. "Domain 164 Validation" (DV) certificates are by far the most common type. For 165 DV validation, the CA merely verifies that the requester has 166 effective control of the web server and/or DNS server for the domain, 167 but does not explicitly attempt to verify their real-world identity. 168 (This is as opposed to "Organization Validation" (OV) and "Extended 169 Validation" (EV) certificates, where the process is intended to also 170 verify the real-world identity of the requester.) 172 DV certificate validation commonly checks claims about properties 173 related to control of a domain name - properties that can be observed 174 by the issuing authority in an interactive process that can be 175 conducted purely online. That means that under typical 176 circumstances, all steps in the request, verification, and issuance 177 process can be represented and performed by Internet protocols with 178 no out-of-band human intervention. 180 When an operator deploys a current HTTPS server, it generally prompts 181 him to generate a self-signed certificate. When an operator deploys 182 an ACME-compatible web server, the experience would be something like 183 this: 185 o The ACME client prompts the operator for the intended domain 186 name(s) that the web server is to stand for. 188 o The ACME client presents the operator with a list of CAs from 189 which it could get a certificate. (This list will change over 190 time based on the capabilities of CAs and updates to ACME 191 configuration.) The ACME client might prompt the operator for 192 payment information at this point. 194 o The operator selects a CA. 196 o In the background, the ACME client contacts the CA and requests 197 that a certificate be issued for the intended domain name(s). 199 o Once the CA is satisfied, the certificate is issued and the ACME 200 client automatically downloads and installs it, potentially 201 notifying the operator via e-mail, SMS, etc. 203 o The ACME client periodically contacts the CA to get updated 204 certificates, stapled OCSP responses, or whatever else would be 205 required to keep the server functional and its credentials up-to- 206 date. 208 The overall idea is that it's nearly as easy to deploy with a CA- 209 issued certificate as a self-signed certificate, and that once the 210 operator has done so, the process is self-sustaining with minimal 211 manual intervention. Close integration of ACME with HTTPS servers, 212 for example, can allow the immediate and automated deployment of 213 certificates as they are issued, optionally sparing the human 214 administrator from additional configuration work. 216 3. Terminology 218 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 219 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 220 document are to be interpreted as described in RFC 2119 [RFC2119]. 222 The two main roles in ACME are "client" and "server". The ACME 223 client uses the protocol to request certificate management actions, 224 such as issuance or revocation. An ACME client therefore typically 225 runs on a web server, mail server, or some other server system which 226 requires valid TLS certificates. The ACME server runs at a 227 certificate authority, and responds to client requests, performing 228 the requested actions if the client is authorized. 230 For simplicity, in all HTTPS transactions used by ACME, the ACME 231 client is the HTTPS client and the ACME server is the HTTPS server. 233 In the discussion below, we will refer to three different types of 234 keys / key pairs: 236 Subject Public Key: A public key to be included in a certificate. 238 Account Key Pair: A key pair for which the ACME server considers the 239 holder of the private key authorized to manage certificates for a 240 given identifier. The same key pair may be authorized for 241 multiple identifiers. 243 Recovery Key: A MAC key that a client can use to demonstrate that it 244 participated in a prior registration transaction. 246 ACME messaging is based on HTTPS [RFC2818] and JSON [RFC7159]. Since 247 JSON is a text-based format, binary fields are Base64-encoded. For 248 Base64 encoding, we use the variant defined in [RFC7515]. The 249 important features of this encoding are (1) that it uses the URL-safe 250 character set, and (2) that "=" padding characters are stripped. 252 Some HTTPS bodies in ACME are authenticated and integrity-protected 253 by being encapsulated in a JSON Web Signature (JWS) object [RFC7515]. 254 ACME uses a profile of JWS, with the following restrictions: 256 o The JWS MUST use the Flattened JSON Serialization 258 o The JWS MUST be encoded using UTF-8 260 o The JWS Header or Protected Header MUST include "alg" and "jwk" 261 fields 263 o The JWS MUST NOT have the value "none" in its "alg" field 265 Additionally, JWS objects used in ACME MUST include the "nonce" 266 header parameter, defined below. 268 4. Protocol Overview 270 ACME allows a client to request certificate management actions using 271 a set of JSON messages carried over HTTPS. In some ways, ACME 272 functions much like a traditional CA, in which a user creates an 273 account, adds identifiers to that account (proving control of the 274 domains), and requests certificate issuance for those domains while 275 logged in to the account. 277 In ACME, the account is represented by an account key pair. The "add 278 a domain" function is accomplished by authorizing the key pair for a 279 given domain. Certificate issuance and revocation are authorized by 280 a signature with the key pair. 282 The first phase of ACME is for the client to register with the ACME 283 server. The client generates an asymmetric key pair and associates 284 this key pair with a set of contact information by signing the 285 contact information. The server acknowledges the registration by 286 replying with a registration object echoing the client's input. 288 Client Server 290 Contact Information 291 Signature -------> 293 <------- Registration 295 Before a client can issue certificates, it must establish an 296 authorization with the server for an account key pair to act for the 297 identifier(s) that it wishes to include in the certificate. To do 298 this, the client must demonstrate to the server both (1) that it 299 holds the private key of the account key pair, and (2) that it has 300 authority over the identifier being claimed. 302 Proof of possession of the account key is built into the ACME 303 protocol. All messages from the client to the server are signed by 304 the client, and the server verifies them using the public key of the 305 account key pair. 307 To verify that the client controls the identifier being claimed, the 308 server issues the client a set of challenges. Because there are many 309 different ways to validate possession of different types of 310 identifiers, the server will choose from an extensible set of 311 challenges that are appropriate for the identifier being claimed. 312 The client responds with a set of responses that tell the server 313 which challenges the client has completed. The server then validates 314 the challenges to check that the client has accomplished the 315 challenge. 317 For example, if the client requests a domain name, the server might 318 challenge the client to provision a record in the DNS under that 319 name, or to provision a file on a web server referenced by an A or 320 AAAA record under that name. The server would then query the DNS for 321 the record in question, or send an HTTP request for the file. If the 322 client provisioned the DNS or the web server as expected, then the 323 server considers the client authorized for the domain name. 325 Client Server 327 Identifier 328 Signature -------> 330 <------- Challenges 332 Responses 333 Signature -------> 335 <------- Updated Challenge 337 <~~~~~~~~Validation~~~~~~~~> 339 Poll -------> 341 <------- Authorization 343 Once the client has authorized an account key pair for an identifier, 344 it can use the key pair to authorize the issuance of certificates for 345 the identifier. To do this, the client sends a PKCS#10 Certificate 346 Signing Request (CSR) to the server (indicating the identifier(s) to 347 be included in the issued certificate) and a signature over the CSR 348 by the private key of the account key pair. 350 If the server agrees to issue the certificate, then it creates the 351 certificate and provides it in its response. The certificate is 352 assigned a URI, which the client can use to fetch updated versions of 353 the certificate. 355 Client Server 357 CSR 358 Signature --------> 360 <-------- Certificate 362 To revoke a certificate, the client simply sends a revocation 363 request, signed with an authorized key pair, and the server indicates 364 whether the request has succeeded. 366 Client Server 368 Revocation request 369 Signature --------> 371 <-------- Result 373 Note that while ACME is defined with enough flexibility to handle 374 different types of identifiers in principle, the primary use case 375 addressed by this document is the case where domain names are used as 376 identifiers. For example, all of the identifier validation 377 challenges described in Section 7 below address validation of domain 378 names. The use of ACME for other protocols will require further 379 specification, in order to describe how these identifiers are encoded 380 in the protocol, and what types of validation challenges the server 381 might require. 383 5. Protocol Elements 385 This section describes several components that are used by ACME, and 386 general rules that apply to ACME transactions. 388 5.1. HTTPS Requests 390 Each ACME function is accomplished by the client sending a sequence 391 of HTTPS requests to the server, carrying JSON messages. Use of 392 HTTPS is REQUIRED. Clients SHOULD support HTTP public key pinning 393 [RFC7469], and servers SHOULD emit pinning headers. Each subsection 394 of Section 6 below describes the message formats used by the 395 function, and the order in which messages are sent. 397 All ACME requests with a non-empty body MUST encapsulate the body in 398 a JWS object, signed using the account key pair. The server MUST 399 verify the JWS before processing the request. (For readability, 400 however, the examples below omit this encapsulation.) Encapsulating 401 request bodies in JWS provides a simple authentication of requests by 402 way of key continuity. 404 Note that this implies that GET requests are not authenticated. 405 Servers MUST NOT respond to GET requests for resources that might be 406 considered sensitive. 408 An ACME request carries a JSON dictionary that provides the details 409 of the client's request to the server. In order to avoid attacks 410 that might arise from sending a request object to a resource of the 411 wrong type, each request object MUST have a "resource" field that 412 indicates what type of resource the request is addressed to, as 413 defined in the below table: 415 +----------------------+------------------+ 416 | Resource type | "resource" value | 417 +----------------------+------------------+ 418 | New registration | new-reg | 419 | | | 420 | Recover registration | recover-reg | 421 | | | 422 | New authorization | new-authz | 423 | | | 424 | New certificate | new-cert | 425 | | | 426 | Revoke certificate | revoke-cert | 427 | | | 428 | Registration | reg | 429 | | | 430 | Authorization | authz | 431 | | | 432 | Challenge | challenge | 433 | | | 434 | Certificate | cert | 435 +----------------------+------------------+ 437 Other fields in ACME request bodies are described below. 439 ACME servers that are intended to be generally accessible need to use 440 Cross-Origin Resource Sharing (CORS) in order to be accessible from 441 browser-based clients [W3C.CR-cors-20130129]. Such servers SHOULD 442 set the Access-Control-Allow-Origin header field to the value "*". 444 5.2. Registration Objects 446 An ACME registration resource represents a set of metadata associated 447 to an account key pair. Registration resources have the following 448 structure: 450 key (required, dictionary): The public key of the account key pair, 451 encoded as a JSON Web Key object [RFC7517]. 453 contact (optional, array of string): An array of URIs that the 454 server can use to contact the client for issues related to this 455 authorization. For example, the server may wish to notify the 456 client about server-initiated revocation. 458 agreement (optional, string): A URI referring to a subscriber 459 agreement or terms of service provided by the server (see below). 460 Including this field indicates the client's agreement with the 461 referenced terms. 463 authorizations (optional, string): A URI from which a list of 464 authorizations granted to this account can be fetched via a GET 465 request. The result of the GET request MUST be a JSON object 466 whose "authorizations" field is an array of strings, where each 467 string is the URI of an authorization belonging to this 468 registration. The server SHOULD include pending authorizations, 469 and SHOULD NOT include authorizations that are invalid or expired. 471 certificates (optional, string): A URI from which a list of 472 certificates issued for this account can be fetched via a GET 473 request. The result of the GET request MUST be a JSON object 474 whose "certificates" field is an array of strings, where each 475 string is the URI of a certificate. The server SHOULD NOT include 476 expired certificates. 478 { 479 "resource": "new-reg", 480 "contact": [ 481 "mailto:cert-admin@example.com", 482 "tel:+12025551212" 483 ], 484 "agreement": "https://example.com/acme/terms", 485 "authorizations": "https://example.com/acme/reg/1/authz", 486 "certificates": "https://example.com/acme/reg/1/cert", 487 } 489 5.3. Authorization Objects 491 An ACME authorization object represents server's authorization for an 492 account to represent an identifier. In addition to the identifier, 493 an authorization includes several metadata fields, such as the status 494 of the authorization (e.g., "pending", "valid", or "revoked") and 495 which challenges were used to validate possession of the identifier. 497 The structure of an ACME authorization resource is as follows: 499 identifier (required, dictionary of string): The identifier that the 500 account is authorized to represent 502 type (required, string): The type of identifier. 504 value (required, string): The identifier itself. 506 status (optional, string): The status of this authorization. 507 Possible values are: "unknown", "pending", "processing", "valid", 508 "invalid" and "revoked". If this field is missing, then the 509 default value is "pending". 511 expires (optional, string): The date after which the server will 512 consider this authorization invalid, encoded in the format 513 specified in RFC 3339 [RFC3339]. 515 challenges (required, array): The challenges that the client needs 516 to fulfill in order to prove possession of the identifier (for 517 pending authorizations). For final authorizations, the challenges 518 that were used. Each array entry is a dictionary with parameters 519 required to validate the challenge, as specified in Section 7. 521 combinations (optional, array of arrays of integers): A collection 522 of sets of challenges, each of which would be sufficient to prove 523 possession of the identifier. Clients complete a set of 524 challenges that that covers at least one set in this array. 525 Challenges are identified by their indices in the challenges 526 array. If no "combinations" element is included in an 527 authorization object, the client completes all challenges. 529 The only type of identifier defined by this specification is a fully- 530 qualified domain name (type: "dns"). The value of the identifier 531 MUST be the ASCII representation of the domain name. Wildcard domain 532 names (with "*" as the first label) MUST NOT be included in 533 authorization requests. See Section 6.6 below for more information 534 about wildcard domains. 536 { 537 "status": "valid", 538 "expires": "2015-03-01", 540 "identifier": { 541 "type": "dns", 542 "value": "example.org" 543 }, 545 "challenges": [ 546 { 547 "type": "simpleHttp", 548 "status": "valid", 549 "validated": "2014-12-01T12:05Z", 550 "token": "IlirfxKKXAsHtmzK29Pj8A" 551 "path": "Hf5GrX4Q7EBax9hc2jJnfw" 552 } 553 ], 554 } 556 5.4. Errors 558 Errors can be reported in ACME both at the HTTP layer and within ACME 559 payloads. ACME servers can return responses with an HTTP error 560 response code (4XX or 5XX). For example: If the client submits a 561 request using a method not allowed in this document, then the server 562 MAY return status code 405 (Method Not Allowed). 564 When the server responds with an error status, it SHOULD provide 565 additional information using problem document 566 [I-D.ietf-appsawg-http-problem]. The "type" and "detail" fields MUST 567 be populated. To facilitate automatic response to errors, this 568 document defines the following standard tokens for use in the "type" 569 field (within the "urn:acme:" namespace): 571 +----------------+--------------------------------------------------+ 572 | Code | Semantic | 573 +----------------+--------------------------------------------------+ 574 | badCSR | The CSR is unacceptable (e.g., due to a short | 575 | | key) | 576 | | | 577 | badNonce | The client sent an unacceptable anti-replay | 578 | | nonce | 579 | | | 580 | connection | The server could not connect to the client for | 581 | | DV | 582 | | | 583 | dnssec | The server could not validate a DNSSEC signed | 584 | | domain | 585 | | | 586 | malformed | The request message was malformed | 587 | | | 588 | serverInternal | The server experienced an internal error | 589 | | | 590 | tls | The server experienced a TLS error during DV | 591 | | | 592 | unauthorized | The client lacks sufficient authorization | 593 | | | 594 | unknownHost | The server could not resolve a domain name | 595 +----------------+--------------------------------------------------+ 597 Authorization and challenge objects can also contain error 598 information to indicate why the server was unable to validate 599 authorization. 601 TODO: Flesh out errors and syntax for them 603 5.5. Replay protection 605 In order to protect ACME resources from any possible replay attacks, 606 ACME requests have a mandatory anti-replay mechanism. This mechanism 607 is based on the server maintaining a list of nonces that it has 608 issued to clients, and requiring any signed request from the client 609 to carry such a nonce. 611 An ACME server MUST include a Replay-Nonce header field in each 612 successful response it provides to a client, with contents as 613 specified below. In particular, the ACME server MUST provide a 614 Replay-Nonce header field in response to a HEAD request for any valid 615 resource. (This allows clients to easily obtain a fresh nonce.) It 616 MAY also provide nonces in error responses. 618 Every JWS sent by an ACME client MUST include, in its protected 619 header, the "nonce" header parameter, with contents as defined below. 620 As part of JWS verification, the ACME server MUST verify that the 621 value of the "nonce" header is a value that the server previously 622 provided in a Replay-Nonce header field. Once a nonce value has 623 appeared in an ACME request, the server MUST consider it invalid, in 624 the same way as a value it had never issued. 626 When a server rejects a request because its nonce value was 627 unacceptable (or not present), it SHOULD provide HTTP status code 400 628 (Bad Request), and indicate the ACME error code "urn:acme:badNonce". 630 The precise method used to generate and track nonces is up to the 631 server. For example, the server could generate a random 128-bit 632 value for each response, keep a list of issued nonces, and strike 633 nonces from this list as they are used. 635 5.5.1. Replay-Nonce 637 The "Replay-Nonce" header field includes a server-generated value 638 that the server can use to detect unauthorized replay in future 639 client requests. The server should generate the value provided in 640 Replay-Nonce in such a way that they are unique to each message, with 641 high probability. 643 The value of the Replay-Nonce field MUST be an octet string encoded 644 according to the base64url encoding described in Section 2 of 645 [RFC7515]. Clients MUST ignore invalid Replay-Nonce values. 647 base64url = [A-Z] / [a-z] / [0-9] / "-" / "_" 649 Replay-Nonce = *base64url 651 The Replay-Nonce header field SHOULD NOT be included in HTTP request 652 messages. 654 5.5.2. "nonce" (Nonce) JWS header parameter 656 The "nonce" header parameter provides a unique value that enables the 657 verifier of a JWS to recognize when replay has occurred. The "nonce" 658 header parameter MUST be carried in the protected header of the JWS. 660 The value of the "nonce" header parameter MUST be an octet string, 661 encoded according to the base64url encoding described in Section 2 of 662 [RFC7515]. If the value of a "nonce" header parameter is not valid 663 according to this encoding, then the verifier MUST reject the JWS as 664 malformed. 666 5.6. Key Agreement 668 Certain elements of the protocol will require the establishment of a 669 shared secret between the client and the server, in such a way that 670 an entity observing the ACME protocol cannot derive the secret. In 671 these cases, we use a simple ECDH key exchange, based on the system 672 used by CMS [RFC5753]: 674 o Inputs: 676 * Client-generated key pair 678 * Server-generated key pair 680 * Length of the shared secret to be derived 682 * Label 684 o Perform the ECDH primitive operation to obtain Z (Section 3.3.1 of 685 [SEC1]) 687 o Select a hash algorithm according to the curve being used: 689 * For "P-256", use SHA-256 691 * For "P-384", use SHA-384 693 * For "P-521", use SHA-512 695 o Derive the shared secret value using the KDF in Section 3.6.1 of 696 [SEC1] using Z and the selected hash algorithm, and with the UTF-8 697 encoding of the label as the SharedInfo value 699 In cases where the length of the derived secret is shorter than the 700 output length of the chosen hash algorithm, the KDF referenced above 701 reduces to a single hash invocation. The shared secret is equal to 702 the leftmost octets of the following: 704 H( Z || 00000001 || label ) 706 6. Certificate Management 708 In this section, we describe the certificate management functions 709 that ACME enables: 711 o Account Key Registration 713 o Account Recovery 715 o Account Key Authorization 717 o Certificate Issuance 719 o Certificate Renewal 721 o Certificate Revocation 723 6.1. Resources 725 ACME is structured as a REST application with a few types of 726 resources: 728 o Registration resources, representing information about an account 730 o Authorization resources, representing an account's authorization 731 to act for an identifier 733 o Challenge resources, representing a challenge to prove control of 734 an identifier 736 o Certificate resources, representing issued certificates 738 o A "directory" resource 740 o A "new-registration" resource 742 o A "new-authorization" resource 744 o A "new-certificate" resource 746 o A "revoke-certificate" resource 747 For the "new-X" resources above, the server MUST have exactly one 748 resource for each function. This resource may be addressed by 749 multiple URIs, but all must provide equivalent functionality. 751 In general, the intent is for authorization and certificate resources 752 to contain only public information, so that CAs may publish these 753 resources to document what certificates have been issued and how they 754 were authorized. Non-public information, such as contact 755 information, is stored in registration resources. 757 ACME uses different URIs for different management functions. Each 758 function is listed in a directory along with its corresponding URI, 759 so clients only need to be configured with the directory URI. 761 The "up" link relation is used with challenge resources to indicate 762 the authorization resource to which a challenge belongs. It is also 763 used from certificate resources to indicate a resource from which the 764 client may fetch a chain of CA certificates that could be used to 765 validate the certificate in the original resource. 767 The following diagram illustrates the relations between resources on 768 an ACME server. The solid lines indicate link relations, and the 769 dotted lines correspond to relationships expressed in other ways, 770 e.g., the Location header in a 201 (Created) response. 772 directory 773 . 774 . 775 .................................................... 776 . . . . 777 . . . . 778 V "next" V "next" V V 779 new-reg ---+----> new-authz ---+----> new-cert revoke-cert 780 . | . | . ^ 781 . | . | . | "revoke" 782 V | V | V | 783 reg* ----+ authz -----+ cert-----------+ 784 . ^ | 785 . | "up" | "up" 786 V | V 787 challenge cert-chain 789 The following table illustrates a typical sequence of requests 790 required to establish a new account with the server, prove control of 791 an identifier, issue a certificate, and fetch an updated certificate 792 some time after issuance. The "->" is a mnemonic for a Location 793 header pointing to a created resource. 795 +--------------------+----------------+--------------+ 796 | Action | Request | Response | 797 +--------------------+----------------+--------------+ 798 | Register | POST new-reg | 201 -> reg | 799 | | | | 800 | Request challenges | POST new-authz | 201 -> authz | 801 | | | | 802 | Answer challenges | POST challenge | 200 | 803 | | | | 804 | Poll for status | GET authz | 200 | 805 | | | | 806 | Request issuance | POST new-cert | 201 -> cert | 807 | | | | 808 | Check for new cert | GET cert | 200 | 809 +--------------------+----------------+--------------+ 811 The remainder of this section provides the details of how these 812 resources are structured and how the ACME protocol makes use of them. 814 6.2. Directory 816 In order to help clients configure themselves with the right URIs for 817 each ACME operation, ACME servers provide a directory object. This 818 should be the root URL with which clients are configured. It is a 819 JSON dictionary, whose keys are the "resource" values listed in 820 Section 5.1, and whose values are the URIs used to accomplish the 821 corresponding function. 823 Clients access the directory by sending a GET request to the 824 directory URI. 826 HTTP/1.1 200 OK 827 Content-Type: application/json 829 { 830 "new-reg": "https://example.com/acme/new-reg", 831 "recover-reg": "https://example.com/acme/recover-reg", 832 "new-authz": "https://example.com/acme/new-authz", 833 "new-cert": "https://example.com/acme/new-cert", 834 "revoke-cert": "https://example.com/acme/revoke-cert" 835 } 837 6.3. Registration 839 A client creates a new account with the server by sending a POST 840 request to the server's new-registration URI. The body of the 841 request is a stub registration object containing only the "contact" 842 field (along with the required "resource" field). 844 POST /acme/new-registration HTTP/1.1 845 Host: example.com 847 { 848 "resource": "new-reg", 849 "contact": [ 850 "mailto:cert-admin@example.com", 851 "tel:+12025551212" 852 ], 853 } 854 /* Signed as JWS */ 856 The server MUST ignore any values provided in the "key", 857 "authorizations", and "certificates" fields in registration bodies 858 sent by the client, as well as any other fields that it does not 859 recognize. If new fields are specified in the future, the 860 specification of those fields MUST describe whether they may be 861 provided by the client. 863 The server creates a registration object with the included contact 864 information. The "key" element of the registration is set to the 865 public key used to verify the JWS (i.e., the "jwk" element of the JWS 866 header). The server returns this registration object in a 201 867 (Created) response, with the registration URI in a Location header 868 field. The server MUST also indicate its new-authorization URI using 869 the "next" link relation. 871 If the server already has a registration object with the provided 872 account key, then it MUST return a 409 (Conflict) response and 873 provide the URI of that registration in a Location header field. 874 This allows a client that has an account key but not the 875 corresponding registration URI to recover the registration URI. 877 If the server wishes to present the client with terms under which the 878 ACME service is to be used, it MUST indicate the URI where such terms 879 can be accessed in a Link header with link relation "terms-of- 880 service". As noted above, the client may indicate its agreement with 881 these terms by updating its registration to include the "agreement" 882 field, with the terms URI as its value. 884 HTTP/1.1 201 Created 885 Content-Type: application/json 886 Location: https://example.com/acme/reg/asdf 887 Link: ;rel="next" 888 Link: ;rel="recover" 889 Link: ;rel="terms-of-service" 891 { 892 "key": { /* JWK from JWS header */ }, 894 "contact": [ 895 "mailto:cert-admin@example.com", 896 "tel:+12025551212" 897 ] 898 } 900 If the client wishes to update this information in the future, it 901 sends a POST request with updated information to the registration 902 URI. The server MUST ignore any updates to the "key", 903 "authorizations, or "certificates" fields, and MUST verify that the 904 request is signed with the private key corresponding to the "key" 905 field of the request before updating the registration. 907 Servers SHOULD NOT respond to GET requests for registration resources 908 as these requests are not authenticated. If a client wishes to query 909 the server for information about its account (e.g., to examine the 910 "contact" or "certificates" fields), then it SHOULD do so by sending 911 a POST request with an empty update. That is, it should send a JWS 912 whose payload is trivial ({"resource":"reg"}). 914 6.3.1. Recovery Keys 916 If the client wishes to establish a secret key with the server that 917 it can use to recover this account later (a "recovery key"), then it 918 must perform a simple key agreement protocol as part of the new- 919 registration transaction. The client and server perform an ECDH 920 exchange through the new-registration transaction (using the 921 technique in Section 5.6), and the result is the recovery key. 923 To request a recovery key, the client includes a "recoveryKey" field 924 in its new-registration request. The value of this field is a JSON 925 object. 927 client (required, JWK): The client's ECDH public key 929 length (required, number): The length of the derived secret, in 930 octets. 932 In the client's request, this object contains a JWK for a random ECDH 933 public key generated by the client and the client-selected length 934 value. Clients need to choose length values that balance security 935 and usability. On the one hand, a longer secret makes it more 936 difficult for an attacker to recover the secret when it is used for 937 recovery (see Section 6.4.1). On the other hand, clients may wish to 938 make the recovery key short enough for a user to easily write it 939 down. 941 POST /acme/new-registration HTTP/1.1 942 Host: example.com 944 { 945 "resource": "new-reg", 946 "contact": [ 947 "mailto:cert-admin@example.com", 948 "tel:+12025551212" 949 ], 950 "recoveryKey": { 951 "client": { "kty": "EC", ... }, 952 "length": 128 953 } 954 } 955 /* Signed as JWS */ 957 The server MUST validate that the elliptic curve ("crv") and length 958 value chosen by the client are acceptable, and that it is otherwise 959 willing to create a recovery key. If not, then it MUST reject the 960 new-registration request. 962 If the server agrees to create a recovery key, then it generates its 963 own random ECDH key pair and combines it with with the client's 964 public key as described in Section 5.6 above, using the label 965 "recovery". The derived secret value is the recovery key. The 966 server then returns to the client the ECDH key that it generated. 967 The server MUST generate a fresh key pair for every transaction. 969 server (required, JWK): The server's ECDH public key 970 HTTP/1.1 201 Created 971 Content-Type: application/json 972 Location: https://example.com/acme/reg/asdf 974 { 975 "key": { /* JWK from JWS header */ }, 977 "contact": [ 978 "mailto:cert-admin@example.com", 979 "tel:+12025551212" 980 ], 982 "recoveryKey": { 983 "server": { "kty": "EC", ... } 984 } 985 } 987 On receiving the server's response, the client can compute the 988 recovery key by combining the server's public key together with the 989 private key corresponding to the public key that it sent to the 990 server. 992 Clients may refresh the recovery key associated with a registration 993 by sending a POST request with a new recoveryKey object. If the 994 server agrees to refresh the recovery key, then it responds in the 995 same way as to a new registration request that asks for a recovery 996 key. 998 POST /acme/reg/asdf HTTP/1.1 999 Host: example.com 1001 { 1002 "resource": "reg", 1003 "recoveryKey": { 1004 "client": { "kty": "EC", ... } 1005 } 1006 } 1007 /* Signed as JWS */ 1009 6.4. Account Recovery 1011 Once a client has created an account with an ACME server, it is 1012 possible that the private key for the account will be lost. The 1013 recovery contacts included in the registration allows the client to 1014 recover from this situation, as long as it still has access to these 1015 contacts. 1017 By "recovery", we mean that the information associated with an old 1018 account key is bound to a new account key. When a recovery process 1019 succeeds, the server provides the client with a new registration 1020 whose contents are the same as base registration object - except for 1021 the "key" field, which is set to the new account key. The server 1022 reassigns resources associated with the base registration to the new 1023 registration (e.g., authorizations and certificates). The server 1024 SHOULD delete the old registration resource after it has been used as 1025 a base for recovery. 1027 In addition to the recovery mechanisms defined by ACME, individual 1028 client implementations may also offer implementation-specific 1029 recovery mechanisms. For example, if a client creates account keys 1030 deterministically from a seed value, then this seed could be used to 1031 recover the account key by re-generating it. Or an implementation 1032 could escrow an encrypted copy of the account key with a cloud 1033 storage provider, and give the encryption key to the user as a 1034 recovery value. 1036 6.4.1. MAC-Based Recovery 1038 With MAC-based recovery, the client proves to the server that it 1039 holds a secret value established in the initial registration 1040 transaction. The client requests MAC-based recovery by sending a MAC 1041 over the new account key, using the recovery key from the initial 1042 registration. 1044 method (required, string): The string "mac" 1046 base (required, string): The URI for the registration to be 1047 recovered. 1049 mac (required, string): A JSON-formatted JWS object using an HMAC 1050 algorithm, whose payload is the JWK representation of the public 1051 key of the new account key pair. 1053 POST /acme/recover-reg HTTP/1.1 1054 Host: example.com 1056 { 1057 "resource": "recover-reg", 1058 "method": "mac", 1059 "base": "https://example.com/acme/reg/asdf", 1060 "mac": { 1061 "header": { "alg": "HS256" }, 1062 "payload": base64(JWK(newAccountKey)), 1063 "signature": "5wUrDI3eAaV4wl2Rfj3aC0Pp--XB3t4YYuNgacv_D3U" 1064 } 1065 } 1066 /* Signed as JWS, with new account key */ 1068 On receiving such a request the server MUST verify that: 1070 o The base registration has a recovery key associated with it 1072 o The "alg" value in the "mac" JWS represents a MAC algorithm 1074 o The "mac" JWS is valid according to the validation rules in 1075 [RFC7515], using the recovery key as the MAC key 1077 o The JWK in the payload represents the new account key (i.e. the 1078 key used to verify the ACME message) 1080 If those conditions are met, and the recovery request is otherwise 1081 acceptable to the server, then the recovery process has succeeded. 1082 The server creates a new registration resource based on the base 1083 registration and the new account key, and returns it on a 201 1084 (Created) response, together with a Location header indicating a URI 1085 for the new registration. If the recovery request is unsuccessful, 1086 the server returns an error response, such as 403 (Forbidden). 1088 HTTP/1.1 201 Created 1089 Content-Type: application/json 1090 Location: https://example.com/acme/reg/asdf 1091 Link: ;rel="next" 1092 Link: ;rel="recover" 1093 Link: ;rel="terms-of-service" 1095 { 1096 "key": { /* JWK from JWS header */ }, 1098 "contact": [ 1099 "mailto:cert-admin@example.com", 1100 "tel:+12025551212" 1101 ], 1103 "authorizations": "...", 1104 "certificate": "..." 1105 } 1107 6.4.2. Contact-Based Recovery 1109 In the contact-based recovery process, the client requests that the 1110 server send a message to one of the contact URIs registered for the 1111 account. That message indicates some action that the server requires 1112 the client's user to perform, e.g., clicking a link in an email. If 1113 the user successfully completes the server's required actions, then 1114 the server will bind the account to the new account key. 1116 (Note that this process is almost entirely out of band with respect 1117 to ACME. ACME only allows the client to initiate the process, and 1118 the server to indicate the result.) 1120 To initiate contact-based recovery, the client sends a POST request 1121 to the server's recover-registration URI, with a body specifying 1122 which registration is to be recovered. The body of the request MUST 1123 be signed by the client's new account key pair. 1125 method (required, string): The string "contact" 1127 base (required, string): The URI for the registration to be 1128 recovered. 1130 POST /acme/recover-reg HTTP/1.1 1131 Host: example.com 1133 { 1134 "resource": "recover-reg", 1135 "method": "contact", 1136 "base": "https://example.com/acme/reg/asdf", 1137 "contact": [ 1138 "mailto:forgetful@example.net" 1139 ] 1140 } 1141 /* Signed as JWS, with new account key */ 1143 If the server agrees to attempt contact-based recovery, then it 1144 creates a new registration resource containing a stub registration 1145 object. The stub registration has the client's new account key and 1146 contacts, but no authorizations or certificates associated. The 1147 server returns the stub contact in a 201 (Created) response, along 1148 with a Location header field indicating the URI for the new 1149 registration resource (which will be the registration URI if the 1150 recovery succeeds). 1152 HTTP/1.1 201 Created 1153 Content-Type: application/json 1154 Location: https://example.com/acme/reg/qwer 1156 { 1157 "key": { /* new account key from JWS header */ }, 1159 "contact": [ 1160 "mailto:forgetful@example.net" 1161 ] 1162 } 1164 After recovery has been initiated, the server follows its chosen 1165 recovery process, out-of-band to ACME. While the recovery process is 1166 ongoing, the client may poll the registration resource's URI for 1167 status, by sending a POST request with a trivial body 1168 ({"resource":"reg"}). If the recovery process is still pending, the 1169 server sends a 202 (Accepted) status code, and a Retry-After header 1170 field. If the recovery process has failed, the server sends an error 1171 code (e.g., 404), and SHOULD delete the stub registration resource. 1173 If the recovery process has succeeded, then the server will send a 1174 200 (OK) response, containing the full registration object, with any 1175 necessary information copied from the old registration). The client 1176 may now use this in the same way as if he had gotten it from a new- 1177 registration transaction. 1179 6.5. Identifier Authorization 1181 The identifier authorization process establishes the authorization of 1182 an account to manage certificates for a given identifier. This 1183 process must assure the server of two things: First, that the client 1184 controls the private key of the account key pair, and second, that 1185 the client holds the identifier in question. This process may be 1186 repeated to associate multiple identifiers to a key pair (e.g., to 1187 request certificates with multiple identifiers), or to associate 1188 multiple accounts with an identifier (e.g., to allow multiple 1189 entities to manage certificates). 1191 As illustrated by the figure in the overview section above, the 1192 authorization process proceeds in two phases. The client first 1193 requests a new authorization, and the server issues challenges, then 1194 the client responds to those challenges and the server validates the 1195 client's responses. 1197 To begin the key authorization process, the client sends a POST 1198 request to the server's new-authorization resource. The body of the 1199 POST request MUST contain a JWS object, whose payload is a partial 1200 authorization object. This JWS object MUST contain only the 1201 "identifier" field, so that the server knows what identifier is being 1202 authorized. The server MUST ignore any other fields present in the 1203 client's request object. 1205 The authorization object is implicitly tied to the account key used 1206 to sign the request. Once created, the authorization may only be 1207 updated by that account. 1209 POST /acme/new-authorization HTTP/1.1 1210 Host: example.com 1212 { 1213 "resource": "new-authz", 1214 "identifier": { 1215 "type": "dns", 1216 "value": "example.org" 1217 } 1218 } 1219 /* Signed as JWS */ 1221 Before processing the authorization further, the server SHOULD 1222 determine whether it is willing to issue certificates for the 1223 identifier. For example, the server should check that the identifier 1224 is of a supported type. Servers might also check names against a 1225 blacklist of known high-value identifiers. If the server is 1226 unwilling to issue for the identifier, it SHOULD return a 403 1227 (Forbidden) error, with a problem document describing the reason for 1228 the rejection. 1230 If the server is willing to proceed, it builds a pending 1231 authorization object from the initial authorization object submitted 1232 by the client. 1234 o "identifier" the identifier submitted by the client. 1236 o "status": MUST be "pending" 1238 o "challenges" and "combinations": As selected by the server's 1239 policy for this identifier 1241 o The "expires" field MUST be absent. 1243 The server allocates a new URI for this authorization, and returns a 1244 201 (Created) response, with the authorization URI in a Location 1245 header field, and the JSON authorization object in the body. 1247 HTTP/1.1 201 Created 1248 Content-Type: application/json 1249 Location: https://example.com/authz/asdf 1250 Link: ;rel="next" 1252 { 1253 "status": "pending", 1255 "identifier": { 1256 "type": "dns", 1257 "value": "example.org" 1258 }, 1260 "challenges": [ 1261 { 1262 "type": "simpleHttp", 1263 "uri": "https://example.com/authz/asdf/0", 1264 "token": "IlirfxKKXAsHtmzK29Pj8A" 1265 }, 1266 { 1267 "type": "dns", 1268 "uri": "https://example.com/authz/asdf/1" 1269 "token": "DGyRejmCefe7v4NfDGDKfA" 1270 } 1271 }, 1273 "combinations": [ 1274 [0, 2], 1275 [1, 2] 1276 ] 1277 } 1279 The client needs to respond with information to complete the 1280 challenges. To do this, the client updates the authorization object 1281 received from the server by filling in any required information in 1282 the elements of the "challenges" dictionary. For example, if the 1283 client wishes to complete the "simpleHttp" challenge, it needs to 1284 provide the "path" component. (This is also the stage where the 1285 client should perform any actions required by the challenge.) 1287 The client sends these updates back to the server in the form of a 1288 JSON object with the response fields required by the challenge type, 1289 carried in a POST request to the challenge URI (not authorization URI 1290 or the new-authorization URI). This allows the client to send 1291 information only for challenges it is responding to. 1293 For example, if the client were to respond to the "simpleHttp" 1294 challenge in the above authorization, it would send the following 1295 request: 1297 POST /acme/authz/asdf/0 HTTP/1.1 1298 Host: example.com 1300 { 1301 "resource": "challenge", 1302 "type": "simpleHttp", 1303 "path": "Hf5GrX4Q7EBax9hc2jJnfw" 1304 } 1305 /* Signed as JWS */ 1307 The server updates the authorization document by updating its 1308 representation of the challenge with the response fields provided by 1309 the client. The server MUST ignore any fields in the response object 1310 that are not specified as response fields for this type of challenge. 1311 The server provides a 200 (OK) response with the updated challenge 1312 object as its body. 1314 Presumably, the client's responses provide the server with enough 1315 information to validate one or more challenges. The server is said 1316 to "finalize" the authorization when it has completed all the 1317 validations it is going to complete, and assigns the authorization a 1318 status of "valid" or "invalid", corresponding to whether it considers 1319 the account authorized for the identifier. If the final state is 1320 "valid", the server MUST add an "expires" field to the authorization. 1321 When finalizing an authorization, the server MAY remove the 1322 "combinations" field (if present) or remove any challenges still 1323 pending. The server SHOULD NOT remove challenges with status 1324 "invalid". 1326 Usually, the validation process will take some time, so the client 1327 will need to poll the authorization resource to see when it is 1328 finalized. For challenges where the client can tell when the server 1329 has validated the challenge (e.g., by seeing an HTTP or DNS request 1330 from the server), the client SHOULD NOT begin polling until it has 1331 seen the validation request from the server. 1333 To check on the status of an authorization, the client sends a GET 1334 request to the authorization URI, and the server responds with the 1335 current authorization object. In responding to poll requests while 1336 the validation is still in progress, the server MUST return a 202 1337 (Accepted) response with a Retry-After header field. 1339 GET /acme/authz/asdf HTTP/1.1 1340 Host: example.com 1342 HTTP/1.1 200 OK 1344 { 1345 "status": "valid", 1346 "expires": "2015-03-01", 1348 "identifier": { 1349 "type": "dns", 1350 "value": "example.org" 1351 }, 1353 "challenges": [ 1354 { 1355 "type": "simpleHttp" 1356 "status": "valid", 1357 "validated": "2014-12-01T12:05Z", 1358 "token": "IlirfxKKXAsHtmzK29Pj8A" 1359 "path": "Hf5GrX4Q7EBax9hc2jJnfw" 1360 } 1361 ] 1362 } 1364 6.6. Certificate Issuance 1366 The holder of an authorized key pair for an identifier may use ACME 1367 to request that a certificate be issued for that identifier. The 1368 client makes this request by sending a POST request to the server's 1369 new-certificate resource. The body of the POST is a JWS object whose 1370 JSON payload contains a Certificate Signing Request (CSR) [RFC2986]. 1371 The CSR encodes the parameters of the requested certificate; 1372 authority to issue is demonstrated by the JWS signature by an account 1373 key, from which the server can look up related authorizations. 1375 csr (required, string): A CSR encoding the parameters for the 1376 certificate being requested. The CSR is sent in the 1377 Base64-encoded version of the DER format. (Note: This field uses 1378 the same modified Base64-encoding rules used elsewhere in this 1379 document, so it is different from PEM.) 1381 POST /acme/new-cert HTTP/1.1 1382 Host: example.com 1383 Accept: application/pkix-cert 1385 { 1386 "resource": "new-cert", 1387 "csr": "5jNudRx6Ye4HzKEqT5...FS6aKdZeGsysoCo4H9P", 1388 } 1389 /* Signed as JWS */ 1391 The CSR encodes the client's requests with regard to the content of 1392 the certificate to be issued. The CSR MUST indicate the requested 1393 identifiers, either in the commonName portion of the requested 1394 subject name, or in an extensionRequest attribute [RFC2985] 1395 requesting a subjectAltName extension. 1397 The values provided in the CSR are only a request, and are not 1398 guaranteed. The server or CA may alter any fields in the certificate 1399 before issuance. For example, the CA may remove identifiers that are 1400 not authorized for the account key that signed the request. 1402 It is up to the server's local policy to decide which names are 1403 acceptable in a certificate, given the authorizations that the server 1404 associates with the client's account key. A server MAY consider a 1405 client authorized for a wildcard domain if it is authorized for the 1406 underlying domain name (without the "*" label). Servers SHOULD NOT 1407 extend authorization across identifier types. For example, if a 1408 client is authorized for "example.com", then the server should not 1409 allow the client to issue a certificate with an iPAddress 1410 subjectAltName, even if it contains an IP address to which 1411 example.com resolves. 1413 If the CA decides to issue a certificate, then the server creates a 1414 new certificate resource and returns a URI for it in the Location 1415 header field of a 201 (Created) response. 1417 HTTP/1.1 201 Created 1418 Location: https://example.com/acme/cert/asdf 1420 If the certificate is available at the time of the response, it is 1421 provided in the body of the response. If the CA has not yet issued 1422 the certificate, the body of this response will be empty. The client 1423 should then send a GET request to the certificate URI to poll for the 1424 certificate. As long as the certificate is unavailable, the server 1425 MUST provide a 202 (Accepted) response and include a Retry-After 1426 header to indicate when the server believes the certificate will be 1427 issued (as in the example above). 1429 GET /acme/cert/asdf HTTP/1.1 1430 Host: example.com 1431 Accept: application/pkix-cert 1433 HTTP/1.1 202 Accepted 1434 Retry-After: 120 1436 The default format of the certificate is DER (application/pkix-cert). 1437 The client may request other formats by including an Accept header in 1438 its request. 1440 The server provides metadata about the certificate in HTTP headers. 1441 In particular, the server MUST include a Link relation header field 1442 [RFC5988] with relation "up" to provide a certificate under which 1443 this certificate was issued, and one with relation "author" to 1444 indicate the registration under which this certicate was issued. The 1445 server MAY also include an Expires header as a hint to the client 1446 about when to renew the certificate. (Of course, the real expiration 1447 of the certificate is controlled by the notAfter time in the 1448 certificate itself.) 1450 GET /acme/cert/asdf HTTP/1.1 1451 Host: example.com 1452 Accept: application/pkix-cert 1454 HTTP/1.1 200 OK 1455 Content-Type: application/pkix-cert 1456 Link: ;rel="up";title="issuer" 1457 Link: ;rel="revoke" 1458 Link: ;rel="author" 1459 Location: https://example.com/acme/cert/asdf 1460 Content-Location: https://example.com/acme/cert-seq/12345 1462 [DER-encoded certificate] 1464 A certificate resource always represents the most recent certificate 1465 issued for the name/key binding expressed in the CSR. If the CA 1466 allows a certificate to be renewed, then it publishes renewed 1467 versions of the certificate through the same certificate URI. 1469 Clients retrieve renewed versions of the certificate using a GET 1470 query to the certificate URI, which the server should then return in 1471 a 200 (OK) response. The server SHOULD provide a stable URI for each 1472 specific certificate in the Content-Location header field, as shown 1473 above. Requests to stable certificate URIs MUST always result in the 1474 same certificate. 1476 To avoid unnecessary renewals, the CA may choose not to issue a 1477 renewed certificate until it receives such a request (if it even 1478 allows renewal at all). In such cases, if the CA requires some time 1479 to generate the new certificate, the CA MUST return a 202 (Accepted) 1480 response, with a Retry-After header field that indicates when the new 1481 certificate will be available. The CA MAY include the current (non- 1482 renewed) certificate as the body of the response. 1484 Likewise, in order to prevent unnecessary renewal due to queries by 1485 parties other than the account key holder, certificate URIs should be 1486 structured as capability URLs [W3C.WD-capability-urls-20140218]. 1488 From the client's perspective, there is no difference between a 1489 certificate URI that allows renewal and one that does not. If the 1490 client wishes to obtain a renewed certificate, and a GET request to 1491 the certificate URI does not yield one, then the client may initiate 1492 a new-certificate transaction to request one. 1494 6.7. Certificate Revocation 1496 To request that a certificate be revoked, the client sends a POST 1497 request to the ACME server's revoke-cert URI. The body of the POST 1498 is a JWS object whose JSON payload contains the certificate to be 1499 revoked: 1501 certificate (required, string): The certificate to be revoked, in 1502 the Base64-encoded version of the DER format. (Note: This field 1503 uses the same modified Base64-encoding rules used elsewhere in 1504 this document, so it is different from PEM.) 1506 POST /acme/revoke-cert HTTP/1.1 1507 Host: example.com 1509 { 1510 "resource": "revoke-cert", 1511 "certificate": "MIIEDTCCAvegAwIBAgIRAP8..." 1512 } 1513 /* Signed as JWS */ 1515 Revocation requests are different from other ACME request in that 1516 they can be signed either with an account key pair or the key pair in 1517 the certificate. Before revoking a certificate, the server MUST 1518 verify at least one of these conditions applies: 1520 o the public key of the key pair signing the request matches the 1521 public key in the certificate. 1523 o the key pair signing the request is an account key, and the 1524 corresponding account is authorized to act for all of the 1525 identifier(s) in the certificate. 1527 If the revocation succeeds, the server responds with status code 200 1528 (OK). If the revocation fails, the server returns an error. 1530 HTTP/1.1 200 OK 1531 Content-Length: 0 1533 --- or --- 1535 HTTP/1.1 403 Forbidden 1536 Content-Type: application/problem+json 1537 Content-Language: en 1539 { 1540 "type": "urn:acme:error:unauthorized" 1541 "detail": "No authorization provided for name example.net" 1542 "instance": "http://example.com/doc/unauthorized" 1543 } 1545 7. Identifier Validation Challenges 1547 There are few types of identifier in the world for which there is a 1548 standardized mechanism to prove possession of a given identifier. In 1549 all practical cases, CAs rely on a variety of means to test whether 1550 an entity applying for a certificate with a given identifier actually 1551 controls that identifier. 1553 Challenges provide the server with assurance the an account key 1554 holder is also the entity that controls an identifier. For each type 1555 of challenge, it must be the case that in order for an entity to 1556 successfully complete the challenge the entity must both: 1558 o Hold the private key of the account key pair used to respond to 1559 the challenge 1561 o Control the identifier in question 1563 Section 9 documents how the challenges defined in this document meet 1564 these requirements. New challenges will need to document how they 1565 do. 1567 To accommodate this reality, ACME includes an extensible challenge/ 1568 response framework for identifier validation. This section describes 1569 an initial set of Challenge types. Each challenge must describe: 1571 o Content of Challenge payloads (in Challenge messages) 1573 o Content of Response payloads (in authorizationRequest messages) 1575 o How the server uses the Challenge and Response to verify control 1576 of an identifier 1578 The general structure of Challenge and Response payloads is as 1579 follows: 1581 type (required, string): The type of Challenge or Response encoded 1582 in the object. 1584 uri (required, string): The URI to which a response can be posted. 1586 status (optional, string): : The status of this authorization. 1587 Possible values are: "unknown", "pending", "processing", "valid", 1588 "invalid" and "revoked". If this field is missing, then the default 1589 value is "pending". 1591 validated (optional, string): : The time at which this challenge was 1592 completed by the server, encoded in the format specified in RFC 3339 1593 [RFC3339]. 1595 error (optional, dictionary of string): : The error that occurred 1596 while the server was validating the challenge, if any. This field is 1597 structured as a problem document [I-D.ietf-appsawg-http-problem]. 1599 All additional fields are specified by the Challenge type. The 1600 server MUST ignore any values provided in the "uri", "status", 1601 "validated", and "error" fields of a Response payload. If the server 1602 sets a Challenge's "status" to "invalid", it SHOULD also include the 1603 "error" field to help the client diagnose why they failed the 1604 challenge. 1606 Different challenges allow the server to obtain proof of different 1607 aspects of control over an identifier. In some challenges, like 1608 Simple HTTP and DVSNI, the client directly proves its ability to do 1609 certain things related to the identifier. In the Proof of Possession 1610 challenge, the client proves historical control of the identifier, by 1611 reference to a prior authorization transaction or certificate. 1613 The choice of which Challenges to offer to a client under which 1614 circumstances is a matter of server policy. A CA may choose 1615 different sets of challenges depending on whether it has interacted 1616 with a domain before, and how. For example: 1618 o New domain with no known certificates: Domain Validation (DVSNI or 1619 Simple HTTP) 1621 o Domain for which known certs exist from other CAs: DV + Proof of 1622 Possession of previous CA-signed key 1624 o Domain with a cert from this CA, lost account key: DV + PoP of 1625 ACME-certified Subject key 1627 o Domain with a cert from this CA, all keys and recovery mechanisms 1628 lost: Out of band proof of authority for the domain 1630 The identifier validation challenges described in this section all 1631 relate to validation of domain names. If ACME is extended in the 1632 future to support other types of identifier, there will need to be 1633 new Challenge types, and they will need to specify which types of 1634 identifier they apply to. 1636 7.1. Simple HTTP 1638 With Simple HTTP validation, the client in an ACME transaction proves 1639 its control over a domain name by proving that it can provision 1640 resources on an HTTP server that responds for that domain name. The 1641 ACME server challenges the client to provision a file with a specific 1642 string as its contents. 1644 As a domain may resolve to multiple IPv4 and IPv6 addresses, the 1645 server will connect to at least one of the hosts found in A and AAAA 1646 records, at its discretion. The HTTP server may be made available 1647 over either HTTPS or unencrypted HTTP; the client tells the server in 1648 its response which to check. 1650 type (required, string): The string "simpleHttp" 1652 token (required, string): The value to be provisioned in the file. 1653 This value MUST have at least 128 bits of entropy, in order to 1654 prevent an attacker from guessing it. It MUST NOT contain any 1655 non-ASCII characters. 1657 { 1658 "type": "simpleHttp", 1659 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ+PCt92wr+oA" 1660 } 1662 A client responds to this challenge by signing a JWS object and 1663 provisioning it as a resource on the HTTP server for the domain in 1664 question. The payload of the JWS MUST be a JSON dictionary 1665 containing the fields "type", "token", "path", and "tls" from the 1666 ACME challenge and response (see below), and no other fields. If the 1667 "tls" field is not included in the response, then validation object 1668 MUST have its "tls" field set to "true". The JWS MUST be signed with 1669 the client's account key pair. This JWS is NOT REQUIRED to have a 1670 "nonce" header parameter (as with the JWS objects that carry ACME 1671 request objects), but MUST otherwise meet the guidelines laid out in 1672 Section 3. 1674 { 1675 "type": "simpleHttp", 1676 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA", 1677 "tls": false 1678 } 1680 The path at which the resource is provisioned is comprised of the 1681 fixed prefix ".well-known/acme-challenge/", followed by the "token" 1682 value in the challenge. 1684 .well-known/acme-challenge/evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA 1686 The client's response to this challenge indicates whether it would 1687 prefer for the validation request to be sent over TLS: 1689 type (required, string): The string "simpleHttp" 1691 tls (optional, boolean, default true): If this attribute is present 1692 and set to "false", the server will perform its validation check 1693 over unencrypted HTTP (on port 80) rather than over HTTPS. 1694 Otherwise the check will be done over HTTPS, on port 443. 1696 { 1697 "type": "simpleHttp", 1698 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA", 1699 "tls": false 1700 } 1701 /* Signed as JWS */ 1703 Given a Challenge/Response pair, the server verifies the client's 1704 control of the domain by verifying that the resource was provisioned 1705 as expected. 1707 1. Form a URI by populating the URI template [RFC6570] 1708 "{scheme}://{domain}/.well-known/acme-challenge/{token}", where: 1710 * the scheme field is set to "http" if the "tls" field in the 1711 response is present and set to false, and "https" otherwise; 1713 * the domain field is set to the domain name being verified; and 1714 * the token field is the token provided in the challenge. 1716 2. Verify that the resulting URI is well-formed. 1718 3. Dereference the URI using an HTTP or HTTPS GET request. If using 1719 HTTPS, the ACME server MUST ignore the certificate provided by 1720 the HTTPS server. 1722 4. Verify that the Content-Type header of the response is either 1723 absent, or has the value "application/jose+json" 1725 5. Verify that the body of the response is a valid JWS of the type 1726 indicated by the Content-Type header (if present), signed with 1727 the client's account key 1729 6. Verify that the payload of the JWS meets the following criteria: 1731 * It is a valid JSON dictionary 1733 * It has exactly four fields 1735 * Its "type" field is set to "simpleHttp" 1737 * Its "token" field is equal to the "token" field in the 1738 challenge 1740 * Its "path" field is equal to the "path" field in the response 1742 * Its "tls" field is equal to the "tls" field in the response, 1743 or "true" if the "tls" field was absent 1745 Comparisons of the "path" and "token" fields MUST be performed in 1746 terms of Unicode code points, taking into account the encodings of 1747 the stored nonce and the body of the request. 1749 If all of the above verifications succeed, then the validation is 1750 successful. If the request fails, or the body does not pass these 1751 checks, then it has failed. 1753 7.2. Domain Validation with Server Name Indication (DVSNI) 1755 The Domain Validation with Server Name Indication (DVSNI) validation 1756 method proves control over a domain name by requiring the client to 1757 configure a TLS server referenced by an A/AAAA record under the 1758 domain name to respond to specific connection attempts utilizing the 1759 Server Name Indication extension [RFC6066]. The server verifies the 1760 client's challenge by accessing the reconfigured server and verifying 1761 a particular challenge certificate is presented. 1763 type (required, string): The string "dvsni" 1765 token (required, string): A random value with at least 128 bits of 1766 entropy, base64-encoded 1768 { 1769 "type": "dvsni", 1770 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJyPCt92wrDoA", 1771 } 1773 In response to the challenge, the client uses its account private key 1774 to sign a JWS over a JSON object describing the challenge. The 1775 validation object covered by the signature MUST have the following 1776 fields and no others: 1778 type (required, string): The string "dvsni" 1780 token (required, string): A random value with at least 128 bits of 1781 entropy, base64-encoded 1783 { 1784 "type": "dvsni", 1785 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJyPCt92wrDoA", 1786 } 1788 The client serializes the validation object to UTF-8, then uses its 1789 account private key to sign a JWS with the serialized JSON object as 1790 its payload. This JWS is NOT REQUIRED to have the "nonce" header 1791 parameter. 1793 The client will compute Z, the SHA-256 of the "signature" value from 1794 the JWS. The hash is calculated over the base64-encoded signature 1795 string. Z is encoded in hexadecimal form. 1797 The client will generate a self-signed certificate with the 1798 subjectAlternativeName extension containing the dNSName 1799 "..acme.invalid". The client will then configure 1800 the TLS server at the domain such that when a handshake is initiated 1801 with the Server Name Indication extension set to 1802 "..acme.invalid", the generated test certificate 1803 is presented. 1805 The response to the DVSNI challenge provides the validation JWS to 1806 the server. 1808 type (required, string): The string "dvsni" 1809 validation (required, string): The JWS object computed with the 1810 validation object and the account key 1812 { 1813 "type": "dvsni", 1814 "validation": { 1815 "header": { "alg": "RS256" }, 1816 "payload": "qzu9...6bjn", 1817 "signature": "gfj9XqFv07e1wU66hSLYkiFqYakPSjAu8TsyXRg85nM" 1818 } 1819 } 1821 Given a Challenge/Response pair, the ACME server verifies the 1822 client's control of the domain by verifying that the TLS server was 1823 configured appropriately. 1825 1. Verify the validation JWS using the account key for which the 1826 challenge was issued. 1828 2. Decode the payload of the JWS as UTF-8 encoded JSON. 1830 3. Verify that there are exactly two fields in the decoded object, 1831 and that: 1833 * The "type" field is set to "dvsni" 1835 * The "token" field matches the "token" value in the challenge 1837 4. Open a TLS connection to the domain name being validated on port 1838 443, presenting the value "..acme.invalid" in 1839 the SNI field. 1841 5. Verify that the certificate contains a subjectAltName extension 1842 with the dNSName of "..acme.invalid". 1844 It is RECOMMENDED that the ACME server validation TLS connections 1845 from multiple vantage points to reduce the risk of DNS hijacking 1846 attacks. 1848 If all of the above verifications succeed, then the validation is 1849 successful. Otherwise, the validation fails. 1851 7.3. Proof of Possession of a Prior Key 1853 The Proof of Possession challenge verifies that a client possesses a 1854 private key corresponding to a server-specified public key, as 1855 demonstrated by its ability to sign with that key. This challenge is 1856 meant to be used when the server knows of a public key that is 1857 already associated with the identifier being claimed, and wishes for 1858 new authorizations to be authorized by the holder of the 1859 corresponding private key. For DNS identifiers, for example, this 1860 can help guard against domain hijacking. 1862 This method is useful if a server policy calls for issuing a 1863 certificate only to an entity that already possesses the subject 1864 private key of a particular prior related certificate (perhaps issued 1865 by a different CA). It may also help enable other kinds of server 1866 policy that are related to authenticating a client's identity using 1867 digital signatures. 1869 This challenge proceeds in much the same way as the proof of 1870 possession of the authorized key pair in the main ACME flow 1871 (challenge + authorizationRequest). The server provides a nonce and 1872 the client signs over the nonce. The main difference is that rather 1873 than signing with the private key of the key pair being authorized, 1874 the client signs with a private key specified by the server. The 1875 server can specify which key pair(s) are acceptable directly (by 1876 indicating a public key), or by asking for the key corresponding to a 1877 certificate. 1879 The server provides the following fields as part of the challenge: 1881 type (required, string): The string "proofOfPossession" 1883 certs (optional, array of string): An array of certificates, in 1884 Base64-encoded DER format, that contain acceptable public keys. 1886 { 1887 "type": "proofOfPossession", 1888 "certs": ["MIIF7z...bYVQLY"] 1889 } 1891 In response to this challenge, the client uses the private key 1892 corresponding to one of the acceptable public keys to sign a JWS 1893 object including data related to the challenge. The validation 1894 object covered by the signature has the following fields: 1896 type (required, string): The string "proofOfPossession" 1898 identifiers (required, identifier): A list of identifiers for which 1899 the holder of the prior key authorizes the new key 1901 accountKey (required, JWK): The client's account public key 1902 { 1903 "type": "proofOfPossession", 1904 "identifiers: [{"type": "dns", "value": "example.com"}], 1905 "accountKey": { "kty": "RSA", ... } 1906 } 1908 This JWS is NOT REQUIRED to have a "nonce" header parameter (as with 1909 the JWS objects that carry ACME request objects). This allows proof- 1910 of-possession response objects to be computed off-line. For example, 1911 as part of a domain transfer, the new domain owner might require the 1912 old domain owner to sign a proof-of-possession validation object, so 1913 that the new domain owner can present that in an ACME transaction 1914 later. 1916 The validation JWS MUST contain a "jwk" header parameter indicating 1917 the public key under which the server should verify the JWS. 1919 The client's response includes the server-provided nonce, together 1920 with a signature over that nonce by one of the private keys requested 1921 by the server. 1923 type (required, string): The string "proofOfPossession" 1925 authorization (required, JWS): The validation JWS 1927 { 1928 "type": "proofOfPossession", 1929 "authorization": { 1930 "header": { 1931 "alg": "RS256", 1932 "jwk": { 1933 "kty": "RSA", 1934 "e": "AQAB", 1935 "n": "AMswMT...3aVtjE" 1936 } 1937 }, 1938 "payload": "SfiR1...gSAl7A", 1939 "signature": "XcQLfL...cW5beg" 1940 } 1941 } 1943 To validate a proof-of-possession challenge, the server performs the 1944 following steps: 1946 1. Verify that the public key in the "jwk" header of the 1947 "authorization" JWS corresponds to one of the certificates in the 1948 "certs" field of the challenge 1950 2. Verify the "authorization" JWS using the key indicated in its 1951 "jwk" header 1953 3. Decode the payload of the JWS as UTF-8 encoded JSON 1955 4. Verify that there are exactly three fields in the decoded object, 1956 and that: 1958 * The "type" field is set to "proofOfPossession" 1960 * The "identifier" field contains the identifier for which 1961 authorization is being validated 1963 * The "accountKey" field matches the account key for which the 1964 challenge was issued 1966 If all of the above verifications succeed, then the validation is 1967 successful. Otherwise, the validation fails. 1969 7.4. DNS 1971 When the identifier being validated is a domain name, the client can 1972 prove control of that domain by provisioning resource records under 1973 it. The DNS challenge requires the client to provision a TXT record 1974 containing a designated value under a specific validation domain 1975 name. 1977 type (required, string): The string "dns" 1979 token (required, string): A random value with at least 128 bits of 1980 entropy. It MUST NOT contain any characters outside the URL-safe 1981 Base64 alphabet. 1983 { 1984 "type": "dns", 1985 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ+PCt92wr+oA", 1986 } 1988 In response to this challenge, the client uses its account private 1989 key to sign a JWS over a JSON object describing the challenge. The 1990 validation object covered by the signature MUST have the following 1991 fields and no others: 1993 type (required, string): The string "dns" 1995 token (required, string): The token value in the challenge 1996 { 1997 "type": "dns", 1998 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ+PCt92wr+oA", 1999 } 2001 The client serializes the validation object to UTF-8, then uses its 2002 account private key to sign a JWS with the serialized JSON object as 2003 its payload. This JWS is NOT REQUIRED to have the "nonce" header 2004 parameter. 2006 The record provisioned to the DNS is the "signature" value from the 2007 JWS, i.e., the base64-encoded signature value. The client constructs 2008 the validation domain name by appending the label "_acme-challenge" 2009 to the domain name being validated, then provisions a TXT record with 2010 the signature value under that name. For example, if the domain name 2011 being validated is "example.com", then the client would provision the 2012 following DNS record: 2014 _acme-challenge.example.com. 300 IN TXT "gfj9Xq...Rg85nM" 2016 The response to a DNS challenge provides the validation JWS to the 2017 server. 2019 type (required, string): The string "dns" 2021 validation (required, JWS): The JWS object computed with the 2022 validation object and the account key 2024 { 2025 "type": "dns" 2026 "clientPublicKey": { "kty": "EC", ... }, 2027 "validation": { 2028 "header": { "alg": "HS256" }, 2029 "payload": "qzu9...6bjn", 2030 "signature": "gfj9XqFv07e1wU66hSLYkiFqYakPSjAu8TsyXRg85nM" 2031 } 2032 } 2034 To validate a DNS challenge, the server performs the following steps: 2036 1. Verify the validation JWS using the account key for which this 2037 challenge was issued 2039 2. Decode the payload of the JWS as UTF-8 encoded JSON 2041 3. Verify that there are exactly two fields in the decoded object, 2042 and that: 2044 * The "type" field is set to "dns" 2046 * The "token" field matches the "token" value in the challenge 2048 4. Query for TXT records under the validation domain name 2050 5. Verify that the contents of one of the TXT records match the 2051 "signature" value in the "validation" JWS 2053 If all of the above verifications succeed, then the validation is 2054 successful. If no DNS record is found, or DNS record and response 2055 payload do not pass these checks, then the validation fails. 2057 8. IANA Considerations 2059 TODO 2061 o Register .well-known path 2063 o Register Replay-Nonce HTTP header 2065 o Register "nonce" JWS header parameter 2067 o Register "urn:acme" namespace 2069 o Create identifier validation method registry 2071 o Registries of syntax tokens, e.g., message types / error types? 2073 9. Security Considerations 2075 ACME is a protocol for managing certificates that attest to 2076 identifier/key bindings. Thus the foremost security goal of ACME is 2077 to ensure the integrity of this process, i.e., to ensure that the 2078 bindings attested by certificates are correct, and that only 2079 authorized entities can manage certificates. ACME identifies clients 2080 by their account keys, so this overall goal breaks down into two more 2081 precise goals: 2083 1. Only an entity that controls a identifier can get an account key 2084 authorized for that identifier 2086 2. Once authorized, an account key's authorizations cannot be 2087 improperly transferred to another account key 2089 In this section, we discuss the threat model that underlies ACME and 2090 the ways that ACME achieves these security goals within that threat 2091 model. We also discuss the denial-of-service risks that ACME servers 2092 face, and a few other miscellaneous considerations. 2094 9.1. Threat model 2096 As a service on the Internet, ACME broadly exists within the Internet 2097 threat model [RFC3552]. In analyzing ACME, it is useful to think of 2098 an ACME server interacting with other Internet hosts along three 2099 "channels": 2101 o An ACME channel, over which the ACME HTTPS requests are exchanged 2103 o A validation channel, over which the ACME server performs 2104 additional requests to validate a client's control of an 2105 identifier 2107 o A contact channel, over which the ACME server sends messages to 2108 the registered contacts for ACME clients 2110 +------------+ 2111 | ACME | ACME Channel 2112 | Client |--------------------+ 2113 +------------+ | 2114 ^ V 2115 | Contact Channel +------------+ 2116 +--------------------| ACME | 2117 | Server | 2118 +------------+ 2119 +------------+ | 2120 | Validation |<-------------------+ 2121 | Server | Validation Channel 2122 +------------+ 2124 In practice, the risks to these channels are not entirely separate, 2125 but they are different in most cases. Each of the three channels, 2126 for example, uses a different communications pattern: the ACME 2127 channel will comprise inbound HTTPS connections to the ACME server, 2128 the validation channel outbound HTTP or DNS requests, and the contact 2129 channel will use channels such as email and PSTN. 2131 Broadly speaking, ACME aims to be secure against active and passive 2132 attackers on any individual channel. Some vulnerabilities arise 2133 (noted below), when an attacker can exploit both the ACME channel and 2134 one of the others. 2136 On the ACME channel, in addition to network-layer attackers, we also 2137 need to account for application-layer man in the middle attacks, and 2138 for abusive use of the protocol itself. Protection against 2139 application-layer MitM addresses potential attackers such as Content 2140 Distribution Networks (CDNs) and middleboxes with a TLS MitM 2141 function. Preventing abusive use of ACME means ensuring that an 2142 attacker with access to the validation or contact channels can't 2143 obtain illegitimate authorization by acting as an ACME client 2144 (legitimately, in terms of the protocol). 2146 9.2. Integrity of Authorizations 2148 ACME allows anyone to request challenges for an identifier by 2149 registering an account key and sending a new-authorization request 2150 under that account key. The integrity of the authorization process 2151 thus depends on the identifier validation challenges to ensure that 2152 the challenge can only be completed by someone who both (1) holds the 2153 private key of the account key pair, and (2) controls the identifier 2154 in question. 2156 Validation responses need to be bound to an account key pair in order 2157 to avoid situations where an ACME MitM can switch out a legitimate 2158 domain holder's account key for one of his choosing, e.g.: 2160 o Legitimate domain holder registers account key pair A 2162 o MitM registers account key pair B 2164 o Legitimate domain holder sends a new-authorization request signed 2165 under account key A 2167 o MitM suppresses the legitimate request, but sends the same request 2168 signed under account key B 2170 o ACME server issues challenges and MitM forwards them to the 2171 legitimate domain holder 2173 o Legitimate domain holder provisions the validation response 2175 o ACME server performs validation query and sees the response 2176 provisioned by the legitimate domain holder 2178 o Because the challenges were issued in response to a message signed 2179 account key B, the ACME server grants authorization to account key 2180 B (the MitM) instead of account key A (the legitimate domain 2181 holder) 2183 All of the challenges above that require an out-of-band query by the 2184 server have a binding to the account private key, such that the only 2185 the account private key holder can successfully respond to the 2186 validation query: 2188 o Simple HTTP: The value provided in the validation request is 2189 signed by the account private key. 2191 o DVSNI: The validation TLS request uses the account key pair as the 2192 server's key pair. 2194 o DNS: The MAC covers the account key, and the MAC key is derived 2195 from an ECDH public key signed with the account private key. 2197 o Proof of possession of a prior key: The signature by the prior key 2198 covers the account public key. 2200 The association of challenges to identifiers is typically done by 2201 requiring the client to perform some action that only someone who 2202 effectively controls the identifier can perform. For the challenges 2203 in this document, the actions are: 2205 o Simple HTTP: Provision files under .well-known on a web server for 2206 the domain 2208 o DVSNI: Configure a TLS server for the domain 2210 o DNS: Provision DNS resource records for the domain 2212 o Proof of possession of a prior key: Sign using the private key 2213 specified by the server 2215 There are several ways that these assumptions can be violated, both 2216 by misconfiguration and by attack. For example, on a web server that 2217 allows non-administrative users to write to .well-known, any user can 2218 claim to own the server's hostname by responding to a Simple HTTP 2219 challenge, and likewise for TLS configuration and DVSNI. 2221 The use of hosting providers is a particular risk for ACME 2222 validation. If the owner of the domain has outsourced operation of 2223 DNS or web services to a hosting provider, there is nothing that can 2224 be done against tampering by the hosting provider. As far as the 2225 outside world is concerned, the zone or web site provided by the 2226 hosting provider is the real thing. 2228 More limited forms of delegation can also lead to an unintended party 2229 gaining the ability to successfully complete a validation 2230 transaction. For example, suppose an ACME server follows HTTP 2231 redirects in Simple HTTP validation and a web site operator 2232 provisions a catch-all redirect rule that redirects requests for 2233 unknown resources to different domain. Then the target of the 2234 redirect could use that to get a certificate through Simple HTTP 2235 validation, since the validation path will not be known to the 2236 primary server. 2238 The DNS is a common point of vulnerability for all of these 2239 challenges. An entity that can provision false DNS records for a 2240 domain can attack the DNS challenge directly, and can provision false 2241 A/AAAA records to direct the ACME server to send its DVSNI or Simple 2242 HTTP validation query to a server of the attacker's choosing. There 2243 are a few different mitigations that ACME servers can apply: 2245 o Checking the DNSSEC status of DNS records used in ACME validation 2246 (for zones that are DNSSEC-enabled) 2248 o Querying the DNS from multiple vantage points to address local 2249 attackers 2251 o Applying mitigations against DNS off-path attackers, e.g., adding 2252 entropy to requests [I-D.vixie-dnsext-dns0x20] or only using TCP 2254 Given these considerations, the ACME validation process makes it 2255 impossible for any attacker on the ACME channel, or a passive 2256 attacker on the validation channel to hijack the authorization 2257 process to authorize a key of the attacker's choice. 2259 An attacker that can only see the ACME channel would need to convince 2260 the validation server to provide a response that would authorize the 2261 attacker's account key, but this is prevented by binding the 2262 validation response to the account key used to request challenges. A 2263 passive attacker on the validation channel can observe the correct 2264 validation response and even replay it, but that response can only be 2265 used with the account key for which it was generated. 2267 An active attacker on the validation channel can subvert the ACME 2268 process, by performing normal ACME transactions and providing a 2269 validation response for his own account key. The risks due to 2270 hosting providers noted above are a particular case. For identifiers 2271 where the server already has some credential associated with the 2272 domain this attack can be prevented by requiring the client to 2273 complete a proof-of-possession challenge. 2275 9.3. Preventing Authorization Hijacking 2277 The account recovery processes described in Section 6.4 allow 2278 authorization to be transferred from one account key to another, in 2279 case the former account key pair's private key is lost. ACME needs 2280 to prevent these processes from being exploited by an attacker to 2281 hijack the authorizations attached to one key and assign them to a 2282 key of the attacker's choosing. 2284 Recovery takes place in two steps: 1. Provisioning recovery 2285 information (contact or recovery key) 2. Using recovery information 2286 to recover an account 2288 The provisioning process needs to ensure that only the account key 2289 holder ends up with information that is useful for recovery. The 2290 recovery process needs to assure that only the (now former) account 2291 key holder can successfully execute recovery, i.e., that this entity 2292 is the only one that can choose the new account key that receives the 2293 capabilities held by the account being recovered. 2295 MAC-based recovery can be performed if the attacker knows the account 2296 key and registration URI for the account being recovered. Both of 2297 these are difficult to obtain for a network attacker, because ACME 2298 uses HTTPS, though if the recovery key and registration URI are 2299 sufficiently predictable, the attacker might be able to guess them. 2300 An ACME MitM can see the registration URI, but still has to guess the 2301 recovery key, since neither the ECDH in the provisioning phase nor 2302 HMAC in the recovery phase will reveal it to him. 2304 ACME clients can thus mitigate problems with MAC-based recovery by 2305 using long recovery keys. ACME servers should enforce a minimum 2306 recovery key length, and impose rate limits on recovery to limit an 2307 attacker's ability to test different guesses about the recovery key. 2309 Contact-based recovery uses both the ACME channel and the contact 2310 channel. The provisioning process is only visible to an ACME MitM, 2311 and even then, the MitM can only observe the contact information 2312 provided. If the ACME attacker does not also have access to the 2313 contact channel, there is no risk. 2315 The security of the contact-based recovery process is entirely 2316 dependent on the security of the contact channel. The details of 2317 this will depend on the specific out-of-band technique used by the 2318 server. For example: 2320 o If the server requires a user to click a link in a message sent to 2321 a contact address, then the contact channel will need to ensure 2322 that the message is only available to the legitimate owner of the 2323 contact address. Otherwise, a passive attacker could see the link 2324 and click it first, or an active attacker could redirect the 2325 message. 2327 o If the server requires a user to respond to a message sent to a 2328 contact address containing a secret value, then the contact 2329 channel will need to ensure that an attacker cannot observe the 2330 secret value and spoof a message from the contact address. 2332 In practice, many contact channels that can be used to reach many 2333 clients do not provide strong assurances of the types noted above. 2334 In designing and deploying contact-based recovery schemes, ACME 2335 servers operators will need to find an appropriate balance between 2336 using contact channels that can reach many clients and using contact- 2337 based recovery schemes that achieve an appropriate level of risk 2338 using those contact channels. 2340 9.4. Denial-of-Service Considerations 2342 As a protocol run over HTTPS, standard considerations for TCP-based 2343 and HTTP-based DoS mitigation also apply to ACME. 2345 At the application layer, ACME requires the server to perform a few 2346 potentially expensive operations. Identifier validation transactions 2347 require the ACME server to make outbound connections to potentially 2348 attacker-controlled servers, and certificate issuance can require 2349 interactions with cryptographic hardware. 2351 In addition, an attacker can also cause the ACME server to send 2352 validation requests to a domain of its choosing by submitting 2353 authorization requests for the victim domain. 2355 All of these attacks can be mitigated by the application of 2356 appropriate rate limits. Issues closer to the front end, like POST 2357 body validation, can be addressed using HTTP request limiting. For 2358 validation and certificate requests, there are other identifiers on 2359 which rate limits can be keyed. For example, the server might limit 2360 the rate at which any individual account key can issue certificates, 2361 or the rate at which validation can be requested within a given 2362 subtree of the DNS. 2364 9.5. CA Policy Considerations 2366 The controls on issuance enabled by ACME are focused on validating 2367 that a certificate applicant controls the identifier he claims. 2368 Before issuing a certificate, however, there are many other checks 2369 that a CA might need to perform, for example: 2371 o Has the client agreed to a subscriber agreement? 2373 o Is the claimed identifier syntactically valid? 2375 o For domain names: 2377 * If the leftmost label is a '*', then have the appropriate 2378 checks been applied? 2380 * Is the name on the Public Suffix List? 2382 * Is the name a high-value name? 2384 * Is the name a known phishing domain? 2386 o Is the key in the CSR sufficiently strong? 2388 o Is the CSR signed with an acceptable algorithm? 2390 CAs that use ACME to automate issuance will need to ensure that their 2391 servers perform all necessary checks before issuing. 2393 10. Acknowledgements 2395 In addition to the editors listed on the front page, this document 2396 has benefited from contributions from a broad set of contributors, 2397 all the way back to its inception. 2399 o Peter Eckersley, EFF 2401 o Eric Rescorla, Mozilla 2403 o Seth Schoen, EFF 2405 o Alex Halderman, University of Michigan 2407 o Martin Thomson, Mozilla 2409 o Jakub Warmuz, University of Oxford 2411 This document draws on many concepts established by Eric Rescorla's 2412 "Automated Certificate Issuance Protocol" draft. Martin Thomson 2413 provided helpful guidance in the use of HTTP. 2415 11. References 2417 11.1. Normative References 2419 [I-D.ietf-appsawg-http-problem] 2420 Nottingham, M. and E. Wilde, "Problem Details for HTTP 2421 APIs", draft-ietf-appsawg-http-problem-00 (work in 2422 progress), September 2014. 2424 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2425 Requirement Levels", BCP 14, RFC 2119, March 1997. 2427 [RFC2314] Kaliski, B., "PKCS #10: Certification Request Syntax 2428 Version 1.5", RFC 2314, March 1998. 2430 [RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object 2431 Classes and Attribute Types Version 2.0", RFC 2985, 2432 November 2000. 2434 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 2435 Request Syntax Specification Version 1.7", RFC 2986, 2436 November 2000. 2438 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 2439 Internet: Timestamps", RFC 3339, July 2002. 2441 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2442 Resource Identifier (URI): Generic Syntax", STD 66, RFC 2443 3986, January 2005. 2445 [RFC4514] Zeilenga, K., "Lightweight Directory Access Protocol 2446 (LDAP): String Representation of Distinguished Names", RFC 2447 4514, June 2006. 2449 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2450 Encodings", RFC 4648, October 2006. 2452 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2453 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2454 May 2008. 2456 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2457 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2459 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2460 Housley, R., and W. Polk, "Internet X.509 Public Key 2461 Infrastructure Certificate and Certificate Revocation List 2462 (CRL) Profile", RFC 5280, May 2008. 2464 [RFC5753] Turner, S. and D. Brown, "Use of Elliptic Curve 2465 Cryptography (ECC) Algorithms in Cryptographic Message 2466 Syntax (CMS)", RFC 5753, January 2010. 2468 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 2470 [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: 2471 Extension Definitions", RFC 6066, January 2011. 2473 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 2474 and D. Orchard, "URI Template", RFC 6570, March 2012. 2476 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 2477 Interchange Format", RFC 7159, March 2014. 2479 [RFC7469] Evans, C., Palmer, C., and R. Sleevi, "Public Key Pinning 2480 Extension for HTTP", RFC 7469, April 2015. 2482 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2483 Signature (JWS)", RFC 7515, May 2015. 2485 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, May 2015. 2487 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, May 2488 2015. 2490 [SEC1] Standards for Efficient Cryptography Group, "SEC 1: 2491 Elliptic Curve Cryptography", May 2009, 2492 . 2494 11.2. Informative References 2496 [I-D.vixie-dnsext-dns0x20] 2497 Vixie, P. and D. Dagon, "Use of Bit 0x20 in DNS Labels to 2498 Improve Transaction Identity", draft-vixie-dnsext- 2499 dns0x20-00 (work in progress), March 2008. 2501 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2503 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 2504 Text on Security Considerations", BCP 72, RFC 3552, July 2505 2003. 2507 [W3C.CR-cors-20130129] 2508 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 2509 Web Consortium CR CR-cors-20130129, January 2013, 2510 . 2512 [W3C.WD-capability-urls-20140218] 2513 Tennison, J., "Good Practices for Capability URLs", World 2514 Wide Web Consortium WD WD-capability-urls-20140218, 2515 February 2014, 2516 . 2518 Authors' Addresses 2520 Richard Barnes 2521 Mozilla 2523 Email: rlb@ipv.sx 2524 Jacob Hoffman-Andrews 2525 EFF 2527 Email: jsha@eff.org 2529 James Kasten 2530 University of Michigan 2532 Email: jdkasten@umich.edu