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.
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”
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.
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!