> 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"
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.
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!
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.
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.
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.
> 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
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.
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)
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.
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).
> 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.
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.
> 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.
> 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.
> `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.
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.
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.
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.
$ 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)
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.
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?
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.
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)
Canada actually respects FIPS 140-2 certification (and cooperates in certifying implementations!), so this would very much be relevant in a Canadian context.
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.
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.
> "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."
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.
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.
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
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.