Just how bad is OpenSSL? (2012) • Hacker News Board

Re: Just how bad is OpenSSL? (2012)

#21

Post by derefr » Sun, Jul 24, 2016, 6:15 PM UTC

ori_b wrote: post #12

dingaling wrote: post #6

Earlier quoted context omitted.

Yes man pages are usually upside-down; the examples should be right at the start and then lead to a drill-down into options. 9/10 times I end-up having to search the web for a basic introductory example. But even in big corps corps with ISO9000 accreditation there is seldom self- questioning as to whether documentation is useful rather than just ticking the box for process-completeness.

No. 90% of the time, I know what I want to do, and how my tools work. I just don't remember the options are called. Having a summary of the options right there at the top is the most valuable thing in a reference.

You're presuming man pages are primarily meant to serve as a reference. But I rarely need man-pages as a reference†.

Most of the time, if I'm looking up a man-page for something, it's because I've just installed a new package that sounded like it would solve a problem and then did a dpkg-query(1) to find out what binaries came with it—or used apropos(1) to find a relevant binary already installed—and now I want to know what the uses of a given binary are and whether those uses include solving my particular problem.

† Well, except for the utilities with absolutely horrible command-line UX-design, like tar(1) or ps(1) or rsync(1), where I just memorize the options I need for my usual case, and then have to look in the man page to do anything novel.

Re: Just how bad is OpenSSL? (2012)

#22

Post by nickpsecurity » Sun, Jul 24, 2016, 6:16 PM UTC

stefs wrote: post #17

nickpsecurity wrote: post #16

The experts writting it for themselves part seemed inaccurate given what I read in LibreSSL commits. It was one atrocity after another. Still love Ted Unganst's observation about them making surd endianess of CPU doesnt change while protocol is running. Just cant remember how often that check was performed. "Experts"... lol...

i interpreted this as: this was written by security experts (cryptographers), not expert programmers. this means the algorithms are generally ok, but the implementation is wacky (and issue prone).

That's a fair interpretation.

Re: Just how bad is OpenSSL? (2012)

#23

Post by bluejekyll » Sun, Jul 24, 2016, 6:25 PM UTC

gpvos wrote: post #20

ori_b wrote: post #12

Earlier quoted context omitted.

No. 90% of the time, I know what I want to do, and how my tools work. I just don't remember the options are called. Having a summary of the options right there at the top is the most valuable thing in a reference.

For that there is the --help option.

And for this implementing cli, I've found http://docopt.org to be an excellent and simple way to provide standard options and docs easily.

Re: Just how bad is OpenSSL? (2012)

#24

Post by taeric » Sun, Jul 24, 2016, 6:27 PM UTC

aerovistae wrote: post #2

Frankly I've never liked man pages. To me they always screamed "This is how documentation was done in the 90s." The examples are often very unclear or incomplete, and the explanations often assume prior knowledge without providing links in case such knowledge is absent. Modern documentation has gotten way better, as seen in the Stripe docs and many others, and I wish the man pages could be updated accordingly.

And, for myself, I couldn't disagree more. Man pages are very well done, since they are more often used for reference than they are for discovery.

Similarly, documentation seems to have apexed with the TeXbook. :(

Re: Just how bad is OpenSSL? (2012)

#25

Post by jm547ster » Sun, Jul 24, 2016, 6:42 PM UTC

ramanan wrote: post #14

dingaling wrote: post #6

Earlier quoted context omitted.

Yes man pages are usually upside-down; the examples should be right at the start and then lead to a drill-down into options. 9/10 times I end-up having to search the web for a basic introductory example. But even in big corps corps with ISO9000 accreditation there is seldom self- questioning as to whether documentation is useful rather than just ticking the box for process-completeness.

You might be interested in bro pages then! http://bropages.org/

Is this real? I'm on mobile can't check it, had nice little chuckle with curl example

Re: Just how bad is OpenSSL? (2012)

#26

Post by red_admiral » Sun, Jul 24, 2016, 6:48 PM UTC

stefs wrote: post #17

nickpsecurity wrote: post #16

The experts writting it for themselves part seemed inaccurate given what I read in LibreSSL commits. It was one atrocity after another. Still love Ted Unganst's observation about them making surd endianess of CPU doesnt change while protocol is running. Just cant remember how often that check was performed. "Experts"... lol...

i interpreted this as: this was written by security experts (cryptographers), not expert programmers. this means the algorithms are generally ok, but the implementation is wacky (and issue prone).

It was also written by cryptographers who for years asked for support, and got barely enough to keep the server running let alone live off it. Meanwhile the world and his wife joined in with feature requests and complaints about things they didn't like, but mostly without offering to help.

So it doesn't surprise me that unit testing, documentation, code review etc. weren't a top priority for spending more unpaid hours on - people literally got what they paid for.

Re: Just how bad is OpenSSL? (2012)

#27

Post by red_admiral » Sun, Jul 24, 2016, 6:52 PM UTC

If you think OpenSSL is bad, try MIRACL (only documentation I could find is a word file that's basically a list of function signatures). And OpenSSL at least generally builds fine on a vanilla Ubuntu machine.

In contrast, libsodium deserves praise for writing documentation like they want people to actually use their library.

Re: Just how bad is OpenSSL? (2012)

#28

Post by geon » Sun, Jul 24, 2016, 6:56 PM UTC

ramanan wrote: post #14

dingaling wrote: post #6

Earlier quoted context omitted.

Yes man pages are usually upside-down; the examples should be right at the start and then lead to a drill-down into options. 9/10 times I end-up having to search the web for a basic introductory example. But even in big corps corps with ISO9000 accreditation there is seldom self- questioning as to whether documentation is useful rather than just ticking the box for process-completeness.

You might be interested in bro pages then! http://bropages.org/

I like tldr: http://tldr-pages.github.io/

Re: Just how bad is OpenSSL? (2012)

#29

Post by qwertyuiop924 » Sun, Jul 24, 2016, 7:01 PM UTC

derefr wrote: post #21

ori_b wrote: post #12

Earlier quoted context omitted.

No. 90% of the time, I know what I want to do, and how my tools work. I just don't remember the options are called. Having a summary of the options right there at the top is the most valuable thing in a reference.

You're presuming man pages are primarily meant to serve as a reference. But I rarely need man-pages as a reference†. Most of the time, if I'm looking up a man-page for something, it's because I've just installed a new package that sounded like it would solve a problem and then did a dpkg-query(1) to find out what binaries came with it—or used apropos(1) to find a relevant binary already installed—and now I want to kn…

>You're presuming man pages are primarily meant to serve as a reference.

They are.

Re: Just how bad is OpenSSL? (2012)

#30

Post by qwertyuiop924 » Sun, Jul 24, 2016, 7:05 PM UTC

OpenSSL is pretty bad. After reading about some of the stuff that lead the the libressl fork, I wouldn't trust it with my lunch money. Sure, the algorithms are good, but as far as the code's concerned, Heartbleed was the tip of the iceberg.