idnits 2.17.1 draft-aaron-acme-ari-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (22 September 2021) is 947 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACME Working Group A. Gable 3 Internet-Draft Internet Security Research Group 4 Intended status: Standards Track 22 September 2021 5 Expires: 26 March 2022 7 Automated Certificate Management Environment (ACME) Renewal Information 8 (ARI) Extension 9 draft-aaron-acme-ari-00 11 Abstract 13 This document specifies how an ACME server may provide hints to ACME 14 clients as to when they should attempt to renew their certificates. 15 This allows servers to mitigate load spikes, and ensures clients do 16 not make false assumptions about appropriate certificate renewal 17 periods. 19 Discussion Venues 21 This note is to be removed before publishing as an RFC. 23 Discussion of this document takes place on the Automated Certificate 24 Management Environment Working Group mailing list (acme@ietf.org), 25 which is archived at https://mailarchive.ietf.org/arch/browse/acme/. 27 Source for this draft and an issue tracker can be found at 28 https://github.com/aarongable/draft-acme-ari. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on 26 March 2022. 47 Copyright Notice 49 Copyright (c) 2021 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 54 license-info) in effect on the date of publication of this document. 55 Please review these documents carefully, as they describe your rights 56 and restrictions with respect to this document. Code Components 57 extracted from this document must include Simplified BSD License text 58 as described in Section 4.e of the Trust Legal Provisions and are 59 provided without warranty as described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 64 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3 65 3. Extensions to the ACME Protocol: The "order" Resource . . . . 3 66 4. Extensions to the ACME Protocol: The "renewalInfo" 67 Resource . . . . . . . . . . . . . . . . . . . . . . . . 3 68 5. Security Considerations . . . . . . . . . . . . . . . . . . . 4 69 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 70 6.1. New Registries . . . . . . . . . . . . . . . . . . . . . 5 71 6.2. ACME Resource Type . . . . . . . . . . . . . . . . . . . 5 72 6.3. ACME Order Object Fields . . . . . . . . . . . . . . . . 5 73 6.4. ACME Renewal Info Object Fields . . . . . . . . . . . . . 5 74 7. Normative References . . . . . . . . . . . . . . . . . . . . 6 75 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 6 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6 78 1. Introduction 80 Most ACME clients today choose when to attempt to renew a certificate 81 in one of three ways. They may be configured to renew at a specific 82 interval (e.g. via "cron"); they may parse the issued certificate to 83 determine its expiration date and renew a specific amount of time 84 before then; or they may parse the issued certificate and renew when 85 some percentage of its validity period has passed. The first two 86 techniques create significant barriers against the issuing CA 87 changing certificate lifetimes. All three techniques lead to load 88 clustering for the issuing CA. 90 Being able to indicate to the client a period in which the issuing CA 91 suggests renewal would allow both dynamic changes to the certificate 92 validity period and proactive smearing of load. This document 93 specifies a mechanism by which ACME servers may provide suggested 94 renewal windows to ACME clients. 96 2. Conventions and Definitions 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 100 "OPTIONAL" in this document are to be interpreted as described in BCP 101 14 [RFC2119] [RFC8174] when, and only when, they appear in all 102 capitals, as shown here. 104 3. Extensions to the ACME Protocol: The "order" Resource 106 An ACME server which wishes to provide renewal information MUST 107 include a new field, "renewalInfo", in finalized Order objects. 109 renewalInfo (optional, string): A URL for renewal information for the 110 certificate that has been issued in response to this order. 112 HTTP/1.1 200 OK 113 Content-Type: application/json 115 { 116 "status": "valid", 117 "expires": "2021-01-20T14:09:07.99Z", 119 "identifiers": [ 120 { "type": "dns", "value": "www.example.org" }, 121 { "type": "dns", "value": "example.org" } 122 ], 124 "notBefore": "2021-01-01T00:00:00Z", 125 "notAfter": "2021-01-08T00:00:00Z", 127 "authorizations": [ 128 "https://example.com/acme/authz/PAniVnsZcis", 129 "https://example.com/acme/authz/r4HqLzrSrpI" 130 ], 132 "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize", 133 "certificate": "https://example.com/acme/cert/mAt3xBGaobw", 134 "renewalInfo": "https://example.com/acme/renewal/eXoM9UwLgbL" 135 } 137 Conforming clients SHOULD store the "renewalInfo" URL locally so that 138 they can poll it at any time during the lifetime of the certificate. 140 4. Extensions to the ACME Protocol: The "renewalInfo" Resource 142 We define a new resource type, the "renewalInfo" resource, as part of 143 the ACME protocol. 145 The structure of an ACME renewalInfo resource is as follows: 147 suggestedWindow (object, required): A JSON object with two keys, 148 "start" and "end", whose values are timestamps, encoded in the format 149 specified in [RFC3339], which bound the window of time in which the 150 CA recommends renewing the certificate. 152 HTTP/1.1 200 OK 153 Content-Type: application/json 155 { 156 "suggestedWindow": { 157 "start": "2021-01-03T00:00:00Z", 158 "end": "2021-01-07T00:00:00Z" 159 } 160 } 162 Conforming servers MUST provide the renewalInfo resource via POST-as- 163 GET; they SHOULD provide it via unauthenticated GET as well. 164 Conforming clients SHOULD use unauthenticated GET to request 165 renewalInfo resources. 167 The server SHOULD include a Retry-After header indicating the polling 168 interval that the ACME server recommends. Conforming clients SHOULD 169 query the "renewalInfo" URL again after the Retry-After period has 170 passed, as the server may provide a different suggestedWindow. 172 Conforming clients SHOULD select a random time within the suggested 173 window to attempt to renew the certificate. If the selected time is 174 in the past, the client SHOULD attempt renewal immediately. 176 5. Security Considerations 178 The extensions to the ACME protocol described in this document build 179 upon the Security Considerations and threat model defined in 180 Section 10.1 of [RFC8555]. 182 This document specifies that renewalInfo resources should be exposed 183 via unauthenticated GET requests, a departure from RFC8555's 184 requirement that clients must send POST-as-GET requests to fetch 185 resources from the server. This is because the information contained 186 in renewalInfo resources is not considered confidential, and because 187 allowing renewalInfo to be easily cached is advantageous to shed load 188 from clients which do not respect the Retry-After header. 190 6. IANA Considerations 192 Draft note: The following changes to IANA registries have not yet 193 been made. 195 6.1. New Registries 197 Within the "Automated Certificate Management Environment (ACME) 198 Protocol" registry, IANA has created the new "ACME Renewal Info 199 Object Fields" registry (Section 6.4). 201 6.2. ACME Resource Type 203 Within the "Automated Certificate Management Environment (ACME) 204 Protocol" registry, the following entry has been added to the "ACME 205 Resource Types" registry. 207 +=============+=====================+============+ 208 | Field Name | Resource Type | Reference | 209 +=============+=====================+============+ 210 | renewalInfo | Renewal Info object | This draft | 211 +-------------+---------------------+------------+ 213 Table 1 215 6.3. ACME Order Object Fields 217 Within the "Automated Certificate Management Environment (ACME) 218 Protocol" registry, the following entry has been added to the "ACME 219 Order Object Fields" registry. 221 +=============+============+==============+============+ 222 | Field Name | Field Type | Configurable | Reference | 223 +=============+============+==============+============+ 224 | renewalInfo | string | false | This draft | 225 +-------------+------------+--------------+------------+ 227 Table 2 229 6.4. ACME Renewal Info Object Fields 231 The "ACME Renewal Info Object Fields" registry lists field names that 232 are defined for use in ACME renewal info objects. 234 Template: 236 * Field name: The string to be used as a field name in the JSON 237 object 239 * Field type: The type of value to be provided, e.g., string, 240 boolean, array of string 242 * Reference: Where this field is defined 244 Initial contents: 246 +=================+============+============+ 247 | Field Name | Field type | Reference | 248 +=================+============+============+ 249 | suggestedWindow | object | This draft | 250 +-----------------+------------+------------+ 252 Table 3 254 7. Normative References 256 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 257 Requirement Levels", BCP 14, RFC 2119, 258 DOI 10.17487/RFC2119, March 1997, 259 . 261 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 262 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 263 . 265 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 266 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 267 May 2017, . 269 [RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. 270 Kasten, "Automatic Certificate Management Environment 271 (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019, 272 . 274 Acknowledgments 276 TODO acknowledge. 278 Author's Address 280 A. Gable 281 Internet Security Research Group 283 Email: aaron@letsencrypt.org