SoylentNews is people
SoylentNews
The Open Source Survey asked a broad array of questions. One that caught my eye was about problems people encounter when working with, or contributing to, open source projects. An incredible 93 percent of people reported being frustrated with “incomplete or confusing documentation”.
That’s hardly a surprise. There are a lot of projects on Github with the sparsest of descriptions, and scant instruction on how to use them. If you aren’t clever enough to figure it out for yourself, tough.
[...] According to the Github Open Source Survey, 60 percent of contributors rarely or never contribute to documentation. And that’s fine.
Documenting software is extremely difficult. People go to university to learn to become technical writers, spending thousands of dollars, and several years of their life. It’s not really reasonable to expect every developer to know how to do it, and do it well.
-- submitted from IRC
(Score: 4, Informative) by ledow on Monday June 05 2017, @11:07AM (3 children)
Say no more.
I could not find any reasoning or explanation for how it's supposed to be used, only example code that was incomplete.
Literally, there is no documentation (or even function) on how to validate a signed certificate, and the possible results. You have to imagine everything that could be wrong (certificate expired, signing certificate not valid, certificate corrupt, signing certificate doesn't actually sign the other certificate, one has a lower security than required, etc.) and work out how to check and code for it.
Most libraries at least have a few helper functions. With OpenSSL it's copy the incomplete examples (and hence introduce vulnerabilities) or do it yourself.
Literally, I just wanted to generate a certificate, sign it with another, then bundle both with a program that then checks the former is signed by the latter. It ran to hundreds and hundreds of lines of code building on the examples after discovering so many ways to "fool" the examples, and having to rip them apart to understand how they worked, splice them together, add extra checks, etc. And I wasn't even doing anything complicated like trying to do this over-the-wire, just literally from a few certs saved on disk (the idea being I could keep a CA cert for myself, sign a customer's software with it, and have the software check that it was signed and valid (i.e. in-date) before continuing). Not defcon levels of security, by any stretch of the imagination, but it was far more hassle than it was worth and also I could never be sure I'd got everything right.
And there is ZERO useful documentation. Even other people's tutorials were far from useful in such regard (literally copy/paste the example code and use).
Lack of documentation certainly hurts, but it's not a magic cure-all by any means. However, it does show you quite how much design effort, user-interaction, and even end-user use the library gets. Libraries like SDL have everything documented, lots of tutorials and third-party docs available, etc. and examples that cover all kinds of scenarios. That proves that people often code against them directly.
OpenSSL has pretty much nothing. Which to me says that almost nobody codes against it directly, and everyone relies on bigger projects, bigger libraries, or wrappers around it to do what they want. To me, that indicates that such wrappers should be PART OF THE LIBRARY.
(Score: 5, Insightful) by driverless on Monday June 05 2017, @11:35AM (1 child)
What do you mean "no documentation"? Here's all the OpenSSL docs you'll ever need [peereboom.us].
(Score: 2) by ledow on Monday June 05 2017, @12:41PM
Cheers for that. If that link doesn't prove my point, nothing does.
And I can't imagine all that much has changed even with all the problems with OpenSSL discovered in recent years.
(Score: 2) by JoeMerchant on Monday June 05 2017, @01:22PM
They claim it's not security by obscurity, but in practice, it is. The flaws are hard to find, but they're there waiting for exploit.
🌻🌻 [google.com]