rfc9773.original   rfc9773.txt 
ACME Working Group A. Gable Internet Engineering Task Force (IETF) A. Gable
Internet-Draft Internet Security Research Group Request for Comments: 9773 Internet Security Research Group
Intended status: Standards Track 26 February 2025 Category: Standards Track May 2025
Expires: 30 August 2025 ISSN: 2070-1721
Automated Certificate Management Environment (ACME) Renewal Information ACME Renewal Information (ARI) Extension
(ARI) Extension
draft-ietf-acme-ari-08
Abstract Abstract
This document specifies how an ACME server may provide suggestions to This document specifies how an Automated Certificate Management
ACME clients as to when they should attempt to renew their Environment (ACME) server may provide suggestions to ACME clients as
certificates. This allows servers to mitigate load spikes, and to when they should attempt to renew their certificates. This allows
ensures clients do not make false assumptions about appropriate servers to mitigate load spikes and ensures that clients do not make
certificate renewal periods. false assumptions about appropriate certificate renewal periods.
Current Implementations
Draft note: this section will be removed by the editor before final
publication.
Let's Encrypt's Boulder (https://github.com/letsencrypt/boulder)
software fully implements the server side of an earlier version of
this draft, and that implementation is deployed in both the
Production (https://acme-v02.api.letsencrypt.org/directory) and
Staging (https://acme-staging-v02.api.letsencrypt.org/directory)
environments. Google Trust Services has done the same
(https://security.googleblog.com/2023/05/google-trust-services-acme-
api_0503894189.html). Client implementations include Lego
(https://github.com/go-acme/lego), eggsampler
(https://github.com/eggsampler/acme), ACMEz
(https://github.com/mholt/acmez), and win-acme (https://github.com/
win-acme/win-acme).
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
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 This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on 30 August 2025. 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/rfc9773.
Copyright Notice Copyright Notice
Copyright (c) 2025 IETF Trust and the persons identified as the Copyright (c) 2025 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents
license-info) in effect on the date of publication of this document. (https://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Revised BSD License text as to this document. Code Components extracted from this document must
described in Section 4.e of the Trust Legal Provisions and are include Revised BSD License text as described in Section 4.e of the
provided without warranty as described in the Revised BSD License. Trust Legal Provisions and are provided without warranty as described
in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3 2. Conventions and Definitions
3. Extensions to the Directory Object . . . . . . . . . . . . . 3 3. Extensions to the Directory Object
4. Getting Renewal Information . . . . . . . . . . . . . . . . . 4 4. Getting Renewal Information
4.1. The "renewalInfo" Resource . . . . . . . . . . . . . . . 4 4.1. The "renewalInfo" Resource
4.2. RenewalInfo Objects . . . . . . . . . . . . . . . . . . . 5 4.2. RenewalInfo Objects
4.3. Schedule for checking the RenewalInfo resource . . . . . 6 4.3. Schedule for Checking the RenewalInfo Resource
4.3.1. Server choice of Retry-After . . . . . . . . . . . . 7 4.3.1. Server Choice of Retry-After
4.3.2. Client handling of Retry-After . . . . . . . . . . . 7 4.3.2. Client Handling of Retry-After
4.3.3. Error handling . . . . . . . . . . . . . . . . . . . 7 4.3.3. Error Handling
5. Extensions to the Order Object . . . . . . . . . . . . . . . 8 5. Extensions to the Order Object
6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 6. Security Considerations
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 7. IANA Considerations
7.1. ACME Resource Type . . . . . . . . . . . . . . . . . . . 10 7.1. ACME Resource Type
7.2. ACME Renewal Info Object Fields . . . . . . . . . . . . . 11 7.2. ACME Renewal Info Object Fields
7.3. ACME Order Object Fields . . . . . . . . . . . . . . . . 11 7.3. ACME Order Object Fields
7.4. ACME Error Types . . . . . . . . . . . . . . . . . . . . 12 7.4. ACME Error Types
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 8. References
8.1. Normative References . . . . . . . . . . . . . . . . . . 12 8.1. Normative References
8.2. Informative References . . . . . . . . . . . . . . . . . 13 8.2. Informative References
Appendix A. Example Certificate . . . . . . . . . . . . . . . . 13 Appendix A. Example Certificate
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 13 Acknowledgments
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 Author's Address
1. Introduction 1. Introduction
Most ACME [RFC8555] clients today choose when to attempt to renew a 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 certificate in one of three ways:
a specific interval (e.g., via cron), they may parse the issued
certificate to determine its expiration date and renew a specific 1. they may be configured to renew at a specific interval (e.g., via
amount of time before then, or they may parse the issued certificate cron),
and renew when some percentage of its validity period has passed.
The first two techniques create significant barriers against the 2. they may parse the issued certificate to determine its expiration
issuing Certification Authority (CA) changing certificate lifetimes. date and renew a specific amount of time before then, or
All three techniques may lead to load clustering for the issuing CA
due to the inability of the issuing CA to schedule renewal requests. 3. they may parse the issued certificate and renew when some
percentage of its validity period has passed.
The first two create significant barriers against the issuing
Certification Authority (CA) changing certificate lifetimes. All
three ways may lead to load clustering for the issuing CA due to its
inability to schedule renewal requests.
Allowing issuing CAs to suggest a period in which clients should Allowing issuing CAs to suggest a period in which clients should
renew their certificates enables dynamic time-based load balancing. renew their certificates enables dynamic time-based load balancing.
This allows a CA to better respond to exceptional circumstances. For This allows a CA to better respond to exceptional circumstances. For
example, a CA could suggest that clients renew prior to a mass- example:
revocation event to mitigate the impact of the revocation, or a CA
could suggest that clients renew earlier than they normally would to
reduce the size of an upcoming mass-renewal spike.
This document specifies ACME Renewal Information (ARI), a mechanism * a CA could suggest that clients renew prior to a mass-revocation
by which ACME servers may provide suggested renewal windows to ACME event to mitigate the impact of the revocation, or
clients, and by which ACME clients may inform ACME servers that they
have successfully renewed and replaced a certificate. * a CA could suggest that clients renew earlier than they normally
would to reduce the size of an upcoming mass-renewal spike.
This document specifies the ACME Renewal Information (ARI) extension,
a mechanism by which ACME servers may provide suggested renewal
windows to ACME clients and by which ACME clients may inform ACME
servers that they have successfully renewed and replaced a
certificate.
2. Conventions and Definitions 2. Conventions and Definitions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in
14 [RFC2119][RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
Throughout this document, the word "renewal" and its variants are Throughout this document, the word "renewal" and its variants are
taken to encompass any combination of "Renewal", "Re-Key", and taken to encompass any combination of "Renewal", "Re-Key", and
"Modification" as defined in [RFC3647]. "Modification" as defined in [RFC3647].
This document assumes that the certificates being issued by the ACME This document assumes that the certificates being issued by the ACME
server are in compliance with [RFC5280], and in particular contain server are in compliance with [RFC5280] and, in particular, contain
the Authority Key Identifier extension and the keyIdentifier field the Authority Key Identifier extension and the keyIdentifier field
within that extension. within that extension.
3. Extensions to the Directory Object 3. Extensions to the Directory Object
An ACME server which wishes to provide renewal information MUST An ACME server that wishes to provide renewal information MUST
include a new field, renewalInfo, in its directory object. include a new field, renewalInfo, in its directory object.
+=============+==============+ +=============+==============+
| Field | URL in Value | | Field | URL in Value |
+=============+==============+ +=============+==============+
| renewalInfo | Renewal info | | renewalInfo | Renewal info |
+-------------+--------------+ +-------------+--------------+
Table 1 Table 1
skipping to change at page 4, line 47 skipping to change at line 172
ACME protocol. This new resource allows clients to query the server ACME protocol. This new resource allows clients to query the server
for suggestions on when they should renew certificates. for suggestions on when they should renew certificates.
To request the suggested renewal information for a certificate, the To request the suggested renewal information for a certificate, the
client sends an unauthenticated GET request to a path under the client sends an unauthenticated GET request to a path under the
server's renewalInfo URL. server's renewalInfo URL.
The path component is a unique identifier for the certificate in The path component is a unique identifier for the certificate in
question. The unique identifier is constructed by concatenating the question. The unique identifier is constructed by concatenating the
base64url-encoding [RFC4648] of the keyIdentifier field of the base64url-encoding [RFC4648] of the keyIdentifier field of the
certificate's Authority Key Identifier (AKI) [RFC5280] extension, a certificate's Authority Key Identifier (AKI) [RFC5280] extension, the
literal period, and the base64url-encoding of the DER-encoded Serial period character ".", and the base64url-encoding of the DER-encoded
Number field (without the tag and length bytes). All trailing "=" Serial Number field (without the tag and length bytes). All trailing
characters MUST be stripped from both parts of the unique identifier. "=" characters MUST be stripped from both parts of the unique
identifier.
Thus the full request URL is constructed as follows (split onto Thus, the full request URL is constructed as follows (split onto
multiple lines for readability), where the "||" operator indicates multiple lines for readability), where the "||" operator indicates
string concatenation and the renewalInfo URL is taken from the string concatenation and the renewalInfo URL is taken from the
Directory object: Directory object:
url = renewalInfo || '/' || url = renewalInfo || '/' ||
base64url(AKI keyIdentifier) || '.' || base64url(Serial) base64url(AKI keyIdentifier) || '.' || base64url(Serial)
For example, to request renewal information for the end-entity For example, to request renewal information for the end-entity
certificate given in Appendix A, the client would make the request as certificate given in Appendix A, the client would make the request as
follows: follows:
skipping to change at page 5, line 22 skipping to change at line 195
For example, to request renewal information for the end-entity For example, to request renewal information for the end-entity
certificate given in Appendix A, the client would make the request as certificate given in Appendix A, the client would make the request as
follows: follows:
1. The keyIdentifier field of the certificate's AKI extension has 1. The keyIdentifier field of the certificate's AKI extension has
the hexadecimal bytes the hexadecimal bytes
69:88:5B:6B:87:46:40:41:E1:B3:7B:84:7B:A0:AE:2C:DE:01:C8:D4 as 69:88:5B:6B:87:46:40:41:E1:B3:7B:84:7B:A0:AE:2C:DE:01:C8:D4 as
its ASN.1 Octet String value. The base64url encoding of those its ASN.1 Octet String value. The base64url encoding of those
bytes is aYhba4dGQEHhs3uEe6CuLN4ByNQ=. bytes is aYhba4dGQEHhs3uEe6CuLN4ByNQ=.
2. The certificate's Serial Number field has the hexadecimal bytes 2. The certificate's Serial Number field has the hexadecimal bytes
00:87:65:43:21 as its DER encoding (note the leading zero byte to 00:87:65:43:21 as its DER encoding (note the leading zero byte to
ensure the serial number remains positive despite the leading 1 ensure the serial number remains positive despite the leading 1
bit in 0x87). The base64url encoding of those bytes is AIdlQyE=. bit in 0x87). The base64url encoding of those bytes is AIdlQyE=.
3. Stripping the trailing padding characters and concatenating with 3. Stripping the trailing padding characters and concatenating with
the separator, the unique identifier is therefore the separator, the unique identifier is therefore
aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE, and the client makes the aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE, and the client makes the
request: request:
GET /renewal-info/aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE HTTP/1.1 GET /renewal-info/aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE HTTP/1.1
Host: acme.example.com Host: acme.example.com
Accept: application/json Accept: application/json
4.2. RenewalInfo Objects 4.2. RenewalInfo Objects
The structure of an ACME renewalInfo resource is as follows: The structure of an ACME renewalInfo resource is as follows:
suggestedWindow (object, required): A JSON object with two keys, suggestedWindow (object, required):
"start" and "end", whose values are timestamps, encoded in the format A JSON object with two keys, "start" and "end", whose values are
specified in [RFC3339], which bound the window of time in which the timestamps, encoded in the format specified in [RFC3339], which
CA recommends renewing the certificate. bound the window of time in which the CA recommends renewing the
certificate.
explanationURL (string, optional): A URL pointing to a page which may explanationURL (string, optional):
explain why the suggested renewal window has its current value. For A URL pointing to a page that may explain why the suggested
example, it may be a page explaining the CA's dynamic load-balancing renewal window has its current value. For example, it may be a
strategy, or a page documenting which certificates are affected by a page explaining the CA's dynamic load-balancing strategy or a page
mass revocation event. Clients SHOULD provide this URL to their documenting which certificates are affected by a mass-revocation
operator, if present. event. Clients SHOULD provide this URL to their operator, if
present.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Retry-After: 21600 Retry-After: 21600
{ {
"suggestedWindow": { "suggestedWindow": {
"start": "2025-01-02T04:00:00Z", "start": "2025-01-02T04:00:00Z",
"end": "2025-01-03T04:00:00Z" "end": "2025-01-03T04:00:00Z"
}, },
skipping to change at page 6, line 22 skipping to change at line 245
"end": "2025-01-03T04:00:00Z" "end": "2025-01-03T04:00:00Z"
}, },
"explanationURL": "https://acme.example.com/docs/ari" "explanationURL": "https://acme.example.com/docs/ari"
} }
Clients MUST attempt renewal at a time of their choosing based on the Clients MUST attempt renewal at a time of their choosing based on the
suggested renewal window. The following algorithm is RECOMMENDED for suggested renewal window. The following algorithm is RECOMMENDED for
choosing a renewal time: choosing a renewal time:
1. Query the renewalInfo resource to get a suggested renewal window. 1. Query the renewalInfo resource to get a suggested renewal window.
2. Select a uniform random time within the suggested window. 2. Select a uniform random time within the suggested window.
3. If the selected time is in the past, attempt renewal immediately. 3. If the selected time is in the past, attempt renewal immediately.
4. Otherwise, if the client can schedule itself to attempt renewal 4. Otherwise, if the client can schedule itself to attempt renewal
at exactly the selected time, do so. at exactly the selected time, do so.
5. Otherwise, if the selected time is before the next time that the 5. Otherwise, if the selected time is before the next time that the
client would wake up normally, attempt renewal immediately. client would wake up normally, attempt renewal immediately.
6. Otherwise, sleep until the time indicated by the Retry-After 6. Otherwise, sleep until the time indicated by the Retry-After
header and return to Step 1. header and return to Step 1.
In all cases, renewal attempts are subject to the client's existing In all cases, renewal attempts are subject to the client's existing
error backoff and retry intervals. error backoff and retry intervals.
In particular, cron-based clients may find they need to increase In particular, cron-based clients may find they need to increase
their run frequency to check ARI more frequently. Those clients will their run frequency to check ARI more frequently. Those clients will
need to store information about failures so that increasing their run need to store information about failures so that increasing their run
frequency doesn't lead to retrying failures without proper backoff. frequency doesn't lead to retrying failures without proper backoff.
Typical information stored should include: number of failures for a Typical information stored should include: number of failures for a
given order (defined by the set of names on the order), and time of given order (defined by the set of names on the order) and time of
the most recent failure. the most recent failure.
A RenewalInfo object in which the end timestamp equals or precedes A RenewalInfo object in which the end timestamp equals or precedes
the start timestamp is invalid. Servers MUST NOT serve such a the start timestamp is invalid. Servers MUST NOT serve such a
response, and clients MUST treat one as though they failed to receive response, and clients MUST treat one as though they failed to receive
any response from the server (e.g., retry at an appropriate interval, any response from the server (e.g., retry at an appropriate interval,
renew on a fallback schedule, etc.). renew on a fallback schedule, etc.).
4.3. Schedule for checking the RenewalInfo resource 4.3. Schedule for Checking the RenewalInfo Resource
Clients SHOULD fetch a certificate's RenewalInfo immediately after Clients SHOULD fetch a certificate's RenewalInfo immediately after
issuance. issuance.
During the lifetime of a certificate, the renewal information needs During the lifetime of a certificate, the renewal information needs
to be fetched frequently enough that clients learn about changes in to be fetched frequently enough that clients learn about changes in
the suggested window quickly, but without overwhelming the server. the suggested window quickly, but without overwhelming the server.
This protocol uses the Retry-After header [RFC9110] to indicate to This protocol uses the Retry-After header [RFC9110] to indicate to
clients how often to retry. Note that in other HTTP applications, clients how often to retry. Note that in other HTTP applications,
Retry-After often indicates the minimum time to wait before retrying Retry-After often indicates the minimum time to wait before retrying
a request. In this protocol, it indicates the desired (i.e. both a request. In this protocol, it indicates the desired (i.e., both
requested minimum and maximum) amount of time to wait. requested minimum and maximum) amount of time to wait.
Clients MUST NOT check a certificate's RenewalInfo after the Clients MUST NOT check a certificate's RenewalInfo after the
certificate has expired. Clients MUST NOT check a certificate's certificate has expired. Clients MUST NOT check a certificate's
RenewalInfo after they consider the certificate to be replaced (for RenewalInfo after they consider the certificate to be replaced (for
instance, after a new certificate for the same identifiers has been instance, after a new certificate for the same identifiers has been
received and configured). received and configured).
4.3.1. Server choice of Retry-After 4.3.1. Server Choice of Retry-After
Servers set the Retry-After header based on their requirements on how Servers set the Retry-After header based on their requirements on how
quickly to perform a revocation. For instance, a server that needs quickly to perform a revocation. For instance, a server that needs
to revoke certificates within 24 hours of notification of a problem to revoke certificates within 24 hours of notification of a problem
might choose to reserve twelve hours for investigation, six hours for might choose to reserve twelve hours for investigation, six hours for
clients to fetch RenewalInfo, and six hours for clients to perform a clients to fetch RenewalInfo, and six hours for clients to perform a
renewal. Setting a small value for Retry-After means that clients renewal. Setting a small value for Retry-After means that clients
can respond more quickly, but also incurs more load on the server. can respond more quickly but also incurs more load on the server.
Servers should estimate their expected load based on the number of Servers should estimate their expected load based on the number of
clients, keeping in mind that third parties may also monitor clients, keeping in mind that third parties may also monitor
RenewalInfo endpoints. RenewalInfo endpoints.
4.3.2. Client handling of Retry-After 4.3.2. Client Handling of Retry-After
After an initial fetch of a certificate's RenewalInfo, clients MUST After an initial fetch of a certificate's RenewalInfo, clients MUST
fetch it again as soon as possible after the time indicated in the fetch it again as soon as possible after the time indicated in the
Retry-After header (backoff on errors takes priority, though). Retry-After header (backoff on errors takes priority, though).
Clients MUST set reasonable limits on their checking interval. For Clients MUST set reasonable limits on their checking interval. For
example, values under one minute could be treated as if they were one example, values under one minute could be treated as if they were one
minute, and values over one day could be treated as if they were one minute, and values over one day could be treated as if they were one
day. day.
4.3.3. Error handling 4.3.3. Error Handling
Temporary errors include, for instance: Temporary errors include, for instance:
* Connection timeout * Connection timeout
* Request timeout * Request timeout
* 5xx HTTP errors * 5xx HTTP errors
On receiving a temporary error, clients SHOULD do exponential backoff On receiving a temporary error, clients SHOULD do exponential backoff
with a capped number of tries. If all tries are exhausted, clients with a capped number of tries. If all tries are exhausted, clients
MUST treat the request as a long-term error. MUST treat the request as a long-term error.
Long term errors include, for instance: Examples of long-term errors include:
* Retry-After is invalid or not present * Retry-After is invalid or not present
* RenewalInfo object is invalid * RenewalInfo object is invalid
* DNS lookup failure * DNS lookup failure
* Connection refused * Connection refused
* Non-5xx HTTP error * Non-5xx HTTP error
On receiving a long term error, clients MUST perform the next On receiving a long-term error, clients MUST perform the next
RenewalInfo fetch as soon as possible after six hours have passed (or RenewalInfo fetch as soon as possible after six hours have passed (or
some other locally configured default). some other locally configured default).
5. Extensions to the Order Object 5. Extensions to the Order Object
In order to convey information regarding which certificate requests In order to convey information regarding which certificate requests
represent renewals of previous certificates, a new field is added to represent renewals of previous certificates, a new field is added to
the Order object: the Order object:
replaces (string, optional): A string uniquely identifying a replaces (string, optional):
previously-issued certificate which this order is intended to A string uniquely identifying a previously issued certificate that
replace. This unique identifier is constructed in the same way as this order is intended to replace. This unique identifier is
the path component for GET requests described above. constructed in the same way as the path component for GET requests
described above.
Clients SHOULD include this field in New Order requests if there is a Clients SHOULD include this field in New Order requests if there is a
clear predecessor certificate, as is the case for most certificate clear predecessor certificate, as is the case for most certificate
renewals. Clients SHOULD NOT include this field if the ACME Server renewals. Clients SHOULD NOT include this field if the ACME Server
has not indicated that it supports this protocol by advertising the has not indicated that it supports this protocol by advertising the
renewalInfo resource in its Directory. renewalInfo resource in its Directory.
POST /new-order HTTP/1.1 POST /new-order HTTP/1.1
Host: acme.example.com Host: acme.example.com
Content-Type: application/jose+json Content-Type: application/jose+json
skipping to change at page 9, line 44 skipping to change at line 400
(Conflict) with a problem document of type "alreadyReplaced" (see (Conflict) with a problem document of type "alreadyReplaced" (see
Section 7.4). Section 7.4).
If the Server accepts a new-order request with a "replaces" field, it If the Server accepts a new-order request with a "replaces" field, it
MUST reflect that field in the response and in subsequent requests MUST reflect that field in the response and in subsequent requests
for the corresponding Order object. for the corresponding Order object.
This replacement information may serve many purposes, including but This replacement information may serve many purposes, including but
not limited to: not limited to:
* granting New Order requests which arrive during the suggested * granting New Order requests that arrive during the suggested
renewal window of their identified predecessor certificate higher renewal window of their identified predecessor certificate higher
priority or allow them to bypass rate limits, if the Server's priority or allowing them to bypass rate limits, if the Server's
policy uses such; policy uses such;
* tracking the replacement of certificates which have been affected
* tracking the replacement of certificates that have been affected
by a compliance incident, so that they can be revoked immediately by a compliance incident, so that they can be revoked immediately
after they are replaced; and after they are replaced; and
* tying together certificates issued under the same contract with an * tying together certificates issued under the same contract with an
entity identified by External Account Binding. entity identified by External Account Binding.
6. Security Considerations 6. Security Considerations
The extensions to the ACME protocol described in this document builds The extensions to the ACME protocol described in this document build
upon the Security Considerations and threat model defined in upon the security considerations and threat model defined in
[RFC8555], Section 10.1. Section 10.1 of [RFC8555].
This document specifies that renewalInfo resources are exposed and This document specifies that renewalInfo resources are exposed and
accessed via unauthenticated GET requests, a departure from RFC8555's accessed via unauthenticated GET requests, a departure from the
requirement that clients send POST-as-GET requests to fetch resources requirement in RFC 8555 that clients send POST-as-GET requests to
from the server. This is because the information contained in fetch resources from the server. This is because the information
renewalInfo resources is not considered confidential, and because contained in renewalInfo resources is not considered confidential and
allowing renewalInfo to be easily cached is advantageous to shed the because allowing renewalInfo to be easily cached is advantageous to
load from clients which do not respect the Retry-After header. As shed the load from clients that do not respect the Retry-After
always, servers should take measures to ensure that unauthenticated header. As always, servers should take measures to ensure that
requests for renewal information cannot result in denial-of-service unauthenticated requests for renewal information cannot result in
attacks. These measures might include ensuring that a cache does not denial-of-service attacks. These measures might include ensuring
include superfluous request headers or query parameters in its cache that a cache does not include superfluous request headers or query
key, instituting IP-based rate limits, or other general best-practice parameters in its cache key, instituting IP-based rate limits, or
measures. other general best-practice measures.
Note that this protocol could exhibit undesired behavior in the Note that this protocol could exhibit undesired behavior in the
presence of significant clock skew between the ACME client and presence of significant clock skew between the ACME client and
server. For example, if a server places the suggested renewal window server. For example, if a server places the suggested renewal window
wholly in the past to encourage a client to renew immediately, a wholly in the past to encourage a client to renew immediately, a
client with a sufficiently slow clock might nonetheless see the client with a sufficiently slow clock might nonetheless see the
window as being in the future. Similarly, a server which wishes to window as being in the future. Similarly, a server that wishes to
schedule renewals very precisely may have difficulty doing so if some schedule renewals very precisely may have difficulty doing so if some
clients have skewed clocks (or do no implement ARI at all). Server clients have skewed clocks (or do no implement ARI at all). Server
operators should take this concern into account when setting operators should take this concern into account when setting
suggested renewal windows. However, many other protocols (including suggested renewal windows. However, many other protocols (including
TLS handshakes themselves) fall apart with sufficient clock skew, so TLS handshakes themselves) fall apart with sufficient clock skew, so
this is not unique to this protocol. this is not unique to this protocol.
7. IANA Considerations 7. IANA Considerations
7.1. ACME Resource Type 7.1. ACME Resource Type
IANA will add the following entry to the "ACME Resource Types" IANA has added the following entry to the "ACME Resource Types"
registry within the "Automated Certificate Management Environment registry within the "Automated Certificate Management Environment
(ACME) Protocol" registry group at https://www.iana.org/assignments/ (ACME) Protocol" registry group at <https://www.iana.org/assignments/
acme (https://www.iana.org/assignments/acme): acme>:
+=============+=====================+===============+ +=============+=====================+===============+
| Field Name | Resource Type | Reference | | Field Name | Resource Type | Reference |
+=============+=====================+===============+ +=============+=====================+===============+
| renewalInfo | Renewal Info object | This document | | renewalInfo | Renewal Info object | This document |
+-------------+---------------------+---------------+ +-------------+---------------------+---------------+
Table 2 Table 2
7.2. ACME Renewal Info Object Fields 7.2. ACME Renewal Info Object Fields
IANA will add the following new registry to the "Automated IANA has added the following new registry to the "Automated
Certificate Management Environment (ACME) Protocol" registry group at Certificate Management Environment (ACME) Protocol" registry group at
https://www.iana.org/assignments/acme <https://www.iana.org/assignments/acme>:
(https://www.iana.org/assignments/acme):
Registry Name: ACME Renewal Info Object Fields Registry Name:
ACME Renewal Info Object Fields
Registration Procedure: Specification Required. The designated Registration Procedure:
expert should ensure that any new fields added to this registry carry Specification Required (see [RFC8126]). The designated expert
useful and unique information that does not better belong elsewhere should ensure that any new fields added to this registry carry
in the ACME protocol. useful and unique information that does not better belong
elsewhere in the ACME protocol.
Template: Template:
Field name: The string to be used as a field name in the JSON
* Field name: The string to be used as a field name in the JSON object
object Field type: The type of value to be provided, e.g., string,
* Field type: The type of value to be provided, e.g., string, boolean, array of string
boolean, array of string Reference: Where this field is defined
* Reference: Where this field is defined
Initial contents: Initial contents:
+=================+============+===============+
| Field Name | Field Type | Reference |
+=================+============+===============+
| suggestedWindow | object | This document |
+-----------------+------------+---------------+
| explanationURL | string | This document |
+-----------------+------------+---------------+
+=================+============+===============+ Table 3
| Field Name | Field type | Reference |
+=================+============+===============+
| suggestedWindow | object | This document |
+-----------------+------------+---------------+
| explanationURL | string | This document |
+-----------------+------------+---------------+
Table 3
7.3. ACME Order Object Fields 7.3. ACME Order Object Fields
IANA will add the following entry to the "ACME Order Object Fields" IANA has added the following entry to the "ACME Order Object Fields"
registry within the "Automated Certificate Management Environment registry within the "Automated Certificate Management Environment
(ACME) Protocol" registry group at https://www.iana.org/assignments/ (ACME) Protocol" registry group at <https://www.iana.org/assignments/
acme (https://www.iana.org/assignments/acme): acme>:
+============+============+==============+===============+ +============+============+==============+===============+
| Field Name | Field Type | Configurable | Reference | | Field Name | Field Type | Configurable | Reference |
+============+============+==============+===============+ +============+============+==============+===============+
| replaces | string | true | This document | | replaces | string | true | This document |
+------------+------------+--------------+---------------+ +------------+------------+--------------+---------------+
Table 4 Table 4
7.4. ACME Error Types 7.4. ACME Error Types
IANA will add the following entry to the "ACME Error Types" registry IANA has added the following entry to the "ACME Error Types" registry
within the "Automated Certificate Management Environment (ACME) within the "Automated Certificate Management Environment (ACME)
Protocol" registry group at https://www.iana.org/assignments/acme Protocol" registry group at <https://www.iana.org/assignments/acme>:
(https://www.iana.org/assignments/acme):
+=================+===================================+===========+ +=================+==================================+===========+
| Type | Description | Reference | | Type | Description | Reference |
+=================+===================================+===========+ +=================+==================================+===========+
| alreadyReplaced | The request specified a | This | | alreadyReplaced | The request specified a | This |
| | predecessor certificate which has | document | | | predecessor certificate that has | document |
| | already been marked as replaced | | | | already been marked as replaced | |
+-----------------+-----------------------------------+-----------+ +-----------------+----------------------------------+-----------+
Table 5 Table 5
8. References 8. References
8.1. Normative References 8.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
skipping to change at page 13, line 27 skipping to change at line 571
<https://www.rfc-editor.org/info/rfc9110>. <https://www.rfc-editor.org/info/rfc9110>.
8.2. Informative References 8.2. Informative References
[RFC3647] Chokhani, S., Ford, W., Sabett, R., Merrill, C., and S. [RFC3647] Chokhani, S., Ford, W., Sabett, R., Merrill, C., and S.
Wu, "Internet X.509 Public Key Infrastructure Certificate Wu, "Internet X.509 Public Key Infrastructure Certificate
Policy and Certification Practices Framework", RFC 3647, Policy and Certification Practices Framework", RFC 3647,
DOI 10.17487/RFC3647, November 2003, DOI 10.17487/RFC3647, November 2003,
<https://www.rfc-editor.org/info/rfc3647>. <https://www.rfc-editor.org/info/rfc3647>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.
Appendix A. Example Certificate Appendix A. Example Certificate
-----BEGIN CERTIFICATE----- -----BEGIN CERTIFICATE-----
MIIBQzCB66ADAgECAgUAh2VDITAKBggqhkjOPQQDAjAVMRMwEQYDVQQDEwpFeGFt MIIBQzCB66ADAgECAgUAh2VDITAKBggqhkjOPQQDAjAVMRMwEQYDVQQDEwpFeGFt
cGxlIENBMCIYDzAwMDEwMTAxMDAwMDAwWhgPMDAwMTAxMDEwMDAwMDBaMBYxFDAS cGxlIENBMCIYDzAwMDEwMTAxMDAwMDAwWhgPMDAwMTAxMDEwMDAwMDBaMBYxFDAS
BgNVBAMTC2V4YW1wbGUuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEeBZu BgNVBAMTC2V4YW1wbGUuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEeBZu
7cbpAYNXZLbbh8rNIzuOoqOOtmxA1v7cRm//AwyMwWxyHz4zfwmBhcSrf47NUAFf 7cbpAYNXZLbbh8rNIzuOoqOOtmxA1v7cRm//AwyMwWxyHz4zfwmBhcSrf47NUAFf
qzLQ2PPQxdTXREYEnKMjMCEwHwYDVR0jBBgwFoAUaYhba4dGQEHhs3uEe6CuLN4B qzLQ2PPQxdTXREYEnKMjMCEwHwYDVR0jBBgwFoAUaYhba4dGQEHhs3uEe6CuLN4B
yNQwCgYIKoZIzj0EAwIDRwAwRAIge09+S5TZAlw5tgtiVvuERV6cT4mfutXIlwTb yNQwCgYIKoZIzj0EAwIDRwAwRAIge09+S5TZAlw5tgtiVvuERV6cT4mfutXIlwTb
+FYN/8oCIClDsqBklhB9KAelFiYt9+6FDj3z4KGVelYM5MdsO3pK +FYN/8oCIClDsqBklhB9KAelFiYt9+6FDj3z4KGVelYM5MdsO3pK
-----END CERTIFICATE----- -----END CERTIFICATE-----
Acknowledgments Acknowledgments
My thanks to Roland Shoemaker and Jacob Hoffman-Andrews for coming up My thanks to Roland Shoemaker and Jacob Hoffman-Andrews for coming up
with the initial idea of ARI and for helping me learn the IETF with the initial idea of ARI and for helping me learn the IETF
process. Thanks also to Samantha Frank, Matt Holt, Ilari Liusvaara, process. Thanks also to Samantha Frank, Matt Holt, Ilari Liusvaara,
and Wouter Tinus for contributing client implementations, and to and Wouter Tinus for contributing client implementations, and to
Freddy Zhang for contributing an independent server implementation. Freddy Zhang for contributing an independent server implementation.
Finally, thanks to Rob Stradling, Andrew Ayer, and J.C. Jones for Finally, thanks to Rob Stradling, Andrew Ayer, and J.C. Jones for
providing meaningful feedback and suggestions which significantly providing meaningful feedback and suggestions that significantly
improved this specification. improved this specification.
Author's Address Author's Address
A. Gable A. Gable
Internet Security Research Group Internet Security Research Group
Email: aaron@letsencrypt.org Email: aaron@letsencrypt.org
 End of changes. 61 change blocks. 
182 lines changed or deleted 188 lines changed or added

This html diff was produced by rfcdiff 1.48.