I can't believe how much this sucks

classic Classic list List threaded Threaded
41 messages Options
123
Reply | Threaded
Open this post in threaded view
|

I can't believe how much this sucks

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

httpd-ssl.conf (11K) Download Attachment
output.txt (8K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: I can't believe how much this sucks

Ben Laurie-2
On Tue, Nov 13, 2012 at 6:34 PM, Sanford Staab <[hidden email]> 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______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
User Support Mailing List                    [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

RE: I can't believe how much this sucks

Charles Mills
In reply to this post by Sanford Staab

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: [hidden email] [mailto:[hidden email]] On Behalf Of Sanford Staab
Sent: Tuesday, November 13, 2012 10:35 AM
To: [hidden email]
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.
Reply | Threaded
Open this post in threaded view
|

Re: I can't believe how much this sucks

"Magosányi, Árpád"
In reply to this post by Sanford Staab
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.

Reply | Threaded
Open this post in threaded view
|

Re: I can't believe how much this sucks

Lee Fisher
In reply to this post by Sanford Staab
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                    [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: I can't believe how much this sucks

John Hascall
In reply to this post by Charles Mills

> 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, [hidden email]
Team Lead, NIADS (Network Infrastructure, Authentication & Directory Services)
IT Services, The Iowa State University of Science and Technology
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
User Support Mailing List                    [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: [openssl-users] I can't believe how much this sucks

Erwann ABALEA
In reply to this post by Sanford Staab
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 <a class="moz-txt-link-freetext" href="file:ssl\keys\Client_1_pwd.txt">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.
Reply | Threaded
Open this post in threaded view
|

Re: I can't believe how much this sucks

Ted Byers
In reply to this post by Lee Fisher
On Tue, Nov 13, 2012 at 2:02 PM, Lee Fisher <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

Re: I can't believe how much this sucks

Jeffrey Walton-3
In reply to this post by Sanford Staab
On Tue, Nov 13, 2012 at 1:34 PM, Sanford Staab <[hidden email]> 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
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
User Support Mailing List                    [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: I can't believe how much this sucks

Jeffrey Walton-3
In reply to this post by "Magosányi, Árpád"
On Tue, Nov 13, 2012 at 1:51 PM, "Magosányi, Árpád" <[hidden email]> 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
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
User Support Mailing List                    [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: I can't believe how much this sucks

Mark H. Wood
In reply to this post by "Magosányi, Árpád"
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   [hidden email]
Asking whether markets are efficient is like asking whether people are smart.

attachment0 (205 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: I can't believe how much this sucks

Alan Buxey
In reply to this post by Ted Byers
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
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
User Support Mailing List                    [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: I can't believe how much this sucks

Terrell
In reply to this post by John Hascall

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, [hidden email]
> Team Lead, NIADS (Network Infrastructure, Authentication & Directory Services)
> IT Services, The Iowa State University of Science and Technology
> ______________________________________________________________________
> OpenSSL Project                                 http://www.openssl.org
> User Support Mailing List                    [hidden email]
> Automated List Manager                           [hidden email]
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
User Support Mailing List                    [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: I can't believe how much this sucks

Sanford Staab
In reply to this post by "Magosányi, Árpád"
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.
 
Sent: Tuesday, November 13, 2012 1:51 PM
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.

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

Reply | Threaded
Open this post in threaded view
|

Re: I can't believe how much this sucks

Sanford Staab
In reply to this post by Ted Byers
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.
 
Sent: Tuesday, November 13, 2012 2:49 PM
Subject: Re: I can't believe how much this sucks
 
On Tue, Nov 13, 2012 at 2:02 PM, Lee Fisher <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

Re: I can't believe how much this sucks

Ted Byers
In reply to this post by Alan Buxey


On Tue, Nov 13, 2012 at 3:18 PM, alan buxey <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

openssh_DSA_verify_inFIPS EVP_VerifyFinal BAD SIG code:-1 ERROR

Anamitra Dutta Majumdar (anmajumd)
We are getting the following error in the syslogs

secure:Nov  9 19:32:04 cls2-pub authpriv 3 sshd[9526]: error: openssh_DSA_verify_inFIPS EVP_VerifyFinal BAD SIG code:-1

when we connect between two servers using ssh key based authentication. 
This issue happens only in FIPS mode and not in non FIPS mode.

What is the root cause for this and what is the workaround.

Any pointers would be appreciated.

Thanks,
Anamitra
Reply | Threaded
Open this post in threaded view
|

RE: I can't believe how much this sucks

Charles Mills
In reply to this post by Sanford Staab

EXACTLY!

 

Charles

From: [hidden email] [mailto:[hidden email]] On Behalf Of Sanford Staab
Sent: Tuesday, November 13, 2012 12:53 PM
To: [hidden email]
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.

 

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

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

 

On Tue, Nov 13, 2012 at 2:02 PM, Lee Fisher <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

Re: I can't believe how much this sucks

Alan Buxey
In reply to this post by Ted Byers
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.

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.


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? ;-)


alan
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
User Support Mailing List                    [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: I can't believe how much this sucks

Ted Byers
On Tue, Nov 13, 2012 at 4:38 PM, alan buxey <[hidden email]> 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
123