Let's make Let's Encrypt easy and simple


#1

Let’s Encrypt is about letting anybody use HTTPS to secure their website.

Our home page implicitly promises that securing any website will now be an easy process, no longer even in Beta, and not the difficult series of steps that securing a site used to be.

Most folks who run small websites know how to use parts of management tools like CPanel or Plesk. They don’t know how to use certificates and certificate tools. They may not have much knowledge of how Linux commands work, the directory structure of the Linux file system, or how Apache config file directives work.

Since Let’s Encrypt is now claiming to be meeting its goal, right on its home page, we have to make Let’s Encrypt accessible to everyone now. This means improving the current documentation.

CPanel will offer Let’s Encrypt soon, hopefully in a simple way. Until then (and even after then), instructions for using Let’s Encrypt on the LE website need to be short, easy to understand, and must just work. The documentation must be a lot better than it is at the moment.

The letsencrypt.org Get Started page needs to explain clearly what our tool is, how to install it, and how to use it to get and install a new certificate, and even how to convert an existing website to HTTPS. The current home page has one and only one obvious link to provide this guidance: Get Started, which points to https://letsencrypt.org/getting-started/.

This Getting Started page is totally confusing for the vast majority of people who run small servers. We can see this by reading this forum, which is filled with confused questions. It is totally confusing for me, and I’ve been a professional software engineer for 40 years and a web designer for several years.

One of the confusing commands currently on this page is:

certbot certonly --webroot -w /var/www/example -d example.com -d www.example.com -w /var/www/thing -d thing.is -d m.thing.is

What, exactly, does this command do? Which of the strings here are literals, and which are placeholders, meant to be substituted? Which of these strings are pathnames that already exist on all Linux systems? Which are pathnames of directories or files that the user is supposed to create? Why isn’t there a detailed and clear explanation?

Why isn’t there a nicely formatted, step-by-step list of instructions that anyone can follow to secure their website? Why aren’t we fulfilling our promised strategy of making it easy to secure any website?

Forget what you know about HTTPS, certificates, certificate authorities, and how Linux, Apache, Nginx, IIS, sockets, tools, etc., work. Let’s have a competition to write clear, simple explanations of our procedure with clear examples, both ordinary simple examples and some more complex examples.

Just my opinion. No criticism of any person is intended, or of the project.


#2

I’m not sure if this is an opinion piece ( which is what you say at the end) … a request for comment ? or you want answers to those specific comments.

Feel free to help improve the documentation.


#3

serverco, Yes, It most certainly is an opinion piece. Yes, it is a request for comment, if anyone seriously disagrees with me. But it is primarily a call for action, a challenge for those who know how Let’s Encrypt works to secure a website automatically to explain how to use it in simple, easy to understand language.

And, yes, I have published this message in an attempt to improve the documentation.


#4

I don’t disagree with your sentiment that things can be improved ( although I disagree with a number of specific comments you make - however having an argument over those will not help anyone).

Let’s Encrypt, I’d say, has been designed as a process with the aim of letting everyone get HTTPS more easily through automation. As such it’s designed to work with the common web ‘engines’ like apache and nginx etc. Having said that, there are many many different web ‘control panels’ such as cpanel, ISPconfig, Plesk etc which also modify the apache / nginx files. I don’t anticipate that “Let’s Encrypt” is ever going to write the individual software to work with all those individual packages. That is for those "control panel"s themselves to incorporate (if they so wish).

I don’t believe there will ever be a simple piece of documentation that covers all. There will ultimately be good documentation for LE use with cpanel within the cpanel documentation though I believe ( and likewise for plesk, ISPconfig etc).

At the moment, I’d have said that Lets Encrypt works fairly well for dedicated servers, and places where people have root access. How effectively it works on shared servers depends very much on the host, who is looking after that server, what control panel they have etc. There are many hosts who have incorporated scripts that make it single click to add an LE certificate and many who don’t support it at all.

If you would like specific help with your setup, then there are people here to help, just let us know exactly what your system / configuration is, and what you’d like to achieve on that configuration.


#5

Documentation can always be improved further, but I do believe that the new certbot homepage has gone a long way in solving this problem by providing detailed instructions specific to your OS and web server software. The getting started page could probably use some refinements in light of this new release (which just happened yesterday), agreed. The state of SSL deployments in the wild unfortunately doesn’t allow for one ultimate guide or tool to exist that will cover every possible edge-case, but I think we’re at a point where there are guides available for nearly every stack imaginable.

