RE: I can't believe how much this sucks

[Charles Mills]

AMEN!

 

Why is it easier to answer dumb question after dumb question here rather than to document the darned product once? (Never mind the cumulative labor of all the programmers trying to figure out and debug the same problems again and again and again, all over the world.)

 

Consider http://www.cs.utexas.edu/~shmat/shmat_ccs12.pdf. Doesn’t *some* of the responsibility for these (severe and scary!) problems fall on the lack of clear documentation?

 

It’s a GREAT product and I love it and am grateful but why after years and years do the man pages still say “under construction”?

 

Charles

From: owner-ope...@openssl.org [mailto:owner-ope...@openssl.org] On Behalf Of Sanford Staab
Sent: Tuesday, November 13, 2012 10:35 AM
To: openss...@openssl.org
Subject: I can't believe how much this sucks

 

I have been struggling with openssl for a few months now writing batch scripts on windows trying to make a .net web client with a client certificate work with 2-way ssl against an apache web server.

 

Do you guys just want to continue to answer questions on this alias and not FIX the docs somewhat over time?  I could go into a litany of how much information is just missing from the docs with INCOMPLETE everywhere.  (see this link for one of the 900k+ hits on a google search of “openssl+docs+suck” for how much hell you guys are putting people through trying to figure out this tool)

 

openssl is used all over the world by tons of people (so I feel dumb having problems here – but I know from Google I am not alone.) but it is just unbelievable to me that the docs remain so terse and useless for so many years.

 

I have sent email to this alias previously asking how I can help with this.  It seems to me there should be an openssl docs forum where content from this eventually finds its way into the online docs themselves.

 

A tool is only as good as people are able to use it.

 

So let me get specific here – one simple specific question (of many that I have) that has me clueless:

 

The command of:

openssl s_client -connect www.pawnmasterpro.com:443 -CApath ssl\certs -cert ssl\certs\client_1.crt -key ssl\keys\client_1.key -pass file:ssl\keys\Client_1_pwd.txt

 

results in output containing:

No client certificate CA names sent

 

from the docs for the s_client command, –cert option says:

-cert certname

The certificate to use, if one is requested by the server. The default is not to use a certificate.

My guess from this is that this command is referring to the CLIENT SSL certificate - no?  If my assumption is correct, then why am I getting this error?  Or is this a notification of something normal and I should be looking elsewhere?

 

I have checked the Apache httpd-ssl.cnf file I am using and verified that all the certificate related parts are filled in and I have verified the integrity of all the certificates referenced by it.

I have been able to do straight one-way SSL with the server as well with both IE and Chrome browsers.  Two-way SSL fails with the server logs indicating that the client “refused” the connection.

I am using a self-signed CA which was used to sign the server certificate.  The client certificate is also signed by the same CA self-signed certificate.

Apache error logs give me this:

[Tue Nov 13 12:38:56 2012] [error] [client 127.0.0.1] Invalid method in request  

Which is about as useful as the openssl docs are.

I am also seeing this in openssl’s s_client output:

verify error:num=19:self signed certificate in certificate chain

From what I think I understand, this should not be a showstopper problem as all root CA certs would naturally be self-signed no?

Full output of this operation with the –showcerts command is attached for reference.

I have read through many forum examples of how to do this and it seems simple enough but then when it doesn’t work, figuring out what things MEAN and how to address what is wrong proves to be be very difficult indeed.

["Magosányi, Árpád"]

On 11/13/2012 07:34 PM, Sanford Staab wrote:

Do you guys just want to continue to answer questions on this alias and not FIX the docs somewhat over time?  I could go into a litany of how much information is just missing from the docs with INCOMPLETE everywhere.

You might have overlooked the fact that openssl is an open source project. Feel free to contribute the needed documentation or finance the creation thereof if your knowledge is lacking to do so.

(Yes, the documentation is lacking, an I (r=1 user of openssl) also find this a sad state of affairs. But I find whining about a problem in an open source project in this tone disturbing. Rule of thumb: the more you contribute you have more right to whine. You and me have right to point out a bug, or respectfully ask for a feature.

[Lee Fisher]

For things that the peer support forum and the existing documentation
don't cover, you have the source code, which is definitive.

Additionally, there are professional OpenSSL consultants you can use for
help.

It would be more productive to submit bugs and patches, instead of a
litany :-)

______________________________________________________________________
OpenSSL Project http://www.openssl.org
User Support Mailing List openss...@openssl.org
Automated List Manager majo...@openssl.org

[Ben Laurie]

On Tue, Nov 13, 2012 at 6:34 PM, Sanford Staab <sanf...@gmail.com> wrote:
> I have been struggling with openssl for a few months now writing batch
> scripts on windows trying to make a .net web client with a client
> certificate work with 2-way ssl against an apache web server.
>

> Do you guys just want to continue to answer questions on this alias and not
> FIX the docs somewhat over time? I could go into a litany of how much

> information is just missing from the docs with INCOMPLETE everywhere. (see

> this link for one of the 900k+ hits on a google search of
> “openssl+docs+suck” for how much hell you guys are putting people through
> trying to figure out this tool)
>
> openssl is used all over the world by tons of people (so I feel dumb having
> problems here – but I know from Google I am not alone.) but it is just
> unbelievable to me that the docs remain so terse and useless for so many
> years.
>
> I have sent email to this alias previously asking how I can help with this.
> It seems to me there should be an openssl docs forum where content from this
> eventually finds its way into the online docs themselves.
>
> A tool is only as good as people are able to use it.
>
> So let me get specific here – one simple specific question (of many that I
> have) that has me clueless:
>
> The command of:
> openssl s_client -connect www.pawnmasterpro.com:443 -CApath ssl\certs -cert
> ssl\certs\client_1.crt -key ssl\keys\client_1.key -pass
> file:ssl\keys\Client_1_pwd.txt
>
> results in output containing:
> No client certificate CA names sent

This seems straightforward: the client expects a list of acceptable
CAs for the client certificate it should send. It got none.

I suspect the reason is that you haven't required client verification
in the context in which Apache is answering - it seems to be only
enabled for certain URLs...

>
> from the docs for the s_client command, –cert option says:
> -cert certname
>
> The certificate to use, if one is requested by the server. The default is
> not to use a certificate.
>
> My guess from this is that this command is referring to the CLIENT SSL
> certificate - no? If my assumption is correct, then why am I getting this
> error? Or is this a notification of something normal and I should be
> looking elsewhere?
>
> I have checked the Apache httpd-ssl.cnf file I am using and verified that
> all the certificate related parts are filled in and I have verified the
> integrity of all the certificates referenced by it.
> I have been able to do straight one-way SSL with the server as well with
> both IE and Chrome browsers. Two-way SSL fails with the server logs
> indicating that the client “refused” the connection.

> I am using a self-signed CA which was used to sign the server certificate______________________________________________________________________

[Erwann Abalea]

Answers inline.

-- 
Erwann ABALEA
-----
paléocapridé: genre de vieille bique, cf paléotalpidé (vieille taupe) ou paléogadidé (vieille morue)

