idnits 2.17.1 draft-barnes-acme-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 28, 2015) is 3375 days in the past. Is this intentional? 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 652 -- Looks like a reference, but probably isn't: '2' on line 652 -- Looks like a reference, but probably isn't: '1' on line 652 -- Looks like a reference, but probably isn't: '34234239832' on line 1353 -- Looks like a reference, but probably isn't: '23993939911' on line 1353 -- Looks like a reference, but probably isn't: '17' on line 1353 == Unused Reference: 'RFC5226' is defined on line 1530, but no explicit reference was found in the text ** 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 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 7 errors (**), 0 flaws (~~), 2 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 E. Rescorla 4 Intended status: Standards Track Mozilla 5 Expires: July 28, 2015 P. Eckersley 6 S. Schoen 7 EFF 8 A. Halderman 9 J. Kasten 10 University of Michigan 11 January 28, 2015 13 Automatic Certificate Management Environment (ACME) 14 draft-barnes-acme-00 16 Abstract 18 Certificates in the Web's X.509 PKI (PKIX) are used for a number of 19 purposes, the most significant of which is the authentication of 20 domain names. Thus, certificate authorities in the Web PKI are 21 trusted to verify that an applicant for a certificate legitimately 22 represents the domain name(s) in the certificate. Today, this 23 verification is done through a collection of ad hoc mechanisms. This 24 document describes a protocol that a certificate authority (CA) and 25 an applicant can use to automate the process of verification and 26 certificate issuance. The protocol also provides facilities for 27 other certificate management functions, such as certificate 28 revocation. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on July 28, 2015. 47 Copyright Notice 49 Copyright (c) 2014 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 65 2. Deployment Model and Operator Experience . . . . . . . . . . 4 66 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 67 4. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 6 68 5. Certificate Management . . . . . . . . . . . . . . . . . . . 8 69 5.1. General Request/Response Lifecycle . . . . . . . . . . . 9 70 5.2. Signatures . . . . . . . . . . . . . . . . . . . . . . . 12 71 5.3. Key Authorization . . . . . . . . . . . . . . . . . . . . 13 72 5.3.1. Recovery Tokens . . . . . . . . . . . . . . . . . . . 18 73 5.4. Certificate Issuance . . . . . . . . . . . . . . . . . . 19 74 5.5. Certificate Revocation . . . . . . . . . . . . . . . . . 21 75 6. Identifier Validation Challenges . . . . . . . . . . . . . . 22 76 6.1. Simple HTTPS . . . . . . . . . . . . . . . . . . . . . . 24 77 6.2. Domain Validation with Server Name Indication . . . . . . 25 78 6.3. Recovery Contact . . . . . . . . . . . . . . . . . . . . 27 79 6.4. Recovery Token . . . . . . . . . . . . . . . . . . . . . 29 80 6.5. Proof of Possession of a Prior Key . . . . . . . . . . . 29 81 6.6. DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 82 6.7. Other possibilities . . . . . . . . . . . . . . . . . . . 33 83 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 84 8. Security Considerations . . . . . . . . . . . . . . . . . . . 34 85 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 86 9.1. Normative References . . . . . . . . . . . . . . . . . . 34 87 9.2. Informative References . . . . . . . . . . . . . . . . . 35 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 90 1. Introduction 92 Certificates in the Web PKI are most commonly used to authenticate 93 domain names. Thus, certificate authorities in the Web PKI are 94 trusted to verify that an applicant for a certificate legitimately 95 represents the domain name(s) in the certificate. 97 Existing Web PKI certificate authorities tend to run on a set of ad 98 hoc protocols for certificate issuance and identity verification. A 99 typical user experience is something like: 101 o Generate a PKCS#10 [RFC2314] Certificate Signing Request (CSR). 103 o Cut-and-paste the CSR into a CA web page. 105 o Prove ownership of the domain by one of the following methods: 107 * Put a CA-provided challenge at a specific place on the web 108 server. 110 * Put a CA-provided challenge at a DNS location corresponding to 111 the target domain. 113 * Receive CA challenge at a (hopefully) administrator-controlled 114 e-mail address corresponding to the domain and then respond to 115 it on the CA's web page. 117 o Download the issued certificate and install it on their Web 118 Server. 120 With the exception of the CSR itself and the certificates that are 121 issued, these are all completely ad hoc procedures and are 122 accomplished by getting the human user to follow interactive natural- 123 language instructions from the CA rather than by machine-implemented 124 published protocols. In many cases, the instructions are difficult 125 to follow and cause significant confusion. Informal usability tests 126 by the authors indicate that webmasters often need 1-3 hours to 127 obtain and install a certificate for a domain. Even in the best 128 case, the lack of published, standardized mechanisms presents an 129 obstacle to the wide deployment of HTTPS and other PKIX-dependent 130 systems because it inhibits mechanization of tasks related to 131 certificate issuance, deployment, and revocation. 133 This document describes an extensible framework for automating the 134 issuance and domain validation procedure, thereby allowing servers 135 and infrastructural software to obtain certificates without user 136 interaction. Use of this protocol should radically simplify the 137 deployment of HTTPS and the practicality of PKIX authentication for 138 other TLS based protocols. 140 2. Deployment Model and Operator Experience 142 The major guiding use case for ACME is obtaining certificates for Web 143 sites (HTTPS [RFC2818]). In that case, the server is intended to 144 speak for one or more domains, and the process of certificate 145 issuance is intended to verify that the server actually speaks for 146 the domain. 148 Different types of certificates reflect different kinds of CA 149 verification of information about the certificate subject. "Domain 150 Validation" (DV) certificates are by far the most common type. For 151 DV validation, the CA merely verifies that the requester has 152 effective control of the web server and/or DNS server for the domain, 153 but does not explicitly attempt to verify their real-world identity. 154 (This is as opposed to "Organization Validation" (OV) and "Extended 155 Validation" (EV) certificates, where the process is intended to also 156 verify the real-world identity of the requester.) 158 DV certificate validation commonly checks claims about properties 159 related to control of a domain name - properties that can be observed 160 by the issuing authority in an interactive process that can be 161 conducted purely online. That means that under typical 162 circumstances, all steps in the request, verification, and issuance 163 process can be represented and performed by Internet protocols with 164 no out-of-band human intervention. 166 When an operator deploys a current HTTPS server, it generally prompts 167 him to generate a self-signed certificate. When an operator deploys 168 an ACME-compatible web server, the experience would be something like 169 this: 171 o The ACME client prompts the operator for the intended domain 172 name(s) that the web server is to stand for. 174 o The ACME client presents the operator with a list of CAs from 175 which it could get a certificate. 176 (This list will change over time based on the capabilities of CAs 177 and updates to ACME configuration.) The ACME client might prompt 178 the operator for payment information at this point. 180 o The operator selects a CA. 182 o In the background, the ACME client contacts the CA and requests 183 that a certificate be issued for the intended domain name(s). 185 o Once the CA is satisfied, the certificate is issued and the ACME 186 client automatically downloads and installs it, potentially 187 notifying the operator via e-mail, SMS, etc. 189 o The ACME client periodically contacts the CA to get updated 190 certificates, stapled OCSP responses, or whatever else would be 191 required to keep the server functional and its credentials up-to- 192 date. 194 The overall idea is that it's nearly as easy to deploy with a CA- 195 issued certificate as a self-signed certificate, and that once the 196 operator has done so, the process is self-sustaining with minimal 197 manual intervention. Close integration of ACME with HTTPS servers, 198 for example, can allow the immediate and automated deployment of 199 certificates as they are issued, optionally sparing the human 200 administrator from additional configuration work. 202 3. Terminology 204 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 205 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 206 document are to be interpreted as described in RFC 2119 [RFC2119]. 208 The two main roles in ACME are "client" and "server". The ACME 209 client uses the protocol to request certificate management actions, 210 such as issuance or revocation. An ACME client therefore typically 211 runs on a web server, mail server, or some other server system which 212 requires valid TLS certificates. The ACME server runs at a 213 certificate authority, and responds to client requests, performing 214 the requested actions if the client is authorized. 216 For simplicity, in the HTTPS transactions used by ACME, the ACME 217 client is the HTTPS client and the ACME server is the HTTPS server. 219 In the discussion below, we will refer to three different types of 220 keys / key pairs: 222 Subject Public Key: A public key to be included in a certificate. 224 Authorized Key Pair: A key pair for which the ACME server considers 225 the holder of the private key authorized to manage certificates 226 for a given identifier. The same key pair may be authorized for 227 multiple identifiers. 229 Recovery Token: A secret value that can be used to demonstrate prior 230 authorization for an identifier, in a situation where all Subject 231 Private Keys and Authorized Keys are lost. 233 ACME messaging is based on HTTPS [RFC2818] and JSON [RFC7159]. Since 234 JSON is a text-based format, binary fields are Base64-encoded. For 235 Base64 encoding, we use the variant defined in 236 [I-D.ietf-jose-json-web-signature]. The important features of this 237 encoding are (1) that it uses the URL-safe character set, and (2) 238 that "=" padding characters are stripped. 240 4. Protocol Overview 242 ACME allows a client to request certificate management actions using 243 a set of JSON messages carried over HTTPS. It is a prerequisite for 244 this process that the client be configured with the HTTPS URI for the 245 server. ACME messages MUST NOT be carried over "plain" HTTP, without 246 HTTPS semantics. 248 In some ways, ACME functions much like a traditional CA, in which a 249 user creates an account, adds domains to that account (proving 250 control of the domains), and requests certificate issuance for those 251 domains while logged in to the account. In ACME, the account is 252 represented by a key pair. The "add a domain" function is 253 accomplished by authorizing the key pair for a given domain, and 254 certificate issuance is authorized by a signature with the key pair. 256 The first phase of ACME is for the client to establish an authorized 257 key pair with the server for the identifier(s) it wishes to include 258 in the certificate. To do this, the client must demonstrate to the 259 server both (1) that it holds the private key of the key pair being 260 authorized, and (2) that it has authority over the identifier being 261 claimed. 263 In the key authorization process, then, the server presents the 264 client with two tests. First, a task to demonstrate that the client 265 holds the private key of key pair being authorized, and second, a set 266 of challenges that the client can perform to demonstrate its 267 authority over the domain in question. 269 Because there are many different ways to validate possession of 270 different types of identifiers, the server will choose from an 271 extensible set of challenges that are appropriate for the identifier 272 being claimed. For example, if the client requests a domain name, 273 the server might challenge the client to provision a record in the 274 DNS under that name, or to provision a file on a web server reference 275 by an A or AAAA record under that name. 277 After the client has prepared responses to the server's challenges, 278 it sends a second request with its responses to these challenges. 279 The server's response indicates whether the request for authorization 280 has succeeded or failed. If the authorization request succeeded, the 281 server also provides a recovery token, which the client can use in a 282 later authorization transaction to show that it is the same as the 283 entity that participated in this authorization. 285 Client Server 287 Desired identifier -------> 289 PoP nonce 290 Session ID 291 <------- Identifier Challenges 293 Public key 294 Session ID 295 PoP nonce 296 PoP signature 297 [Contact information] 298 Responses to challenges -------> 300 <------- Recovery token 302 Once the client has established an authorized key pair for an 303 identifier, it can use the key pair to authorize the issuance of 304 certificates for the identifier. To do this, the client sends a 305 PKCS#10 Certificate Signing Request (CSR) to the server (indicating 306 the identifier(s) to be included in the issued certificate), and a 307 signature over the CSR by the private key of the authorized key pair. 309 If the server agrees to issue the certificate, then it creates the 310 certificate and provides it in its response. The server may also 311 provide a URI that can be used to renew the certificate, if it allows 312 renewal without re-validation. 314 Client Server 316 CSR 317 Signature by auth'd key --------> 319 Certificate 320 <-------- Renewal URI 322 To revoke a certificate, the client simply sends a revocation 323 request, signed with an authorized key pair, and the server indicates 324 whether the request has succeeded. 326 Client Server 328 Revocation request 329 Signature by auth'd key --------> 331 <-------- Result 333 Note that while ACME is defined with enough flexibility to handle 334 different types of identifiers in principle, the primary use case 335 addressed by this document is the case where domain names are used as 336 identifiers. For example, all of the identifier validation 337 challenges described in Section Section 6 below address validation of 338 domain names. The use of ACME for other protocols will require 339 further specification, in order to describe how these identifiers are 340 encoded in the protocol, and what types of validation challenges the 341 server might require. 343 5. Certificate Management 345 In this section, we describe the four certificate management 346 functions that ACME enables: 348 o Key Authorization 350 o Certificate Issuance 352 o Certificate Revocation 354 Each of these functions is accomplished by the client sending a 355 sequence of HTTPS requests to the server, carrying JSON messages. 356 Each subsection below describes the message formats used by the 357 function, and the order in which messages are sent. 359 All ACME messages share some common structure. At base, each ACME 360 message is a JSON dictionary, and MUST include a "type" field to 361 indicate which type of message it is. 363 type (required, string): The type of ACME message encoded in this 364 JSON dictionary. 366 All other fields in an ACME message are defined by the type, as 367 described below. Unrecognized fields in ACME messages MUST be 368 ignored. Creators of ACME messages MUST NOT create messages with 369 duplicate fields. Parsers of ACME messages MAY be tolerant of 370 duplicate fields, but the behavior of the protocol in this case is 371 undefined. 373 5.1. General Request/Response Lifecycle 375 Client-server interactions in ACME are logically request/response 376 transactions, corresponding directly to HTTPS requests and responses. 377 The client sends a request message of a particular type, and the 378 server sends response of a corresponding type. 380 All requests for a given ACME server are sent to the same HTTPS URI. 381 It is assumed that clients are configured with this URI out of band. 382 ACME requests MUST use the POST method, and since they carry JSON 383 payloads, SHOULD set the Content-Type header field to "application/ 384 json". ACME responses MUST be carried in HTTP responses with the 385 status code 200. ACME clients SHOULD follow HTTP redirects (301 or 386 302 responses), in case an ACME server is relocated. 388 ACME provides three general message types - "error", "defer", and 389 "statusRequest" - to cover cases where the server is not able to 390 return a successful result immediately. If there is a problem that 391 prevents the request from succeeding, then the server sends an error 392 message. The fields in an error message are as follows: 394 type (required, string): "error" 396 error (required, string): A token from the below list indicating 397 what type of error occurred. 399 message (optional, string): A human-readable string describing the 400 error. 402 moreInfo (optional, string): A URL of a resource containing 403 additional human-readable documentation about the error, such as 404 advice on how to revise the request or adjust the client 405 configuration to allow the request to succeed, or documentation of 406 CA issuance policies that describe why the request cannot be 407 fulfilled. 409 { 410 "type": "error", 411 "error": "badCSR", 412 "message": "RSA keys must be at least 2048 bits long", 413 "moreInfo": "https://ca.example.com/documentation/csr-requirements" 414 } 416 The possible error codes are as follows: 418 +----------------+--------------------------------------------------+ 419 | Code | Semantic | 420 +----------------+--------------------------------------------------+ 421 | malformed | The request message was malformed | 422 | | | 423 | unauthorized | The client lacks sufficient authorization | 424 | | | 425 | serverInternal | The server experienced an internal error | 426 | | | 427 | notSupported | The request type is not supported | 428 | | | 429 | unknown | The server does not recognize an ID/token in the | 430 | | request | 431 | | | 432 | badCSR | The CSR is unacceptable (e.g., due to a short | 433 | | key) | 434 +----------------+--------------------------------------------------+ 436 The server may also defer providing a response by sending a defer 437 message. For example, in the key authorization process, the server 438 may need additional time to validate the client's responses to its 439 challenges. Or in the issuance process, there may be some delay due 440 to batch signing. The fields in a defer message are as follows: 442 type (required, string): "defer" 444 token (required, string): An opaque value that the client uses to 445 check on the status of the request (using a statusRequest 446 message). 448 interval (optional, number): The amount of time, in seconds, that 449 the client should wait before checking on the status of the 450 request. (This is a recommendation only, and clients SHOULD 451 enforce minimum and maximum deferral times.) 453 message (optional, string): A human-readable string describing the 454 reason for the deferral. 456 For example, a deferral due to batch signing might be indicated with 457 a message of the following form: 459 { 460 "type": "defer", 461 "token": "O7-s9MNq1siZHlgrMzi9_A", 462 "interval": 60, 463 "message": "Warming up the HSM" 464 } 465 When a client receives a defer message, it periodically sends a 466 statusRequest message to the server, with the token provided in the 467 defer message. 469 type (required, string): "statusRequest" 471 token (required, string): An opaque value that was provided in a 472 defer message. 474 { 475 "type": "statusRequest", 476 "token": "O7-s9MNq1siZHlgrMzi9_A" 477 } 479 If the server responds with another defer message, then the server 480 still does not have a final response. The client MUST ignore the 481 "token" value in defer responses provided in responses to status 482 requests, and continue polling with the original token. Any non- 483 defer response (error or success) is considered final, and the client 484 MUST cease polling. 486 In summary, the client goes through the following state machine to 487 perform an ACME transaction: 489 START 490 | 491 V 492 RESPONSE_WAIT <-----------+ 493 | | 494 +----------+-----------+ | 495 | | | | 496 V V V | 497 TIMEOUT GOT_FINAL GOT_DEFER --+ 499 The client begins by sending a request and awaiting the response. If 500 the response contains an ACME message of any type besides "defer", 501 then the request is completed, and if no response arrives, the 502 request times out. If a defer request arrives, then the client waits 503 some time and sends a polling request, whose response is handled in 504 the same way as the original request. 506 The following table summarizes the request and response types defined 507 in this document. If the server provides the client with a non-error 508 response of a type that does not match the request message type, then 509 the client MUST treat it as an error message with code 510 "serverInternal". 512 +----------------------+---------------+ 513 | Request | Response | 514 +----------------------+---------------+ 515 | challengeRequest | challenge | 516 | | | 517 | authorizationRequest | authorization | 518 | | | 519 | certificateRequest | certificate | 520 | | | 521 | revocationRequest | revocation | 522 | | | 523 | statusRequest | (any) | 524 +----------------------+---------------+ 526 5.2. Signatures 528 ACME uses a simple JSON-based structure for encoding signatures, 529 based on the JSON Web Signature structure. An ACME signature is a 530 JSON object, with the following fields: 532 alg (required, string): A token indicating the cryptographic 533 algorithm used to compute the signature 534 [I-D.ietf-jose-json-web-algorithms]. (MAC algorithms such as 535 "HS*" MUST NOT be used.) 537 sig (required, string): The signature, base64-encoded. 539 nonce (required, string): A signer-provided random nonce of at least 540 16 bytes, base64-encoded. (For anti-replay.) 542 jwk (required, object): A JSON Web Key object describing the key 543 used to verify the signature [I-D.ietf-jose-json-web-key]. 545 Each usage of a signature object must specify the content being 546 signed. To avoid replay risk, the input to the signature algorithm 547 is the concatenation of the nonce with the content to be signed. 549 signature-input = nonce || content 551 A verifier computes the same input before verifying the signature. 552 Note that while an signature object contains all of the information 553 required to verify the signature, the verifier must also check that 554 the public key encoded in the JWK object is the correct key for a 555 given context. 557 5.3. Key Authorization 559 The key authorization process establishes a key pair as an authorized 560 key pair for a given identifier. This process must assure the server 561 of two things: First, that the client controls the private key of the 562 key pair, and second, that the client holds the identifier in 563 question. This process may be repeated to associate multiple 564 identifiers to a key pair (e.g., to request certificates with 565 multiple identifiers), or to associate multiple key pairs with an 566 identifier (e.g., for load balancing). 568 As illustrated by the figure in the overview section above, the 569 authorization process proceeds in two transactions. The client first 570 requests a list of challenges from the server, and then requests 571 authorization based on its answers to those challenges. 573 The first request in the key authorization process is a 574 "challengeRequest" message, specifying the identifier for which the 575 client will be requesting authorization. The fields in a 576 "challengeRequest" message are as follows: 578 type (required, string): "challengeRequest" 580 identifier (required, string): The identifier for which 581 authorization is being sought. For implementations of this 582 specification, this identifier MUST be a domain name. (If other 583 types of identifier are supported, then an extension to this 584 protocol will need to add a field to distinguish types of 585 identifier.) 587 { 588 "type": "challengeRequest", 589 "identifier": "example.com" 590 } 592 On receiving a "challengeRequest" message, the server determines what 593 sorts of challenges it will accept as proof that the client holds the 594 identifier. (The server could also decide that a particular 595 identifier is invalid or that the server cannot possibly issue 596 certificates related to that identifier, in which case the server may 597 return an error.) The set of challenges may be limited by the 598 server's capabilities, and the server may require different 599 challenges to be completed for different identifiers (e.g., requiring 600 a higher standard for higher-value names). In all cases, however, 601 the server provides a nonce as a proof-of-possession challenge for 602 the key pair being authorized. The server returns this policy to the 603 client in a "challenge" message: 605 type (required, string): "challenge" 607 sessionID (required, string): An opaque string that allows the 608 server to correlate transactions related to this challenge 609 request. 611 nonce (required, string): A base64-encoded octet string that the 612 client is expected to sign with the private key of the key pair 613 being authorized. 615 challenges (required, array): A list of challenges to be fulfilled 616 by the client in order to prove possession of the identifier. The 617 syntax for challenges is described in Section Section 6. 619 combinations (optional, array of arrays): A collection of sets of 620 challenges, each of which would be sufficient to prove possession 621 of the identifier. Clients SHOULD complete a set of challenges 622 that that covers at least one set in this array. Challenges are 623 represented by their associated zero-based index in the challenges 624 array. 626 For example, if the server wants to have the client demonstrate both 627 that the client controls the domain name in question, and that this 628 client is the same client that previously requested authorization for 629 the domain name, it might issue the following request. The client is 630 expected to provide "simpleHttps" and "recoveryToken" responses 631 ("[0,2]"), or else "dns" and "recoveryToken" responses ("[1,2]"), or 632 all three. 634 { 635 "type": "challenge", 636 "sessionID": "aefoGaavieG9Wihuk2aufai3aeZ5EeW4", 637 "nonce": "czpsrF0KMH6dgajig3TGHw", 638 "challenges": [ 639 { 640 "type": "simpleHttps", 641 "token": "IlirfxKKXAsHtmzK29Pj8A" 642 }, 643 { 644 "type": "dns", 645 "token": "DGyRejmCefe7v4NfDGDKfA" 646 }, 647 { 648 "type": "recoveryToken" 649 } 650 ], 651 "combinations": [ 652 [0, 2], [1, 2] 653 ] 654 } 656 In order to avoid replay attacks, the server MUST generate a fresh 657 nonce of at least 128 bits for each authorization transaction, and 658 MUST NOT accept more than one authorizationRequest with the same 659 nonce. 661 The client SHOULD satisfy all challenges in one of the sets expressed 662 in the "combinations" array. If a "combinations" field is not 663 specified, the client SHOULD attempt to fulfill as many challenges as 664 possible. 666 Once the client believes that it has fulfilled enough challenges, it 667 creates an authorizationRequest object requesting authorization of a 668 key pair for this identifier based on its responses. The 669 authorizationRequest also contains the public key to be authorized, 670 and the signature by the corresponding private key over the nonce in 671 the challenge. 673 type (required, string): "authorizationRequest" 675 sessionID (required, string): The session ID provided by the server 676 in the challenge message (to allow the server to correlate the two 677 transactions). 679 nonce (required, string): The nonce provided by the server in the 680 challenge message. 682 signature (required, object): A signature object reflecting a 683 signature over the identifier being authorized and the nonce 684 provided by the server. Thus, for this authorization: 686 signature-input = signature-nonce || identifier || server-nonce 688 responses (required, array): The client's responses to the server's 689 challenges, in the same order as the challenges. If the client 690 chooses not to respond to a given challenge, then the 691 corresponding entry in the response array is set to null. 692 Otherwise, it is set to a value defined by the challenge type. 694 contact (optional, array): An array of URIs that the server can use 695 to contact the client for issues related to this authorization. 696 For example, the server may wish to notify the client about 697 server-initiated revocation, or check with the client on future 698 authorizations (see the "recoveryContact" challenge type). 700 { 701 "type": "authorizationRequest", 702 "sessionID": "aefoGaavieG9Wihuk2aufai3aeZ5EeW4", 703 "nonce": "czpsrF0KMH6dgajig3TGHw", 704 "signature": { 705 "nonce": "Aenb3DvfvOPImdXdnxHMlp7Jh4qsgYeTEM-dFgFOGxU", 706 "alg": "ES256", 707 "jwk": { 708 "kty": "EC", 709 "crv": "P-256", 710 "x": "NJ15BoXput18sSwnXA3gJEEnqIAzxSEl9ga8wGM4mEU", 711 "y": "6l_U9mals_dwt77tIxSiQ6oL_CyLVey4baa8wCn0V9k" 712 }, 713 "sig": "lxj0Ucdo4r5s1c1cuY2R7oKqWi4QuNJzdwe5/4m9zWQ" 714 }, 715 "responses": [ 716 { 717 "type": "simpleHttps", 718 "path": "Hf5GrX4Q7EBax9hc2jJnfw" 719 }, 720 null, 721 { 722 "type": "recoveryToken", 723 "token": "23029d88d9e123e" 724 } 725 ], 726 "contact": [ 727 "mailto:cert-admin@example.com", 728 "tel:+12025551212" 729 ] 730 } 732 Once it has received the client's responses, the server verifies them 733 according to procedures specific to each challenge type. Because 734 some of these procedures take time to verify, it is likely that the 735 server will respond to an authorizationRequest message with a defer 736 message. 738 If there is a problem with the authorizationRequest (e.g., the 739 signature object does not verify), or if the available responses are 740 not sufficient to convince the server that the client controls the 741 identifier, then the server responds with an error message. The 742 server should use the "unauthorized" error code for cases where the 743 client's responses were insufficient. If the server is satisfied 744 that the client controls the private key and identifier in question, 745 then it sends an authorization message indicating the success of the 746 authorization request, and providing a recovery token that the client 747 can use to help recover authorization if the private key of the 748 authorized key pair is lost. 750 type (required, string): "authorization" 752 recoveryToken (optional, string): An arbitrary server-generated 753 string. If the server provides a recovery token, it MUST generate 754 a unique value for every authorization transaction, and this value 755 MUST NOT be predictable or guessable by a third party. 757 identifier (optional, string): The identifier for which 758 authorization has been granted. 760 jwk (optional, object): A JSON Web Key object describing the 761 authorized public key. 763 5.3.1. Recovery Tokens 765 A recovery token is a fallback authentication mechanism. In the 766 event that a client loses all other state, including authorized key 767 pairs and key pairs bound to certificates, the client can use the 768 recovery token to prove that it was previously authorized for the 769 identifier in question. 771 This mechanism is necessary because once an ACME server has issued an 772 Authorization Key for a given identifier, that identifier enters a 773 higher-security state, at least with respect the ACME server. That 774 state exists to protect against attacks such as DNS hijacking and 775 router compromise which tend to inherently defeat all forms of Domain 776 Validation. So once a domain has begun using ACME, new DV-only 777 authorization will not be performed without proof of continuity via 778 possession of an Authorized Private Key or potentially a Subject 779 Private Key for that domain. 781 This higher state of security poses some risks. From time to time, 782 the administrators and owners of domains may lose access to keys they 783 have previously had issued or certified, including Authorized private 784 keys and Subject private keys. For instance, the disks on which this 785 key material is stored may suffer failures, or passphrases for these 786 keys may be forgotten. In some cases, the security measures that are 787 taken to protect this sensitive data may contribute to its loss. 789 Recovery Tokens and Recovery Challenges exist to provide a fallback 790 mechanism to restore the state of the domain to the server-side 791 administrative security state it was in prior to the use of ACME, 792 such that fresh Domain Validation is sufficient for reauthorization. 794 Recovery tokens are therefore only useful to an attacker who can also 795 perform Domain Validation against a target domain, and as a result 796 client administrators may choose to handle them with somewhat fewer 797 security precautions than Authorized and Subject private keys, 798 decreasing the risk of their loss. 800 Recovery tokens come in several types, including high-entropy 801 passcodes (which need to be safely preserved by the client admin) and 802 email addresses (which are inherently hard to lose, and which can be 803 used for verification, though they may be a little less secure). 805 Recovery tokens are employed in response to Recovery Challenges. 806 Such challenges will be available if the server has issued Recovery 807 Tokens for a given domain, and the combination of a Recovery 808 Challenge and a domain validation Challenge is a plausible 809 alternative to other challenge sets for domains that already have 810 extant Authorized keys. 812 5.4. Certificate Issuance 814 The holder of an authorized key pair for an identifier may use ACME 815 to request that a certificate be issued for that identifier. The 816 client makes this request using a "certificateRequest" message, which 817 contains a Certificate Signing Request (CSR) [RFC2986] and a 818 signature by the authorized key pair. 820 type (required, string): "certificateRequest" 822 csr (required, string): A CSR encoding the parameters for the 823 certificate being requested. The CSR is sent in base64-encoded 824 version the DER format. (Note: This field uses the same modified 825 base64-encoding rules used elsewhere in this document, so it is 826 different from PEM.) 828 signature (required, object): A signature object reflecting a 829 signature by an authorized key pair over the CSR. 831 { 832 "type": "certificateRequest", 833 "csr": "5jNudRx6Ye4HzKEqT5...FS6aKdZeGsysoCo4H9P", 834 "signature": { 835 "alg": "RS256", 836 "nonce": "h5aYpWVkq-xlJh6cpR-3cw", 837 "sig": "KxITJ0rNlfDMAtfDr8eAw...fSSoehDFNZKQKzTZPtQ", 838 "jwk": { 839 "kty":"RSA", 840 "e":"AQAB", 841 "n":"KxITJ0rNlfDMAtfDr8eAw...fSSoehDFNZKQKzTZPtQ" 842 } 843 } 844 } 846 The CSR encodes the client's requests with regard to the content of 847 the certificate to be issued. The CSR MUST contain at least one 848 extensionRequest attribute [RFC2985] requesting a subjectAltName 849 extension, containing the requested identifiers. 851 The values provided in the CSR are only a request, and are not 852 guaranteed. The server or CA may alter any fields in the certificate 853 before issuance. For example, the CA may remove identifiers that are 854 not authorized for the key indicated in the "authorization" field. 856 If the CA decides to issue a certificate, then the server responds 857 with a certificate message. (Of course, the server may also respond 858 with an error message if issuance is denied, or a defer message if 859 there may be some delay in issuance.) 861 type (required, string): "certificate" 863 certificate (required, string): The issued certificate, as a 864 base64-encoded DER certificate. 866 chain (optional, array of string): A chain of CA certificates which 867 are parents of the issued certificate. Each certificate is in 868 base64-encoded DER form (not PEM, as for CSRs above). This array 869 MUST be presented in the same order as would be required in a TLS 870 handshake [RFC5246]. 872 refresh (optional, string): An HTTP or HTTPS URI from which updated 873 versions of this certificate can be fetched. 875 { 876 "type": "certificate", 877 "certificate": "Zmzdx7UKvwDJ6bk...YBX22NPGQZyYcg", 878 "chain": [ 879 "WUn8L2vLT553pIWJ2...gJ574o2anls1k2p", 880 "y3O4puZa9r5KBk1LX...Ya7jlaAZUfuYZGZ" 881 ], 882 "refresh": "https://example.com/refresh/Dr8eAwTVQfSS/" 883 } 885 The certificate message allows the server to provide the certificate 886 itself, as well as some associated management information. The chain 887 of CA certificates can simplify TLS server configuration, by allowing 888 the server to suggest the certificate chain that a TLS server using 889 the issued certificate should present. 891 The refresh URI allows the client to download updated versions of the 892 issued certificate, in the sense of certificates with different 893 validity intervals, but otherwise the same contents (in particular, 894 the same names and public key). This can be useful in cases where a 895 CA wishes to issue short-lived certificates, but is still willing to 896 vouch for an identifier-key binding over a longer period of time. To 897 download an updated certificate, the client simply sends a GET 898 request to the refresh URI. 900 5.5. Certificate Revocation 902 To request that a certificate be revoked, the client sends a 903 revocationRequest message that indicates the certificate to be 904 revoked, with a signature by an authorized key: 906 type (required, string): "revocationRequest" 908 certificate (required, string): The certificate to be revoked. 910 signature (required, object): A signature object reflecting a 911 signature by an authorized key pair over the certificate. 913 { 914 "type": "revocationRequest", 915 "certificate": "Zmzdx7UKvwDJ6bk...YBX22NPGQZyYcg", 916 "signature": { 917 "alg": "RS256", 918 "nonce": "OQqU4VlhXhvZW9FIqNW-jg", 919 "sig": "KxITJ0rNlfDMAtfDr8eAw...fSSoehDFNZKQKzTZPtQ", 920 "jwk": { 921 "kty":"RSA", 922 "e":"AQAB", 923 "n":"KxITJ0rNlfDMAtfDr8eAw...fSSoehDFNZKQKzTZPtQ" 924 } 925 } 926 } 928 Before revoking a certificate, the server MUST verify that the public 929 key indicated in the signature object is authorized to act for all of 930 the identifier(s) in the certificate. The server MAY also accept a 931 signature by the private key corresponding to the public key in the 932 certificate. 934 If the revocation fails, the server returns an error message, e.g., 935 an "unauthorized" error if the signing key was not authorized to 936 revoke this certificate. If the revocation succeeds, then the server 937 confirms with a "revocation" message, which has no payload. 939 type (required, string): "revocation" 941 { 942 "type": "revocation" 943 } 945 6. Identifier Validation Challenges 947 There are few types of identifier in the world for which there is a 948 standardized mechanism to prove possession of a given identifier. In 949 all practical cases, CAs rely on a variety of means to test whether 950 an entity applying for a certificate with a given identifier actually 951 controls that identifier. 953 To accommodate this reality, ACME includes an extensible challenge/ 954 response framework for identifier validation. This section describes 955 an initial set of Challenge types. Each challenge must describe: 957 o Content of Challenge payloads (in Challenge messages) 958 o Content of Response payloads (in authorizationRequest messages) 960 o How the server uses the Challenge and Response to verify control 961 of an identifier 963 The only general requirement for Challenge and Response payloads is 964 that they MUST be structured as a JSON object, and they MUST contain 965 a parameter "type" that specifies the type of Challenge or Response 966 encoded in the object. 968 Different challenges allow the server to obtain proof of different 969 aspects of control over an identifier. In some challenges, like 970 Simple HTTPS and DVSNI, the client directly proves control of an 971 identifier. In other challenges, such as Recovery or Proof of 972 Possession, the client proves historical control of the identifier, 973 by reference to a prior authorization transaction or certificate. 975 The choice of which Challenges to offer to a client under which 976 circumstances is a matter of server policy. A server may choose 977 different sets of challenges depending on whether it has interacted 978 with a domain before, and how. For example: 980 +-------------------------------+-----------------------------------+ 981 | Domain status | Challenges typically sufficient | 982 | | for (re)Authorization | 983 +-------------------------------+-----------------------------------+ 984 | No known prior certificates | Domain Validation (DVSNI or | 985 | or ACME usage | Simple HTTPS) | 986 | | | 987 | Existing valid certs, first | DV + Proof of Possession of | 988 | use of ACME | previous CA-signed key | 989 | | | 990 | Ongoing ACME usage | PoP of previous Authorized key | 991 | | | 992 | Ongoing ACME usage, lost | DV + (Recovery or PoP of ACME- | 993 | Authorized key | certified Subject key) | 994 | | | 995 | ACME usage, all keys and | Recertification by another CA + | 996 | recovery tokens lost | PoP of that key | 997 +-------------------------------+-----------------------------------+ 999 The identifier validation challenges described in this section all 1000 relate to validation of domain names. If ACME is extended in the 1001 future to support other types of identifier, there will need to be 1002 new Challenge types, and they will need to specify which types of 1003 identifier they apply to. 1005 6.1. Simple HTTPS 1007 With Simple HTTPS validation, the client in an ACME transaction 1008 proves its control over a domain name by proving that it can 1009 provision resources on an HTTPS server that responds for that domain 1010 name. The ACME server challenges the client to provision a file with 1011 a specific string as its contents. 1013 type (required, string): The string "simpleHttps" 1015 token (required, string): The value to be provisioned in the file. 1016 This value MUST have at least 128 bits of entropy, in order to 1017 prevent an attacker from guessing it. It MUST NOT contain any 1018 non-ASCII characters. 1020 { 1021 "type": "simpleHttps", 1022 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ+PCt92wr+oA" 1023 } 1025 A client responds to this Challenge by provisioning the nonce as a 1026 resource on the HTTPS server for the domain in question. The path at 1027 which the resource is provisioned is determined by the client, but 1028 MUST begin with ".well-known/acme-challenge/". The content type of 1029 the resource MUST be "text/plain". The client returns the part of 1030 the path coming after that prefix in its Response message. 1032 type (required, string): The string "simpleHttps" 1034 path (required, string): The string to be appended to the standard 1035 prefix ".well-known/acme-challenge" in order to form the path at 1036 which the nonce resource is provisioned. The result of 1037 concatenating the prefix with this value MUST match the "path" 1038 production in the standard URI format [RFC3986] 1040 { 1041 "type": "simpleHttps", 1042 "path": "6tbIMBC5Anhl5bOlWT5ZFA" 1043 } 1045 Given a Challenge/Response pair, the server verifies the client's 1046 control of the domain by verifying that the resource was provisioned 1047 as expected. 1049 1. Form a URI by populating the URI template 1050 "https://{domain}/.well-known/acme-challenge/{path}", where the 1051 domain field is set to the domain name being verified and the 1052 path field is the path provided in the challenge [RFC6570]. 1054 2. Verify that the resulting URI is well-formed. 1056 3. Dereference the URI using an HTTPS GET request. 1058 4. Verify that the certificate presented by the HTTPS server is a 1059 valid self-signed certificate, and contains the domain name being 1060 validated as well as the public key of the key pair being 1061 authorized. 1063 5. Verify that the Content-Type header of the response is either 1064 absent, or has the value "text/plain" 1066 6. Compare the entity body of the response with the nonce. This 1067 comparison MUST be performed in terms of Unicode code points, 1068 taking into account the encodings of the stored nonce and the 1069 body of the request. 1071 If the GET request succeeds and the entity body is equal to the 1072 nonce, then the validation is successful. If the request fails, or 1073 the body does not match the nonce, then it has failed. 1075 6.2. Domain Validation with Server Name Indication 1077 The Domain Validation with Server Name Indication (DVSNI) validation 1078 method aims to ensure that the ACME client has administrative access 1079 to the web server at the domain name being validated, and possession 1080 of the private key being authorized. The ACME server verifies that 1081 the operator can reconfigure the web server by having the client 1082 create a new self-signed challenge certificate and respond to TLS 1083 connections from the ACME server with it. 1085 The challenge proceeds as follows: The ACME server sends the client a 1086 random value R and a nonce used to identify the transaction. The 1087 client responds with another random value S. The server initiates a 1088 TLS connection on port 443 to a host with the domain name being 1089 validated. In the handshake, the ACME server sets the Server Name 1090 Indication extension set to ".acme.invalid". The TLS server 1091 (i.e., the ACME client) should respond with a valid self-signed 1092 certificate containing both the domain name being validated and the 1093 domain name ".acme.invalid", where Z = SHA-256(R || S). 1095 The ACME server's Challenge provides its random value R, and a random 1096 nonce used to identify the transaction: 1098 type (required, string): The string "dvsni" 1099 r (required, string): A random 32-byte octet, base64-encoded 1101 nonce (required, string): A random 16-byte octet string, hex-encoded 1102 (so that it can be used as a DNS label) 1104 { 1105 "type": "dvsni", 1106 "r": "Tyq0La3slT7tqQ0wlOiXnCY2vyez7Zo5blgPJ1xt5xI", 1107 "nonce": "a82d5ff8ef740d12881f6d3c2277ab2e" 1108 } 1110 The ACME server MAY re-use nonce values, but SHOULD periodically 1111 refresh them. ACME clients MUST NOT rely on nonce values being 1112 stable over time. 1114 The client responds to this Challenge by configuring a TLS server on 1115 port 443 of a server with the domain name being validated: 1117 1. Decode the server's random value R 1119 2. Generate a random 32-byte octet string S 1121 3. Compute Z = SHA-256(R || S) (where || denotes concatenation of 1122 octet strings) 1124 4. Generate a self-signed certificate with a subjectAltName 1125 extension containing two dNSName values: 1127 5. The domain name being validated 1129 6. A name formed by hex-encoding Z and appending the suffix 1130 ".acme.invalid" 1132 7. Compute a nonce domain name by appending the suffix 1133 ".acme.invalid" to the nonce provided by the server. 1135 8. Configure the TLS server such that when a client presents the 1136 nonce domain name in the SNI field, the server presents the 1137 generated certificate. 1139 The client's response provides its random value S: 1141 type (required, string): The string "dvsni" 1143 s (required, string): A random 32-byte secret octet string, 1144 base64-encoded 1146 { 1147 "type": "dvsni", 1148 "s": "9dbjsl3gTAtOnEtKFEmhS6Mj-ajNjDcOmRkp3Lfzm3c" 1149 } 1151 Given a Challenge/Response pair, the ACME server verifies the 1152 client's control of the domain by verifying that the TLS server was 1153 configured as expected: 1155 1. Compute the value Z = SHA-256(R || S) 1157 2. Open a TLS connection to the domain name being validated on port 1158 443, presenting the value ".acme.invalid" in the SNI 1159 field. 1161 3. Verify the following properties of the certificate provided by 1162 the TLS server: 1164 * It is a valid self-signed certificate 1166 * The public key is the public key for the key pair being 1167 authorized 1169 * It contains the domain name being validated as a 1170 subjectAltName 1172 * It contains a subjectAltName matching the hex-encoding of Z, 1173 with the suffix ".acme.invalid" 1175 It is RECOMMENDED that the ACME server verify the challenge 1176 certificate using multi-path probing techniques to reduce the risk of 1177 DNS hijacking attacks. 1179 If the server presents a certificate matching all of the above 1180 criteria, then the validation is successful. Otherwise, the 1181 validation fails. 1183 6.3. Recovery Contact 1185 A server may issue a recovery contact challenge to verify that the 1186 client is the same as the entity that previously requested 1187 authorization, using contact information provided by the client in a 1188 prior authorizationRequest message. 1190 The server's message to the client may request action in-band or out- 1191 of-band to ACME. The server can provide a token in the message that 1192 the client provides in its response. Or the server could provide 1193 some out-of-band response channel in its message, such as a URL to 1194 click in an email. 1196 type (required, string): The string "recoveryContact" 1198 activationURL (optional, string): A URL the client can visit to 1199 cause a recovery message to be sent to client's contact address. 1201 successURL (optional, string): A URL the client may poll to 1202 determine if the user has successfully clicked a link or completed 1203 other tasks specified by the recovery message. This URL will 1204 return a 200 success code if the required tasks have been 1205 completed. The client SHOULD NOT poll the URL more than once 1206 every three seconds. 1208 contact (optional, string) A full or partly obfuscated version of 1209 the contact URI that the server will use to contact the client. 1210 Client software may present this to a user in order to suggest 1211 what contact point the user should check (e.g., an email address). 1213 { 1214 "type": "recoveryContact", 1215 "activationURL" : "https://example.ca/sendrecovery/a5bd99383fb0", 1216 "successURL" : "https://example.ca/confirmrecovery/bb1b9928932", 1217 "contact" : "c********n@example.com" 1218 } 1220 type (required, string): The string "recoveryContact" 1222 token (optional, string): If the user transferred a token from a 1223 contact email or call into the client software, the client sends 1224 it here. If it the client has received a 200 success response 1225 while polling the RecoveryContact Challenge's successURL, this 1226 field SHOULD be omitted. 1228 { 1229 "type": "recoveryContact", 1230 "token": "23029d88d9e123e" 1231 } 1233 If the value of the "token" field matches the value provided in the 1234 out-of-band message to the client, or if the client has completed the 1235 required out-of-band action, then the validation succeeds. 1236 Otherwise, the validation fails. 1238 6.4. Recovery Token 1240 A recovery token is a simple way for the server to verify that the 1241 client was previously authorized for a domain. The client simply 1242 provides the recovery token that was provided in the authorize 1243 message. 1245 type (required, string): The string "recoveryToken" 1247 { 1248 "type": "recoveryToken" 1249 } 1251 The response to a recovery token challenge is simple; the client 1252 sends the requested token that it was provided by the server earlier. 1254 type (required, string): The string "recoveryToken" 1256 token (optional, string): The recovery token provided by the server. 1258 { 1259 "type": "recoveryToken", 1260 "token": "23029d88d9e123e" 1261 } 1263 If the value of the "token" field matches a recovery token that the 1264 server previously provided for this domain, then the validation 1265 succeeds. Otherwise, the validation fails. 1267 6.5. Proof of Possession of a Prior Key 1269 The Proof of Possession challenge verifies that a client possesses a 1270 private key corresponding to a server-specified public key, as 1271 demonstrated by its ability to correctly sign server-provided data 1272 with that key. 1274 This method is useful if a server policy calls for issuing a 1275 certificate only to an entity that already possesses the subject 1276 private key of a particular prior related certificate (perhaps issued 1277 by a different CA). It may also help enable other kinds of server 1278 policy that are related to authenticating a client's identity using 1279 digital signatures. 1281 This challenge proceeds in much the same way as the proof of 1282 possession of the authorized key pair in the main ACME flow 1283 (challenge + authorizationRequest). The server provides a nonce and 1284 the client signs over the nonce. The main difference is that rather 1285 than signing with the private key of the key pair being authorized, 1286 the client signs with a private key specified by the server. The 1287 server can specify which key pair(s) are acceptable directly (by 1288 indicating a public key), or by asking for the key corresponding to a 1289 certificate. 1291 The server provides the following fields as part of the challenge: 1293 type (required, string): The string "proofOfPossession" 1295 alg (required, string): A token indicating the cryptographic 1296 algorithm that should be used by the client to compute the 1297 signature [I-D.ietf-jose-json-web-algorithms]. (MAC algorithms 1298 such as "HS*" MUST NOT be used.) The client MUST verify that this 1299 algorithm is supported for the indicated key before responding to 1300 this challenge. 1302 nonce (required, string): A random 16-byte octet string, 1303 base64-encoded 1305 hints (required, object): A JSON object that contains various clues 1306 for the client about what the requested key is, such that the 1307 client can find it. Entries in the hints object may include: 1309 jwk (required, object): A JSON Web Key object describing the public 1310 key whose corresponding private key should be used to generate the 1311 signature [I-D.ietf-jose-json-web-key] 1313 certFingerprints (optional, array): An array of certificate 1314 fingerprints, hex-encoded SHA1 hashes of DER-encoded certificates 1315 that are known to contain this key 1317 certs (optional, array): An array of certificates, in PEM encoding, 1318 that contain acceptable public keys. 1320 subjectKeyIdentifiers (optional, array): An array of hex-encoded 1321 Subject Key Identifiers (SKIDs) from certificate(s) that contain 1322 the key. Because of divergences in the way that SKIDs are 1323 calculated [RFC5280], there may conceivably be more than one of 1324 these. 1326 serialNumbers (optional, array of numbers): An array of serial 1327 numbers of certificates that are known to contain the requested 1328 key 1330 issuers (optional, array): An array of X.509 Distinguished Names 1331 [RFC5280] of CAs that have been observed to issue certificates for 1332 this key, in text form [RFC4514] 1334 authorizedFor (optional, array): An array of domain names, if any, 1335 for which this server regards the key as an ACME Authorized key. 1337 { 1338 "type": "proofOfPossession", 1339 "alg": "RS256", 1340 "nonce": "eET5udtV7aoX8Xl8gYiZIA", 1341 "hints" : { 1342 "jwk": { 1343 "kty": "RSA", 1344 "e": "AQAB", 1345 "n": "KxITJ0rNlfDMAtfDr8eAw...fSSoehDFNZKQKzTZPtQ" 1346 }, 1347 "certFingerprints": [ 1348 "93416768eb85e33adc4277f4c9acd63e7418fcfe", 1349 "16d95b7b63f1972b980b14c20291f3c0d1855d95", 1350 "48b46570d9fc6358108af43ad1649484def0debf" 1351 ], 1352 "subjectKeyIdentifiers": ["d0083162dcc4c8a23ecb8aecbd86120e56fd24e5"], 1353 "serialNumbers": [34234239832, 23993939911, 17], 1354 "issuers": [ 1355 "C=US, O=SuperT LLC, CN=SuperTrustworthy Public CA", 1356 "O=LessTrustworthy CA Inc, CN=LessTrustworthy But StillSecure" 1357 ], 1358 "authorizedFor": ["www.example.com", "example.net"] 1359 } 1360 } 1362 In this case the server is challenging the client to prove its 1363 control over the private key that corresponds to the public key 1364 specified in the jwk object. The signing algorithm is specified by 1365 the alg field. The nonce value is used by the server to identify 1366 this challenge and is also used, also with a client-provided 1367 signature nonce, as part of the signature input. 1369 signature-input = signature-nonce || server-nonce 1371 The client's response includes the server-provided nonce, together 1372 with a signature over that nonce by one of the private keys requested 1373 by the server. 1375 type (required, string): The string "proofOfPossession" 1376 nonce (required, string): The server nonce that the server 1377 previously associated with this challenge 1379 signature (required, object): The ACME signature computed over the 1380 signature-input using the server-specified algorithm 1382 { 1383 "type": "proofOfPossession", 1384 "nonce": "eET5udtV7aoX8Xl8gYiZIA", 1385 "signature": { 1386 "alg": "RS256", 1387 "nonce": "eET5udtV7aoX8Xl8gYiZIA", 1388 "sig": "KxITJ0rNlfDMAtfDr8eAw...fSSoehDFNZKQKzTZPtQ", 1389 "jwk": { 1390 "kty": "RSA", 1391 "e": "AQAB", 1392 "n": "KxITJ0rNlfDMAtfDr8eAw...fSSoehDFNZKQKzTZPtQ" 1393 } 1394 } 1395 } 1397 Note that just as in the authorizationRequest message, there are two 1398 nonces here, once provided by the client (inside the signature 1399 object) and one provided by the server in its challenge (outside the 1400 signature object). The signature covers the concatenation of these 1401 two nonces (as specified in the signature-input above). 1403 If the server is able to validate the signature and confirm that the 1404 jwk and alg objects are unchanged from the original challenge, the 1405 server can conclude that the client is in control of the private key 1406 that corresponds to the specified public key. The server can use 1407 this evidence in support of its authorization and certificate 1408 issuance policies. 1410 6.6. DNS 1412 When the identifier being validated is a domain name, the client can 1413 prove control of that domain by provisioning records under it. The 1414 DNS challenge requires the client to provision a TXT record 1415 containing a validation token under a specific validation domain 1416 name. 1418 type (required, string): The string "dns" 1420 token (required, string): An ASCII string that is to be provisioned 1421 in the TXT record. This string SHOULD be randomly generated, with 1422 at least 128 bits of entropy (e.g., a hex-encoded random octet 1423 string). 1425 { 1426 "type": "dns", 1427 "token": "17817c66b60ce2e4012dfad92657527a" 1428 } 1430 In response to this challenge, the client first MUST verify that the 1431 token contains only ASCII characters. If so, the client constructs 1432 the validation domain name by appending the label "_acme-challenge" 1433 to the domain name being validated. For example, if the domain name 1434 being validated is "example.com", then the client would provision the 1435 following DNS record: 1437 _acme-challenge.example.com. IN TXT "17817c66b60ce2e4012dfad92657527a" 1439 The response to a DNS challenge is simply an acknowledgement that the 1440 relevant record has been provisioned. 1442 type (required, string): The string "dns" 1444 { 1445 "type": "dns" 1446 } 1448 To validate a DNS challenge, the server queries for TXT records under 1449 the validation domain name. If it receives a record whose contents 1450 match the token in the challenge, then the validation succeeds. 1451 Otherwise, the validation fails. 1453 6.7. Other possibilities 1455 For future work: 1457 o Email 1459 o DNSSEC 1461 o WHOIS 1463 7. IANA Considerations 1465 TODO 1467 o Register .well-known path 1469 o Create identifier validation method registry 1471 o Registries of syntax tokens, e.g., message types / error types? 1473 8. Security Considerations 1475 TODO 1477 o General authorization story 1479 o PoP nonce entropy 1481 o ToC/ToU; duration of key authorization 1483 o Clients need to protect recovery key 1485 o CA needs to perform a very wide range of issuance policy 1486 enforcement and sanity-check steps 1488 o Parser safety (for JSON, JWK, ASN.1, and any other formats that 1489 can be parsed by the ACME server) 1491 9. References 1493 9.1. Normative References 1495 [I-D.ietf-jose-json-web-algorithms] 1496 Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- 1497 json-web-algorithms-40 (work in progress), January 2015. 1499 [I-D.ietf-jose-json-web-key] 1500 Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web- 1501 key-41 (work in progress), January 2015. 1503 [I-D.ietf-jose-json-web-signature] 1504 Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1505 Signature (JWS)", draft-ietf-jose-json-web-signature-41 1506 (work in progress), January 2015. 1508 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1509 Requirement Levels", BCP 14, RFC 2119, March 1997. 1511 [RFC2314] Kaliski, B., "PKCS #10: Certification Request Syntax 1512 Version 1.5", RFC 2314, March 1998. 1514 [RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object 1515 Classes and Attribute Types Version 2.0", RFC 2985, 1516 November 2000. 1518 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 1519 Request Syntax Specification Version 1.7", RFC 2986, 1520 November 2000. 1522 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1523 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1524 3986, January 2005. 1526 [RFC4514] Zeilenga, K., "Lightweight Directory Access Protocol 1527 (LDAP): String Representation of Distinguished Names", RFC 1528 4514, June 2006. 1530 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1531 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1532 May 2008. 1534 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1535 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1537 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1538 Housley, R., and W. Polk, "Internet X.509 Public Key 1539 Infrastructure Certificate and Certificate Revocation List 1540 (CRL) Profile", RFC 5280, May 2008. 1542 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1543 and D. Orchard, "URI Template", RFC 6570, March 2012. 1545 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1546 Interchange Format", RFC 7159, March 2014. 1548 9.2. Informative References 1550 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1552 Authors' Addresses 1554 Richard Barnes 1555 Mozilla 1557 Email: rlb@ipv.sx 1558 Eric Rescorla 1559 Mozilla 1561 Email: ekr@rtfm.com 1563 Peter Eckersley 1564 EFF 1566 Email: pde@eff.org 1568 Seth Schoen 1569 EFF 1571 Email: schoen@eff.org 1573 Alex Halderman 1574 University of Michigan 1576 Email: jhalderm@eecs.umich.edu 1578 James Kasten 1579 University of Michigan 1581 Email: jdkasten@umich.edu