One of the goals of Let’s Encrypt is to allow software vendors to provide HTTPS for their users without having to do anything. Projects such as Caddy, but also existing plugins for control panel software such as Plesk show that this strategy is working quite well, and at this point most control panel software vendors have plans to add support for ACME sooner or later. This project hasn’t been live for even a full year yet, and we already have packages in most linux distributions, as well as a huge ecosystem of ACME clients, with support for essentially all platforms. I’m sure that, given enough time, ACME will soon be a thing that, like, say, NTP, we all use, maybe have a basic understanding of, but don’t really have to care about because It Just Works.


#6

let’s encrypt documentation is not developer friendly.
already spent more than 72 hours continuously without sleep still i am unable to get dns challenge validation working. :disappointed:
may be letsencrypt was created to be used only by its own developers . that is what i feel seeing the documentation.
i don’t even know which one is official documentation
https://tools.ietf.org/html/draft-ietf-acme-acme-01#section-7.5
or
https://letsencrypt.github.io/acme-spec/#rfc.section.7.4


#7

serverco, I agree with what you say. Utimately, integration with management control panels will be a major step to achieving the LE goal.

I especially agree with your statement, “At the moment, I’d have said that Lets Encrypt works fairly well for dedicated servers, and places where people have root access. How effectively it works on shared servers depends very much on the host…”

In fact, this major current limitation needs to be highlighted on the Getting Started page. People have to understand exactly what LE supports and what it does not support.

I don’t have any “setup” and I don’t need help. I’m trying to get the documentation improved.


#8

https://tools.ietf.org/html/draft-ietf-acme-acme-01 (acme-01) would be the draft that boulder, the CA server behind Let’s Encrypt, is currently tracking for the most part. The other link is a different/older version of the draft.

There’s a large number of clients that wasn’t developed by anyone related to Let’s Encrypt. Maybe reading the existing implementations would help with writing your own?


#9

thanks i will try to learn from other LE clients.:relaxed:


#10

pfg, I appreciate your comments, and agree that LE is being accepted quicker than expected by software vendors. It is a wonderful situation, and LE is to be congratulated on its articulation and for proposing a practical path to universal secure websites.

Nevertheless, I’ll stand by my publicizing the very poor documentation we are currently offering under an implied offer of ease and simplicity. I do agree with you that someday very soon the LE website will no longer have the central importance it now has, and new sources of documentation will undoubtedly appear.


#11

hotwap, Thank you for supporting my claims that the existing documentation (“Getting Started”) is woefully inadequate for such an important project.


#12

pfg, Two major limitations of the new certbot homepage, which you recommended above, are that it does not cover my hosting environment (Centos) and will not help anyone wanting to turn an old Windows computer into a secure webserver with little effort.

If LE is truly out of Beta, it should install a working certificate in any common server, and should have simple documentation for doing it. Any limitations should also be documented clearly.

My criticisms are not aimed at you or any person, only at a project that is evidently too self-satisfied to bother documenting what it is offering to the world as well as other projects (say, jquery) are documented.

Assuming the user is a website administrator (has the appropriate passwords), I believe that it is possible for a Linux or Windows based tool to ask the user a few questions (mostly the questions needed for a Certificate Request), then automatically take care of obtaining and storing the certificate, making an entry in a renewal database, and doing anything else that is necessary to convert a server to HTTPS operation under popular server software. I don’t believe that LE is ready to work this way, reliably, as yet. I believe that the sketchy documentation may be a way to hide the fact that LE is not completely ready as yet. Just to be frank.


#13

Am I missing something - it has CentOS/RHEL 6 and CentOS/RHEL 7


#14

Wow, Have you hit the nail on the head David.

By way of background, I’ve had web sites here and there since sometime in the nineties, have been exclusively Linux on the desktop for most of that time, and aren’t the least bit afraid of the command line or mucking about.

My current project is moving some small sites from shared hosting to an EC2 instance, and I’m finding that fun and easy despite a bit of a learning curve. It is though my first time doing stuff via SSH and not a panel of come sort.

I like it.

I was certainly aware of Lets Encrypt, and loved the idea. I had assumed it was aimed at “regular” users, not just hard-core, full-time sysadmin types. I assumed that I could swing over to the Lets Encrypt web site and have a functional certificate in a fairly short time period.

I’m reasonably smart, reasonably skilled, and can follow instructions.

Yet at “How To Use The Client” I hit a brick wall, and haven’t a clue where to go from there.

I’m dismayed that so many of the people responding to you answer by complaining that it’s not their problem to write decent documentation, or with that hoary old canard “if you don’t like it, YOU write it!”

Takes me back to the bad old days of having some loudmouth yell “READ THE FRIGGIN MAN PAGES!”

For a group like the EFF, and for a project which is aimed at least somewhat at the layperson, or the less skilled person, your suggestion is absolutely right.

If you or I can’t figure out how to make this thing work (without investing way too many hours of blind alleys and trial and error) there’s no chance that more ordinary people will ever be able to use it.