Le 13/11/2012 19:34, Sanford Staab a écrit :

I have been struggling with openssl for a few months now writing batch scripts on windows trying to make a .net web client with a client certificate work with 2-way ssl against an apache web server.

So you've looked at Apache documentation in addition to OpenSSL doc, right?

Do you guys just want to continue to answer questions on this alias and not FIX the docs somewhat over time?  I could go into a litany of how much information is just missing from the docs with INCOMPLETE everywhere.  (see this link for one of the 900k+ hits on a google search of “openssl+docs+suck” for how much hell you guys are putting people through trying to figure out this tool)

 

openssl is used all over the world by tons of people (so I feel dumb having problems here – but I know from Google I am not alone.) but it is just unbelievable to me that the docs remain so terse and useless for so many years.

 

I have sent email to this alias previously asking how I can help with this.  It seems to me there should be an openssl docs forum where content from this eventually finds its way into the online docs themselves.

 

A tool is only as good as people are able to use it.

 

So let me get specific here – one simple specific question (of many that I have) that has me clueless:

 

The command of:

openssl s_client -connect www.pawnmasterpro.com:443 -CApath ssl\certs -cert ssl\certs\client_1.crt -key ssl\keys\client_1.key -pass file:ssl\keys\Client_1_pwd.txt

 

results in output containing:

No client certificate CA names sent

 

That's a warning. OpenSSL client warns you that your Apache server hasn't sent any CA name to the client to help decide which certificate it should present. That's the result of your Apache configuration.

from the docs for the s_client command, –cert option says:

-cert certname

The certificate to use, if one is requested by the server. The default is not to use a certificate.

My guess from this is that this command is referring to the CLIENT SSL certificate - no?  If my assumption is correct, then why am I getting this error?  Or is this a notification of something normal and I should be looking elsewhere?

This isn't an error, and OpenSSL has tried to present the certificate you asked it to. 

I have checked the Apache httpd-ssl.cnf file I am using and verified that all the certificate related parts are filled in and I have verified the integrity of all the certificates referenced by it.

I have been able to do straight one-way SSL with the server as well with both IE and Chrome browsers.  Two-way SSL fails with the server logs indicating that the client “refused” the connection.

I am using a self-signed CA which was used to sign the server certificate.  The client certificate is also signed by the same CA self-signed certificate.

Apache error logs give me this:

[Tue Nov 13 12:38:56 2012] [error] [client 127.0.0.1] Invalid method in request  
Which is about as useful as the openssl docs are.

It indicates Apache didn't receive a valid HTTP request. That's not OpenSSL's job.
Right now (19:29 UTC), your server doesn't do TLS, only plain HTTP on port 443. Trying to do TLS on such a server might give this error message in your Apache.

I am also seeing this in openssl’s s_client output:

verify error:num=19:self signed certificate in certificate chain

From what I think I understand, this should not be a showstopper problem as all root CA certs would naturally be self-signed no?

Full output of this operation with the –showcerts command is attached for reference.

I have read through many forum examples of how to do this and it seems simple enough but then when it doesn’t work, figuring out what things MEAN and how to address what is wrong proves to be be very difficult indeed.

Having read the provided output of your tests, it seems you configured your Apache server to send both its own certificate and the root as intermediate certificates. That's both wrong and useless. OpenSSL s_client tells you that he found a self-signed certificate in the returned chain (which is true). Disable the "SSLCertificateChainFile" directive in your Apache, it should get better.

Anyway, the output shows that the TLS connexion went OK, and that Apache received something that looked like a valid request.

Go read Apache doc again.

[John Hascall]

> It's a GREAT product and I love it and am grateful but why after
> years and years do the man pages still say "under construction"?

Because it is an open source project and the things that get done
are the things people volunteer to do. Most programmers would
much rather create cool things than write about them.

That said, perhaps this is something that a Google Summer Of Code
project could help get off the ground (money being a pretty decent
motivator for poor students).

John

-------------------------------------------------------------------------------
John Hascall, jo...@iastate.edu
Team Lead, NIADS (Network Infrastructure, Authentication & Directory Services)
IT Services, The Iowa State University of Science and Technology

[Ted Byers]

On Tue, Nov 13, 2012 at 2:02 PM, Lee Fisher <bli...@gmail.com> wrote:

For things that the peer support forum and the existing documentation don't cover, you have the source code, which is definitive.

Additionally, there are professional OpenSSL consultants you can use for help.

It would be more productive to submit bugs and patches, instead of a litany :-)

Even so, some of those closely involved in the project ought to be doing a better job of documenting the product.  Telling people to hire consultants is even worse than telling people to read the code.  I develop software for a living, and I would be ashamed of any attempt to release even one of my products without a proper reference manual, complete design documentation, including a reasonable suite of UML documents (in the case of an open source product since good coders benefit from good design documentation - which, admittedly, I have not produced) and a thorough tutorial.  I have had feedback on some of my products that the end users found my interface so intuitive that they did not look at the documentation I'd provided even once, but I do not see that as an excuse for not producing proper documentation.  In my view, the documentation for a product is as much a part of the product as the code in the product.  The product is not ready for release until the documentation is as complete and polished as is the code.

Peer support is hardly a good, or cost effective, substitute for good documentation; and contrary to what some coders I have met, and worked with, have claimed, the source code is often not adequate documentation.  Yes, you see what the code is doing, but tracing execution paths through it can be a tedious nightmare; especially if the coder that produced it wrote the code as a candidate for an obfuscated coding contest (something, BTW, I would regard as grounds for dismissal if obfuscation is the only justification the code can offer for it).

