idnits 2.17.1 draft-barnes-acme-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 84 instances of too long lines in the document, the longest one being 536 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 430 has weird spacing: '...ew-cert cer...' -- The document date (January 28, 2015) is 3377 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 760 -- Looks like a reference, but probably isn't: '2' on line 761 -- Looks like a reference, but probably isn't: '1' on line 761 -- Looks like a reference, but probably isn't: '34234239832' on line 1213 -- Looks like a reference, but probably isn't: '23993939911' on line 1213 -- Looks like a reference, but probably isn't: '17' on line 1213 == Unused Reference: 'I-D.ietf-jose-json-web-algorithms' is defined on line 1327, but no explicit reference was found in the text == Unused Reference: 'RFC2985' is defined on line 1346, but no explicit reference was found in the text == Unused Reference: 'RFC3986' is defined on line 1357, but no explicit reference was found in the text == Unused Reference: 'RFC4514' is defined on line 1361, but no explicit reference was found in the text == Unused Reference: 'RFC5226' is defined on line 1365, but no explicit reference was found in the text == Unused Reference: 'RFC5246' is defined on line 1369, but no explicit reference was found in the text == Unused Reference: 'RFC5280' is defined on line 1372, but no explicit reference was found in the text == Unused Reference: 'RFC5988' is defined on line 1377, but no explicit reference was found in the text == Unused Reference: 'RFC6570' is defined on line 1379, but no explicit reference was found in the text == Unused Reference: 'RFC7386' is defined on line 1385, 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) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7386 (Obsoleted by RFC 7396) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 9 errors (**), 0 flaws (~~), 13 warnings (==), 9 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 P. Eckersley 5 Expires: July 28, 2015 S. Schoen 6 EFF 7 A. Halderman 8 J. Kasten 9 University of Michigan 10 January 28, 2015 12 Automatic Certificate Management Environment (ACME) 13 draft-barnes-acme-01 15 Abstract 17 Certificates in the Web's X.509 PKI (PKIX) are used for a number of 18 purposes, the most significant of which is the authentication of 19 domain names. Thus, certificate authorities in the Web PKI are 20 trusted to verify that an applicant for a certificate legitimately 21 represents the domain name(s) in the certificate. Today, this 22 verification is done through a collection of ad hoc mechanisms. This 23 document describes a protocol that a certificate authority (CA) and 24 an applicant can use to automate the process of verification and 25 certificate issuance. The protocol also provides facilities for 26 other certificate management functions, such as certificate 27 revocation. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on July 28, 2015. 46 Copyright Notice 48 Copyright (c) 2014 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 64 2. Deployment Model and Operator Experience . . . . . . . . . . 3 65 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 4. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 6 67 5. Certificate Management . . . . . . . . . . . . . . . . . . . 8 68 5.1. Resources and Requests . . . . . . . . . . . . . . . . . 9 69 5.2. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 11 70 5.3. Registration . . . . . . . . . . . . . . . . . . . . . . 11 71 5.4. Authorization Resources . . . . . . . . . . . . . . . . . 13 72 5.5. Key Authorization . . . . . . . . . . . . . . . . . . . . 15 73 5.5.1. Recovery Tokens . . . . . . . . . . . . . . . . . . . 19 74 5.6. Certificate Issuance . . . . . . . . . . . . . . . . . . 20 75 5.7. Other possibilities . . . . . . . . . . . . . . . . . . . 30 76 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 77 7. Security Considerations . . . . . . . . . . . . . . . . . . . 31 78 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 31 79 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 80 9.1. Normative References . . . . . . . . . . . . . . . . . . 31 81 9.2. Informative References . . . . . . . . . . . . . . . . . 33 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33 84 1. Introduction 86 Certificates in the Web PKI are most commonly used to authenticate 87 domain names. Thus, certificate authorities in the Web PKI are 88 trusted to verify that an applicant for a certificate legitimately 89 represents the domain name(s) in the certificate. 91 Existing Web PKI certificate authorities tend to run on a set of ad 92 hoc protocols for certificate issuance and identity verification. A 93 typical user experience is something like: 95 o Generate a PKCS#10 [RFC2314] Certificate Signing Request (CSR). 97 o Cut-and-paste the CSR into a CA web page. 99 o Prove ownership of the domain by one of the following methods: 101 * Put a CA-provided challenge at a specific place on the web 102 server. 104 * Put a CA-provided challenge at a DNS location corresponding to 105 the target domain. 107 * Receive CA challenge at a (hopefully) administrator-controlled 108 e-mail address corresponding to the domain and then respond to 109 it on the CA's web page. 111 o Download the issued certificate and install it on their Web 112 Server. 114 With the exception of the CSR itself and the certificates that are 115 issued, these are all completely ad hoc procedures and are 116 accomplished by getting the human user to follow interactive natural- 117 language instructions from the CA rather than by machine-implemented 118 published protocols. In many cases, the instructions are difficult 119 to follow and cause significant confusion. Informal usability tests 120 by the authors indicate that webmasters often need 1-3 hours to 121 obtain and install a certificate for a domain. Even in the best 122 case, the lack of published, standardized mechanisms presents an 123 obstacle to the wide deployment of HTTPS and other PKIX-dependent 124 systems because it inhibits mechanization of tasks related to 125 certificate issuance, deployment, and revocation. 127 This document describes an extensible framework for automating the 128 issuance and domain validation procedure, thereby allowing servers 129 and infrastructural software to obtain certificates without user 130 interaction. Use of this protocol should radically simplify the 131 deployment of HTTPS and the practicality of PKIX authentication for 132 other TLS based protocols. 134 2. Deployment Model and Operator Experience 136 The major guiding use case for ACME is obtaining certificates for Web 137 sites (HTTPS [RFC2818]). In that case, the server is intended to 138 speak for one or more domains, and the process of certificate 139 issuance is intended to verify that the server actually speaks for 140 the domain. 142 Different types of certificates reflect different kinds of CA 143 verification of information about the certificate subject. "Domain 144 Validation" (DV) certificates are by far the most common type. For 145 DV validation, the CA merely verifies that the requester has 146 effective control of the web server and/or DNS server for the domain, 147 but does not explicitly attempt to verify their real-world identity. 148 (This is as opposed to "Organization Validation" (OV) and "Extended 149 Validation" (EV) certificates, where the process is intended to also 150 verify the real-world identity of the requester.) 152 DV certificate validation commonly checks claims about properties 153 related to control of a domain name - properties that can be observed 154 by the issuing authority in an interactive process that can be 155 conducted purely online. That means that under typical 156 circumstances, all steps in the request, verification, and issuance 157 process can be represented and performed by Internet protocols with 158 no out-of-band human intervention. 160 When an operator deploys a current HTTPS server, it generally prompts 161 him to generate a self-signed certificate. When an operator deploys 162 an ACME-compatible web server, the experience would be something like 163 this: 165 o The ACME client prompts the operator for the intended domain 166 name(s) that the web server is to stand for. 168 o The ACME client presents the operator with a list of CAs from 169 which it could get a certificate. 170 (This list will change over time based on the capabilities of CAs 171 and updates to ACME configuration.) The ACME client might prompt 172 the operator for payment information at this point. 174 o The operator selects a CA. 176 o In the background, the ACME client contacts the CA and requests 177 that a certificate be issued for the intended domain name(s). 179 o Once the CA is satisfied, the certificate is issued and the ACME 180 client automatically downloads and installs it, potentially 181 notifying the operator via e-mail, SMS, etc. 183 o The ACME client periodically contacts the CA to get updated 184 certificates, stapled OCSP responses, or whatever else would be 185 required to keep the server functional and its credentials up-to- 186 date. 188 The overall idea is that it's nearly as easy to deploy with a CA- 189 issued certificate as a self-signed certificate, and that once the 190 operator has done so, the process is self-sustaining with minimal 191 manual intervention. Close integration of ACME with HTTPS servers, 192 for example, can allow the immediate and automated deployment of 193 certificates as they are issued, optionally sparing the human 194 administrator from additional configuration work. 196 3. Terminology 198 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 199 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 200 document are to be interpreted as described in RFC 2119 [RFC2119]. 202 The two main roles in ACME are "client" and "server". The ACME 203 client uses the protocol to request certificate management actions, 204 such as issuance or revocation. An ACME client therefore typically 205 runs on a web server, mail server, or some other server system which 206 requires valid TLS certificates. The ACME server runs at a 207 certificate authority, and responds to client requests, performing 208 the requested actions if the client is authorized. 210 For simplicity, in the HTTPS transactions used by ACME, the ACME 211 client is the HTTPS client and the ACME server is the HTTPS server. 213 In the discussion below, we will refer to three different types of 214 keys / key pairs: 216 Subject Public Key: A public key to be included in a certificate. 218 Account Key Pair: A key pair for which the ACME server considers the 219 holder of the private key authorized to manage certificates for a 220 given identifier. The same key pair may be authorized for 221 multiple identifiers. 223 Recovery Token: A secret value that can be used to demonstrate prior 224 authorization for an identifier, in a situation where all Subject 225 Private Keys and Account Keys are lost. 227 ACME messaging is based on HTTPS [RFC2818] and JSON [RFC7159]. Since 228 JSON is a text-based format, binary fields are Base64-encoded. For 229 Base64 encoding, we use the variant defined in 230 [I-D.ietf-jose-json-web-signature]. The important features of this 231 encoding are (1) that it uses the URL-safe character set, and (2) 232 that "=" padding characters are stripped. 234 Some HTTPS bodies in ACME are authenticated and integrity-protected 235 by being encapsulated in a JSON Web Signature (JWS) object 236 [I-D.ietf-jose-json-web-signature]. ACME uses a profile of JWS, with 237 the following restrictions: 239 o The JWS MUST use the JSON or Flattened JSON Serialization 241 o If the JWS is in the JSON Serialization, it MUST NOT include more 242 than one signature in the "signatures" array 244 o The JWS Header MUST include "alg" and "jwk" fields 246 4. Protocol Overview 248 ACME allows a client to request certificate management actions using 249 a set of JSON messages carried over HTTPS. In some ways, ACME 250 functions much like a traditional CA, in which a user creates an 251 account, adds identifiers to that account (proving control of the 252 domains), and requests certificate issuance for those domains while 253 logged in to the account. 255 In ACME, the account is represented by a account key pair. The "add 256 a domain" function is accomplished by authorizing the key pair for a 257 given domain. Certificate issuance and revocation are authorized by 258 a signature with the key pair. 260 The first phase of ACME is for the client to register with the ACME 261 server. The client generates an asymmetric key pair and associates 262 this key pair with a set of contact information by signing the 263 contact information. The server acknowledges the registration by 264 replying with a recovery token that the client can provide later to 265 associate a new account key pair in the event that the first account 266 key pair is lost. 268 Client Server 270 Contact Information 271 Signature -------> 273 <------- Recovery Token 275 Before a client can issue certificates, it must establish an 276 authorization with the server for an account key pair to act for the 277 identifier(s) that it wishes to include in the certificate. To do 278 this, the client must demonstrate to the server both (1) that it 279 holds the private key of the account key pair, and (2) that it has 280 authority over the identifier being claimed. 282 Proof of possession of the account key is built into the ACME 283 protocol. All messages from the client to the server are signed by 284 the client, and the server verifies them using the public key of the 285 account key pair. 287 To verify that the client controls the identifier being claimed, the 288 server issues the client a set of challenges. Because there are many 289 different ways to validate possession of different types of 290 identifiers, the server will choose from an extensible set of 291 challenges that are appropriate for the identifier being claimed. 292 The client responds with a set of responses that tell the server 293 which challenges the client has completed. The server then validate 294 the challenges to check that the client has accomplished the 295 challenge. 297 For example, if the client requests a domain name, the server might 298 challenge the client to provision a record in the DNS under that 299 name, or to provision a file on a web server referenced by an A or 300 AAAA record under that name. The server would then query the DNS for 301 the record in question, or send an HTTP request for the file. If the 302 client provisioned the DNS or the web server as expected, then the 303 server considers the client authorized for the domain name. 305 Client Server 307 Identifier 308 Signature -------> 310 <------- Challenges 312 Responses 313 Signature -------> 315 <------- Updated Challenge 317 Poll -------> 319 <------- Authorization 321 Once the client has authorized an account key pair for an identifier, 322 it can use the key pair to authorize the issuance of certificates for 323 the identifier. To do this, the client sends a PKCS#10 Certificate 324 Signing Request (CSR) to the server (indicating the identifier(s) to 325 be included in the issued certificate), a set of links to any 326 required authorizations, and a signature over the CSR by the private 327 key of the account key pair. 329 If the server agrees to issue the certificate, then it creates the 330 certificate and provides it in its response. The certificate is 331 assigned a URI, which the client can use to fetch updated versions of 332 the certificate. 334 Client Server 336 CSR 337 Authorization URI(s) 338 Signature --------> 340 <-------- Certificate 342 To revoke a certificate, the client simply sends a revocation 343 request, signed with an authorized key pair, and the server indicates 344 whether the request has succeeded. 346 Client Server 348 Revocation request 349 Signature --------> 351 <-------- Result 353 Note that while ACME is defined with enough flexibility to handle 354 different types of identifiers in principle, the primary use case 355 addressed by this document is the case where domain names are used as 356 identifiers. For example, all of the identifier validation 357 challenges described in Section {identifier-validation-challenges} 358 below address validation of domain names. The use of ACME for other 359 protocols will require further specification, in order to describe 360 how these identifiers are encoded in the protocol, and what types of 361 validation challenges the server might require. 363 5. Certificate Management 365 In this section, we describe the certificate management functions 366 that ACME enables: 368 o Registration 370 o Key Authorization 372 o Certificate Issuance 374 o Certificate Revocation 376 Each of these functions is accomplished by the client sending a 377 sequence of HTTPS requests to the server, carrying JSON messages. 378 Each subsection below describes the message formats used by the 379 function, and the order in which messages are sent. 381 5.1. Resources and Requests 383 ACME is structured as a REST application with a few types of 384 resources: 386 o Registration resources, representing information about an account 387 key 389 o Authorization resources, representing an account key's 390 authorization to act for an identifier 392 o Challenge resources, representing a challenge to prove control of 393 an identifier 395 o Certificate resources, representing issued certificates 397 o A "new-registration" resource 399 o A "new-authorization" resource 401 o A "new-certificate" resource 403 In general, the intent is for authorization and certificate resources 404 to contain only public information, so that CAs may publish these 405 resoruces to document what certificates have been issued and how they 406 were authorized. Non-public information, such as contact 407 information, is stored in registration resources. 409 In order to accomplish ACME transactions, a client needs to have the 410 server's new-registration, new-authorization, and new-ceritificate 411 URIs; the remaining URIs are provided to the client as a result of 412 requests to these URIs. To simplify configuration, ACME uses the 413 "next" link relation to indicate URI to contact for the next step in 414 processing: From registration to authorization, and from 415 authorization to certificate issuance. In this way, a client need 416 only be configured with the registration URI. 418 The "up" link relation is used with challenge resources to indicate 419 the authorization resource to which a challenge belongs. It is also 420 used from certificate resources to indicate a resource from which the 421 client may fetch a chain of CA certificates that could be used to 422 validate the certificate in the original resource. 424 The following diagram illustrates the relations between resources on 425 an ACME server. The solid lines indicate link relations, and the 426 dotted lines correspond to relationships expressed in other ways, 427 e.g., the Location header in a 201 (Created) response. 429 "next" "next" 430 new-reg ---+----> new-authz ---+----> new-cert cert-chain 431 . | . | . ^ 432 . | . | . | "up" 433 V | V | V | 434 reg* ----+ authz -----+ cert-----------+ 435 . ^ 436 . | "up" 437 V | 438 challenge 440 The remainder of this section provides the details of how these 441 resources are structured and how the ACME protocol makes use of them. 443 All ACME requests with a non-empty body MUST encapsulate the body in 444 a JWS object, signed using the account key pair. The server MUST 445 verify the JWS before processing the request. (For readability, 446 however, the examples below omit this encapsulation.) Encapsulating 447 request bodies in JWS provides a simple authentication of requests by 448 way of key continuity. 450 Note that this implies that GET requests are not authenticated. 451 Servers MUST NOT respond to GET requests for resources that might be 452 considered sensitive. 454 The following table illustrates a typical sequence of requests 455 required to establish a new account with the server, prove control of 456 an identifier, issue a certificate, and fetch an updated certificate 457 some time after issuance. The "->" is a mnemonic for a Location 458 header pointing to a created resource. 460 +--------------------+----------------+--------------+ 461 | Action | Request | Response | 462 +--------------------+----------------+--------------+ 463 | Register | POST new-reg | 201 -> reg | 464 | | | | 465 | Request challenges | POST new-authz | 201 -> authz | 466 | | | | 467 | Answer challenges | POST challenge | 200 | 468 | | | | 469 | Poll for status | GET authz | 200 | 470 | | | | 471 | Request issuane | POST new-cert | 201 -> cert | 472 | | | | 473 | Check for new cert | GET cert | 200 | 474 +--------------------+----------------+--------------+ 476 5.2. Errors 478 Errors can be reported in ACME both at the HTTP layer and within ACME 479 payloads. ACME servers can return responses with an HTTP error 480 response codes (4XX or 5XX). For example: If the client submits a 481 request using a method not allowed in this document, then the server 482 MAY return status code 405 (Method Not Allowed). 484 When the server responds with an error status, it SHOULD provide 485 additional information using problem document 486 [I-D.ietf-appsawg-http-problem]. The "type", "detail", and 487 "instance" fields MUST be populated. To facilitate automatic 488 response to errors, this document defines the following standard 489 tokens for use in the "type" field (within the "urn:acme:" 490 namespace): 492 +----------------+--------------------------------------------------+ 493 | Code | Semantic | 494 +----------------+--------------------------------------------------+ 495 | malformed | The request message was malformed | 496 | | | 497 | unauthorized | The client lacks sufficient authorization | 498 | | | 499 | serverInternal | The server experienced an internal error | 500 | | | 501 | badCSR | The CSR is unacceptable (e.g., due to a short | 502 | | key) | 503 +----------------+--------------------------------------------------+ 505 Authorization and challenge objects can also contain error 506 information to indicate why the server was unable to validate 507 authorization. 509 TODO: Flesh out errors and syntax for them 511 5.3. Registration 513 An ACME registration resource represents a set of metadata associated 514 to an account key pair, most importantly contact information and a 515 recovery token. Registration resources have the following structure: 517 key (required, dictionary): The public key of the account key pair, 518 encoded as a JSON Web Key object [I-D.ietf-jose-json-web-key]. 520 contact (optional, array of string): An array of URIs that the 521 server can use to contact the client for issues related to this 522 authorization. For example, the server may wish to notify the 523 client about server-initiated revocation, or check with the client 524 on future authorizations (see the "recoveryContact" challenge 525 type). 527 recoveryToken (optional, string): An opaque token that the client 528 can present to demonstrate that it participated in a prior 529 authorization transaction. 531 A client creates a new account with the server by sending a POST 532 request to the server's new-registration URI. The body of the 533 request is a registration object containing only the "contact" field. 535 POST /acme/new-registration HTTP/1.1 536 Host: example.com 538 { 539 "contact": [ 540 "mailto:cert-admin@example.com", 541 "tel:+12025551212" 542 ], 543 } 544 /* Signed as JWS */ 546 The server MUST ignore any values provided in the "key" or 547 "recoveryToken" fields, as well as any other fields that it does not 548 recognize. If new fields are specified in the future, the 549 specification of those fields MUST describe whether they may be 550 provided by the client. 552 The server creates a registration object with the included contact 553 information. The "key" element of the registration is set to the 554 public key used to verify the JWS (i.e., the "jwk" element of the JWS 555 header). The server also provides a random recovery token. The 556 server returns this registration object in a 201 (Created) response, 557 with the registration URI in a Location header field. The server may 558 also indicate its new-authorization URI using the "next" link 559 relation. 561 HTTP/1.1 201 Created 562 Content-Type: application/json 563 Location: https://example.com/reg/asdf 564 Link: ;rel="next" 566 { 567 "key": { /* JWK from JWS header */ }, 569 "contact": [ 570 "mailto:cert-admin@example.com", 571 "tel:+12025551212" 572 ], 574 "recoveryToken": "uV2Aph7-sghuCcFVmvsiZw" 575 } 577 If the client wishes to update this information in the future, it 578 sends a POST request with updated information to the registration 579 URI. The server MUST ignore any updates to the "key" or 580 "recoveryToken" fields, and MUST verify that the request is signed 581 with the private key corresponding to the "key" field of the request 582 before updating the registration. 584 Servers SHOULD NOT respond to GET requests for registration 585 resources, since these requests not authenticated. 587 5.4. Authorization Resources 589 An ACME authorization resource represents server's authorization for 590 an account key pair to represent an identifier. In addition to a 591 public key and identifier, an authorization includes several metadata 592 fields, such as the status of the authorization (e.g., "pending", 593 "valid", or "revoked") and which challenges were used to validate 594 possession of the identifier. 596 The structure of an ACME authorization resource is as follows: 598 identifier (required, dictionary of string): The identifier that the 599 account key is authorized to represent 601 type (required, string): The type of identifier. 603 value (required, string): The identifier itself. 605 key (required, dictionary): The public key of the account key pair, 606 encoded as a JSON Web Key object [I-D.ietf-jose-json-web-key]. 608 status (optional, string): The status of this authorization. 609 Possible values are: "pending", "valid", and "invalid". If this 610 field is missing, then the default value is "pending". 612 expires (optional, string): The date after which the server will 613 consider this authorization invalid, encoded in the format 614 specified in RFC 3339 [RFC3339]. 616 challenges (required, dictionary): The challenges that the client 617 needs to fulfill in order to prove possession of the identifier 618 (for pending authorizations). For final authorizations, the 619 challenges that were used. Each key in the dictionary is a type 620 of challenge, and the value is a dictionary with parameters 621 required to validate the challenge, as specified in Section 622 {identifier-validation-challenges}. 624 combinations (optional, array of arrays of integers): A collection 625 of sets of challenges, each of which would be sufficient to prove 626 possession of the identifier. Clients complete a set of 627 challenges that that covers at least one set in this array. 628 Challenges are identified by their indices in the challenges 629 array. If no "combinations" element is included in an 630 authorization object, the client completes all challenges. 632 The only type of identifier defined by this specification is a fully- 633 qualified domain name (type: "dns"). The value of the identifier 634 MUST be the ASCII representation of the domain name. 636 { 637 "status": "valid", 638 "expires": "2015-03-01", 640 "identifier": { 641 "type": "domain", 642 "value": "example.org" 643 }, 645 "key": { /* JWK */ }, 647 "challenges": [ 648 "simpleHttps": { 649 "status": "valid", 650 "validated": "2014-12-01T12:05Z", 651 "token": "IlirfxKKXAsHtmzK29Pj8A" 652 "path": "Hf5GrX4Q7EBax9hc2jJnfw" 653 }, 654 "recoveryToken": { 655 "status": "valid", 656 "validated": "2014-12-01T12:07Z", 657 "token": "23029d88d9e123e" 658 } 659 ], 660 } 662 5.5. Key Authorization 664 The key authorization process establishes the authorization of an 665 account key pair to manage certificates for a given identifier. This 666 process must assure the server of two things: First, that the client 667 controls the private key of the key pair, and second, that the client 668 holds the identifier in question. This process may be repeated to 669 associate multiple identifiers to a key pair (e.g., to request 670 certificates with multiple identifiers), or to associate multiple key 671 pairs with an identifier (e.g., to allow multiple entities to manage 672 certificates). 674 As illustrated by the figure in the overview section above, the 675 authorization process proceeds in two phases. The client first 676 requests a new authorization, and then the server issues challenges 677 that the client responds to. 679 To begin the key authorization process, the client sends a POST 680 request to the server's new-authorization resource. The body of the 681 POST request MUST contain a JWS object, whose payload is a partial 682 authorization object. This JWS object MUST contain only the 683 "identifier" field, so that the server knows what identifier is being 684 authorized. The client MAY provide contact information in the 685 "contact" field in this or any subsequent request. 687 POST /acme/new-authorization HTTP/1.1 688 Host: example.com 690 { 691 "identifier": { 692 "type": "domain", 693 "value": "example.org" 694 } 695 } 696 /* Signed as JWS */ 698 Before processing the authorization further, the server SHOULD 699 determine whether it is willing to issue certificates for the 700 identifier. For example, the server should check that the identifier 701 is of a supported type. Servers might also check names against a 702 blacklist of known high-value identifiers. If the server is 703 unwilling to issue for the identifier, it SHOULD return a 403 704 (Forbidden) error, with a problem document describing the reason for 705 the rejection. 707 If the server is willing to proceed, it builds a pending 708 authorization object from the initial authorization object submitted 709 by the client. 711 o "identifier" the identifier submitted by the client. 713 o "key": the key used to verify the client's JWS request (i.e., the 714 contents of the "jwk" field in the JWS header) 716 o "status": SHOULD be "pending" (MAY be omitted) 718 o "challenges" and "combinations": As selected by the server's 719 policy for this identifier 721 o The "expires" field MUST be absent. 723 The server allocates a new URI for this authorization, and returns a 724 201 (Created) response, with the authorization URI in a Location 725 header field, and the JSON authorization object in the body. 727 HTTP/1.1 201 Created 728 Content-Type: application/json 729 Location: https://example.com/authz/asdf 730 Link: ;rel="next" 732 { 733 "status": "pending", 735 "identifier": { 736 "type": "domain", 737 "value": "example.org" 738 }, 740 "key": { /* JWK from JWS header */ }, 742 "challenges": [ 743 { 744 "type": "simpleHttps", 745 "uri": "https://example.com/authz/asdf/0", 746 "token": "IlirfxKKXAsHtmzK29Pj8A" 747 }, 748 { 749 "type": "dns", 750 "uri": "https://example.com/authz/asdf/1" 751 "token": "DGyRejmCefe7v4NfDGDKfA" 752 }, 753 { 754 "type": "recoveryToken", 755 "uri": "https://example.com/authz/asdf/2" 756 } 757 }, 759 "combinations": [ 760 [0, 2], 761 [1, 2] 762 ] 763 } 765 The client needs to respond with information to complete the 766 challenges. To do this, the client updates the authorization object 767 received from the server by filling in any required information in 768 the elements of the "challenges" dictionary. For example, if the 769 client wishes to complete the "simpleHttps" challenge, it needs to 770 provide the "path" component. (This is also the stage where the 771 client should perform any actions required by the challenge.) 772 The client sends these updates back to the server in the form of a 773 JSON object with the response fields required by the challenge type, 774 carried in a POST request to the challenge URI (not authorization URI 775 or the new-authorization URI). This allows the client to send 776 information only for challenges it is responding to. 778 For example, if the client were to respond to the "simpleHttps" 779 challenge in the above authorization, it would send the following 780 request: 782 POST /acme/authz/asdf/0 HTTP/1.1 783 Host: example.com 785 { 786 "path": "Hf5GrX4Q7EBax9hc2jJnfw" 787 } 788 /* Signed as JWS */ 790 The server updates the authorization document by updating its 791 representation of the challenge with the response fields provided by 792 the client. The server MUST ignore any fields in the response object 793 that are not specified as response fields for this type of challenge. 794 The server provides a 200 response including the updated challenge. 796 Presumably, the client's responses provide the server with enough 797 information to validate one or more challenges. The server is said 798 to "finalize" the authorization when it has completed all the 799 validations it is going to complete, and assigns the authorization a 800 status of "valid" or "invalid", corresponding to whether it considers 801 the account key authorized for the identifier. If the final state is 802 "valid", the server MUST add an "expires" field to the authorization. 803 When finalizing an authorization, the server MAY remove the 804 "combinations" field (if present), remove any unfulfilled challenges, 805 or add a "recoveryToken" field. 807 Usually, the validation process will take some time, so the client 808 will need to poll the authorization resource to see when it is 809 finalized. For challenges where the client can tell when the server 810 has validated the challenge (e.g., by seeing an HTTP or DNS request 811 from the server), the client SHOULD NOT begin polling until it has 812 seen the validation request from the server. 814 To check on the status of an authorization, the client sends a GET 815 request to the authorization URI, and the server responds with the 816 current authorization object. To provide some degree of control over 817 polling, the server MAY provide a Retry-After header field to 818 indicate how long it expect to take in finalizing the response. 820 GET /acme/authz/asdf HTTP/1.1 821 Host: example.com 823 HTTP/1.1 200 OK 825 { 826 "status": "valid", 827 "expires": "2015-03-01", 829 "identifier": { 830 "type": "domain", 831 "value": "example.org" 832 }, 834 "key": { /* JWK */ }, 836 "contact": [ 837 "mailto:cert-admin@example.com", 838 "tel:+12025551212" 839 ], 841 "challenges": [ 842 "simpleHttps": { 843 "status": "valid", 844 "validated": "2014-12-01T12:05Z", 845 "token": "IlirfxKKXAsHtmzK29Pj8A" 846 "path": "Hf5GrX4Q7EBax9hc2jJnfw" 847 }, 848 "recoveryToken": { 849 "status": "valid", 850 "validated": "2014-12-01T12:07Z", 851 "token": "23029d88d9e123e" 852 } 853 ], 854 } 856 5.5.1. Recovery Tokens 858 A recovery token is a fallback authentication mechanism. In the 859 event that a client loses all other state, including authorized key 860 pairs and key pairs bound to certificates, the client can use the 861 recovery token to prove that it was previously authorized for the 862 identifier in question. 864 This mechanism is necessary because once an ACME server has issued an 865 Authorization Key for a given identifier, that identifier enters a 866 higher-security state, at least with respect the ACME server. That 867 state exists to protect against attacks such as DNS hijacking and 868 router compromise which tend to inherently defeat all forms of Domain 869 Validation. So once a domain has begun using ACME, new DV-only 870 authorization will not be performed without proof of continuity via 871 possession of an Authorized Private Key or potentially a Subject 872 Private Key for that domain. 874 This higher state of security poses some risks. From time to time, 875 the administrators and owners of domains may lose access to keys they 876 have previously had issued or certified, including Authorized private 877 keys and Subject private keys. For instance, the disks on which this 878 key material is stored may suffer failures, or passphrases for these 879 keys may be forgotten. In some cases, the security measures that are 880 taken to protect this sensitive data may contribute to its loss. 882 Recovery Tokens and Recovery Challenges exist to provide a fallback 883 mechanism to restore the state of the domain to the server-side 884 administrative security state it was in prior to the use of ACME, 885 such that fresh Domain Validation is sufficient for reauthorization. 887 Recovery tokens are therefore only useful to an attacker who can also 888 perform Domain Validation against a target domain, and as a result 889 client administrators may choose to handle them with somewhat fewer 890 security precautions than Authorized and Subject private keys, 891 decreasing the risk of their loss. 893 Recovery tokens come in several types, including high-entropy 894 passcodes (which need to be safely preserved by the client admin) and 895 email addresses (which are inherently hard to lose, and which can be 896 used for verification, though they may be a little less secure). 898 Recovery tokens are employed in response to Recovery Challenges. 899 Such challenges will be available if the server has issued Recovery 900 Tokens for a given domain, and the combination of a Recovery 901 Challenge and a domain validation Challenge is a plausible 902 alternative to other challenge sets for domains that already have 903 extant Authorized keys. 905 5.6. Certificate Issuance 907 The holder of an authorized key pair for an identifier may use ACME 908 to request that a certificate be issued for that identifier. The 909 client makes this request by sending a POST request to the server's 910 new-certificate resource. The body of the POST is a JWS object whose 911 JSON payload contains a Certificate Signing Request (CSR) [RFC2986] 912 and set of authorization URIs. The CSR encodes the parameters of the 913 requested certificate; authority to issue is demonstrated by the JWS 914 signature and the linked authorizations. 916 csr (required, string): A CSR encoding the parameters for the 917 certificate being requested. The CSR is sent in base64-encoded 918 version the DER format. (Note: This field uses the same modified 919 base64-encoding rules used elsewhere in this document, so it is 920 different from PEM.) 922 authorizations (required, array of string): An array of URIs for 923 authorization resources. 925 POST /acme/new-cert HTTP/1.1 926 Host: example.com 927 Accept: application/pkix-cert 929 { 930 "csr": "5jNudRx6Ye4HzKEqT5...FS6aKdZeGsysoCo4H9P", 931 "authorizations": [ 932 "https://example.com/acme/authz/asdf" 933 ] 934 } 935 /* Signed as JWS */ 937 ~~~~~~~~~ 939 The CSR encodes the client's requests with regard to the content of the certificate to be issued. The CSR MUST contain at least one extensionRequest attribute {{RFC2985}} requesting a subjectAltName extension, containing the requested identifiers. 941 The values provided in the CSR are only a request, and are not guaranteed. The server or CA may alter any fields in the certificate before issuance. For example, the CA may remove identifiers that are not authorized for the key indicated in the "authorization" field. 943 If the CA decides to issue a certificate, then the server returns the certificate in a response with status code 201 (Created). The server MUST indicate a URL for this certificate in a Location header field. 945 The default format of the certificate is DER (application/pkix-cert). The client may request other formats by including an Accept header in its request. 947 The server can provide metadata about the certificate in HTTP headers. For example, the server can include a Link relation header field {{RFC5988}} with relation "up" to provide a certificate under which this certificate was issued. Or the server can include an Expires header as a hint to the client about when to re-query to refresh the certificate. (Of course, the real expiration of the certificate is controlled by the notAfter time in the certificate itself.) 949 HTTP/1.1 201 Created Content-Type: application/pkix-cert Link: 950 https://example.com/acme/ca-cert ;rel="up";title="issuer" Location: 951 https://example.com/acme/cert/asdf 953 [DER-encoded certificate] 955 ## Certificate Refresh 957 The certificate URL (provided in the Location header of the server's response) is used to refresh or revoke the certificate. To refresh the certificate, the client simply sends a GET request to the certificate URL. This allows the server to provide the client with updated certificates with the same content and different validity intervals, for as long as all of the authorization objects underlying the certificate are valid. 959 If a client sends a refresh request and the server is not willing to refresh the certificate, the server MUST respond with status code 403 (Forbidden). If the client still wishes to obtain a certificate, it can re-initiate the authorization process for any expired authorizations related to the certificate. 961 ## Certificate Revocation 963 To request that a certificate be revoked, the client sends a POST request to the certificate URL. The body of the POST is a JWS object whose JSON payload contains an indication when the client would like the certificate to be revoked: 965 revoke (required, string): 966 : The time at which the certificate should be revoked. The value of this field MUST be either the literal string "now", or a date in RFC 3339 format {{RFC3339}}. 968 authorizations (required, array of string): 969 : An array of URIs for authorization resources. 971 POST /acme/cert/asdf HTTP/1.1 Host: example.com 973 { "revoke": "now", "authorizations": [ 974 "https://example.com/acme/authz/asdf" ] } /* Signed as JWS */ 976 Before revoking a certificate, the server MUST verify that the account key pair used to sign the request is authorized to act for all of the identifier(s) in the certificate. The server MAY also accept a signature by the private key corresponding to the public key in the certificate. 978 If the revocation succeeds, the server responds with status code 200 (OK). If the revocation fails, the server returns an error. 980 HTTP/1.1 200 OK Content-Length: 0 982 -- or -- 984 HTTP/1.1 403 Forbidden Content-Type: application/problem+json 985 Content-Language: en 987 { "type": "urn:acme:error:unauthorized" "detail": "No authorization 988 provided for name example.net" "instance": "http://example.com/doc/ 989 unauthorized" } 991 # Identifier Validation Challenges 993 There are few types of identifier in the world for which there is a standardized mechanism to prove possession of a given identifier. In all practical cases, CAs rely on a variety of means to test whether an entity applying for a certificate with a given identifier actually controls that identifier. 995 To accommodate this reality, ACME includes an extensible challenge/response framework for identifier validation. This section describes an initial set of Challenge types. Each challenge must describe: 997 * Content of Challenge payloads (in Challenge messages) 998 * Content of Response payloads (in authorizationRequest messages) 999 * How the server uses the Challenge and Response to verify control of an identifier 1001 The only general requirement for Challenge and Response payloads is that they MUST be structured as a JSON object, and they MUST contain a parameter "type" that specifies the type of Challenge or Response encoded in the object. 1003 Different challenges allow the server to obtain proof of different aspects of control over an identifier. In some challenges, like Simple HTTPS and DVSNI, the client directly proves control of an identifier. In other challenges, such as Recovery or Proof of Possession, the client proves historical control of the identifier, by reference to a prior authorization transaction or certificate. 1005 The choice of which Challenges to offer to a client under which circumstances is a matter of server policy. A server may choose different sets of challenges depending on whether it has interacted with a domain before, and how. For example: 1007 | Domain status | Challenges typically sufficient for (re)Authorization | 1008 |:==============================================|:======================================================| 1009 | No known prior certificates or ACME usage | Domain Validation (DVSNI or Simple HTTPS) | 1010 | Existing valid certs, first use of ACME | DV + Proof of Possession of previous CA-signed key | 1011 | Ongoing ACME usage | PoP of previous Authorized key | 1012 | Ongoing ACME usage, lost Authorized key | DV + (Recovery or PoP of ACME-certified Subject key) | 1013 | ACME usage, all keys and recovery tokens lost | Recertification by another CA + PoP of that key | 1015 The identifier validation challenges described in this section all relate to validation of domain names. If ACME is extended in the future to support other types of identifier, there will need to be new Challenge types, and they will need to specify which types of identifier they apply to. 1017 ## Simple HTTPS 1019 With Simple HTTPS validation, the client in an ACME transaction proves its control over a domain name by proving that it can provision resources on an HTTPS server that responds for that domain name. The ACME server challenges the client to provision a file with a specific string as its contents. 1021 type (required, string): 1022 : The string "simpleHttps" 1024 token (required, string): 1025 : The value to be provisioned in the file. This value MUST have at least 128 bits of entropy, in order to prevent an attacker from guessing it. It MUST NOT contain any non-ASCII characters. 1027 { "type": "simpleHttps", "token": 1028 "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ+PCt92wr+oA" } 1030 A client responds to this Challenge by provisioning the nonce as a resource on the HTTPS server for the domain in question. The path at which the resource is provisioned is determined by the client, but MUST begin with ".well-known/acme-challenge/". The content type of the resource MUST be "text/plain". The client returns the part of the path coming after that prefix in its Response message. 1032 type (required, string): 1033 : The string "simpleHttps" 1035 path (required, string): 1036 : The string to be appended to the standard prefix ".well-known/acme-challenge" in order to form the path at which the nonce resource is provisioned. The result of concatenating the prefix with this value MUST match the "path" production in the standard URI format {{RFC3986}} 1037 { "type": "simpleHttps", "path": "6tbIMBC5Anhl5bOlWT5ZFA" } 1039 Given a Challenge/Response pair, the server verifies the client's control of the domain by verifying that the resource was provisioned as expected. 1041 1. Form a URI by populating the URI template "https://{domain}/.well-known/acme-challenge/{path}", where the domain field is set to the domain name being verified and the path field is the path provided in the challenge {{RFC6570}}. 1042 2. Verify that the resulting URI is well-formed. 1043 3. Dereference the URI using an HTTPS GET request. 1044 4. Verify that the certificate presented by the HTTPS server is a valid self-signed certificate, and contains the domain name being validated as well as the public key of the key pair being authorized. 1045 5. Verify that the Content-Type header of the response is either absent, or has the value "text/plain" 1046 6. Compare the entity body of the response with the nonce. This comparison MUST be performed in terms of Unicode code points, taking into account the encodings of the stored nonce and the body of the request. 1048 If the GET request succeeds and the entity body is equal to the nonce, then the validation is successful. If the request fails, or the body does not match the nonce, then it has failed. 1050 ## Domain Validation with Server Name Indication 1052 The Domain Validation with Server Name Indication (DVSNI) validation method aims to ensure that the ACME client has administrative access to the web server at the domain name being validated, and possession of the private key being authorized. The ACME server verifies that the operator can reconfigure the web server by having the client create a new self-signed challenge certificate and respond to TLS connections from the ACME server with it. 1054 The challenge proceeds as follows: The ACME server sends the client a random value R and a nonce used to identify the transaction. The client responds with another random value S. The server initiates a TLS connection on port 443 to a host with the domain name being validated. In the handshake, the ACME server sets the Server Name Indication extension set to "\.acme.invalid". The TLS server (i.e., the ACME client) should respond with a valid self-signed certificate containing both the domain name being validated and the domain name "\.acme.invalid", where Z = SHA-256(R || S). 1056 The ACME server's Challenge provides its random value R, and a random nonce used to identify the transaction: 1058 type (required, string): 1059 : The string "dvsni" 1061 r (required, string): 1062 : A random 32-byte octet, base64-encoded 1064 nonce (required, string): 1065 : A random 16-byte octet string, hex-encoded (so that it can be used as a DNS label) 1067 { "type": "dvsni", "r": 1068 "Tyq0La3slT7tqQ0wlOiXnCY2vyez7Zo5blgPJ1xt5xI", "nonce": 1069 "a82d5ff8ef740d12881f6d3c2277ab2e" } 1071 The ACME server MAY re-use nonce values, but SHOULD periodically refresh them. ACME clients MUST NOT rely on nonce values being stable over time. 1073 The client responds to this Challenge by configuring a TLS server on port 443 of a server with the domain name being validated: 1075 1. Decode the server's random value R 1076 2. Generate a random 32-byte octet string S 1077 3. Compute Z = SHA-256(R || S) (where || denotes concatenation of octet strings) 1078 4. Generate a self-signed certificate with a subjectAltName extension containing two dNSName values: 1079 1. The domain name being validated 1080 2. A name formed by hex-encoding Z and appending the suffix ".acme.invalid" 1081 5. Compute a nonce domain name by appending the suffix ".acme.invalid" to the nonce provided by the server. 1082 6. Configure the TLS server such that when a client presents the nonce domain name in the SNI field, the server presents the generated certificate. 1084 The client's response provides its random value S: 1086 type (required, string): 1087 : The string "dvsni" 1089 s (required, string): 1090 : A random 32-byte secret octet string, base64-encoded 1092 { "type": "dvsni", "s": "9dbjsl3gTAtOnEtKFEmhS6Mj-ajNjDcOmRkp3Lfzm3c" 1093 } 1095 Given a Challenge/Response pair, the ACME server verifies the client's control of the domain by verifying that the TLS server was configured as expected: 1097 1. Compute the value Z = SHA-256(R || S) 1098 2. Open a TLS connection to the domain name being validated on port 443, presenting the value "\.acme.invalid" in the SNI field. 1099 3. Verify the following properties of the certificate provided by the TLS server: 1100 * It is a valid self-signed certificate 1101 * The public key is the public key for the key pair being authorized 1102 * It contains the domain name being validated as a subjectAltName 1103 * It contains a subjectAltName matching the hex-encoding of Z, with the suffix ".acme.invalid" 1105 It is RECOMMENDED that the ACME server verify the challenge certificate using multi-path probing techniques to reduce the risk of DNS hijacking attacks. 1107 If the server presents a certificate matching all of the above criteria, then the validation is successful. Otherwise, the validation fails. 1109 ## Recovery Contact 1111 A server may issue a recovery contact challenge to verify that the client is the same as the entity that previously requested authorization, using contact information provided by the client in a prior authorizationRequest message. 1113 The server's message to the client may request action in-band or out-of-band to ACME. The server can provide a token in the message that the client provides in its response. Or the server could provide some out-of-band response channel in its message, such as a URL to click in an email. 1115 type (required, string): 1116 : The string "recoveryContact" 1118 activationURL (optional, string): 1119 : A URL the client can visit to cause a recovery message to be sent to client's contact address. 1121 successURL (optional, string): 1122 : A URL the client may poll to determine if the user has successfully clicked a link or completed other tasks specified by the recovery message. This URL will return a 200 success code if the required tasks have been completed. The client SHOULD NOT poll the URL more than once every three seconds. 1124 contact (optional, string) 1125 : A full or partly obfuscated version of the contact URI that the server will use to contact the client. Client software may present this to a user in order to suggest what contact point the user should check (e.g., an email address). 1127 { "type": "recoveryContact", "activationURL" : 1128 "https://example.ca/sendrecovery/a5bd99383fb0", "successURL" : 1129 "https://example.ca/confirmrecovery/bb1b9928932", "contact" : 1130 "c******n@example.com" } 1132 type (required, string): 1133 : The string "recoveryContact" 1135 token (optional, string): 1136 : If the user transferred a token from a contact email or call into the client software, the client sends it here. If it the client has received a 200 success response while polling the RecoveryContact Challenge's successURL, this field SHOULD be omitted. 1138 { "type": "recoveryContact", "token": "23029d88d9e123e" } 1140 If the value of the "token" field matches the value provided in the out-of-band message to the client, or if the client has completed the required out-of-band action, then the validation succeeds. Otherwise, the validation fails. 1142 ## Recovery Token 1144 A recovery token is a simple way for the server to verify that the client was previously authorized for a domain. The client simply provides the recovery token that was provided in the authorize message. 1146 type (required, string): 1147 : The string "recoveryToken" 1149 { "type": "recoveryToken" } 1151 The response to a recovery token challenge is simple; the client sends the requested token that it was provided by the server earlier. 1153 type (required, string): 1154 : The string "recoveryToken" 1156 token (optional, string): 1157 : The recovery token provided by the server. 1159 { "type": "recoveryToken", "token": "23029d88d9e123e" } 1161 If the value of the "token" field matches a recovery token that the server previously provided for this domain, then the validation succeeds. Otherwise, the validation fails. 1163 ## Proof of Possession of a Prior Key 1165 The Proof of Possession challenge verifies that a client possesses a private key corresponding to a server-specified public key, as demonstrated by its ability to correctly sign server-provided data with that key. 1167 This method is useful if a server policy calls for issuing a certificate only to an entity that already possesses the subject private key of a particular prior related certificate (perhaps issued by a different CA). It may also help enable other kinds of server policy that are related to authenticating a client's identity using digital signatures. 1169 This challenge proceeds in much the same way as the proof of possession of the authorized key pair in the main ACME flow (challenge + authorizationRequest). The server provides a nonce and the client signs over the nonce. The main difference is that rather than signing with the private key of the key pair being authorized, the client signs with a private key specified by the server. The server can specify which key pair(s) are acceptable directly (by indicating a public key), or by asking for the key corresponding to a certificate. 1171 The server provides the following fields as part of the challenge: 1173 type (required, string): 1174 : The string "proofOfPossession" 1176 alg (required, string): 1177 : A token indicating the cryptographic algorithm that should be used by the client to compute the signature {{I-D.ietf-jose-json-web-algorithms}}. (MAC algorithms such as "HS*" MUST NOT be used.) The client MUST verify that this algorithm is supported for the indicated key before responding to this challenge. 1179 nonce (required, string): 1180 : A random 16-byte octet string, base64-encoded 1182 hints (required, object): 1183 : A JSON object that contains various clues for the client about what the requested key is, such that the client can find it. Entries in the hints object may include: 1185 jwk (required, object): 1186 : A JSON Web Key object describing the public key whose corresponding private key should be used to generate the signature {{I-D.ietf-jose-json-web-key}} 1188 certFingerprints (optional, array): 1189 : An array of certificate fingerprints, hex-encoded SHA1 hashes of DER-encoded certificates that are known to contain this key 1191 certs (optional, array): 1192 : An array of certificates, in PEM encoding, that contain acceptable public keys. 1194 subjectKeyIdentifiers (optional, array): 1195 : An array of hex-encoded Subject Key Identifiers (SKIDs) from certificate(s) that contain the key. Because of divergences in the way that SKIDs are calculated {{RFC5280}}, there may conceivably be more than one of these. 1197 serialNumbers (optional, array of numbers): 1198 : An array of serial numbers of certificates that are known to contain the requested key 1200 issuers (optional, array): 1201 : An array of X.509 Distinguished Names {{RFC5280}} of CAs that have been observed to issue certificates for this key, in text form {{RFC4514}} 1203 authorizedFor (optional, array): 1204 : An array of domain names, if any, for which this server regards the key as an ACME Authorized key. 1206 { "type": "proofOfPossession", "alg": "RS256", "nonce": 1207 "eET5udtV7aoX8Xl8gYiZIA", "hints" : { "jwk": { "kty": "RSA", "e": 1208 "AQAB", "n": "KxITJ0rNlfDMAtfDr8eAw...fSSoehDFNZKQKzTZPtQ" }, 1209 "certFingerprints": [ "93416768eb85e33adc4277f4c9acd63e7418fcfe", 1210 "16d95b7b63f1972b980b14c20291f3c0d1855d95", 1211 "48b46570d9fc6358108af43ad1649484def0debf" ], 1212 "subjectKeyIdentifiers": [ "d0083162dcc4c8a23ecb8aecbd86120e56fd24e5" 1213 ], "serialNumbers": [34234239832, 23993939911, 17], "issuers": [ 1214 "C=US, O=SuperT LLC, CN=SuperTrustworthy Public CA", 1215 "O=LessTrustworthy CA Inc, CN=LessTrustworthy But StillSecure" ], 1216 "authorizedFor": ["www.example.com", "example.net"] } } 1218 In this case the server is challenging the client to prove its control over the private key that corresponds to the public key specified in the jwk object. The signing algorithm is specified by the alg field. The nonce value is used by the server to identify this challenge and is also used, also with a client-provided signature nonce, as part of the signature input. 1220 signature-input = signature-nonce || server-nonce 1222 The client's response includes the server-provided nonce, together with a signature over that nonce by one of the private keys requested by the server. 1224 type (required, string): 1225 : The string "proofOfPossession" 1227 nonce (required, string): 1228 : The server nonce that the server previously associated with this challenge 1230 signature (required, object): 1231 : The ACME signature computed over the signature-input using the server-specified algorithm 1233 { "type": "proofOfPossession", "nonce": "eET5udtV7aoX8Xl8gYiZIA", 1234 "signature": { "alg": "RS256", "nonce": "eET5udtV7aoX8Xl8gYiZIA", 1235 "sig": "KxITJ0rNlfDMAtfDr8eAw...fSSoehDFNZKQKzTZPtQ", "jwk": { "kty": 1236 "RSA", "e": "AQAB", "n": 1237 "KxITJ0rNlfDMAtfDr8eAw...fSSoehDFNZKQKzTZPtQ" } } } 1239 Note that just as in the authorizationRequest message, there are two nonces here, once provided by the client (inside the signature object) and one provided by the server in its challenge (outside the signature object). The signature covers the concatenation of these two nonces (as specified in the signature-input above). 1241 If the server is able to validate the signature and confirm that the jwk and alg objects are unchanged from the original challenge, the server can conclude that the client is in control of the private key that corresponds to the specified public key. The server can use this evidence in support of its authorization and certificate issuance policies. 1243 ## DNS 1245 When the identifier being validated is a domain name, the client can prove control of that domain by provisioning records under it. The DNS challenge requires the client to provision a TXT record containing a validation token under a specific validation domain name. 1247 type (required, string): 1248 : The string "dns" 1250 token (required, string): 1251 : An ASCII string that is to be provisioned in the TXT record. This string SHOULD be randomly generated, with at least 128 bits of entropy (e.g., a hex-encoded random octet string). 1253 { "type": "dns", "token": "17817c66b60ce2e4012dfad92657527a" } 1255 In response to this challenge, the client first MUST verify that the token contains only ASCII characters. If so, the client constructs the validation domain name by appending the label "_acme-challenge" to the domain name being validated. For example, if the domain name being validated is "example.com", then the client would provision the following DNS record: 1257 _acme-challenge.example.com. IN TXT 1258 "17817c66b60ce2e4012dfad92657527a" 1260 The response to a DNS challenge is simply an acknowledgement that the relevant record has been provisioned. 1262 type (required, string): 1263 : The string "dns" 1265 { "type": "dns" } 1267 ~~~~~~~~~~ 1269 To validate a DNS challenge, the server queries for TXT records under 1270 the validation domain name. If it receives a record whose contents 1271 match the token in the challenge, then the validation succeeds. 1272 Otherwise, the validation fails. 1274 5.7. Other possibilities 1276 For future work: 1278 o Email 1280 o DNSSEC 1282 o WHOIS 1284 6. IANA Considerations 1286 TODO 1288 o Register .well-known path 1290 o Create identifier validation method registry 1292 o Registries of syntax tokens, e.g., message types / error types? 1294 7. Security Considerations 1296 TODO 1298 o General authorization story 1300 o PoP nonce entropy 1302 o ToC/ToU; duration of key authorization 1304 o Clients need to protect recovery key 1306 o CA needs to perform a very wide range of issuance policy 1307 enforcement and sanity-check steps 1309 o Parser safety (for JSON, JWK, ASN.1, and any other formats that 1310 can be parsed by the ACME server) 1312 8. Acknowledgements 1314 This document draws on many concepts established by Eric Rescorla's 1315 "Automated Certificate Issuance Protocol" draft. Martin Thomson 1316 provided helpful guidance in the use of HTTP. 1318 9. References 1320 9.1. Normative References 1322 [I-D.ietf-appsawg-http-problem] 1323 Nottingham, M. and E. Wilde, "Problem Details for HTTP 1324 APIs", draft-ietf-appsawg-http-problem-00 (work in 1325 progress), January 2015. 1327 [I-D.ietf-jose-json-web-algorithms] 1328 Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- 1329 json-web-algorithms-40 (work in progress), January 2015. 1331 [I-D.ietf-jose-json-web-key] 1332 Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web- 1333 key-41 (work in progress), January 2015. 1335 [I-D.ietf-jose-json-web-signature] 1336 Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1337 Signature (JWS)", draft-ietf-jose-json-web-signature-41 1338 (work in progress), January 2015. 1340 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1341 Requirement Levels", BCP 14, RFC 2119, March 1997. 1343 [RFC2314] Kaliski, B., "PKCS #10: Certification Request Syntax 1344 Version 1.5", RFC 2314, March 1998. 1346 [RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object 1347 Classes and Attribute Types Version 2.0", RFC 2985, 1348 November 2000. 1350 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 1351 Request Syntax Specification Version 1.7", RFC 2986, 1352 November 2000. 1354 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 1355 Internet: Timestamps", RFC 3339, July 2002. 1357 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1358 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1359 3986, January 2005. 1361 [RFC4514] Zeilenga, K., "Lightweight Directory Access Protocol 1362 (LDAP): String Representation of Distinguished Names", RFC 1363 4514, June 2006. 1365 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1366 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1367 May 2008. 1369 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1370 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1372 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1373 Housley, R., and W. Polk, "Internet X.509 Public Key 1374 Infrastructure Certificate and Certificate Revocation List 1375 (CRL) Profile", RFC 5280, May 2008. 1377 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1379 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1380 and D. Orchard, "URI Template", RFC 6570, March 2012. 1382 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1383 Interchange Format", RFC 7159, March 2014. 1385 [RFC7386] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7386, 1386 October 2014. 1388 9.2. Informative References 1390 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1392 Authors' Addresses 1394 Richard Barnes 1395 Mozilla 1397 Email: rlb@ipv.sx 1399 Peter Eckersley 1400 EFF 1402 Email: pde@eff.org 1404 Seth Schoen 1405 EFF 1407 Email: schoen@eff.org 1409 Alex Halderman 1410 University of Michigan 1412 Email: jhalderm@eecs.umich.edu 1414 James Kasten 1415 University of Michigan 1417 Email: jdkasten@umich.edu