As it stands now LetsEncrypt is really only approachable by people who already had the skills and knowledge to set them selves up with a certificate by other means.

Which kind of defeats the purpose doesn’t it?


#15

As @serverco mentioned, CentOS (as well as pretty much any other UNIX-like OS) is supported. Windows support in certbot is pending, but there are a number of high-quality clients out there that do support Windows and even provide things like automated configuration for IIS and auto-renewal.

Let’s Encrypt (the CA) is out of beta because the infrastructure was deemed stable, and the adoption numbers showed that many people were quite successful in implementing Let’s Encrypt. The ACME ecosystem has produced clients for all major platforms.
Certbot, the client, is still beta-quality software. It is now also developed by a separate team and organization in order to promote a healthy client ecosystem.
It is very much possible to use Let’s Encrypt in any environment where you’d be able to use a domain-validated certificate from any other CA. In fact, it is significantly easier and can be automated completely in most environments, which is something that essentially no CAs did before Let’s Encrypt. I don’t think any of them would call themselves a beta service either.

For every project like jQuery with excellent documentation, you have 10 projects with abysmal documentation. That certainly shouldn’t be the benchmark Let’s Encrypt or certbot uses, but I do think that the documentation that does exist is fairly accurate. Is there room for improvement? Sure, that’s true for most things, and I certainly agree with regards to the “Getting started” page. Is it still possible for users with at least a small amount of experience with regards to programming, web development or server administration to find documentation on how to use Let’s Encrypt on their platform? Personally, I haven’t found a single case where a simple Google search for “letsencrypt $platform” hasn’t yielded at least 10 how-to’s.

It’s worth pointing out that more than 90% of the domain names that got a certificate from Let’s Encrypt never had a certificate from any other publicly-trusted CA before. If you’d like to share the issues you ran into, I’m sure this community would be happy to assist.


LE on AWS EC2 AMI for Beginners
#16

Appalbarry, Thanks for your supportive position, and for sharing a few of your experiences. Everyone in development for long enough has experiences like yours. I agree with all your points, just don’t forget what is actually new with LE: their finding a CA willing to originate a free CA, already present and accepted in all modern browsers. This is the key that will make secure websites a reality, not really the ACME client. Someone had to be brave enough to risk their own profits in order to improve the infrastructure of the Web.

There are other areas that also need similar transformations. For example, because we live with it, we assume that there will always be spam and malware sent (directly and indirectly) through email, simply because the original Internet standards (RFCs) for email assumed a cooperative (utopian) environment. But, someday soon, mark my words, there will be a similar pioneering project to create a new email architecture, free from malware and spam via a very few elegant principles.

History shows that even when a problem has become almost universal through history and acceptance, change can still come. All it takes is intelligence, creativity, insight, compassion, and courage. These are all human qualities, and we all have them.


#17

Good points all, and I generally avoid flogging dead horses, but feel compelled to comment that “Just Google it” is really the 2016 equivalent to “Read the Man pages” and about as useful.

It presumes a level of prior knowledge that may not exist, which is in itself always a challenge when developing documentation.

More importantly though, it assumes that the user will manage to pick the one Google result out of ten, twenty, or a hundred, that is actually useful.

i use Google and forums a lot when diving into something new or resolving a sticky problem, and know too well that can be very hard to find the “how-to” or answer that is a) correct b) applicable to your software version or c) not missing some critical but essential step that it is assumed you’ll already know.

The reason why it matters here and now is that (I’m assuming) Let’sEncrypt is going to attract a lot of people who have never dealt with certificates before - which I assume is one of the primary goals - or who just let their ISP or hosting company handle the details in the past.

They’re the people who’ll see “It’s free, automated, and open. Get Started” and assume that they’ll be getting some kind of one-click install.

At which point they’ll walk away and carry on with an insecure site, free certificate or not.

In broad terms I have to agree that we all need to take security much, much more seriously, and applaud the Lets Encrypt folk for a wonderful initiative.

But that facility is only half of the equation - end users, especially those with reduced knowledge or skills sets, need to be supported - arguably more than the high skilled folk who can figure things out on their own.


#18

From my perspective, one issue here is that saying “the documentation isn’t good enough” (which no one is disagreeing with) doesn’t help.

If you have a specific issue, that you can’t understand how do do, because it’s not in the documentation, then please ask about that specific thing. That way, an answer can be provided so that you can obtain a certificate, and also people understand then a specific point where the documentation needs to be clearer.