In my own coding, the only libraries I use often are those that are well documented.  Life is just too short to waste on libraries that are poorly documented (unless someone wants to pay me to do so - but they'd be paying a significant premium for such a tedious, and  usually frustrating, task).

I am not criticising the documentation for openssl, and will not; but I would encourage those who are responsible for maintaining and improving openssl to not neglect the documentation.  It would be a mistake to leave that for someone else to do, for when that happens, it is certain that the documentation will suffer.

just my $0.02, as a coder with decades of coding experience.

Cheers

Ted

[Jeffrey Walton]

On Tue, Nov 13, 2012 at 1:34 PM, Sanford Staab <sanf...@gmail.com> wrote:
> I have been struggling with openssl for a few months now writing batch
> scripts on windows trying to make a .net web client with a client
> certificate work with 2-way ssl against an apache web server.
>

> Do you guys just want to continue to answer questions on this alias and not
> FIX the docs somewhat over time? I could go into a litany of how much
> information is just missing from the docs with INCOMPLETE everywhere. (see
> this link for one of the 900k+ hits on a google search of
> “openssl+docs+suck” for how much hell you guys are putting people through
> trying to figure out this tool

OpenSSL has a book by Viega, Messier, and Chandra (though its a bit
dated). It will get you through most of the basics when using the API
set. Its what I used years ago.

If its any consolation, NSS's documentation is even worse. I banned
NSS's use in code under my purview because I could not ensure it was
being used correctly (that's how shitty their docs were at the time).
Its a shame that Mozilla makes millions being Google's whore and it
could not even hire a technical writer to produce a decent set of
documents (perhaps that's changed now).

Jeff

[Jeffrey Walton]

On Tue, Nov 13, 2012 at 1:51 PM, "Magosányi, Árpád" <m4g...@gmail.com> wrote:
> On 11/13/2012 07:34 PM, Sanford Staab wrote:
>

> Do you guys just want to continue to answer questions on this alias and not
> FIX the docs somewhat over time? I could go into a litany of how much
> information is just missing from the docs with INCOMPLETE everywhere.
>

> You might have overlooked the fact that openssl is an open source project.
> Feel free to contribute the needed documentation or finance the creation
> thereof if your knowledge is lacking to do so.

I have to call bulshit on this one. The project does not appear to be
interested in outside help (and I'm tired of folks making these
statements).

Confer:
* IBM submitted patches for CCM and GCM nearly 10 years ago [1]. Not
incorporated.
* Thomas Wu submitted patches for SRP nearly 5 years ago [2]. Not incorporated.
* I submitted patches (to try the waters) [3]. Not incorporated
* Others have submitted documentation patches [4]. Not incorporated.

Jeff

[1] http://rt.openssl.org/Ticket/Display.html?id=782&user=guest&pass=guest
[2] http://rt.openssl.org/Ticket/Display.html?id=1794&user=guest&pass=guest
[3] http://rt.openssl.org/Ticket/Display.html?user=guest&pass=guest&id=2402
[4] http://rt.openssl.org/Ticket/Display.html?user=guest&pass=guest&id=2401
[5] http://rt.openssl.org/Ticket/Display.html?id=2697&user=guest&pass=guest

[alan buxey]

Hi,

> I am not criticising the documentation for openssl, and will not; but I
> would encourage those who are responsible for maintaining and improving
> openssl to not neglect the documentation.  It would be a mistake to leave

it is an Open Source project - thus there is also an onus on the USERS who use the code
to also provide something into the mix - commonly that is for documentation - as
users are often not the ones maintaining or improving the codebase...but are people
USING the API and software (usually for their own purposes and financial gain) - so ideal
for being people to offer something back in the way of , eg, better documentation.

I'd cite a use example - eg Cisco use OpenSSL for their AnyConnect SSL client - they are
using quite a few of the APIs and functions in their commercial product(s) - a proper
symbiotic relationship would be for their expertise to be fed back in the way of
bug fixes and documentation.

coders are often NOT the best documentation writers ;-)

alan

[te...@terralogic.net]

I beg to differ and this is one reason I am not very active.

Several years ago I contributed a function to determine endianess. I had done it years and years before so it was quite simple for me. I took the time to put documentation in the function. Also I am a professional consulting programmer adn I know both what to document, how to document and how to write code.

Someone came in and removed the documentation.

At the time I voluntered to start putting some documentation together. I saw no interest.

I agree with those who point out the dreath in OSS documentation and the fact that years after problems have been identified that the docs are still not upgraded and moreover I never found out HOW to do any documentation. Besides which when I contributed a function someone went to the effort to remove the documentation.


I have ALWAYS written the documentation for a function before the code because it is much faster and one can design the interface in about 1/4 of the time that it takes to code it. Then if I come back to the function years later I can read the documentation and I know how the function should work! I keep the documenation and the code in the same source file. Then I have utilities which will read the source file and split out the documentation and prepare a printable manual if I want.

I've had clients ask me how long to document a rather large system which I wrote and my comment was I can have the manual by noon - which I did and it was 3 cm thick.


they were quite impressed.


This is just a NORMAL way for a programmer to work IMHO. I HATE comming into undocumented code years after its been written and IMHO its a big booby trap because its very easy to miss something and that creates hard to find bugs. Really criptic error messages don't help this. I've looked in the OOS community and there are attempts to put together systems and one I looked at was OXYGEN.

http://www.stack.nl/~dimitri/doxygen/


I have no idea at this time how useful this would be.


Perhaps the best we might be able to do on the user side is a wiki and perhaps one exists.


I did a google search on this.

https://help.ubuntu.com/community/OpenSSL

^ I did find this and I did not look very hard. Maybe there is something better. If there is then it doesn't come up in the 1st hits google finds.


So I think we can do much better.

Just my 2 cents.

On Tue, Nov 13, 2012 at 01:33:48PM -0600, John Hascall wrote:
>
> > It's a GREAT product and I love it and am grateful but why after
> > years and years do the man pages still say "under construction"?
>
> Because it is an open source project and the things that get done
> are the things people volunteer to do. Most programmers would
> much rather create cool things than write about them.
>
> That said, perhaps this is something that a Google Summer Of Code
> project could help get off the ground (money being a pretty decent
> motivator for poor students).
>
> John
>
> -------------------------------------------------------------------------------
> John Hascall, jo...@iastate.edu
> Team Lead, NIADS (Network Infrastructure, Authentication & Directory Services)
> IT Services, The Iowa State University of Science and Technology

[Mark H. Wood]

On Tue, Nov 13, 2012 at 07:51:24PM +0100, "Magosányi, Árpád" wrote:
> On 11/13/2012 07:34 PM, Sanford Staab wrote:
> >
> > Do you guys just want to continue to answer questions on this alias
> > and not FIX the docs somewhat over time? I could go into a litany of
> > how much information is just missing from the docs with INCOMPLETE
> > everywhere.
>
> You might have overlooked the fact that openssl is an open source
> project. Feel free to contribute the needed documentation or finance the
> creation thereof if your knowledge is lacking to do so.

I've read more variations of this than I can count, and I never know
whether to laugh or cry when I read the assertion that the person with
the most imperfect understanding of the product is the best to tell
everyone how it works. I've been that person and I know better.

> (Yes, the documentation is lacking, an I (r=1 user of openssl) also find
> this a sad state of affairs. But I find whining about a problem in an
> open source project in this tone disturbing. Rule of thumb: the more you
> contribute you have more right to whine. You and me have right to point
> out a bug, or respectfully ask for a feature.

Well, I've also been in the position of the person who *is* best
qualified to write documentation: the author of the software. In
that role, I would hope that people complain (with details) when I've
left something out. And if I continue to leave it out, I would hope
that someone would show his respect for my skills with a good sharp
poke: Mark, I know you can do better than this!

Reporting documentation problems is different from reporting software
problems. In the latter case we send a report because we understand
(to some extent) what is wrong; in the former, often we only
understand that there is something missing but we have no idea what it
may be. Our contribution is notice of the fact that someone read X
and did not find the knowledge he needed to use the product. It could
(and should) extend to willingness to work with the writer to ensure
that the coverage and clarity of the writing is substantially
improved.

--
Mark H. Wood, Lead System Programmer mw...@IUPUI.Edu
Asking whether markets are efficient is like asking whether people are smart.

[Sanford Staab]

Couldn’t agree more Ted.  I think the bar on open-source product documentation has been going way up over time.  If I were these guys, I’d get it right so I wouldn’t have to keep bothering to answer so many questions over and over.

[Sanford Staab]

You miss the fact that I VOLUNTEER TO HELP FIX IT if someone will tell me where to start.  There are lots of open source projects out there with WAY better docs.  Take JQuery for one example.  I think the reason openssl docs suck is because the authors don’t really care about docs and they don’t even seem to want someone who does to help.

 

From: "Magosányi, Árpád"

Sent: Tuesday, November 13, 2012 1:51 PM

To: openss...@openssl.org

Subject: Re: I can't believe how much this sucks

 

On 11/13/2012 07:34 PM, Sanford Staab wrote:

 

Do you guys just want to continue to answer questions on this alias and not FIX the docs somewhat over time?  I could go into a litany of how much information is just missing from the docs with INCOMPLETE everywhere.

You might have overlooked the fact that openssl is an open source project. Feel free to contribute the needed documentation or finance the creation thereof if your knowledge is lacking to do so.

[Ted Byers]

On Tue, Nov 13, 2012 at 3:18 PM, alan buxey <A.L.M...@lboro.ac.uk> wrote:

Hi,

>    I am not criticising the documentation for openssl, and will not; but I
>    would encourage those who are responsible for maintaining and improving
>    openssl to not neglect the documentation.  It would be a mistake to leave

it is an Open Source project - thus there is also an onus on the USERS who use the code
to also provide something into the mix - commonly that is for documentation - as
users are often not the ones maintaining or improving the codebase...but are people
USING the API and software (usually for their own purposes and financial gain) - so ideal
for being people to offer something back in the way of , eg, better documentation.

Nonsense.  The most the users can be expected to contribute is their questions.  That is where the fodder for FAQs comes from.  From the perspective of a library writer, they also show what you've missed.  I am CTO in my company, and when I direct a junior or intermediate programmer to use library X (which may well be one I have developed over the decades), I do not tell them to study the code to figure out how to use it.  In many cases, the library details involve aspects of the problem at hand that are well beyond their experience.  However, when I give them direction to use the library, I also point them to good quality user documentation: documentation that clearly llustrates how the library is properly used, and it is at a level that they can understand.  in this way, I can educate them, or introduce them, to technologies that are new to them at a pace they can handle, and that without wasting time examining the details fo the library implementation code which, as I said, is often well beyond what their experience can handle.
 

I'd cite a use example - eg Cisco use OpenSSL for their AnyConnect SSL client - they are
using quite a few of the APIs and functions in their commercial product(s) - a proper
symbiotic relationship would be for their expertise to be fed back in the way of
bug fixes and documentation.

coders are often NOT the best documentation writers ;-)

Nonsense.  No-one knows better how the code ought to be working than the folk who developed it.  I begin with the assumption that all my coders are functionally literate.  I expect them to document their own code as part of the duties for their position.  Of course, the senior staff will review, and require edits, as part of the routine code reviews; and, on a large project, there may be a professional educator who takes responsibility for the final drafts of the user documentation.  But there is no excuse for a coder not to document his own code.

And that a given product is open source, or free, is not an excuse for library developers doing a poor job documenting their product.  Take a look at the boost documentation.  Some of that is great; and some not so much.  But the boost library documentation is gnerally more than enough for a capable programmer to make good use of most of those libraries.  Granted, though, some of those libraries are sufficiently advanced that I would only ask senior members of my team to make use of them.  And there are other open source products that do have adequate to good documentation; at least if you look carefully.

Cheers

Ted

[Charles Mills]

EXACTLY!

 

Charles

From: owner-ope...@openssl.org [mailto:owner-ope...@openssl.org] On Behalf Of Sanford Staab
Sent: Tuesday, November 13, 2012 12:53 PM
To: openss...@openssl.org
Subject: Re: I can't believe how much this sucks

 

Couldn’t agree more Ted.  I think the bar on open-source product documentation has been going way up over time.  If I were these guys, I’d get it right so I wouldn’t have to keep bothering to answer so many questions over and over.

 

From: Ted Byers

Sent: Tuesday, November 13, 2012 2:49 PM

To: openss...@openssl.org

Subject: Re: I can't believe how much this sucks

 

On Tue, Nov 13, 2012 at 2:02 PM, Lee Fisher <bli...@gmail.com> wrote:

For things that the peer support forum and the existing documentation don't cover, you have the source code, which is definitive.

Additionally, there are professional OpenSSL consultants you can use for help.

It would be more productive to submit bugs and patches, instead of a litany :-)

[Ted Byers]

On Tue, Nov 13, 2012 at 4:38 PM, alan buxey <A.L.M...@lboro.ac.uk> wrote:

Hi,

>    Nonsense.  No-one knows better how the code ought to be working than the
>    folk who developed it.  I begin with the assumption that all my coders are

i'd cite the cathedral and the bazaar ...or the 'many eyes make all bugs shallow'
views - if you are given the API and the documents, you use the code without seeing
what its doing. by looking at each library you can see what it does and how it does it
but most importantly, you can see the bugs/issues/problems.

You neglect context.  My junior staff generally don't see the library implementations, even when we own the code.  To ask them to study that code pushes them way too far much too fast.  I want junior staff to develop at a reasonable pace; but at their own pace.  I will not assign them tasks that they haven't a hope of completing in a reasonable timeframe.  That is just plain cruel!  It is madness to expect a junior coder to have all the expertise of a senior software engineer.  To do so is a recipe for disaster, and for rapid burnout of your junior staff.  Your cathedral and bazaar metaphore therefore does not apply in most cases.

Your metaphore only applies in the case of senior programmers interacting with other senior programmers.  And, when it comes to security, you want as many senior programmers' eyes on the code as is possible.  And I would be concerned about using a library that my senior staff have trouble figuring out.  But even this does not excuse the senior programmers responsible for developing the code from documenting it.  There is no-one better to do it, especially if they put themselves in the place of the junior programmers they are responsible for training.
 

with the closed source proprietary software you expect to get 100% perfect docs because
you cannot see the source code - you are told how it works and what to feed it. thats that.

That's just plain wishful thinking!  The perfect product does not exist, closed source or otherwise!  We know software engineers are human, and thus error is always certain in any document.  It is, though, to be expected that closed source software and its documentation goes through a QU process to ensure that error is at a minimum, and also that their support staff are sufficiently senior that when a user encounters a problem, they are competent enough to jointly test the nature of each complaint and correctly distinguish between a bug in their own product and user error.  In a product that is acceptable for production use, from an acceptable supplier, it is never a case of "that's that".  Failure on either count above guarantees that the library in question will not be used, at least in any product I am responsible for.
 

yes, one can complain until you are blue abotu documentation - and a few comments in this
thread have certainly alerted me to some of OpenSSLs other issues - enough perhaps to look
at GNUTLS or some alternative....'ReallyOpenSSL' anyone? ;-)

It is always a question of examining whichof the available products/libraries to use, vs writing your own code.  In every such case, it is a question of having (only) your senior staff invest a bit of time to evaluate the options.  This includes applying tests to determine the adequacy and reliability, and limit s of application, of the product in question.

I will not waste time on complaining about documentation for one library or another.  Instead, I will examine the product, including its documentation.  I will then make a judgement as to whether or not it will be used, and by which of my staff.  We might even decide to use multiple compeeting products for different tasks, perhaps with our own 'abstraction layer' to ensure that what we have our junior people coding to is of sufficient quality and that we do not get hurt by deficiencies in each of the products we're using.  I set the coding standard for me staff, as well as the criteria that must be met by any library, or other tool, we will use; along with any conditions for their use.  And nne of that is static.  Some of the senior staff are responsible for reviewing available libraries, with a view toward adding or removing products from teh mix, based on deficiencies and improvements that appear in each as they develop.

Cheers

Ted

[Pierre DELAAGE]

If we would have to have deep understanding of the various codes we are using everyday (I am myself a programmer, and openssl WCE contributor),
we would not have enough time to work, to produce anything.

Anyway understanding "what the code is SUPPOSED to do" is one thing, and HOW it is doing it, another thing.
This is the basic difference between specifications and design...

Do you really need to understand the code of zlib to use it ?
the code of libpng to produce png ?
the code of c-lib (written in assembly !!!) to produce c code ?

So, this kind of argument is just pretending sarcasm.

Maybe the doc could be improved by a kind of wiki system ?
Where people having found useful answers in the distribution list could push back some useful info.

This is just a suggestion.

Yours sincerely
Pierre

[james]

> For things that the peer support forum and the existing documentation
don't cover, you have the source code, which is definitive.

The source code can tell you what it DOES do - but the cost of
understanding that can be very high in some cases, and the problem
domain of OpenSSL almost guarantees it.

But what raw source will not tell you is WHY it does what it does, or
what the INTENT was when it was written, or what non-obvious assumptions
are in play and necessary for correct operation.

Nor does it tell you how to use it, and that is not necessarily obvious
from the source code, even if it contains embedded documentation
(comments) that address the points above.

[james]

> the 'many eyes make all bugs shallow' views

You don't believe that, do you?

The number of counter-examples of long-standing bugs in widely available
and active open-source systems should be large enough to call it now.
Especially in subtle, complex systems where there is no documentation of
the design itself - just code.

Bugs in code generators and race conditions in kernels do not become
shallow by making the source available to millions of developers with no
experience in those domains.

[Jakob Bohm]

On 11/13/2012 11:24 PM, Pierre DELAAGE wrote:
> If we would have to have deep understanding of the various codes we are
> using everyday (I am myself a programmer, and openssl WCE contributor),
> we would not have enough time to work, to produce anything.
>
> Anyway understanding "what the code is SUPPOSED to do" is one thing, and
> HOW it is doing it, another thing.
> This is the basic difference between specifications and design...
>

There is also the fundamental rule that good docs indicate what is
allowed to silently change in new versions and what is generally not.

This is important for both library users (to avoid relying on things
that are not going to work in the next version) and for library writers
(to avoid changing things that users rely on).

> Do you really need to understand the code of zlib to use it ?
> the code of libpng to produce png ?
> the code of c-lib (written in assembly !!!) to produce c code ?

(Aside: libc is written mostly in C with as few bits and pieces as
possible coded in assembly for each target CPU, I can say this having
seen the source code for at least GNU, uclinux, Microsoft and Borland
implementations of libc).

>
> So, this kind of argument is just pretending sarcasm.
>
> Maybe the doc could be improved by a kind of wiki system ?
> Where people having found useful answers in the distribution list could
> push back some useful info.
>
> This is just a suggestion.
>

Nah, wiki documentation tends to get completely out of sync with reality
and itself, I have seen that failure in other OSS projects.

Once written, documentation needs to be in sync with the code, just as
header files and test cases do.

>
>
> Le 13/11/2012 23:13, Ted Byers a écrit :
>> On Tue, Nov 13, 2012 at 4:38 PM, alan buxey <A.L.M...@lboro.ac.uk
>> <mailto:A.L.M...@lboro.ac.uk>> wrote:
>>
>> > Nonsense. No-one knows better how the code ought to be
>> working than the
>> > folk who developed it. I begin with the assumption that all
>> my coders are
>>
>>

>> i'd cite the cathedral and the bazaar ...or the 'many eyes make
>> all bugs shallow'

Enjoy

Jakob
--
Jakob Bohm, CIO, Partner, WiseMo A/S. http://www.wisemo.com
Transformervej 29, 2730 Herlev, Denmark. Direct +45 31 13 16 10
This public discussion message is non-binding and may contain errors.
WiseMo - Remote Service Management for PCs, Phones and Embedded

[Marco Molteni (mmolteni)]

Another amen.

I am a professional programmer. I am grateful for OpenSSL. At the same
time, each time I have to use it directly (as opposed to use a few of the
good C++ wrappers) I know I will be going down to hell and fight for my
life, and when I will come back, my hairs will be grayer :-)

