The sorry state of OpenSSL usability | Hacker News Reader

The sorry state of OpenSSL usability

jameshfisher.com

78 pointsjamesfisher37 comments

> 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

[1] https://undeadly.org/cgi?action=article&sid=20161215221715

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.

[1]: https://www.google.co.uk/search?q=site%3Alibressl.org+docume...

The links for libcrypto, libssl, libtls, openssl(1), nc(1), and ocspcheck(1) all go to online man pages.

The section on http://www.libressl.org/ that starts with: "LibreSSL releases contain several parts" lists said parts, with links to manpages for those parts. For example: https://man.openbsd.org/openssl

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?

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/

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.

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.

The second part is a direct consequence of how malleable and easy to misinterpret the first part is. It's a 'usability' problem of its own.

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.

This is a macOS problem. OpenSSL on Linux has extensive man pages and a --help switch.

I just said the same thing but Mac OS seems to be sacred here...

On Linux Mint 18:

> (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.

Funny that is what you get in Linux Mint, given that it is based on Debian and on Debian (stretch) you get...

    $ openssl --help
    Invalid command '--help'; type "help" for a list.

Maybe Linux Mint 18 is based on an older version.

The big problem is so many different versions between operating systems. Everyone wants to fiddle with code.

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.

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.

Clicking on OpenSSL takes you to OpenSSL wiki, and he talks about the wiki vs. man pages at the very beginning of his article.

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.

openssl(1) links to https://man.openbsd.org/openssl

It took me a while to find where the link to openssl(1) is on that page.

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.

No, it takes you to the OpenBSD man page wiki, not the Open SSL wiki. But the tool is still named OpenSSL for interoperability.

Original quote:

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

> Please tell me where the very first OpenSSL link takes you. That's the one I clicked just to check.

Are you referring to the line informing the reader that LibreSSL is a fork and provides a link the the OpenSSL project?

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

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

Inspired by your blog post, I've written a small tutorial on how to use OpenSSL for creating SSL certificates: https://www.thenativeweb.io/blog/2017-12-29-11-51-the-openss...

On my Ubuntu 16.04 system, `man openssl` works just fine for me.

One could export the man pages from another *nix and import them into OSX perhaps?

If your OS is "shit", don't blame others for this. "man openssl" perfectly works on correct OS and you can ask "--help" for all commands.

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.

wtf.. donate/contribute

Reply on news.ycombinator.com