The sorry state of OpenSSL usability (2017) | Hacker News Reader

The sorry state of OpenSSL usability (2017)

jameshfisher.com

161 pointsanchpop79 comments

> Unfortunately, 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://youtu.be/jwfN7S1-fRA

And earlier writeups from 2016.

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.

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.

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.

In many ways user friendliness corresponds directly with real life security level. Lots of compromises aren't due to a deficiency in the code, but someone using it incorrectly. Maybe by assuming the defaults are sane, or not understanding the implications of some of the technical jargon in the manual.

Remember Sony, a 60 billion dollar company, completely fubared the DRM on the Playstation 2 because a developer didn't understand what an IV is. And you go through the OpenSSL docs and it will tell you where to supply your IV without ever explaining what it is. All it needs is a single paragraph explaining the best practices, probably 5 or 10 lines in the manual.

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!

Unfamiliar people might not realize openssl(1) is linking to the manual page for openssl, or that it's in section one of the manual, thus the (1).

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.

Not just read. There are 23 or so links on that page, roughly one-fourth of which lead to documentation pages, non-obviously. Of course, anything is obvious once you know it, but clearly it isn't obvious enough, or we wouldn't be having this discussion!

So they don't have to search, just read and click on links until they hit one that looks like a man page.

They're rather working on the assumption that readers know that anything with a "(1)" or an "(8)" after it is a reference to a user manual. This is a very common thing in BSD doco, and in Unix doco more generally.

For experienced Unix users this is likely to be true. It's something that one just learns. For novice users, it is less likely.

Why would a novice would care? Why would a novice interact with OpenSSL anyway?

I found it strange since OpenBSD is known for their excellent docs. So after opening the libressl site they have that paragraph stating the parts of the lib and links to their docs. That page works as the documentation index.

Namely

https://man.openbsd.org/openssl.1

Which the author was complaining about needing to use google for. Specifically the https://man.openbsd.org/openssl.1#GENRSA seems well document.

Forks are just the way open source works and if documentation could be better then we are all free to contribute to it.

Yup, I pointed this out last time this was posted.

https://news.ycombinator.com/item?id=16025063

It would be nice if the author revised that remark.

> 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

> 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

Didnt most of their changes get merged back?

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.

Source on this?

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.

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.

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)

Yeah the accessibility of the manpages was clearly the least significant objection by far, but yours is the first comment about anything else.

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.

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

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

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

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

5. Follow the code commits of the LibreSSL fork and if you continue to use OpenSSL and not LibreSSL at least you will know the various issues you are going to have.

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.

> `openssl help` does work on OSX (I literally just tested it).

For anyone else interested, I just tested it as well. It appears that it prints a listing of all the commands offered by openssl (split into sections "Standard commands", "Message Digest commands", and "Cipher commands"), with no other descriptions or usage instructions. I tried `openssl help bf` to get more information, and it prints the options available to that command and their descriptions. I did not see any way to actually figure out what a command does, but it is possible I missed it.

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

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

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

Other systems probably upgrade their copy of BSD userland more than once a decade... especially if they are the richest company on Earth.

There are probably 100 other user rants to accompany this for all the other massively out of date bits of BSD on MacOS.

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

Apple would actually very much like you to not use their OpenSSL: it is deprecated and you are not supposed to rely on it in your own applications.

On #3, I bet the man pages do exist, just not for openssl itself, but for each of the modules like genrsa, rsa, s_client, x509, etc.

on a generic openbsd machine :

  OPENSSL(1)                  General Commands Manual                 OPENSSL(1)

  NAME
     openssl ? OpenSSL command line tool

  SYNOPSIS
     openssl command [command_opts] [command_args]

     openssl list-standard-commands | list-message-digest-commands |
             list-cipher-commands | list-cipher-algorithms |
             list-message-digest-algorithms | list-public-key-algorithms

     openssl no-command

  DESCRIPTION
     OpenSSL is a cryptography toolkit implementing the Transport Layer
     Security (TLS v1) network protocol, as well as related cryptography
     standards.

[...]

Happily, it will likely be removed in the next macOS, at which point anything still dependent on it will break utterly until either updated to use SecureTransport or to bundle OpenSSL.

I predict a popular tool favored by the HN community will break, leading to a highly-upvoted front page post that instructs everyone on how to reinstall the shim wrapper using an unsigned tarball from an unsafe non-Apple source and zero patches to that tool from us to make it use the modern macOS-provided library instead.

  $ lsb_release -a          
  No LSB modules are available.
  Distributor ID: Ubuntu
  Description: Ubuntu 19.04
  Release: 19.04
  Codename: disco
  $ openssl --help           
  Invalid command '--help'; type "help" for a list.
  $ openssl help 2>&1 | head -n 3
  Standard commands
  asn1parse         ca                ciphers           cms               
  crl               crl2pkcs7         dgst              dhparam           
  $ openssl help asn1parse
  Usage: asn1parse [options]
  Valid options are:
  -help            Display this summary
  -inform PEM|DER  input format - one of DER PEM
  -in infile       input file
  -out outfile     output file (output format is always DER)
  -i               indents the output
  $ openssl genrsa -out foo.pem
  Generating RSA private key, 2048 bit long modulus (2 primes)
  ......................................................+++++
  .......................+++++
  e is 65537 (0x010001)