Lack of good documentation is a problem for any software library, but in
this case lack of documentation can also cause security vulnerabilities
because the user of the API misunderstood it.

As Charles, I propose as food for though the very recent, very good paper
on the security risks of (among other things) wrong APIs and wrong
documentation:
"The Most Dangerous Code in the World: Validating SSL Certificates in
Non-Browser Software",
available at http://www.cs.utexas.edu/~shmat/shmat_ccs12.pdf

marco.m

On 13.11.2012 19:49 , "Charles Mills" <char...@mcn.org> wrote:

>AMEN!
>
>Why is it easier to answer dumb question after dumb question here rather
>than to document the darned product once? (Never mind the cumulative
>labor of all the
> programmers trying to figure out and debug the same problems again and
>again and again, all over the world.)
>
>Consider
>http://www.cs.utexas.edu/~shmat/shmat_ccs12.pdf. Doesn’t *some* of the
>responsibility for these (severe and scary!) problems fall on the lack of
>clear documentation?
>

>It’s a GREAT product and I love it and am grateful but why after years
>and years do the man pages still say “under construction”?
>

>Charles

[Carlo Wood]

On Tue, 13 Nov 2012 14:11:17 -0700
te...@terralogic.net wrote:
> This is just a NORMAL way for a programmer to work IMHO. I HATE
> comming into undocumented code years after its been written and IMHO
> its a big booby trap because its very easy to miss something and that
> creates hard to find bugs. Really criptic error messages don't help
> this. I've looked in the OOS community and there are attempts to put
> together systems and one I looked at was OXYGEN.

