New Request vs Renewal vs Reissue

I've been working with various LE clients for a while, but this is actually the first time I'm integrating directly with the API and I'd like a confirmation about a doubt I have regarding New Requests vs Renewals.

As far as I can see, there is no notion of "renewal". A renewal is essentially a "new request" sent to the new-cert resource endpoint. Is it correct?

From the acme specification I read:

To avoid unnecessary renewals, the CA may choose not to issue a renewed certificate until it receives such a request (if it even allows renewal at all). In such cases, if the CA requires some time to generate the new certificate, the CA MUST return a 202 (Accepted) response, with a Retry-After header field that indicates when the new certificate will be available. The CA MAY include the current (non-renewed) certificate as the body of the response.

and also

From the client’s perspective, there is no difference between a certificate URI that allows renewal and one that does not. If the client wishes to obtain a renewed certificate, and a GET request to the certificate URI does not yield one, then the client may initiate a new-certificate transaction to request one.

My interpretation is that a client should first send a GET to the certificate URI and compare the existing certificate. If it's the same, then a new cert should be requested. And, in fact, this is what some clients I've worked with already do.

This implies that, in some cases, Let's Encrypt may actually self-renew a certificate. Is it correct?

  • In which cases LE will renew a certificate (resulting then in a different resource when I perform the GET)?
  • Also, if I request a new certificate, how will LE detect that this is a renewal (and therefore lift the corresponding issuance limit)? Do I have to reuse the same CSR/private key?

As for reissue/rekey, I assume there is no such thing. To re-key a certificate I simply need to request a new one (and the request will be rules by the issuance limit). Is it correct?

The rate limits track issuances for “FQDN sets”

For example if you ask for a certificate with SANs www.example.com and example.com, that’s one FQDN set, and another certificate with the same SANs is considered a “renewal” and doesn’t count against the 20 per week limit. But if you ask now for a certificate with www.example.com, www.example.net, www.example.org, the set of FQDNs is different, it’s not counted as a “renewal” of the old certificate and does count against the 20 per week limit.

Normally, issuance will require validation that you control the names. In some cases (and policy for this is expected to shift over time) an account may already have unexpired validations for the names you want in a renewal, left from when a previous certificate was issued. Your client should ideally be able to cope with this, examining the “authz” I think they’re called, and spotting that some are “done” already and it can skip those. But the only advantage is that it reduces the work you need to do (or the user needs to do if it’s semi-manual) to get the certificate issued. You should ensure you can cope with the case where new “authz” are needed because that will be the most common scenario.

To be clear: Let's Encrypt is a CA implementing the ACME specification. So there can be a big difference between what's written in the ACME specs and what Let's Encrypt is doing.

If the specs say: "a CA might do something, or could do something else", you can not determine (from the specs alone that is) how Let's Encrypt implemented things.

And on top of that, the specs you're referring to, is the fourth version. I don't know which version Boulder (the open source software Let's Encrypt uses for issuing certs) is implementing, but it might be another version of the ACME specs..

As far as I know, at this moment, Let's Encrypt renewal works by the client requesting a new certificate. :slight_smile:

Yes, I'm very well aware of that. In fact, I was asking if LE was somehow implementing self-renewal, or if instead it required explicit requests, which seems to be the case.

That was my guess. However, this mean I can potentially request a new certificate every day, for the same SAN set, and never fall into the issuance limits. This seems kind of strange to believe.

Once per day would exceed the per-FQDN-set limit of 5 per week which is separate to the limit of new certificates in a domain. Once per week - while unnecessary - would thus not trip any limits.

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.