idnits 2.17.1 draft-ietf-acme-acme-06.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 15 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 724 has weird spacing: '...account new-a...' -- The exact meaning of the all-uppercase expression 'NOT REQUIRED' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. -- The document date (March 13, 2017) is 2600 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'A-Z' is mentioned on line 545, but not defined == Missing Reference: '0-9' is mentioned on line 545, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS180-4' ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Downref: Normative reference to an Informational RFC: RFC 2985 ** Downref: Normative reference to an Informational RFC: RFC 2986 ** Obsolete normative reference: RFC 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 6844 (Obsoleted by RFC 8659) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7807 (Obsoleted by RFC 9457) -- Obsolete informational reference (is this intentional?): RFC 5785 (Obsoleted by RFC 8615) Summary: 11 errors (**), 0 flaws (~~), 4 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACME Working Group R. Barnes 3 Internet-Draft Mozilla 4 Intended status: Standards Track J. Hoffman-Andrews 5 Expires: September 14, 2017 EFF 6 J. Kasten 7 University of Michigan 8 March 13, 2017 10 Automatic Certificate Management Environment (ACME) 11 draft-ietf-acme-acme-06 13 Abstract 15 Certificates in PKI using X.509 (PKIX) are used for a number of 16 purposes, the most significant of which is the authentication of 17 domain names. Thus, certificate authorities in the Web PKI are 18 trusted to verify that an applicant for a certificate legitimately 19 represents the domain name(s) in the certificate. Today, this 20 verification is done through a collection of ad hoc mechanisms. This 21 document describes a protocol that a certification authority (CA) and 22 an applicant can use to automate the process of verification and 23 certificate issuance. The protocol also provides facilities for 24 other certificate management functions, such as certificate 25 revocation. 27 DISCLAIMER: This is a work in progress draft of ACME and has not yet 28 had a thorough security analysis. 30 RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH: The source for 31 this draft is maintained in GitHub. Suggested changes should be 32 submitted as pull requests at https://github.com/ietf-wg-acme/acme . 33 Instructions are on that page as well. Editorial changes can be 34 managed in GitHub, but any substantive change should be discussed on 35 the ACME mailing list (acme@ietf.org). 37 Status of This Memo 39 This Internet-Draft is submitted in full conformance with the 40 provisions of BCP 78 and BCP 79. 42 Internet-Drafts are working documents of the Internet Engineering 43 Task Force (IETF). Note that other groups may also distribute 44 working documents as Internet-Drafts. The list of current Internet- 45 Drafts is at http://datatracker.ietf.org/drafts/current/. 47 Internet-Drafts are draft documents valid for a maximum of six months 48 and may be updated, replaced, or obsoleted by other documents at any 49 time. It is inappropriate to use Internet-Drafts as reference 50 material or to cite them other than as "work in progress." 52 This Internet-Draft will expire on September 14, 2017. 54 Copyright Notice 56 Copyright (c) 2017 IETF Trust and the persons identified as the 57 document authors. All rights reserved. 59 This document is subject to BCP 78 and the IETF Trust's Legal 60 Provisions Relating to IETF Documents 61 (http://trustee.ietf.org/license-info) in effect on the date of 62 publication of this document. Please review these documents 63 carefully, as they describe your rights and restrictions with respect 64 to this document. Code Components extracted from this document must 65 include Simplified BSD License text as described in Section 4.e of 66 the Trust Legal Provisions and are provided without warranty as 67 described in the Simplified BSD License. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 72 2. Deployment Model and Operator Experience . . . . . . . . . . 5 73 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 74 4. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 6 75 5. Character Encoding . . . . . . . . . . . . . . . . . . . . . 8 76 6. Message Transport . . . . . . . . . . . . . . . . . . . . . . 8 77 6.1. HTTPS Requests . . . . . . . . . . . . . . . . . . . . . 9 78 6.2. Request Authentication . . . . . . . . . . . . . . . . . 9 79 6.3. Request URI Integrity . . . . . . . . . . . . . . . . . . 10 80 6.3.1. "url" (URL) JWS header parameter . . . . . . . . . . 11 81 6.4. Replay protection . . . . . . . . . . . . . . . . . . . . 11 82 6.4.1. Replay-Nonce . . . . . . . . . . . . . . . . . . . . 12 83 6.4.2. "nonce" (Nonce) JWS header parameter . . . . . . . . 12 84 6.5. Rate limits . . . . . . . . . . . . . . . . . . . . . . . 13 85 6.6. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 13 86 7. Certificate Management . . . . . . . . . . . . . . . . . . . 15 87 7.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 15 88 7.1.1. Directory . . . . . . . . . . . . . . . . . . . . . . 17 89 7.1.2. Account Objects . . . . . . . . . . . . . . . . . . . 19 90 7.1.3. Order Objects . . . . . . . . . . . . . . . . . . . . 20 91 7.1.4. Authorization Objects . . . . . . . . . . . . . . . . 22 92 7.2. Getting a Nonce . . . . . . . . . . . . . . . . . . . . . 23 93 7.3. Account Creation . . . . . . . . . . . . . . . . . . . . 24 94 7.3.1. Changes of Terms of Service . . . . . . . . . . . . . 26 95 7.3.2. External Account Binding . . . . . . . . . . . . . . 27 96 7.3.3. Account Key Roll-over . . . . . . . . . . . . . . . . 29 97 7.3.4. Account deactivation . . . . . . . . . . . . . . . . 31 98 7.4. Applying for Certificate Issuance . . . . . . . . . . . . 32 99 7.4.1. Pre-Authorization . . . . . . . . . . . . . . . . . . 34 100 7.4.2. Downloading the Certificate . . . . . . . . . . . . . 36 101 7.5. Identifier Authorization . . . . . . . . . . . . . . . . 37 102 7.5.1. Responding to Challenges . . . . . . . . . . . . . . 38 103 7.5.2. Deactivating an Authorization . . . . . . . . . . . . 40 104 7.6. Certificate Revocation . . . . . . . . . . . . . . . . . 41 105 8. Identifier Validation Challenges . . . . . . . . . . . . . . 43 106 8.1. Key Authorizations . . . . . . . . . . . . . . . . . . . 45 107 8.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . 45 108 8.3. TLS with Server Name Indication (TLS SNI) . . . . . . . . 48 109 8.4. DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 110 8.5. Out-of-Band . . . . . . . . . . . . . . . . . . . . . . . 52 111 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 53 112 9.1. MIME Type: application/pem-certificate-chain . . . . . . 53 113 9.2. Well-Known URI for the HTTP Challenge . . . . . . . . . . 54 114 9.3. Replay-Nonce HTTP Header . . . . . . . . . . . . . . . . 54 115 9.4. "url" JWS Header Parameter . . . . . . . . . . . . . . . 54 116 9.5. "nonce" JWS Header Parameter . . . . . . . . . . . . . . 55 117 9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) . . . . 55 118 9.7. New Registries . . . . . . . . . . . . . . . . . . . . . 55 119 9.7.1. Fields in Account Objects . . . . . . . . . . . . . . 56 120 9.7.2. Fields in Order Objects . . . . . . . . . . . . . . . 57 121 9.7.3. Error Types . . . . . . . . . . . . . . . . . . . . . 58 122 9.7.4. Resource Types . . . . . . . . . . . . . . . . . . . 58 123 9.7.5. Identifier Types . . . . . . . . . . . . . . . . . . 59 124 9.7.6. Challenge Types . . . . . . . . . . . . . . . . . . . 59 125 10. Security Considerations . . . . . . . . . . . . . . . . . . . 60 126 10.1. Threat model . . . . . . . . . . . . . . . . . . . . . . 61 127 10.2. Integrity of Authorizations . . . . . . . . . . . . . . 62 128 10.3. Denial-of-Service Considerations . . . . . . . . . . . . 64 129 10.4. Server-Side Request Forgery . . . . . . . . . . . . . . 65 130 10.5. CA Policy Considerations . . . . . . . . . . . . . . . . 65 131 11. Operational Considerations . . . . . . . . . . . . . . . . . 66 132 11.1. DNS security . . . . . . . . . . . . . . . . . . . . . . 66 133 11.2. Default Virtual Hosts . . . . . . . . . . . . . . . . . 67 134 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 67 135 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 68 136 13.1. Normative References . . . . . . . . . . . . . . . . . . 68 137 13.2. Informative References . . . . . . . . . . . . . . . . . 70 138 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 71 140 1. Introduction 142 Certificates [RFC5280] in the Web PKI are most commonly used to 143 authenticate domain names. Thus, certificate authorities in the Web 144 PKI are trusted to verify that an applicant for a certificate 145 legitimately represents the domain name(s) in the certificate. 147 Different types of certificates reflect different kinds of CA 148 verification of information about the certificate subject. "Domain 149 Validation" (DV) certificates are by far the most common type. For 150 DV validation, the CA merely verifies that the requester has 151 effective control of the web server and/or DNS server for the domain, 152 but does not explicitly attempt to verify their real-world identity. 153 (This is as opposed to "Organization Validation" (OV) and "Extended 154 Validation" (EV) certificates, where the process is intended to also 155 verify the real-world identity of the requester.) 157 Existing Web PKI certificate authorities tend to run on a set of ad 158 hoc protocols for certificate issuance and identity verification. In 159 the case of DV certificates, a typical user experience is something 160 like: 162 o Generate a PKCS#10 [RFC2986] Certificate Signing Request (CSR). 164 o Cut-and-paste the CSR into a CA web page. 166 o Prove ownership of the domain by one of the following methods: 168 * Put a CA-provided challenge at a specific place on the web 169 server. 171 * Put a CA-provided challenge at a DNS location corresponding to 172 the target domain. 174 * Receive CA challenge at a (hopefully) administrator-controlled 175 e-mail address corresponding to the domain and then respond to 176 it on the CA's web page. 178 o Download the issued certificate and install it on their Web 179 Server. 181 With the exception of the CSR itself and the certificates that are 182 issued, these are all completely ad hoc procedures and are 183 accomplished by getting the human user to follow interactive natural- 184 language instructions from the CA rather than by machine-implemented 185 published protocols. In many cases, the instructions are difficult 186 to follow and cause significant confusion. Informal usability tests 187 by the authors indicate that webmasters often need 1-3 hours to 188 obtain and install a certificate for a domain. Even in the best 189 case, the lack of published, standardized mechanisms presents an 190 obstacle to the wide deployment of HTTPS and other PKIX-dependent 191 systems because it inhibits mechanization of tasks related to 192 certificate issuance, deployment, and revocation. 194 This document describes an extensible framework for automating the 195 issuance and domain validation procedure, thereby allowing servers 196 and infrastructural software to obtain certificates without user 197 interaction. Use of this protocol should radically simplify the 198 deployment of HTTPS and the practicality of PKIX authentication for 199 other protocols based on TLS [RFC5246]. 201 2. Deployment Model and Operator Experience 203 The guiding use case for ACME is obtaining certificates for websites 204 (HTTPS [RFC2818]). In this case, the user's web server is intended 205 to speak for one or more domains, and the process of certificate 206 issuance is intended to verify that this web server actually speaks 207 for the domain(s). 209 DV certificate validation commonly checks claims about properties 210 related to control of a domain name - properties that can be observed 211 by the certificate issuer in an interactive process that can be 212 conducted purely online. That means that under typical 213 circumstances, all steps in the request, verification, and issuance 214 process can be represented and performed by Internet protocols with 215 no out-of-band human intervention. 217 Prior to ACME, when deploying an HTTPS server, an operator typically 218 gets a prompt to generate a self-signed certificate. If the operator 219 were instead deploying an ACME-compatible web server, the experience 220 would be something like this: 222 o The ACME client prompts the operator for the intended domain 223 name(s) that the web server is to stand for. 225 o The ACME client presents the operator with a list of CAs from 226 which it could get a certificate. (This list will change over 227 time based on the capabilities of CAs and updates to ACME 228 configuration.) The ACME client might prompt the operator for 229 payment information at this point. 231 o The operator selects a CA. 233 o In the background, the ACME client contacts the CA and requests 234 that it issue a certificate for the intended domain name(s). 236 o Once the CA is satisfied, the certificate is issued and the ACME 237 client automatically downloads and installs it, potentially 238 notifying the operator via e-mail, SMS, etc. 240 o The ACME client periodically contacts the CA to get updated 241 certificates, stapled OCSP responses, or whatever else would be 242 required to keep the web server functional and its credentials up- 243 to-date. 245 In this way, it would be nearly as easy to deploy with a CA-issued 246 certificate as with a self-signed certificate. Furthermore, the 247 maintenance of that CA-issued certificate would require minimal 248 manual intervention. Such close integration of ACME with HTTPS 249 servers would allow the immediate and automated deployment of 250 certificates as they are issued, sparing the human administrator from 251 much of the time-consuming work described in the previous section. 253 3. Terminology 255 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 256 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 257 document are to be interpreted as described in RFC 2119 [RFC2119]. 259 The two main roles in ACME are "client" and "server". The ACME 260 client uses the protocol to request certificate management actions, 261 such as issuance or revocation. An ACME client therefore typically 262 runs on a web server, mail server, or some other server system which 263 requires valid TLS certificates. The ACME server runs at a 264 certification authority, and responds to client requests, performing 265 the requested actions if the client is authorized. 267 An ACME client is represented by an "account key pair". The client 268 uses the private key of this key pair to sign all messages sent to 269 the server. The server uses the public key to verify the 270 authenticity and integrity of messages from the client. 272 4. Protocol Overview 274 ACME allows a client to request certificate management actions using 275 a set of JSON messages carried over HTTPS. In many ways, ACME 276 functions much like a traditional CA, in which a user creates an 277 account, requests a certificate, and proves control of the domains in 278 that certificate in order for the CA to sign the requested 279 certificate. 281 The first phase of ACME is for the client to request an account with 282 the ACME server. The client generates an asymmetric key pair and 283 requests a new account, optionally providing contact information, 284 agreeing to terms of service, and/or associating the account with an 285 existing account in another system. The creation request is signed 286 with the generated private key to prove that the client controls it. 288 Client Server 290 Contact Information 291 ToS Agreement 292 Additional Data 293 Signature -------> 295 <------- Account 297 Once an account is registered, there are three major steps the client 298 needs to take to get a certificate: 300 1. Submit an order for a certificate to be issued 302 2. Prove control of any identifiers requested in the certificate 304 3. Await issuance and download the issued certificate 306 The client's order for a certificate describes the desired 307 certificate using a PKCS#10 Certificate Signing Request (CSR) plus a 308 few additional fields that capture semantics that are not supported 309 in the CSR format. If the server is willing to consider issuing such 310 a certificate, it responds with a list of requirements that the 311 client must satisfy before the certificate will be issued. 313 For example, in most cases, the server will require the client to 314 demonstrate that it controls the identifiers in the requested 315 certificate. Because there are many different ways to validate 316 possession of different types of identifiers, the server will choose 317 from an extensible set of challenges that are appropriate for the 318 identifier being claimed. The client responds with a set of 319 responses that tell the server which challenges the client has 320 completed. The server then validates the challenges to check that 321 the client has accomplished the challenge. 323 Once the validation process is complete and the server is satisfied 324 that the client has met its requirements, the server will issue the 325 requested certificate and make it available to the client. 327 Order 328 Signature -------> 329 Required 330 <------- Authorizations 332 Responses 333 Signature -------> 335 <~~~~~~~~Validation~~~~~~~~> 337 <------- Certificate 339 To revoke a certificate, the client sends a signed revocation request 340 indicating the certificate to be revoked: 342 Client Server 344 Revocation request 345 Signature --------> 347 <-------- Result 349 Note that while ACME is defined with enough flexibility to handle 350 different types of identifiers in principle, the primary use case 351 addressed by this document is the case where domain names are used as 352 identifiers. For example, all of the identifier validation 353 challenges described in Section 8 below address validation of domain 354 names. The use of ACME for other identifiers will require further 355 specification, in order to describe how these identifiers are encoded 356 in the protocol, and what types of validation challenges the server 357 might require. 359 5. Character Encoding 361 All requests and responses sent via HTTP by ACME clients, ACME 362 servers, and validation servers as well as any inputs for digest 363 computations MUST be encoded using the UTF-8 [RFC3629] character set. 365 6. Message Transport 367 Communications between an ACME client and an ACME server are done 368 over HTTPS, using JSON Web Signature (JWS) [RFC7515] to provide some 369 additional security properties for messages sent from the client to 370 the server. HTTPS provides server authentication and 371 confidentiality. With some ACME-specific extensions, JWS provides 372 authentication of the client's request payloads, anti-replay 373 protection, and integrity for the HTTPS request URI. 375 6.1. HTTPS Requests 377 Each ACME function is accomplished by the client sending a sequence 378 of HTTPS requests to the server, carrying JSON messages 379 [RFC2818][RFC7159]. Use of HTTPS is REQUIRED. Each subsection of 380 Section 7 below describes the message formats used by the function 381 and the order in which messages are sent. 383 In most HTTPS transactions used by ACME, the ACME client is the HTTPS 384 client and the ACME server is the HTTPS server. The ACME server acts 385 as an HTTP and HTTPS client when validating challenges via HTTP. 387 ACME clients SHOULD send a User-Agent header in accordance with 388 [RFC7231], including the name and version of the ACME software in 389 addition to the name and version of the underlying HTTP client 390 software. 392 ACME clients SHOULD send an Accept-Language header in accordance with 393 [RFC7231] to enable localization of error messages. 395 ACME servers that are intended to be generally accessible need to use 396 Cross-Origin Resource Sharing (CORS) in order to be accessible from 397 browser-based clients [W3C.CR-cors-20130129]. Such servers SHOULD 398 set the Access-Control-Allow-Origin header field to the value "*". 400 Binary fields in the JSON objects used by ACME are encoded using 401 base64url encoding described in [RFC4648] Section 5, according to the 402 profile specified in JSON Web Signature [RFC7515] Section 2. This 403 encoding uses a URL safe character set. Trailing '=' characters MUST 404 be stripped. 406 6.2. Request Authentication 408 All ACME requests with a non-empty body MUST encapsulate their 409 payload in a JSON Web Signature (JWS) [RFC7515] object, signed using 410 the account's private key unless otherwise specified. The server 411 MUST verify the JWS before processing the request. Encapsulating 412 request bodies in JWS provides authentication of requests. 414 JWS objects sent in ACME requests MUST meet the following additional 415 criteria: 417 o The JWS MUST NOT have the value "none" in its "alg" field 419 o The JWS MUST NOT have a MAC-based algorithm in its "alg" field 421 o The JWS Protected Header MUST include the following fields: 423 * "alg" 425 * "jwk" (only for requests to new-account and revoke-cert 426 resources) 428 * "kid" (for all other requests). 430 * "nonce" (defined below) 432 * "url" (defined below) 434 The "jwk" and "kid" fields are mutually exclusive. Servers MUST 435 reject requests that contain both. 437 For new-account requests, and for revoke-cert requests authenticated 438 by certificate key, there MUST be a "jwk" field. 440 For all other requests, there MUST be a "kid" field. This field must 441 contain the account URI received by POSTing to the new-account 442 resource. 444 Note that authentication via signed JWS request bodies implies that 445 GET requests are not authenticated. Servers MUST NOT respond to GET 446 requests for resources that might be considered sensitive. Account 447 resources are the only sensitive resources defined in this 448 specification. 450 If the client sends a JWS signed with an algorithm that the server 451 does not support, then the server MUST return an error with status 452 code 400 (Bad Request) and type 453 "urn:ietf:params:acme:error:badSignatureAlgorithm". The problem 454 document returned with the error MUST include an "algorithms" field 455 with an array of supported "alg" values. 457 In the examples below, JWS objects are shown in the JSON or flattened 458 JSON serialization, with the protected header and payload expressed 459 as base64url(content) instead of the actual base64-encoded value, so 460 that the content is readable. 462 6.3. Request URI Integrity 464 It is common in deployment for the entity terminating TLS for HTTPS 465 to be different from the entity operating the logical HTTPS server, 466 with a "request routing" layer in the middle. For example, an ACME 467 CA might have a content delivery network terminate TLS connections 468 from clients so that it can inspect client requests for denial-of- 469 service protection. 471 These intermediaries can also change values in the request that are 472 not signed in the HTTPS request, e.g., the request URI and headers. 473 ACME uses JWS to provide an integrity mechanism, which protects 474 against an intermediary changing the request URI to another ACME URI. 476 As noted above, all ACME request objects carry a "url" parameter in 477 their protected header. This header parameter encodes the URL to 478 which the client is directing the request. On receiving such an 479 object in an HTTP request, the server MUST compare the "url" 480 parameter to the request URI. If the two do not match, then the 481 server MUST reject the request as unauthorized. 483 Except for the directory resource, all ACME resources are addressed 484 with URLs provided to the client by the server. For these resources, 485 the client MUST set the "url" field to the exact string provided by 486 the server (rather than performing any re-encoding on the URL). The 487 server SHOULD perform the corresponding string equality check, 488 configuring each resource with the URL string provided to clients and 489 having the resource check that requests have the same string in their 490 "url" fields. 492 6.3.1. "url" (URL) JWS header parameter 494 The "url" header parameter specifies the URL [RFC3986] to which this 495 JWS object is directed. The "url" parameter MUST be carried in the 496 protected header of the JWS. The value of the "url" header MUST be a 497 string representing the URL. 499 6.4. Replay protection 501 In order to protect ACME resources from any possible replay attacks, 502 ACME requests have a mandatory anti-replay mechanism. This mechanism 503 is based on the server maintaining a list of nonces that it has 504 issued to clients, and requiring any signed request from the client 505 to carry such a nonce. 507 An ACME server provides nonces to clients using the Replay-Nonce 508 header field, as specified below. The server MUST include a Replay- 509 Nonce header field in every successful response to a POST request and 510 SHOULD provide it in error responses as well. 512 Every JWS sent by an ACME client MUST include, in its protected 513 header, the "nonce" header parameter, with contents as defined below. 514 As part of JWS verification, the ACME server MUST verify that the 515 value of the "nonce" header is a value that the server previously 516 provided in a Replay-Nonce header field. Once a nonce value has 517 appeared in an ACME request, the server MUST consider it invalid, in 518 the same way as a value it had never issued. 520 When a server rejects a request because its nonce value was 521 unacceptable (or not present), it MUST provide HTTP status code 400 522 (Bad Request), and indicate the ACME error type 523 "urn:ietf:params:acme:error:badNonce". An error response with the 524 "badNonce" error type MUST include a Replay-Nonce header with a fresh 525 nonce. On receiving such a response, a client SHOULD retry the 526 request using the new nonce. 528 The precise method used to generate and track nonces is up to the 529 server. For example, the server could generate a random 128-bit 530 value for each response, keep a list of issued nonces, and strike 531 nonces from this list as they are used. 533 6.4.1. Replay-Nonce 535 The "Replay-Nonce" header field includes a server-generated value 536 that the server can use to detect unauthorized replay in future 537 client requests. The server should generate the value provided in 538 Replay-Nonce in such a way that they are unique to each message, with 539 high probability. 541 The value of the Replay-Nonce field MUST be an octet string encoded 542 according to the base64url encoding described in Section 2 of 543 [RFC7515]. Clients MUST ignore invalid Replay-Nonce values. 545 base64url = [A-Z] / [a-z] / [0-9] / "-" / "_" 547 Replay-Nonce = *base64url 549 The Replay-Nonce header field SHOULD NOT be included in HTTP request 550 messages. 552 6.4.2. "nonce" (Nonce) JWS header parameter 554 The "nonce" header parameter provides a unique value that enables the 555 verifier of a JWS to recognize when replay has occurred. The "nonce" 556 header parameter MUST be carried in the protected header of the JWS. 558 The value of the "nonce" header parameter MUST be an octet string, 559 encoded according to the base64url encoding described in Section 2 of 560 [RFC7515]. If the value of a "nonce" header parameter is not valid 561 according to this encoding, then the verifier MUST reject the JWS as 562 malformed. 564 6.5. Rate limits 566 Creation of resources can be rate limited to ensure fair usage and 567 prevent abuse. Once the rate limit is exceeded, the server MUST 568 respond with an error with the type 569 "urn:ietf:params:acme:error:rateLimited". Additionally, the server 570 SHOULD send a "Retry-After" header indicating when the current 571 request may succeed again. If multiple rate limits are in place, 572 that is the time where all rate limits allow access again for the 573 current request with exactly the same parameters. 575 In addition to the human readable "detail" field of the error 576 response, the server MAY send one or multiple tokens in the "Link" 577 header pointing to documentation about the specific hit rate limits 578 using the "urn:ietf:params:acme:documentation" relation. 580 6.6. Errors 582 Errors can be reported in ACME both at the HTTP layer and within 583 challenge objects as defined in {{identifier-validation-challenges}. 584 ACME servers can return responses with an HTTP error response code 585 (4XX or 5XX). For example: If the client submits a request using a 586 method not allowed in this document, then the server MAY return 587 status code 405 (Method Not Allowed). 589 When the server responds with an error status, it SHOULD provide 590 additional information using a problem document [RFC7807]. To 591 facilitate automatic response to errors, this document defines the 592 following standard tokens for use in the "type" field (within the 593 "urn:ietf:params:acme:error:" namespace): 595 +-----------------------+-------------------------------------------+ 596 | Type | Description | 597 +-----------------------+-------------------------------------------+ 598 | badCSR | The CSR is unacceptable (e.g., due to a | 599 | | short key) | 600 | | | 601 | badNonce | The client sent an unacceptable anti- | 602 | | replay nonce | 603 | | | 604 | badSignatureAlgorithm | The JWS was signed with an algorithm the | 605 | | server does not support | 606 | | | 607 | invalidContact | The contact URI for an account was | 608 | | invalid | 609 | | | 610 | malformed | The request message was malformed | 611 | | | 612 | rateLimited | The request exceeds a rate limit | 613 | | | 614 | rejectedIdentifier | The server will not issue for the | 615 | | identifier | 616 | | | 617 | serverInternal | The server experienced an internal error | 618 | | | 619 | unauthorized | The client lacks sufficient authorization | 620 | | | 621 | unsupportedIdentifier | Identifier is not supported, but may be | 622 | | in future | 623 | | | 624 | userActionRequired | Visit the "instance" URL and take actions | 625 | | specified there | 626 | | | 627 | badRevocationReason | The revocation reason provided is not | 628 | | allowed by the server | 629 | | | 630 | caa | CAA records forbid the CA from issuing | 631 | | | 632 | dns | There was a problem with a DNS query | 633 | | | 634 | connection | The server could not connect to | 635 | | validation target | 636 | | | 637 | tls | The server received a TLS error during | 638 | | validation | 639 | | | 640 | incorrectResponse | Response received didn't match the | 641 | | challenge's requirements | 642 +-----------------------+-------------------------------------------+ 643 This list is not exhaustive. The server MAY return errors whose 644 "type" field is set to a URI other than those defined above. Servers 645 MUST NOT use the ACME URN namespace for errors other than the 646 standard types. Clients SHOULD display the "detail" field of all 647 errors. 649 7. Certificate Management 651 In this section, we describe the certificate management functions 652 that ACME enables: 654 o Account Creation 656 o Ordering a Certificate 658 o Identifier Authorization 660 o Certificate Issuance 662 o Certificate Revocation 664 7.1. Resources 666 ACME is structured as a REST application with a few types of 667 resources: 669 o Account resources, representing information about an account 670 (Section 7.1.2, Section 7.3) 672 o Order resources, representing an account's requests to issue 673 certificates (Section 7.1.3) 675 o Authorization resources, representing an account's authorization 676 to act for an identifier (Section 7.1.4) 678 o Challenge resources, representing a challenge to prove control of 679 an identifier (Section 7.5, Section 8) 681 o Certificate resources, representing issued certificates 682 (Section 7.4.2) 684 o A "directory" resource (Section 7.1.1) 686 o A "new-nonce" resource (Section 7.2) 688 o A "new-account" resource (Section 7.3) 690 o A "new-order" resource (Section 7.4) 691 o A "revoke-certificate" resource (Section 7.6) 693 o A "key-change" resource (Section 7.3.3) 695 The server MUST provide "directory" and "new-nonce" resources. 697 ACME uses different URIs for different management functions. Each 698 function is listed in a directory along with its corresponding URI, 699 so clients only need to be configured with the directory URI. These 700 URIs are connected by a few different link relations [RFC5988]. 702 The "up" link relation is used with challenge resources to indicate 703 the authorization resource to which a challenge belongs. It is also 704 used from certificate resources to indicate a resource from which the 705 client may fetch a chain of CA certificates that could be used to 706 validate the certificate in the original resource. 708 The "index" link relation is present on all resources other than the 709 directory and indicates the URL of the directory. 711 The following diagram illustrates the relations between resources on 712 an ACME server. For the most part, these relations are expressed by 713 URLs provided as strings in the resources' JSON representations. 714 Lines with labels in quotes indicate HTTP link relations. 716 directory 717 | 718 |--> new-nonce 719 | 720 ----------------------------------+ 721 | | | | 722 | | | | 723 V V V V 724 new-account new-authz new-order revoke-cert 725 | | | 726 | | | 727 V | V 728 acct | order --------> cert 729 | | ^ | 730 | | | "up" | "up" 731 | V | V 732 +------> authz cert-chain 733 | ^ 734 | | "up" 735 V | 736 challenge 738 The following table illustrates a typical sequence of requests 739 required to establish a new account with the server, prove control of 740 an identifier, issue a certificate, and fetch an updated certificate 741 some time after issuance. The "->" is a mnemonic for a Location 742 header pointing to a created resource. 744 +----------------------+------------------+----------------+ 745 | Action | Request | Response | 746 +----------------------+------------------+----------------+ 747 | Get a nonce | HEAD new-nonce | 204 | 748 | | | | 749 | Create account | POST new-account | 201 -> account | 750 | | | | 751 | Submit an order | POST new-order | 201 -> order | 752 | | | | 753 | Fetch challenges | GET authz | 200 | 754 | | | | 755 | Respond to challenge | POST challenge | 200 | 756 | | | | 757 | Poll for status | GET authz | 200 | 758 | | | | 759 | Check for new cert | GET cert | 200 | 760 +----------------------+------------------+----------------+ 762 The remainder of this section provides the details of how these 763 resources are structured and how the ACME protocol makes use of them. 765 7.1.1. Directory 767 In order to help clients configure themselves with the right URIs for 768 each ACME operation, ACME servers provide a directory object. This 769 should be the only URL needed to configure clients. It is a JSON 770 object, whose keys are drawn from the following table and whose 771 values are the corresponding URLs. 773 +-------------+--------------------+ 774 | Key | URL in value | 775 +-------------+--------------------+ 776 | new-nonce | New nonce | 777 | | | 778 | new-account | New account | 779 | | | 780 | new-order | New order | 781 | | | 782 | new-authz | New authorization | 783 | | | 784 | revoke-cert | Revoke certificate | 785 | | | 786 | key-change | Key change | 787 +-------------+--------------------+ 789 There is no constraint on the actual URI of the directory except that 790 it should be different from the other ACME server resources' URIs, 791 and that it should not clash with other services. For instance: 793 o a host which functions as both an ACME and a Web server may want 794 to keep the root path "/" for an HTML "front page", and place the 795 ACME directory under the path "/acme". 797 o a host which only functions as an ACME server could place the 798 directory under the path "/". 800 The object MAY additionally contain a key "meta". If present, it 801 MUST be a JSON object; each field in the object is an item of 802 metadata relating to the service provided by the ACME server. 804 The following metadata items are defined, all of which are OPTIONAL: 806 "terms-of-service" (optional, string): A URI identifying the current 807 terms of service. 809 "website" (optional, string): An HTTP or HTTPS URL locating a 810 website providing more information about the ACME server. 812 "caa-identities" (optional, array of string): Each string MUST be a 813 lowercase hostname which the ACME server recognizes as referring 814 to itself for the purposes of CAA record validation as defined in 815 [RFC6844]. This allows clients to determine the correct issuer 816 domain name to use when configuring CAA records. 818 Clients access the directory by sending a GET request to the 819 directory URI. 821 HTTP/1.1 200 OK 822 Content-Type: application/json 824 { 825 "new-nonce": "https://example.com/acme/new-nonce", 826 "new-account": "https://example.com/acme/new-account", 827 "new-order": "https://example.com/acme/new-order", 828 "new-authz": "https://example.com/acme/new-authz", 829 "revoke-cert": "https://example.com/acme/revoke-cert", 830 "key-change": "https://example.com/acme/key-change", 831 "meta": { 832 "terms-of-service": "https://example.com/acme/terms", 833 "website": "https://www.example.com/", 834 "caa-identities": ["example.com"] 835 } 836 } 838 7.1.2. Account Objects 840 An ACME account resource represents a set of metadata associated with 841 an account. Account resources have the following structure: 843 status (required, string): The status of this account. Possible 844 values are: "valid", "deactivated", and "revoked". The value 845 "deactivated" should be used to indicate user initiated 846 deactivation whereas "revoked" should be used to indicate 847 administratively initiated deactivation. 849 contact (optional, array of string): An array of URIs that the 850 server can use to contact the client for issues related to this 851 account. For example, the server may wish to notify the client 852 about server-initiated revocation or certificate expiration. 854 terms-of-service-agreed (optional, boolean): Including this field in 855 a new-account request, with a value of true, indicates the 856 client's agreement with the terms of service. This field is not 857 updateable by the client. 859 orders (required, string): A URI from which a list of orders 860 submitted by this account can be fetched via a GET request, as 861 described in Section 7.1.2.1. 863 { 864 "contact": [ 865 "mailto:cert-admin@example.com", 866 "tel:+12025551212" 867 ], 868 "terms-of-service-agreed": true, 869 "orders": "https://example.com/acme/acct/1/orders" 870 } 872 7.1.2.1. Orders List 874 Each account object includes an "orders" URI from which a list of 875 orders created by the account can be fetched via GET request. The 876 result of the GET request MUST be a JSON object whose "orders" field 877 is an array of URIs, each identifying an order belonging to the 878 account. The server SHOULD include pending orders, and SHOULD NOT 879 include orders that are invalid in the array of URIs. The server MAY 880 return an incomplete list, along with a Link header with a "next" 881 link relation indicating where further entries can be acquired. 883 HTTP/1.1 200 OK 884 Content-Type: application/json 885 Link: href="/acme/acct/1/orders?cursor=2", rel="next" 887 { 888 "orders": [ 889 "https://example.com/acme/acct/1/order/1", 890 "https://example.com/acme/acct/1/order/2", 891 /* 47 more URLs not shown for example brevity */ 892 "https://example.com/acme/acct/1/order/50" 893 ] 894 } 896 7.1.3. Order Objects 898 An ACME order object represents a client's request for a certificate 899 and is used to track the progress of that order through to issuance. 900 Thus, the object contains information about the requested 901 certificate, the authorizations that the server requires the client 902 to complete, and any certificates that have resulted from this order. 904 status (required, string): The status of this order. Possible 905 values are: "pending", "processing", "valid", and "invalid". 907 expires (optional, string): The timestamp after which the server 908 will consider this order invalid, encoded in the format specified 909 in RFC 3339 [RFC3339]. This field is REQUIRED for objects with 910 "pending" or "valid" in the status field. 912 csr (required, string): A CSR encoding the parameters for the 913 certificate being requested [RFC2986]. The CSR is sent in the 914 base64url-encoded version of the DER format. (Note: Because this 915 field uses base64url, and does not include headers, it is 916 different from PEM.) 918 notBefore (optional, string): The requested value of the notBefore 919 field in the certificate, in the date format defined in [RFC3339]. 921 notAfter (optional, string): The requested value of the notAfter 922 field in the certificate, in the date format defined in [RFC3339]. 924 error (optional, object): The error that occurred while processing 925 the order, if any. This field is structured as a problem document 926 [RFC7807]. 928 authorizations (required, array of string): For pending orders, the 929 authorizations that the client needs to complete before the 930 requested certificate can be issued (see Section 7.5). For final 931 orders, the authorizations that were completed. Each entry is a 932 URL from which an authorization can be fetched with a GET request. 934 certificate (optional, string): A URL for the certificate that has 935 been issued in response to this order. 937 { 938 "status": "pending", 939 "expires": "2015-03-01T14:09:00Z", 941 "csr": "jcRf4uXra7FGYW5ZMewvV...rhlnznwy8YbpMGqwidEXfE", 942 "notBefore": "2016-01-01T00:00:00Z", 943 "notAfter": "2016-01-08T00:00:00Z", 945 "authorizations": [ 946 "https://example.com/acme/authz/1234", 947 "https://example.com/acme/authz/2345" 948 ], 950 "certificate": "https://example.com/acme/cert/1234" 951 } 953 The elements of the "authorizations" array are immutable once set. 954 The server MUST NOT change the contents of the "authorizations" array 955 after it is created. If a client observes a change in the contents 956 of the "authorizations" array, then it SHOULD consider the order 957 invalid. 959 The "authorizations" array in the challenge SHOULD reflect all 960 authorizations that the CA takes into account in deciding to issue, 961 even if some authorizations were fulfilled in earlier orders or in 962 pre-authorization transactions. For example, if a CA allows multiple 963 orders to be fulfilled based on a single authorization transaction, 964 then it SHOULD reflect that authorization in all of the order. 966 7.1.4. Authorization Objects 968 An ACME authorization object represents a server's authorization for 969 an account to represent an identifier. In addition to the 970 identifier, an authorization includes several metadata fields, such 971 as the status of the authorization (e.g., "pending", "valid", or 972 "revoked") and which challenges were used to validate possession of 973 the identifier. 975 The structure of an ACME authorization resource is as follows: 977 identifier (required, object): The identifier that the account is 978 authorized to represent 980 type (required, string): The type of identifier. 982 value (required, string): The identifier itself. 984 status (required, string): The status of this authorization. 985 Possible values are: "pending", "processing", "valid", "invalid" 986 and "revoked". 988 expires (optional, string): The timestamp after which the server 989 will consider this authorization invalid, encoded in the format 990 specified in RFC 3339 [RFC3339]. This field is REQUIRED for 991 objects with "valid" in the "status" field. 993 scope (optional, string): If this field is present, then it MUST 994 contain a URI for an order resource, such that this authorization 995 is only valid for that resource. If this field is absent, then 996 the CA MUST consider this authorization valid for all orders until 997 the authorization expires. 999 challenges (required, array of objects): The challenges that the 1000 client can fulfill in order to prove possession of the identifier 1001 (for pending authorizations). For final authorizations, the 1002 challenges that were used. Each array entry is an object with 1003 parameters required to validate the challenge. A client should 1004 attempt to fulfill one of these challenges, and a server should 1005 consider any one of the challenges sufficient to make the 1006 authorization valid. For final authorizations it contains the 1007 challenges that were completed. 1009 The only type of identifier defined by this specification is a fully- 1010 qualified domain name (type: "dns"). If a domain name contains non- 1011 ASCII Unicode characters it MUST be encoded using the rules defined 1012 in [RFC3492]. Servers MUST verify any identifier values that begin 1013 with the ASCII Compatible Encoding prefix "xn-" as defined in 1014 [RFC5890] are properly encoded. Wildcard domain names (with "*" as 1015 the first label) MUST NOT be included in authorization objects. 1017 Section 8 describes a set of challenges for domain name validation. 1019 { 1020 "status": "valid", 1021 "expires": "2015-03-01T14:09:00Z", 1023 "identifier": { 1024 "type": "dns", 1025 "value": "example.org" 1026 }, 1028 "challenges": [ 1029 { 1030 "type": "http-01", 1031 "status": "valid", 1032 "validated": "2014-12-01T12:05:00Z", 1033 "keyAuthorization": "SXQe-2XODaDxNR...vb29HhjjLPSggwiE" 1034 } 1035 ] 1036 } 1038 7.2. Getting a Nonce 1040 Before sending a POST request to the server, an ACME client needs to 1041 have a fresh anti-replay nonce to put in the "nonce" header of the 1042 JWS. In most cases, the client will have gotten a nonce from a 1043 previous request. However, the client might sometimes need to get a 1044 new nonce, e.g., on its first request to the server or if an existing 1045 nonce is no longer valid. 1047 To get a fresh nonce, the client sends a HEAD request to the new- 1048 nonce resource on the server. The server's response MUST include a 1049 Replay-Nonce header field containing a fresh nonce, and SHOULD have 1050 status code 204 (No Content). The server SHOULD also respond to GET 1051 requests for this resource, returning an empty body (while still 1052 providing a Replay-Nonce header) with a 204 (No Content) status. 1054 HEAD /acme/new-nonce HTTP/1.1 1055 Host: example.com 1057 HTTP/1.1 204 No Content 1058 Replay-Nonce: oFvnlFP1wIhRlYS2jTaXbA 1059 Cache-Control: no-store 1061 Proxy caching of responses from the new-nonce resource can cause 1062 clients receive the same nonce repeatedly, leading to badNonce 1063 errors. The server MUST include a Cache-Control header field with 1064 the "no-store" directive in responses for the new-nonce resource, in 1065 order to prevent caching of this resource. 1067 7.3. Account Creation 1069 A client creates a new account with the server by sending a POST 1070 request to the server's new-account URI. The body of the request is 1071 a stub account object containing the "contact" field and optionally 1072 the "terms-of-service-agreed" field. 1074 POST /acme/new-account HTTP/1.1 1075 Host: example.com 1076 Content-Type: application/jose+json 1078 { 1079 "protected": base64url({ 1080 "alg": "ES256", 1081 "jwk": {...}, 1082 "nonce": "6S8IqOGY7eL2lsGoTZYifg", 1083 "url": "https://example.com/acme/new-account" 1084 }), 1085 "payload": base64url({ 1086 "terms-of-service-agreed": true, 1087 "contact": [ 1088 "mailto:cert-admin@example.com", 1089 "tel:+12025551212" 1090 ] 1091 }), 1092 "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I" 1093 } 1095 The server MUST ignore any values provided in the "orders" fields in 1096 account bodies sent by the client, as well as any other fields that 1097 it does not recognize. If new fields are specified in the future, 1098 the specification of those fields MUST describe whether they can be 1099 provided by the client. 1101 In general, the server MUST ignore any fields in the request object 1102 that it does not recognize. In particular, it MUST NOT reflect 1103 unrecognized fields in the resulting account object. This allows 1104 clients to detect when servers do not support an extension field. 1106 The server SHOULD validate that the contact URLs in the "contact" 1107 field are valid and supported by the server. If the client provides 1108 the server with an invalid or unsupported contact URL, then the 1109 server MUST return an error of type "invalidContact", with a 1110 description describing the error and what types of contact URL the 1111 server considers acceptable. 1113 The server creates an account and stores the public key used to 1114 verify the JWS (i.e., the "jwk" element of the JWS header) to 1115 authenticate future requests from the account. The server returns 1116 this account object in a 201 (Created) response, with the account URI 1117 in a Location header field. 1119 If the server already has an account registered with the provided 1120 account key, then it MUST return a response with a 200 (OK) status 1121 code and provide the URI of that account in the Location header 1122 field. This allows a client that has an account key but not the 1123 corresponding account URI to recover the account URI. 1125 If the server wishes to present the client with terms under which the 1126 ACME service is to be used, it MUST indicate the URI where such terms 1127 can be accessed in the "terms-of-service" subfield of the "meta" 1128 field in the directory object, and the server MUST reject new-account 1129 requests that do not have the "terms-of-service-agreed" set to 1130 "true". Clients SHOULD NOT automatically agree to terms by default. 1131 Rather, they SHOULD require some user interaction for agreement to 1132 terms. 1134 HTTP/1.1 201 Created 1135 Content-Type: application/json 1136 Replay-Nonce: D8s4D2mLs8Vn-goWuPQeKA 1137 Location: https://example.com/acme/acct/1 1138 Link: ;rel="index" 1140 { 1141 "status": "valid", 1143 "contact": [ 1144 "mailto:cert-admin@example.com", 1145 "tel:+12025551212" 1146 ] 1147 } 1148 If the client wishes to update this information in the future, it 1149 sends a POST request with updated information to the account URI. 1150 The server MUST ignore any updates to "order" fields or any other 1151 fields it does not recognize. 1153 For example, to update the contact information in the above account, 1154 the client could send the following request: 1156 POST /acme/acct/1 HTTP/1.1 1157 Host: example.com 1158 Content-Type: application/jose+json 1160 { 1161 "protected": base64url({ 1162 "alg": "ES256", 1163 "kid": "https://example.com/acme/acct/1", 1164 "nonce": "ax5RnthDqp_Yf4_HZnFLmA", 1165 "url": "https://example.com/acme/acct/1" 1166 }), 1167 "payload": base64url({ 1168 "contact": [ 1169 "mailto:certificates@example.com", 1170 "tel:+12125551212" 1171 ] 1172 }), 1173 "signature": "hDXzvcj8T6fbFbmn...rDzXzzvzpRy64N0o" 1174 } 1176 Servers SHOULD NOT respond to GET requests for account resources as 1177 these requests are not authenticated. If a client wishes to query 1178 the server for information about its account (e.g., to examine the 1179 "contact" or "certificates" fields), then it SHOULD do so by sending 1180 a POST request with an empty update. That is, it should send a JWS 1181 whose payload is an empty object ({}). 1183 7.3.1. Changes of Terms of Service 1185 As described above, a client can indicate its agreement with the CA's 1186 terms of service by setting the "terms-of-service-agreed" field in 1187 its account object to "true". 1189 If the server has changed its terms of service since a client 1190 initially agreed, and the server is unwilling to process a request 1191 without explicit agreement to the new terms, then it MUST return an 1192 error response with status code 403 (Forbidden) and type 1193 "urn:ietf:params:acme:error:userActionRequired". This response MUST 1194 include a Link header with link relation "terms-of-service" and the 1195 latest terms-of-service URL. 1197 The problem document returned with the error MUST also include an 1198 "instance" field, indicating a URL that the client should direct a 1199 human user to visit in order for instructions on how to agree to the 1200 terms. 1202 HTTP/1.1 403 Forbidden 1203 Replay-Nonce: IXVHDyxIRGcTE0VSblhPzw 1204 Content-Type: application/problem+json 1205 Content-Language: en 1207 { 1208 "type": "urn:ietf:params:acme:error:userActionRequired", 1209 "detail": "Terms of service have changed", 1210 "instance": "http://example.com/agreement/?token=W8Ih3PswD-8" 1211 } 1213 7.3.2. External Account Binding 1215 The server MAY require a value to be present for the "external- 1216 account-binding" field. This can be used to an ACME account with an 1217 existing account in a non-ACME system, such as a CA customer 1218 database. 1220 To enable ACME account binding, a CA needs to provision the ACME 1221 client with a MAC key and a key identifier. The key identifier MUST 1222 be an ASCII string. The MAC key SHOULD be provided in base64url- 1223 encoded form, to maximize compatibility between provisioning systems 1224 and ACME clients. 1226 The ACME client then computes a binding JWS to indicate the external 1227 account's approval of the ACME account key. The payload of this JWS 1228 is the account key being registered, in JWK form. The protected 1229 header of the JWS MUST meet the following criteria: 1231 o The "alg" field MUST indicate a MAC-based algorithm 1233 o The "kid" field MUST contain the key identifier provided by the CA 1235 o The "nonce" field MUST NOT be present 1237 o The "url" field MUST be set to the same value as the outer JWS 1239 The "signature" field of the JWS will contain the MAC value computed 1240 with the MAC key provided by the CA. 1242 POST /acme/new-account HTTP/1.1 1243 Host: example.com 1244 Content-Type: application/jose+json 1246 { 1247 "protected": base64url({ 1248 "alg": "ES256", 1249 "jwk": /* account key */, 1250 "nonce": "K60BWPrMQG9SDxBDS_xtSw", 1251 "url": "https://example.com/acme/new-account" 1252 }), 1253 "payload": base64url({ 1254 "contact": ["mailto:example@anonymous.invalid"], 1255 "terms-of-service-agreed": true, 1257 "external-account-binding": { 1258 "protected": base64url({ 1259 "alg": "HS256", 1260 "kid": /* key identifier from CA */, 1261 "url": "https://example.com/acme/new-account" 1262 }), 1263 "payload": base64url(/* same as in "jwk" above */), 1264 "signature": /* MAC using MAC key from CA */ 1265 } 1266 }), 1267 "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4" 1268 } 1270 When a CA receives a new-account request containing an "external- 1271 account-binding" field, it decides whether or not to verify the 1272 binding. If the CA does not verify the binding, then it MUST NOT 1273 reflect the "external-account-binding" field in the resulting account 1274 object (if any). To verify the account binding, the CA MUST take the 1275 following steps: 1277 1. Verify that the value of the field is a well-formed JWS 1279 2. Verify that the JWS protected meets the above criteria 1281 3. Retrieve the MAC key corresponding to the key identifier in the 1282 "kid" field 1284 4. Verify that the MAC on the JWS verifies using that MAC key 1286 5. Verify that the payload of the JWS represents the same key as was 1287 used to verify the outer JWS (i.e., the "jwk" field of the outer 1288 JWS) 1290 If all of these checks pass and the CA creates a new account, then 1291 the CA may consider the new account associated with the external 1292 account corresponding to the MAC key and MUST reflect value of the 1293 "external-account-binding" field in the resulting account object. If 1294 any of these checks fail, then the CA MUST reject the new-account 1295 request. 1297 7.3.3. Account Key Roll-over 1299 A client may wish to change the public key that is associated with an 1300 account in order to recover from a key compromise or proactively 1301 mitigate the impact of an unnoticed key compromise. 1303 To change the key associated with an account, the client first 1304 constructs a key-change object describing the change that it would 1305 like the server to make: 1307 account (required, string): The URL for account being modified. The 1308 content of this field MUST be the exact string provided in the 1309 Location header field in response to the new-account request that 1310 created the account. 1312 newKey (required, JWK): The JWK representation of the new key 1314 The client then encapsulates the key-change object in a JWS, signed 1315 with the requested new account key (i.e., the key matching the 1316 "newKey" value). 1318 The outer JWS MUST meet the normal requirements for an ACME JWS (see 1319 Section 6.2). The inner JWS MUST meet the normal requirements, with 1320 the following exceptions: 1322 o The inner JWS MUST have the same "url" parameter as the outer JWS. 1324 o The inner JWS is NOT REQUIRED to have a "nonce" parameter. The 1325 server MUST ignore any value provided for the "nonce" header 1326 parameter. 1328 This transaction has signatures from both the old and new keys so 1329 that the server can verify that the holders of the two keys both 1330 agree to the change. The signatures are nested to preserve the 1331 property that all signatures on POST messages are signed by exactly 1332 one key. 1334 POST /acme/key-change HTTP/1.1 1335 Host: example.com 1336 Content-Type: application/jose+json 1338 { 1339 "protected": base64url({ 1340 "alg": "ES256", 1341 "jwk": /* old key */, 1342 "nonce": "K60BWPrMQG9SDxBDS_xtSw", 1343 "url": "https://example.com/acme/key-change" 1344 }), 1345 "payload": base64url({ 1346 "protected": base64url({ 1347 "alg": "ES256", 1348 "jwk": /* new key */, 1349 "url": "https://example.com/acme/key-change" 1350 }), 1351 "payload": base64url({ 1352 "account": "https://example.com/acme/acct/1", 1353 "newKey": /* new key */ 1354 }), 1355 "signature": "Xe8B94RD30Azj2ea...8BmZIRtcSKPSd8gU" 1356 }), 1357 "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4" 1358 } 1360 On receiving key-change request, the server MUST perform the 1361 following steps in addition to the typical JWS validation: 1363 1. Validate the POST request belongs to a currently active account, 1364 as described in Message Transport. 1366 2. Check that the payload of the JWS is a well-formed JWS object 1367 (the "inner JWS"). 1369 3. Check that the JWS protected header of the inner JWS has a "jwk" 1370 field. 1372 4. Check that the inner JWS verifies using the key in its "jwk" 1373 field. 1375 5. Check that the payload of the inner JWS is a well-formed key- 1376 change object (as described above). 1378 6. Check that the "url" parameters of the inner and outer JWSs are 1379 the same. 1381 7. Check that the "account" field of the key-change object contains 1382 the URL for the account matching the old key 1384 8. Check that the "newKey" field of the key-change object also 1385 verifies the inner JWS. 1387 If all of these checks pass, then the server updates the 1388 corresponding account by replacing the old account key with the new 1389 public key and returns status code 200. Otherwise, the server 1390 responds with an error status code and a problem document describing 1391 the error. 1393 7.3.4. Account deactivation 1395 A client can deactivate an account by posting a signed update to the 1396 server with a status field of "deactivated." Clients may wish to do 1397 this when the account key is compromised or decommissioned. 1399 POST /acme/acct/1 HTTP/1.1 1400 Host: example.com 1401 Content-Type: application/jose+json 1403 { 1404 "protected": base64url({ 1405 "alg": "ES256", 1406 "kid": "https://example.com/acme/acct/1", 1407 "nonce": "ntuJWWSic4WVNSqeUmshgg", 1408 "url": "https://example.com/acme/acct/1" 1409 }), 1410 "payload": base64url({ 1411 "status": "deactivated" 1412 }), 1413 "signature": "earzVLd3m5M4xJzR...bVTqn7R08AKOVf3Y" 1414 } 1416 The server MUST verify that the request is signed by the account key. 1417 If the server accepts the deactivation request, it replies with a 200 1418 (OK) status code and the current contents of the account object. 1420 Once an account is deactivated, the server MUST NOT accept further 1421 requests authorized by that account's key. A server may take a 1422 variety of actions in response to an account deactivation, e.g., 1423 deleting data related to that account or sending mail to the 1424 account's contacts. Servers SHOULD NOT revoke certificates issued by 1425 the deactivated account, since this could cause operational 1426 disruption for servers using these certificates. ACME does not 1427 provide a way to reactivate a deactivated account. 1429 7.4. Applying for Certificate Issuance 1431 The client requests certificate issuance by sending a POST request to 1432 the server's new-order resource. The body of the POST is a JWS 1433 object whose JSON payload is a subset of the order object defined in 1434 Section 7.1.3, containing the fields that describe the certificate to 1435 be issued: 1437 csr (required, string): A CSR encoding the parameters for the 1438 certificate being requested [RFC2986]. The CSR is sent in the 1439 base64url-encoded version of the DER format. (Note: Because this 1440 field uses base64url, and does not include headers, it is 1441 different from PEM.) 1443 notBefore (optional, string): The requested value of the notBefore 1444 field in the certificate, in the date format defined in [RFC3339] 1446 notAfter (optional, string): The requested value of the notAfter 1447 field in the certificate, in the date format defined in [RFC3339] 1449 POST /acme/new-order HTTP/1.1 1450 Host: example.com 1451 Content-Type: application/jose+json 1453 { 1454 "protected": base64url({ 1455 "alg": "ES256", 1456 "kid": "https://example.com/acme/acct/1", 1457 "nonce": "5XJ1L3lEkMG7tR6pA00clA", 1458 "url": "https://example.com/acme/new-order" 1459 }), 1460 "payload": base64url({ 1461 "csr": "5jNudRx6Ye4HzKEqT5...FS6aKdZeGsysoCo4H9P", 1462 "notBefore": "2016-01-01T00:00:00Z", 1463 "notAfter": "2016-01-08T00:00:00Z" 1464 }), 1465 "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g" 1466 } 1468 The CSR encodes the client's requests with regard to the content of 1469 the certificate to be issued. The CSR MUST indicate the requested 1470 identifiers, either in the commonName portion of the requested 1471 subject name, or in an extensionRequest attribute [RFC2985] 1472 requesting a subjectAltName extension. 1474 The server MUST return an error if it cannot fulfill the request as 1475 specified, and MUST NOT issue a certificate with contents other than 1476 those requested. If the server requires the request to be modified 1477 in a certain way, it should indicate the required changes using an 1478 appropriate error type and description. 1480 If the server is willing to issue the requested certificate, it 1481 responds with a 201 (Created) response. The body of this response is 1482 an order object reflecting the client's request and any 1483 authorizations the client must complete before the certificate will 1484 be issued. 1486 HTTP/1.1 201 Created 1487 Replay-Nonce: MYAuvOpaoIiywTezizk5vw 1488 Location: https://example.com/acme/order/asdf 1490 { 1491 "status": "pending", 1492 "expires": "2016-01-01T00:00:00Z", 1494 "csr": "jcRf4uXra7FGYW5ZMewvV...rhlnznwy8YbpMGqwidEXfE", 1495 "notBefore": "2016-01-01T00:00:00Z", 1496 "notAfter": "2016-01-08T00:00:00Z", 1498 "authorizations": [ 1499 "https://example.com/acme/authz/1234", 1500 "https://example.com/acme/authz/2345" 1501 ] 1502 } 1504 The order object returned by the server represents a promise that if 1505 the client fulfills the server's requirements before the "expires" 1506 time, then the server will issue the requested certificate. In the 1507 order object, any authorization referenced in the "authorizations" 1508 array whose status is "pending" represents an authorization 1509 transaction that the client must complete before the server will 1510 issue the certificate (see Section 7.5). If the client fails to 1511 complete the required actions before the "expires" time, then the 1512 server SHOULD change the status of the order to "invalid" and MAY 1513 delete the order resource. 1515 The server MUST issue the requested certificate and update the order 1516 resource with a URL for the certificate shortly after the client has 1517 fulfilled the server's requirements. If the client has already 1518 satisfied the server's requirements at the time of this request 1519 (e.g., by obtaining authorization for all of the identifiers in the 1520 certificate in previous transactions), then the server MUST 1521 proactively issue the requested certificate and provide a URL for it 1522 in the "certificate" field of the order. The server MUST, however, 1523 still list the completed authorizations in the "authorizations" 1524 array. 1526 Once the client believes it has fulfilled the server's requirements, 1527 it should send a GET request to the order resource to obtain its 1528 current state. The status of the order will indicate what action the 1529 client should take: 1531 o "invalid": The certificate will not be issued. Consider this 1532 order process abandoned. 1534 o "pending": The server does not believe that the client has 1535 fulfilled the requirements. Check the "authorizations" array for 1536 entries that are still pending. 1538 o "processing": The server agrees that the requirements have been 1539 fulfilled, and is in the process of generating the certificate. 1540 Retry after the time given in the "Retry-After" header field of 1541 the response, if any. 1543 o "valid": The server has issued the certificate and provisioned its 1544 URL to the "certificate" field of the order. 1546 7.4.1. Pre-Authorization 1548 The order process described above presumes that authorization objects 1549 are created reactively, in response to a certificate order. Some 1550 servers may also wish to enable clients to obtain authorization for 1551 an identifier proactively, outside of the context of a specific 1552 issuance. For example, a client hosting virtual servers for a 1553 collection of names might wish to obtain authorization before any 1554 virtual servers are created and only create a certificate when a 1555 virtual server starts up. 1557 In some cases, a CA running an ACME server might have a completely 1558 external, non-ACME process for authorizing a client to issue for an 1559 identifier. In these case, the CA should provision its ACME server 1560 with authorization objects corresponding to these authorizations and 1561 reflect them as already valid in any orders submitted by the client. 1563 If a CA wishes to allow pre-authorization within ACME, it can offer a 1564 "new authorization" resource in its directory by adding the key "new- 1565 authz" with a URL for the new authorization resource. 1567 To request authorization for an identifier, the client sends a POST 1568 request to the new-authorization resource specifying the identifier 1569 for which authorization is being requested and how the server should 1570 behave with respect to existing authorizations for this identifier. 1572 identifier (required, object): The identifier that the account is 1573 authorized to represent: 1575 type (required, string): The type of identifier. 1577 value (required, string): The identifier itself. 1579 POST /acme/new-authz HTTP/1.1 1580 Host: example.com 1581 Content-Type: application/jose+json 1583 { 1584 "protected": base64url({ 1585 "alg": "ES256", 1586 "jwk": {...}, 1587 "nonce": "uQpSjlRb4vQVCjVYAyyUWg", 1588 "url": "https://example.com/acme/new-authz" 1589 }), 1590 "payload": base64url({ 1591 "identifier": { 1592 "type": "dns", 1593 "value": "example.net" 1594 } 1595 }), 1596 "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" 1597 } 1599 Before processing the authorization request, the server SHOULD 1600 determine whether it is willing to issue certificates for the 1601 identifier. For example, the server should check that the identifier 1602 is of a supported type. Servers might also check names against a 1603 blacklist of known high-value identifiers. If the server is 1604 unwilling to issue for the identifier, it SHOULD return a 403 1605 (Forbidden) error, with a problem document describing the reason for 1606 the rejection. 1608 If the server is willing to proceed, it builds a pending 1609 authorization object from the inputs submitted by the client. 1611 o "identifier" the identifier submitted by the client 1613 o "status" MUST be "pending" unless the server has out-of-band 1614 information about the client's authorization status 1616 o "challenges" and "combinations" as selected by the server's policy 1617 for this identifier 1619 The server allocates a new URI for this authorization, and returns a 1620 201 (Created) response, with the authorization URI in the Location 1621 header field, and the JSON authorization object in the body. The 1622 client then follows the process described in Section 7.5 to complete 1623 the authorization process. 1625 7.4.2. Downloading the Certificate 1627 To download the issued certificate, the client simply sends a GET 1628 request to the certificate URL. 1630 The default format of the certificate is application/pem-certificate- 1631 chain (see IANA Considerations). 1633 The server MAY provide one or more link relation header fields 1634 [RFC5988] with relation "alternate". Each such field SHOULD express 1635 an alternative certificate chain starting with the same end-entity 1636 certificate. This can be used to express paths to various trust 1637 anchors. Clients can fetch these alternates and use their own 1638 heuristics to decide which is optimal. 1640 GET /acme/cert/asdf HTTP/1.1 1641 Host: example.com 1642 Accept: application/pkix-cert 1644 HTTP/1.1 200 OK 1645 Content-Type: application/pem-certificate-chain 1646 Link: ;rel="index" 1648 -----BEGIN CERTIFICATE----- 1649 [End-entity certificate contents] 1650 -----END CERTIFICATE----- 1651 -----BEGIN CERTIFICATE----- 1652 [Issuer certificate contents] 1653 -----END CERTIFICATE----- 1654 -----BEGIN CERTIFICATE----- 1655 [Other certificate contents] 1656 -----END CERTIFICATE----- 1658 A certificate resource represents a single, immutable certificate. 1659 If the client wishes to obtain a renewed certificate, the client 1660 initiates a new order process to request one. 1662 Because certificate resources are immutable once issuance is 1663 complete, the server MAY enable the caching of the resource by adding 1664 Expires and Cache-Control headers specifying a point in time in the 1665 distant future. These headers have no relation to the certificate's 1666 period of validity. 1668 The ACME client MAY request other formats by including an Accept 1669 header in its request. For example, the client could use the media 1670 type "application/pkix-cert" [RFC2585] to request the end-entity 1671 certificate in DER format. Server support for alternate formats is 1672 OPTIONAL. For formats that can only express a single certificate, 1673 the server SHOULD provide one or more "Link: rel="up"" headers 1674 pointing to an issuer or issuers so that ACME clients can build a 1675 certificate chain as defined in TLS. 1677 7.5. Identifier Authorization 1679 The identifier authorization process establishes the authorization of 1680 an account to manage certificates for a given identifier. This 1681 process assures the server of two things: 1683 1. That the client controls the private key of the account key pair, 1684 and 1686 2. That the client controls the identifier in question. 1688 This process may be repeated to associate multiple identifiers to a 1689 key pair (e.g., to request certificates with multiple identifiers), 1690 or to associate multiple accounts with an identifier (e.g., to allow 1691 multiple entities to manage certificates). The server may declare 1692 that an authorization is only valid for a specific order by setting 1693 the "scope" field of the authorization to the URI for that order. 1695 Authorization resources are created by the server in response to 1696 certificate orders or authorization requests submitted by an account 1697 key holder; their URLs are provided to the client in the responses to 1698 these requests. The authorization object is implicitly tied to the 1699 account key used to sign the request. 1701 When a client receives an order from the server it downloads the 1702 authorization resources by sending GET requests to the indicated 1703 URLs. If the client initiates authorization using a request to the 1704 new authorization resource, it will have already received the pending 1705 authorization object in the response to that request. 1707 GET /acme/authz/1234 HTTP/1.1 1708 Host: example.com 1710 HTTP/1.1 200 OK 1711 Content-Type: application/json 1712 Link: ;rel="index" 1714 { 1715 "status": "pending", 1716 "expires": "2018-03-03T14:09:00Z", 1718 "identifier": { 1719 "type": "dns", 1720 "value": "example.org" 1721 }, 1723 "challenges": [ 1724 { 1725 "type": "http-01", 1726 "url": "https://example.com/authz/1234/0", 1727 "token": "DGyRejmCefe7v4NfDGDKfA" 1728 }, 1729 { 1730 "type": "tls-sni-02", 1731 "url": "https://example.com/authz/1234/1", 1732 "token": "DGyRejmCefe7v4NfDGDKfA" 1733 }, 1734 { 1735 "type": "dns-01", 1736 "url": "https://example.com/authz/1234/2", 1737 "token": "DGyRejmCefe7v4NfDGDKfA" 1738 } 1739 ] 1740 } 1742 7.5.1. Responding to Challenges 1744 To prove control of the identifier and receive authorization, the 1745 client needs to respond with information to complete the challenges. 1746 To do this, the client updates the authorization object received from 1747 the server by filling in any required information in the elements of 1748 the "challenges" dictionary. 1750 The client sends these updates back to the server in the form of a 1751 JSON object with the response fields required by the challenge type, 1752 carried in a POST request to the challenge URI (not authorization 1753 URI) once it is ready for the server to attempt validation. 1755 For example, if the client were to respond to the "http-01" challenge 1756 in the above authorization, it would send the following request: 1758 POST /acme/authz/asdf/0 HTTP/1.1 1759 Host: example.com 1760 Content-Type: application/jose+json 1762 { 1763 "protected": base64url({ 1764 "alg": "ES256", 1765 "kid": "https://example.com/acme/acct/1", 1766 "nonce": "Q_s3MWoqT05TrdkM2MTDcw", 1767 "url": "https://example.com/acme/authz/asdf/0" 1768 }), 1769 "payload": base64url({ 1770 "type": "http-01", 1771 "keyAuthorization": "IlirfxKKXA...vb29HhjjLPSggwiE" 1772 }), 1773 "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ" 1774 } 1776 The server updates the authorization document by updating its 1777 representation of the challenge with the response fields provided by 1778 the client. The server MUST ignore any fields in the response object 1779 that are not specified as response fields for this type of challenge. 1780 The server provides a 200 (OK) response with the updated challenge 1781 object as its body. 1783 If the client's response is invalid for any reason or does not 1784 provide the server with appropriate information to validate the 1785 challenge, then the server MUST return an HTTP error. On receiving 1786 such an error, the client SHOULD undo any actions that have been 1787 taken to fulfill the challenge, e.g., removing files that have been 1788 provisioned to a web server. 1790 The server is said to "finalize" the authorization when it has 1791 completed one of the validations, by assigning the authorization a 1792 status of "valid" or "invalid", corresponding to whether it considers 1793 the account authorized for the identifier. If the final state is 1794 "valid", then the server MUST include an "expires" field. When 1795 finalizing an authorization, the server MAY remove challenges other 1796 than the one that was completed, and may modify the "expires" field. 1797 The server SHOULD NOT remove challenges with status "invalid". 1799 Usually, the validation process will take some time, so the client 1800 will need to poll the authorization resource to see when it is 1801 finalized. For challenges where the client can tell when the server 1802 has validated the challenge (e.g., by seeing an HTTP or DNS request 1803 from the server), the client SHOULD NOT begin polling until it has 1804 seen the validation request from the server. 1806 To check on the status of an authorization, the client sends a GET 1807 request to the authorization URI, and the server responds with the 1808 current authorization object. In responding to poll requests while 1809 the validation is still in progress, the server MUST return a 200 1810 (OK) response and MAY include a Retry-After header field to suggest a 1811 polling interval to the client. 1813 GET /acme/authz/asdf HTTP/1.1 1814 Host: example.com 1816 HTTP/1.1 200 OK 1818 { 1819 "status": "valid", 1820 "expires": "2018-09-09T14:09:00Z", 1822 "identifier": { 1823 "type": "dns", 1824 "value": "example.org" 1825 }, 1827 "challenges": [ 1828 { 1829 "type": "http-01" 1830 "url": "https://example.com/authz/asdf/0", 1831 "status": "valid", 1832 "validated": "2014-12-01T12:05:00Z", 1833 "token": "IlirfxKKXAsHtmzK29Pj8A", 1834 "keyAuthorization": "IlirfxKKXA...vb29HhjjLPSggwiE" 1835 } 1836 ] 1837 } 1839 7.5.2. Deactivating an Authorization 1841 If a client wishes to relinquish its authorization to issue 1842 certificates for an identifier, then it may request that the server 1843 deactivates each authorization associated with it by sending POST 1844 requests with the static object {"status": "deactivated"} to each 1845 authorization URI. 1847 POST /acme/authz/asdf HTTP/1.1 1848 Host: example.com 1849 Content-Type: application/jose+json 1851 { 1852 "protected": base64url({ 1853 "alg": "ES256", 1854 "kid": "https://example.com/acme/acct/1", 1855 "nonce": "xWCM9lGbIyCgue8di6ueWQ", 1856 "url": "https://example.com/acme/authz/asdf" 1857 }), 1858 "payload": base64url({ 1859 "status": "deactivated" 1860 }), 1861 "signature": "srX9Ji7Le9bjszhu...WTFdtujObzMtZcx4" 1862 } 1864 The server MUST verify that the request is signed by the account key 1865 corresponding to the account that owns the authorization. If the 1866 server accepts the deactivation, it should reply with a 200 (OK) 1867 status code and the updated contents of the authorization object. 1869 The server MUST NOT treat deactivated authorization objects as 1870 sufficient for issuing certificates. 1872 7.6. Certificate Revocation 1874 To request that a certificate be revoked, the client sends a POST 1875 request to the ACME server's revoke-cert URI. The body of the POST 1876 is a JWS object whose JSON payload contains the certificate to be 1877 revoked: 1879 certificate (required, string): The certificate to be revoked, in 1880 the base64url-encoded version of the DER format. (Note: Because 1881 this field uses base64url, and does not include headers, it is 1882 different from PEM.) 1884 reason (optional, int): One of the revocation reasonCodes defined in 1885 Section 5.3.1 of [RFC5280] to be used when generating OCSP 1886 responses and CRLs. If this field is not set the server SHOULD 1887 use the unspecified (0) reasonCode value when generating OCSP 1888 responses and CRLs. The server MAY disallow a subset of 1889 reasonCodes from being used by the user. If a request contains a 1890 disallowed reasonCode the server MUST reject it with the error 1891 type "urn:ietf:params:acme:error:badRevocationReason". The 1892 problem document detail SHOULD indicate which reasonCodes are 1893 allowed. 1895 POST /acme/revoke-cert HTTP/1.1 1896 Host: example.com 1897 Content-Type: application/jose+json 1899 { 1900 "protected": base64url({ 1901 "alg": "ES256", 1902 "kid": "https://example.com/acme/acct/1", // OR "jwk" 1903 "nonce": "JHb54aT_KTXBWQOzGYkt9A", 1904 "url": "https://example.com/acme/revoke-cert" 1905 }), 1906 "payload": base64url({ 1907 "certificate": "MIIEDTCCAvegAwIBAgIRAP8...", 1908 "reason": 1 1909 }), 1910 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 1911 } 1913 Revocation requests are different from other ACME requests in that 1914 they can be signed either with an account key pair or the key pair in 1915 the certificate. Before revoking a certificate, the server MUST 1916 verify that the key used to sign the request is authorized to revoke 1917 the certificate. The server SHOULD consider at least the following 1918 accounts authorized for a given certificate: 1920 o the account that issued the certificate. 1922 o an account that holds authorizations for all of the identifiers in 1923 the certificate. 1925 The server SHOULD also consider a revocation request valid if it is 1926 signed with the private key corresponding to the public key in the 1927 certificate. 1929 If the revocation succeeds, the server responds with status code 200 1930 (OK). If the revocation fails, the server returns an error. 1932 HTTP/1.1 200 OK 1933 Replay-Nonce: IXVHDyxIRGcTE0VSblhPzw 1934 Content-Length: 0 1936 --- or --- 1938 HTTP/1.1 403 Forbidden 1939 Replay-Nonce: IXVHDyxIRGcTE0VSblhPzw 1940 Content-Type: application/problem+json 1941 Content-Language: en 1943 { 1944 "type": "urn:ietf:params:acme:error:unauthorized", 1945 "detail": "No authorization provided for name example.net", 1946 "instance": "http://example.com/doc/unauthorized" 1947 } 1949 8. Identifier Validation Challenges 1951 There are few types of identifiers in the world for which there is a 1952 standardized mechanism to prove possession of a given identifier. In 1953 all practical cases, CAs rely on a variety of means to test whether 1954 an entity applying for a certificate with a given identifier actually 1955 controls that identifier. 1957 Challenges provide the server with assurance that an account holder 1958 is also the entity that controls an identifier. For each type of 1959 challenge, it must be the case that in order for an entity to 1960 successfully complete the challenge the entity must both: 1962 o Hold the private key of the account key pair used to respond to 1963 the challenge 1965 o Control the identifier in question 1967 Section 10 documents how the challenges defined in this document meet 1968 these requirements. New challenges will need to document how they 1969 do. 1971 ACME uses an extensible challenge/response framework for identifier 1972 validation. The server presents a set of challenges in the 1973 authorization object it sends to a client (as objects in the 1974 "challenges" array), and the client responds by sending a response 1975 object in a POST request to a challenge URI. 1977 This section describes an initial set of challenge types. Each 1978 challenge must describe: 1980 1. Content of challenge objects 1982 2. Content of response objects 1984 3. How the server uses the challenge and response to verify control 1985 of an identifier 1987 Challenge objects all contain the following basic fields: 1989 type (required, string): The type of challenge encoded in the 1990 object. 1992 url (required, string): The URL to which a response can be posted. 1994 status (required, string): The status of this authorization. 1995 Possible values are: "pending", "valid", and "invalid". 1997 validated (optional, string): The time at which this challenge was 1998 completed by the server, encoded in the format specified in RFC 1999 3339 [RFC3339]. This field is REQUIRED if the "status" field is 2000 "valid". 2002 error (optional, object): The error that occurred while the server 2003 was validating the challenge, if any. This field is structured as 2004 a problem document [RFC7807]. 2006 All additional fields are specified by the challenge type. If the 2007 server sets a challenge's "status" to "invalid", it SHOULD also 2008 include the "error" field to help the client diagnose why the 2009 challenge failed. 2011 Different challenges allow the server to obtain proof of different 2012 aspects of control over an identifier. In some challenges, like 2013 HTTP, TLS SNI, and DNS, the client directly proves its ability to do 2014 certain things related to the identifier. The choice of which 2015 challenges to offer to a client under which circumstances is a matter 2016 of server policy. 2018 The identifier validation challenges described in this section all 2019 relate to validation of domain names. If ACME is extended in the 2020 future to support other types of identifiers, there will need to be 2021 new challenge types, and they will need to specify which types of 2022 identifier they apply to. 2024 [[ Editor's Note: In pre-RFC versions of this specification, 2025 challenges are labeled by type, and with the version of the draft in 2026 which they were introduced. For example, if an HTTP challenge were 2027 introduced in version -03 and a breaking change made in version -05, 2028 then there would be a challenge labeled "http-03" and one labeled 2029 "http-05" - but not one labeled "http-04", since challenge in version 2030 -04 was compatible with one in version -03. ]] 2032 8.1. Key Authorizations 2034 Several of the challenges in this document make use of a key 2035 authorization string. A key authorization is a string that expresses 2036 a domain holder's authorization for a specified key to satisfy a 2037 specified challenge, by concatenating the token for the challenge 2038 with a key fingerprint, separated by a "." character: 2040 key-authz = token || '.' || base64url(JWK_Thumbprint(accountKey)) 2042 The "JWK_Thumbprint" step indicates the computation specified in 2043 [RFC7638], using the SHA-256 digest [FIPS180-4]. As noted in JWA 2044 [RFC7518] any prepended zero octets in the JWK object MUST be 2045 stripped before doing the computation. 2047 As specified in the individual challenges below, the token for a 2048 challenge is a string comprised entirely of characters in the URL- 2049 safe base64 alphabet. The "||" operator indicates concatenation of 2050 strings. 2052 8.2. HTTP 2054 With HTTP validation, the client in an ACME transaction proves its 2055 control over a domain name by proving that for that domain name it 2056 can provision resources to be returned by an HTTP server. The ACME 2057 server challenges the client to provision a file at a specific path, 2058 with a specific string as its content. 2060 As a domain may resolve to multiple IPv4 and IPv6 addresses, the 2061 server will connect to at least one of the hosts found in the DNS A 2062 and AAAA records, at its discretion. Because many web servers 2063 allocate a default HTTPS virtual host to a particular low-privilege 2064 tenant user in a subtle and non-intuitive manner, the challenge must 2065 be completed over HTTP, not HTTPS. 2067 type (required, string): The string "http-01" 2069 token (required, string): A random value that uniquely identifies 2070 the challenge. This value MUST have at least 128 bits of entropy, 2071 in order to prevent an attacker from guessing it. It MUST NOT 2072 contain any characters outside the base64url alphabet, including 2073 padding characters ("="). 2075 GET /acme/authz/1234/0 HTTP/1.1 2076 Host: example.com 2078 HTTP/1.1 200 OK 2079 { 2080 "type": "http-01", 2081 "url": "https://example.com/acme/authz/0", 2082 "status": "pending", 2083 "token": "evaGxfADs6pSRb2LAv9IZf17" 2084 } 2086 A client responds to this challenge by constructing a key 2087 authorization from the "token" value provided in the challenge and 2088 the client's account key. The client then provisions the key 2089 authorization as a resource on the HTTP server for the domain in 2090 question. 2092 The path at which the resource is provisioned is comprised of the 2093 fixed prefix ".well-known/acme-challenge/", followed by the "token" 2094 value in the challenge. The value of the resource MUST be the ASCII 2095 representation of the key authorization. 2097 GET .well-known/acme-challenge/evaGxfADs6pSRb2LAv9IZf17 2098 Host: example.com 2100 HTTP/1.1 200 OK 2101 LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0.9jg46WB3rR_AHD-EBXdN7cBkH1WOu0tA3M9fm21mqTI 2103 The client's response to this challenge indicates its agreement to 2104 this challenge by sending the server the key authorization covering 2105 the challenge's token and the client's account key. 2107 keyAuthorization (required, string): The key authorization for this 2108 challenge. This value MUST match the token from the challenge and 2109 the client's account key. 2111 POST /acme/authz/1234/0 2112 Host: example.com 2113 Content-Type: application/jose+json 2115 { 2116 "protected": base64url({ 2117 "alg": "ES256", 2118 "kid": "https://example.com/acme/acct/1", 2119 "nonce": "JHb54aT_KTXBWQOzGYkt9A", 2120 "url": "https://example.com/acme/authz/1234/0" 2121 }), 2122 "payload": base64url({ 2123 "keyAuthorization": "evaGxfADs...62jcerQ" 2124 }), 2125 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2126 } 2128 On receiving a response, the server MUST verify that the key 2129 authorization in the response matches the "token" value in the 2130 challenge and the client's account key. If they do not match, then 2131 the server MUST return an HTTP error in response to the POST request 2132 in which the client sent the challenge. 2134 Given a challenge/response pair, the server verifies the client's 2135 control of the domain by verifying that the resource was provisioned 2136 as expected. 2138 1. Construct a URI by populating the URI template [RFC6570] 2139 "http://{domain}/.well-known/acme-challenge/{token}", where: 2141 * the domain field is set to the domain name being verified; and 2143 * the token field is set to the token in the challenge. 2145 2. Verify that the resulting URI is well-formed. 2147 3. Dereference the URI using an HTTP GET request. This request MUST 2148 be sent to TCP port 80 on the HTTP server. 2150 4. Verify that the body of the response is well-formed key 2151 authorization. The server SHOULD ignore whitespace characters at 2152 the end of the body. 2154 5. Verify that key authorization provided by the HTTP server matches 2155 the token for this challenge and the client's account key. 2157 The server SHOULD follow redirects when dereferencing the URI. 2159 If all of the above verifications succeed, then the validation is 2160 successful. If the request fails, or the body does not pass these 2161 checks, then it has failed. 2163 8.3. TLS with Server Name Indication (TLS SNI) 2165 The TLS with Server Name Indication (TLS SNI) validation method 2166 proves control over a domain name by requiring the client to 2167 configure a TLS server referenced by the DNS A and AAAA resource 2168 records for the domain name to respond to specific connection 2169 attempts utilizing the Server Name Indication extension [RFC6066]. 2170 The server verifies the client's challenge by accessing the TLS 2171 server and verifying a particular certificate is presented. 2173 type (required, string): The string "tls-sni-02" 2175 token (required, string): A random value that uniquely identifies 2176 the challenge. This value MUST have at least 128 bits of entropy, 2177 in order to prevent an attacker from guessing it. It MUST NOT 2178 contain any characters outside the base64url alphabet, including 2179 padding characters ("="). 2181 GET /acme/authz/1234/1 HTTP/1.1 2182 Host: example.com 2184 HTTP/1.1 200 OK 2185 { 2186 "type": "tls-sni-02", 2187 "url": "https://example.com/acme/authz/1234/1", 2188 "status": "pending", 2189 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA" 2190 } 2192 A client responds to this challenge by constructing a self-signed 2193 certificate which the client MUST provision at the domain name 2194 concerned in order to pass the challenge. 2196 The certificate may be constructed arbitrarily, except that each 2197 certificate MUST have exactly two subjectAlternativeNames, SAN A and 2198 SAN B. Both MUST be dNSNames. 2200 SAN A MUST be constructed as follows: compute the SHA-256 digest 2201 [FIPS180-4] of the challenge token and encode it in lowercase 2202 hexadecimal form. The dNSName is "x.y.token.acme.invalid", where x 2203 is the first half of the hexadecimal representation and y is the 2204 second half. 2206 SAN B MUST be constructed as follows: compute the SHA-256 digest of 2207 the key authorization and encode it in lowercase hexadecimal form. 2208 The dNSName is "x.y.ka.acme.invalid" where x is the first half of the 2209 hexadecimal representation and y is the second half. 2211 The client MUST ensure that the certificate is served to TLS 2212 connections specifying a Server Name Indication (SNI) value of SAN A. 2214 The response to the TLS-SNI challenge simply acknowledges that the 2215 client is ready to fulfill this challenge. 2217 keyAuthorization (required, string): The key authorization for this 2218 challenge. This value MUST match the token from the challenge and 2219 the client's account key. 2221 POST /acme/authz/1234/1 2222 Host: example.com 2223 Content-Type: application/jose+json 2225 { 2226 "protected": base64url({ 2227 "alg": "ES256", 2228 "kid": "https://example.com/acme/acct/1", 2229 "nonce": "JHb54aT_KTXBWQOzGYkt9A", 2230 "url": "https://example.com/acme/authz/1234/1" 2231 }), 2232 "payload": base64url({ 2233 "keyAuthorization": "evaGxfADs...62jcerQ" 2234 }), 2235 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2236 } 2238 On receiving a response, the server MUST verify that the key 2239 authorization in the response matches the "token" value in the 2240 challenge and the client's account key. If they do not match, then 2241 the server MUST return an HTTP error in response to the POST request 2242 in which the client sent the challenge. 2244 Given a challenge/response pair, the ACME server verifies the 2245 client's control of the domain by verifying that the TLS server was 2246 configured appropriately, using these steps: 2248 1. Compute SAN A and SAN B in the same way as the client. 2250 2. Open a TLS connection to the domain name being validated, 2251 presenting SAN A in the SNI field. This connection MUST be sent 2252 to TCP port 443 on the TLS server. In the ClientHello initiating 2253 the TLS handshake, the server MUST include a server_name 2254 extension (i.e., SNI) containing SAN A. The server SHOULD ensure 2255 that it does not reveal SAN B in any way when making the TLS 2256 connection, such that the presentation of SAN B in the returned 2257 certificate proves association with the client. 2259 3. Verify that the certificate contains a subjectAltName extension 2260 containing dNSName entries of SAN A and SAN B and no other 2261 entries. The comparison MUST be insensitive to case and ordering 2262 of names. 2264 It is RECOMMENDED that the server opens multiple TLS connections from 2265 various network perspectives, in order to make MitM attacks harder. 2267 If all of the above verifications succeed, then the validation is 2268 successful. Otherwise, the validation fails. 2270 8.4. DNS 2272 When the identifier being validated is a domain name, the client can 2273 prove control of that domain by provisioning a TXT resource record 2274 containing a designated value for a specific validation domain name. 2276 type (required, string): The string "dns-01" 2278 token (required, string): A random value that uniquely identifies 2279 the challenge. This value MUST have at least 128 bits of entropy, 2280 in order to prevent an attacker from guessing it. It MUST NOT 2281 contain any characters outside the base64url alphabet, including 2282 padding characters ("="). 2284 GET /acme/authz/1234/2 HTTP/1.1 2285 Host: example.com 2287 HTTP/1.1 200 OK 2288 { 2289 "type": "dns-01", 2290 "url": "https://example.com/acme/authz/1234/2", 2291 "status": "pending", 2292 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA" 2293 } 2295 A client responds to this challenge by constructing a key 2296 authorization from the "token" value provided in the challenge and 2297 the client's account key. The client then computes the SHA-256 2298 digest [FIPS180-4] of the key authorization. 2300 The record provisioned to the DNS is the base64url encoding of this 2301 digest. The client constructs the validation domain name by 2302 prepending the label "_acme-challenge" to the domain name being 2303 validated, then provisions a TXT record with the digest value under 2304 that name. For example, if the domain name being validated is 2305 "example.com", then the client would provision the following DNS 2306 record: 2308 _acme-challenge.example.com. 300 IN TXT "gfj9Xq...Rg85nM" 2310 The response to the DNS challenge provides the computed key 2311 authorization to acknowledge that the client is ready to fulfill this 2312 challenge. 2314 keyAuthorization (required, string): The key authorization for this 2315 challenge. This value MUST match the token from the challenge and 2316 the client's account key. 2318 POST /acme/authz/1234/2 2319 Host: example.com 2320 Content-Type: application/jose+json 2322 { 2323 "protected": base64url({ 2324 "alg": "ES256", 2325 "kid": "https://example.com/acme/acct/1", 2326 "nonce": "JHb54aT_KTXBWQOzGYkt9A", 2327 "url": "https://example.com/acme/authz/1234/2" 2328 }), 2329 "payload": base64url({ 2330 "keyAuthorization": "evaGxfADs...62jcerQ" 2331 }), 2332 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2333 } 2335 On receiving a response, the server MUST verify that the key 2336 authorization in the response matches the "token" value in the 2337 challenge and the client's account key. If they do not match, then 2338 the server MUST return an HTTP error in response to the POST request 2339 in which the client sent the challenge. 2341 To validate a DNS challenge, the server performs the following steps: 2343 1. Compute the SHA-256 digest [FIPS180-4] of the key authorization 2345 2. Query for TXT records for the validation domain name 2347 3. Verify that the contents of one of the TXT records matches the 2348 digest value 2350 If all of the above verifications succeed, then the validation is 2351 successful. If no DNS record is found, or DNS record and response 2352 payload do not pass these checks, then the validation fails. 2354 8.5. Out-of-Band 2356 There may be cases where a server cannot perform automated validation 2357 of an identifier, for example, if validation requires some manual 2358 steps. In such cases, the server may provide an "out of band" (OOB) 2359 challenge to request that the client perform some action outside of 2360 ACME in order to validate possession of the identifier. 2362 The OOB challenge requests that the client have a human user visit a 2363 web page to receive instructions on how to validate possession of the 2364 identifier, by providing a URL for that web page. 2366 type (required, string): The string "oob-01" 2368 href (required, string): The URL to be visited. The scheme of this 2369 URL MUST be "http" or "https". Note that this field is distinct 2370 from the "url" field of the challenge, which identifies the 2371 challenge itself. 2373 GET /acme/authz/1234/3 HTTP/1.1 2374 Host: example.com 2376 HTTP/1.1 200 OK 2377 { 2378 "type": "oob-01", 2379 "href": "https://example.com/validate/evaGxfADs6pSRb2LAv9IZ" 2380 } 2382 A client responds to this challenge by presenting the indicated URL 2383 for a human user to navigate to. If the user chooses to complete 2384 this challenge (by visiting the website and completing its 2385 instructions), the client indicates this by sending a simple 2386 acknowledgement response to the server. 2388 type (required, string): The string "oob-01" 2389 POST /acme/authz/1234/3 2390 Host: example.com 2391 Content-Type: application/jose+json 2393 { 2394 "protected": base64url({ 2395 "alg": "ES256", 2396 "kid": "https://example.com/acme/acct/1", 2397 "nonce": "JHb54aT_KTXBWQOzGYkt9A", 2398 "url": "https://example.com/acme/authz/1234/3" 2399 }), 2400 "payload": base64url({ 2401 "type": "oob-01" 2402 }), 2403 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2404 } 2406 On receiving a response, the server MUST verify that the value of the 2407 "type" field is "oob-01". Otherwise, the steps the server takes to 2408 validate identifier possession are determined by the server's local 2409 policy. 2411 9. IANA Considerations 2413 9.1. MIME Type: application/pem-certificate-chain 2415 The "Media Types" registry should be updated with the following 2416 additional value: 2418 MIME media type name: application 2420 MIME subtype name: pem-certificate-chain 2422 Required parameters: None 2424 Optional parameters: None 2426 Encoding considerations: None 2428 Security considerations: Carries a cryptographic certificate 2430 Interoperability considerations: None 2432 Published specification: draft-ietf-acme-acme [[ RFC EDITOR: Please 2433 replace draft-ietf-acme-acme above with the RFC number assigned to 2434 this ]] 2436 Applications which use this media type: Any MIME-complaint transport 2437 Additional information: 2439 File should contain one or more certificates encoded as PEM according 2440 to RFC 7468. In order to provide easy interoperation with TLS, the 2441 first certificate MUST be an end-entity certificate. Each following 2442 certificate SHOULD directly certify one preceding it. Because 2443 certificate validation requires that trust anchors be distributed 2444 independently, a certificate that specifies a trust anchor MAY be 2445 omitted from the chain, provided that supported peers are known to 2446 possess any omitted certificates. 2448 9.2. Well-Known URI for the HTTP Challenge 2450 The "Well-Known URIs" registry should be updated with the following 2451 additional value (using the template from [RFC5785]): 2453 URI suffix: acme-challenge 2455 Change controller: IETF 2457 Specification document(s): This document, Section Section 8.2 2459 Related information: N/A 2461 9.3. Replay-Nonce HTTP Header 2463 The "Message Headers" registry should be updated with the following 2464 additional value: 2466 +-------------------+----------+----------+---------------+ 2467 | Header Field Name | Protocol | Status | Reference | 2468 +-------------------+----------+----------+---------------+ 2469 | Replay-Nonce | http | standard | Section 6.4.1 | 2470 +-------------------+----------+----------+---------------+ 2472 9.4. "url" JWS Header Parameter 2474 The "JSON Web Signature and Encryption Header Parameters" registry 2475 should be updated with the following additional value: 2477 o Header Parameter Name: "url" 2479 o Header Parameter Description: URL 2481 o Header Parameter Usage Location(s): JWE, JWS 2483 o Change Controller: IESG 2484 o Specification Document(s): Section 6.3.1 of RFC XXXX 2486 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2487 to this document ]] 2489 9.5. "nonce" JWS Header Parameter 2491 The "JSON Web Signature and Encryption Header Parameters" registry 2492 should be updated with the following additional value: 2494 o Header Parameter Name: "nonce" 2496 o Header Parameter Description: Nonce 2498 o Header Parameter Usage Location(s): JWE, JWS 2500 o Change Controller: IESG 2502 o Specification Document(s): Section 6.4.2 of RFC XXXX 2504 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2505 to this document ]] 2507 9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) 2509 The "IETF URN Sub-namespace for Registered Protocol Parameter 2510 Identifiers" registry should be updated with the following additional 2511 value, following the template in [RFC3553]: 2513 Registry name: acme 2515 Specification: RFC XXXX 2517 Repository: URL-TBD 2519 Index value: No transformation needed. 2521 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2522 to this document, and replace URL-TBD with the URL assigned by IANA 2523 for registries of ACME parameters. ]] 2525 9.7. New Registries 2527 This document requests that IANA create the following new registries: 2529 1. ACME Account Object Fields (Section 9.7.1) 2531 2. ACME Order Object Fields (Section 9.7.2) 2532 3. ACME Error Types (Section 9.7.3) 2534 4. ACME Resource Types (Section 9.7.4) 2536 5. ACME Identifier Types (Section 9.7.5) 2538 6. ACME Challenge Types (Section 9.7.6) 2540 All of these registries are under a heading of "Automated Certificate 2541 Management Environment (ACME) Protocol" and are administered under a 2542 Specification Required policy [RFC5226]. 2544 9.7.1. Fields in Account Objects 2546 This registry lists field names that are defined for use in ACME 2547 account objects. Fields marked as "configurable" may be included in 2548 a new-account request. 2550 Template: 2552 o Field name: The string to be used as a key in the JSON object 2554 o Field type: The type of value to be provided, e.g., string, 2555 boolean, array of string 2557 o Client configurable: Boolean indicating whether the server should 2558 accept values provided by the client 2560 o Reference: Where this field is defined 2562 Initial contents: The fields and descriptions defined in 2563 Section 7.1.2. 2565 +--------------------------+-------------+--------------+-----------+ 2566 | Field Name | Field Type | Configurable | Reference | 2567 +--------------------------+-------------+--------------+-----------+ 2568 | key | object | false | RFC XXXX | 2569 | | | | | 2570 | status | string | false | RFC XXXX | 2571 | | | | | 2572 | contact | array of | true | RFC XXXX | 2573 | | string | | | 2574 | | | | | 2575 | external-account-binding | object | true | RFC XXXX | 2576 | | | | | 2577 | terms-of-service-agreed | boolean | true | RFC XXXX | 2578 | | | | | 2579 | orders | array of | false | RFC XXXX | 2580 | | string | | | 2581 +--------------------------+-------------+--------------+-----------+ 2583 9.7.2. Fields in Order Objects 2585 This registry lists field names that are defined for use in ACME 2586 order objects. Fields marked as "configurable" may be included in a 2587 new-order request. 2589 Template: 2591 o Field name: The string to be used as a key in the JSON object 2593 o Field type: The type of value to be provided, e.g., string, 2594 boolean, array of string 2596 o Client configurable: Boolean indicating whether the server should 2597 accept values provided by the client 2599 o Reference: Where this field is defined 2601 Initial contents: The fields and descriptions defined in 2602 Section 7.1.3. 2604 +----------------+-----------------+--------------+-----------+ 2605 | Field Name | Field Type | Configurable | Reference | 2606 +----------------+-----------------+--------------+-----------+ 2607 | status | string | false | RFC XXXX | 2608 | | | | | 2609 | expires | string | false | RFC XXXX | 2610 | | | | | 2611 | csr | string | true | RFC XXXX | 2612 | | | | | 2613 | notBefore | string | true | RFC XXXX | 2614 | | | | | 2615 | notAfter | string | true | RFC XXXX | 2616 | | | | | 2617 | authorizations | array of string | false | RFC XXXX | 2618 | | | | | 2619 | certificate | string | false | RFC XXXX | 2620 +----------------+-----------------+--------------+-----------+ 2622 9.7.3. Error Types 2624 This registry lists values that are used within URN values that are 2625 provided in the "type" field of problem documents in ACME. 2627 Template: 2629 o Type: The label to be included in the URN for this error, 2630 following "urn:ietf:params:acme:error:" 2632 o Description: A human-readable description of the error 2634 o Reference: Where the error is defined 2636 Initial contents: The types and descriptions in the table in 2637 Section 6.6 above, with the Reference field set to point to this 2638 specification. 2640 9.7.4. Resource Types 2642 This registry lists the types of resources that ACME servers may list 2643 in their directory objects. 2645 Template: 2647 o Key: The value to be used as a field name in the directory object 2649 o Resource type: The type of resource labeled by the key 2651 o Reference: Where the resource type is defined 2652 Initial contents: 2654 +-------------+--------------------+-----------+ 2655 | Key | Resource type | Reference | 2656 +-------------+--------------------+-----------+ 2657 | new-account | New account | RFC XXXX | 2658 | | | | 2659 | new-order | New order | RFC XXXX | 2660 | | | | 2661 | revoke-cert | Revoke certificate | RFC XXXX | 2662 | | | | 2663 | key-change | Key change | RFC XXXX | 2664 +-------------+--------------------+-----------+ 2666 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2667 to this document ]] 2669 9.7.5. Identifier Types 2671 This registry lists the types of identifiers in certificates that 2672 ACME clients may request authorization to issue. 2674 Template: 2676 o Label: The value to be put in the "type" field of the identifier 2677 object 2679 o Reference: Where the identifier type is defined 2681 Initial contents: 2683 +-------+-----------+ 2684 | Label | Reference | 2685 +-------+-----------+ 2686 | dns | RFC XXXX | 2687 +-------+-----------+ 2689 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2690 to this document ]] 2692 9.7.6. Challenge Types 2694 This registry lists the ways that ACME servers can offer to validate 2695 control of an identifier. The "Identifier Type" field in the 2696 template must be contained in the Label column of the ACME Identifier 2697 Types registry. 2699 Template: 2701 o Label: The value to be put in the "type" field of challenge 2702 objects using this validation mechanism 2704 o Identifier Type: The type of identifier that this mechanism 2705 applies to 2707 o Reference: Where the challenge type is defined 2709 Initial Contents 2711 +---------+-----------------+-----------+ 2712 | Label | Identifier Type | Reference | 2713 +---------+-----------------+-----------+ 2714 | http | dns | RFC XXXX | 2715 | | | | 2716 | tls-sni | dns | RFC XXXX | 2717 | | | | 2718 | dns | dns | RFC XXXX | 2719 +---------+-----------------+-----------+ 2721 [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned 2722 to this document ]] 2724 10. Security Considerations 2726 ACME is a protocol for managing certificates that attest to 2727 identifier/key bindings. Thus the foremost security goal of ACME is 2728 to ensure the integrity of this process, i.e., to ensure that the 2729 bindings attested by certificates are correct and that only 2730 authorized entities can manage certificates. ACME identifies clients 2731 by their account keys, so this overall goal breaks down into two more 2732 precise goals: 2734 1. Only an entity that controls an identifier can get an 2735 authorization for that identifier 2737 2. Once authorized, an account key's authorizations cannot be 2738 improperly used by another account 2740 In this section, we discuss the threat model that underlies ACME and 2741 the ways that ACME achieves these security goals within that threat 2742 model. We also discuss the denial-of-service risks that ACME servers 2743 face, and a few other miscellaneous considerations. 2745 10.1. Threat model 2747 As a service on the Internet, ACME broadly exists within the Internet 2748 threat model [RFC3552]. In analyzing ACME, it is useful to think of 2749 an ACME server interacting with other Internet hosts along two 2750 "channels": 2752 o An ACME channel, over which the ACME HTTPS requests are exchanged 2754 o A validation channel, over which the ACME server performs 2755 additional requests to validate a client's control of an 2756 identifier 2758 +------------+ 2759 | ACME | ACME Channel 2760 | Client |--------------------+ 2761 +------------+ | 2762 V 2763 +------------+ 2764 | ACME | 2765 | Server | 2766 +------------+ 2767 +------------+ | 2768 | Validation |<-------------------+ 2769 | Server | Validation Channel 2770 +------------+ 2772 In practice, the risks to these channels are not entirely separate, 2773 but they are different in most cases. Each channel, for example, 2774 uses a different communications pattern: the ACME channel will 2775 comprise inbound HTTPS connections to the ACME server and the 2776 validation channel outbound HTTP or DNS requests. 2778 Broadly speaking, ACME aims to be secure against active and passive 2779 attackers on any individual channel. Some vulnerabilities arise 2780 (noted below) when an attacker can exploit both the ACME channel and 2781 one of the others. 2783 On the ACME channel, in addition to network layer attackers, we also 2784 need to account for man-in-the-middle (MitM) attacks at the 2785 application layer, and for abusive use of the protocol itself. 2786 Protection against application layer MitM addresses potential 2787 attackers such as Content Distribution Networks (CDNs) and 2788 middleboxes with a TLS MitM function. Preventing abusive use of ACME 2789 means ensuring that an attacker with access to the validation channel 2790 can't obtain illegitimate authorization by acting as an ACME client 2791 (legitimately, in terms of the protocol). 2793 10.2. Integrity of Authorizations 2795 ACME allows anyone to request challenges for an identifier by 2796 registering an account key and sending a new-order request using that 2797 account key. The integrity of the authorization process thus depends 2798 on the identifier validation challenges to ensure that the challenge 2799 can only be completed by someone who both (1) holds the private key 2800 of the account key pair, and (2) controls the identifier in question. 2802 Validation responses need to be bound to an account key pair in order 2803 to avoid situations where an ACME MitM can switch out a legitimate 2804 domain holder's account key for one of his choosing, e.g.: 2806 o Legitimate domain holder registers account key pair A 2808 o MitM registers account key pair B 2810 o Legitimate domain holder sends a new-order request signed using 2811 account key A 2813 o MitM suppresses the legitimate request but sends the same request 2814 signed using account key B 2816 o ACME server issues challenges and MitM forwards them to the 2817 legitimate domain holder 2819 o Legitimate domain holder provisions the validation response 2821 o ACME server performs validation query and sees the response 2822 provisioned by the legitimate domain holder 2824 o Because the challenges were issued in response to a message signed 2825 account key B, the ACME server grants authorization to account key 2826 B (the MitM) instead of account key A (the legitimate domain 2827 holder) 2829 All of the challenges above have a binding between the account 2830 private key and the validation query made by the server, via the key 2831 authorization. The key authorization is signed by the account 2832 private key, reflects the corresponding public key, and is provided 2833 to the server in the validation response. 2835 The association of challenges to identifiers is typically done by 2836 requiring the client to perform some action that only someone who 2837 effectively controls the identifier can perform. For the challenges 2838 in this document, the actions are: 2840 o HTTP: Provision files under .well-known on a web server for the 2841 domain 2843 o TLS SNI: Configure a TLS server for the domain 2845 o DNS: Provision DNS resource records for the domain 2847 There are several ways that these assumptions can be violated, both 2848 by misconfiguration and by attacks. For example, on a web server 2849 that allows non-administrative users to write to .well-known, any 2850 user can claim to own the web server's hostname by responding to an 2851 HTTP challenge, and likewise for TLS configuration and TLS SNI. 2853 The use of hosting providers is a particular risk for ACME 2854 validation. If the owner of the domain has outsourced operation of 2855 DNS or web services to a hosting provider, there is nothing that can 2856 be done against tampering by the hosting provider. As far as the 2857 outside world is concerned, the zone or website provided by the 2858 hosting provider is the real thing. 2860 More limited forms of delegation can also lead to an unintended party 2861 gaining the ability to successfully complete a validation 2862 transaction. For example, suppose an ACME server follows HTTP 2863 redirects in HTTP validation and a website operator provisions a 2864 catch-all redirect rule that redirects requests for unknown resources 2865 to a different domain. Then the target of the redirect could use 2866 that to get a certificate through HTTP validation since the 2867 validation path will not be known to the primary server. 2869 The DNS is a common point of vulnerability for all of these 2870 challenges. An entity that can provision false DNS records for a 2871 domain can attack the DNS challenge directly and can provision false 2872 A/AAAA records to direct the ACME server to send its TLS SNI or HTTP 2873 validation query to a remote server of the attacker's choosing. 2874 There are a few different mitigations that ACME servers can apply: 2876 o Always querying the DNS using a DNSSEC-validating resolver 2877 (enhancing security for zones that are DNSSEC-enabled) 2879 o Querying the DNS from multiple vantage points to address local 2880 attackers 2882 o Applying mitigations against DNS off-path attackers, e.g., adding 2883 entropy to requests [I-D.vixie-dnsext-dns0x20] or only using TCP 2885 Given these considerations, the ACME validation process makes it 2886 impossible for any attacker on the ACME channel or a passive attacker 2887 on the validation channel to hijack the authorization process to 2888 authorize a key of the attacker's choice. 2890 An attacker that can only see the ACME channel would need to convince 2891 the validation server to provide a response that would authorize the 2892 attacker's account key, but this is prevented by binding the 2893 validation response to the account key used to request challenges. A 2894 passive attacker on the validation channel can observe the correct 2895 validation response and even replay it, but that response can only be 2896 used with the account key for which it was generated. 2898 An active attacker on the validation channel can subvert the ACME 2899 process, by performing normal ACME transactions and providing a 2900 validation response for his own account key. The risks due to 2901 hosting providers noted above are a particular case. 2903 It is RECOMMENDED that the server perform DNS queries and make HTTP 2904 and TLS connections from various network perspectives, in order to 2905 make MitM attacks harder. 2907 10.3. Denial-of-Service Considerations 2909 As a protocol run over HTTPS, standard considerations for TCP-based 2910 and HTTP-based DoS mitigation also apply to ACME. 2912 At the application layer, ACME requires the server to perform a few 2913 potentially expensive operations. Identifier validation transactions 2914 require the ACME server to make outbound connections to potentially 2915 attacker-controlled servers, and certificate issuance can require 2916 interactions with cryptographic hardware. 2918 In addition, an attacker can also cause the ACME server to send 2919 validation requests to a domain of its choosing by submitting 2920 authorization requests for the victim domain. 2922 All of these attacks can be mitigated by the application of 2923 appropriate rate limits. Issues closer to the front end, like POST 2924 body validation, can be addressed using HTTP request limiting. For 2925 validation and certificate requests, there are other identifiers on 2926 which rate limits can be keyed. For example, the server might limit 2927 the rate at which any individual account key can issue certificates 2928 or the rate at which validation can be requested within a given 2929 subtree of the DNS. And in order to prevent attackers from 2930 circumventing these limits simply by minting new accounts, servers 2931 would need to limit the rate at which accounts can be registered. 2933 10.4. Server-Side Request Forgery 2935 Server-Side Request Forgery (SSRF) attacks can arise when an attacker 2936 can cause a server to perform HTTP requests to an attacker-chosen 2937 URL. In the ACME HTTP challenge validation process, the ACME server 2938 performs an HTTP GET request to a URL in which the attacker can 2939 choose the domain. This request is made before the server has 2940 verified that the client controls the domain, so any client can cause 2941 a query to any domain. 2943 Some server implementations include information from the validation 2944 server's response (in order to facilitate debugging). Such 2945 implementations enable an attacker to extract this information from 2946 any web server that is accessible to the ACME server, even if it is 2947 not accessible to the ACME client. 2949 It might seem that the risk of SSRF through this channel is limited 2950 by the fact that the attacker can only control the domain of the URL, 2951 not the path. However, if the attacker first sets the domain to one 2952 they control, then they can send the server an HTTP redirect (e.g., a 2953 302 response) which will cause the server to query an arbitrary URI. 2955 In order to further limit the SSRF risk, ACME server operators should 2956 ensure that validation queries can only be sent to servers on the 2957 public Internet, and not, say, web services within the server 2958 operator's internal network. Since the attacker could make requests 2959 to these public servers himself, he can't gain anything extra through 2960 an SSRF attack on ACME aside from a layer of anonymization. 2962 10.5. CA Policy Considerations 2964 The controls on issuance enabled by ACME are focused on validating 2965 that a certificate applicant controls the identifier he claims. 2966 Before issuing a certificate, however, there are many other checks 2967 that a CA might need to perform, for example: 2969 o Has the client agreed to a subscriber agreement? 2971 o Is the claimed identifier syntactically valid? 2973 o For domain names: 2975 * If the leftmost label is a '*', then have the appropriate 2976 checks been applied? 2978 * Is the name on the Public Suffix List? 2980 * Is the name a high-value name? 2981 * Is the name a known phishing domain? 2983 o Is the key in the CSR sufficiently strong? 2985 o Is the CSR signed with an acceptable algorithm? 2987 CAs that use ACME to automate issuance will need to ensure that their 2988 servers perform all necessary checks before issuing. 2990 CAs using ACME to allow clients to agree to terms of service should 2991 keep in mind that ACME clients can automate this agreement, possibly 2992 not involving a human user. If a CA wishes to have stronger evidence 2993 of user consent, it may present an out-of-band requirement or 2994 challenge to require human involvement. 2996 11. Operational Considerations 2998 There are certain factors that arise in operational reality that 2999 operators of ACME-based CAs will need to keep in mind when 3000 configuring their services. For example: 3002 11.1. DNS security 3004 As noted above, DNS forgery attacks against the ACME server can 3005 result in the server making incorrect decisions about domain control 3006 and thus mis-issuing certificates. Servers SHOULD perform DNS 3007 queries over TCP, which provides better resistance to some forgery 3008 attacks than DNS over UDP. 3010 An ACME-based CA will often need to make DNS queries, e.g., to 3011 validate control of DNS names. Because the security of such 3012 validations ultimately depends on the authenticity of DNS data, every 3013 possible precaution should be taken to secure DNS queries done by the 3014 CA. It is therefore RECOMMENDED that ACME-based CAs make all DNS 3015 queries via DNSSEC-validating stub or recursive resolvers. This 3016 provides additional protection to domains which choose to make use of 3017 DNSSEC. 3019 An ACME-based CA must use only a resolver if it trusts the resolver 3020 and every component of the network route by which it is accessed. It 3021 is therefore RECOMMENDED that ACME-based CAs operate their own 3022 DNSSEC-validating resolvers within their trusted network and use 3023 these resolvers both for both CAA record lookups and all record 3024 lookups in furtherance of a challenge scheme (A, AAAA, TXT, etc.). 3026 11.2. Default Virtual Hosts 3028 In many cases, TLS-based services are deployed on hosted platforms 3029 that use the Server Name Indication (SNI) TLS extension to 3030 distinguish between different hosted services or "virtual hosts". 3031 When a client initiates a TLS connection with an SNI value indicating 3032 a provisioned host, the hosting platform routes the connection to 3033 that host. 3035 When a connection comes in with an unknown SNI value, one might 3036 expect the hosting platform to terminate the TLS connection. 3037 However, some hosting platforms will choose a virtual host to be the 3038 "default", and route connections with unknown SNI values to that 3039 host. 3041 In such cases, the owner of the default virtual host can complete a 3042 TLS-based challenge (e.g., "tls-sni-02") for any domain with an A 3043 record that points to the hosting platform. This could result in 3044 mis-issuance in cases where there are multiple hosts with different 3045 owners resident on the hosting platform. 3047 A CA that accepts TLS-based proof of domain control should attempt to 3048 check whether a domain is hosted on a domain with a default virtual 3049 host before allowing an authorization request for this host to use a 3050 TLS-based challenge. Typically, systems with default virtual hosts 3051 do not allow the holder of the default virtual host to control what 3052 certificates are presented on a request-by-request basis. Rather, 3053 the default virtual host can configure which certificate is presented 3054 in TLS on a fairly static basis, so that the certificate presented 3055 should be stable over small intervals. 3057 A CA can detect such a bounded default vhost by initiating TLS 3058 connections to the host with random SNI values within the namespace 3059 used for the TLS-based challenge (the "acme.invalid" namespace for 3060 "tls-sni-02"). If it receives the same certificate on two different 3061 connections, then it is very likely that the server is in a default 3062 virtual host configuration. Conversely, if the TLS server returns an 3063 unrecognized_name alert, then this is an indication that the server 3064 is not in a default virtual host configuration. 3066 12. Acknowledgements 3068 In addition to the editors listed on the front page, this document 3069 has benefited from contributions from a broad set of contributors, 3070 all the way back to its inception. 3072 o Peter Eckersley, EFF 3073 o Eric Rescorla, Mozilla 3075 o Seth Schoen, EFF 3077 o Alex Halderman, University of Michigan 3079 o Martin Thomson, Mozilla 3081 o Jakub Warmuz, University of Oxford 3083 This document draws on many concepts established by Eric Rescorla's 3084 "Automated Certificate Issuance Protocol" draft. Martin Thomson 3085 provided helpful guidance in the use of HTTP. 3087 13. References 3089 13.1. Normative References 3091 [FIPS180-4] 3092 Department of Commerce, National., "NIST FIPS 180-4, 3093 Secure Hash Standard", March 2012, 3094 . 3097 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3098 Requirement Levels", BCP 14, RFC 2119, 3099 DOI 10.17487/RFC2119, March 1997, 3100 . 3102 [RFC2585] Housley, R. and P. Hoffman, "Internet X.509 Public Key 3103 Infrastructure Operational Protocols: FTP and HTTP", 3104 RFC 2585, DOI 10.17487/RFC2585, May 1999, 3105 . 3107 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 3108 DOI 10.17487/RFC2818, May 2000, 3109 . 3111 [RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object 3112 Classes and Attribute Types Version 2.0", RFC 2985, 3113 DOI 10.17487/RFC2985, November 2000, 3114 . 3116 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 3117 Request Syntax Specification Version 1.7", RFC 2986, 3118 DOI 10.17487/RFC2986, November 2000, 3119 . 3121 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 3122 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 3123 . 3125 [RFC3492] Costello, A., "Punycode: A Bootstring encoding of Unicode 3126 for Internationalized Domain Names in Applications 3127 (IDNA)", RFC 3492, DOI 10.17487/RFC3492, March 2003, 3128 . 3130 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3131 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 3132 2003, . 3134 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3135 Resource Identifier (URI): Generic Syntax", STD 66, 3136 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3137 . 3139 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 3140 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 3141 . 3143 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3144 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 3145 DOI 10.17487/RFC5226, May 2008, 3146 . 3148 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3149 (TLS) Protocol Version 1.2", RFC 5246, 3150 DOI 10.17487/RFC5246, August 2008, 3151 . 3153 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3154 Housley, R., and W. Polk, "Internet X.509 Public Key 3155 Infrastructure Certificate and Certificate Revocation List 3156 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3157 . 3159 [RFC5890] Klensin, J., "Internationalized Domain Names for 3160 Applications (IDNA): Definitions and Document Framework", 3161 RFC 5890, DOI 10.17487/RFC5890, August 2010, 3162 . 3164 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 3165 DOI 10.17487/RFC5988, October 2010, 3166 . 3168 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 3169 Extensions: Extension Definitions", RFC 6066, 3170 DOI 10.17487/RFC6066, January 2011, 3171 . 3173 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 3174 and D. Orchard, "URI Template", RFC 6570, 3175 DOI 10.17487/RFC6570, March 2012, 3176 . 3178 [RFC6844] Hallam-Baker, P. and R. Stradling, "DNS Certification 3179 Authority Authorization (CAA) Resource Record", RFC 6844, 3180 DOI 10.17487/RFC6844, January 2013, 3181 . 3183 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3184 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3185 2014, . 3187 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3188 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 3189 DOI 10.17487/RFC7231, June 2014, 3190 . 3192 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 3193 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 3194 2015, . 3196 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 3197 DOI 10.17487/RFC7518, May 2015, 3198 . 3200 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 3201 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 3202 2015, . 3204 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 3205 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 3206 . 3208 13.2. Informative References 3210 [I-D.vixie-dnsext-dns0x20] 3211 Vixie, P. and D. Dagon, "Use of Bit 0x20 in DNS Labels to 3212 Improve Transaction Identity", draft-vixie-dnsext- 3213 dns0x20-00 (work in progress), March 2008. 3215 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 3216 Text on Security Considerations", BCP 72, RFC 3552, 3217 DOI 10.17487/RFC3552, July 2003, 3218 . 3220 [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An 3221 IETF URN Sub-namespace for Registered Protocol 3222 Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June 3223 2003, . 3225 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 3226 Uniform Resource Identifiers (URIs)", RFC 5785, 3227 DOI 10.17487/RFC5785, April 2010, 3228 . 3230 [W3C.CR-cors-20130129] 3231 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 3232 Web Consortium CR CR-cors-20130129, January 2013, 3233 . 3235 Authors' Addresses 3237 Richard Barnes 3238 Mozilla 3240 Email: rlb@ipv.sx 3242 Jacob Hoffman-Andrews 3243 EFF 3245 Email: jsha@eff.org 3247 James Kasten 3248 University of Michigan 3250 Email: jdkasten@umich.edu