I concur. When I was 12, I wrote compact code with only single
character variables and no documentation. For some reason I was able to
have thousands of code lines all in my head at once and I had no idea
why I'd need to add documentation.

When I got older, I started to use more descriptive variable and
function names, mostly for the purpose of being able to
'grep' (reg.exp) them in large code. At some point I completely did
away with abbreviations and only used complete English words,
discovering that code is incredibly better to understand when the
variable names express exactly what they mean (to the point that it
avoids bugs). I still didn't see the point in documentation however:
the code explained itself as if it was English.

Only when my memory started to get worse and I couldn't remember
Megabytes of code anymore, especially when my code became so complex
that I had to use Object Orientation because it was impossible to keep
an overview, I started to document code. The funny thing is: I did this
mostly because I knew that a year later I wouldn't be able to
understand it myself anymore if I didn't; not because I thought that
anyone else might need it.

Now, after more than 30 years of coding experience I have reached the
same conclusion as terra wrote: Code is only as useful as it's
documentation. Don't bother to write code without good COMPLETE
documentation as it's worthless: only you, the developer (with a good
memory on top of that) will think it's trivial and usable. Everyone
else will not be able to use it.

>
> http://www.stack.nl/~dimitri/doxygen/
>
>
> I have no idea at this time how useful this would be.
>
>
> Perhaps the best we might be able to do on the user side is a wiki
> and perhaps one exists.
>
>
> I did a google search on this.
>
> https://help.ubuntu.com/community/OpenSSL
>
> ^ I did find this and I did not look very hard. Maybe there is
> something better. If there is then it doesn't come up in the 1st
> hits google finds.
>
>
> So I think we can do much better.
>
> Just my 2 cents.

