ACME Renewal Information (RFC 9773)

Certeasy implements ACME Renewal Information (ARI), the standard mechanism that lets the server tell ACME clients when to renew. Compliant clients (recent certbot, acme.sh, lego, Caddy, Traefik) honour the suggested window instead of relying on their own renewal heuristics.

ARI is always enabled and exposes one new endpoint:

GET /acme/renewal-info/<certID>

It is also advertised in the /directory response under the renewalInfo key. Clients discover the endpoint automatically.

Why ARI Matters

Without ARI, every client picks its own renewal threshold (typically "30 days before expiry"). When ten thousand certificates were all issued on the same day, ten thousand clients renew on the same day, hammering the CA. ARI lets the CA suggest a per-certificate window so renewals are spread out across days and the server can also signal an early renewal — for example, after a key compromise.

Configuration

renewal-info:
  lifetime-fraction: 0.66
  window-width: 48h
  retry-after: 6h

Omitting this section applies the defaults.

Field	Default	Meaning
lifetime-fraction	0.66	Fraction of the cert lifetime past which the suggested window opens. 0.66 means renewal is suggested in the last third of the certificate's validity.
window-width	48h	Width of the suggested window. Spreads renewals over this interval to avoid thundering-herd reissue.
retry-after	6h	Sent as the HTTP Retry-After header — tells clients how long to wait before polling renewal-info again.

There is no enabled flag. ARI is a recovery tool: a client cannot ignore renewal-info if you also need it to react to revocation. Disabling it would only encourage clients to fall back to their own heuristics, defeating the purpose.

How the Window Is Computed

For a non-revoked certificate:

lifetime = notAfter − notBefore
start    = notBefore + lifetime × lifetime-fraction
end      = min(start + window-width, notAfter)

For a revoked certificate, the window collapses to [now, now]. Compliant clients renew immediately. This makes revocation an effective rollover mechanism — operators no longer need to coordinate manual reissuance after a key compromise or template change.

For a degenerate (zero-lifetime) certificate, the window is also [now, now].

Endpoint Details

Property	Value
Method	GET (no JWS)
Path	/acme/renewal-info/<certID>
Auth	None (public)
Rate limit	Global per-IP only — see Rate Limiting
Body format	RFC 9773 §4.2: suggestedWindow.start and suggestedWindow.end as RFC 3339 timestamps
Response headers	Retry-After: <seconds>

The certID path parameter is the RFC 9773 §4.1 format:

base64url(AKI) "." base64url(serialNumber)

Both components use unpadded base64url. AKI is the Authority Key Identifier extension of the leaf certificate; serial number is the cert's serial as unsigned big-endian bytes.

Example response

{
  "suggestedWindow": {
    "start": "2026-08-15T00:00:00Z",
    "end":   "2026-08-17T00:00:00Z"
  }
}

Lookup Storage

Each issued certificate is stored with its aki and serial (lowercase hex) in acme_certificates, with a composite index (aki, serial). Lookup is O(log n).

Compatibility Notes

• Certificates issued by an authority that does not include an Authority Key Identifier extension are not addressable via ARI. The renewal-info endpoint will return 404 for them. Configure your ADCS template to include AKI (this is the default in modern ADCS).
• Older ACME clients that do not implement ARI continue to work normally — the directory.renewalInfo field is simply ignored by them.