Clarifying the 'how it works' for Domain Validation

Server
1

When I started investigating LetsEncrypt, I read https://letsencrypt.org/how-it-works/ and thought I knew what was going on.

My conclusion having finally got things working for a web server (WAS Liberty profile) with no obvious working agent on WIndows is that the how-it-works skips very nonchalantly around some very important details that if they were mentioned might avoid some disappointment/frustration when being stopped by these details not being clear and having to be learned the hard way.

NOTE I don’t have any objection to these details, they all seem reasonable and necessary for the domain validation process to be robust, what I am complaining about is that they aren’t explicit in the how-it-works.

  1. http challenge for the first (bootstrap) issue of a cert MUST be on port 80 because I haven’t yet got a CA cert and the process (perfectly reasonably) rejects connecting using self-signed cert in my webserver on 443. This means that where the how-it-works talks about “Provisioning an HTTP resource under a well-known URI on https://example.com/” what it means is “Provisioning an HTTP resource under a well-known URI on http://example.com/ and the webserver must be on port 80”

  2. That same nonchalant statement “Provisioning an HTTP resource under a well-known URI on https://example.com/” means you (the agent) need access to the production webserver filesystem on the domain and if you haven’t got that there’s no point continuing. Again this isn’t unreasonable, but by not being specific about this right at the front, the how-it-works leaves potential users to bash up against this requirement later after they have spent time and energy trying to get it working.

  3. While it is technically reasonable to use “http” and “https” as shorthand for an HTTP protocol server running on well-known ports 80 or 443, I think the fact that these ports are explicitly required by the ACME standard means it is import to be explicit about the ports being used, and also that port 80 MUST be used for the bootstrap Domain Validation.

Overall, I’d like how-it-works to include a more precise/complete summary of the pre-requisites for Domain Validation, for example:

  • http challenge requires the (production) domain webserver to be on port 80 for the first issue of a certificate. Renewals can be on 80 or 443.
  • http challenge requires you or the agent to be able to manually/automatically put a file onto the production webserver on the domain for retrieval by the DV process
  • dns challenge requires you or the agent to be able to manually/automatically add a detail to the dns server record for retrieval by the DV process

Overall, though, Let’s Encrypt is a great piece of work - well done!

2

This isn't the case - Let's Encrypt will happily accept a redirect and connect to an HTTPS connection even with a self-signed certificate. It will always initiate the connection over HTTP on port 80, but if you serve a 30x redirect to HTTPS, Let's Encrypt will follow that.

This is misleading as well - renewals also have to be on 80, but as mentioned before, redirects are allowed.

I think a big point to note is that the "How It Works" guide doesn't strike me as a manual as much as a technical bulletin. You should probably refer more to documents like the Getting Started guide for that.

3

So correct me, I don’t mind, then update the how-it-works please. It won’t take adding many words to make it much more enlightening.

I started from the Getting Started and that’s got absolutely ZERO technical detail: all it says is effectively ‘here use one of these ready-built agents’ but there wasn’t one I could use directly so I started with what I knew using acme-tiny, struggled with a then-incompatibility with the then openssl on windows, and finally got there via trying to get http-01 to connect on 443 to my self-signed cert and failing and then moving to port 80 and it works.

From everything you say, that statement “Provisioning an HTTP resource under a well-known URI on https://example.com/” MUST at least be corrected to read “http://example.com:80/ (i.e. on port 80)” because regardless of the ability to redirect the initial connection must be on port 80.

Anyway, whatever.

4

I agree with @jared.m that we don’t really mean for people to use this page as a guide for getting certificates, but I also agree with @barny that this page ought to be more explicit about what the technical requirements are. (And also that the reference to provisioning a file in an https URI is outright wrong and needs to be corrected to http!) So, thank you for the feedback and suggestions and I’ll make a note to improve the page as you indicated.

5

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