Re: [Acme] The ACME Renewal Information (ARI) extension

[Aaron Gable <[e-mail]>]

Hi again all,

Below I have included the full text of my first attempt at a draft for the
ARI extension to the ACME protocol. Having never done this before, I'm sure
there are a number of issues with the draft, both semantic (e.g.
underspecifying something) and technical (e.g. formatting). I look forward
to your feedback on both, as well as to learning more about what the next
steps in this process are. I also look forward to talking through this
draft in our interim meeting later this month!

Thanks again,
Aaron

------------------------

# Automated Certificate Renewal Environment (ACME) Renewal Information
(ARI) Extension

## 1. Introduction

Most ACME 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.

## 2. 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.

## 3. Extensions to the ACME Protocol: The “order” Resource

An ACME server which wishes to provide renewal information MUST include a
new field, “renewalInfo”, in finalized Order objects.

renewalInfo (optional, string): A URL for renewal information for the
certificate that has been issued in response to this order.

HTTP/1.1 200 OK

Content-Type: application/json

{

  "status": "valid",

  "expires": "2021-01-20T14:09:07.99Z",

  "identifiers": [

    { "type": "dns", "value": "www.example.org" },

    { "type": "dns", "value": "example.org" }

  ],

  "notBefore": "2021-01-01T00:00:00Z",

  "notAfter": "2021-01-08T00:00:00Z",

  "authorizations": [

    "https://example.com/acme/authz/PAniVnsZcis",

    "https://example.com/acme/authz/r4HqLzrSrpI"

  ],

  "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize",

  "certificate": "https://example.com/acme/cert/mAt3xBGaobw",

  “renewalInfo”: “https://example.com/acme/renewal/eXoM9UwLgbL”

}

Conforming clients SHOULD store the “renewalInfo” URL locally so that they
can poll it at any time during the lifetime of the certificate.

## 4. Extensions to the ACME Protocol: The “renewalInfo” Resource

We define a new resource type, the “renewalInfo” resource, as part of the
ACME protocol.

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

{

  "suggestedWindow": {

    “start”: "2021-01-03T00:00:00Z",

    “end”: "2021-01-07T00:00:00Z"

  }

}

Conforming servers MUST provide the renewalInfo resource via POST-as-GET;
they SHOULD provide it via unauthenticated GET as well. Conforming clients
SHOULD use unauthenticated GET to request renewalInfo resources.

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 SHOULD select a 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.

## 5. Security Considerations

The extensions to the ACME protocol described in this document build upon
the Security Considerations and threat model defined in Section 10.1 of
[RFC8555].

This document specifies that renewalInfo resources should be exposed 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.

# 6. IANA Considerations

Draft note: The following changes to IANA registries have not yet been made.

6.1 New Registries

Within the “Automated Certificate Management Environment (ACME) Protocol”
registry, IANA has created the new “ACME Renewal Info Object Fields”
registry (Section 6.4).

6.2 ACME Resource Type

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 |
<https://www.rfc-editor.org/rfc/rfc8555>This draft |

+-------------+---------------------+------------+

6.3 ACME Order Object Fields

Within the “Automated Certificate Management Environment (ACME) Protocol”
registry, the following entry has been added to the “ACME Order Object
Fields” registry.

+-------------+------------+--------------+------------+

| Field Name  | Field Type | Configurable | Reference  |

+-------------+------------+--------------+------------+

| renewalInfo | string     | false        | This draft |

+-------------+------------+--------------+------------+

6.4 ACME Renewal Info Object Fields

The “ACME Renewal Info Object Fields” registry lists field names that are
defined for use in ACME renewal info objects.

Template:

o Field name: The string to be used as a field name in the JSON object

o Field type: The type of value to be provided, e.g., string, boolean,
array of string

o Reference: Where this field is defined

Initial contents:

+-----------------+------------+------------+

| Field Name      | Field type | Reference  |

+----------------+-------------+------------+

| suggestedWindow | object     | <https://www.rfc-editor.org/rfc/rfc8555>This
draft |

+-----------------+------------+------------+

On Fri, Aug 20, 2021, 17:34 Aaron Gable <[e-mail]> wrote:

