Hacker News Reader

Comment by brynet | Hacker News Reader

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

View on HN

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!

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.

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

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?

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.

Reply on news.ycombinator.com