Internet-Draft | ACME ARI | November 2021 |
Gable | Expires 12 May 2022 | [Page] |
This document specifies how an ACME server may provide hints to ACME clients as to when they should attempt to renew their certificates. This allows servers to mitigate load spikes, and ensures clients do not make false assumptions about appropriate certificate renewal periods.¶
Draft note: this section will be removed by the editor before final publication.¶
Let's Encrypt's Staging environment (available at [lestaging], source at [boulder]) implements this draft specification.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
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 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 12 May 2022.¶
Copyright (c) 2021 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 Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶
Most ACME [RFC8555] clients today choose when to attempt to renew a certificate in one of three ways. They may be configured to renew at a specific interval (e.g. via cron
); they may parse the issued certificate to determine its expiration date and renew a specific amount of time before then; or they may parse the issued certificate and renew when some percentage of its validity period has passed. The first two techniques create significant barriers against the issuing CA changing certificate lifetimes. All three techniques lead to load clustering for the issuing CA.¶
Being able to indicate to the client a period in which the issuing CA suggests renewal would allow both dynamic changes to the certificate validity period and proactive smearing of load. This document specifies a mechanism by which ACME servers may provide suggested renewal windows to ACME clients.¶
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.¶
An ACME server which wishes to provide renewal information MUST include a new field, renewalInfo
, in its directory object.¶
Field | URL in Value |
---|---|
renewalInfo | Renewal info |
HTTP/1.1 200 OK Content-Type: application/json { "newNonce": "https://example.com/acme/new-nonce", "newAccount": "https://example.com/acme/new-account", "newOrder": "https://example.com/acme/new-order", "newAuthz": "https://example.com/acme/new-authz", "revokeCert": "https://example.com/acme/revoke-cert", "keyChange": "https://example.com/acme/key-change", "renewalInfo": "https://example.com/acme/renewal-info", "meta": { "termsOfService": "https://example.com/acme/terms/2021-10-05", "website": "https://www.example.com/", "caaIdentities": ["example.com"], "externalAccountRequired": false } }¶
We define a new resource type, the "renewalInfo
" resource, as part of the ACME protocol. To request the suggested renewal information for a certificate, the client sends a GET request to a path under the server's renewalInfo
URL.¶
The full request URL is computed by concatenating the renewalInfo
URL from the server's directory with the following case-insensitive hex-encoded (see [RFC4648], Section [RFC4648]) elements, separated by forward slashes:¶
These are the same components that make up the CertID
sequence of an OCSPRequest
[RFC6960], Section [RFC6960], with the caveat that the hash algorithm is restricted to SHA-1, in line with [RFC5019].¶
GET https://example.com/acme/renewal-info /254581685026383D3B2D2CBECD6AD9B63DB36663 /06FE0BABD8E6746EFCC4730285F7A9487ED1344F /BCDF4596B6BDC523¶
The structure of an ACME renewalInfo
resource is as follows:¶
suggestedWindow
(object, required): A JSON object with two keys, "start
" and "end
", whose values are timestamps, encoded in the format specified in [RFC3339], which bound the window of time in which the CA recommends renewing the certificate.¶
HTTP/1.1 200 OK Content-Type: application/json Retry-After: "21600" { "suggestedWindow": { "start": "2021-01-03T00:00:00Z", "end": "2021-01-07T00:00:00Z" } }¶
The server SHOULD include a Retry-After
header indicating the polling interval that the ACME server recommends. Conforming clients SHOULD query the renewalInfo
URL again after the Retry-After
period has passed, as the server may provide a different suggestedWindow
.¶
Conforming clients MUST select a uniform random time within the suggested window to attempt to renew the certificate. If the selected time is in the past, the client SHOULD attempt renewal immediately. If the selected time is in the future, but before the next time that the client would wake up normally, the client MAY attempt renewal immediately. In all cases, renewal attempts are subject to the client's existing error backoff and retry intervals.¶
In particular, cron-based clients may find they need to increase their run frequency to check ARI more frequently. Those clients will need to store information about failures so that increasing their run frequency doesn't lead to retrying failures without proper backoff. Typical information stored should include: number of failures for a given order (defined by the set of names on the order), and time of the most recent failure.¶
If the client receives no response or a malformed response (e.g. an end
timestamp which precedes the start
timestamp), it SHOULD make its own determination of when to renew the certificate, and MAY retry the renewalInfo
request with appropriate exponential backoff behavior.¶
The extensions to the ACME protocol described in this document build upon the Security Considerations and threat model defined in [RFC8555], Section [RFC8555].¶
This document specifies that renewalInfo
resources MUST be exposed and accessed via unauthenticated GET requests, a departure from RFC8555's requirement that clients must send POST-as-GET requests to fetch resources from the server. This is because the information contained in renewalInfo
resources is not considered confidential, and because allowing renewalInfo
to be easily cached is advantageous to shed load from clients which do not respect the Retry-After header.¶
Draft note: The following changes to IANA registries have not yet been made.¶
Within the "Automated Certificate Management Environment (ACME) Protocol" registry, IANA has created the new "ACME Renewal Info Object Fields" registry (Section 6.4).¶
Within the "Automated Certificate Management Environment (ACME) Protocol" registry, the following entry has been added to the "ACME Resource Types" registry.¶
Field Name | Resource Type | Reference |
---|---|---|
renewalInfo | Renewal Info object | This draft |
The "ACME Renewal Info Object Fields" registry lists field names that are defined for use in ACME renewal info objects.¶
Template:¶
Initial contents:¶
Field Name | Field type | Reference |
---|---|---|
suggestedWindow | object | This draft |
TODO acknowledge.¶