I was reading the ACME protocol and Boulder divergences from ACME and I have some questions for which hopefully I could find an answer here.
Am I safe to assume that while creating new authorizations, Boulder will always return a HTTP validation challenge, therefor allowing me to implement only HTTP validation challenge and disregard other challenges?
If sometime in the future Boulder will remove HTTP validation challenge, will this be considered breaking change and thus a new version of API will be created?
That’s safe to assume but there is a chance one day we might deprecate a challenge (say, due to a vulnerability). I would make sure your code is able to handle this case by failing with appropriate warnings. If we do deprecate a challenge you can definitely expect we would post about it in the API Announcements forum (Make sure to subscribe!) & give plenty of warning with cutoff dates.
I haven’t been present for any discussions about this question directly. My own thoughts are that removing one challenge type if there are others present isn’t an API breaking change, but it is a change with backwards compatibility implications so we would handle it carefully as mentioned above. I don’t think we would offer a new endpoint.
It’s hard to say for sure for certain. If we imagine a vulnerability was found in HTTP-01 and we were forced to remove it then we likely wouldn’t prioritize backwards compatibility to the same extent. Conversely if we were removing it because there was a new & improved HTTP-02 we would probably spend more time evaluating options that preserved backwards compatibility for longer.
How does Boulder handles renewals ? I believe the following would apply:
1.a there is no difference between renewals and new certificates from boulder point of view.
1.b new certificate and old certificate would have an overlapping period between new certificate issue period and old certificate expiry period
What sort of issues that require retry should I expect?
Beside well known errors defined by RFC( badNounce, etc… ), and api limits, I believe the only one would be a timeout while trying to connect to boulder server
Other than that, I cannot foresee other scenarios as why new or renew would fail.
If a http validation fails due to client connection timeout ( boulder cannot connect to client for http validation ), would boulder mark the validation as failure or it would retry again ?
That’s correct. The only thing that’s handled differently for renewals is that the rate limits are handled differently - specifically, even if you’ve run into the rate limit for your domain for this week, you’ll be able to renew a certificate (where renew is defined as “you’ve issued a certificate for the exact same set of FQDNs before”). The API calls and all that are the same for the first certificate and renewals.
That seems reasonable.
Issues on Let’s Encrypt’s end could cause anything from Internal Server Error to possibly Bad Gateway or Gateway Time-Out. My approach would be to wrap any non-successful HTTP status code in the “general” retry logic, except for specific error types that you know how to handle differently.
The verification is attempted once, and if it fails for any reason (including timeout), it’s marked as invalid (along with the corresponding authorization). The correct way to recover/retry would be to create a new authorization for the domain and submit the new challenge for verification.