5 ms·

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 libra

by ivl 7y ago

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 7y ago
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.
- jandrese 7y ago
  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.
- PuercoPop 7y ago
  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!
  - toast0 7y ago
    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).
  - nocman 7y ago
    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.
  - pwinnski 7y ago
    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.
JdeBP 7y ago
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.
- JetSpiegel 7y ago
  Why would a novice would care? Why would a novice interact with OpenSSL anyway?
HugoDaniel 7y ago
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 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 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.
- deleted 7y ago
  [deleted]

by ivl 7y ago

thepangolino 7y ago

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.

jandrese 7y ago
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.
PuercoPop 7y ago
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!
- toast0 7y ago
  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).
- nocman 7y ago
  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.
- pwinnski 7y ago
  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.

JdeBP 7y ago

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.

JetSpiegel 7y ago
Why would a novice would care? Why would a novice interact with OpenSSL anyway?

HugoDaniel 7y ago

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

deleted 7y ago
[deleted]