1
2
3
4
5
6
7Internet Engineering Task Force (IETF) R. Barnes
8Request for Comments: 8555 Cisco
9Category: Standards Track J. Hoffman-Andrews
10ISSN: 2070-1721 EFF
11 D. McCarney
12 Let's Encrypt
13 J. Kasten
14 University of Michigan
15 March 2019
16
17
18 Automatic Certificate Management Environment (ACME)
19
20Abstract
21
22 Public Key Infrastructure using X.509 (PKIX) certificates are used
23 for a number of purposes, the most significant of which is the
24 authentication of domain names. Thus, certification authorities
25 (CAs) in the Web PKI are trusted to verify that an applicant for a
26 certificate legitimately represents the domain name(s) in the
27 certificate. As of this writing, this verification is done through a
28 collection of ad hoc mechanisms. This document describes a protocol
29 that a CA and an applicant can use to automate the process of
30 verification and certificate issuance. The protocol also provides
31 facilities for other certificate management functions, such as
32 certificate revocation.
33
34Status of This Memo
35
36 This is an Internet Standards Track document.
37
38 This document is a product of the Internet Engineering Task Force
39 (IETF). It represents the consensus of the IETF community. It has
40 received public review and has been approved for publication by the
41 Internet Engineering Steering Group (IESG). Further information on
42 Internet Standards is available in Section 2 of RFC 7841.
43
44 Information about the current status of this document, any errata,
45 and how to provide feedback on it may be obtained at
46 https://www.rfc-editor.org/info/rfc8555.
47
48
49
50
51
52
53
54
55
56
57
58Barnes, et al. Standards Track [Page 1]
59
60RFC 8555 ACME March 2019
61
62
63Copyright Notice
64
65 Copyright (c) 2019 IETF Trust and the persons identified as the
66 document authors. All rights reserved.
67
68 This document is subject to BCP 78 and the IETF Trust's Legal
69 Provisions Relating to IETF Documents
70 (https://trustee.ietf.org/license-info) in effect on the date of
71 publication of this document. Please review these documents
72 carefully, as they describe your rights and restrictions with respect
73 to this document. Code Components extracted from this document must
74 include Simplified BSD License text as described in Section 4.e of
75 the Trust Legal Provisions and are provided without warranty as
76 described in the Simplified BSD License.
77
78Table of Contents
79
80 1. Introduction ....................................................4
81 2. Deployment Model and Operator Experience ........................5
82 3. Terminology .....................................................7
83 4. Protocol Overview ...............................................7
84 5. Character Encoding .............................................10
85 6. Message Transport ..............................................10
86 6.1. HTTPS Requests ............................................10
87 6.2. Request Authentication ....................................11
88 6.3. GET and POST-as-GET Requests ..............................13
89 6.4. Request URL Integrity .....................................13
90 6.4.1. "url" (URL) JWS Header Parameter ...................14
91 6.5. Replay Protection .........................................14
92 6.5.1. Replay-Nonce .......................................15
93 6.5.2. "nonce" (Nonce) JWS Header Parameter ...............16
94 6.6. Rate Limits ...............................................16
95 6.7. Errors ....................................................16
96 6.7.1. Subproblems ........................................18
97 7. Certificate Management .........................................20
98 7.1. Resources .................................................20
99 7.1.1. Directory ..........................................23
100 7.1.2. Account Objects ....................................24
101 7.1.3. Order Objects ......................................26
102 7.1.4. Authorization Objects ..............................28
103 7.1.5. Challenge Objects ..................................30
104 7.1.6. Status Changes .....................................30
105 7.2. Getting a Nonce ...........................................34
106 7.3. Account Management ........................................34
107 7.3.1. Finding an Account URL Given a Key .................36
108 7.3.2. Account Update .....................................37
109 7.3.3. Changes of Terms of Service ........................38
110 7.3.4. External Account Binding ...........................38
111
112
113
114Barnes, et al. Standards Track [Page 2]
115
116RFC 8555 ACME March 2019
117
118
119 7.3.5. Account Key Rollover ...............................40
120 7.3.6. Account Deactivation ...............................43
121 7.4. Applying for Certificate Issuance .........................44
122 7.4.1. Pre-authorization ..................................49
123 7.4.2. Downloading the Certificate ........................51
124 7.5. Identifier Authorization ..................................53
125 7.5.1. Responding to Challenges ...........................54
126 7.5.2. Deactivating an Authorization ......................57
127 7.6. Certificate Revocation ....................................58
128 8. Identifier Validation Challenges ...............................60
129 8.1. Key Authorizations ........................................62
130 8.2. Retrying Challenges .......................................63
131 8.3. HTTP Challenge ............................................63
132 8.4. DNS Challenge .............................................66
133 9. IANA Considerations ............................................68
134 9.1. Media Type: application/pem-certificate-chain .............68
135 9.2. Well-Known URI for the HTTP Challenge .....................69
136 9.3. Replay-Nonce HTTP Header ..................................69
137 9.4. "url" JWS Header Parameter ................................70
138 9.5. "nonce" JWS Header Parameter ..............................70
139 9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) .........70
140 9.7. New Registries ............................................71
141 9.7.1. Fields in Account Objects ..........................71
142 9.7.2. Fields in Order Objects ............................72
143 9.7.3. Fields in Authorization Objects ....................73
144 9.7.4. Error Types ........................................74
145 9.7.5. Resource Types .....................................74
146 9.7.6. Fields in the "meta" Object within a
147 Directory Object ...................................75
148 9.7.7. Identifier Types ...................................76
149 9.7.8. Validation Methods .................................76
150 10. Security Considerations .......................................78
151 10.1. Threat Model .............................................78
152 10.2. Integrity of Authorizations ..............................80
153 10.3. Denial-of-Service Considerations .........................83
154 10.4. Server-Side Request Forgery ..............................84
155 10.5. CA Policy Considerations .................................84
156 11. Operational Considerations ....................................86
157 11.1. Key Selection ............................................86
158 11.2. DNS Security .............................................87
159 11.3. Token Entropy ............................................88
160 11.4. Malformed Certificate Chains .............................88
161 12. References ....................................................88
162 12.1. Normative References .....................................88
163 12.2. Informative References ...................................92
164 Acknowledgements ..................................................94
165 Authors' Addresses ................................................95
166
167
168
169
170Barnes, et al. Standards Track [Page 3]
171
172RFC 8555 ACME March 2019
173
174
1751. Introduction
176
177 Certificates [RFC5280] in the Web PKI are most commonly used to
178 authenticate domain names. Thus, certification authorities (CAs) in
179 the Web PKI are trusted to verify that an applicant for a certificate
180 legitimately represents the domain name(s) in the certificate.
181
182 Different types of certificates reflect different kinds of CA
183 verification of information about the certificate subject. "Domain
184 Validation" (DV) certificates are by far the most common type. The
185 only validation the CA is required to perform in the DV issuance
186 process is to verify that the requester has effective control of the
187 domain [CABFBR]. The CA is not required to attempt to verify the
188 requester's real-world identity. (This is as opposed to
189 "Organization Validation" (OV) and "Extended Validation" (EV)
190 certificates, where the process is intended to also verify the real-
191 world identity of the requester.)
192
193 Existing Web PKI certification authorities tend to use a set of ad
194 hoc protocols for certificate issuance and identity verification. In
195 the case of DV certificates, a typical user experience is something
196 like:
197
198 o Generate a PKCS#10 [RFC2986] Certificate Signing Request (CSR).
199
200 o Cut and paste the CSR into a CA's web page.
201
202 o Prove ownership of the domain(s) in the CSR by one of the
203 following methods:
204
205 * Put a CA-provided challenge at a specific place on the web
206 server.
207
208 * Put a CA-provided challenge in a DNS record corresponding to
209 the target domain.
210
211 * Receive a CA-provided challenge at (hopefully) an
212 administrator-controlled email address corresponding to the
213 domain, and then respond to it on the CA's web page.
214
215 o Download the issued certificate and install it on the user's Web
216 Server.
217
218 With the exception of the CSR itself and the certificates that are
219 issued, these are all completely ad hoc procedures and are
220 accomplished by getting the human user to follow interactive natural-
221 language instructions from the CA rather than by machine-implemented
222 published protocols. In many cases, the instructions are difficult
223
224
225
226Barnes, et al. Standards Track [Page 4]
227
228RFC 8555 ACME March 2019
229
230
231 to follow and cause significant frustration and confusion. Informal
232 usability tests by the authors indicate that webmasters often need
233 1-3 hours to obtain and install a certificate for a domain. Even in
234 the best case, the lack of published, standardized mechanisms
235 presents an obstacle to the wide deployment of HTTPS and other PKIX-
236 dependent systems because it inhibits mechanization of tasks related
237 to certificate issuance, deployment, and revocation.
238
239 This document describes an extensible framework for automating the
240 issuance and domain validation procedure, thereby allowing servers
241 and infrastructure software to obtain certificates without user
242 interaction. Use of this protocol should radically simplify the
243 deployment of HTTPS and the practicality of PKIX-based authentication
244 for other protocols based on Transport Layer Security (TLS)
245 [RFC8446].
246
247 It should be noted that while the focus of this document is on
248 validating domain names for purposes of issuing certificates in the
249 Web PKI, ACME supports extensions for uses with other identifiers in
250 other PKI contexts. For example, as of this writing, there is
251 ongoing work to use ACME for issuance of Web PKI certificates
252 attesting to IP addresses [ACME-IP] and Secure Telephone Identity
253 Revisited (STIR) certificates attesting to telephone numbers
254 [ACME-TELEPHONE].
255
256 ACME can also be used to automate some aspects of certificate
257 management even where non-automated processes are still needed. For
258 example, the external account binding feature (see Section 7.3.4) can
259 allow an ACME account to use authorizations that have been granted to
260 an external, non-ACME account. This allows ACME to address issuance
261 scenarios that cannot yet be fully automated, such as the issuance of
262 "Extended Validation" certificates.
263
2642. Deployment Model and Operator Experience
265
266 The guiding use case for ACME is obtaining certificates for websites
267 (HTTPS [RFC2818]). In this case, a web server is intended to speak
268 for one or more domains, and the process of certificate issuance is
269 intended to verify that this web server actually speaks for the
270 domain(s).
271
272 DV certificate validation commonly checks claims about properties
273 related to control of a domain name -- properties that can be
274 observed by the certificate issuer in an interactive process that can
275 be conducted purely online. That means that under typical
276 circumstances, all steps in the request, verification, and issuance
277 process can be represented and performed by Internet protocols with
278 no out-of-band human intervention.
279
280
281
282Barnes, et al. Standards Track [Page 5]
283
284RFC 8555 ACME March 2019
285
286
287 Prior to ACME, when deploying an HTTPS server, a server operator
288 typically gets a prompt to generate a self-signed certificate. If
289 the operator were instead deploying an HTTPS server using ACME, the
290 experience would be something like this:
291
292 o The operator's ACME client prompts the operator for the intended
293 domain name(s) that the web server is to stand for.
294
295 o The ACME client presents the operator with a list of CAs from
296 which it could get a certificate. (This list will change over
297 time based on the capabilities of CAs and updates to ACME
298 configuration.) The ACME client might prompt the operator for
299 payment information at this point.
300
301 o The operator selects a CA.
302
303 o In the background, the ACME client contacts the CA and requests
304 that it issue a certificate for the intended domain name(s).
305
306 o The CA verifies that the client controls the requested domain
307 name(s) by having the ACME client perform some action(s) that can
308 only be done with control of the domain name(s). For example, the
309 CA might require a client requesting example.com to provision a
310 DNS record under example.com or an HTTP resource under
311 http://example.com.
312
313 o Once the CA is satisfied, it issues the certificate and the ACME
314 client automatically downloads and installs it, potentially
315 notifying the operator via email, SMS, etc.
316
317 o The ACME client periodically contacts the CA to get updated
318 certificates, stapled Online Certificate Status Protocol (OCSP)
319 responses [RFC6960], or whatever else would be required to keep
320 the web server functional and its credentials up to date.
321
322 In this way, it would be nearly as easy to deploy with a CA-issued
323 certificate as with a self-signed certificate. Furthermore, the
324 maintenance of that CA-issued certificate would require minimal
325 manual intervention. Such close integration of ACME with HTTPS
326 servers allows the immediate and automated deployment of certificates
327 as they are issued, sparing the human administrator from much of the
328 time-consuming work described in the previous section.
329
330
331
332
333
334
335
336
337
338Barnes, et al. Standards Track [Page 6]
339
340RFC 8555 ACME March 2019
341
342
3433. Terminology
344
345 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
346 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
347 "OPTIONAL" in this document are to be interpreted as described in
348 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
349 capitals, as shown here.
350
351 The two main roles in ACME are "client" and "server". The ACME
352 client uses the protocol to request certificate management actions,
353 such as issuance or revocation. An ACME client may run on a web
354 server, mail server, or some other server system that requires valid
355 X.509 certificates. Or, it may run on a separate server that does
356 not consume the certificate but is authorized to respond to a CA-
357 provided challenge. The ACME server runs at a certification
358 authority and responds to client requests, performing the requested
359 actions if the client is authorized.
360
361 An ACME client authenticates to the server by means of an "account
362 key pair". The client uses the private key of this key pair to sign
363 all messages sent to the server. The server uses the public key to
364 verify the authenticity and integrity of messages from the client.
365
3664. Protocol Overview
367
368 ACME allows a client to request certificate management actions using
369 a set of JavaScript Object Notation (JSON) messages [RFC8259] carried
370 over HTTPS [RFC2818]. Issuance using ACME resembles a traditional
371 CA's issuance process, in which a user creates an account, requests a
372 certificate, and proves control of the domain(s) in that certificate
373 in order for the CA to issue the requested certificate.
374
375 The first phase of ACME is for the client to request an account with
376 the ACME server. The client generates an asymmetric key pair and
377 requests a new account, optionally providing contact information,
378 agreeing to terms of service (ToS), and/or associating the account
379 with an existing account in another system. The creation request is
380 signed with the generated private key to prove that the client
381 controls it.
382
383
384
385
386
387
388
389
390
391
392
393
394Barnes, et al. Standards Track [Page 7]
395
396RFC 8555 ACME March 2019
397
398
399 Client Server
400
401 [Contact Information]
402 [ToS Agreement]
403 [Additional Data]
404 Signature ------->
405 Account URL
406 <------- Account Object
407
408
409 [] Information covered by request signatures
410
411 Account Creation
412
413 Once an account is registered, there are four major steps the client
414 needs to take to get a certificate:
415
416 1. Submit an order for a certificate to be issued
417
418 2. Prove control of any identifiers requested in the certificate
419
420 3. Finalize the order by submitting a CSR
421
422 4. Await issuance and download the issued certificate
423
424 The client's order for a certificate describes the desired
425 identifiers plus a few additional fields that capture semantics that
426 are not supported in the CSR format. If the server is willing to
427 consider issuing such a certificate, it responds with a list of
428 requirements that the client must satisfy before the certificate will
429 be issued.
430
431 For example, in most cases, the server will require the client to
432 demonstrate that it controls the identifiers in the requested
433 certificate. Because there are many different ways to validate
434 possession of different types of identifiers, the server will choose
435 from an extensible set of challenges that are appropriate for the
436 identifier being claimed. The client responds with a set of
437 responses that tell the server which challenges the client has
438 completed. The server then validates that the client has completed
439 the challenges.
440
441 Once the validation process is complete and the server is satisfied
442 that the client has met its requirements, the client finalizes the
443 order by submitting a PKCS#10 Certificate Signing Request (CSR). The
444 server will issue the requested certificate and make it available to
445 the client.
446
447
448
449
450Barnes, et al. Standards Track [Page 8]
451
452RFC 8555 ACME March 2019
453
454
455 Client Server
456
457 [Order]
458 Signature ------->
459 <------- Required Authorizations
460
461 [Responses]
462 Signature ------->
463
464 <~~~~~~~~Validation~~~~~~~~>
465
466 [CSR]
467 Signature ------->
468 <------- Acknowledgement
469
470 <~~~~~~Await issuance~~~~~~>
471
472 [POST-as-GET request]
473 Signature ------->
474 <------- Certificate
475
476 [] Information covered by request signatures
477
478 Certificate Issuance
479
480 To revoke a certificate, the client sends a signed revocation request
481 indicating the certificate to be revoked:
482
483 Client Server
484
485 [Revocation request]
486 Signature -------->
487
488 <-------- Result
489
490 [] Information covered by request signatures
491
492 Certificate Revocation
493
494 Note that while ACME is defined with enough flexibility to handle
495 different types of identifiers in principle, the primary use case
496 addressed by this document is the case where domain names are used as
497 identifiers. For example, all of the identifier validation
498 challenges described in Section 8 address validation of domain names.
499 The use of ACME for other identifiers will require further
500 specification in order to describe how these identifiers are encoded
501 in the protocol and what types of validation challenges the server
502 might require.
503
504
505
506Barnes, et al. Standards Track [Page 9]
507
508RFC 8555 ACME March 2019
509
510
5115. Character Encoding
512
513 All requests and responses sent via HTTP by ACME clients, ACME
514 servers, and validation servers as well as any inputs for digest
515 computations MUST be encoded using the UTF-8 character set [RFC3629].
516 Note that identifiers that appear in certificates may have their own
517 encoding considerations (e.g., DNS names containing non-ASCII
518 characters are expressed as A-labels rather than U-labels). Any such
519 encoding considerations are to be applied prior to the aforementioned
520 UTF-8 encoding.
521
5226. Message Transport
523
524 Communications between an ACME client and an ACME server are done
525 over HTTPS, using JSON Web Signature (JWS) [RFC7515] to provide some
526 additional security properties for messages sent from the client to
527 the server. HTTPS provides server authentication and
528 confidentiality. With some ACME-specific extensions, JWS provides
529 authentication of the client's request payloads, anti-replay
530 protection, and integrity for the HTTPS request URL.
531
5326.1. HTTPS Requests
533
534 Each ACME function is accomplished by the client sending a sequence
535 of HTTPS requests to the server [RFC2818], carrying JSON messages
536 [RFC8259]. Use of HTTPS is REQUIRED. Each subsection of Section 7
537 below describes the message formats used by the function and the
538 order in which messages are sent.
539
540 In most HTTPS transactions used by ACME, the ACME client is the HTTPS
541 client and the ACME server is the HTTPS server. The ACME server acts
542 as a client when validating challenges: an HTTP client when
543 validating an 'http-01' challenge, a DNS client with 'dns-01', etc.
544
545 ACME servers SHOULD follow the recommendations of [RFC7525] when
546 configuring their TLS implementations. ACME servers that support TLS
547 1.3 MAY allow clients to send early data (0-RTT). This is safe
548 because the ACME protocol itself includes anti-replay protections
549 (see Section 6.5) in all cases where they are required. For this
550 reason, there are no restrictions on what ACME data can be carried in
551 0-RTT.
552
553 ACME clients MUST send a User-Agent header field, in accordance with
554 [RFC7231]. This header field SHOULD include the name and version of
555 the ACME software in addition to the name and version of the
556 underlying HTTP client software.
557
558
559
560
561
562Barnes, et al. Standards Track [Page 10]
563
564RFC 8555 ACME March 2019
565
566
567 ACME clients SHOULD send an Accept-Language header field in
568 accordance with [RFC7231] to enable localization of error messages.
569
570 ACME servers that are intended to be generally accessible need to use
571 Cross-Origin Resource Sharing (CORS) in order to be accessible from
572 browser-based clients [W3C.REC-cors-20140116]. Such servers SHOULD
573 set the Access-Control-Allow-Origin header field to the value "*".
574
575 Binary fields in the JSON objects used by ACME are encoded using
576 base64url encoding described in Section 5 of [RFC4648] according to
577 the profile specified in JSON Web Signature in Section 2 of
578 [RFC7515]. This encoding uses a URL safe character set. Trailing
579 '=' characters MUST be stripped. Encoded values that include
580 trailing '=' characters MUST be rejected as improperly encoded.
581
5826.2. Request Authentication
583
584 All ACME requests with a non-empty body MUST encapsulate their
585 payload in a JSON Web Signature (JWS) [RFC7515] object, signed using
586 the account's private key unless otherwise specified. The server
587 MUST verify the JWS before processing the request. Encapsulating
588 request bodies in JWS provides authentication of requests.
589
590 A JWS object sent as the body of an ACME request MUST meet the
591 following additional criteria:
592
593 o The JWS MUST be in the Flattened JSON Serialization [RFC7515]
594
595 o The JWS MUST NOT have multiple signatures
596
597 o The JWS Unencoded Payload Option [RFC7797] MUST NOT be used
598
599 o The JWS Unprotected Header [RFC7515] MUST NOT be used
600
601 o The JWS Payload MUST NOT be detached
602
603 o The JWS Protected Header MUST include the following fields:
604
605 * "alg" (Algorithm)
606
607 + This field MUST NOT contain "none" or a Message
608 Authentication Code (MAC) algorithm (e.g. one in which the
609 algorithm registry description mentions MAC/HMAC).
610
611 * "nonce" (defined in Section 6.5)
612
613 * "url" (defined in Section 6.4)
614
615
616
617
618Barnes, et al. Standards Track [Page 11]
619
620RFC 8555 ACME March 2019
621
622
623 * Either "jwk" (JSON Web Key) or "kid" (Key ID) as specified
624 below
625
626 An ACME server MUST implement the "ES256" signature algorithm
627 [RFC7518] and SHOULD implement the "EdDSA" signature algorithm using
628 the "Ed25519" variant (indicated by "crv") [RFC8037].
629
630 The "jwk" and "kid" fields are mutually exclusive. Servers MUST
631 reject requests that contain both.
632
633 For newAccount requests, and for revokeCert requests authenticated by
634 a certificate key, there MUST be a "jwk" field. This field MUST
635 contain the public key corresponding to the private key used to sign
636 the JWS.
637
638 For all other requests, the request is signed using an existing
639 account, and there MUST be a "kid" field. This field MUST contain
640 the account URL received by POSTing to the newAccount resource.
641
642 If the client sends a JWS signed with an algorithm that the server
643 does not support, then the server MUST return an error with status
644 code 400 (Bad Request) and type
645 "urn:ietf:params:acme:error:badSignatureAlgorithm". The problem
646 document returned with the error MUST include an "algorithms" field
647 with an array of supported "alg" values. See Section 6.7 for more
648 details on the structure of error responses.
649
650 If the server supports the signature algorithm "alg" but either does
651 not support or chooses to reject the public key "jwk", then the
652 server MUST return an error with status code 400 (Bad Request) and
653 type "urn:ietf:params:acme:error:badPublicKey". The problem document
654 detail SHOULD describe the reason for rejecting the public key; some
655 example reasons are:
656
657 o "alg" is "RS256" but the modulus "n" is too small (e.g., 512-bit)
658
659 o "alg" is "ES256" but "jwk" does not contain a valid P-256 public
660 key
661
662 o "alg" is "EdDSA" and "crv" is "Ed448", but the server only
663 supports "EdDSA" with "Ed25519"
664
665 o the corresponding private key is known to have been compromised
666
667
668
669
670
671
672
673
674Barnes, et al. Standards Track [Page 12]
675
676RFC 8555 ACME March 2019
677
678
679 Because client requests in ACME carry JWS objects in the Flattened
680 JSON Serialization, they must have the Content-Type header field set
681 to "application/jose+json". If a request does not meet this
682 requirement, then the server MUST return a response with status code
683 415 (Unsupported Media Type).
684
6856.3. GET and POST-as-GET Requests
686
687 Note that authentication via signed JWS request bodies implies that
688 requests without an entity body are not authenticated, in particular
689 GET requests. Except for the cases described in this section, if the
690 server receives a GET request, it MUST return an error with status
691 code 405 (Method Not Allowed) and type "malformed".
692
693 If a client wishes to fetch a resource from the server (which would
694 otherwise be done with a GET), then it MUST send a POST request with
695 a JWS body as described above, where the payload of the JWS is a
696 zero-length octet string. In other words, the "payload" field of the
697 JWS object MUST be present and set to the empty string ("").
698
699 We will refer to these as "POST-as-GET" requests. On receiving a
700 request with a zero-length (and thus non-JSON) payload, the server
701 MUST authenticate the sender and verify any access control rules.
702 Otherwise, the server MUST treat this request as having the same
703 semantics as a GET request for the same resource.
704
705 The server MUST allow GET requests for the directory and newNonce
706 resources (see Section 7.1), in addition to POST-as-GET requests for
707 these resources. This enables clients to bootstrap into the ACME
708 authentication system.
709
7106.4. Request URL Integrity
711
712 It is common in deployment for the entity terminating TLS for HTTPS
713 to be different from the entity operating the logical HTTPS server,
714 with a "request routing" layer in the middle. For example, an ACME
715 CA might have a content delivery network terminate TLS connections
716 from clients so that it can inspect client requests for denial-of-
717 service (DoS) protection.
718
719 These intermediaries can also change values in the request that are
720 not signed in the HTTPS request, e.g., the request URL and header
721 fields. ACME uses JWS to provide an integrity mechanism, which
722 protects against an intermediary changing the request URL to another
723 ACME URL.
724
725
726
727
728
729
730Barnes, et al. Standards Track [Page 13]
731
732RFC 8555 ACME March 2019
733
734
735 As noted in Section 6.2, all ACME request objects carry a "url"
736 header parameter in their protected header. This header parameter
737 encodes the URL to which the client is directing the request. On
738 receiving such an object in an HTTP request, the server MUST compare
739 the "url" header parameter to the request URL. If the two do not
740 match, then the server MUST reject the request as unauthorized.
741
742 Except for the directory resource, all ACME resources are addressed
743 with URLs provided to the client by the server. In POST requests
744 sent to these resources, the client MUST set the "url" header
745 parameter to the exact string provided by the server (rather than
746 performing any re-encoding on the URL). The server SHOULD perform
747 the corresponding string equality check, configuring each resource
748 with the URL string provided to clients and having the resource check
749 that requests have the same string in their "url" header parameter.
750 The server MUST reject the request as unauthorized if the string
751 equality check fails.
752
7536.4.1. "url" (URL) JWS Header Parameter
754
755 The "url" header parameter specifies the URL [RFC3986] to which this
756 JWS object is directed. The "url" header parameter MUST be carried
757 in the protected header of the JWS. The value of the "url" header
758 parameter MUST be a string representing the target URL.
759
7606.5. Replay Protection
761
762 In order to protect ACME resources from any possible replay attacks,
763 ACME POST requests have a mandatory anti-replay mechanism. This
764 mechanism is based on the server maintaining a list of nonces that it
765 has issued, and requiring any signed request from the client to carry
766 such a nonce.
767
768 An ACME server provides nonces to clients using the HTTP Replay-Nonce
769 header field, as specified in Section 6.5.1. The server MUST include
770 a Replay-Nonce header field in every successful response to a POST
771 request and SHOULD provide it in error responses as well.
772
773 Every JWS sent by an ACME client MUST include, in its protected
774 header, the "nonce" header parameter, with contents as defined in
775 Section 6.5.2. As part of JWS verification, the ACME server MUST
776 verify that the value of the "nonce" header is a value that the
777 server previously provided in a Replay-Nonce header field. Once a
778 nonce value has appeared in an ACME request, the server MUST consider
779 it invalid, in the same way as a value it had never issued.
780
781
782
783
784
785
786Barnes, et al. Standards Track [Page 14]
787
788RFC 8555 ACME March 2019
789
790
791 When a server rejects a request because its nonce value was
792 unacceptable (or not present), it MUST provide HTTP status code 400
793 (Bad Request), and indicate the ACME error type
794 "urn:ietf:params:acme:error:badNonce". An error response with the
795 "badNonce" error type MUST include a Replay-Nonce header field with a
796 fresh nonce that the server will accept in a retry of the original
797 query (and possibly in other requests, according to the server's
798 nonce scoping policy). On receiving such a response, a client SHOULD
799 retry the request using the new nonce.
800
801 The precise method used to generate and track nonces is up to the
802 server. For example, the server could generate a random 128-bit
803 value for each response, keep a list of issued nonces, and strike
804 nonces from this list as they are used.
805
806 Other than the constraint above with regard to nonces issued in
807 "badNonce" responses, ACME does not constrain how servers scope
808 nonces. Clients MAY assume that nonces have broad scope, e.g., by
809 having a single pool of nonces used for all requests. However, when
810 retrying in response to a "badNonce" error, the client MUST use the
811 nonce provided in the error response. Servers should scope nonces
812 broadly enough that retries are not needed very often.
813
8146.5.1. Replay-Nonce
815
816 The Replay-Nonce HTTP header field includes a server-generated value
817 that the server can use to detect unauthorized replay in future
818 client requests. The server MUST generate the values provided in
819 Replay-Nonce header fields in such a way that they are unique to each
820 message, with high probability, and unpredictable to anyone besides
821 the server. For instance, it is acceptable to generate Replay-Nonces
822 randomly.
823
824 The value of the Replay-Nonce header field MUST be an octet string
825 encoded according to the base64url encoding described in Section 2 of
826 [RFC7515]. Clients MUST ignore invalid Replay-Nonce values. The
827 ABNF [RFC5234] for the Replay-Nonce header field follows:
828
829 base64url = ALPHA / DIGIT / "-" / "_"
830
831 Replay-Nonce = 1*base64url
832
833 The Replay-Nonce header field SHOULD NOT be included in HTTP request
834 messages.
835
836
837
838
839
840
841
842Barnes, et al. Standards Track [Page 15]
843
844RFC 8555 ACME March 2019
845
846
8476.5.2. "nonce" (Nonce) JWS Header Parameter
848
849 The "nonce" header parameter provides a unique value that enables the
850 verifier of a JWS to recognize when replay has occurred. The "nonce"
851 header parameter MUST be carried in the protected header of the JWS.
852
853 The value of the "nonce" header parameter MUST be an octet string,
854 encoded according to the base64url encoding described in Section 2 of
855 [RFC7515]. If the value of a "nonce" header parameter is not valid
856 according to this encoding, then the verifier MUST reject the JWS as
857 malformed.
858
8596.6. Rate Limits
860
861 Creation of resources can be rate limited by ACME servers to ensure
862 fair usage and prevent abuse. Once the rate limit is exceeded, the
863 server MUST respond with an error with the type
864 "urn:ietf:params:acme:error:rateLimited". Additionally, the server
865 SHOULD send a Retry-After header field [RFC7231] indicating when the
866 current request may succeed again. If multiple rate limits are in
867 place, that is the time where all rate limits allow access again for
868 the current request with exactly the same parameters.
869
870 In addition to the human-readable "detail" field of the error
871 response, the server MAY send one or multiple link relations in the
872 Link header field [RFC8288] pointing to documentation about the
873 specific rate limit that was hit, using the "help" link relation
874 type.
875
8766.7. Errors
877
878 Errors can be reported in ACME both at the HTTP layer and within
879 challenge objects as defined in Section 8. ACME servers can return
880 responses with an HTTP error response code (4XX or 5XX). For
881 example, if the client submits a request using a method not allowed
882 in this document, then the server MAY return status code 405 (Method
883 Not Allowed).
884
885 When the server responds with an error status, it SHOULD provide
886 additional information using a problem document [RFC7807]. To
887 facilitate automatic response to errors, this document defines the
888 following standard tokens for use in the "type" field (within the
889 ACME URN namespace "urn:ietf:params:acme:error:"):
890
891
892
893
894
895
896
897
898Barnes, et al. Standards Track [Page 16]
899
900RFC 8555 ACME March 2019
901
902
903 +-------------------------+-----------------------------------------+
904 | Type | Description |
905 +-------------------------+-----------------------------------------+
906 | accountDoesNotExist | The request specified an account that |
907 | | does not exist |
908 | | |
909 | alreadyRevoked | The request specified a certificate to |
910 | | be revoked that has already been |
911 | | revoked |
912 | | |
913 | badCSR | The CSR is unacceptable (e.g., due to a |
914 | | short key) |
915 | | |
916 | badNonce | The client sent an unacceptable anti- |
917 | | replay nonce |
918 | | |
919 | badPublicKey | The JWS was signed by a public key the |
920 | | server does not support |
921 | | |
922 | badRevocationReason | The revocation reason provided is not |
923 | | allowed by the server |
924 | | |
925 | badSignatureAlgorithm | The JWS was signed with an algorithm |
926 | | the server does not support |
927 | | |
928 | caa | Certification Authority Authorization |
929 | | (CAA) records forbid the CA from |
930 | | issuing a certificate |
931 | | |
932 | compound | Specific error conditions are indicated |
933 | | in the "subproblems" array |
934 | | |
935 | connection | The server could not connect to |
936 | | validation target |
937 | | |
938 | dns | There was a problem with a DNS query |
939 | | during identifier validation |
940 | | |
941 | externalAccountRequired | The request must include a value for |
942 | | the "externalAccountBinding" field |
943 | | |
944 | incorrectResponse | Response received didn't match the |
945 | | challenge's requirements |
946 | | |
947 | invalidContact | A contact URL for an account was |
948 | | invalid |
949 | | |
950 | malformed | The request message was malformed |
951
952
953
954Barnes, et al. Standards Track [Page 17]
955
956RFC 8555 ACME March 2019
957
958
959 | | |
960 | orderNotReady | The request attempted to finalize an |
961 | | order that is not ready to be finalized |
962 | | |
963 | rateLimited | The request exceeds a rate limit |
964 | | |
965 | rejectedIdentifier | The server will not issue certificates |
966 | | for the identifier |
967 | | |
968 | serverInternal | The server experienced an internal |
969 | | error |
970 | | |
971 | tls | The server received a TLS error during |
972 | | validation |
973 | | |
974 | unauthorized | The client lacks sufficient |
975 | | authorization |
976 | | |
977 | unsupportedContact | A contact URL for an account used an |
978 | | unsupported protocol scheme |
979 | | |
980 | unsupportedIdentifier | An identifier is of an unsupported type |
981 | | |
982 | userActionRequired | Visit the "instance" URL and take |
983 | | actions specified there |
984 +-------------------------+-----------------------------------------+
985
986 This list is not exhaustive. The server MAY return errors whose
987 "type" field is set to a URI other than those defined above. Servers
988 MUST NOT use the ACME URN namespace for errors not listed in the
989 appropriate IANA registry (see Section 9.6). Clients SHOULD display
990 the "detail" field of all errors.
991
992 In the remainder of this document, we use the tokens in the table
993 above to refer to error types, rather than the full URNs. For
994 example, an "error of type 'badCSR'" refers to an error document with
995 "type" value "urn:ietf:params:acme:error:badCSR".
996
9976.7.1. Subproblems
998
999 Sometimes a CA may need to return multiple errors in response to a
1000 request. Additionally, the CA may need to attribute errors to
1001 specific identifiers. For instance, a newOrder request may contain
1002 multiple identifiers for which the CA cannot issue certificates. In
1003 this situation, an ACME problem document MAY contain the
1004 "subproblems" field, containing a JSON array of problem documents,
1005 each of which MAY contain an "identifier" field. If present, the
1006 "identifier" field MUST contain an ACME identifier (Section 9.7.7).
1007
1008
1009
1010Barnes, et al. Standards Track [Page 18]
1011
1012RFC 8555 ACME March 2019
1013
1014
1015 The "identifier" field MUST NOT be present at the top level in ACME
1016 problem documents. It can only be present in subproblems.
1017 Subproblems need not all have the same type, and they do not need to
1018 match the top level type.
1019
1020 ACME clients may choose to use the "identifier" field of a subproblem
1021 as a hint that an operation would succeed if that identifier were
1022 omitted. For instance, if an order contains ten DNS identifiers, and
1023 the newOrder request returns a problem document with two subproblems
1024 (referencing two of those identifiers), the ACME client may choose to
1025 submit another order containing only the eight identifiers not listed
1026 in the problem document.
1027
1028HTTP/1.1 403 Forbidden
1029Content-Type: application/problem+json
1030Link: <https://example.com/acme/directory>;rel="index"
1031
1032{
1033 "type": "urn:ietf:params:acme:error:malformed",
1034 "detail": "Some of the identifiers requested were rejected",
1035 "subproblems": [
1036 {
1037 "type": "urn:ietf:params:acme:error:malformed",
1038 "detail": "Invalid underscore in DNS name \"_example.org\"",
1039 "identifier": {
1040 "type": "dns",
1041 "value": "_example.org"
1042 }
1043 },
1044 {
1045 "type": "urn:ietf:params:acme:error:rejectedIdentifier",
1046 "detail": "This CA will not issue for \"example.net\"",
1047 "identifier": {
1048 "type": "dns",
1049 "value": "example.net"
1050 }
1051 }
1052 ]
1053}
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066Barnes, et al. Standards Track [Page 19]
1067
1068RFC 8555 ACME March 2019
1069
1070
10717. Certificate Management
1072
1073 In this section, we describe the certificate management functions
1074 that ACME enables:
1075
1076 o Account Creation
1077
1078 o Ordering a Certificate
1079
1080 o Identifier Authorization
1081
1082 o Certificate Issuance
1083
1084 o Certificate Revocation
1085
10867.1. Resources
1087
1088 ACME is structured as an HTTP-based application with the following
1089 types of resources:
1090
1091 o Account resources, representing information about an account
1092 (Section 7.1.2, Section 7.3)
1093
1094 o Order resources, representing an account's requests to issue
1095 certificates (Section 7.1.3)
1096
1097 o Authorization resources, representing an account's authorization
1098 to act for an identifier (Section 7.1.4)
1099
1100 o Challenge resources, representing a challenge to prove control of
1101 an identifier (Section 7.5, Section 8)
1102
1103 o Certificate resources, representing issued certificates
1104 (Section 7.4.2)
1105
1106 o A "directory" resource (Section 7.1.1)
1107
1108 o A "newNonce" resource (Section 7.2)
1109
1110 o A "newAccount" resource (Section 7.3)
1111
1112 o A "newOrder" resource (Section 7.4)
1113
1114 o A "revokeCert" resource (Section 7.6)
1115
1116 o A "keyChange" resource (Section 7.3.5)
1117
1118 The server MUST provide "directory" and "newNonce" resources.
1119
1120
1121
1122Barnes, et al. Standards Track [Page 20]
1123
1124RFC 8555 ACME March 2019
1125
1126
1127 ACME uses different URLs for different management functions. Each
1128 function is listed in a directory along with its corresponding URL,
1129 so clients only need to be configured with the directory URL. These
1130 URLs are connected by a few different link relations [RFC8288].
1131
1132 The "up" link relation is used with challenge resources to indicate
1133 the authorization resource to which a challenge belongs. It is also
1134 used, with some media types, from certificate resources to indicate a
1135 resource from which the client may fetch a chain of CA certificates
1136 that could be used to validate the certificate in the original
1137 resource.
1138
1139 The "index" link relation is present on all resources other than the
1140 directory and indicates the URL of the directory.
1141
1142 The following diagram illustrates the relations between resources on
1143 an ACME server. For the most part, these relations are expressed by
1144 URLs provided as strings in the resources' JSON representations.
1145 Lines with labels in quotes indicate HTTP link relations.
1146
1147 directory
1148 |
1149 +--> newNonce
1150 |
1151 +----------+----------+-----+-----+------------+
1152 | | | | |
1153 | | | | |
1154 V V V V V
1155 newAccount newAuthz newOrder revokeCert keyChange
1156 | | |
1157 | | |
1158 V | V
1159 account | order --+--> finalize
1160 | | |
1161 | | +--> cert
1162 | V
1163 +---> authorization
1164 | ^
1165 | | "up"
1166 V |
1167 challenge
1168
1169 ACME Resources and Relationships
1170
1171
1172
1173
1174
1175
1176
1177
1178Barnes, et al. Standards Track [Page 21]
1179
1180RFC 8555 ACME March 2019
1181
1182
1183 The following table illustrates a typical sequence of requests
1184 required to establish a new account with the server, prove control of
1185 an identifier, issue a certificate, and fetch an updated certificate
1186 some time after issuance. The "->" is a mnemonic for a Location
1187 header field pointing to a created resource.
1188
1189 +-------------------+--------------------------------+--------------+
1190 | Action | Request | Response |
1191 +-------------------+--------------------------------+--------------+
1192 | Get directory | GET directory | 200 |
1193 | | | |
1194 | Get nonce | HEAD newNonce | 200 |
1195 | | | |
1196 | Create account | POST newAccount | 201 -> |
1197 | | | account |
1198 | | | |
1199 | Submit order | POST newOrder | 201 -> order |
1200 | | | |
1201 | Fetch challenges | POST-as-GET order's | 200 |
1202 | | authorization urls | |
1203 | | | |
1204 | Respond to | POST authorization challenge | 200 |
1205 | challenges | urls | |
1206 | | | |
1207 | Poll for status | POST-as-GET order | 200 |
1208 | | | |
1209 | Finalize order | POST order's finalize url | 200 |
1210 | | | |
1211 | Poll for status | POST-as-GET order | 200 |
1212 | | | |
1213 | Download | POST-as-GET order's | 200 |
1214 | certificate | certificate url | |
1215 +-------------------+--------------------------------+--------------+
1216
1217 The remainder of this section provides the details of how these
1218 resources are structured and how the ACME protocol makes use of them.
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234Barnes, et al. Standards Track [Page 22]
1235
1236RFC 8555 ACME March 2019
1237
1238
12397.1.1. Directory
1240
1241 In order to help clients configure themselves with the right URLs for
1242 each ACME operation, ACME servers provide a directory object. This
1243 should be the only URL needed to configure clients. It is a JSON
1244 object, whose field names are drawn from the resource registry
1245 (Section 9.7.5) and whose values are the corresponding URLs.
1246
1247 +------------+--------------------+
1248 | Field | URL in Value |
1249 +------------+--------------------+
1250 | newNonce | New nonce |
1251 | | |
1252 | newAccount | New account |
1253 | | |
1254 | newOrder | New order |
1255 | | |
1256 | newAuthz | New authorization |
1257 | | |
1258 | revokeCert | Revoke certificate |
1259 | | |
1260 | keyChange | Key change |
1261 +------------+--------------------+
1262
1263 There is no constraint on the URL of the directory except that it
1264 should be different from the other ACME server resources' URLs, and
1265 that it should not clash with other services. For instance:
1266
1267 o a host that functions as both an ACME and a Web server may want to
1268 keep the root path "/" for an HTML "front page" and place the ACME
1269 directory under the path "/acme".
1270
1271 o a host that only functions as an ACME server could place the
1272 directory under the path "/".
1273
1274 If the ACME server does not implement pre-authorization
1275 (Section 7.4.1), it MUST omit the "newAuthz" field of the directory.
1276
1277 The object MAY additionally contain a "meta" field. If present, it
1278 MUST be a JSON object; each field in the object is an item of
1279 metadata relating to the service provided by the ACME server.
1280
1281 The following metadata items are defined (Section 9.7.6), all of
1282 which are OPTIONAL:
1283
1284 termsOfService (optional, string): A URL identifying the current
1285 terms of service.
1286
1287
1288
1289
1290Barnes, et al. Standards Track [Page 23]
1291
1292RFC 8555 ACME March 2019
1293
1294
1295 website (optional, string): An HTTP or HTTPS URL locating a website
1296 providing more information about the ACME server.
1297
1298 caaIdentities (optional, array of string): The hostnames that the
1299 ACME server recognizes as referring to itself for the purposes of
1300 CAA record validation as defined in [RFC6844]. Each string MUST
1301 represent the same sequence of ASCII code points that the server
1302 will expect to see as the "Issuer Domain Name" in a CAA issue or
1303 issuewild property tag. This allows clients to determine the
1304 correct issuer domain name to use when configuring CAA records.
1305
1306 externalAccountRequired (optional, boolean): If this field is
1307 present and set to "true", then the CA requires that all
1308 newAccount requests include an "externalAccountBinding" field
1309 associating the new account with an external account.
1310
1311 Clients access the directory by sending a GET request to the
1312 directory URL.
1313
1314 HTTP/1.1 200 OK
1315 Content-Type: application/json
1316
1317 {
1318 "newNonce": "https://example.com/acme/new-nonce",
1319 "newAccount": "https://example.com/acme/new-account",
1320 "newOrder": "https://example.com/acme/new-order",
1321 "newAuthz": "https://example.com/acme/new-authz",
1322 "revokeCert": "https://example.com/acme/revoke-cert",
1323 "keyChange": "https://example.com/acme/key-change",
1324 "meta": {
1325 "termsOfService": "https://example.com/acme/terms/2017-5-30",
1326 "website": "https://www.example.com/",
1327 "caaIdentities": ["example.com"],
1328 "externalAccountRequired": false
1329 }
1330 }
1331
13327.1.2. Account Objects
1333
1334 An ACME account resource represents a set of metadata associated with
1335 an account. Account resources have the following structure:
1336
1337 status (required, string): The status of this account. Possible
1338 values are "valid", "deactivated", and "revoked". The value
1339 "deactivated" should be used to indicate client-initiated
1340 deactivation whereas "revoked" should be used to indicate server-
1341 initiated deactivation. See Section 7.1.6.
1342
1343
1344
1345
1346Barnes, et al. Standards Track [Page 24]
1347
1348RFC 8555 ACME March 2019
1349
1350
1351 contact (optional, array of string): An array of URLs that the
1352 server can use to contact the client for issues related to this
1353 account. For example, the server may wish to notify the client
1354 about server-initiated revocation or certificate expiration. For
1355 information on supported URL schemes, see Section 7.3.
1356
1357 termsOfServiceAgreed (optional, boolean): Including this field in a
1358 newAccount request, with a value of true, indicates the client's
1359 agreement with the terms of service. This field cannot be updated
1360 by the client.
1361
1362 externalAccountBinding (optional, object): Including this field in a
1363 newAccount request indicates approval by the holder of an existing
1364 non-ACME account to bind that account to this ACME account. This
1365 field is not updateable by the client (see Section 7.3.4).
1366
1367 orders (required, string): A URL from which a list of orders
1368 submitted by this account can be fetched via a POST-as-GET
1369 request, as described in Section 7.1.2.1.
1370
1371 {
1372 "status": "valid",
1373 "contact": [
1374 "mailto:cert-admin@example.org",
1375 "mailto:admin@example.org"
1376 ],
1377 "termsOfServiceAgreed": true,
1378 "orders": "https://example.com/acme/orders/rzGoeA"
1379 }
1380
13817.1.2.1. Orders List
1382
1383 Each account object includes an "orders" URL from which a list of
1384 orders created by the account can be fetched via POST-as-GET request.
1385 The result of the request MUST be a JSON object whose "orders" field
1386 is an array of URLs, each identifying an order belonging to the
1387 account. The server SHOULD include pending orders and SHOULD NOT
1388 include orders that are invalid in the array of URLs. The server MAY
1389 return an incomplete list, along with a Link header field with a
1390 "next" link relation indicating where further entries can be
1391 acquired.
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402Barnes, et al. Standards Track [Page 25]
1403
1404RFC 8555 ACME March 2019
1405
1406
1407 HTTP/1.1 200 OK
1408 Content-Type: application/json
1409 Link: <https://example.com/acme/directory>;rel="index"
1410 Link: <https://example.com/acme/orders/rzGoeA?cursor=2>;rel="next"
1411
1412 {
1413 "orders": [
1414 "https://example.com/acme/order/TOlocE8rfgo",
1415 "https://example.com/acme/order/4E16bbL5iSw",
1416 /* more URLs not shown for example brevity */
1417 "https://example.com/acme/order/neBHYLfw0mg"
1418 ]
1419 }
1420
14217.1.3. Order Objects
1422
1423 An ACME order object represents a client's request for a certificate
1424 and is used to track the progress of that order through to issuance.
1425 Thus, the object contains information about the requested
1426 certificate, the authorizations that the server requires the client
1427 to complete, and any certificates that have resulted from this order.
1428
1429 status (required, string): The status of this order. Possible
1430 values are "pending", "ready", "processing", "valid", and
1431 "invalid". See Section 7.1.6.
1432
1433 expires (optional, string): The timestamp after which the server
1434 will consider this order invalid, encoded in the format specified
1435 in [RFC3339]. This field is REQUIRED for objects with "pending"
1436 or "valid" in the status field.
1437
1438 identifiers (required, array of object): An array of identifier
1439 objects that the order pertains to.
1440
1441 type (required, string): The type of identifier. This document
1442 defines the "dns" identifier type. See the registry defined in
1443 Section 9.7.7 for any others.
1444
1445 value (required, string): The identifier itself.
1446
1447 notBefore (optional, string): The requested value of the notBefore
1448 field in the certificate, in the date format defined in [RFC3339].
1449
1450 notAfter (optional, string): The requested value of the notAfter
1451 field in the certificate, in the date format defined in [RFC3339].
1452
1453
1454
1455
1456
1457
1458Barnes, et al. Standards Track [Page 26]
1459
1460RFC 8555 ACME March 2019
1461
1462
1463 error (optional, object): The error that occurred while processing
1464 the order, if any. This field is structured as a problem document
1465 [RFC7807].
1466
1467 authorizations (required, array of string): For pending orders, the
1468 authorizations that the client needs to complete before the
1469 requested certificate can be issued (see Section 7.5), including
1470 unexpired authorizations that the client has completed in the past
1471 for identifiers specified in the order. The authorizations
1472 required are dictated by server policy; there may not be a 1:1
1473 relationship between the order identifiers and the authorizations
1474 required. For final orders (in the "valid" or "invalid" state),
1475 the authorizations that were completed. Each entry is a URL from
1476 which an authorization can be fetched with a POST-as-GET request.
1477
1478 finalize (required, string): A URL that a CSR must be POSTed to once
1479 all of the order's authorizations are satisfied to finalize the
1480 order. The result of a successful finalization will be the
1481 population of the certificate URL for the order.
1482
1483 certificate (optional, string): A URL for the certificate that has
1484 been issued in response to this order.
1485
1486 {
1487 "status": "valid",
1488 "expires": "2016-01-20T14:09:07.99Z",
1489
1490 "identifiers": [
1491 { "type": "dns", "value": "www.example.org" },
1492 { "type": "dns", "value": "example.org" }
1493 ],
1494
1495 "notBefore": "2016-01-01T00:00:00Z",
1496 "notAfter": "2016-01-08T00:00:00Z",
1497
1498 "authorizations": [
1499 "https://example.com/acme/authz/PAniVnsZcis",
1500 "https://example.com/acme/authz/r4HqLzrSrpI"
1501 ],
1502
1503 "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize",
1504
1505 "certificate": "https://example.com/acme/cert/mAt3xBGaobw"
1506 }
1507
1508 Any identifier of type "dns" in a newOrder request MAY have a
1509 wildcard domain name as its value. A wildcard domain name consists
1510 of a single asterisk character followed by a single full stop
1511
1512
1513
1514Barnes, et al. Standards Track [Page 27]
1515
1516RFC 8555 ACME March 2019
1517
1518
1519 character ("*.") followed by a domain name as defined for use in the
1520 Subject Alternate Name Extension by [RFC5280]. An authorization
1521 returned by the server for a wildcard domain name identifier MUST NOT
1522 include the asterisk and full stop ("*.") prefix in the authorization
1523 identifier value. The returned authorization MUST include the
1524 optional "wildcard" field, with a value of true.
1525
1526 The elements of the "authorizations" and "identifiers" arrays are
1527 immutable once set. The server MUST NOT change the contents of
1528 either array after they are created. If a client observes a change
1529 in the contents of either array, then it SHOULD consider the order
1530 invalid.
1531
1532 The "authorizations" array of the order SHOULD reflect all
1533 authorizations that the CA takes into account in deciding to issue,
1534 even if some authorizations were fulfilled in earlier orders or in
1535 pre-authorization transactions. For example, if a CA allows multiple
1536 orders to be fulfilled based on a single authorization transaction,
1537 then it SHOULD reflect that authorization in all of the orders.
1538
1539 Note that just because an authorization URL is listed in the
1540 "authorizations" array of an order object doesn't mean that the
1541 client is required to take action. There are several reasons that
1542 the referenced authorizations may already be valid:
1543
1544 o The client completed the authorization as part of a previous order
1545
1546 o The client previously pre-authorized the identifier (see
1547 Section 7.4.1)
1548
1549 o The server granted the client authorization based on an external
1550 account
1551
1552 Clients SHOULD check the "status" field of an order to determine
1553 whether they need to take any action.
1554
15557.1.4. Authorization Objects
1556
1557 An ACME authorization object represents a server's authorization for
1558 an account to represent an identifier. In addition to the
1559 identifier, an authorization includes several metadata fields, such
1560 as the status of the authorization (e.g., "pending", "valid", or
1561 "revoked") and which challenges were used to validate possession of
1562 the identifier.
1563
1564
1565
1566
1567
1568
1569
1570Barnes, et al. Standards Track [Page 28]
1571
1572RFC 8555 ACME March 2019
1573
1574
1575 The structure of an ACME authorization resource is as follows:
1576
1577 identifier (required, object): The identifier that the account is
1578 authorized to represent.
1579
1580 type (required, string): The type of identifier (see below and
1581 Section 9.7.7).
1582
1583 value (required, string): The identifier itself.
1584
1585 status (required, string): The status of this authorization.
1586 Possible values are "pending", "valid", "invalid", "deactivated",
1587 "expired", and "revoked". See Section 7.1.6.
1588
1589 expires (optional, string): The timestamp after which the server
1590 will consider this authorization invalid, encoded in the format
1591 specified in [RFC3339]. This field is REQUIRED for objects with
1592 "valid" in the "status" field.
1593
1594 challenges (required, array of objects): For pending authorizations,
1595 the challenges that the client can fulfill in order to prove
1596 possession of the identifier. For valid authorizations, the
1597 challenge that was validated. For invalid authorizations, the
1598 challenge that was attempted and failed. Each array entry is an
1599 object with parameters required to validate the challenge. A
1600 client should attempt to fulfill one of these challenges, and a
1601 server should consider any one of the challenges sufficient to
1602 make the authorization valid.
1603
1604 wildcard (optional, boolean): This field MUST be present and true
1605 for authorizations created as a result of a newOrder request
1606 containing a DNS identifier with a value that was a wildcard
1607 domain name. For other authorizations, it MUST be absent.
1608 Wildcard domain names are described in Section 7.1.3.
1609
1610 The only type of identifier defined by this specification is a fully
1611 qualified domain name (type: "dns"). The domain name MUST be encoded
1612 in the form in which it would appear in a certificate. That is, it
1613 MUST be encoded according to the rules in Section 7 of [RFC5280].
1614 Servers MUST verify any identifier values that begin with the ASCII-
1615 Compatible Encoding prefix "xn--" as defined in [RFC5890] are
1616 properly encoded. Wildcard domain names (with "*" as the first
1617 label) MUST NOT be included in authorization objects. If an
1618 authorization object conveys authorization for the base domain of a
1619 newOrder DNS identifier containing a wildcard domain name, then the
1620 optional authorizations "wildcard" field MUST be present with a value
1621 of true.
1622
1623
1624
1625
1626Barnes, et al. Standards Track [Page 29]
1627
1628RFC 8555 ACME March 2019
1629
1630
1631 Section 8 describes a set of challenges for domain name validation.
1632
1633 {
1634 "status": "valid",
1635 "expires": "2015-03-01T14:09:07.99Z",
1636
1637 "identifier": {
1638 "type": "dns",
1639 "value": "www.example.org"
1640 },
1641
1642 "challenges": [
1643 {
1644 "url": "https://example.com/acme/chall/prV_B7yEyA4",
1645 "type": "http-01",
1646 "status": "valid",
1647 "token": "DGyRejmCefe7v4NfDGDKfA",
1648 "validated": "2014-12-01T12:05:58.16Z"
1649 }
1650 ],
1651
1652 "wildcard": false
1653 }
1654
16557.1.5. Challenge Objects
1656
1657 An ACME challenge object represents a server's offer to validate a
1658 client's possession of an identifier in a specific way. Unlike the
1659 other objects listed above, there is not a single standard structure
1660 for a challenge object. The contents of a challenge object depend on
1661 the validation method being used. The general structure of challenge
1662 objects and an initial set of validation methods are described in
1663 Section 8.
1664
16657.1.6. Status Changes
1666
1667 Each ACME object type goes through a simple state machine over its
1668 lifetime. The "status" field of the object indicates which state the
1669 object is currently in.
1670
1671 Challenge objects are created in the "pending" state. They
1672 transition to the "processing" state when the client responds to the
1673 challenge (see Section 7.5.1) and the server begins attempting to
1674 validate that the client has completed the challenge. Note that
1675 within the "processing" state, the server may attempt to validate the
1676 challenge multiple times (see Section 8.2). Likewise, client
1677
1678
1679
1680
1681
1682Barnes, et al. Standards Track [Page 30]
1683
1684RFC 8555 ACME March 2019
1685
1686
1687 requests for retries do not cause a state change. If validation is
1688 successful, the challenge moves to the "valid" state; if there is an
1689 error, the challenge moves to the "invalid" state.
1690
1691 pending
1692 |
1693 | Receive
1694 | response
1695 V
1696 processing <-+
1697 | | | Server retry or
1698 | | | client retry request
1699 | +----+
1700 |
1701 |
1702 Successful | Failed
1703 validation | validation
1704 +---------+---------+
1705 | |
1706 V V
1707 valid invalid
1708
1709 State Transitions for Challenge Objects
1710
1711 Authorization objects are created in the "pending" state. If one of
1712 the challenges listed in the authorization transitions to the "valid"
1713 state, then the authorization also changes to the "valid" state. If
1714 the client attempts to fulfill a challenge and fails, or if there is
1715 an error while the authorization is still pending, then the
1716 authorization transitions to the "invalid" state. Once the
1717 authorization is in the "valid" state, it can expire ("expired"), be
1718 deactivated by the client ("deactivated", see Section 7.5.2), or
1719 revoked by the server ("revoked").
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738Barnes, et al. Standards Track [Page 31]
1739
1740RFC 8555 ACME March 2019
1741
1742
1743 pending --------------------+
1744 | |
1745 Challenge failure | |
1746 or | |
1747 Error | Challenge valid |
1748 +---------+---------+ |
1749 | | |
1750 V V |
1751 invalid valid |
1752 | |
1753 | |
1754 | |
1755 +--------------+--------------+
1756 | | |
1757 | | |
1758 Server | Client | Time after |
1759 revoke | deactivate | "expires" |
1760 V V V
1761 revoked deactivated expired
1762
1763 State Transitions for Authorization Objects
1764
1765 Order objects are created in the "pending" state. Once all of the
1766 authorizations listed in the order object are in the "valid" state,
1767 the order transitions to the "ready" state. The order moves to the
1768 "processing" state after the client submits a request to the order's
1769 "finalize" URL and the CA begins the issuance process for the
1770 certificate. Once the certificate is issued, the order enters the
1771 "valid" state. If an error occurs at any of these stages, the order
1772 moves to the "invalid" state. The order also moves to the "invalid"
1773 state if it expires or one of its authorizations enters a final state
1774 other than "valid" ("expired", "revoked", or "deactivated").
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794Barnes, et al. Standards Track [Page 32]
1795
1796RFC 8555 ACME March 2019
1797
1798
1799 pending --------------+
1800 | |
1801 | All authz |
1802 | "valid" |
1803 V |
1804 ready ---------------+
1805 | |
1806 | Receive |
1807 | finalize |
1808 | request |
1809 V |
1810 processing ------------+
1811 | |
1812 | Certificate | Error or
1813 | issued | Authorization failure
1814 V V
1815 valid invalid
1816
1817 State Transitions for Order Objects
1818
1819 Account objects are created in the "valid" state, since no further
1820 action is required to create an account after a successful newAccount
1821 request. If the account is deactivated by the client or revoked by
1822 the server, it moves to the corresponding state.
1823
1824 valid
1825 |
1826 |
1827 +-----------+-----------+
1828 Client | Server |
1829 deactiv.| revoke |
1830 V V
1831 deactivated revoked
1832
1833 State Transitions for Account Objects
1834
1835 Note that some of these states may not ever appear in a "status"
1836 field, depending on server behavior. For example, a server that
1837 issues synchronously will never show an order in the "processing"
1838 state. A server that deletes expired authorizations immediately will
1839 never show an authorization in the "expired" state.
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850Barnes, et al. Standards Track [Page 33]
1851
1852RFC 8555 ACME March 2019
1853
1854
18557.2. Getting a Nonce
1856
1857 Before sending a POST request to the server, an ACME client needs to
1858 have a fresh anti-replay nonce to put in the "nonce" header of the
1859 JWS. In most cases, the client will have gotten a nonce from a
1860 previous request. However, the client might sometimes need to get a
1861 new nonce, e.g., on its first request to the server or if an existing
1862 nonce is no longer valid.
1863
1864 To get a fresh nonce, the client sends a HEAD request to the newNonce
1865 resource on the server. The server's response MUST include a Replay-
1866 Nonce header field containing a fresh nonce and SHOULD have status
1867 code 200 (OK). The server MUST also respond to GET requests for this
1868 resource, returning an empty body (while still providing a Replay-
1869 Nonce header) with a status code of 204 (No Content).
1870
1871 HEAD /acme/new-nonce HTTP/1.1
1872 Host: example.com
1873
1874 HTTP/1.1 200 OK
1875 Replay-Nonce: oFvnlFP1wIhRlYS2jTaXbA
1876 Cache-Control: no-store
1877 Link: <https://example.com/acme/directory>;rel="index"
1878
1879 Proxy caching of responses from the newNonce resource can cause
1880 clients to receive the same nonce repeatedly, leading to "badNonce"
1881 errors. The server MUST include a Cache-Control header field with
1882 the "no-store" directive in responses for the newNonce resource, in
1883 order to prevent caching of this resource.
1884
18857.3. Account Management
1886
1887 In this section, we describe how an ACME client can create an account
1888 on an ACME server and perform some modifications to the account after
1889 it has been created.
1890
1891 A client creates a new account with the server by sending a POST
1892 request to the server's newAccount URL. The body of the request is a
1893 stub account object containing some subset of the following fields:
1894
1895 contact (optional, array of string): Same meaning as the
1896 corresponding server field defined in Section 7.1.2.
1897
1898 termsOfServiceAgreed (optional, boolean): Same meaning as the
1899 corresponding server field defined in Section 7.1.2.
1900
1901
1902
1903
1904
1905
1906Barnes, et al. Standards Track [Page 34]
1907
1908RFC 8555 ACME March 2019
1909
1910
1911 onlyReturnExisting (optional, boolean): If this field is present
1912 with the value "true", then the server MUST NOT create a new
1913 account if one does not already exist. This allows a client to
1914 look up an account URL based on an account key (see
1915 Section 7.3.1).
1916
1917 externalAccountBinding (optional, object): Same meaning as the
1918 corresponding server field defined in Section 7.1.2
1919
1920 POST /acme/new-account HTTP/1.1
1921 Host: example.com
1922 Content-Type: application/jose+json
1923
1924 {
1925 "protected": base64url({
1926 "alg": "ES256",
1927 "jwk": {...},
1928 "nonce": "6S8IqOGY7eL2lsGoTZYifg",
1929 "url": "https://example.com/acme/new-account"
1930 }),
1931 "payload": base64url({
1932 "termsOfServiceAgreed": true,
1933 "contact": [
1934 "mailto:cert-admin@example.org",
1935 "mailto:admin@example.org"
1936 ]
1937 }),
1938 "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
1939 }
1940
1941 The server MUST ignore any values provided in the "orders" fields in
1942 account objects sent by the client, as well as any other fields that
1943 it does not recognize. If new fields are specified in the future,
1944 the specification of those fields MUST describe whether they can be
1945 provided by the client. The server MUST NOT reflect the
1946 "onlyReturnExisting" field or any unrecognized fields in the
1947 resulting account object. This allows clients to detect when servers
1948 do not support an extension field.
1949
1950 The server SHOULD validate that the contact URLs in the "contact"
1951 field are valid and supported by the server. If the server validates
1952 contact URLs, it MUST support the "mailto" scheme. Clients MUST NOT
1953 provide a "mailto" URL in the "contact" field that contains "hfields"
1954 [RFC6068] or more than one "addr-spec" in the "to" component. If a
1955 server encounters a "mailto" contact URL that does not meet these
1956 criteria, then it SHOULD reject it as invalid.
1957
1958
1959
1960
1961
1962Barnes, et al. Standards Track [Page 35]
1963
1964RFC 8555 ACME March 2019
1965
1966
1967 If the server rejects a contact URL for using an unsupported scheme,
1968 it MUST return an error of type "unsupportedContact", with a
1969 description of the error and what types of contact URLs the server
1970 considers acceptable. If the server rejects a contact URL for using
1971 a supported scheme but an invalid value, then the server MUST return
1972 an error of type "invalidContact".
1973
1974 If the server wishes to require the client to agree to terms under
1975 which the ACME service is to be used, it MUST indicate the URL where
1976 such terms can be accessed in the "termsOfService" subfield of the
1977 "meta" field in the directory object, and the server MUST reject
1978 newAccount requests that do not have the "termsOfServiceAgreed" field
1979 set to "true". Clients SHOULD NOT automatically agree to terms by
1980 default. Rather, they SHOULD require some user interaction for
1981 agreement to terms.
1982
1983 The server creates an account and stores the public key used to
1984 verify the JWS (i.e., the "jwk" element of the JWS header) to
1985 authenticate future requests from the account. The server returns
1986 this account object in a 201 (Created) response, with the account URL
1987 in a Location header field. The account URL is used as the "kid"
1988 value in the JWS authenticating subsequent requests by this account
1989 (see Section 6.2). The account URL is also used for requests for
1990 management actions on this account, as described below.
1991
1992 HTTP/1.1 201 Created
1993 Content-Type: application/json
1994 Replay-Nonce: D8s4D2mLs8Vn-goWuPQeKA
1995 Link: <https://example.com/acme/directory>;rel="index"
1996 Location: https://example.com/acme/acct/evOfKhNU60wg
1997
1998 {
1999 "status": "valid",
2000
2001 "contact": [
2002 "mailto:cert-admin@example.org",
2003 "mailto:admin@example.org"
2004 ],
2005
2006 "orders": "https://example.com/acme/acct/evOfKhNU60wg/orders"
2007 }
2008
20097.3.1. Finding an Account URL Given a Key
2010
2011 If the server receives a newAccount request signed with a key for
2012 which it already has an account registered with the provided account
2013 key, then it MUST return a response with status code 200 (OK) and
2014 provide the URL of that account in the Location header field. The
2015
2016
2017
2018Barnes, et al. Standards Track [Page 36]
2019
2020RFC 8555 ACME March 2019
2021
2022
2023 body of this response represents the account object as it existed on
2024 the server before this request; any fields in the request object MUST
2025 be ignored. This allows a client that has an account key but not the
2026 corresponding account URL to recover the account URL.
2027
2028 If a client wishes to find the URL for an existing account and does
2029 not want an account to be created if one does not already exist, then
2030 it SHOULD do so by sending a POST request to the newAccount URL with
2031 a JWS whose payload has an "onlyReturnExisting" field set to "true"
2032 ({"onlyReturnExisting": true}). If a client sends such a request and
2033 an account does not exist, then the server MUST return an error
2034 response with status code 400 (Bad Request) and type
2035 "urn:ietf:params:acme:error:accountDoesNotExist".
2036
20377.3.2. Account Update
2038
2039 If the client wishes to update this information in the future, it
2040 sends a POST request with updated information to the account URL.
2041 The server MUST ignore any updates to the "orders" field,
2042 "termsOfServiceAgreed" field (see Section 7.3.3), the "status" field
2043 (except as allowed by Section 7.3.6), or any other fields it does not
2044 recognize. If the server accepts the update, it MUST return a
2045 response with a 200 (OK) status code and the resulting account
2046 object.
2047
2048 For example, to update the contact information in the above account,
2049 the client could send the following request:
2050
2051 POST /acme/acct/evOfKhNU60wg HTTP/1.1
2052 Host: example.com
2053 Content-Type: application/jose+json
2054
2055 {
2056 "protected": base64url({
2057 "alg": "ES256",
2058 "kid": "https://example.com/acme/acct/evOfKhNU60wg",
2059 "nonce": "ax5RnthDqp_Yf4_HZnFLmA",
2060 "url": "https://example.com/acme/acct/evOfKhNU60wg"
2061 }),
2062 "payload": base64url({
2063 "contact": [
2064 "mailto:certificates@example.org",
2065 "mailto:admin@example.org"
2066 ]
2067 }),
2068 "signature": "hDXzvcj8T6fbFbmn...rDzXzzvzpRy64N0o"
2069 }
2070
2071
2072
2073
2074Barnes, et al. Standards Track [Page 37]
2075
2076RFC 8555 ACME March 2019
2077
2078
20797.3.3. Changes of Terms of Service
2080
2081 As described above, a client can indicate its agreement with the CA's
2082 terms of service by setting the "termsOfServiceAgreed" field in its
2083 account object to "true".
2084
2085 If the server has changed its terms of service since a client
2086 initially agreed, and the server is unwilling to process a request
2087 without explicit agreement to the new terms, then it MUST return an
2088 error response with status code 403 (Forbidden) and type
2089 "urn:ietf:params:acme:error:userActionRequired". This response MUST
2090 include a Link header field with link relation "terms-of-service" and
2091 the latest terms-of-service URL.
2092
2093 The problem document returned with the error MUST also include an
2094 "instance" field, indicating a URL that the client should direct a
2095 human user to visit in order for instructions on how to agree to the
2096 terms.
2097
2098 HTTP/1.1 403 Forbidden
2099 Replay-Nonce: T81bdZroZ2ITWSondpTmAw
2100 Link: <https://example.com/acme/directory>;rel="index"
2101 Link: <https://example.com/acme/terms/2017-6-02>;rel="terms-of-service"
2102 Content-Type: application/problem+json
2103 Content-Language: en
2104
2105 {
2106 "type": "urn:ietf:params:acme:error:userActionRequired",
2107 "detail": "Terms of service have changed",
2108 "instance": "https://example.com/acme/agreement/?token=W8Ih3PswD-8"
2109 }
2110
21117.3.4. External Account Binding ../config/config.go:127
2112
2113 The server MAY require a value for the "externalAccountBinding" field
2114 to be present in "newAccount" requests. This can be used to
2115 associate an ACME account with an existing account in a non-ACME
2116 system, such as a CA customer database.
2117
2118 To enable ACME account binding, the CA operating the ACME server
2119 needs to provide the ACME client with a MAC key and a key identifier,
2120 using some mechanism outside of ACME. The key identifier MUST be an
2121 ASCII string. The MAC key SHOULD be provided in base64url-encoded
2122 form, to maximize compatibility between non-ACME provisioning systems
2123 and ACME clients.
2124
2125
2126
2127
2128
2129
2130Barnes, et al. Standards Track [Page 38]
2131
2132RFC 8555 ACME March 2019
2133
2134
2135 The ACME client then computes a binding JWS to indicate the external
2136 account holder's approval of the ACME account key. The payload of
2137 this JWS is the ACME account key being registered, in JWK form. The
2138 protected header of the JWS MUST meet the following criteria:
2139
2140 o The "alg" field MUST indicate a MAC-based algorithm
2141
2142 o The "kid" field MUST contain the key identifier provided by the CA
2143
2144 o The "nonce" field MUST NOT be present
2145
2146 o The "url" field MUST be set to the same value as the outer JWS
2147
2148 The "signature" field of the JWS will contain the MAC value computed
2149 with the MAC key provided by the CA.
2150
2151 POST /acme/new-account HTTP/1.1
2152 Host: example.com
2153 Content-Type: application/jose+json
2154
2155 {
2156 "protected": base64url({
2157 "alg": "ES256",
2158 "jwk": /* account key */,
2159 "nonce": "K60BWPrMQG9SDxBDS_xtSw",
2160 "url": "https://example.com/acme/new-account"
2161 }),
2162 "payload": base64url({
2163 "contact": [
2164 "mailto:cert-admin@example.org",
2165 "mailto:admin@example.org"
2166 ],
2167 "termsOfServiceAgreed": true,
2168
2169 "externalAccountBinding": {
2170 "protected": base64url({
2171 "alg": "HS256",
2172 "kid": /* key identifier from CA */,
2173 "url": "https://example.com/acme/new-account"
2174 }),
2175 "payload": base64url(/* same as in "jwk" above */),
2176 "signature": /* MAC using MAC key from CA */
2177 }
2178 }),
2179 "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4"
2180 }
2181
2182
2183
2184
2185
2186Barnes, et al. Standards Track [Page 39]
2187
2188RFC 8555 ACME March 2019
2189
2190
2191 If such a CA requires that newAccount requests contain an
2192 "externalAccountBinding" field, then it MUST provide the value "true"
2193 in the "externalAccountRequired" subfield of the "meta" field in the
2194 directory object. If the CA receives a newAccount request without an
2195 "externalAccountBinding" field, then it SHOULD reply with an error of
2196 type "externalAccountRequired".
2197
2198 When a CA receives a newAccount request containing an
2199 "externalAccountBinding" field, it decides whether or not to verify
2200 the binding. If the CA does not verify the binding, then it MUST NOT
2201 reflect the "externalAccountBinding" field in the resulting account
2202 object (if any). To verify the account binding, the CA MUST take the
2203 following steps:
2204
2205 1. Verify that the value of the field is a well-formed JWS
2206
2207 2. Verify that the JWS protected field meets the above criteria
2208
2209 3. Retrieve the MAC key corresponding to the key identifier in the
2210 "kid" field
2211
2212 4. Verify that the MAC on the JWS verifies using that MAC key
2213
2214 5. Verify that the payload of the JWS represents the same key as was
2215 used to verify the outer JWS (i.e., the "jwk" field of the outer
2216 JWS)
2217
2218 If all of these checks pass and the CA creates a new account, then
2219 the CA may consider the new account associated with the external
2220 account corresponding to the MAC key. The account object the CA
2221 returns MUST include an "externalAccountBinding" field with the same
2222 value as the field in the request. If any of these checks fail, then
2223 the CA MUST reject the newAccount request.
2224
22257.3.5. Account Key Rollover
2226
2227 A client may wish to change the public key that is associated with an
2228 account in order to recover from a key compromise or proactively
2229 mitigate the impact of an unnoticed key compromise.
2230
2231 To change the key associated with an account, the client sends a
2232 request to the server containing signatures by both the old and new
2233 keys. The signature by the new key covers the account URL and the
2234 old key, signifying a request by the new key holder to take over the
2235 account from the old key holder. The signature by the old key covers
2236 this request and its signature, and indicates the old key holder's
2237 assent to the rollover request.
2238
2239
2240
2241
2242Barnes, et al. Standards Track [Page 40]
2243
2244RFC 8555 ACME March 2019
2245
2246
2247 To create this request object, the client first constructs a
2248 keyChange object describing the account to be updated and its account
2249 key:
2250
2251 account (required, string): The URL for the account being modified.
2252 The content of this field MUST be the exact string provided in the
2253 Location header field in response to the newAccount request that
2254 created the account.
2255
2256 oldKey (required, JWK): The JWK representation of the old key.
2257
2258 The client then encapsulates the keyChange object in an "inner" JWS,
2259 signed with the requested new account key. This "inner" JWS becomes
2260 the payload for the "outer" JWS that is the body of the ACME request.
2261
2262 The outer JWS MUST meet the normal requirements for an ACME JWS
2263 request body (see Section 6.2). The inner JWS MUST meet the normal
2264 requirements, with the following differences:
2265
2266 o The inner JWS MUST have a "jwk" header parameter, containing the
2267 public key of the new key pair.
2268
2269 o The inner JWS MUST have the same "url" header parameter as the
2270 outer JWS.
2271
2272 o The inner JWS MUST omit the "nonce" header parameter.
2273
2274 This transaction has signatures from both the old and new keys so
2275 that the server can verify that the holders of the two keys both
2276 agree to the change. The signatures are nested to preserve the
2277 property that all signatures on POST messages are signed by exactly
2278 one key. The "inner" JWS effectively represents a request by the
2279 holder of the new key to take over the account form the holder of the
2280 old key. The "outer" JWS represents the current account holder's
2281 assent to this request.
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298Barnes, et al. Standards Track [Page 41]
2299
2300RFC 8555 ACME March 2019
2301
2302
2303 POST /acme/key-change HTTP/1.1
2304 Host: example.com
2305 Content-Type: application/jose+json
2306
2307 {
2308 "protected": base64url({
2309 "alg": "ES256",
2310 "kid": "https://example.com/acme/acct/evOfKhNU60wg",
2311 "nonce": "S9XaOcxP5McpnTcWPIhYuB",
2312 "url": "https://example.com/acme/key-change"
2313 }),
2314 "payload": base64url({
2315 "protected": base64url({
2316 "alg": "ES256",
2317 "jwk": /* new key */,
2318 "url": "https://example.com/acme/key-change"
2319 }),
2320 "payload": base64url({
2321 "account": "https://example.com/acme/acct/evOfKhNU60wg",
2322 "oldKey": /* old key */
2323 }),
2324 "signature": "Xe8B94RD30Azj2ea...8BmZIRtcSKPSd8gU"
2325 }),
2326 "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4"
2327 }
2328
2329 On receiving a keyChange request, the server MUST perform the
2330 following steps in addition to the typical JWS validation:
2331
2332 1. Validate the POST request belongs to a currently active account,
2333 as described in Section 6.
2334
2335 2. Check that the payload of the JWS is a well-formed JWS object
2336 (the "inner JWS").
2337
2338 3. Check that the JWS protected header of the inner JWS has a "jwk"
2339 field.
2340
2341 4. Check that the inner JWS verifies using the key in its "jwk"
2342 field.
2343
2344 5. Check that the payload of the inner JWS is a well-formed
2345 keyChange object (as described above).
2346
2347 6. Check that the "url" parameters of the inner and outer JWSs are
2348 the same.
2349
2350
2351
2352
2353
2354Barnes, et al. Standards Track [Page 42]
2355
2356RFC 8555 ACME March 2019
2357
2358
2359 7. Check that the "account" field of the keyChange object contains
2360 the URL for the account matching the old key (i.e., the "kid"
2361 field in the outer JWS).
2362
2363 8. Check that the "oldKey" field of the keyChange object is the same
2364 as the account key for the account in question.
2365
2366 9. Check that no account exists whose account key is the same as the
2367 key in the "jwk" header parameter of the inner JWS.
2368
2369 If all of these checks pass, then the server updates the
2370 corresponding account by replacing the old account key with the new
2371 public key and returns status code 200 (OK). Otherwise, the server
2372 responds with an error status code and a problem document describing
2373 the error. If there is an existing account with the new key
2374 provided, then the server SHOULD use status code 409 (Conflict) and
2375 provide the URL of that account in the Location header field.
2376
2377 Note that changing the account key for an account SHOULD NOT have any
2378 other impact on the account. For example, the server MUST NOT
2379 invalidate pending orders or authorization transactions based on a
2380 change of account key.
2381
23827.3.6. Account Deactivation
2383
2384 A client can deactivate an account by posting a signed update to the
2385 account URL with a status field of "deactivated". Clients may wish
2386 to do this when the account key is compromised or decommissioned. A
2387 deactivated account can no longer request certificate issuance or
2388 access resources related to the account, such as orders or
2389 authorizations. If a server receives a POST or POST-as-GET from a
2390 deactivated account, it MUST return an error response with status
2391 code 401 (Unauthorized) and type
2392 "urn:ietf:params:acme:error:unauthorized".
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410Barnes, et al. Standards Track [Page 43]
2411
2412RFC 8555 ACME March 2019
2413
2414
2415 POST /acme/acct/evOfKhNU60wg HTTP/1.1
2416 Host: example.com
2417 Content-Type: application/jose+json
2418
2419 {
2420 "protected": base64url({
2421 "alg": "ES256",
2422 "kid": "https://example.com/acme/acct/evOfKhNU60wg",
2423 "nonce": "ntuJWWSic4WVNSqeUmshgg",
2424 "url": "https://example.com/acme/acct/evOfKhNU60wg"
2425 }),
2426 "payload": base64url({
2427 "status": "deactivated"
2428 }),
2429 "signature": "earzVLd3m5M4xJzR...bVTqn7R08AKOVf3Y"
2430 }
2431
2432 The server MUST verify that the request is signed by the account key.
2433 If the server accepts the deactivation request, it replies with a 200
2434 (OK) status code and the current contents of the account object.
2435
2436 Once an account is deactivated, the server MUST NOT accept further
2437 requests authorized by that account's key. The server SHOULD cancel
2438 any pending operations authorized by the account's key, such as
2439 certificate orders. A server may take a variety of actions in
2440 response to an account deactivation, e.g., deleting data related to
2441 that account or sending mail to the account's contacts. Servers
2442 SHOULD NOT revoke certificates issued by the deactivated account,
2443 since this could cause operational disruption for servers using these
2444 certificates. ACME does not provide a way to reactivate a
2445 deactivated account.
2446
24477.4. Applying for Certificate Issuance
2448
2449 The client begins the certificate issuance process by sending a POST
2450 request to the server's newOrder resource. The body of the POST is a
2451 JWS object whose JSON payload is a subset of the order object defined
2452 in Section 7.1.3, containing the fields that describe the certificate
2453 to be issued:
2454
2455 identifiers (required, array of object): An array of identifier
2456 objects that the client wishes to submit an order for.
2457
2458 type (required, string): The type of identifier.
2459
2460 value (required, string): The identifier itself.
2461
2462
2463
2464
2465
2466Barnes, et al. Standards Track [Page 44]
2467
2468RFC 8555 ACME March 2019
2469
2470
2471 notBefore (optional, string): The requested value of the notBefore
2472 field in the certificate, in the date format defined in [RFC3339].
2473
2474 notAfter (optional, string): The requested value of the notAfter
2475 field in the certificate, in the date format defined in [RFC3339].
2476
2477 POST /acme/new-order HTTP/1.1
2478 Host: example.com
2479 Content-Type: application/jose+json
2480
2481 {
2482 "protected": base64url({
2483 "alg": "ES256",
2484 "kid": "https://example.com/acme/acct/evOfKhNU60wg",
2485 "nonce": "5XJ1L3lEkMG7tR6pA00clA",
2486 "url": "https://example.com/acme/new-order"
2487 }),
2488 "payload": base64url({
2489 "identifiers": [
2490 { "type": "dns", "value": "www.example.org" },
2491 { "type": "dns", "value": "example.org" }
2492 ],
2493 "notBefore": "2016-01-01T00:04:00+04:00",
2494 "notAfter": "2016-01-08T00:04:00+04:00"
2495 }),
2496 "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g"
2497 }
2498
2499 The server MUST return an error if it cannot fulfill the request as
2500 specified, and it MUST NOT issue a certificate with contents other
2501 than those requested. If the server requires the request to be
2502 modified in a certain way, it should indicate the required changes
2503 using an appropriate error type and description.
2504
2505 If the server is willing to issue the requested certificate, it
2506 responds with a 201 (Created) response. The body of this response is
2507 an order object reflecting the client's request and any
2508 authorizations the client must complete before the certificate will
2509 be issued.
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522Barnes, et al. Standards Track [Page 45]
2523
2524RFC 8555 ACME March 2019
2525
2526
2527 HTTP/1.1 201 Created
2528 Replay-Nonce: MYAuvOpaoIiywTezizk5vw
2529 Link: <https://example.com/acme/directory>;rel="index"
2530 Location: https://example.com/acme/order/TOlocE8rfgo
2531
2532 {
2533 "status": "pending",
2534 "expires": "2016-01-05T14:09:07.99Z",
2535
2536 "notBefore": "2016-01-01T00:00:00Z",
2537 "notAfter": "2016-01-08T00:00:00Z",
2538
2539 "identifiers": [
2540 { "type": "dns", "value": "www.example.org" },
2541 { "type": "dns", "value": "example.org" }
2542 ],
2543
2544 "authorizations": [
2545 "https://example.com/acme/authz/PAniVnsZcis",
2546 "https://example.com/acme/authz/r4HqLzrSrpI"
2547 ],
2548
2549 "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize"
2550 }
2551
2552 The order object returned by the server represents a promise that if
2553 the client fulfills the server's requirements before the "expires"
2554 time, then the server will be willing to finalize the order upon
2555 request and issue the requested certificate. In the order object,
2556 any authorization referenced in the "authorizations" array whose
2557 status is "pending" represents an authorization transaction that the
2558 client must complete before the server will issue the certificate
2559 (see Section 7.5). If the client fails to complete the required
2560 actions before the "expires" time, then the server SHOULD change the
2561 status of the order to "invalid" and MAY delete the order resource.
2562 Clients MUST NOT make any assumptions about the sort order of
2563 "identifiers" or "authorizations" elements in the returned order
2564 object.
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578Barnes, et al. Standards Track [Page 46]
2579
2580RFC 8555 ACME March 2019
2581
2582
2583 Once the client believes it has fulfilled the server's requirements,
2584 it should send a POST request to the order resource's finalize URL.
2585 The POST body MUST include a CSR:
2586
2587 csr (required, string): A CSR encoding the parameters for the
2588 certificate being requested [RFC2986]. The CSR is sent in the
2589 base64url-encoded version of the DER format. (Note: Because this
2590 field uses base64url, and does not include headers, it is
2591 different from PEM.)
2592
2593 POST /acme/order/TOlocE8rfgo/finalize HTTP/1.1
2594 Host: example.com
2595 Content-Type: application/jose+json
2596
2597 {
2598 "protected": base64url({
2599 "alg": "ES256",
2600 "kid": "https://example.com/acme/acct/evOfKhNU60wg",
2601 "nonce": "MSF2j2nawWHPxxkE3ZJtKQ",
2602 "url": "https://example.com/acme/order/TOlocE8rfgo/finalize"
2603 }),
2604 "payload": base64url({
2605 "csr": "MIIBPTCBxAIBADBFMQ...FS6aKdZeGsysoCo4H9P",
2606 }),
2607 "signature": "uOrUfIIk5RyQ...nw62Ay1cl6AB"
2608 }
2609
2610 The CSR encodes the client's requests with regard to the content of
2611 the certificate to be issued. The CSR MUST indicate the exact same
2612 set of requested identifiers as the initial newOrder request.
2613 Identifiers of type "dns" MUST appear either in the commonName
2614 portion of the requested subject name or in an extensionRequest
2615 attribute [RFC2985] requesting a subjectAltName extension, or both.
2616 (These identifiers may appear in any sort order.) Specifications
2617 that define new identifier types must specify where in the
2618 certificate signing request these identifiers can appear.
2619
2620 A request to finalize an order will result in an error if the CA is
2621 unwilling to issue a certificate corresponding to the submitted CSR.
2622 For example:
2623
2624 o If the CSR and order identifiers differ
2625
2626 o If the account is not authorized for the identifiers indicated in
2627 the CSR
2628
2629 o If the CSR requests extensions that the CA is not willing to
2630 include
2631
2632
2633
2634Barnes, et al. Standards Track [Page 47]
2635
2636RFC 8555 ACME March 2019
2637
2638
2639 In such cases, the problem document returned by the server SHOULD use
2640 error code "badCSR" and describe specific reasons the CSR was
2641 rejected in its "detail" field. After returning such an error, the
2642 server SHOULD leave the order in the "ready" state, to allow the
2643 client to submit a new finalize request with an amended CSR.
2644
2645 A request to finalize an order will result in error if the order is
2646 not in the "ready" state. In such cases, the server MUST return a
2647 403 (Forbidden) error with a problem document of type
2648 "orderNotReady". The client should then send a POST-as-GET request
2649 to the order resource to obtain its current state. The status of the
2650 order will indicate what action the client should take (see below).
2651
2652 If a request to finalize an order is successful, the server will
2653 return a 200 (OK) with an updated order object. The status of the
2654 order will indicate what action the client should take:
2655
2656 o "invalid": The certificate will not be issued. Consider this
2657 order process abandoned.
2658
2659 o "pending": The server does not believe that the client has
2660 fulfilled the requirements. Check the "authorizations" array for
2661 entries that are still pending.
2662
2663 o "ready": The server agrees that the requirements have been
2664 fulfilled, and is awaiting finalization. Submit a finalization
2665 request.
2666
2667 o "processing": The certificate is being issued. Send a POST-as-GET
2668 request after the time given in the Retry-After header field of
2669 the response, if any.
2670
2671 o "valid": The server has issued the certificate and provisioned its
2672 URL to the "certificate" field of the order. Download the
2673 certificate.
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690Barnes, et al. Standards Track [Page 48]
2691
2692RFC 8555 ACME March 2019
2693
2694
2695 HTTP/1.1 200 OK
2696 Replay-Nonce: CGf81JWBsq8QyIgPCi9Q9X
2697 Link: <https://example.com/acme/directory>;rel="index"
2698 Location: https://example.com/acme/order/TOlocE8rfgo
2699
2700 {
2701 "status": "valid",
2702 "expires": "2016-01-20T14:09:07.99Z",
2703
2704 "notBefore": "2016-01-01T00:00:00Z",
2705 "notAfter": "2016-01-08T00:00:00Z",
2706
2707 "identifiers": [
2708 { "type": "dns", "value": "www.example.org" },
2709 { "type": "dns", "value": "example.org" }
2710 ],
2711
2712 "authorizations": [
2713 "https://example.com/acme/authz/PAniVnsZcis",
2714 "https://example.com/acme/authz/r4HqLzrSrpI"
2715 ],
2716
2717 "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize",
2718
2719 "certificate": "https://example.com/acme/cert/mAt3xBGaobw"
2720 }
2721
27227.4.1. Pre-authorization
2723
2724 The order process described above presumes that authorization objects
2725 are created reactively, in response to a certificate order. Some
2726 servers may also wish to enable clients to obtain authorization for
2727 an identifier proactively, outside of the context of a specific
2728 issuance. For example, a client hosting virtual servers for a
2729 collection of names might wish to obtain authorization before any
2730 virtual servers are created and only create a certificate when a
2731 virtual server starts up.
2732
2733 In some cases, a CA running an ACME server might have a completely
2734 external, non-ACME process for authorizing a client to issue
2735 certificates for an identifier. In these cases, the CA should
2736 provision its ACME server with authorization objects corresponding to
2737 these authorizations and reflect them as already valid in any orders
2738 submitted by the client.
2739
2740 If a CA wishes to allow pre-authorization within ACME, it can offer a
2741 "new authorization" resource in its directory by adding the field
2742 "newAuthz" with a URL for the newAuthz resource.
2743
2744
2745
2746Barnes, et al. Standards Track [Page 49]
2747
2748RFC 8555 ACME March 2019
2749
2750
2751 To request authorization for an identifier, the client sends a POST
2752 request to the newAuthz resource specifying the identifier for which
2753 authorization is being requested.
2754
2755 identifier (required, object): The identifier to appear in the
2756 resulting authorization object (see Section 7.1.4).
2757
2758 type (required, string): The type of identifier.
2759
2760 value (required, string): The identifier itself.
2761
2762 POST /acme/new-authz HTTP/1.1
2763 Host: example.com
2764 Content-Type: application/jose+json
2765
2766 {
2767 "protected": base64url({
2768 "alg": "ES256",
2769 "kid": "https://example.com/acme/acct/evOfKhNU60wg",
2770 "nonce": "uQpSjlRb4vQVCjVYAyyUWg",
2771 "url": "https://example.com/acme/new-authz"
2772 }),
2773 "payload": base64url({
2774 "identifier": {
2775 "type": "dns",
2776 "value": "example.org"
2777 }
2778 }),
2779 "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps"
2780 }
2781
2782 Note that because the identifier in a pre-authorization request is
2783 the exact identifier to be included in the authorization object, pre-
2784 authorization cannot be used to authorize issuance of certificates
2785 containing wildcard domain names.
2786
2787 Before processing the authorization request, the server SHOULD
2788 determine whether it is willing to issue certificates for the
2789 identifier. For example, the server should check that the identifier
2790 is of a supported type. Servers might also check names against a
2791 blacklist of known high-value identifiers. If the server is
2792 unwilling to issue for the identifier, it SHOULD return an error with
2793 status code 403 (Forbidden), with a problem document describing the
2794 reason for the rejection.
2795
2796
2797
2798
2799
2800
2801
2802Barnes, et al. Standards Track [Page 50]
2803
2804RFC 8555 ACME March 2019
2805
2806
2807 If the server is willing to proceed, it builds a pending
2808 authorization object from the inputs submitted by the client:
2809
2810 o "identifier" the identifier submitted by the client
2811
2812 o "status" MUST be "pending" unless the server has out-of-band
2813 information about the client's authorization status
2814
2815 o "challenges" as selected by the server's policy for this
2816 identifier
2817
2818 The server allocates a new URL for this authorization and returns a
2819 201 (Created) response with the authorization URL in the Location
2820 header field and the JSON authorization object in the body. The
2821 client then follows the process described in Section 7.5 to complete
2822 the authorization process.
2823
28247.4.2. Downloading the Certificate
2825
2826 To download the issued certificate, the client simply sends a POST-
2827 as-GET request to the certificate URL.
2828
2829 The default format of the certificate is application/pem-certificate-
2830 chain (see Section 9).
2831
2832 The server MAY provide one or more link relation header fields
2833 [RFC8288] with relation "alternate". Each such field SHOULD express
2834 an alternative certificate chain starting with the same end-entity
2835 certificate. This can be used to express paths to various trust
2836 anchors. Clients can fetch these alternates and use their own
2837 heuristics to decide which is optimal.
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858Barnes, et al. Standards Track [Page 51]
2859
2860RFC 8555 ACME March 2019
2861
2862
2863 POST /acme/cert/mAt3xBGaobw HTTP/1.1
2864 Host: example.com
2865 Content-Type: application/jose+json
2866 Accept: application/pem-certificate-chain
2867
2868 {
2869 "protected": base64url({
2870 "alg": "ES256",
2871 "kid": "https://example.com/acme/acct/evOfKhNU60wg",
2872 "nonce": "uQpSjlRb4vQVCjVYAyyUWg",
2873 "url": "https://example.com/acme/cert/mAt3xBGaobw"
2874 }),
2875 "payload": "",
2876 "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps"
2877 }
2878
2879 HTTP/1.1 200 OK
2880 Content-Type: application/pem-certificate-chain
2881 Link: <https://example.com/acme/directory>;rel="index"
2882
2883 -----BEGIN CERTIFICATE-----
2884 [End-entity certificate contents]
2885 -----END CERTIFICATE-----
2886 -----BEGIN CERTIFICATE-----
2887 [Issuer certificate contents]
2888 -----END CERTIFICATE-----
2889 -----BEGIN CERTIFICATE-----
2890 [Other certificate contents]
2891 -----END CERTIFICATE-----
2892
2893 A certificate resource represents a single, immutable certificate.
2894 If the client wishes to obtain a renewed certificate, the client
2895 initiates a new order process to request one.
2896
2897 Because certificate resources are immutable once issuance is
2898 complete, the server MAY enable the caching of the resource by adding
2899 Expires and Cache-Control header fields specifying a point in time in
2900 the distant future. These header fields have no relation to the
2901 certificate's period of validity.
2902
2903 The ACME client MAY request other formats by including an Accept
2904 header field [RFC7231] in its request. For example, the client could
2905 use the media type "application/pkix-cert" [RFC2585] or "application/
2906 pkcs7-mime" [RFC5751] to request the end-entity certificate in DER
2907 format. Server support for alternate formats is OPTIONAL. For
2908 formats that can only express a single certificate, the server SHOULD
2909
2910
2911
2912
2913
2914Barnes, et al. Standards Track [Page 52]
2915
2916RFC 8555 ACME March 2019
2917
2918
2919 provide one or more "Link: rel="up"" header fields pointing to an
2920 issuer or issuers so that ACME clients can build a certificate chain
2921 as defined in TLS (see Section 4.4.2 of [RFC8446]).
2922
29237.5. Identifier Authorization
2924
2925 The identifier authorization process establishes the authorization of
2926 an account to manage certificates for a given identifier. This
2927 process assures the server of two things:
2928
2929 1. That the client controls the private key of the account key pair,
2930 and
2931
2932 2. That the client controls the identifier in question.
2933
2934 This process may be repeated to associate multiple identifiers with
2935 an account (e.g., to request certificates with multiple identifiers)
2936 or to associate multiple accounts with an identifier (e.g., to allow
2937 multiple entities to manage certificates).
2938
2939 Authorization resources are created by the server in response to
2940 newOrder or newAuthz requests submitted by an account key holder;
2941 their URLs are provided to the client in the responses to these
2942 requests. The authorization object is implicitly tied to the account
2943 key used to sign the request.
2944
2945 When a client receives an order from the server in reply to a
2946 newOrder request, it downloads the authorization resources by sending
2947 POST-as-GET requests to the indicated URLs. If the client initiates
2948 authorization using a request to the newAuthz resource, it will have
2949 already received the pending authorization object in the response to
2950 that request.
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970Barnes, et al. Standards Track [Page 53]
2971
2972RFC 8555 ACME March 2019
2973
2974
2975 POST /acme/authz/PAniVnsZcis HTTP/1.1
2976 Host: example.com
2977 Content-Type: application/jose+json
2978
2979 {
2980 "protected": base64url({
2981 "alg": "ES256",
2982 "kid": "https://example.com/acme/acct/evOfKhNU60wg",
2983 "nonce": "uQpSjlRb4vQVCjVYAyyUWg",
2984 "url": "https://example.com/acme/authz/PAniVnsZcis"
2985 }),
2986 "payload": "",
2987 "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps"
2988 }
2989
2990 HTTP/1.1 200 OK
2991 Content-Type: application/json
2992 Link: <https://example.com/acme/directory>;rel="index"
2993
2994 {
2995 "status": "pending",
2996 "expires": "2016-01-02T14:09:30Z",
2997
2998 "identifier": {
2999 "type": "dns",
3000 "value": "www.example.org"
3001 },
3002
3003 "challenges": [
3004 {
3005 "type": "http-01",
3006 "url": "https://example.com/acme/chall/prV_B7yEyA4",
3007 "token": "DGyRejmCefe7v4NfDGDKfA"
3008 },
3009 {
3010 "type": "dns-01",
3011 "url": "https://example.com/acme/chall/Rg5dV14Gh1Q",
3012 "token": "DGyRejmCefe7v4NfDGDKfA"
3013 }
3014 ]
3015 }
3016
30177.5.1. Responding to Challenges
3018
3019 To prove control of the identifier and receive authorization, the
3020 client needs to provision the required challenge response based on
3021 the challenge type and indicate to the server that it is ready for
3022 the challenge validation to be attempted.
3023
3024
3025
3026Barnes, et al. Standards Track [Page 54]
3027
3028RFC 8555 ACME March 2019
3029
3030
3031 The client indicates to the server that it is ready for the challenge
3032 validation by sending an empty JSON body ("{}") carried in a POST
3033 request to the challenge URL (not the authorization URL).
3034
3035 For example, if the client were to respond to the "http-01" challenge
3036 in the above authorization, it would send the following request:
3037
3038 POST /acme/chall/prV_B7yEyA4 HTTP/1.1
3039 Host: example.com
3040 Content-Type: application/jose+json
3041
3042 {
3043 "protected": base64url({
3044 "alg": "ES256",
3045 "kid": "https://example.com/acme/acct/evOfKhNU60wg",
3046 "nonce": "Q_s3MWoqT05TrdkM2MTDcw",
3047 "url": "https://example.com/acme/chall/prV_B7yEyA4"
3048 }),
3049 "payload": base64url({}),
3050 "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ"
3051 }
3052
3053 The server updates the authorization document by updating its
3054 representation of the challenge with the response object provided by
3055 the client. The server MUST ignore any fields in the response object
3056 that are not specified as response fields for this type of challenge.
3057 Note that the challenges in this document do not define any response
3058 fields, but future specifications might define them. The server
3059 provides a 200 (OK) response with the updated challenge object as its
3060 body.
3061
3062 If the client's response is invalid for any reason or does not
3063 provide the server with appropriate information to validate the
3064 challenge, then the server MUST return an HTTP error. On receiving
3065 such an error, the client SHOULD undo any actions that have been
3066 taken to fulfill the challenge, e.g., removing files that have been
3067 provisioned to a web server.
3068
3069 The server is said to "finalize" the authorization when it has
3070 completed one of the validations. This is done by assigning the
3071 authorization a status of "valid" or "invalid", corresponding to
3072 whether it considers the account authorized for the identifier. If
3073 the final state is "valid", then the server MUST include an "expires"
3074 field. When finalizing an authorization, the server MAY remove
3075 challenges other than the one that was completed, and it may modify
3076 the "expires" field. The server SHOULD NOT remove challenges with
3077 status "invalid".
3078
3079
3080
3081
3082Barnes, et al. Standards Track [Page 55]
3083
3084RFC 8555 ACME March 2019
3085
3086
3087 Usually, the validation process will take some time, so the client
3088 will need to poll the authorization resource to see when it is
3089 finalized. For challenges where the client can tell when the server
3090 has validated the challenge (e.g., by seeing an HTTP or DNS request
3091 from the server), the client SHOULD NOT begin polling until it has
3092 seen the validation request from the server.
3093
3094 To check on the status of an authorization, the client sends a POST-
3095 as-GET request to the authorization URL, and the server responds with
3096 the current authorization object. In responding to poll requests
3097 while the validation is still in progress, the server MUST return a
3098 200 (OK) response and MAY include a Retry-After header field to
3099 suggest a polling interval to the client.
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138Barnes, et al. Standards Track [Page 56]
3139
3140RFC 8555 ACME March 2019
3141
3142
3143 POST /acme/authz/PAniVnsZcis HTTP/1.1
3144 Host: example.com
3145 Content-Type: application/jose+json
3146
3147 {
3148 "protected": base64url({
3149 "alg": "ES256",
3150 "kid": "https://example.com/acme/acct/evOfKhNU60wg",
3151 "nonce": "uQpSjlRb4vQVCjVYAyyUWg",
3152 "url": "https://example.com/acme/authz/PAniVnsZcis"
3153 }),
3154 "payload": "",
3155 "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps"
3156 }
3157
3158 HTTP/1.1 200 OK
3159 Content-Type: application/json
3160 Link: <https://example.com/acme/directory>;rel="index"
3161
3162 {
3163 "status": "valid",
3164 "expires": "2018-09-09T14:09:01.13Z",
3165
3166 "identifier": {
3167 "type": "dns",
3168 "value": "www.example.org"
3169 },
3170
3171 "challenges": [
3172 {
3173 "type": "http-01",
3174 "url": "https://example.com/acme/chall/prV_B7yEyA4",
3175 "status": "valid",
3176 "validated": "2014-12-01T12:05:13.72Z",
3177 "token": "IlirfxKKXAsHtmzK29Pj8A"
3178 }
3179 ]
3180 }
3181
31827.5.2. Deactivating an Authorization
3183
3184 If a client wishes to relinquish its authorization to issue
3185 certificates for an identifier, then it may request that the server
3186 deactivate each authorization associated with it by sending POST
3187 requests with the static object {"status": "deactivated"} to each
3188 authorization URL.
3189
3190
3191
3192
3193
3194Barnes, et al. Standards Track [Page 57]
3195
3196RFC 8555 ACME March 2019
3197
3198
3199 POST /acme/authz/PAniVnsZcis HTTP/1.1
3200 Host: example.com
3201 Content-Type: application/jose+json
3202
3203 {
3204 "protected": base64url({
3205 "alg": "ES256",
3206 "kid": "https://example.com/acme/acct/evOfKhNU60wg",
3207 "nonce": "xWCM9lGbIyCgue8di6ueWQ",
3208 "url": "https://example.com/acme/authz/PAniVnsZcis"
3209 }),
3210 "payload": base64url({
3211 "status": "deactivated"
3212 }),
3213 "signature": "srX9Ji7Le9bjszhu...WTFdtujObzMtZcx4"
3214 }
3215
3216 The server MUST verify that the request is signed by the account key
3217 corresponding to the account that owns the authorization. If the
3218 server accepts the deactivation, it should reply with a 200 (OK)
3219 status code and the updated contents of the authorization object.
3220
3221 The server MUST NOT treat deactivated authorization objects as
3222 sufficient for issuing certificates.
3223
32247.6. Certificate Revocation
3225
3226 To request that a certificate be revoked, the client sends a POST
3227 request to the ACME server's revokeCert URL. The body of the POST is
3228 a JWS object whose JSON payload contains the certificate to be
3229 revoked:
3230
3231 certificate (required, string): The certificate to be revoked, in
3232 the base64url-encoded version of the DER format. (Note: Because
3233 this field uses base64url, and does not include headers, it is
3234 different from PEM.)
3235
3236 reason (optional, int): One of the revocation reasonCodes defined in
3237 Section 5.3.1 of [RFC5280] to be used when generating OCSP
3238 responses and CRLs. If this field is not set, the server SHOULD
3239 omit the reasonCode CRL entry extension when generating OCSP
3240 responses and CRLs. The server MAY disallow a subset of
3241 reasonCodes from being used by the user. If a request contains a
3242 disallowed reasonCode, then the server MUST reject it with the
3243 error type "urn:ietf:params:acme:error:badRevocationReason". The
3244 problem document detail SHOULD indicate which reasonCodes are
3245 allowed.
3246
3247
3248
3249
3250Barnes, et al. Standards Track [Page 58]
3251
3252RFC 8555 ACME March 2019
3253
3254
3255 Revocation requests are different from other ACME requests in that
3256 they can be signed with either an account key pair or the key pair in
3257 the certificate.
3258
3259 Example using an account key pair for the signature:
3260
3261 POST /acme/revoke-cert HTTP/1.1
3262 Host: example.com
3263 Content-Type: application/jose+json
3264
3265 {
3266 "protected": base64url({
3267 "alg": "ES256",
3268 "kid": "https://example.com/acme/acct/evOfKhNU60wg",
3269 "nonce": "JHb54aT_KTXBWQOzGYkt9A",
3270 "url": "https://example.com/acme/revoke-cert"
3271 }),
3272 "payload": base64url({
3273 "certificate": "MIIEDTCCAvegAwIBAgIRAP8...",
3274 "reason": 4
3275 }),
3276 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4"
3277 }
3278
3279 Example using the certificate key pair for the signature:
3280
3281 POST /acme/revoke-cert HTTP/1.1
3282 Host: example.com
3283 Content-Type: application/jose+json
3284
3285 {
3286 "protected": base64url({
3287 "alg": "RS256",
3288 "jwk": /* certificate's public key */,
3289 "nonce": "JHb54aT_KTXBWQOzGYkt9A",
3290 "url": "https://example.com/acme/revoke-cert"
3291 }),
3292 "payload": base64url({
3293 "certificate": "MIIEDTCCAvegAwIBAgIRAP8...",
3294 "reason": 1
3295 }),
3296 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4"
3297 }
3298
3299
3300
3301
3302
3303
3304
3305
3306Barnes, et al. Standards Track [Page 59]
3307
3308RFC 8555 ACME March 2019
3309
3310
3311 Before revoking a certificate, the server MUST verify that the key
3312 used to sign the request is authorized to revoke the certificate.
3313 The server MUST consider at least the following accounts authorized
3314 for a given certificate:
3315
3316 o the account that issued the certificate.
3317
3318 o an account that holds authorizations for all of the identifiers in
3319 the certificate.
3320
3321 The server MUST also consider a revocation request valid if it is
3322 signed with the private key corresponding to the public key in the
3323 certificate.
3324
3325 If the revocation succeeds, the server responds with status code 200
3326 (OK). If the revocation fails, the server returns an error. For
3327 example, if the certificate has already been revoked, the server
3328 returns an error response with status code 400 (Bad Request) and type
3329 "urn:ietf:params:acme:error:alreadyRevoked".
3330
3331 HTTP/1.1 200 OK
3332 Replay-Nonce: IXVHDyxIRGcTE0VSblhPzw
3333 Content-Length: 0
3334 Link: <https://example.com/acme/directory>;rel="index"
3335
3336 --- or ---
3337
3338 HTTP/1.1 403 Forbidden
3339 Replay-Nonce: lXfyFzi6238tfPQRwgfmPU
3340 Content-Type: application/problem+json
3341 Content-Language: en
3342 Link: <https://example.com/acme/directory>;rel="index"
3343
3344 {
3345 "type": "urn:ietf:params:acme:error:unauthorized",
3346 "detail": "No authorization provided for name example.org"
3347 }
3348
33498. Identifier Validation Challenges
3350
3351 There are few types of identifiers in the world for which there is a
3352 standardized mechanism to prove possession of a given identifier. In
3353 all practical cases, CAs rely on a variety of means to test whether
3354 an entity applying for a certificate with a given identifier actually
3355 controls that identifier.
3356
3357
3358
3359
3360
3361
3362Barnes, et al. Standards Track [Page 60]
3363
3364RFC 8555 ACME March 2019
3365
3366
3367 Challenges provide the server with assurance that an account holder
3368 is also the entity that controls an identifier. For each type of
3369 challenge, it must be the case that, in order for an entity to
3370 successfully complete the challenge, the entity must both:
3371
3372 o Hold the private key of the account key pair used to respond to
3373 the challenge, and
3374
3375 o Control the identifier in question.
3376
3377 Section 10 documents how the challenges defined in this document meet
3378 these requirements. New challenges will need to document how they
3379 do.
3380
3381 ACME uses an extensible challenge/response framework for identifier
3382 validation. The server presents a set of challenges in the
3383 authorization object it sends to a client (as objects in the
3384 "challenges" array), and the client responds by sending a response
3385 object in a POST request to a challenge URL.
3386
3387 This section describes an initial set of challenge types. The
3388 definition of a challenge type includes:
3389
3390 1. Content of challenge objects
3391
3392 2. Content of response objects
3393
3394 3. How the server uses the challenge and response to verify control
3395 of an identifier
3396
3397 Challenge objects all contain the following basic fields:
3398
3399 type (required, string): The type of challenge encoded in the
3400 object.
3401
3402 url (required, string): The URL to which a response can be posted.
3403
3404 status (required, string): The status of this challenge. Possible
3405 values are "pending", "processing", "valid", and "invalid" (see
3406 Section 7.1.6).
3407
3408 validated (optional, string): The time at which the server validated
3409 this challenge, encoded in the format specified in [RFC3339].
3410 This field is REQUIRED if the "status" field is "valid".
3411
3412
3413
3414
3415
3416
3417
3418Barnes, et al. Standards Track [Page 61]
3419
3420RFC 8555 ACME March 2019
3421
3422
3423 error (optional, object): Error that occurred while the server was
3424 validating the challenge, if any, structured as a problem document
3425 [RFC7807]. Multiple errors can be indicated by using subproblems
3426 Section 6.7.1. A challenge object with an error MUST have status
3427 equal to "invalid".
3428
3429 All additional fields are specified by the challenge type. If the
3430 server sets a challenge's "status" to "invalid", it SHOULD also
3431 include the "error" field to help the client diagnose why the
3432 challenge failed.
3433
3434 Different challenges allow the server to obtain proof of different
3435 aspects of control over an identifier. In some challenges, like HTTP
3436 and DNS, the client directly proves its ability to do certain things
3437 related to the identifier. The choice of which challenges to offer
3438 to a client under which circumstances is a matter of server policy.
3439
3440 The identifier validation challenges described in this section all
3441 relate to validation of domain names. If ACME is extended in the
3442 future to support other types of identifiers, there will need to be
3443 new challenge types, and they will need to specify which types of
3444 identifier they apply to.
3445
34468.1. Key Authorizations
3447
3448 All challenges defined in this document make use of a key
3449 authorization string. A key authorization is a string that
3450 concatenates the token for the challenge with a key fingerprint,
3451 separated by a "." character:
3452
3453 keyAuthorization = token || '.' || base64url(Thumbprint(accountKey))
3454
3455 The "Thumbprint" step indicates the computation specified in
3456 [RFC7638], using the SHA-256 digest [FIPS180-4]. As noted in
3457 [RFC7518] any prepended zero octets in the fields of a JWK object
3458 MUST be stripped before doing the computation.
3459
3460 As specified in the individual challenges below, the token for a
3461 challenge is a string comprised entirely of characters in the URL-
3462 safe base64 alphabet. The "||" operator indicates concatenation of
3463 strings.
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474Barnes, et al. Standards Track [Page 62]
3475
3476RFC 8555 ACME March 2019
3477
3478
34798.2. Retrying Challenges
3480
3481 ACME challenges typically require the client to set up some network-
3482 accessible resource that the server can query in order to validate
3483 that the client controls an identifier. In practice, it is not
3484 uncommon for the server's queries to fail while a resource is being
3485 set up, e.g., due to information propagating across a cluster or
3486 firewall rules not being in place.
3487
3488 Clients SHOULD NOT respond to challenges until they believe that the
3489 server's queries will succeed. If a server's initial validation
3490 query fails, the server SHOULD retry the query after some time, in
3491 order to account for delay in setting up responses such as DNS
3492 records or HTTP resources. The precise retry schedule is up to the
3493 server, but server operators should keep in mind the operational
3494 scenarios that the schedule is trying to accommodate. Given that
3495 retries are intended to address things like propagation delays in
3496 HTTP or DNS provisioning, there should not usually be any reason to
3497 retry more often than every 5 or 10 seconds. While the server is
3498 still trying, the status of the challenge remains "processing"; it is
3499 only marked "invalid" once the server has given up.
3500
3501 The server MUST provide information about its retry state to the
3502 client via the "error" field in the challenge and the Retry-After
3503 HTTP header field in response to requests to the challenge resource.
3504 The server MUST add an entry to the "error" field in the challenge
3505 after each failed validation query. The server SHOULD set the Retry-
3506 After header field to a time after the server's next validation
3507 query, since the status of the challenge will not change until that
3508 time.
3509
3510 Clients can explicitly request a retry by re-sending their response
3511 to a challenge in a new POST request (with a new nonce, etc.). This
3512 allows clients to request a retry when the state has changed (e.g.,
3513 after firewall rules have been updated). Servers SHOULD retry a
3514 request immediately on receiving such a POST request. In order to
3515 avoid denial-of-service attacks via client-initiated retries, servers
3516 SHOULD rate-limit such requests.
3517
35188.3. HTTP Challenge
3519
3520 With HTTP validation, the client in an ACME transaction proves its
3521 control over a domain name by proving that it can provision HTTP
3522 resources on a server accessible under that domain name. The ACME
3523 server challenges the client to provision a file at a specific path,
3524 with a specific string as its content.
3525
3526
3527
3528
3529
3530Barnes, et al. Standards Track [Page 63]
3531
3532RFC 8555 ACME March 2019
3533
3534
3535 As a domain may resolve to multiple IPv4 and IPv6 addresses, the
3536 server will connect to at least one of the hosts found in the DNS A
3537 and AAAA records, at its discretion. Because many web servers
3538 allocate a default HTTPS virtual host to a particular low-privilege
3539 tenant user in a subtle and non-intuitive manner, the challenge must
3540 be completed over HTTP, not HTTPS.
3541
3542 type (required, string): The string "http-01".
3543
3544 token (required, string): A random value that uniquely identifies
3545 the challenge. This value MUST have at least 128 bits of entropy.
3546 It MUST NOT contain any characters outside the base64url alphabet
3547 and MUST NOT include base64 padding characters ("="). See
3548 [RFC4086] for additional information on randomness requirements.
3549
3550 {
3551 "type": "http-01",
3552 "url": "https://example.com/acme/chall/prV_B7yEyA4",
3553 "status": "pending",
3554 "token": "LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0"
3555 }
3556
3557 A client fulfills this challenge by constructing a key authorization
3558 from the "token" value provided in the challenge and the client's
3559 account key. The client then provisions the key authorization as a
3560 resource on the HTTP server for the domain in question.
3561
3562 The path at which the resource is provisioned is comprised of the
3563 fixed prefix "/.well-known/acme-challenge/", followed by the "token"
3564 value in the challenge. The value of the resource MUST be the ASCII
3565 representation of the key authorization.
3566
3567 GET /.well-known/acme-challenge/LoqXcYV8...jxAjEuX0
3568 Host: example.org
3569
3570 HTTP/1.1 200 OK
3571 Content-Type: application/octet-stream
3572
3573 LoqXcYV8...jxAjEuX0.9jg46WB3...fm21mqTI
3574
3575 (In the above, "..." indicates that the token and the JWK thumbprint
3576 in the key authorization have been truncated to fit on the page.)
3577
3578 A client responds with an empty object ({}) to acknowledge that the
3579 challenge can be validated by the server.
3580
3581
3582
3583
3584
3585
3586Barnes, et al. Standards Track [Page 64]
3587
3588RFC 8555 ACME March 2019
3589
3590
3591 POST /acme/chall/prV_B7yEyA4
3592 Host: example.com
3593 Content-Type: application/jose+json
3594
3595 {
3596 "protected": base64url({
3597 "alg": "ES256",
3598 "kid": "https://example.com/acme/acct/evOfKhNU60wg",
3599 "nonce": "UQI1PoRi5OuXzxuX7V7wL0",
3600 "url": "https://example.com/acme/chall/prV_B7yEyA4"
3601 }),
3602 "payload": base64url({}),
3603 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4"
3604 }
3605
3606 On receiving a response, the server constructs and stores the key
3607 authorization from the challenge "token" value and the current client
3608 account key.
3609
3610 Given a challenge/response pair, the server verifies the client's
3611 control of the domain by verifying that the resource was provisioned
3612 as expected.
3613
3614 1. Construct a URL by populating the URL template [RFC6570]
3615 "http://{domain}/.well-known/acme-challenge/{token}", where:
3616
3617 * the domain field is set to the domain name being verified; and
3618
3619 * the token field is set to the token in the challenge.
3620
3621 2. Verify that the resulting URL is well-formed.
3622
3623 3. Dereference the URL using an HTTP GET request. This request MUST
3624 be sent to TCP port 80 on the HTTP server.
3625
3626 4. Verify that the body of the response is a well-formed key
3627 authorization. The server SHOULD ignore whitespace characters at
3628 the end of the body.
3629
3630 5. Verify that key authorization provided by the HTTP server matches
3631 the key authorization stored by the server.
3632
3633 The server SHOULD follow redirects when dereferencing the URL.
3634 Clients might use redirects, for example, so that the response can be
3635 provided by a centralized certificate management server. See
3636 Section 10.2 for security considerations related to redirects.
3637
3638
3639
3640
3641
3642Barnes, et al. Standards Track [Page 65]
3643
3644RFC 8555 ACME March 2019
3645
3646
3647 If all of the above verifications succeed, then the validation is
3648 successful. If the request fails, or the body does not pass these
3649 checks, then it has failed.
3650
3651 The client SHOULD de-provision the resource provisioned for this
3652 challenge once the challenge is complete, i.e., once the "status"
3653 field of the challenge has the value "valid" or "invalid".
3654
3655 Note that because the token appears both in the request sent by the
3656 ACME server and in the key authorization in the response, it is
3657 possible to build clients that copy the token from request to
3658 response. Clients should avoid this behavior because it can lead to
3659 cross-site scripting vulnerabilities; instead, clients should be
3660 explicitly configured on a per-challenge basis. A client that does
3661 copy tokens from requests to responses MUST validate that the token
3662 in the request matches the token syntax above (e.g., that it includes
3663 only characters from the base64url alphabet).
3664
36658.4. DNS Challenge
3666
3667 When the identifier being validated is a domain name, the client can
3668 prove control of that domain by provisioning a TXT resource record
3669 containing a designated value for a specific validation domain name.
3670
3671 type (required, string): The string "dns-01".
3672
3673 token (required, string): A random value that uniquely identifies
3674 the challenge. This value MUST have at least 128 bits of entropy.
3675 It MUST NOT contain any characters outside the base64url alphabet,
3676 including padding characters ("="). See [RFC4086] for additional
3677 information on randomness requirements.
3678
3679 {
3680 "type": "dns-01",
3681 "url": "https://example.com/acme/chall/Rg5dV14Gh1Q",
3682 "status": "pending",
3683 "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA"
3684 }
3685
3686 A client fulfills this challenge by constructing a key authorization
3687 from the "token" value provided in the challenge and the client's
3688 account key. The client then computes the SHA-256 digest [FIPS180-4]
3689 of the key authorization.
3690
3691 The record provisioned to the DNS contains the base64url encoding of
3692 this digest. The client constructs the validation domain name by
3693 prepending the label "_acme-challenge" to the domain name being
3694 validated, then provisions a TXT record with the digest value under
3695
3696
3697
3698Barnes, et al. Standards Track [Page 66]
3699
3700RFC 8555 ACME March 2019
3701
3702
3703 that name. For example, if the domain name being validated is
3704 "www.example.org", then the client would provision the following DNS
3705 record:
3706
3707 _acme-challenge.www.example.org. 300 IN TXT "gfj9Xq...Rg85nM"
3708
3709 A client responds with an empty object ({}) to acknowledge that the
3710 challenge can be validated by the server.
3711
3712 POST /acme/chall/Rg5dV14Gh1Q
3713 Host: example.com
3714 Content-Type: application/jose+json
3715
3716 {
3717 "protected": base64url({
3718 "alg": "ES256",
3719 "kid": "https://example.com/acme/acct/evOfKhNU60wg",
3720 "nonce": "SS2sSl1PtspvFZ08kNtzKd",
3721 "url": "https://example.com/acme/chall/Rg5dV14Gh1Q"
3722 }),
3723 "payload": base64url({}),
3724 "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4"
3725 }
3726
3727 On receiving a response, the server constructs and stores the key
3728 authorization from the challenge "token" value and the current client
3729 account key.
3730
3731 To validate a DNS challenge, the server performs the following steps:
3732
3733 1. Compute the SHA-256 digest [FIPS180-4] of the stored key
3734 authorization
3735
3736 2. Query for TXT records for the validation domain name
3737
3738 3. Verify that the contents of one of the TXT records match the
3739 digest value
3740
3741 If all of the above verifications succeed, then the validation is
3742 successful. If no DNS record is found, or DNS record and response
3743 payload do not pass these checks, then the validation fails.
3744
3745 The client SHOULD de-provision the resource record(s) provisioned for
3746 this challenge once the challenge is complete, i.e., once the
3747 "status" field of the challenge has the value "valid" or "invalid".
3748
3749
3750
3751
3752
3753
3754Barnes, et al. Standards Track [Page 67]
3755
3756RFC 8555 ACME March 2019
3757
3758
37599. IANA Considerations
3760
37619.1. Media Type: application/pem-certificate-chain
3762
3763 A file of this type contains one or more certificates encoded with
3764 the PEM textual encoding, according to [RFC7468]. The textual
3765 encoding of certificates in this file MUST use the strict encoding
3766 and MUST NOT include explanatory text. The ABNF for this format is
3767 as follows, where "stricttextualmsg" and "eol" are as defined in
3768 Section 3 of RFC 7468:
3769
3770 certchain = stricttextualmsg *(eol stricttextualmsg)
3771
3772 In order to provide easy interoperation with TLS, the first
3773 certificate MUST be an end-entity certificate. Each following
3774 certificate SHOULD directly certify the one preceding it. Because
3775 certificate validation requires that trust anchors be distributed
3776 independently, a certificate that represents a trust anchor MAY be
3777 omitted from the chain, provided that supported peers are known to
3778 possess any omitted certificates.
3779
3780 The following has been registered in the "Media Types" registry:
3781 Type name: application
3782
3783 Subtype name: pem-certificate-chain
3784
3785 Required parameters: None
3786
3787 Optional parameters: None
3788
3789 Encoding considerations: 7bit
3790
3791 Security considerations: Carries a cryptographic certificate and its
3792 associated certificate chain. This media type carries no active
3793 content.
3794
3795 Interoperability considerations: None
3796
3797 Published specification: RFC 8555
3798
3799 Applications that use this media type: ACME clients and servers, HTTP
3800 servers, other applications that need to be configured with a
3801 certificate chain
3802
3803 Additional information:
3804
3805 Deprecated alias names for this type: n/a
3806 Magic number(s): n/a
3807
3808
3809
3810Barnes, et al. Standards Track [Page 68]
3811
3812RFC 8555 ACME March 2019
3813
3814
3815 File extension(s): .pem
3816 Macintosh file type code(s): n/a
3817
3818 Person & email address to contact for further information: See
3819 Authors' Addresses section.
3820
3821 Intended usage: COMMON
3822
3823 Restrictions on usage: n/a
3824
3825 Author: See Authors' Addresses section.
3826
3827 Change controller: IETF <iesg@ietf.org>
3828
38299.2. Well-Known URI for the HTTP Challenge
3830
3831 The following value has been registered in the "Well-Known URIs"
3832 registry (using the template from [RFC5785]):
3833
3834 URI suffix: acme-challenge
3835
3836 Change controller: IETF
3837
3838 Specification document(s): RFC 8555, Section 8.3
3839
3840 Related information: N/A
3841
38429.3. Replay-Nonce HTTP Header
3843
3844 The following value has been registered in the "Message Headers"
3845 registry:
3846
3847 +-------------------+----------+----------+-------------------------+
3848 | Header Field Name | Protocol | Status | Reference |
3849 +-------------------+----------+----------+-------------------------+
3850 | Replay-Nonce | http | standard | RFC 8555, Section 6.5.1 |
3851 +-------------------+----------+----------+-------------------------+
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866Barnes, et al. Standards Track [Page 69]
3867
3868RFC 8555 ACME March 2019
3869
3870
38719.4. "url" JWS Header Parameter
3872
3873 The following value has been registered in the "JSON Web Signature
3874 and Encryption Header Parameters" registry:
3875
3876 o Header Parameter Name: "url"
3877
3878 o Header Parameter Description: URL
3879
3880 o Header Parameter Usage Location(s): JWE, JWS
3881
3882 o Change Controller: IESG
3883
3884 o Specification Document(s): RFC 8555, Section 6.4.1
3885
38869.5. "nonce" JWS Header Parameter
3887
3888 The following value has been registered in the "JSON Web Signature
3889 and Encryption Header Parameters" registry:
3890
3891 o Header Parameter Name: "nonce"
3892
3893 o Header Parameter Description: Nonce
3894
3895 o Header Parameter Usage Location(s): JWE, JWS
3896
3897 o Change Controller: IESG
3898
3899 o Specification Document(s): RFC 8555, Section 6.5.2
3900
39019.6. URN Sub-namespace for ACME (urn:ietf:params:acme)
3902
3903 The following value has been registered in the "IETF URN Sub-
3904 namespace for Registered Protocol Parameter Identifiers" registry,
3905 following the template in [RFC3553]:
3906
3907 Registry name: acme
3908
3909 Specification: RFC 8555
3910
3911 Repository: http://www.iana.org/assignments/acme
3912
3913 Index value: No transformation needed.
3914
3915
3916
3917
3918
3919
3920
3921
3922Barnes, et al. Standards Track [Page 70]
3923
3924RFC 8555 ACME March 2019
3925
3926
39279.7. New Registries
3928
3929 IANA has created the following registries:
3930
3931 1. ACME Account Object Fields (Section 9.7.1)
3932
3933 2. ACME Order Object Fields (Section 9.7.2)
3934
3935 3. ACME Authorization Object Fields (Section 9.7.3)
3936
3937 4. ACME Error Types (Section 9.7.4)
3938
3939 5. ACME Resource Types (Section 9.7.5)
3940
3941 6. ACME Directory Metadata Fields (Section 9.7.6)
3942
3943 7. ACME Identifier Types (Section 9.7.7)
3944
3945 8. ACME Validation Methods (Section 9.7.8)
3946
3947 All of these registries are under a heading of "Automated Certificate
3948 Management Environment (ACME) Protocol" and are administered under a
3949 Specification Required policy [RFC8126].
3950
39519.7.1. Fields in Account Objects
3952
3953 The "ACME Account Object Fields" registry lists field names that are
3954 defined for use in ACME account objects. Fields marked as
3955 "configurable" may be included in a newAccount request.
3956
3957 Template:
3958
3959 o Field name: The string to be used as a field name in the JSON
3960 object
3961
3962 o Field type: The type of value to be provided, e.g., string,
3963 boolean, array of string
3964
3965 o Requests: Either the value "none" or a list of types of requests
3966 where the field is allowed in a request object, taken from the
3967 following values:
3968
3969 * "new" - Requests to the "newAccount" URL
3970
3971 * "account" - Requests to an account URL
3972
3973 o Reference: Where this field is defined
3974
3975
3976
3977
3978Barnes, et al. Standards Track [Page 71]
3979
3980RFC 8555 ACME March 2019
3981
3982
3983 Initial contents: The fields and descriptions defined in
3984 Section 7.1.2.
3985
3986 +------------------------+---------------+--------------+-----------+
3987 | Field Name | Field Type | Requests | Reference |
3988 +------------------------+---------------+--------------+-----------+
3989 | status | string | new, account | RFC 8555 |
3990 | | | | |
3991 | contact | array of | new, account | RFC 8555 |
3992 | | string | | |
3993 | | | | |
3994 | externalAccountBinding | object | new | RFC 8555 |
3995 | | | | |
3996 | termsOfServiceAgreed | boolean | new | RFC 8555 |
3997 | | | | |
3998 | onlyReturnExisting | boolean | new | RFC 8555 |
3999 | | | | |
4000 | orders | string | none | RFC 8555 |
4001 +------------------------+---------------+--------------+-----------+
4002
40039.7.2. Fields in Order Objects
4004
4005 The "ACME Order Object Fields" registry lists field names that are
4006 defined for use in ACME order objects. Fields marked as
4007 "configurable" may be included in a newOrder request.
4008
4009 Template:
4010
4011 o Field name: The string to be used as a field name in the JSON
4012 object
4013
4014 o Field type: The type of value to be provided, e.g., string,
4015 boolean, array of string
4016
4017 o Configurable: Boolean indicating whether the server should accept
4018 values provided by the client
4019
4020 o Reference: Where this field is defined
4021
4022
4023
4024
4025
4026
4027
4028
4029
4030
4031
4032
4033
4034Barnes, et al. Standards Track [Page 72]
4035
4036RFC 8555 ACME March 2019
4037
4038
4039 Initial contents: The fields and descriptions defined in
4040 Section 7.1.3.
4041
4042 +----------------+-----------------+--------------+-----------+
4043 | Field Name | Field Type | Configurable | Reference |
4044 +----------------+-----------------+--------------+-----------+
4045 | status | string | false | RFC 8555 |
4046 | | | | |
4047 | expires | string | false | RFC 8555 |
4048 | | | | |
4049 | identifiers | array of object | true | RFC 8555 |
4050 | | | | |
4051 | notBefore | string | true | RFC 8555 |
4052 | | | | |
4053 | notAfter | string | true | RFC 8555 |
4054 | | | | |
4055 | error | string | false | RFC 8555 |
4056 | | | | |
4057 | authorizations | array of string | false | RFC 8555 |
4058 | | | | |
4059 | finalize | string | false | RFC 8555 |
4060 | | | | |
4061 | certificate | string | false | RFC 8555 |
4062 +----------------+-----------------+--------------+-----------+
4063
40649.7.3. Fields in Authorization Objects
4065
4066 The "ACME Authorization Object Fields" registry lists field names
4067 that are defined for use in ACME authorization objects. Fields
4068 marked as "configurable" may be included in a newAuthz request.
4069
4070 Template:
4071
4072 o Field name: The string to be used as a field name in the JSON
4073 object
4074
4075 o Field type: The type of value to be provided, e.g., string,
4076 boolean, array of string
4077
4078 o Configurable: Boolean indicating whether the server should accept
4079 values provided by the client
4080
4081 o Reference: Where this field is defined
4082
4083
4084
4085
4086
4087
4088
4089
4090Barnes, et al. Standards Track [Page 73]
4091
4092RFC 8555 ACME March 2019
4093
4094
4095 Initial contents: The fields and descriptions defined in
4096 Section 7.1.4.
4097
4098 +------------+-----------------+--------------+-----------+
4099 | Field Name | Field Type | Configurable | Reference |
4100 +------------+-----------------+--------------+-----------+
4101 | identifier | object | true | RFC 8555 |
4102 | | | | |
4103 | status | string | false | RFC 8555 |
4104 | | | | |
4105 | expires | string | false | RFC 8555 |
4106 | | | | |
4107 | challenges | array of object | false | RFC 8555 |
4108 | | | | |
4109 | wildcard | boolean | false | RFC 8555 |
4110 +------------+-----------------+--------------+-----------+
4111
41129.7.4. Error Types
4113
4114 The "ACME Error Types" registry lists values that are used within URN
4115 values that are provided in the "type" field of problem documents in
4116 ACME.
4117
4118 Template:
4119
4120 o Type: The label to be included in the URN for this error,
4121 following "urn:ietf:params:acme:error:"
4122
4123 o Description: A human-readable description of the error
4124
4125 o Reference: Where the error is defined
4126
4127 Initial contents: The types and descriptions in the table in
4128 Section 6.7 above, with the Reference field set to point to this
4129 specification.
4130
41319.7.5. Resource Types
4132
4133 The "ACME Resource Types" registry lists the types of resources that
4134 ACME servers may list in their directory objects.
4135
4136 Template:
4137
4138 o Field name: The value to be used as a field name in the directory
4139 object
4140
4141 o Resource type: The type of resource labeled by the field
4142
4143
4144
4145
4146Barnes, et al. Standards Track [Page 74]
4147
4148RFC 8555 ACME March 2019
4149
4150
4151 o Reference: Where the resource type is defined
4152
4153 Initial contents:
4154
4155 +------------+--------------------+-----------+
4156 | Field Name | Resource Type | Reference |
4157 +------------+--------------------+-----------+
4158 | newNonce | New nonce | RFC 8555 |
4159 | | | |
4160 | newAccount | New account | RFC 8555 |
4161 | | | |
4162 | newOrder | New order | RFC 8555 |
4163 | | | |
4164 | newAuthz | New authorization | RFC 8555 |
4165 | | | |
4166 | revokeCert | Revoke certificate | RFC 8555 |
4167 | | | |
4168 | keyChange | Key change | RFC 8555 |
4169 | | | |
4170 | meta | Metadata object | RFC 8555 |
4171 +------------+--------------------+-----------+
4172
41739.7.6. Fields in the "meta" Object within a Directory Object
4174
4175 The "ACME Directory Metadata Fields" registry lists field names that
4176 are defined for use in the JSON object included in the "meta" field
4177 of an ACME directory object.
4178
4179 Template:
4180
4181 o Field name: The string to be used as a field name in the JSON
4182 object
4183
4184 o Field type: The type of value to be provided, e.g., string,
4185 boolean, array of string
4186
4187 o Reference: Where this field is defined
4188
4189
4190
4191
4192
4193
4194
4195
4196
4197
4198
4199
4200
4201
4202Barnes, et al. Standards Track [Page 75]
4203
4204RFC 8555 ACME March 2019
4205
4206
4207 Initial contents: The fields and descriptions defined in
4208 Section 7.1.1.
4209
4210 +-------------------------+-----------------+-----------+
4211 | Field Name | Field Type | Reference |
4212 +-------------------------+-----------------+-----------+
4213 | termsOfService | string | RFC 8555 |
4214 | | | |
4215 | website | string | RFC 8555 |
4216 | | | |
4217 | caaIdentities | array of string | RFC 8555 |
4218 | | | |
4219 | externalAccountRequired | boolean | RFC 8555 |
4220 +-------------------------+-----------------+-----------+
4221
42229.7.7. Identifier Types
4223
4224 The "ACME Identifier Types" registry lists the types of identifiers
4225 that can be present in ACME authorization objects.
4226
4227 Template:
4228
4229 o Label: The value to be put in the "type" field of the identifier
4230 object
4231
4232 o Reference: Where the identifier type is defined
4233
4234 Initial contents:
4235
4236 +-------+-----------+
4237 | Label | Reference |
4238 +-------+-----------+
4239 | dns | RFC 8555 |
4240 +-------+-----------+
4241
42429.7.8. Validation Methods
4243
4244 The "ACME Validation Methods" registry lists identifiers for the ways
4245 that CAs can validate control of identifiers. Each method's entry
4246 must specify whether it corresponds to an ACME challenge type. The
4247 "Identifier Type" field must be contained in the Label column of the
4248 "ACME Identifier Types" registry.
4249
4250
4251
4252
4253
4254
4255
4256
4257
4258Barnes, et al. Standards Track [Page 76]
4259
4260RFC 8555 ACME March 2019
4261
4262
4263 Template:
4264
4265 o Label: The identifier for this validation method
4266
4267 o Identifier Type: The type of identifier that this method applies
4268 to
4269
4270 o ACME: "Y" if the validation method corresponds to an ACME
4271 challenge type; "N" otherwise
4272
4273 o Reference: Where the validation method is defined
4274
4275 This registry may also contain reserved entries (e.g., to avoid
4276 collisions). Such entries should have the "ACME" field set to "N"
4277 and the "Identifier Type" set to "RESERVED".
4278
4279 Initial Contents
4280
4281 +------------+-----------------+------+-----------+
4282 | Label | Identifier Type | ACME | Reference |
4283 +------------+-----------------+------+-----------+
4284 | http-01 | dns | Y | RFC 8555 |
4285 | | | | |
4286 | dns-01 | dns | Y | RFC 8555 |
4287 | | | | |
4288 | tls-sni-01 | RESERVED | N | RFC 8555 |
4289 | | | | |
4290 | tls-sni-02 | RESERVED | N | RFC 8555 |
4291 +------------+-----------------+------+-----------+
4292
4293 When evaluating a request for an assignment in this registry, the
4294 designated expert should ensure that the method being registered has
4295 a clear, interoperable definition and does not overlap with existing
4296 validation methods. That is, it should not be possible for a client
4297 and server to follow the same set of actions to fulfill two different
4298 validation methods.
4299
4300 The values "tls-sni-01" and "tls-sni-02" are reserved because they
4301 were used in pre-RFC versions of this specification to denote
4302 validation methods that were removed because they were found not to
4303 be secure in some cases.
4304
4305 Validation methods do not have to be compatible with ACME in order to
4306 be registered. For example, a CA might wish to register a validation
4307 method to support its use with the ACME extensions to CAA [ACME-CAA].
4308
4309
4310
4311
4312
4313
4314Barnes, et al. Standards Track [Page 77]
4315
4316RFC 8555 ACME March 2019
4317
4318
431910. Security Considerations
4320
4321 ACME is a protocol for managing certificates that attest to
4322 identifier/key bindings. Thus, the foremost security goal of ACME is
4323 to ensure the integrity of this process, i.e., to ensure that the
4324 bindings attested by certificates are correct and that only
4325 authorized entities can manage certificates. ACME identifies clients
4326 by their account keys, so this overall goal breaks down into two more
4327 precise goals:
4328
4329 1. Only an entity that controls an identifier can get an
4330 authorization for that identifier
4331
4332 2. Once authorized, an account key's authorizations cannot be
4333 improperly used by another account
4334
4335 In this section, we discuss the threat model that underlies ACME and
4336 the ways that ACME achieves these security goals within that threat
4337 model. We also discuss the denial-of-service risks that ACME servers
4338 face, and a few other miscellaneous considerations.
4339
434010.1. Threat Model
4341
4342 As a service on the Internet, ACME broadly exists within the Internet
4343 threat model [RFC3552]. In analyzing ACME, it is useful to think of
4344 an ACME server interacting with other Internet hosts along two
4345 "channels":
4346
4347 o An ACME channel, over which the ACME HTTPS requests are exchanged
4348
4349 o A validation channel, over which the ACME server performs
4350 additional requests to validate a client's control of an
4351 identifier
4352
4353
4354
4355
4356
4357
4358
4359
4360
4361
4362
4363
4364
4365
4366
4367
4368
4369
4370Barnes, et al. Standards Track [Page 78]
4371
4372RFC 8555 ACME March 2019
4373
4374
4375 +------------+
4376 | ACME | ACME Channel
4377 | Client |--------------------+
4378 +------------+ |
4379 V
4380 +------------+
4381 | ACME |
4382 | Server |
4383 +------------+
4384 +------------+ |
4385 | Validation |<-------------------+
4386 | Server | Validation Channel
4387 +------------+
4388
4389 Communications Channels Used by ACME
4390
4391 In practice, the risks to these channels are not entirely separate,
4392 but they are different in most cases. Each channel, for example,
4393 uses a different communications pattern: the ACME channel will
4394 comprise inbound HTTPS connections to the ACME server and the
4395 validation channel outbound HTTP or DNS requests.
4396
4397 Broadly speaking, ACME aims to be secure against active and passive
4398 attackers on any individual channel. Some vulnerabilities arise
4399 (noted below) when an attacker can exploit both the ACME channel and
4400 one of the others.
4401
4402 On the ACME channel, in addition to network-layer attackers, we also
4403 need to account for man-in-the-middle (MitM) attacks at the
4404 application layer and for abusive use of the protocol itself.
4405 Protection against application-layer MitM addresses potential
4406 attackers such as Content Distribution Networks (CDNs) and
4407 middleboxes with a TLS MitM function. Preventing abusive use of ACME
4408 means ensuring that an attacker with access to the validation channel
4409 can't obtain illegitimate authorization by acting as an ACME client
4410 (legitimately, in terms of the protocol).
4411
4412 ACME does not protect against other types of abuse by a MitM on the
4413 ACME channel. For example, such an attacker could send a bogus
4414 "badSignatureAlgorithm" error response to downgrade a client to the
4415 lowest-quality signature algorithm that the server supports. A MitM
4416 that is present on all connections (such as a CDN) can cause denial-
4417 of-service conditions in a variety of ways.
4418
4419
4420
4421
4422
4423
4424
4425
4426Barnes, et al. Standards Track [Page 79]
4427
4428RFC 8555 ACME March 2019
4429
4430
443110.2. Integrity of Authorizations
4432
4433 ACME allows anyone to request challenges for an identifier by
4434 registering an account key and sending a newOrder request using that
4435 account key. The integrity of the authorization process thus depends
4436 on the identifier validation challenges to ensure that the challenge
4437 can only be completed by someone who both (1) holds the private key
4438 of the account key pair and (2) controls the identifier in question.
4439
4440 Validation responses need to be bound to an account key pair in order
4441 to avoid situations where a MitM on ACME HTTPS requests can switch
4442 out a legitimate domain holder's account key for one of his choosing.
4443 Such MitMs can arise, for example, if a CA uses a CDN or third-party
4444 reverse proxy in front of its ACME interface. An attack by such an
4445 MitM could have the following form:
4446
4447 1. Legitimate domain holder registers account key pair A
4448
4449 2. MitM registers account key pair B
4450
4451 3. Legitimate domain holder sends a newOrder request signed using
4452 account key A
4453
4454 4. MitM suppresses the legitimate request but sends the same request
4455 signed using account key B
4456
4457 5. ACME server issues challenges and MitM forwards them to the
4458 legitimate domain holder
4459
4460 6. Legitimate domain holder provisions the validation response
4461
4462 7. ACME server performs validation query and sees the response
4463 provisioned by the legitimate domain holder
4464
4465 8. Because the challenges were issued in response to a message
4466 signed with account key B, the ACME server grants authorization
4467 to account key B (the MitM) instead of account key A (the
4468 legitimate domain holder)
4469
4470
4471
4472
4473
4474
4475
4476
4477
4478
4479
4480
4481
4482Barnes, et al. Standards Track [Page 80]
4483
4484RFC 8555 ACME March 2019
4485
4486
4487 Domain ACME
4488 Holder MitM Server
4489 | | |
4490 | newAccount(A) | |
4491 |--------------------->|--------------------->|
4492 | | |
4493 | | newAccount(B) |
4494 | |--------------------->|
4495 | newOrder(domain, A) | |
4496 |--------------------->| |
4497 | | newOrder(domain, B) |
4498 | |--------------------->|
4499 | | |
4500 | authz, challenges | authz, challenges |
4501 |<---------------------|<---------------------|
4502 | | |
4503 | response(chall, A) | response(chall, B) |
4504 |--------------------->|--------------------->|
4505 | | |
4506 | validation request | |
4507 |<--------------------------------------------|
4508 | | |
4509 | validation response | |
4510 |-------------------------------------------->|
4511 | | |
4512 | | | Considers challenge
4513 | | | fulfilled by B
4514 | | |
4515
4516 Man-in-the-Middle Attack Exploiting a Validation
4517 Method without Account Key Binding
4518
4519 All of the challenges defined in this document have a binding between
4520 the account private key and the validation query made by the server,
4521 via the key authorization. The key authorization reflects the
4522 account public key and is provided to the server in the validation
4523 response over the validation channel.
4524
4525 The association of challenges to identifiers is typically done by
4526 requiring the client to perform some action that only someone who
4527 effectively controls the identifier can perform. For the challenges
4528 in this document, the actions are as follows:
4529
4530 o HTTP: Provision files under .well-known on a web server for the
4531 domain
4532
4533 o DNS: Provision DNS resource records for the domain
4534
4535
4536
4537
4538Barnes, et al. Standards Track [Page 81]
4539
4540RFC 8555 ACME March 2019
4541
4542
4543 There are several ways that these assumptions can be violated, both
4544 by misconfiguration and by attacks. For example, on a web server
4545 that allows non-administrative users to write to .well-known, any
4546 user can claim to own the web server's hostname by responding to an
4547 HTTP challenge. Similarly, if a server that can be used for ACME
4548 validation is compromised by a malicious actor, then that malicious
4549 actor can use that access to obtain certificates via ACME.
4550
4551 The use of hosting providers is a particular risk for ACME
4552 validation. If the owner of the domain has outsourced operation of
4553 DNS or web services to a hosting provider, there is nothing that can
4554 be done against tampering by the hosting provider. As far as the
4555 outside world is concerned, the zone or website provided by the
4556 hosting provider is the real thing.
4557
4558 More limited forms of delegation can also lead to an unintended party
4559 gaining the ability to successfully complete a validation
4560 transaction. For example, suppose an ACME server follows HTTP
4561 redirects in HTTP validation and a website operator provisions a
4562 catch-all redirect rule that redirects requests for unknown resources
4563 to a different domain. Then the target of the redirect could use
4564 that to get a certificate through HTTP validation since the
4565 validation path will not be known to the primary server.
4566
4567 The DNS is a common point of vulnerability for all of these
4568 challenges. An entity that can provision false DNS records for a
4569 domain can attack the DNS challenge directly and can provision false
4570 A/AAAA records to direct the ACME server to send its HTTP validation
4571 query to a remote server of the attacker's choosing. There are a few
4572 different mitigations that ACME servers can apply:
4573
4574 o Always querying the DNS using a DNSSEC-validating resolver
4575 (enhancing security for zones that are DNSSEC-enabled)
4576
4577 o Querying the DNS from multiple vantage points to address local
4578 attackers
4579
4580 o Applying mitigations against DNS off-path attackers, e.g., adding
4581 entropy to requests [DNS0x20] or only using TCP
4582
4583 Given these considerations, the ACME validation process makes it
4584 impossible for any attacker on the ACME channel or a passive attacker
4585 on the validation channel to hijack the authorization process to
4586 authorize a key of the attacker's choice.
4587
4588 An attacker that can only see the ACME channel would need to convince
4589 the validation server to provide a response that would authorize the
4590 attacker's account key, but this is prevented by binding the
4591
4592
4593
4594Barnes, et al. Standards Track [Page 82]
4595
4596RFC 8555 ACME March 2019
4597
4598
4599 validation response to the account key used to request challenges. A
4600 passive attacker on the validation channel can observe the correct
4601 validation response and even replay it, but that response can only be
4602 used with the account key for which it was generated.
4603
4604 An active attacker on the validation channel can subvert the ACME
4605 process, by performing normal ACME transactions and providing a
4606 validation response for his own account key. The risks due to
4607 hosting providers noted above are a particular case.
4608
4609 Attackers can also exploit vulnerabilities in Internet routing
4610 protocols to gain access to the validation channel (see, e.g.,
4611 [RFC7132]). In order to make such attacks more difficult, it is
4612 RECOMMENDED that the server perform DNS queries and make HTTP
4613 connections from multiple points in the network. Since routing
4614 attacks are often localized or dependent on the position of the
4615 attacker, forcing the attacker to attack multiple points (the
4616 server's validation vantage points) or a specific point (the DNS /
4617 HTTP server) makes it more difficult to subvert ACME validation using
4618 attacks on routing.
4619
462010.3. Denial-of-Service Considerations
4621
4622 As a protocol run over HTTPS, standard considerations for TCP-based
4623 and HTTP-based DoS mitigation also apply to ACME.
4624
4625 At the application layer, ACME requires the server to perform a few
4626 potentially expensive operations. Identifier validation transactions
4627 require the ACME server to make outbound connections to potentially
4628 attacker-controlled servers, and certificate issuance can require
4629 interactions with cryptographic hardware.
4630
4631 In addition, an attacker can also cause the ACME server to send
4632 validation requests to a domain of its choosing by submitting
4633 authorization requests for the victim domain.
4634
4635 All of these attacks can be mitigated by the application of
4636 appropriate rate limits. Issues closer to the front end, like POST
4637 body validation, can be addressed using HTTP request limiting. For
4638 validation and certificate requests, there are other identifiers on
4639 which rate limits can be keyed. For example, the server might limit
4640 the rate at which any individual account key can issue certificates
4641 or the rate at which validation can be requested within a given
4642 subtree of the DNS. And in order to prevent attackers from
4643 circumventing these limits simply by minting new accounts, servers
4644 would need to limit the rate at which accounts can be registered.
4645
4646
4647
4648
4649
4650Barnes, et al. Standards Track [Page 83]
4651
4652RFC 8555 ACME March 2019
4653
4654
465510.4. Server-Side Request Forgery
4656
4657 Server-Side Request Forgery (SSRF) attacks can arise when an attacker
4658 can cause a server to perform HTTP requests to an attacker-chosen
4659 URL. In the ACME HTTP challenge validation process, the ACME server
4660 performs an HTTP GET request to a URL in which the attacker can
4661 choose the domain. This request is made before the server has
4662 verified that the client controls the domain, so any client can cause
4663 a query to any domain.
4664
4665 Some ACME server implementations include information from the
4666 validation server's response (in order to facilitate debugging).
4667 Such implementations enable an attacker to extract this information
4668 from any web server that is accessible to the ACME server, even if it
4669 is not accessible to the ACME client. For example, the ACME server
4670 might be able to access servers behind a firewall that would prevent
4671 access by the ACME client.
4672
4673 It might seem that the risk of SSRF through this channel is limited
4674 by the fact that the attacker can only control the domain of the URL,
4675 not the path. However, if the attacker first sets the domain to one
4676 they control, then they can send the server an HTTP redirect (e.g., a
4677 302 response) which will cause the server to query an arbitrary URL.
4678
4679 In order to further limit the SSRF risk, ACME server operators should
4680 ensure that validation queries can only be sent to servers on the
4681 public Internet, and not, say, web services within the server
4682 operator's internal network. Since the attacker could make requests
4683 to these public servers himself, he can't gain anything extra through
4684 an SSRF attack on ACME aside from a layer of anonymization.
4685
468610.5. CA Policy Considerations
4687
4688 The controls on issuance enabled by ACME are focused on validating
4689 that a certificate applicant controls the identifier he claims.
4690 Before issuing a certificate, however, there are many other checks
4691 that a CA might need to perform, for example:
4692
4693 o Has the client agreed to a subscriber agreement?
4694
4695 o Is the claimed identifier syntactically valid?
4696
4697 o For domain names:
4698
4699 * If the leftmost label is a '*', then have the appropriate
4700 checks been applied?
4701
4702 * Is the name on the Public Suffix List?
4703
4704
4705
4706Barnes, et al. Standards Track [Page 84]
4707
4708RFC 8555 ACME March 2019
4709
4710
4711 * Is the name a high-value name?
4712
4713 * Is the name a known phishing domain?
4714
4715 o Is the key in the CSR sufficiently strong?
4716
4717 o Is the CSR signed with an acceptable algorithm?
4718
4719 o Has issuance been authorized or forbidden by a Certification
4720 Authority Authorization (CAA) record ([RFC6844])?
4721
4722 CAs that use ACME to automate issuance will need to ensure that their
4723 servers perform all necessary checks before issuing.
4724
4725 CAs using ACME to allow clients to agree to terms of service should
4726 keep in mind that ACME clients can automate this agreement, possibly
4727 not involving a human user.
4728
4729 ACME does not specify how the server constructs the URLs that it uses
4730 to address resources. If the server operator uses URLs that are
4731 predictable to third parties, this can leak information about what
4732 URLs exist on the server, since an attacker can probe for whether a
4733 POST-as-GET request to the URL returns 404 (Not Found) or 401
4734 (Unauthorized).
4735
4736 For example, suppose that the CA uses highly structured URLs with
4737 guessable fields:
4738
4739 o Accounts: https://example.com/:accountID
4740
4741 o Orders: https://example.com/:accountID/:domainName
4742
4743 o Authorizations: https://example.com/:accountID/:domainName
4744
4745 o Certificates: https://example.com/:accountID/:domainName
4746
4747 Under that scheme, an attacker could probe for which domain names are
4748 associated with which accounts, which may allow correlation of
4749 ownership between domain names, if the CA does not otherwise permit
4750 it.
4751
4752
4753
4754
4755
4756
4757
4758
4759
4760
4761
4762Barnes, et al. Standards Track [Page 85]
4763
4764RFC 8555 ACME March 2019
4765
4766
4767 To avoid leaking these correlations, CAs SHOULD assign URLs with an
4768 unpredictable component. For example, a CA might assign URLs for
4769 each resource type from an independent namespace, using unpredictable
4770 IDs for each resource:
4771
4772 o Accounts: https://example.com/acct/:accountID
4773
4774 o Orders: https://example.com/order/:orderID
4775
4776 o Authorizations: https://example.com/authz/:authorizationID
4777
4778 o Certificates: https://example.com/cert/:certID
4779
4780 Such a scheme would leak only the type of resource, hiding the
4781 additional correlations revealed in the example above.
4782
478311. Operational Considerations
4784
4785 There are certain factors that arise in operational reality that
4786 operators of ACME-based CAs will need to keep in mind when
4787 configuring their services. See the subsections below for examples.
4788
478911.1. Key Selection
4790
4791 ACME relies on two different classes of key pair:
4792
4793 o Account key pairs, which are used to authenticate account holders
4794
4795 o Certificate key pairs, which are used to sign and verify CSRs (and
4796 whose public keys are included in certificates)
4797
4798 Compromise of the private key of an account key pair has more serious
4799 consequences than compromise of a private key corresponding to a
4800 certificate. While the compromise of a certificate key pair allows
4801 the attacker to impersonate the entities named in the certificate for
4802 the lifetime of the certificate, the compromise of an account key
4803 pair allows the attacker to take full control of the victim's ACME
4804 account and take any action that the legitimate account holder could
4805 take within the scope of ACME:
4806
4807 1. Issuing certificates using existing authorizations
4808
4809 2. Revoking existing certificates
4810
4811 3. Accessing and changing account information (e.g., contacts)
4812
4813 4. Changing the account key pair for the account, locking out the
4814 legitimate account holder
4815
4816
4817
4818Barnes, et al. Standards Track [Page 86]
4819
4820RFC 8555 ACME March 2019
4821
4822
4823 For this reason, it is RECOMMENDED that each account key pair be used
4824 only for authentication of a single ACME account. For example, the
4825 public key of an account key pair MUST NOT be included in a
4826 certificate. If an ACME client receives a request from a user for
4827 account creation or key rollover using an account key that the client
4828 knows to be used elsewhere, then the client MUST return an error.
4829 Clients MUST generate a fresh account key for every account creation
4830 or rollover operation. Note that given the requirements of
4831 Section 7.3.1, servers will not create accounts with reused keys
4832 anyway.
4833
4834 ACME clients and servers MUST verify that a CSR submitted in a
4835 finalize request does not contain a public key for any known account
4836 key pair. In particular, when a server receives a finalize request,
4837 it MUST verify that the public key in a CSR is not the same as the
4838 public key of the account key pair used to authenticate that request.
4839 This assures that vulnerabilities in the protocols with which the
4840 certificate is used (e.g., signing oracles in TLS [JSS15]) do not
4841 result in compromise of the ACME account. Because ACME accounts are
4842 uniquely identified by their account key pair (see Section 7.3.1),
4843 the server MUST not allow account key pair reuse across multiple
4844 accounts.
4845
484611.2. DNS Security
4847
4848 As noted above, DNS forgery attacks against the ACME server can
4849 result in the server making incorrect decisions about domain control
4850 and thus mis-issuing certificates. Servers SHOULD perform DNS
4851 queries over TCP, which provides better resistance to some forgery
4852 attacks than DNS over UDP.
4853
4854 An ACME-based CA will often need to make DNS queries, e.g., to
4855 validate control of DNS names. Because the security of such
4856 validations ultimately depends on the authenticity of DNS data, every
4857 possible precaution should be taken to secure DNS queries done by the
4858 CA. Therefore, it is RECOMMENDED that ACME-based CAs make all DNS
4859 queries via DNSSEC-validating stub or recursive resolvers. This
4860 provides additional protection to domains that choose to make use of
4861 DNSSEC.
4862
4863 An ACME-based CA must only use a resolver if it trusts the resolver
4864 and every component of the network route by which it is accessed.
4865 Therefore, it is RECOMMENDED that ACME-based CAs operate their own
4866 DNSSEC-validating resolvers within their trusted network and use
4867 these resolvers both for CAA record lookups and all record lookups in
4868 furtherance of a challenge scheme (A, AAAA, TXT, etc.).
4869
4870
4871
4872
4873
4874Barnes, et al. Standards Track [Page 87]
4875
4876RFC 8555 ACME March 2019
4877
4878
487911.3. Token Entropy
4880
4881 The http-01 and dns-01 validation methods mandate the use of a random
4882 token value to uniquely identify the challenge. The value of the
4883 token is required to contain at least 128 bits of entropy for the
4884 following security properties. First, the ACME client should not be
4885 able to influence the ACME server's choice of token as this may allow
4886 an attacker to reuse a domain owner's previous challenge responses
4887 for a new validation request. Second, the entropy requirement makes
4888 it more difficult for ACME clients to implement a "naive" validation
4889 server that automatically replies to challenges without being
4890 configured per challenge.
4891
489211.4. Malformed Certificate Chains
4893
4894 ACME provides certificate chains in the widely used format known
4895 colloquially as PEM (though it may diverge from the actual Privacy
4896 Enhanced Mail specification [RFC1421], as noted in [RFC7468]). Some
4897 current software will allow the configuration of a private key and a
4898 certificate in one PEM file by concatenating the textual encodings of
4899 the two objects. In the context of ACME, such software might be
4900 vulnerable to key replacement attacks. A malicious ACME server could
4901 cause a client to use a private key of its choosing by including the
4902 key in the PEM file returned in response to a query for a certificate
4903 URL.
4904
4905 When processing a file of type "application/pem-certificate-chain", a
4906 client SHOULD verify that the file contains only encoded
4907 certificates. If anything other than a certificate is found (i.e.,
4908 if the string "-----BEGIN" is ever followed by anything other than
4909 "CERTIFICATE"), then the client MUST reject the file as invalid.
4910
491112. References
4912
491312.1. Normative References
4914
4915 [FIPS180-4]
4916 National Institute of Standards and Technology (NIST),
4917 "Secure Hash Standard (SHS)", FIPS PUB 180-4,
4918 DOI 10.6028/NIST.FIPS.180-4, August 2015,
4919 <http://csrc.nist.gov/publications/fips/fips180-4/
4920 fips-180-4.pdf>.
4921
4922
4923
4924
4925
4926
4927
4928
4929
4930Barnes, et al. Standards Track [Page 88]
4931
4932RFC 8555 ACME March 2019
4933
4934
4935 [JSS15] Somorovsky, J., Schwenk, J., and J. Somorovsky, "On the
4936 Security of TLS 1.3 and QUIC Against Weaknesses in PKCS#1
4937 v1.5 Encryption", CSS '15 Proceedings of the 22nd ACM
4938 SIGSAC Conference on Computer and Communications
4939 Security Pages 1185-1196, DOI 10.1145/2810103.2813657,
4940 <https://dl.acm.org/citation.cfm?id=2813657>.
4941
4942 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
4943 Requirement Levels", BCP 14, RFC 2119,
4944 DOI 10.17487/RFC2119, March 1997,
4945 <https://www.rfc-editor.org/info/rfc2119>.
4946
4947 [RFC2585] Housley, R. and P. Hoffman, "Internet X.509 Public Key
4948 Infrastructure Operational Protocols: FTP and HTTP",
4949 RFC 2585, DOI 10.17487/RFC2585, May 1999,
4950 <https://www.rfc-editor.org/info/rfc2585>.
4951
4952 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818,
4953 DOI 10.17487/RFC2818, May 2000,
4954 <https://www.rfc-editor.org/info/rfc2818>.
4955
4956 [RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object
4957 Classes and Attribute Types Version 2.0", RFC 2985,
4958 DOI 10.17487/RFC2985, November 2000,
4959 <https://www.rfc-editor.org/info/rfc2985>.
4960
4961 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification
4962 Request Syntax Specification Version 1.7", RFC 2986,
4963 DOI 10.17487/RFC2986, November 2000,
4964 <https://www.rfc-editor.org/info/rfc2986>.
4965
4966 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
4967 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
4968 <https://www.rfc-editor.org/info/rfc3339>.
4969
4970 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
4971 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
4972 2003, <https://www.rfc-editor.org/info/rfc3629>.
4973
4974 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
4975 Resource Identifier (URI): Generic Syntax", STD 66,
4976 RFC 3986, DOI 10.17487/RFC3986, January 2005,
4977 <https://www.rfc-editor.org/info/rfc3986>.
4978
4979 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker,
4980 "Randomness Requirements for Security", BCP 106, RFC 4086,
4981 DOI 10.17487/RFC4086, June 2005,
4982 <https://www.rfc-editor.org/info/rfc4086>.
4983
4984
4985
4986Barnes, et al. Standards Track [Page 89]
4987
4988RFC 8555 ACME March 2019
4989
4990
4991 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
4992 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
4993 <https://www.rfc-editor.org/info/rfc4648>.
4994
4995 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
4996 Specifications: ABNF", STD 68, RFC 5234,
4997 DOI 10.17487/RFC5234, January 2008,
4998 <https://www.rfc-editor.org/info/rfc5234>.
4999
5000 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
5001 Housley, R., and W. Polk, "Internet X.509 Public Key
5002 Infrastructure Certificate and Certificate Revocation List
5003 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
5004 <https://www.rfc-editor.org/info/rfc5280>.
5005
5006 [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet
5007 Mail Extensions (S/MIME) Version 3.2 Message
5008 Specification", RFC 5751, DOI 10.17487/RFC5751, January
5009 2010, <https://www.rfc-editor.org/info/rfc5751>.
5010
5011 [RFC5890] Klensin, J., "Internationalized Domain Names for
5012 Applications (IDNA): Definitions and Document Framework",
5013 RFC 5890, DOI 10.17487/RFC5890, August 2010,
5014 <https://www.rfc-editor.org/info/rfc5890>.
5015
5016 [RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto'
5017 URI Scheme", RFC 6068, DOI 10.17487/RFC6068, October 2010,
5018 <https://www.rfc-editor.org/info/rfc6068>.
5019
5020 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
5021 and D. Orchard, "URI Template", RFC 6570,
5022 DOI 10.17487/RFC6570, March 2012,
5023 <https://www.rfc-editor.org/info/rfc6570>.
5024
5025 [RFC6844] Hallam-Baker, P. and R. Stradling, "DNS Certification
5026 Authority Authorization (CAA) Resource Record", RFC 6844,
5027 DOI 10.17487/RFC6844, January 2013,
5028 <https://www.rfc-editor.org/info/rfc6844>.
5029
5030 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
5031 Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
5032 DOI 10.17487/RFC7231, June 2014,
5033 <https://www.rfc-editor.org/info/rfc7231>.
5034
5035 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX,
5036 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468,
5037 April 2015, <https://www.rfc-editor.org/info/rfc7468>.
5038
5039
5040
5041
5042Barnes, et al. Standards Track [Page 90]
5043
5044RFC 8555 ACME March 2019
5045
5046
5047 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
5048 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
5049 2015, <https://www.rfc-editor.org/info/rfc7515>.
5050
5051 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
5052 DOI 10.17487/RFC7518, May 2015,
5053 <https://www.rfc-editor.org/info/rfc7518>.
5054
5055 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK)
5056 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September
5057 2015, <https://www.rfc-editor.org/info/rfc7638>.
5058
5059 [RFC7797] Jones, M., "JSON Web Signature (JWS) Unencoded Payload
5060 Option", RFC 7797, DOI 10.17487/RFC7797, February 2016,
5061 <https://www.rfc-editor.org/info/rfc7797>.
5062
5063 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP
5064 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016,
5065 <https://www.rfc-editor.org/info/rfc7807>.
5066
5067 [RFC8037] Liusvaara, I., "CFRG Elliptic Curve Diffie-Hellman (ECDH)
5068 and Signatures in JSON Object Signing and Encryption
5069 (JOSE)", RFC 8037, DOI 10.17487/RFC8037, January 2017,
5070 <https://www.rfc-editor.org/info/rfc8037>.
5071
5072 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
5073 Writing an IANA Considerations Section in RFCs", BCP 26,
5074 RFC 8126, DOI 10.17487/RFC8126, June 2017,
5075 <https://www.rfc-editor.org/info/rfc8126>.
5076
5077 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
5078 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
5079 May 2017, <https://www.rfc-editor.org/info/rfc8174>.
5080
5081 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
5082 Interchange Format", STD 90, RFC 8259,
5083 DOI 10.17487/RFC8259, December 2017,
5084 <https://www.rfc-editor.org/info/rfc8259>.
5085
5086 [RFC8288] Nottingham, M., "Web Linking", RFC 8288,
5087 DOI 10.17487/RFC8288, October 2017,
5088 <https://www.rfc-editor.org/info/rfc8288>.
5089
5090 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
5091 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
5092 <https://www.rfc-editor.org/info/rfc8446>.
5093
5094
5095
5096
5097
5098Barnes, et al. Standards Track [Page 91]
5099
5100RFC 8555 ACME March 2019
5101
5102
510312.2. Informative References
5104
5105 [ACME-CAA]
5106 Landau, H., "CAA Record Extensions for Account URI and
5107 ACME Method Binding", Work in Progress, draft-ietf-acme-
5108 caa-06, January 2019.
5109
5110 [ACME-IP] Shoemaker, R., "ACME IP Identifier Validation Extension",
5111 Work in Progress, draft-ietf-acme-ip-05, February 2019.
5112
5113 [ACME-TELEPHONE]
5114 Peterson, J. and R. Barnes, "ACME Identifiers and
5115 Challenges for Telephone Numbers", Work in Progress,
5116 draft-ietf-acme-telephone-01, October 2017.
5117
5118 [CABFBR] CA/Browser Forum, "CA/Browser Forum Baseline
5119 Requirements", September 2018,
5120 <https://cabforum.org/baseline-requirements-documents/>.
5121
5122 [DNS0x20] Vixie, P. and D. Dagon, "Use of Bit 0x20 in DNS Labels to
5123 Improve Transaction Identity", Work in Progress,
5124 draft-vixie-dnsext-dns0x20-00, March 2008.
5125
5126 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic
5127 Mail: Part I: Message Encryption and Authentication
5128 Procedures", RFC 1421, DOI 10.17487/RFC1421, February
5129 1993, <https://www.rfc-editor.org/info/rfc1421>.
5130
5131 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC
5132 Text on Security Considerations", BCP 72, RFC 3552,
5133 DOI 10.17487/RFC3552, July 2003,
5134 <https://www.rfc-editor.org/info/rfc3552>.
5135
5136 [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An
5137 IETF URN Sub-namespace for Registered Protocol
5138 Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June
5139 2003, <https://www.rfc-editor.org/info/rfc3553>.
5140 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
5141 Uniform Resource Identifiers (URIs)", RFC 5785,
5142 DOI 10.17487/RFC5785, April 2010,
5143 <https://www.rfc-editor.org/info/rfc5785>.
5144
5145 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A.,
5146 Galperin, S., and C. Adams, "X.509 Internet Public Key
5147 Infrastructure Online Certificate Status Protocol - OCSP",
5148 RFC 6960, DOI 10.17487/RFC6960, June 2013,
5149 <https://www.rfc-editor.org/info/rfc6960>.
5150
5151
5152
5153
5154Barnes, et al. Standards Track [Page 92]
5155
5156RFC 8555 ACME March 2019
5157
5158
5159 [RFC7132] Kent, S. and A. Chi, "Threat Model for BGP Path Security",
5160 RFC 7132, DOI 10.17487/RFC7132, February 2014,
5161 <https://www.rfc-editor.org/info/rfc7132>.
5162
5163 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre,
5164 "Recommendations for Secure Use of Transport Layer
5165 Security (TLS) and Datagram Transport Layer Security
5166 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May
5167 2015, <https://www.rfc-editor.org/info/rfc7525>.
5168
5169 [W3C.REC-cors-20140116]
5170 Kesteren, A., Ed., "Cross-Origin Resource Sharing", W3C
5171 Recommendation REC-cors-20140116, January 2014,
5172 <http://www.w3.org/TR/2014/REC-cors-20140116>.
5173
5174
5175
5176
5177
5178
5179
5180
5181
5182
5183
5184
5185
5186
5187
5188
5189
5190
5191
5192
5193
5194
5195
5196
5197
5198
5199
5200
5201
5202
5203
5204
5205
5206
5207
5208
5209
5210Barnes, et al. Standards Track [Page 93]
5211
5212RFC 8555 ACME March 2019
5213
5214
5215Acknowledgements
5216
5217 In addition to the editors listed on the front page, this document
5218 has benefited from contributions from a broad set of contributors,
5219 all the way back to its inception.
5220
5221 o Andrew Ayer, SSLMate
5222
5223 o Karthik Bhargavan, INRIA
5224
5225 o Peter Eckersley, EFF
5226
5227 o Alex Halderman, University of Michigan
5228
5229 o Sophie Herold, Hemio
5230
5231 o Tim Hollebeek, DigiCert
5232
5233 o Eric Rescorla, Mozilla
5234
5235 o Seth Schoen, EFF
5236
5237 o Roland Shoemaker, Let's Encrypt
5238
5239 o Rob Stradling, Sectigo
5240
5241 o Martin Thomson, Mozilla
5242
5243 o Jakub Warmuz, University of Oxford
5244
5245 This document draws on many concepts established by Eric Rescorla's
5246 "Automated Certificate Issuance Protocol" draft. Martin Thomson
5247 provided helpful guidance in the use of HTTP.
5248
5249
5250
5251
5252
5253
5254
5255
5256
5257
5258
5259
5260
5261
5262
5263
5264
5265
5266Barnes, et al. Standards Track [Page 94]
5267
5268RFC 8555 ACME March 2019
5269
5270
5271Authors' Addresses
5272
5273 Richard Barnes
5274 Cisco
5275
5276 Email: rlb@ipv.sx
5277
5278
5279 Jacob Hoffman-Andrews
5280 EFF
5281
5282 Email: jsha@eff.org
5283
5284
5285 Daniel McCarney
5286 Let's Encrypt
5287
5288 Email: cpu@letsencrypt.org
5289
5290
5291 James Kasten
5292 University of Michigan
5293
5294 Email: jdkasten@umich.edu
5295
5296
5297
5298
5299
5300
5301
5302
5303
5304
5305
5306
5307
5308
5309
5310
5311
5312
5313
5314
5315
5316
5317
5318
5319
5320
5321
5322Barnes, et al. Standards Track [Page 95]
5323
5324