I’m not an employee, or have any link to Let’s Encrypt, I appreciate what they are trying to do, and hence put some of my time aside to help others. The documentation was good enough for me to obtain certificates, and also to write my own client for issuing certificates - hence I have a reasonable understanding of how the system works. Since I understand how the system works, I don’t read the documentation in the same way as a new user. If you really want help either getting a a certificate, or improving the documentation, please be specific about things ( rather than the generalisations of “it’s not good enough” - as I don’t know how to improve “it’s not good enough” but I do know how to improve "in page X of the document at Y I don’t understand what it means by the line zzzz " or "my system is qqqq which the documentation doesn’t mention - where do I start "


#19

Appalbarry, Thank you! Beautifully put.


#20

serverco,

Thanks for your clarifications.

“one issue here is that saying ‘the documentation isn’t good enough’ (which no one is disagreeing with) doesn’t help.”

Not so; it does help. If no one points out a big problem, the problem will simply remain. The evidence is that no one working to develop LE has much interest in developing high-quality, clear easy-start documentation that will help the audience of LE to gain the enthusiasm to give it a try and become a convert. Appalbarry expressed this perfectly.

“If you have a specific issue, that you can’t understand how do do, because it’s not in the documentation, then please ask about that specific thing.”

No, that is not the best way to view either documentation or software. Applied to software, you are saying something like, “yes, we know the software is buggy, but until we have your set of specific bug reports we have no way to fix it. All the software works perfectly for me, so I can’t know what problems you are encountering.”

The point here is that if our solution is “free, automated, and open. Get Started”, then forcing visitors to have a bad experience on the Get Started page shoots ourself in the foot. Offering even an interactive chat panel on the Get Started page to hold the visitor’s hands cannot compensate for a bad experience with the initial documentation.

Compare with other ambitious projects like Angular, jQuery, Prezi, Weebly.com, Google AdWords, Python, and so many others that, whether complex or simple, work right away either full-scale or starting with easy examples, thanks to great documentation). We not only fall short, we fail.

Also, it is beyond the project’s resources to answer the thousands of questions we would have if our entire audience visited our site as we might secretly desire. Already, we have seen LE been more successful than anticipated. Do you really want us to be overwhelmed with interest and visits and become the next Internet news about a failed project? Please abandon this tired old advice. Yes, it is clear that you believe it, but belief is not enough; clarity, honesty, and courage are also useful (reference: the Emperor’s New Clothes, by Hans Christian Andersen).

“and also people understand then a specific point where the documentation needs to be clearer.”

Neither documentation nor software should be developed by fixing bugs. Fixing bugs is the last resort, and even that process should be done as early in the development as possible (reference: almost everyone who has written about the software development cycle).

If you don’t know how to write clear, simple, appealing, and adequate documentation, as you seem to be claiming, then we simply find someone else in the project who does. If no one does (which is possible, since this has been primarily an engineeering project), then we should hire an outside person with a good track record for doing the job. Documentation, like software development, requires unique skills.

“I appreciate what they are trying to do, and hence put some of my time aside to help others.”

And I thank you. I’m sorry to be so forceful here, but it’s an important area that has been neglected, and your latest post doesn’t seem to help. I have no intention to criticise any person on the project, and certainly not you (you have spent much time on this thread alone, which I appreciate). I try to focus my criticism on the issues.

“The documentation was good enough for me to obtain certificates, and also to write my own client for issuing certificates”

I am happy to hear of your success. I would be interested in knowing your training and experience and to compare it with the median training and experience of the potential audience for our technology. Nowhere on the LE website is a list of required training and experience specified, therefore it appears that our audience is anyone who runs a webserver. That includes people who use shared hosting (who are currently not served by the Get Started solution), anyone who runs a Windows webserver (who currently are not served by the Get Started solution, and are not served at all if they don’t want to install python and other doo dads that make Linux developers happy), and people who have no idea how certificates or command lines work, who are also not served by the Get Started solution as it is currently documented (and, perhaps, as it is implemented).

Our documentation does not present the expected training and experience required of our current technology, nor does it present any limits of that technology. It is just a cheerful, promising claim backed up by a documentation and technology that does not match the claim. LE is poised to fail as a result of its success.

“I don’t read the documentation in the same way as a new user.”

If you don’t have the ability to recognize poor documentation (defined as not matching the audience), that is fine. As a software developer you can be a great contributor. Just don’t get in the way of finding someone who can write great documentation, perhaps someone with technical writing experience. Feeling that you yourself must take on the responsibility to improve the documentation means taking on more responsibility than you can handle; that is not good for you or the project (reference: https://en.wikipedia.org/wiki/Peter_principle).

Each contributor should work within their limitations, and not force others to be “specific” in making problem reports when the basics have not yet been covered clearly or completely.

Again, I am trying hard not to criticize you, but your posting is getting very personal about how you read documentation and how you like your problem reports. It is fine to express your opinion, but please state it as opinion and not as The Required Way We Do Things, okay? (Oops, unless this is not really an open software project but you are actually the project manager and in charge of everything, in which case I humbly apologize for my inappropriate suggestions.)