> And stop forking OpenSSL; you’re just making things worse.
I strongly disagree that forks are making things worse. The solution to a project that is too difficult to fix due to baggage or a bad community or bad maintainers is to fork.
Exactly, the fork is done for the sake of maintaining the code, not the communities. Saying a fork without docs is evidence no forks should exist is throwing the baby out with the bathwater - by comparison, you would never consider a base project without docs to need shutting down just on that alone.
Unfortunately, http://www.libressl.org/ won’t help you either, because there literally isn’t any documentation of LibreSSL.
Going to that website and clicking on openssl reveals a manual page. So, I guess the "literally isn’t any documentation" is wrong. OpenBSD likes their man pages.
Not to mention summary pages to each of the three libraries provided by libressl. On each of those there are then links to man pages for each function offered by the libraries.
Not sure what he's missing, I've always found OpenBSD's documentation to be first class.
Yes. That’s the most prominent OpenSSL link on that page. And as someone pointed out elsewhere, “There are links to the documentation, but they're not labeled as such. They're labeled as though they're links to download the components.”
While I wouldn't call macOS "shit" you're not wrong. On a Slackware 14.2 box and an OpenBSD 6.2 box I just tried both man openssl and openssl --help work fine.
edit: Actually --help does start by saying --help is an invalid command but that's easy to miss because you then get a standard usage command with a basic summary to get you started.
Unfortunately, from my perspective, the same situation is actually common with a lot of security libraries/tools. Usability and documentation often seem to be sub-standard. The API themselves are mostly not build around the “common” use cases.
I was always asuming that’s caused by the orginal programmers being more interested into the crypto algorithmics than building an actual useful tool. But what do I know.
My solution so far is to wrap crypto code into own modules and expose only the most simple interface for the job.
For the cli, especially openssl, I am relying on (customized) scripts to make common tasks easier, with my ultimate goal to not have to call openssl directly anymore.
It's funny to me when people complain about something they get for free. There are at least two solutions to this problem and neither of them are writing a blog to complain about the work that someone else has done and given a way for free.
You could write some documentation and give it to them. Or you could pay someone to write it for the project.
The author seems to know quite a bit about OpenSSL/LibreSSL. I'd think writing up a bit of documentation for it would be a win for everyone. Writing a blog complaining that the authors haven't done it and given it away for free is not.
But there is documentation for LibreSSL. As an OpenBSD project they take documentation just as seriously as code. I just don't get how the article makes that claim when there are links to any man page you need here: http://www.libressl.org/
It does not have a "documentation" link. It does not even say "man pages" anywhere on the page. ALso, the man pages go to something called "openssl", and when I click on the link, there is no "libressl" on the resulting page. Am I still on the libreSSL site? Is the libreSSL API exactly same as OpenSSL API? I have no clue. If it is, it does not say so, if it is not, it does not say so. What a mess.
He could, but you seem to be expecting him to do this work for free. The article he’s written is useful, informative and free, so you seem to have a catch-22 when you criticise him for not going further.
The usability points in this post are very well taken, but I'd push back on "we're told not to roll our own crypto but instead to use OpenSSL", since the first part of that claim is true but the second is emphatically not.
I see where you're coming from and there's obviously some truth to it, but even an exceptionally well-documented OpenSSL with carefully thought-out command line UX would still be dangerous just by dint of what OpenSSL (as in, the "openssl" CLI) sets out to do, which is to provide an interface to low-level cryptography.
would still be dangerous just by dint of what OpenSSL (as in, the "openssl" CLI) sets out to do
Of course. What I'm getting at is "don't roll your own crypto" is one of the things that gives people a false sense of confidence in using the low-level crypto facilities. It might as well not be true for all the good it does the people it's supposed to help. I guess 'emphatically' is what I'm responding to, the 'don't roll' thing is, effectively, not that great either.
> there literally isn’t any documentation of LibreSSL.
This is plain wrong, it's particularly annoying as a great deal of effort has been put into updating the documentation [1].
> Instead, you just have to read the OpenSSL docs, and just hope the behavior is roughly the same.
I'll give the author the benefit of the doubt and assume they refer the "OpenSSL docs" as naming hasn't been changed, as opposed to looking at actual OpenSSL documentation. Indeed it doesn't make a great sense rename everything in the documents because as the LibreSSL website states.
libssl: a TLS library, backwards-compatible with OpenSSL
libtls: a new TLS library, designed to make it easier to write foolproof applications
Maybe I'm missing something - could you link me to the docs on http://www.libressl.org/? I expected a big link saying "Docs", but I don't see one. I've also tried a Google search for the docs[1], without success.
That page claims to be docs for OpenSSL. Is that incorrect? If it actually is docs for OpenSSL and not for LibreSSL, where's the LibreSSL-specific docs gbrown_ was talking about?
44 comments
[ 5.1 ms ] story [ 97.4 ms ] threadI strongly disagree that forks are making things worse. The solution to a project that is too difficult to fix due to baggage or a bad community or bad maintainers is to fork.
Going to that website and clicking on openssl reveals a manual page. So, I guess the "literally isn’t any documentation" is wrong. OpenBSD likes their man pages.
Not sure what he's missing, I've always found OpenBSD's documentation to be first class.
Other links take you elsewhere. Like OpenBSD man pages for libs. He didn’t need a lib.
Yes, the LibreSSL pages contains in total 0 man/docs/wiki pages. Instead it points to external websites.
So, in order to find documentation, one would have to land on LibreSSL webpage and click on all links hoping to get to the correct one.
> Going to that website and clicking on openssl reveals a manual page
Please tell me where the very first OpenSSL link takes you. That's the one I clicked just to check.
Oh, right, it has to be the openssl(1), helpfully hidden away in the list of various utilities.
Are you referring to the line informing the reader that LibreSSL is a fork and provides a link the the OpenSSL project?
edit: Actually --help does start by saying --help is an invalid command but that's easy to miss because you then get a standard usage command with a basic summary to get you started.
I was always asuming that’s caused by the orginal programmers being more interested into the crypto algorithmics than building an actual useful tool. But what do I know.
My solution so far is to wrap crypto code into own modules and expose only the most simple interface for the job.
For the cli, especially openssl, I am relying on (customized) scripts to make common tasks easier, with my ultimate goal to not have to call openssl directly anymore.
You could write some documentation and give it to them. Or you could pay someone to write it for the project.
The author seems to know quite a bit about OpenSSL/LibreSSL. I'd think writing up a bit of documentation for it would be a win for everyone. Writing a blog complaining that the authors haven't done it and given it away for free is not.
> (bso) larrik@local:~/bso$ openssl --help > openssl:Error: '--help' is an invalid command.
It lists a bunch of valid commands, though. Of course, you can't do `openssl help genrsa` or anything sensible like that.
E.g. OpenSSL on OpenBSD does have a man page. But unfortunately no --help, at least on my older version.
Also, on OpenBSD his example of generating an RSA key creates one with a 2048 bit modulus.
Of course. What I'm getting at is "don't roll your own crypto" is one of the things that gives people a false sense of confidence in using the low-level crypto facilities. It might as well not be true for all the good it does the people it's supposed to help. I guess 'emphatically' is what I'm responding to, the 'don't roll' thing is, effectively, not that great either.
This is plain wrong, it's particularly annoying as a great deal of effort has been put into updating the documentation [1].
> Instead, you just have to read the OpenSSL docs, and just hope the behavior is roughly the same.
I'll give the author the benefit of the doubt and assume they refer the "OpenSSL docs" as naming hasn't been changed, as opposed to looking at actual OpenSSL documentation. Indeed it doesn't make a great sense rename everything in the documents because as the LibreSSL website states.
[1] https://undeadly.org/cgi?action=article&sid=20161215221715[1]: https://www.google.co.uk/search?q=site%3Alibressl.org+docume...