--
Carlo Wood <ca...@alinoe.com>

[Sanford Staab(Gmail)]

It’s interesting that this article shows that LACK OF GOOD DOCUMENTATION and POOR API DESIGN are at the heart of this problem.

I have noticed over the years that much of our society has changed its very idea of what a "good" application is.

It used to be that if something could not be easily understood or behaved badly or unexpectedly, people would see this as a "bug" in need of fixing.

With the rise in software complexity, requirements for budgets and schedules, we have now evolved to a society of "hoop jumpers" who see software as "good enough" if they can find a path to make it do what they want.

Developers have followed suit, practically forced to do so, and we now have massive amounts of broken code on broken code on broken code.

Ownership of code (ie really taking responsibility for it) is unheard of because the onerous burden of being responsible for your work is simply an open door to a lawyer that wants to steal the fruit of your labor.

It is no wonder under these circumstances that “security by obscurity” has become the defacto standard of the day.

The true bug here is our justice system unfortunately.

I think it is high time for a v2 of openssl, a rewrite almost from scratch, removing support for older protocols and ciphers and simplifying it down with full TDD from start to finish to really correct this problem.

And of course, probably not gonna happen.

But thanks for listening.

 

Sandy

 

-----Original Message-----

From: Marco Molteni (mmolteni)

Sent: Thursday, November 15, 2012 4:42 AM

To: openss...@openssl.org

Subject: Re: I can't believe how much this sucks

 

:��I"Ϯ��r�m���� (���Z+�K �+����1���x ��h���[�z�(���Z+� ��f�y��� �� �f���h��)z{,���

[Sanford Staab(Gmail)]

In the case of openssl, a big gain would be to simply document the command
line interface better and create a doc centric forum for people to add their
lessons learned filed around the particular feature area of openssl.
WORKING EXAMPLES would be REAL cool. Does anyone on this alias want to let
me or others know how we can update the docs somehow?

-----Original Message-----
From: Carlo Wood
Sent: Thursday, November 15, 2012 8:31 AM
To: openss...@openssl.org
Subject: Re: I can't believe how much this sucks

[Charles Mills]

That article is unbelievably scary, and your analysis is spot on.

 

I admit it: I sometimes assume that if the C compiler “likes” (matches to a declaration) what I have coded then it must be correct – given the absence of documentation. Did you see the example in the article of the API where a parameter of 1 meant No and 2 meant Yes, and a programmer had coded it passing a value of true, intending it to mean Yes, but which the compiler (of course) accepted and the function saw as a parameter of 1 (= No)?

 

Charles

From: owner-ope...@openssl.org [mailto:owner-ope...@openssl.org] On Behalf Of Sanford Staab(Gmail)
Sent: Thursday, November 15, 2012 5:27 AM
To: openss...@openssl.org
Subject: Re: I can't believe how much this sucks

 

It’s interesting that this article shows that LACK OF GOOD DOCUMENTATION and POOR API DESIGN are at the heart of this problem.

I have noticed over the years that much of our society has changed its very idea of what a "good" application is.

It used to be that if something could not be easily understood or behaved badly or unexpectedly, people would see this as a "bug" in need of fixing.

With the rise in software complexity, requirements for budgets and schedules, we have now evolved to a society of "hoop jumpers" who see software as "good enough" if they can find a path to make it do what they want.

Developers have followed suit, practically forced to do so, and we now have massive amounts of broken code on broken code on broken code.

Ownership of code (ie really taking responsibility for it) is unheard of because the onerous burden of being responsible for your work is simply an open door to a lawyer that wants to steal the fruit of your labor.

It is no wonder under these circumstances that “security by obscurity” has become the defacto standard of the day.

The true bug here is our justice system unfortunately.

I think it is high time for a v2 of openssl, a rewrite almost from scratch, removing support for older protocols and ciphers and simplifying it down with full TDD from start to finish to really correct this problem.

And of course, probably not gonna happen.

But thanks for listening.

 

Sandy

 

-----Original Message-----

From: Marco Molteni (mmolteni)

Sent: Thursday, November 15, 2012 4:42 AM

To: openss...@openssl.org

Subject: Re: I can't believe how much this sucks

 

Another amen.

[Jeffrey Walton]

> WORKING EXAMPLES would be REAL cool.

You kind of have it with the source code to openssl.exe.

Crypto++ had the same way back when (its a C++ crypto library, and its
not nearly as popular as OpenSSL). Users did not check cryptest.exe
for API usage (cryptest.exe is the equivalent of openssl.exe). In
addition, it was terse C++ code and hard to understand.

We fixed most of the "How do I" questions by adding a wiki and
providing code examples. It drastically reduced the number of
questions. When there is a question on basic usage, I just provide a
link to the wiki. For example: http://www.cryptopp.com/wiki/3des,
http://www.cryptopp.com/wiki/Cbc_Mode and
http://www.cryptopp.com/wiki/Rsa.

As Wei Dai (the author of Crypto++) answers design questions or
questions that require insight, I make sure it goes in the wiki for
those who RTFM. For example at
http://www.cryptopp.com/wiki/Elliptic_Curve_Cryptography: "Taking from
Wei Dai on the Crypto++ mailing list: To minimize the size of public
and private keys, what you need to do is encode only the private
exponent of the private key, and the public point of the public key."
We then provide a code sample.

The wiki started out bad - it was sloppy and incomplete. Over time,
the crowd converged on the right answer. Its a property of the crowd.

Jeff

