RFC 9773

ACME Renewal Information (ARI) Extension

📅 published June 2025, from ietf

RFC 9773: ACME Renewal Information (ARI) Extension 🦋

okay bestie, RFC 9773 is the ACME Renewal Information (ARI) Extension ✨ It was written by A. Gable from the Internet Security Research Group, and it's a Standards Track document, which means it's an official IETF Internet Standard 👑 It was published in June 2025 and has ISSN 2070-1721.

Abstract ✨

okay so this doc is about how an ACME server can give clients suggestions about when to renew their certificates 💖 The server can help smooth out load spikes, and clients stop making wrong guesses about how often they should renew. it's giving good planning, no cap 🎀

Status of This Memo

this is an Internet Standards Track document 🌸

this doc is a product of the Internet Engineering Task Force (IETF). it represents the consensus of the IETF community, received public review, and got approved for publication by the Internet Engineering Steering Group (IESG). if you want more info on Internet Standards, check out Section 2 of RFC 7841 💅

for the current status, any errata, and how to send feedback, go to https://www.rfc-editor.org/info/rfc9773 🔗

Copyright (c) 2025 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) as they stand on the date of publication. please read these carefully, because they explain your rights and restrictions for this document 🫶 Code Components pulled out of this document must include Revised BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Revised BSD License.

Table of Contents 🧚

1.  Introduction
2.  Conventions and Definitions
3.  Extensions to the Directory Object
4.  Getting Renewal Information
  4.1.  The RenewalInfo Resource
  4.2.  RenewalInfo Objects
  4.3.  Schedule for Checking the RenewalInfo Resource
    4.3.1.  Server Choice of Retry-After
    4.3.2.  Client Handling of Retry-After
    4.3.3.  Error Handling
5.  Extensions to the Order Object
6.  Security Considerations
7.  IANA Considerations
  7.1.  ACME Resource Type
  7.2.  ACME RenewalInfo Object Fields
  7.3.  ACME Order Object Fields
  7.4.  ACME Error Types
8.  References
  8.1.  Normative References
  8.2.  Informative References
Appendix A.  Example Certificate
Acknowledgments
Author's Address

1. Introduction 💫

okay so most ACME [RFC8555] clients pick when to renew a certificate in one of three ways 🍓

  1. they might be set to renew on a fixed interval (for example, with cron),
  2. they might read the issued certificate to find its expiration date, then renew a certain amount of time before that, or
  3. they might read the issued certificate and renew once some percentage of its validity period has gone by.

the first two make it really hard for the issuing Certification Authority (CA) to change certificate lifetimes 😭 All three can also cause load clustering at the issuing CA, because the CA can't schedule renewal requests 💀

so if issuing CAs can suggest a window for clients to renew in, you get dynamic, time-based load balancing 🎀 That lets a CA handle unusual situations better. for example:

  • a CA could suggest that clients renew before a mass-revocation event, so the impact of the revocation is smaller, or
  • a CA could suggest that clients renew earlier than they normally would, to shrink an upcoming mass-renewal spike.

this document specifies the ACME Renewal Information (ARI) extension 🦋 It's the mechanism that lets ACME servers hand out suggested renewal windows to ACME clients, and that lets ACME clients tell ACME servers they've successfully renewed and replaced a certificate. iconic 👑

2. Conventions and Definitions 📚

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 read as described in BCP 14 [RFC2119] [RFC8174], but only when they show up in all capitals, exactly like this 💅

in this doc, "renewal" and its variants cover any mix of "Renewal", "Re-Key", and "Modification", as defined in [RFC3647] ✨

this doc assumes the certificates the ACME server issues follow [RFC5280]. specifically, they contain the Authority Key Identifier extension and the keyIdentifier field inside that extension 🫶

3. Extensions to the Directory Object 🗂️

an ACME server that wants to provide renewal information MUST add a new field, "renewalInfo", to its directory object 🌸

                 +=============+=====================+
                 | Field       | URL in Value        |
                 +=============+=====================+
                 | renewalInfo | Renewal information |
                 +-------------+---------------------+

                                Table 1

here's what that looks like in an actual response 🍓

HTTP/1.1 200 OK
Content-Type: application/json

{
  "newNonce": "https://acme.example.com/new-nonce",
  "newAccount": "https://acme.example.com/new-account",
  "newOrder": "https://acme.example.com/new-order",
  "newAuthz": "https://acme.example.com/new-authz",
  "revokeCert": "https://acme.example.com/revoke-cert",
  "keyChange": "https://acme.example.com/key-change",
  "renewalInfo": "https://acme.example.com/renewal-info",
  "meta": {
    "termsOfService": "https://example.com/acme/terms",
    "website": "https://example.com/acme/docs",
    "caaIdentities": ["example.com"],
    "externalAccountRequired": false
  }
}