And as pointed out in this very discussion at https://news.ycombinator.com/item?id=20043375 and https://news.ycombinator.com/item?id=20042633 , they do not even apply to MacOS.

Seems that, regardless of platform, this was only really relevant back in 2017.

Debian (OpenSSL), man page is present, and 2048 mod is default:

    openssl genrsa -out private_key.pem
    Generating RSA private key, 2048 bit long modulus (2 primes)

These are all either MacOS or LibreSSL problems.

This may not even be a LibreSSL problem since the version the author is using is 3 years old [1] MacOS userland is always so ancient, the other bits of BSD userland are even worse as far as I remember.

[1] https://www.libressl.org/releases.html

> These are all MacOS | LibreSSL problems

Just MacOS.

> If you want documented examples, everyone should know this is where man pages suck in general, they are usually just reference manuals.

OpenBSD is generally pretty good about providing some useful examples in man pages. The libressl man page has examples too, for genpkey at least.

I meant OR (|) as a do not _know_ having only tried OpenSSL, updated to clarify this - I thought using bitwise operators would be safe here, I guess it doesn't work with english.

RE man pages, I am speaking generally (as i said), i know nothing of OpenBSDs man pages, and it doesn't matter, my point was not that LibreSSL or OpenSSL man pages suck for examples, but that it's a bad premise for an argument against Open/LibreSSL.

Current MacOS (Mojave, 10.14.5) has a man page for openssl, command line help for openssl, and generates a 2048 bit modulus, and is LibreSSL version 2.6.5 (admittedly nearly a year old.)

    $ openssl genrsa -out private_key.pem
    Generating RSA private key, 2048 bit long modulus
    .................+++
    ........................................+++
    e is 65537 (0x10001)

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.

> 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

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

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

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

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.

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

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

http://man.openbsd.org/openssl

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)

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

Canada actually respects FIPS 140-2 certification (and cooperates in certifying implementations!), so this would very much be relevant in a Canadian context.

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

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

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

Yes, this is why I had to stick to OpenSSL for my Linux distribution even though I would have preferred LibreSSL.

If anyone really wanted FIPS 140-2 compliance for libressl they should pony up the money to get it certified instead of complaining about it on message boards.

They actively removed and refuse FIPS mode as policy.

https://marc.info/?l=openbsd-misc&m=139819485423701&w=2

No one that cares enough to use LibreSSL over OpenSSL would want FIPS as reintroducing it would make LibreSSL demonstrably worse. Anyone that requires FIPS doesn't know or care enough about security to have a dog in the fight.

There are people in government that care about security. Unfortunately we aren't the ones that write the specifications/regulations.

> "But I need FIPS mode for blah blah." I notice nobody claims that there's any intrinsic value to FIPS mode. It's widely recognized as a worthless checkbox; now it's time to stand up to the clowns in charge and tell them the same thing. It's funny to compare how many people like to quote Gandhi's "Be the change that you wish to see in the world." with how few people actually like to be the change.

This is news to me! All I can say is, "Godspeed, Ted Unangst."

Based on Ted's take on FIPS [1], I don't think that's likely to happen anytime soon.

I'm constantly thankful that I'm able to work somewhere that I don't have to worry about other people's bogus security checkboxes.

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

I agree. Until someone convinces NIST to modernize and/or improve the FIPS standard, people who work with government agencies are stuck with it...

I guess this also matters: https://en.wikipedia.org/wiki/FIPS_140#Criticism It is very easy to see how this in practice lessens security.

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?

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

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.

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

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... for more info and links

it's not quite true - on latest macOS (10.14.5), on openssl based on LibreSSL 2.6.5 there's complete man page available - but, the funniest thing, it's dated on... today

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.

This article was written years ago

Oh! It really should have [2017] in the title, then.

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

https://latacora.micro.blog/2018/04/03/cryptographic-right-a...

https://paragonie.com/blog/2017/06/libsodium-quick-reference...

https://libsodium.gitbook.io/doc/bindings_for_other_language...

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

Sometimes it is a necessity to accommodate for various networking gear as load balancers, wireless controllers etc as RSA may be the only thing that they support.

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

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

Use Noise then:

https://noiseprotocol.org/

https://github.com/mcginty/snow

Reply on news.ycombinator.com