On Thu, Nov 15, 2012 at 9:52 AM, Sanford Staab(Gmail)
<sanf...@gmail.com> wrote:
> In the case of openssl, a big gain would be to simply document the command
> line interface better and create a doc centric forum for people to add their
> lessons learned filed around the particular feature area of openssl. WORKING
> EXAMPLES would be REAL cool. Does anyone on this alias want to let me or
> others know how we can update the docs somehow?
>
> -----Original Message----- From: Carlo Wood

> Sent: Thursday, November 15, 2012 8:31 AM

> To: openss...@openssl.org
> Subject: Re: I can't believe how much this sucks
>
>

[te...@terralogic.net]

On Thu, Nov 15, 2012 at 09:52:49AM -0500, Sanford Staab(Gmail) wrote:
> In the case of openssl, a big gain would be to simply document the command
> line interface better and create a doc centric forum for people to add their
> lessons learned filed around the particular feature area of openssl.
> WORKING EXAMPLES would be REAL cool. Does anyone on this alias want to let
> me or others know how we can update the docs somehow?

I concurr. Life is too short for each of us to have to plod the same ugly goat trail to make it work.

> --
> Carlo Wood <ca...@alinoe.com>

[Gisle Vanem]

"Sanford Staab(Gmail)" <sanf...@gmail.com> wrote:

> I think it is high time for a v2 of openssl, a rewrite almost from scratch, removing
> support for older protocols and ciphers and simplifying it down with full TDD from
> start to finish to really correct this problem.

So why don't you simply switch to PolarSSL?

http://polarssl.org/
... PolarSSL offers an intuitive API and readable source code, so you
can actually understand what the code does.
...

--gv

[Thomas J. Hruska]

On 11/13/2012 11:34 AM, Sanford Staab wrote:
> I have been struggling with openssl for a few months now writing batch scripts on windows trying to make a .net web client with a client certificate work with 2-way ssl against an apache web server.
>

> Do you guys just want to continue to answer questions on this alias and not FIX the docs somewhat over time? I could go into a litany of how much information is just missing from the docs with INCOMPLETE everywhere. (see this link for one of the 900k+ hits on a google search of “openssl+docs+suck” for how much hell you guys are putting people through trying to figure out this tool)

>
> openssl is used all over the world by tons of people (so I feel dumb having problems here – but I know from Google I am not alone.) but it is just unbelievable to me that the docs remain so terse and useless for so many years.
>
> I have sent email to this alias previously asking how I can help with this. It seems to me there should be an openssl docs forum where content from this eventually finds its way into the online docs themselves.
>
> A tool is only as good as people are able to use it.

The OpenSSL dev team consists of fairly old-school *NIX folks. It is a
low-level library and certificate generation and manipulation tool that
has gained significant notoriety for its reliability, stability, and
security.

The primary documentation is manpages. This is an outdated method of
documenting software and, as I've found, the primary source of many
complaints. In this regard, it is time to move on. I can't remember
the last time I had to fire up 'man'. I'm much more apt to just run a
Google search.

Given my experience with end-users of this product, I've come to the
conclusion that there are three distinct forms of documentation needed
for OpenSSL:

- API documentation. This is already fairly complete but hard to find
everything and needs someone to go over it and update it. Areas that
are entirely missing need to be fleshed out. It is also time to
consider an alternative format to the traditional manpage.

- Cookbook usage examples. 'openssl' command-line commands to
accomplish common tasks in a cookbook format. I can point people to
third-party sites (madboa comes to mind). However this sort of thing
should really be on the OpenSSL website.

- Complete, easy-to-follow code examples for a variety of common
programming tasks. There are the test programs, but I view those more
for testing the library for consistency against itself than
demonstration on how to code against the library. There's a difference.
The OpenSSL website should always have the definitive collection in a
copy-and-paste ready format. Also, OpenSSL is used within a variety of
programming languages. Examples and integration by language would be
ideal. Pick the top three to five languages that cause the most churn
on this list (C# comes to mind as #1).


It is approaching six months since the last OpenSSL update. We're
probably due for a new set of source releases any time now. So now is
the ideal time to talk it up about getting "better documentation" on the
dev team's schedule while they begin the planning stages of the next
release. If you succeed at this, you'll be my hero of the month because
I've been wanting this for ages. You might want to approach the devs
though with a little more respect/tact. Saying the documentation
"sucks" is a great way to get ignored. Their time is valuable.

--
Thomas Hruska
Shining Light Productions

Home of BMP2AVI and Win32 OpenSSL.
http://www.slproweb.com/

[Jeffrey Walton]

> [SNIP]

>
> It is approaching six months since the last OpenSSL update. We're probably
> due for a new set of source releases any time now. So now is the ideal time
> to talk it up about getting "better documentation" on the dev team's
> schedule while they begin the planning stages of the next release. If you
> succeed at this, you'll be my hero of the month because I've been wanting
> this for ages. You might want to approach the devs though with a little
> more respect/tact. Saying the documentation "sucks" is a great way to get
> ignored. Their time is valuable.

You can lead them to water, but you can;t make them drink:
http://rt.openssl.org/Ticket/Display.html?id=2697&user=guest&pass=guest.

Jeff

[John Zavgren]

Thomas:

You make very good suggestions. Of them all (aside from the use of tact in approaching the developers :-) ), I think that easy-to-follow code examples would improve the openSSL experience more than anything else you identify. These examples could even provide a natural context for the "cookbook usage examples", and then we'd achieve two of your objectives.

I can recall situations where I had to incorporate a cartographic calculation in code I was writing, e.g., compute a signature, and was unable to find any examples, and the man pages were a poor starting point. They are good for learning the individual library procedures, but they aren't good for pulling them together to create a working software module. (In fact, when I needed to learn how to compute a signature, I downloaded the openVPN source code and read it.)

So, what is a list of easy-to-follow code examples? Here are some suggestions:

1.) read private key and a message from a file: encrypt message with private key, write encrypted buffer to (another) file.

2.) read cert and private key, read file, compute signature, etc.

3.) read file, read signature, read ca certs, validate signature.

4.) Example 3 + check CRL.

5.) Example 3 + check with OCSP responder.

???

I'm sure there are a LOT of CA related examples that would help, because I find the creation of a CA to be one of the more painful exercises.

On Sun, Nov 18, 2012 at 11:19 PM, Thomas J. Hruska <shine...@shininglightpro.com> wrote:

On 11/13/2012 11:34 AM, Sanford Staab wrote:

I have been struggling with openssl for a few months now writing batch scripts on windows trying to make a .net web client with a client certificate work with 2-way ssl against an apache web server.

Do you guys just want to continue to answer questions on this alias and not FIX the docs somewhat over time?  I could go into a litany of how much information is just missing from the docs with INCOMPLETE everywhere.  (see this link for one of the 900k+ hits on a google search of “openssl+docs+suck” for how much hell you guys are putting people through trying to figure out this tool)

openssl is used all over the world by tons of people (so I feel dumb having problems here – but I know from Google I am not alone.) but it is just unbelievable to me that the docs remain so terse and useless for so many years.