4. Getting Renewal Information 🔥

4.1. The RenewalInfo Resource 🧚

the RenewalInfo resource is a brand-new resource type in the ACME protocol 🦋 It lets clients ask the server for suggestions about when they should renew.

to request suggested renewal info for a certificate, the client sends an unauthenticated GET request to a path under the server's renewalInfo URL 💖

the path component is a unique identifier for the certificate. you build it by concatenating three things: the base64url encoding [RFC4648] of the keyIdentifier field from the certificate's Authority Key Identifier (AKI) [RFC5280] extension, the period character ".", and the base64url encoding of the DER-encoded Serial Number field (without the tag and length bytes). All trailing "=" characters MUST be stripped from both parts of the unique identifier 🫶

so the full request URL gets built like this (split across lines so it's easier to read), where the "||" operator means string concatenation and the renewalInfo URL comes from the Directory object 💅

url = renewalInfo || '/' ||
      base64url(AKI keyIdentifier) || '.' || base64url(Serial)

here's an example. to get renewal info for the end-entity certificate in Appendix A, the client would do this:

  1. The keyIdentifier field of the certificate's AKI extension has the hexadecimal bytes 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 bytes is aYhba4dGQEHhs3uEe6CuLN4ByNQ=.
  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: it keeps the serial number positive despite the leading 1 bit in 0x87.) The base64url encoding of those bytes is AIdlQyE=.
  3. Strip the trailing padding characters and join with the separator, and the unique identifier becomes aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE. The client then makes this request:
GET /renewal-info/aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE HTTP/1.1
Host: acme.example.com
Accept: application/json

4.2. RenewalInfo Objects 📦

here's the shape of an ACME RenewalInfo object 🌈

suggestedWindow (object, required): a JSON object with two keys, "start" and "end". Their values are timestamps encoded in the format from [RFC3339], and together they bound the window in which the CA recommends renewing the certificate 🍓

explanationURL (string, optional): a URL for a page that may explain why the suggested renewal window has its current value. for example, it could be a page about the CA's dynamic load-balancing strategy, or a page listing which certificates a mass-revocation event affects. Clients SHOULD pass this URL along to their operator, if one is present 💖

HTTP/1.1 200 OK
Content-Type: application/json
Retry-After: 21600

{
  "suggestedWindow": {
    "start": "2025-01-02T04:00:00Z",
    "end": "2025-01-03T04:00:00Z"
  },
  "explanationURL": "https://acme.example.com/docs/ari"
}

clients MUST attempt renewal at a time of their own choosing, based on the suggested renewal window 🫶 The following algorithm is RECOMMENDED for picking a renewal time ✨

  1. Make a renewalInfo request to get a suggested renewal window.
  2. Select a uniform random time within the suggested window.
  3. If the selected time is in the past, attempt renewal immediately.
  4. Otherwise, if the client can schedule itself to attempt renewal at exactly the selected time, do so.
  5. Otherwise, if the selected time is before the next time the client would wake up normally, attempt renewal immediately.
  6. Otherwise, sleep until the time indicated by the Retry-After header, and return to Step 1.

in every case, renewal attempts are subject to the client's existing error backoff and retry intervals 🛡️

cron-based clients might find they need to bump up how often they run so they check ARI more frequently 🙈 Those clients will need to store information about failures, so that running more often doesn't mean retrying failures without proper backoff. the typical stuff to store includes the number of failures for a given order (defined by the set of identifiers on the order), and the time of the most recent failure 📝

A RenewalInfo object where the end timestamp equals or comes before the start timestamp is invalid. Servers MUST NOT serve such a response, and clients MUST treat one as though they never got any response from the server at all (for example, retry at an appropriate interval, or renew on a fallback schedule). 🚨

4.3. Schedule for Checking the RenewalInfo Resource 🗓️

okay bestie, clients SHOULD fetch a certificate's RenewalInfo right after issuance 💖

Over a certificate's whole lifetime, the renewal info has to be fetched often enough that clients catch changes to the suggested window fast, but not so often that the server gets overwhelmed 🦋 This protocol uses the Retry-After header [RFC9110] to tell clients how often to retry. Now, ngl, this is the part that trips people up: in other HTTP apps, Retry-After usually means the minimum time to wait before retrying. Here it means the desired amount of time to wait, so both the requested minimum and the requested maximum 💅

Clients MUST NOT check a certificate's RenewalInfo after the certificate has expired. Clients MUST NOT check a certificate's RenewalInfo after they consider the certificate to be replaced (for instance, after a new certificate for the same identifiers has been received and configured). Not me checking an expired cert 💀

