This repository was archived by the owner on Jun 18, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 15
/
Copy pathrfc8555.diff
6128 lines (5218 loc) · 243 KB
/
rfc8555.diff
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
--- draft-ietf-acme-acme-12.txt 2018-04-24 20:05:25.000000000 +0200
+++ rfc8555.txt 2019-03-11 22:04:54.000000000 +0100
@@ -2,70 +2,67 @@
-ACME Working Group R. Barnes
-Internet-Draft Cisco
-Intended status: Standards Track J. Hoffman-Andrews
-Expires: October 26, 2018 EFF
+
+
+Internet Engineering Task Force (IETF) R. Barnes
+Request for Comments: 8555 Cisco
+Category: Standards Track J. Hoffman-Andrews
+ISSN: 2070-1721 EFF
D. McCarney
Let's Encrypt
J. Kasten
University of Michigan
- April 24, 2018
+ March 2019
Automatic Certificate Management Environment (ACME)
- draft-ietf-acme-acme-12
Abstract
- Certificates in PKI using X.509 (PKIX) are used for a number of
- purposes, the most significant of which is the authentication of
- domain names. Thus, certificate authorities in the Web PKI are
- trusted to verify that an applicant for a certificate legitimately
- represents the domain name(s) in the certificate. Today, this
- verification is done through a collection of ad hoc mechanisms. This
- document describes a protocol that a certification authority (CA) and
- an applicant can use to automate the process of verification and
- certificate issuance. The protocol also provides facilities for
- other certificate management functions, such as certificate
- revocation.
-
- RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH: The source for
- this draft is maintained in GitHub. Suggested changes should be
- submitted as pull requests at https://github.com/ietf-wg-acme/acme
- [1]. Instructions are on that page as well. Editorial changes can
- be managed in GitHub, but any substantive change should be discussed
- on the ACME mailing list ([email protected]).
+ Public Key Infrastructure using X.509 (PKIX) certificates are used
+ for a number of purposes, the most significant of which is the
+ authentication of domain names. Thus, certification authorities
+ (CAs) in the Web PKI are trusted to verify that an applicant for a
+ certificate legitimately represents the domain name(s) in the
+ certificate. As of this writing, this verification is done through a
+ collection of ad hoc mechanisms. This document describes a protocol
+ that a CA and an applicant can use to automate the process of
+ verification and certificate issuance. The protocol also provides
+ facilities for other certificate management functions, such as
+ certificate revocation.
Status of This Memo
- This Internet-Draft is submitted in full conformance with the
- provisions of BCP 78 and BCP 79.
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 7841.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ https://www.rfc-editor.org/info/rfc8555.
- Internet-Drafts are working documents of the Internet Engineering
- Task Force (IETF). Note that other groups may also distribute
- working documents as Internet-Drafts. The list of current Internet-
- Drafts is at https://datatracker.ietf.org/drafts/current/.
- Internet-Drafts are draft documents valid for a maximum of six months
- and may be updated, replaced, or obsoleted by other documents at any
-Barnes, et al. Expires October 26, 2018 [Page 1]
-
-Internet-Draft ACME April 2018
- time. It is inappropriate to use Internet-Drafts as reference
- material or to cite them other than as "work in progress."
- This Internet-Draft will expire on October 26, 2018.
+
+
+Barnes, et al. Standards Track [Page 1]
+
+RFC 8555 ACME March 2019
+
Copyright Notice
- Copyright (c) 2018 IETF Trust and the persons identified as the
+ Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
@@ -80,127 +77,130 @@
Table of Contents
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
- 2. Deployment Model and Operator Experience . . . . . . . . . . 5
- 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6
- 4. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 7
- 5. Character Encoding . . . . . . . . . . . . . . . . . . . . . 9
- 6. Message Transport . . . . . . . . . . . . . . . . . . . . . . 9
- 6.1. HTTPS Requests . . . . . . . . . . . . . . . . . . . . . 9
- 6.2. Request Authentication . . . . . . . . . . . . . . . . . 10
- 6.3. Request URL Integrity . . . . . . . . . . . . . . . . . . 12
- 6.3.1. "url" (URL) JWS Header Parameter . . . . . . . . . . 12
- 6.4. Replay protection . . . . . . . . . . . . . . . . . . . . 12
- 6.4.1. Replay-Nonce . . . . . . . . . . . . . . . . . . . . 13
- 6.4.2. "nonce" (Nonce) JWS Header Parameter . . . . . . . . 14
- 6.5. Rate Limits . . . . . . . . . . . . . . . . . . . . . . . 14
- 6.6. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 14
- 6.6.1. Subproblems . . . . . . . . . . . . . . . . . . . . . 16
- 7. Certificate Management . . . . . . . . . . . . . . . . . . . 17
- 7.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 17
- 7.1.1. Directory . . . . . . . . . . . . . . . . . . . . . . 20
- 7.1.2. Account Objects . . . . . . . . . . . . . . . . . . . 22
- 7.1.3. Order Objects . . . . . . . . . . . . . . . . . . . . 23
- 7.1.4. Authorization Objects . . . . . . . . . . . . . . . . 26
- 7.1.5. Challenge Objects . . . . . . . . . . . . . . . . . . 27
- 7.1.6. Status Changes . . . . . . . . . . . . . . . . . . . 27
- 7.2. Getting a Nonce . . . . . . . . . . . . . . . . . . . . . 30
- 7.3. Account Creation . . . . . . . . . . . . . . . . . . . . 31
-
-
-
-Barnes, et al. Expires October 26, 2018 [Page 2]
-
-Internet-Draft ACME April 2018
-
-
- 7.3.1. Finding an Account URL Given a Key . . . . . . . . . 33
- 7.3.2. Account Update . . . . . . . . . . . . . . . . . . . 33
- 7.3.3. Account Information . . . . . . . . . . . . . . . . . 34
- 7.3.4. Changes of Terms of Service . . . . . . . . . . . . . 34
- 7.3.5. External Account Binding . . . . . . . . . . . . . . 35
- 7.3.6. Account Key Roll-over . . . . . . . . . . . . . . . . 37
- 7.3.7. Account Deactivation . . . . . . . . . . . . . . . . 39
- 7.4. Applying for Certificate Issuance . . . . . . . . . . . . 40
- 7.4.1. Pre-Authorization . . . . . . . . . . . . . . . . . . 44
- 7.4.2. Downloading the Certificate . . . . . . . . . . . . . 46
- 7.5. Identifier Authorization . . . . . . . . . . . . . . . . 47
- 7.5.1. Responding to Challenges . . . . . . . . . . . . . . 48
- 7.5.2. Deactivating an Authorization . . . . . . . . . . . . 50
- 7.6. Certificate Revocation . . . . . . . . . . . . . . . . . 51
- 8. Identifier Validation Challenges . . . . . . . . . . . . . . 53
- 8.1. Key Authorizations . . . . . . . . . . . . . . . . . . . 55
- 8.2. Retrying Challenges . . . . . . . . . . . . . . . . . . . 55
- 8.3. HTTP Challenge . . . . . . . . . . . . . . . . . . . . . 56
- 8.4. DNS Challenge . . . . . . . . . . . . . . . . . . . . . . 58
- 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60
- 9.1. MIME Type: application/pem-certificate-chain . . . . . . 60
- 9.2. Well-Known URI for the HTTP Challenge . . . . . . . . . . 61
- 9.3. Replay-Nonce HTTP Header . . . . . . . . . . . . . . . . 61
- 9.4. "url" JWS Header Parameter . . . . . . . . . . . . . . . 61
- 9.5. "nonce" JWS Header Parameter . . . . . . . . . . . . . . 62
- 9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) . . . . 62
- 9.7. New Registries . . . . . . . . . . . . . . . . . . . . . 62
- 9.7.1. Fields in Account Objects . . . . . . . . . . . . . . 63
- 9.7.2. Fields in Order Objects . . . . . . . . . . . . . . . 64
- 9.7.3. Fields in Authorization Objects . . . . . . . . . . . 65
- 9.7.4. Error Types . . . . . . . . . . . . . . . . . . . . . 66
- 9.7.5. Resource Types . . . . . . . . . . . . . . . . . . . 66
- 9.7.6. Fields in the "meta" Object within a Directory Object 67
- 9.7.7. Identifier Types . . . . . . . . . . . . . . . . . . 68
- 9.7.8. Validation Methods . . . . . . . . . . . . . . . . . 68
- 10. Security Considerations . . . . . . . . . . . . . . . . . . . 69
- 10.1. Threat Model . . . . . . . . . . . . . . . . . . . . . . 70
- 10.2. Integrity of Authorizations . . . . . . . . . . . . . . 71
- 10.3. Denial-of-Service Considerations . . . . . . . . . . . . 73
- 10.4. Server-Side Request Forgery . . . . . . . . . . . . . . 74
- 10.5. CA Policy Considerations . . . . . . . . . . . . . . . . 74
- 11. Operational Considerations . . . . . . . . . . . . . . . . . 75
- 11.1. Key Selection . . . . . . . . . . . . . . . . . . . . . 75
- 11.2. DNS security . . . . . . . . . . . . . . . . . . . . . . 76
- 11.3. Token Entropy . . . . . . . . . . . . . . . . . . . . . 76
- 11.4. Malformed Certificate Chains . . . . . . . . . . . . . . 77
- 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 77
- 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 78
-
-
-
-Barnes, et al. Expires October 26, 2018 [Page 3]
-
-Internet-Draft ACME April 2018
-
-
- 13.1. Normative References . . . . . . . . . . . . . . . . . . 78
- 13.2. Informative References . . . . . . . . . . . . . . . . . 80
- 13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 81
- Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82
+ 1. Introduction ....................................................4
+ 2. Deployment Model and Operator Experience ........................5
+ 3. Terminology .....................................................7
+ 4. Protocol Overview ...............................................7
+ 5. Character Encoding .............................................10
+ 6. Message Transport ..............................................10
+ 6.1. HTTPS Requests ............................................10
+ 6.2. Request Authentication ....................................11
+ 6.3. GET and POST-as-GET Requests ..............................13
+ 6.4. Request URL Integrity .....................................13
+ 6.4.1. "url" (URL) JWS Header Parameter ...................14
+ 6.5. Replay Protection .........................................14
+ 6.5.1. Replay-Nonce .......................................15
+ 6.5.2. "nonce" (Nonce) JWS Header Parameter ...............16
+ 6.6. Rate Limits ...............................................16
+ 6.7. Errors ....................................................16
+ 6.7.1. Subproblems ........................................18
+ 7. Certificate Management .........................................20
+ 7.1. Resources .................................................20
+ 7.1.1. Directory ..........................................23
+ 7.1.2. Account Objects ....................................24
+ 7.1.3. Order Objects ......................................26
+ 7.1.4. Authorization Objects ..............................28
+ 7.1.5. Challenge Objects ..................................30
+ 7.1.6. Status Changes .....................................30
+ 7.2. Getting a Nonce ...........................................34
+ 7.3. Account Management ........................................34
+ 7.3.1. Finding an Account URL Given a Key .................36
+ 7.3.2. Account Update .....................................37
+ 7.3.3. Changes of Terms of Service ........................38
+ 7.3.4. External Account Binding ...........................38
+
+
+
+Barnes, et al. Standards Track [Page 2]
+
+RFC 8555 ACME March 2019
+
+
+ 7.3.5. Account Key Rollover ...............................40
+ 7.3.6. Account Deactivation ...............................43
+ 7.4. Applying for Certificate Issuance .........................44
+ 7.4.1. Pre-authorization ..................................49
+ 7.4.2. Downloading the Certificate ........................51
+ 7.5. Identifier Authorization ..................................53
+ 7.5.1. Responding to Challenges ...........................54
+ 7.5.2. Deactivating an Authorization ......................57
+ 7.6. Certificate Revocation ....................................58
+ 8. Identifier Validation Challenges ...............................60
+ 8.1. Key Authorizations ........................................62
+ 8.2. Retrying Challenges .......................................63
+ 8.3. HTTP Challenge ............................................63
+ 8.4. DNS Challenge .............................................66
+ 9. IANA Considerations ............................................68
+ 9.1. Media Type: application/pem-certificate-chain .............68
+ 9.2. Well-Known URI for the HTTP Challenge .....................69
+ 9.3. Replay-Nonce HTTP Header ..................................69
+ 9.4. "url" JWS Header Parameter ................................70
+ 9.5. "nonce" JWS Header Parameter ..............................70
+ 9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) .........70
+ 9.7. New Registries ............................................71
+ 9.7.1. Fields in Account Objects ..........................71
+ 9.7.2. Fields in Order Objects ............................72
+ 9.7.3. Fields in Authorization Objects ....................73
+ 9.7.4. Error Types ........................................74
+ 9.7.5. Resource Types .....................................74
+ 9.7.6. Fields in the "meta" Object within a
+ Directory Object ...................................75
+ 9.7.7. Identifier Types ...................................76
+ 9.7.8. Validation Methods .................................76
+ 10. Security Considerations .......................................78
+ 10.1. Threat Model .............................................78
+ 10.2. Integrity of Authorizations ..............................80
+ 10.3. Denial-of-Service Considerations .........................83
+ 10.4. Server-Side Request Forgery ..............................84
+ 10.5. CA Policy Considerations .................................84
+ 11. Operational Considerations ....................................86
+ 11.1. Key Selection ............................................86
+ 11.2. DNS Security .............................................87
+ 11.3. Token Entropy ............................................88
+ 11.4. Malformed Certificate Chains .............................88
+ 12. References ....................................................88
+ 12.1. Normative References .....................................88
+ 12.2. Informative References ...................................92
+ Acknowledgements ..................................................94
+ Authors' Addresses ................................................95
+
+
+
+
+Barnes, et al. Standards Track [Page 3]
+
+RFC 8555 ACME March 2019
+
1. Introduction
Certificates [RFC5280] in the Web PKI are most commonly used to
- authenticate domain names. Thus, certificate authorities in the Web
- PKI are trusted to verify that an applicant for a certificate
+ authenticate domain names. Thus, certification authorities (CAs) in
+ the Web PKI are trusted to verify that an applicant for a certificate
legitimately represents the domain name(s) in the certificate.
Different types of certificates reflect different kinds of CA
verification of information about the certificate subject. "Domain
- Validation" (DV) certificates are by far the most common type. For
- DV validation, the CA merely verifies that the requester has
- effective control of the web server and/or DNS server for the domain,
- but does not explicitly attempt to verify their real-world identity.
- (This is as opposed to "Organization Validation" (OV) and "Extended
- Validation" (EV) certificates, where the process is intended to also
- verify the real-world identity of the requester.)
-
- Existing Web PKI certificate authorities tend to use a set of ad hoc
- protocols for certificate issuance and identity verification. In the
- case of DV certificates, a typical user experience is something like:
+ Validation" (DV) certificates are by far the most common type. The
+ only validation the CA is required to perform in the DV issuance
+ process is to verify that the requester has effective control of the
+ domain [CABFBR]. The CA is not required to attempt to verify the
+ requester's real-world identity. (This is as opposed to
+ "Organization Validation" (OV) and "Extended Validation" (EV)
+ certificates, where the process is intended to also verify the real-
+ world identity of the requester.)
+
+ Existing Web PKI certification authorities tend to use a set of ad
+ hoc protocols for certificate issuance and identity verification. In
+ the case of DV certificates, a typical user experience is something
+ like:
o Generate a PKCS#10 [RFC2986] Certificate Signing Request (CSR).
- o Cut-and-paste the CSR into a CA web page.
+ o Cut and paste the CSR into a CA's web page.
- o Prove ownership of the domain by one of the following methods:
+ o Prove ownership of the domain(s) in the CSR by one of the
+ following methods:
* Put a CA-provided challenge at a specific place on the web
server.
@@ -208,78 +208,80 @@
* Put a CA-provided challenge in a DNS record corresponding to
the target domain.
- * Receive a CA-provided challenge at a (hopefully) administrator-
- controlled email address corresponding to the domain and then
- respond to it on the CA's web page.
+ * Receive a CA-provided challenge at (hopefully) an
+ administrator-controlled email address corresponding to the
+ domain, and then respond to it on the CA's web page.
- o Download the issued certificate and install it on their Web
+ o Download the issued certificate and install it on the user's Web
Server.
With the exception of the CSR itself and the certificates that are
issued, these are all completely ad hoc procedures and are
accomplished by getting the human user to follow interactive natural-
+ language instructions from the CA rather than by machine-implemented
+ published protocols. In many cases, the instructions are difficult
-Barnes, et al. Expires October 26, 2018 [Page 4]
+Barnes, et al. Standards Track [Page 4]
-Internet-Draft ACME April 2018
+RFC 8555 ACME March 2019
- language instructions from the CA rather than by machine-implemented
- published protocols. In many cases, the instructions are difficult
- to follow and cause significant confusion. Informal usability tests
- by the authors indicate that webmasters often need 1-3 hours to
- obtain and install a certificate for a domain. Even in the best
- case, the lack of published, standardized mechanisms presents an
- obstacle to the wide deployment of HTTPS and other PKIX-dependent
- systems because it inhibits mechanization of tasks related to
- certificate issuance, deployment, and revocation.
+ to follow and cause significant frustration and confusion. Informal
+ usability tests by the authors indicate that webmasters often need
+ 1-3 hours to obtain and install a certificate for a domain. Even in
+ the best case, the lack of published, standardized mechanisms
+ presents an obstacle to the wide deployment of HTTPS and other PKIX-
+ dependent systems because it inhibits mechanization of tasks related
+ to certificate issuance, deployment, and revocation.
This document describes an extensible framework for automating the
issuance and domain validation procedure, thereby allowing servers
- and infrastructural software to obtain certificates without user
+ and infrastructure software to obtain certificates without user
interaction. Use of this protocol should radically simplify the
- deployment of HTTPS and the practicality of PKIX authentication for
- other protocols based on Transport Layer Security (TLS) [RFC5246].
+ deployment of HTTPS and the practicality of PKIX-based authentication
+ for other protocols based on Transport Layer Security (TLS)
+ [RFC8446].
It should be noted that while the focus of this document is on
validating domain names for purposes of issuing certificates in the
Web PKI, ACME supports extensions for uses with other identifiers in
other PKI contexts. For example, as of this writing, there is
- ongoing work to use ACME for issuance of WebPKI certificates
- attesting to IP addresses [I-D.ietf-acme-ip] and STIR certificates
- attesting to telephone numbers [I-D.ietf-acme-telephone].
+ ongoing work to use ACME for issuance of Web PKI certificates
+ attesting to IP addresses [ACME-IP] and Secure Telephone Identity
+ Revisited (STIR) certificates attesting to telephone numbers
+ [ACME-TELEPHONE].
ACME can also be used to automate some aspects of certificate
management even where non-automated processes are still needed. For
- example, the external account binding feature (see Section 7.3.5) can
+ example, the external account binding feature (see Section 7.3.4) can
allow an ACME account to use authorizations that have been granted to
an external, non-ACME account. This allows ACME to address issuance
scenarios that cannot yet be fully automated, such as the issuance of
- Extended Validation certificates.
+ "Extended Validation" certificates.
2. Deployment Model and Operator Experience
The guiding use case for ACME is obtaining certificates for websites
- (HTTPS [RFC2818]). In this case, the user's web server is intended
- to speak for one or more domains, and the process of certificate
- issuance is intended to verify that this web server actually speaks
- for the domain(s).
+ (HTTPS [RFC2818]). In this case, a web server is intended to speak
+ for one or more domains, and the process of certificate issuance is
+ intended to verify that this web server actually speaks for the
+ domain(s).
DV certificate validation commonly checks claims about properties
- related to control of a domain name - properties that can be observed
- by the certificate issuer in an interactive process that can be
- conducted purely online. That means that under typical
+ related to control of a domain name -- properties that can be
+ observed by the certificate issuer in an interactive process that can
+ be conducted purely online. That means that under typical
circumstances, all steps in the request, verification, and issuance
process can be represented and performed by Internet protocols with
no out-of-band human intervention.
-Barnes, et al. Expires October 26, 2018 [Page 5]
+Barnes, et al. Standards Track [Page 5]
-Internet-Draft ACME April 2018
+RFC 8555 ACME March 2019
Prior to ACME, when deploying an HTTPS server, a server operator
@@ -302,17 +304,20 @@
that it issue a certificate for the intended domain name(s).
o The CA verifies that the client controls the requested domain
- name(s) by having the ACME client perform some action related to
- the domain name(s).
+ name(s) by having the ACME client perform some action(s) that can
+ only be done with control of the domain name(s). For example, the
+ CA might require a client requesting example.com to provision a
+ DNS record under example.com or an HTTP resource under
+ http://example.com.
o Once the CA is satisfied, it issues the certificate and the ACME
client automatically downloads and installs it, potentially
notifying the operator via email, SMS, etc.
o The ACME client periodically contacts the CA to get updated
- certificates, stapled OCSP responses, or whatever else would be
- required to keep the web server functional and its credentials up-
- to-date.
+ certificates, stapled Online Certificate Status Protocol (OCSP)
+ responses [RFC6960], or whatever else would be required to keep
+ the web server functional and its credentials up to date.
In this way, it would be nearly as easy to deploy with a CA-issued
certificate as with a self-signed certificate. Furthermore, the
@@ -322,59 +327,88 @@
as they are issued, sparing the human administrator from much of the
time-consuming work described in the previous section.
-3. Terminology
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in RFC 2119 [RFC2119].
- The two main roles in ACME are "client" and "server". The ACME
- client uses the protocol to request certificate management actions,
-Barnes, et al. Expires October 26, 2018 [Page 6]
+
+
+
+Barnes, et al. Standards Track [Page 6]
-Internet-Draft ACME April 2018
+RFC 8555 ACME March 2019
+
+3. Terminology
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+ "OPTIONAL" in this document are to be interpreted as described in
+ BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
+ capitals, as shown here.
+ The two main roles in ACME are "client" and "server". The ACME
+ client uses the protocol to request certificate management actions,
such as issuance or revocation. An ACME client may run on a web
- server, mail server, or some other server system which requires valid
- TLS certificates. Or, it may run on a separate server that does not
- consume the certificate, but is authorized to respond to a CA-
+ server, mail server, or some other server system that requires valid
+ X.509 certificates. Or, it may run on a separate server that does
+ not consume the certificate but is authorized to respond to a CA-
provided challenge. The ACME server runs at a certification
- authority, and responds to client requests, performing the requested
+ authority and responds to client requests, performing the requested
actions if the client is authorized.
- An ACME client is represented by an "account key pair". The client
- uses the private key of this key pair to sign all messages sent to
- the server. The server uses the public key to verify the
- authenticity and integrity of messages from the client.
+ An ACME client authenticates to the server by means of an "account
+ key pair". The client uses the private key of this key pair to sign
+ all messages sent to the server. The server uses the public key to
+ verify the authenticity and integrity of messages from the client.
4. Protocol Overview
ACME allows a client to request certificate management actions using
- a set of JavaScript Object Notation (JSON) messages carried over
- HTTPS. Issuance using ACME resembles a traditional CA's issuance
- process, in which a user creates an account, requests a certificate,
- and proves control of the domain(s) in that certificate in order for
- the CA to sign the requested certificate.
+ a set of JavaScript Object Notation (JSON) messages [RFC8259] carried
+ over HTTPS [RFC2818]. Issuance using ACME resembles a traditional
+ CA's issuance process, in which a user creates an account, requests a
+ certificate, and proves control of the domain(s) in that certificate
+ in order for the CA to issue the requested certificate.
The first phase of ACME is for the client to request an account with
the ACME server. The client generates an asymmetric key pair and
requests a new account, optionally providing contact information,
- agreeing to terms of service, and/or associating the account with an
- existing account in another system. The creation request is signed
- with the generated private key to prove that the client controls it.
-
- Client Server
-
- Contact Information
- ToS Agreement
- Additional Data
+ agreeing to terms of service (ToS), and/or associating the account
+ with an existing account in another system. The creation request is
+ signed with the generated private key to prove that the client
+ controls it.
+
+
+
+
+
+
+
+
+
+
+
+
+Barnes, et al. Standards Track [Page 7]
+
+RFC 8555 ACME March 2019
+
+
+ Client Server
+
+ [Contact Information]
+ [ToS Agreement]
+ [Additional Data]
Signature ------->
+ Account URL
+ <------- Account Object
+
- <------- Account
+ [] Information covered by request signatures
+
+ Account Creation
Once an account is registered, there are four major steps the client
needs to take to get a certificate:
@@ -387,13 +421,6 @@
4. Await issuance and download the issued certificate
-
-
-Barnes, et al. Expires October 26, 2018 [Page 7]
-
-Internet-Draft ACME April 2018
-
-
The client's order for a certificate describes the desired
identifiers plus a few additional fields that capture semantics that
are not supported in the CSR format. If the server is willing to
@@ -417,61 +444,80 @@
server will issue the requested certificate and make it available to
the client.
+
+
+
+Barnes, et al. Standards Track [Page 8]
+
+RFC 8555 ACME March 2019
+
+
Client Server
- Order
+ [Order]
Signature ------->
<------- Required Authorizations
- Responses
+ [Responses]
Signature ------->
<~~~~~~~~Validation~~~~~~~~>
- CSR
+ [CSR]
Signature ------->
+ <------- Acknowledgement
<~~~~~~Await issuance~~~~~~>
- <------- Certificate
-
- To revoke a certificate, the client sends a signed revocation request
- indicating the certificate to be revoked:
-
-
-
-
-
-
+ [POST-as-GET request]
+ Signature ------->
+ <------- Certificate
+ [] Information covered by request signatures
-Barnes, et al. Expires October 26, 2018 [Page 8]
-
-Internet-Draft ACME April 2018
+ Certificate Issuance
+ To revoke a certificate, the client sends a signed revocation request
+ indicating the certificate to be revoked:
Client Server
- Revocation request
+ [Revocation request]
Signature -------->
<-------- Result
+ [] Information covered by request signatures
+
+ Certificate Revocation
+
Note that while ACME is defined with enough flexibility to handle
different types of identifiers in principle, the primary use case
addressed by this document is the case where domain names are used as
identifiers. For example, all of the identifier validation
- challenges described in Section 8 below address validation of domain
- names. The use of ACME for other identifiers will require further
+ challenges described in Section 8 address validation of domain names.
+ The use of ACME for other identifiers will require further
specification in order to describe how these identifiers are encoded
in the protocol and what types of validation challenges the server
might require.
+
+
+Barnes, et al. Standards Track [Page 9]
+
+RFC 8555 ACME March 2019
+
+
5. Character Encoding
All requests and responses sent via HTTP by ACME clients, ACME
servers, and validation servers as well as any inputs for digest
- computations MUST be encoded using the UTF-8 [RFC3629] character set.
+ computations MUST be encoded using the UTF-8 character set [RFC3629].
+ Note that identifiers that appear in certificates may have their own
+ encoding considerations (e.g., DNS names containing non-ASCII
+ characters are expressed as A-labels rather than U-labels). Any such
+ encoding considerations are to be applied prior to the aforementioned
+ UTF-8 encoding.
6. Message Transport
@@ -486,47 +532,52 @@
6.1. HTTPS Requests
Each ACME function is accomplished by the client sending a sequence
- of HTTPS requests to the server, carrying JSON messages
- [RFC2818][RFC7159]. Use of HTTPS is REQUIRED. Each subsection of
- Section 7 below describes the message formats used by the function
- and the order in which messages are sent.
+ of HTTPS requests to the server [RFC2818], carrying JSON messages
+ [RFC8259]. Use of HTTPS is REQUIRED. Each subsection of Section 7
+ below describes the message formats used by the function and the
+ order in which messages are sent.
In most HTTPS transactions used by ACME, the ACME client is the HTTPS
client and the ACME server is the HTTPS server. The ACME server acts
- as an HTTP and HTTPS client when validating challenges via HTTP.
+ as a client when validating challenges: an HTTP client when
+ validating an 'http-01' challenge, a DNS client with 'dns-01', etc.
ACME servers SHOULD follow the recommendations of [RFC7525] when
configuring their TLS implementations. ACME servers that support TLS
1.3 MAY allow clients to send early data (0-RTT). This is safe
+ because the ACME protocol itself includes anti-replay protections
+ (see Section 6.5) in all cases where they are required. For this
+ reason, there are no restrictions on what ACME data can be carried in
+ 0-RTT.
+ ACME clients MUST send a User-Agent header field, in accordance with
+ [RFC7231]. This header field SHOULD include the name and version of
+ the ACME software in addition to the name and version of the
+ underlying HTTP client software.
-Barnes, et al. Expires October 26, 2018 [Page 9]
-
-Internet-Draft ACME April 2018
- because the ACME protocol itself includes anti-replay protections
- (see Section 6.4).
- ACME clients MUST send a User-Agent header, in accordance with
- [RFC7231]. This header SHOULD include the name and version of the
- ACME software in addition to the name and version of the underlying
- HTTP client software.
+Barnes, et al. Standards Track [Page 10]
+
+RFC 8555 ACME March 2019
+
- ACME clients SHOULD send an Accept-Language header in accordance with
- [RFC7231] to enable localization of error messages.
+ ACME clients SHOULD send an Accept-Language header field in
+ accordance with [RFC7231] to enable localization of error messages.
ACME servers that are intended to be generally accessible need to use
Cross-Origin Resource Sharing (CORS) in order to be accessible from
- browser-based clients [W3C.CR-cors-20130129]. Such servers SHOULD
+ browser-based clients [W3C.REC-cors-20140116]. Such servers SHOULD
set the Access-Control-Allow-Origin header field to the value "*".
Binary fields in the JSON objects used by ACME are encoded using
- base64url encoding described in [RFC4648] Section 5, according to the
- profile specified in JSON Web Signature [RFC7515] Section 2. This
- encoding uses a URL safe character set. Trailing '=' characters MUST
- be stripped.
+ base64url encoding described in Section 5 of [RFC4648] according to
+ the profile specified in JSON Web Signature in Section 2 of
+ [RFC7515]. This encoding uses a URL safe character set. Trailing
+ '=' characters MUST be stripped. Encoded values that include
+ trailing '=' characters MUST be rejected as improperly encoded.
6.2. Request Authentication
@@ -536,103 +587,152 @@
MUST verify the JWS before processing the request. Encapsulating
request bodies in JWS provides authentication of requests.
- JWS objects sent in ACME requests MUST meet the following additional
- criteria:
+ A JWS object sent as the body of an ACME request MUST meet the
+ following additional criteria:
o The JWS MUST be in the Flattened JSON Serialization [RFC7515]
- o The JWS MUST NOT have the value "none" in its "alg" field
-
o The JWS MUST NOT have multiple signatures
o The JWS Unencoded Payload Option [RFC7797] MUST NOT be used
o The JWS Unprotected Header [RFC7515] MUST NOT be used
- o The JWS MUST NOT have a Message Authentication Code (MAC)-based
- algorithm in its "alg" field
-
o The JWS Payload MUST NOT be detached
+ o The JWS Protected Header MUST include the following fields:
+ * "alg" (Algorithm)
+ + This field MUST NOT contain "none" or a Message
+ Authentication Code (MAC) algorithm (e.g. one in which the
+ algorithm registry description mentions MAC/HMAC).
-Barnes, et al. Expires October 26, 2018 [Page 10]
-
-Internet-Draft ACME April 2018
+ * "nonce" (defined in Section 6.5)
+ * "url" (defined in Section 6.4)
- o The JWS Protected Header MUST include the following fields:
- * "alg" (Algorithm)
- * "jwk" (JSON Web Key, for all requests not signed using an
- existing account, e.g. newAccount)
- * "kid" (Key ID, for all requests signed using an existing
- account)
+Barnes, et al. Standards Track [Page 11]
+
+RFC 8555 ACME March 2019
+
- * "nonce" (defined in Section 6.4 below)
+ * Either "jwk" (JSON Web Key) or "kid" (Key ID) as specified
+ below
- * "url" (defined in Section 6.3 below)
+ An ACME server MUST implement the "ES256" signature algorithm
+ [RFC7518] and SHOULD implement the "EdDSA" signature algorithm using
+ the "Ed25519" variant (indicated by "crv") [RFC8037].
The "jwk" and "kid" fields are mutually exclusive. Servers MUST
reject requests that contain both.
For newAccount requests, and for revokeCert requests authenticated by
- certificate key, there MUST be a "jwk" field. This field MUST
+ a certificate key, there MUST be a "jwk" field. This field MUST
contain the public key corresponding to the private key used to sign
the JWS.
For all other requests, the request is signed using an existing
- account and there MUST be a "kid" field. This field MUST contain the
- account URL received by POSTing to the newAccount resource.
-
- Note that authentication via signed JWS request bodies implies that
- GET requests are not authenticated. Servers MUST NOT respond to GET
- requests for resources that might be considered sensitive. Account
- resources are the only sensitive resources defined in this
- specification.
+ account, and there MUST be a "kid" field. This field MUST contain
+ the account URL received by POSTing to the newAccount resource.
If the client sends a JWS signed with an algorithm that the server
does not support, then the server MUST return an error with status
code 400 (Bad Request) and type
"urn:ietf:params:acme:error:badSignatureAlgorithm". The problem
document returned with the error MUST include an "algorithms" field
- with an array of supported "alg" values.
+ with an array of supported "alg" values. See Section 6.7 for more
+ details on the structure of error responses.
- Because client requests in ACME carry JWS objects in the Flattened
- JSON Serialization, they must have the "Content-Type" header field
- set to "application/jose+json". If a request does not meet this
- requirement, then the server MUST return a response with status code
- 415 (Unsupported Media Type).
+ If the server supports the signature algorithm "alg" but either does
+ not support or chooses to reject the public key "jwk", then the
+ server MUST return an error with status code 400 (Bad Request) and
+ type "urn:ietf:params:acme:error:badPublicKey". The problem document
+ detail SHOULD describe the reason for rejecting the public key; some
+ example reasons are:
+
+ o "alg" is "RS256" but the modulus "n" is too small (e.g., 512-bit)
+
+ o "alg" is "ES256" but "jwk" does not contain a valid P-256 public
+ key
+ o "alg" is "EdDSA" and "crv" is "Ed448", but the server only
+ supports "EdDSA" with "Ed25519"
+ o the corresponding private key is known to have been compromised
-Barnes, et al. Expires October 26, 2018 [Page 11]
+
+
+
+Barnes, et al. Standards Track [Page 12]
-Internet-Draft ACME April 2018
+RFC 8555 ACME March 2019
-6.3. Request URL Integrity
+ Because client requests in ACME carry JWS objects in the Flattened
+ JSON Serialization, they must have the Content-Type header field set
+ to "application/jose+json". If a request does not meet this
+ requirement, then the server MUST return a response with status code
+ 415 (Unsupported Media Type).
+
+6.3. GET and POST-as-GET Requests
+
+ Note that authentication via signed JWS request bodies implies that
+ requests without an entity body are not authenticated, in particular
+ GET requests. Except for the cases described in this section, if the
+ server receives a GET request, it MUST return an error with status
+ code 405 (Method Not Allowed) and type "malformed".
+
+ If a client wishes to fetch a resource from the server (which would
+ otherwise be done with a GET), then it MUST send a POST request with
+ a JWS body as described above, where the payload of the JWS is a
+ zero-length octet string. In other words, the "payload" field of the
+ JWS object MUST be present and set to the empty string ("").
+
+ We will refer to these as "POST-as-GET" requests. On receiving a
+ request with a zero-length (and thus non-JSON) payload, the server
+ MUST authenticate the sender and verify any access control rules.
+ Otherwise, the server MUST treat this request as having the same
+ semantics as a GET request for the same resource.
+
+ The server MUST allow GET requests for the directory and newNonce
+ resources (see Section 7.1), in addition to POST-as-GET requests for
+ these resources. This enables clients to bootstrap into the ACME
+ authentication system.
+
+6.4. Request URL Integrity
It is common in deployment for the entity terminating TLS for HTTPS
to be different from the entity operating the logical HTTPS server,
with a "request routing" layer in the middle. For example, an ACME
CA might have a content delivery network terminate TLS connections
from clients so that it can inspect client requests for denial-of-
- service protection.
+ service (DoS) protection.
These intermediaries can also change values in the request that are
- not signed in the HTTPS request, e.g., the request URL and headers.
- ACME uses JWS to provide an integrity mechanism, which protects
- against an intermediary changing the request URL to another ACME URL.
+ not signed in the HTTPS request, e.g., the request URL and header
+ fields. ACME uses JWS to provide an integrity mechanism, which
+ protects against an intermediary changing the request URL to another
+ ACME URL.
+
+
+
+
- As noted in Section 6.2 above, all ACME request objects carry a "url"
+
+Barnes, et al. Standards Track [Page 13]
+
+RFC 8555 ACME March 2019
+
+
+ As noted in Section 6.2, all ACME request objects carry a "url"
header parameter in their protected header. This header parameter
encodes the URL to which the client is directing the request. On
receiving such an object in an HTTP request, the server MUST compare
@@ -640,80 +740,95 @@
match, then the server MUST reject the request as unauthorized.
Except for the directory resource, all ACME resources are addressed
- with URLs provided to the client by the server. In requests sent to
- these resources, the client MUST set the "url" header parameter to
- the exact string provided by the server (rather than performing any
- re-encoding on the URL). The server SHOULD perform the corresponding
- string equality check, configuring each resource with the URL string