I have sent email to this alias previously asking how I can help with this.  It seems to me there should be an openssl docs forum where content from this eventually finds its way into the online docs themselves.

A tool is only as good as people are able to use it.

The OpenSSL dev team consists of fairly old-school *NIX folks.  It is a low-level library and certificate generation and manipulation tool that has gained significant notoriety for its reliability, stability, and security.

The primary documentation is manpages.  This is an outdated method of documenting software and, as I've found, the primary source of many complaints.  In this regard, it is time to move on.  I can't remember the last time I had to fire up 'man'.  I'm much more apt to just run a Google search.

Given my experience with end-users of this product, I've come to the conclusion that there are three distinct forms of documentation needed for OpenSSL:

- API documentation.  This is already fairly complete but hard to find everything and needs someone to go over it and update it.  Areas that are entirely missing need to be fleshed out.  It is also time to consider an alternative format to the traditional manpage.

- Cookbook usage examples.  'openssl' command-line commands to accomplish common tasks in a cookbook format.  I can point people to third-party sites (madboa comes to mind).  However this sort of thing should really be on the OpenSSL website.

- Complete, easy-to-follow code examples for a variety of common programming tasks.  There are the test programs, but I view those more for testing the library for consistency against itself than demonstration on how to code against the library.  There's a difference.  The OpenSSL website should always have the definitive collection in a copy-and-paste ready format.  Also, OpenSSL is used within a variety of programming languages.  Examples and integration by language would be ideal.  Pick the top three to five languages that cause the most churn on this list (C# comes to mind as #1).

It is approaching six months since the last OpenSSL update.  We're probably due for a new set of source releases any time now.  So now is the ideal time to talk it up about getting "better documentation" on the dev team's schedule while they begin the planning stages of the next release.  If you succeed at this, you'll be my hero of the month because I've been wanting this for ages.  You might want to approach the devs though with a little more respect/tact.  Saying the documentation "sucks" is a great way to get ignored.  Their time is valuable.

--
Thomas Hruska
Shining Light Productions

Home of BMP2AVI and Win32 OpenSSL.
http://www.slproweb.com/

______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
User Support Mailing List                    openss...@openssl.org
Automated List Manager                           majo...@openssl.org

--

No amount of believing makes something a fact. James Randi

John Zavgren
603-371-0513 (home)
603-801-2094 (cell)
johnzavgren (skype)
603-821-0904 (skype)
jo...@zavgren.com

[Charles Mills]

It tends to be a shortcoming of many, many types of software documentation that it is feature-oriented rather than task-oriented. That is, it does a good job of saying “this switch does this, that parm specfies that” and a poor job of answering the question “I want to accomplish X. What the heck do I do?” Examples are good, but they are not the only, and perhaps not the best, way of presenting task-oriented documentation. (The trouble with an example is one sometimes finds oneself asking “do I HAVE to do it that way, or did that writer just CHOOSE to do it that way?”)

 

Charles

From: owner-ope...@openssl.org [mailto:owner-ope...@openssl.org] On Behalf Of John Zavgren
Sent: Monday, November 19, 2012 6:45 AM
To: openss...@openssl.org
Subject: Re: I can't believe how much this sucks

 

Thomas:

[Ted Byers]

On Mon, Nov 19, 2012 at 9:45 AM, John Zavgren <jo...@zavgren.com> wrote:

Thomas:

You make very good suggestions. Of them all (aside from the use of tact in approaching the developers :-) ), I think that easy-to-follow code examples would improve the openSSL experience more than anything else you identify. These examples could even provide a natural context for the "cookbook usage examples", and then we'd achieve two of your objectives.

I can recall situations where I had to incorporate a cartographic calculation in code I was writing, e.g., compute a signature, and was unable to find any examples, and the man pages were a poor starting point. They are good for learning the individual library procedures, but they aren't good for pulling them together to create a working software module. (In fact, when I needed to learn how to compute a signature, I downloaded the openVPN source code and read it.)

So, what is a list of easy-to-follow code examples? Here are some suggestions:

1.) read private key and a message from a file: encrypt message with private key, write encrypted buffer to (another) file.

2.) read cert and private key, read file, compute signature, etc.

3.) read file, read signature, read ca certs, validate signature.

4.) Example 3 + check CRL.

5.) Example 3 + check with OCSP responder.

???

I'm sure there are a LOT of CA related examples that would help, because I find the creation of a CA to be one of the more painful exercises.

I concur.  But I'd take it a step further.  To take C/C++ programming, as an example.  It is one thing to learn to write decent code, but quite another to write 'secure' code.  I have several references that assume a better than average knowledge of C and C++, and focusses on good and bad coding practices that  relate to writing secure code.  All of the code, good and bad, in these rferences is legal C or C++, but some of it represents an opportunity for bad guys to hack the application for whatever purpose.

Similarly, I would suggest that your easy to follow examples include several variants of each use case, and followed by illustrations of coding practice that are possible withthe library but ill advised because they compromise security acompanied by examples of how to support the same requirement without compromising security.  I would suggest that this is especially important for a library like openssl since it will only be used in applications in which one of the main requirements is security, and using it badly seems likely to make the application using it less secure than it would be without use of a library like it.

Cheers

Ted

[Jakob Bohm]

Actually, the primary format is the Perl POD format, which can be
readily "compiled" to multiple formats, including manpages (which I
prefer when coding on POSIX-like systems), HTML pages and a few others.

It would be nice if:

1. The documentation collection on openssl.org is automatically kept in
sync with the latest release tarball.

2. There are alternate areas on openssl.org holding the latest in each
of the still maintained older release series (such as 0.9.8 and 1.0.0)
and the latest development head.

3. There was an extra option in the non-POSIX build scripts for building
an indexed and cross linked folder of HTML docs, perhaps the same script
used for the automated web site updating

4. There was an extra option in the Win32/Win64 build scripts which
package the HTML pages into a properly indexed .chm file.

Enjoy

Jakob
--
Jakob Bohm, CIO, Partner, WiseMo A/S. http://www.wisemo.com
Transformervej 29, 2730 Herlev, Denmark. Direct +45 31 13 16 10
This public discussion message is non-binding and may contain errors.
WiseMo - Remote Service Management for PCs, Phones and Embedded

[Richard Könning]

Am 19.11.2012 15:45, schrieb John Zavgren:
>
> So, what is a list of easy-to-follow code examples? Here are some
> suggestions:
> 1.) read private key and a message from a file: encrypt message with
> private key, write encrypted buffer to (another) file.
> 2.) read cert and private key, read file, compute signature, etc.
> 3.) read file, read signature, read ca certs, validate signature.
> 4.) Example 3 + check CRL.
> 5.) Example 3 + check with OCSP responder.
> ???
> I'm sure there are a LOT of CA related examples that would help, because
> I find the creation of a CA to be one of the more painful exercises.

Well, many of these things are covered at least partially by the OpenSSL
book from Viega et al. The book is somewhat outdated/incomplete but
still my first reference when i have to implement a new cryptography
related task with OpenSSL.

Best regards,
Richard