4.3.1. Server Choice of Retry-After

Servers set the Retry-After header based on how quickly they need to perform a revocation 🍓 For example, say a server has to revoke certificates within 24 hours of hearing about a problem. It might save twelve hours for investigating, six hours for clients to fetch updated RenewalInfo objects, and six hours for clients to actually renew. Setting a small Retry-After value means clients can respond faster, but it also puts more load on the server 🫶 Servers should estimate their expected load based on how many clients there are, and keep in mind that third parties may also monitor renewalInfo endpoints 👀

4.3.2. Client Handling of Retry-After

After the first fetch of a certificate's RenewalInfo, clients MUST fetch it again as soon as possible after the time in the Retry-After header has passed (backoff on errors takes priority, though) ✨ Clients MUST set reasonable limits on their checking interval. For example, values under one minute could be treated as one minute, and values over one day could be treated as one day. Limits are giving responsible energy 🌈

4.3.3. Error Handling

Temporary errors include, for instance:

  • Connection timeout
  • Request timeout
  • 5xx HTTP errors

On receiving a temporary error, clients SHOULD do exponential backoff with a capped number of tries. If all tries are exhausted, clients MUST treat the request as a long-term error 😭

Examples of long-term errors include:

  • Retry-After is invalid or not present
  • RenewalInfo object is invalid
  • DNS lookup failure
  • Connection refused
  • Non-5xx HTTP error

On receiving a long-term error, clients MUST make the next renewalInfo request as soon as possible after six hours have passed (or some other locally configured default) 🧚

5. Extensions to the Order Object 🎀

okay so, in order to show which certificate requests are renewals of older certificates, a new field gets added to the Order object 💜

replaces (string, optional): A string uniquely identifying a previously issued certificate that this order is intended to replace. This unique identifier is constructed the same way as the path component for GET requests described in Section 4.1.

Clients SHOULD include this field in newOrder requests if there is a clear predecessor certificate, which is the case for most certificate renewals 🔥 Clients SHOULD NOT include this field if the ACME server hasn't indicated that it supports this protocol by advertising the renewalInfo resource in its Directory. Main character energy for the ones who check first 💅

POST /new-order HTTP/1.1
Host: acme.example.com
Content-Type: application/jose+json

{
  "protected": base64url({
    "alg": "ES256",
    "kid": "https://acme.example.com/acct/evOfKhNU60wg",
    "nonce": "5XJ1L3lEkMG7tR6pA00clA",
    "url": "https://acme.example.com/new-order"
  }),
  "payload": base64url({
    "identifiers": [
      { "type": "dns", "value": "acme.example.com" }
    ],
    "replaces": "aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE"
  }),
  "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g"
}

Servers SHOULD check that the identified certificate and the newOrder request belong to the same ACME Account, that they share at least one identifier, and that the identified certificate hasn't already been marked as replaced by a different Order that isn't "invalid". Any checks beyond that (like requiring exact identifier matching) are left up to server policy 🙈 If any of these checks fail, the server SHOULD reject the newOrder request. If the server rejects the request because the identified certificate has already been marked as replaced, it MUST return an HTTP 409 (Conflict) with a problem document of type alreadyReplaced (see Section 7.4).

If the server accepts a newOrder request with a replaces field, it MUST reflect that field in the response and in subsequent requests for the corresponding Order object 🦋

This replacement info can be useful for lots of things, including but not limited to:

  • giving newOrder requests that arrive during the suggested renewal window of their identified predecessor certificate higher priority, or letting them skip rate limits, if the server's policy does that;
  • tracking the replacement of certificates affected by a compliance incident, so they can be revoked right after they're replaced; and
  • tying together certificates issued under the same contract with an entity identified by External Account Binding.

6. Security Considerations 🔐

The extensions to the ACME protocol described in this document build on the security considerations and threat model defined in Section 10.1 of [RFC8555] 🧠

This document specifies that RenewalInfo resources are exposed and accessed via unauthenticated GET requests. That's a departure from the requirement in RFC 8555 that clients send POST-as-GET requests to fetch resources from the server. Why? Because the information in RenewalInfo resources isn't considered confidential, and letting RenewalInfo resources be cached easily helps take load off clients that don't respect the Retry-After header 🌸 As always, servers should take measures to make sure unauthenticated requests for renewal information can't cause denial-of-service attacks. These measures might include making sure a cache doesn't include superfluous request headers or query parameters in its cache key, adding IP-based rate limits, or other general best-practice measures.

