
The sorry state of OpenSSL usability (2017) - anchpop
https://jameshfisher.com/2017/12/02/the-sorry-state-of-openssl-usability/
======
brynet
> Unfortunately, [http://www.libressl.org/](http://www.libressl.org/) won’t
> help you either, because there literally isn’t any documentation of
> LibreSSL.

This is untrue. The front page contains links to the documentation inline,
OpenBSD/LibreSSL converted all of OpenSSL's awful perlpod documentation to
semantic mdoc(5) markup, and even wrote new man pages for functions completely
undocumented by OpenSSL.

See Ingo Schwarze' EuroBSDCon 2018 talk "Better documentation - on the web and
for LibreSSL"

[https://www.openbsd.org/papers/eurobsdcon2018-mandoc.pdf](https://www.openbsd.org/papers/eurobsdcon2018-mandoc.pdf)

[https://youtu.be/jwfN7S1-fRA](https://youtu.be/jwfN7S1-fRA)

And earlier writeups from 2016.

[https://undeadly.org/cgi?action=article;sid=20161215221715](https://undeadly.org/cgi?action=article;sid=20161215221715)

It's been a long road to improve the documentation, and it's substantially
better than OpenSSL.

~~~
ivl
You're not wrong, but there's a big middleground here. To a user without some
curiosity this:

    
    
      LibreSSL releases contain several parts:
    
      libcrypto: a library of cryptography fundamentals
    
      libssl: a TLS library
    
      libtls: a new TLS library, designed to make it easier to write foolproof applications
    
      Various utilities such as openssl(1), nc(1), and ocspcheck(8).
    

With libcrypto, libssl, libtls, openssl, nc, and ocspcheck all links pointing
to man.openbsd.org/x does not scream documentation. The words 'documentation'
or 'manual' appear nowhere on the libressl home page.

They are undoubtedly _present_ , but unless you click around assuming those
aren't links to individual components, you wouldn't think so at a glance.

~~~
thepangolino
So what your saying the issue is libressl should put a link to the
documentation on their front page?

Sounds like a fair request. Perhaps someone should send them an email to let
them know.

That being said, you put a finger on the main issue most security and privacy
tool have: user friendliness.

~~~
PuercoPop
It _is_ linked to in their front page. The article is complaining about not
finding documentation for the openssl command while literally linking to the
front page that contains a link to said the documentation. They don't even
have to Google, just read!

~~~
nocman
I do think it would be a good idea for the libressl.org site to put a link on
the left "sidebar" with the text "Documentation" (which shows a page of links
at minimum), just to make it obvious where to find it.

That was the first thing I looked for, and it took me a while to realize that
the links "libcrypto", "libssl", etc on the main page were links to the
documentation for each command. In fact, the only reason I found them was the
fact that your post said "It _is_ linked to in their front page.", so I went
back to find them.

Yeah, if I'd needed it right now, I would have figured it out eventually, but
I think making it a bit more explicit (for lack of a better term) would be a
good thing.

------
eloy
> And stop forking OpenSSL; you’re just making things worse.

Yeah no. OpenBSD developers did a really good job by improving the codebase of
OpenSSL. See also some of their presentations:
[https://www.libressl.org/papers.html](https://www.libressl.org/papers.html)

~~~
crescentfresh
> by improving the codebase of OpenSSL

Just to clarify: LibreSSL forked OpenSSL [1]. By definition they did not
improve the codebase of OpenSSL.

[1]
[https://en.wikipedia.org/wiki/LibreSSL](https://en.wikipedia.org/wiki/LibreSSL)

~~~
zwerdlds
Didnt most of their changes get merged back?

~~~
aomix
Most of the LibreSSL changes were removing features or platform support so I
don't know how many of their changes were desired or applicable to OpenSSL.

------
notacoward
If you think the _user_ interface is bad, try the _programmer_ interface. OMG.
Layer upon layer of nonsensical objects to initialize and chain together, each
with a bazillion options and no decent documentation about which few are
secure. No decent interface for getting the specifics about an error. Not
thread-safe unless you create your own array of locking functions (which must
meet barely-documented requirements) and pass them in for the library to call
at random times. Weird WANT_READ/WANT_WRITE nonsense that makes integration
with a bog-standard poll/select loop more difficult. It's like the OpenSSL
developers think SSL is the main thing your program should be doing and you're
lucky they let any other functionality exist in the same program. The phrase
"fractal of bad design" was originally invented for PHP but applies to OpenSSL
just as much.

~~~
alias_neo
The developer interface is _much_ worse than the user interface. At least the
user interface had shell completions to guide your guess work. As you
suggested, having to initialise a bunch of things in some undisclosed order is
bordering on meddling with the dark arts, good luck tearing it all down again
safely. Then let's say you want to streaming-encrypt something on the fly,
good luck understanding the correct way to chain BIOs and what exactly the
behaviour for seeking, buffering, writing, closing, opening, decrypting,
reading, popping BIOs and then working with the remainder of the chain, before
pushing a BIO back on is.

I wrote a steaming data encryptor a little while back using openssl, just in
C, it works fine now but the majority of my reading was existing
implementations on the web and some out-of-date blogs coupled with some,
sometimes-correct documentation and just pain trial-and-error paired with my
good old friend Valgrind.

Unfortunately, in some industries it's go-FIPS-or-go-home, so we don't even
have the choice of using a fork or an alternative at times.

------
ergothus
A lot of comments here about LibreSSL and Apple vs OpenSSL. Which is fine,
that was my immediate reaction. But do the criticisms re:weak defaults,
unlabeled deprecated commands, and uninformative output apply? Because I'll
admit - every time I have to use (some version of) openSSL I google for the
command I need and blindly use it. The commands are cryptic and meaningless.

If this is true outside of LibreSSL, that definitely sounds like Apple is NOT
the problem in this case (though certainly not helping)

~~~
tialaramex
As someone who actually understands what is going on here I only partly agree.

The commands aren't meaningless, but OpenSSL approaches the problem from a
perspective that isn't what any ordinary user will want. Imagine you want to
post a package to Brazil. You see a shop selling postage stamps - perfect. But
of course such a shop is for stamp collectors.

They've got lots of Brazilian stamps (you don't need those at all). They've
got stamps from every decade (you need current stamps). They have rare stamps
(you don't want to pay extra!) and they have lots of used stamps (no longer
valid).

Until relatively recently OpenSSL would default to creating CSRs by urging you
to fill out largely irrelevant X.500 Distinguished Name and not even mention
SAN dnsNames even though most users who want a CSR want it for a TLS server
(e.g. web server) where the former is unimportant and the latter is vital.

When it comes to writing TLS client software you probably know the name of the
server you want to talk to. A sane API would let you tell the library this
once and do all the rest for you. But OpenSSL reflects the interesting (to
stamp collectors) half dozen different places that server names are involved
in different versions of the protocols, not this sane but boring API.

If you are a student of cryptographic history OpenSSL is great. If you are a
application developer it's... poor. If you're a regular end user it's awful.

~~~
ergothus
> You see a shop selling postage stamps - perfect. But of course such a shop
> is for stamp collectors.

That is a fantastic analogy and I'm stealing it for my own uses!

Thanks for the great breakdown.

------
CaliforniaKarl
I think this should be retitled to "The sorry state of OpenSSL usability [on
macOS]", because the author is using the built-in OpenSSL on macOS (which, as
is eventually discovered, isn't actually OpenSSL).

If you want to use OpenSSL on macOS, I suggest using the OpenSSL provided
either in Brew or in MacPorts. That will give you a fully-functional setup
(including help and man pages).

~~~
tedivm
Outside of the man page issue all of the complaints from the author apply to
all platforms that have openssl.

~~~
kevin_b_er
> Users matter: try doing some usability testing. Try adding some help text
> and man pages, instead of hijacking the wiki webpage of a different SSL
> project. And stop forking OpenSSL; you’re just making things worse.

1\. Apple is not usability testing this 3 year old version of a fork of
openssl, because they're not supporting it at all.

2\. help text not available because its an apple supplied fork. openssl does
tell you to use 'help'

3\. man pages do exist. Just not installed by apple like author expected

4\. and stop forking OpenSSL; BSD project forked it and Apple wants BSD over
anything else because they can put the software in their closed platforms.
Even if libressl were on the up and up, Apple's still got a version from 2016
installed.

Those are all Apple problems, not openssl problems.

~~~
tedivm
1\. The OpenSSL API hasn't changed, and if Apple changed it on their own that
would break more things

2\. The issue the author complained about was `openssl --help` not working,
and it doesn't work on any platform (because he got the command wrong).
`openssl help` does work on OSX (I literally just tested it).

3\. Yeah, that's the one issue we agree is an Apple issue.

4\. Apple didn't make LibreSSL. Other systems besides Apple use LibreSSL, and
the authors complaints about their lack of documentation are relevant
regardless of what Apple does.

~~~
clarry
> 4\. Apple didn't make LibreSSL. Other systems besides Apple use LibreSSL,
> and the authors complaints about their lack of documentation are relevant
> regardless of what Apple does.

No, this is specifically Apple's fuck up. The documentation is right there on
OpenBSD! It pretty much always was. I have a live system running OpenBSD older
than this rant, and the man pages are there. The default modulus is 2048 too.

~~~
tomxor
> I have a live system running OpenBSD older than this rant, and the man pages
> are there. The default modulus is 2048 too.

That's pretty hilarious if Apple changed the default from 2048 to 512!

------
closeparen
The Go crypto package is really a treat. I found it scary and incomprehensible
to do anything with certificates using the OpenSSL command line, convenience
wrappers notwithstanding. Adam Langley’s work shows what a reasonably
ergonomic and approachable interface for this domain could look like. Turns
out that issuing certificates doesn’t have to be dark magic.

------
beefhash
> OpenSSL decided to use a “512 bit long modulus”, the default. We’re told:
> “don’t roll your own crypto; instead trust standard tools like OpenSSL”. The
> modulus length is a good example of why: a wrong value results in a
> trivially breakable key, and you the user shouldn’t need to know what the
> right value is. So OpenSSL chooses a sensible modulus length for you.

Checking the OpenBSD man page for the LibreSSL genrsa, it does seem to
generate 2048-bit RSA keys by default[1].

Perhaps Apple just stuck with an older default (for backwards compat) or
perhaps this wasn't changed yet in the old version of LibreSSL that Apple
uses?

[1]
[https://man.openbsd.org/openssl#GENRSA](https://man.openbsd.org/openssl#GENRSA)

~~~
JdeBP
2.2.7 came out in May 2016. The switch to 2048 bits was in May 2014.

* [https://github.com/libressl-portable/openbsd/commit/30eb68d7...](https://github.com/libressl-portable/openbsd/commit/30eb68d7caa1f7d4cf5dafa69d294567f5213500#diff-a249ba52ce01b7d5770a4e6f88d10640)

------
avoidwork
`openssl help` ... the macos version hides the `Invalid command '\--help';
type "help" for a list.` message.

~~~
guitarbill
that's kind of annoying. at the same time, this also underscores the issue of
usability. why not alias "\--help" to "help"?

yes, i know even critical open source projects are extremely underfunded.
perversely, the lack of funding meant that there weren't enough people to
review code, which meant contributing was difficult - at least according to
this article from 2014 shortly after heartbleed:
[https://arstechnica.com/information-
technology/2014/04/tech-...](https://arstechnica.com/information-
technology/2014/04/tech-giants-chastened-by-heartbleed-finally-agree-to-fund-
openssl/)

~~~
JdeBP
Note that part of the problem is the erroneous assumption that "\--help" is
ubiquitous. It isn't, in practice. It's a GNUism that one does not find very
often in the BSD world.

~~~
guitarbill
fair enough, but still: how much effort would it be to support both?

------
minusf
libressl has documentation. it's an OpenBSD project so you use the man pages.

[http://man.openbsd.org/openssl](http://man.openbsd.org/openssl)

~~~
mhb_eng
Unfortunately, libressl is not FIPS 140-2 compliant, so you can't leverage it
for open source development of secure applications for the US government
(though this is more to do with the certification headache than a fault of
libressl itself)

~~~
snazz
This is not a priority at all for the OpenBSD developers. Most of them are
Canadian anyway, as I understand it.

~~~
upofadown
That is actually understating it. The libressl developers purged the code base
of the FIPS stuff as part of a policy. From here:

* [https://marc.info/?l=openbsd-misc&m=139819485423701&w=2](https://marc.info/?l=openbsd-misc&m=139819485423701&w=2)

"Note that FIPS mode isn't just worthless, it's actively harmful."

~~~
compuguy
Unfortunately if you work with the US Government, there are situations where
FIPS mode is _required_. This is why RHEL and CentOS still use OpenSSL...

------
garyb2
Just tried openssl genrsa on my Mac:

openssl genrsa Generating RSA private key, 2048 bit long modulus

openssl version LibreSSL 2.6.5

So maybe install Mac updates?

~~~
JdeBP
As pointed out in this discussion elsewhere, this is an article written in
2017 and never updated.

* [https://github.com/jameshfisher/jameshfisher.com/commits/mas...](https://github.com/jameshfisher/jameshfisher.com/commits/master/_posts/2017-12-02-the-sorry-state-of-openssl-usability.md)

------
parliament32
All of these complaints are MacOS problems. On my Debian laptop, "openssl
--help" actually displays some help (despite --help not being a real flag),
"man openssl" works as expected, and "openssl genrsa" uses a 2048-bit
modulus... and "openssl verison" confirms it's actually openssl.

------
bromonkey
manpages for openssl (`man openssl`) exist on Linux + Solaris + BSD, this
seems like a mac usability issue to me...

~~~
CaliforniaKarl
Apple deprecated OpenSSL in macOS some time ago, directing people to their
Core Crypto framework instead.

See [http://stackoverflow.com/questions/7406946/why-is-apple-
depr...](http://stackoverflow.com/questions/7406946/why-is-apple-deprecating-
openssl-in-macos-10-7-lion) for more info and links

------
CiPHPerCoder
My question is: Why are you trying to use RSA at all?

It's 2019! I can't think of anyone who seriously recommends RSA anymore.
Switch to elliptic curve cryptography, where footbullets like a 512-bit RSA
key offer aren't even on the table.

~~~
recursive
> Why are you trying to use RSA at all?

Probably because you have to use _something_ , and it's not obvious which
things have footbullets and which don't.

~~~
CiPHPerCoder
[https://latacora.micro.blog/2018/04/03/cryptographic-
right-a...](https://latacora.micro.blog/2018/04/03/cryptographic-right-
answers.html)

[https://paragonie.com/blog/2017/06/libsodium-quick-
reference...](https://paragonie.com/blog/2017/06/libsodium-quick-reference-
quick-comparison-similar-functions-and-which-one-use)

[https://libsodium.gitbook.io/doc/bindings_for_other_language...](https://libsodium.gitbook.io/doc/bindings_for_other_languages)

It's a lot easier in 2019 than it was years ago.

------
GTP
If on macOS openSSL is replaced by LibreSSL isn't OpenSSL's fault, and I also
think that the title "The sorry state of OpenSSL usability" isn't right since
it's actually talking about LibreSSL. By the way I've just ran "man openssl"
on a Linux box and got the manual for OpenSSL, so I'm thinking that this could
be more a problem of macOS than OpenSSL. Of course I agree that the online
docs should say if something is deprecated or is using a default value that is
no longer safe, but the rest of the article doesn't seem well made to me

------
low_key
Sure, the commands are difficult to digest. Where it gets truly awful, though,
is trying to write a program that uses the openssl library.

------
mtgx
Use Noise then:

[https://noiseprotocol.org/](https://noiseprotocol.org/)

[https://github.com/mcginty/snow](https://github.com/mcginty/snow)

