Http challenge API spec

Hi, is there a standard API spec for implementing the http-challenge well-known API - https://{domain}/.well-known/acme/challenge/{token} ?for example, expected Response headers, Response body, Response http codes by the acme server ?

What kind of response does the server expect in case of error scenarios ? Example for the following error cases:

Invalid token format (400 BAD REQUEST)
File content not found (404 Not found)
Domain value in the Host header field does not match with the domain in the URL (403 Forbidden)

I see the RFC spec(rfc8555) only specifies the response in a success scenario where the expected file content was served by the http server.

   GET /.well-known/acme-challenge/LoqXcYV8...jxAjEuX0
   Host: example.org

   HTTP/1.1 200 OK
   Content-Type: application/octet-stream

   LoqXcYV8...jxAjEuX0.9jg46WB3...fm21mqTI
1 Like

I don't think you're going to find a lot of guidance beyond what's in the RFC. If the URL is what you expect, then send 200 and the code. If it's not, I'd probably just send a 404 and be done with it. If an ACME server is requesting something that's not what you expect, it's more likely a bug in your code (or in the proxy settings on the way to your system) than a bug in the ACME server, though I suppose it could be somebody else trying to fulfill a challenge for your domain when they shouldn't be.

I suppose you might want some diagnostic information (including the name/version of your client maybe?) at the very start of the body for an error condition, since the beginning of the body is returned to the user when a challenge request managed to connect to a server but the server didn't return the right token.

You might want to look at what major ACME clients (certbot et al) do when handling requests when running in "standalone" mode. It's probably the closest you'll get to how it's handled in practice.

3 Likes

thanks for the quick reply!

1 Like