Real talk: this protocol could behave badly if there's significant clock skew between the ACME client and server 😱 For example, if a server puts the suggested renewal window entirely in the past to push a client to renew immediately, a client with a sufficiently slow clock might still see the window as being in the future. Similarly, a server that wants to schedule renewals very precisely may have trouble doing so if some clients have skewed clocks (or don't implement ARI at all). Server operators should take this concern into account when setting suggested renewal windows. Honestly though, many other protocols (including TLS handshakes themselves) fall apart with enough clock skew, so this isn't unique to this protocol 🫠

7. IANA Considerations 📚

7.1. ACME Resource Type

IANA has added the following entry to the "ACME Resource Types" registry within the "Automated Certificate Management Environment (ACME) Protocol" registry group at <https://www.iana.org/assignments/acme>:

        +=============+====================+===============+
        | Field Name  | Resource Type      | Reference     |
        +=============+====================+===============+
        | renewalInfo | RenewalInfo object | This document |
        +-------------+--------------------+---------------+

                              Table 2

7.2. ACME RenewalInfo Object Fields

IANA has added the following new registry to the "Automated Certificate Management Environment (ACME) Protocol" registry group at <https://www.iana.org/assignments/acme>:

Registry Name: ACME RenewalInfo Object Fields

Registration Procedure: Specification Required (see [RFC8126]). The designated expert should ensure that any new fields added to this registry carry useful and unique information that doesn't better belong elsewhere in the ACME protocol.

Template: Field name: The string to be used as a field name in the JSON object Field type: The type of value to be provided, e.g., string, boolean, array of string Reference: Where this field is defined

Initial contents:

            +=================+============+===============+
            | Field Name      | Field Type | Reference     |
            +=================+============+===============+
            | suggestedWindow | object     | This document |
            +-----------------+------------+---------------+
            | explanationURL  | string     | This document |
            +-----------------+------------+---------------+

                                Table 3

7.3. ACME Order Object Fields

IANA has added the following entry to the "ACME Order Object Fields" registry within the "Automated Certificate Management Environment (ACME) Protocol" registry group at <https://www.iana.org/assignments/acme>:

     +============+============+==============+===============+
     | Field Name | Field Type | Configurable | Reference     |
     +============+============+==============+===============+
     | replaces   | string     | true         | This document |
     +------------+------------+--------------+---------------+

                              Table 4

7.4. ACME Error Types

IANA has added the following entry to the "ACME Error Types" registry within the "Automated Certificate Management Environment (ACME) Protocol" registry group at <https://www.iana.org/assignments/acme>:

 +=================+==================================+===========+
 | Type            | Description                      | Reference |
 +=================+==================================+===========+
 | alreadyReplaced | The request specified a          | This      |
 |                 | predecessor certificate that has | document  |
 |                 | already been marked as replaced  |           |
 +-----------------+----------------------------------+-----------+

                              Table 5

8. References 📖

8. References ✨

okay bestie, this is the reading list 📚 we're gonna split it into the stuff you must have read and the stuff that's just nice to know 🫶

8.1. Normative References

8.2. Informative References

Appendix A. Example Certificate 🎀

here's an example certificate, just sitting there looking cute 🦋 copy it exactly as it is:

-----BEGIN CERTIFICATE-----
MIIBQzCB66ADAgECAgUAh2VDITAKBggqhkjOPQQDAjAVMRMwEQYDVQQDEwpFeGFt
cGxlIENBMCIYDzAwMDEwMTAxMDAwMDAwWhgPMDAwMTAxMDEwMDAwMDBaMBYxFDAS
BgNVBAMTC2V4YW1wbGUuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEeBZu
7cbpAYNXZLbbh8rNIzuOoqOOtmxA1v7cRm//AwyMwWxyHz4zfwmBhcSrf47NUAFf
qzLQ2PPQxdTXREYEnKMjMCEwHwYDVR0jBBgwFoAUaYhba4dGQEHhs3uEe6CuLN4B
yNQwCgYIKoZIzj0EAwIDRwAwRAIge09+S5TZAlw5tgtiVvuERV6cT4mfutXIlwTb
+FYN/8oCIClDsqBklhB9KAelFiYt9+6FDj3z4KGVelYM5MdsO3pK
-----END CERTIFICATE-----

Acknowledgments 🫶

Huge thank-yous to Roland Shoemaker and Jacob Hoffman-Andrews for coming up with the initial idea of ARI and for helping the author learn the IETF process 💖 Thanks also to Samantha Frank, Matt Holt, Ilari Liusvaara, and Wouter Tinus for contributing client implementations, and to Freddy Zhang for contributing an independent server implementation 🌸 Finally, thanks to Rob Stradling, Andrew Ayer, and J.C. Jones for providing meaningful feedback and suggestions that significantly improved this specification 👑

Author's Address 💌

A. Gable
Internet Security Research Group
Email: aaron@letsencrypt.org
📦 where this page comes from