> Hello all,
>
> In March of 2020, Roland Shoemaker started a conversation[1] on this list
> regarding a potential new ACME extension, the ACME Renewal Information
> (ARI) API. The goal of this extension is to allow ACME servers to provide
> hints to ACME clients about when they should renew the certificates they
> are responsible for.
>
> [1]
> https://mailarchive.ietf.org/arch/msg/acme/b-RddSX8TdGYvO3f9c7Lzg6I2I4/
>
> The purpose of this message is to restart this conversation. It is my (and
> Let’s Encrypt’s) intention to draft, design, implement, and standardize
> something to fulfil this role in the ACME ecosystem.
>
> I have already begun work on the text of an Internet Draft based on
> Roland’s initial proposal. I hope to have that ready to share in the next
> week. At IETF 111 we discussed having an interim virtual ACME WG meeting in
> mid-late September. It is my goal to present the draft at that meeting. If
> that meeting does not occur, then I will present at IETF 112.
>
> As part of moving this conversation forward, I’d like to directly address
> some of the comments raised by Matt Holt[2] and Andrew Ayer[3] on the
> original proposal.
>
> [2]
> https://mailarchive.ietf.org/arch/msg/acme/kSm_atiR9ageSoEheNp6xYyJZOU/
> [3]
> https://mailarchive.ietf.org/arch/msg/acme/szDHa5z6qRiAtmeC2ohrePPoBjU/
>
> -----
>
> On Tuesday, 24 March 2020, Matt Holt <[e-mail]> wrote:
> > In terms of trust, what is the difference between knowing a certificate
> is going to be revoked soon, and a certificate that is already revoked? In
> a binary sense, if you know a certificate is going to be revoked, it's as
> good as revoked. Why should you continue to trust a certificate when the CA
> already knows it shouldn't continue to be trusted?
> > ...
> > Before going too deep into implementation details, I think the
> philosophical paradox this proposal introduces should be resolved.
>
> The purpose of this proposal is not to inform clients that their
> certificate is about to be revoked; rather, the purpose is to inform
> clients of a window in which it would be good for them to renew their
> certificate. This can be used in many scenarios: spreading out clients
> whose certificates have clustered `notAfter` timestamps; ensuring that a
> client doesn’t miss that their current certificate has a validity period
> different from that which it normally expects (e.g. if a CA switched from
> 90-day to 30-day certs, renewing 30 days before expiration would suddenly
> be a mistake); accelerating the timeframe in which certificates issued by a
> valid-but-undesirable intermediate rotate out of circulation; or hinting to
> a client that its certificate might be revoked soon and should be replaced
> prior to that event.
>
> In particular, one of the most critical applications of this proposal is
> not for the event of a mass revocation, but rather to manage the fallout of
> such an event. If a CA were to revoke and replace a significant number of
> certificates in a 24-hour period, then they will experience an ongoing
> “thundering herd” problem every few days/weeks/months (depending on their
> standard validity period) thereafter. ARI could be used to hint to some
> clients that they should wait the maximum possible time before renewing,
> while others could be directed to renew immediately, immediately mitigating
> the thundering herd problem.
>
> As such, data communicated by the ARI API should not be taken to mean
> “this certificate is going to be revoked soon”, and does not communicate
> trust information.
>
> -----
>
> On Tuesday, 24 March 2020, Matt Holt <[e-mail]> wrote:
> > In my opinion, the burden is on the clients to just be a little more
> fault-tolerant. They should staple OCSP responses. They should do so
> conservatively. They can call `renewCert()` when they see a Revoked
> response.
>
> Unfortunately, this approach only works for ACME clients that are
> themselves also web servers, and are therefore capable of stapling an OCSP
> response to a TLS handshake. Many clients are only responsible for
> populating a certificate on disk, not responsible for providing that
> certificate to TLS clients, and so cannot guarantee things like stapling.
>
> In addition, this approach does not handle the load-smoothing case
> discussed above.
>
> -----
>
> On Tuesday, 24 March 2020, Andrew Ayer <[e-mail]> wrote:
> > I think it would be really useful if the renewal information could be
> discovered and retrieved by third parties.  This would permit monitoring
> services to raise an alarm if a certificate is going to be revoked soon,
> just in case the automation fails to renew it (or there is no automation,
> which is unfortunately common).  For example, during the recent Let's
> Encrypt revocation incident, Cert Spotter used the list of serial numbers
> published by Let's Encrypt to alert the users of Cert Spotter who were
> affected.
>
> This sounds to me like a point in favor of having the proposal specify how
> the renewalInfo url is constructed, such that clients don’t have to cache
> it on-disk, and such that it could be constructed by third parties as well.
>
> Notably, RFC 8555 does not specify how to construct Certificate URLs. As
> per spec, the url from which to download a certificate can only be
> determined by examining the corresponding Order (which can only be loaded
> by the Subscriber that created the Order) and loading the Certificate URL
> contained in that resource. Given that there is no
> third-party-constructable way to fetch certificates from an ACME, it would
> feel odd to me for there to be consistent third-party-constructable ways to
> fetch certificate renewal info.
>
> (It is open knowledge that Let’s Encrypt constructs certificate URLs by
> concatenating the original and creative “/acme/cert/” prefix with the
> hex-encoded certificate Serial number, and we have taken advantage of that
> fact to provide affected certificate details in incident reports, but that
> is not standardized.)
>
> ----
>
> Thank you all for your thoughtful comments a year ago, and I look forward
> to more discussion and sharing my draft in the near future.
>
> Aaron
>