
The sorry state of OpenSSL usability - jamesfisher
https://jameshfisher.com/2017/12/02/the-sorry-state-of-openssl-usability
======
gbrown_
> 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](https://undeadly.org/cgi?action=article&sid=20161215221715)

~~~
jamesfisher
Maybe I'm missing something - could you link me to the docs on
[http://www.libressl.org/](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...](https://www.google.co.uk/search?q=site%3Alibressl.org+documentation)

~~~
nagvx
The section on [http://www.libressl.org/](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](https://man.openbsd.org/openssl)

~~~
mort96
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?

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

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

~~~
smhenderson
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/](http://www.libressl.org/)

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

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

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

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

~~~
pvg
_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.

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

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

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

------
protomyth
_Unfortunately,[http://www.libressl.org/](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.

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

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

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

~~~
gbrown_
> 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?

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

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

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

------
goloroden
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...](https://www.thenativeweb.io/blog/2017-12-29-11-51-the-openssl-
beginners-guide-to-creating-ssl-certificates/)

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

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

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

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

------
w00bl3ywook
wtf.. donate/contribute

