8 ms·

The sorry state of OpenSSL usability

78 points by jamesfisher 9y ago

TheDong 9y ago
> 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 9y ago
  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.
protomyth 9y ago
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.
- smhenderson 9y ago
  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.
  - deleted 9y ago
    [deleted]
- dmitriid 9y ago
  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.
  - dsp1234 9y ago
    openssl(1) links to https://man.openbsd.org/openssl https://man.openbsd.org/openssl
    - dmitriid 9y ago
      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.
      - tonysidaway 9y ago
        LibreSSL comes with copious documentation. Whence this latterday ignorance of offline documentation?
  - SAI_Peregrinus 9y ago
    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 9y ago
      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.
      - 9y ago
mt42or 9y ago
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 9y ago
  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.
deleted 9y ago
[deleted]
pintxo 9y ago
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 9y ago
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 9y ago
  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 9y ago
    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.
  - proginthebox 9y ago
    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.
- moomin 9y ago
  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.
gpf 9y ago
This is a macOS problem. OpenSSL on Linux has extensive man pages and a --help switch.
- mt42or 9y ago
  I just said the same thing but Mac OS seems to be sacred here...
- larrik 9y ago
  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 9y ago
    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.
- PhantomGremlin 9y ago
  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.
tptacek 9y ago
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 9y ago
  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 9y ago
    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 9y ago
      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.
bloblaw 9y ago
On my Ubuntu 16.04 system, `man openssl` works just fine for me.
24gttghh 9y ago
One could export the man pages from another *nix and import them into OSX perhaps?
gbrown_ 9y ago
> 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 9y ago
  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+documentation https://www.google.co.uk/search?q=site%3Alibressl.org+docume...
  - gbrown_ 9y ago
    The links for libcrypto, libssl, libtls, openssl(1), nc(1), and ocspcheck(1) all go to online man pages.
    - deleted 9y ago
      [deleted]
  - nagvx 9y ago
    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
w00bl3ywook 9y ago
wtf.. donate/contribute
deleted 9y ago
[deleted]
goloroden 9y ago
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-openssl-beginners-guide-to-creating-ssl-certificates/ https://www.thenativeweb.io/blog/2017-12-29-11-51-the-openss...

78 points by jamesfisher 9y ago

> 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 9y ago
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.

protomyth 9y ago

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.

smhenderson 9y ago
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.
- deleted 9y ago
  [deleted]
dmitriid 9y ago
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.
- dsp1234 9y ago
  openssl(1) links to https://man.openbsd.org/openssl https://man.openbsd.org/openssl
  - dmitriid 9y ago
    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.
    - tonysidaway 9y ago
      LibreSSL comes with copious documentation. Whence this latterday ignorance of offline documentation?
- SAI_Peregrinus 9y ago
  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 9y ago
    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.
    - 9y ago

mt42or 9y ago

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 9y ago
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.

deleted 9y ago

[deleted]

pintxo 9y ago

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 9y ago

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 9y ago
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 9y ago
  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.
- proginthebox 9y ago
  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.
moomin 9y ago
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.

gpf 9y ago

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

mt42or 9y ago
I just said the same thing but Mac OS seems to be sacred here...
larrik 9y ago
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 9y ago
  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.
PhantomGremlin 9y ago
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.

tptacek 9y ago

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 9y ago
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 9y ago
  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 9y ago
    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.

bloblaw 9y ago

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

24gttghh 9y ago

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

gbrown_ 9y ago

> 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 9y ago
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+documentation https://www.google.co.uk/search?q=site%3Alibressl.org+docume...
- gbrown_ 9y ago
  The links for libcrypto, libssl, libtls, openssl(1), nc(1), and ocspcheck(1) all go to online man pages.
  - deleted 9y ago
    [deleted]
- nagvx 9y ago
  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

w00bl3ywook 9y ago

wtf.. donate/contribute

deleted 9y ago

[deleted]

goloroden 9y ago

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