Re: I can't believe how much this sucks
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 shineli...@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. --
RE: I can't believe how much this sucks
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-openssl-us...@openssl.org [mailto:owner-openssl-us...@openssl.org] On Behalf Of John Zavgren Sent: Monday, November 19, 2012 6:45 AM To: openssl-users@openssl.org Subject: Re: I can't believe how much this sucks 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 shineli...@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
Re: I can't believe how much this sucks
On Mon, Nov 19, 2012 at 9:45 AM, John Zavgren j...@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
Re: I can't believe how much this sucks
On 11/19/2012 5:19 AM, Thomas J. Hruska 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. 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 __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: I can't believe how much this sucks
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 __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: I can't believe how much this sucks
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 Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: I can't believe how much this sucks
On Sun, Nov 18, 2012 at 11:19 PM, Thomas J. Hruska shineli...@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. [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=2697user=guestpass=guest. Jeff __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: I can't believe how much this sucks
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 charl...@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
:��IϮ��r�m
(Z+�K �+1���x ��h[�z�(Z+� ��f�y�� �f���h��)z{,���
Re: I can't believe how much this sucks
On Tue, 13 Nov 2012 14:11:17 -0700 t...@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 __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
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: openssl-users@openssl.org
Subject: Re: I can't believe how much this sucks
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 charl...@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
:��IϮ��r�m (���Z+�K �+1���x ��h���[�z�(���Z+�
��f�y����� �f���h��)z{,���
Re: I can't believe how much this sucks
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: openssl-users@openssl.org Subject: Re: I can't believe how much this sucks On Tue, 13 Nov 2012 14:11:17 -0700 t...@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 __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
RE: I can't believe how much this sucks
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-openssl-us...@openssl.org [mailto:owner-openssl-us...@openssl.org]
On Behalf Of Sanford Staab(Gmail)
Sent: Thursday, November 15, 2012 5:27 AM
To: openssl-users@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: openssl-users@openssl.org
Subject: Re: I can't believe how much this sucks
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
http://www.cs.utexas.edu/~shmat/shmat_ccs12.pdf
marco.m
On 13.11.2012 19:49 , Charles Mills charl...@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
:��IϮ��r�m (���Z+�K‑�+1���x ��h���[�z�(���Z+�
��f�y�‑�f���h��)z{,���
Re: I can't believe how much this sucks
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) sanfo...@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: openssl-users@openssl.org Subject: Re: I can't believe how much this sucks On Tue, 13 Nov 2012 14:11:17 -0700 t...@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. __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: I can't believe how much this sucks
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. -Original Message- From: Carlo Wood Sent: Thursday, November 15, 2012 8:31 AM To: openssl-users@openssl.org Subject: Re: I can't believe how much this sucks On Tue, 13 Nov 2012 14:11:17 -0700 t...@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 __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: I can't believe how much this sucks
Sanford Staab(Gmail) sanfo...@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 __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: I can't believe how much this sucks
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.bu...@lboro.ac.uk mailto:a.l.m.bu...@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' 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
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 chainFrom 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 Description: Binary data CONNECTED(0190) --- Certificate chain 0 s:/C=KY/ST=Grand Cayman/O=CashWiz/OU=Development/CN=www.pawnmasterpro.com i:/C=KY/ST=Grand Cayman/L=George Town/O=CashWiz/OU=Development/CN=CashWiz Root CA -BEGIN CERTIFICATE- MIID2zCCAsOgAwIBAgIBCjANBgkqhkiG9w0BAQQFADB8MQswCQYDVQQGEwJLWTEV MBMGA1UECBMMR3JhbmQgQ2F5bWFuMRQwEgYDVQQHEwtHZW9yZ2UgVG93bjEQMA4G A1UEChMHQ2FzaFdpejEUMBIGA1UECxMLRGV2ZWxvcG1lbnQxGDAWBgNVBAMTD0Nh c2hXaXogUm9vdCBDQTAeFw0xMjExMTMxNzI5NDBaFw0yMjExMTExNzI5NDBaMGwx CzAJBgNVBAYTAktZMRUwEwYDVQQIEwxHcmFuZCBDYXltYW4xEDAOBgNVBAoTB0Nh c2hXaXoxFDASBgNVBAsTC0RldmVsb3BtZW50MR4wHAYDVQQDExV3d3cucGF3bm1h c3RlcnByby5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDTp1dY GOY2ew6O7CbHvokVMSYNYv/uBghjeO3hP2FVXQSCfPWk4NpCh1ve8vu9kUgZ6Ezh slTSn7FM5RlG3NoOx1XnVkJNQ30cRX7oi01l1vwXHPvxn+dq0gJzGofamSYv6Hkm X+zhqhiK37GFmHG5gVZVKg84fEOV10WI+9j6SuOoVg646Rsu91Q3ZYW+v08ucmrC ZfoeuxXwZ/6kJkn8PkRb0RAgy20UMkYTPj7dgC5HkVlDdldJ1+IxegNGG0pMM6SW E6J08mAOs4t2wZ+oybtQZ4+2aeKylMUb/EEDBkSh+bab9k4fe48cmBxj4mnumajx b5pkm3d8HXOk1N5nAgMBAAGjeDB2MAkGA1UdEwQCMAAwHQYDVR0OBBYEFL5T2NTf xfmf3exS2OZB+t8ghcZ/MB8GA1UdIwQYMBaAFFRJfotvTu3PmEaV9+qJf95MmP1e MAsGA1UdDwQEAwIF4DARBglghkgBhvhCAQEEBAMCBkAwCQYDVR0RBAIwADANBgkq hkiG9w0BAQQFAAOCAQEAXlG4az+P/JrtNVgLux67FMQomimcppYVqkPS/HgERZvp VUhTxWClKqC+wQ4RS90VtjcMGQs7iPL5D+563u0CudBaXz3QK7oVInGLAqEIEhfa Si/S6tKA8bxeujKY5GnppRfV9DcTYIjX1eCLx+n8neI9gwiaKgXV8XLIQoE8g/r6 3Dsfn/uLatQZM7a+V8U/JtF/fGHP81M1D2aqG2JmSayZ9gMgwPAPqI3OdGRsCDqj zTI3z6XomblD1cUdEepMCxnhRHsGVaVXOY0ubM1zWB3b92pVDsKV8TwAlzeijGE1 vAVRptr58jAQXVIN0M3HzmtneHulvOP7UFu2Ozm4OQ== -END CERTIFICATE- 1 s:/C=KY/ST=Grand Cayman/O=CashWiz/OU=Development/CN=www.pawnmasterpro.com i:/C=KY/ST=Grand Cayman/L=George Town/O=CashWiz/OU=Development/CN=CashWiz Root CA -BEGIN CERTIFICATE-
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.
Re: I can't believe how much this sucks
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 Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
RE: I can't believe how much this sucks
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-openssl-us...@openssl.org [mailto:owner-openssl-us...@openssl.org] On Behalf Of Sanford Staab Sent: Tuesday, November 13, 2012 10:35 AM To: openssl-users@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 http://www.wolmarans.com/drupal/?q=node/22 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.
Re: I can't believe how much this sucks
On Tue, Nov 13, 2012 at 6:34 PM, Sanford Staab sanfo...@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__ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: [openssl-users] I can't believe how much this sucks
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 http://www.wolmarans.com/drupal/?q=node/22 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.
Re: I can't believe how much this sucks
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, j...@iastate.edu 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 Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: I can't believe how much this sucks
On Tue, Nov 13, 2012 at 2:02 PM, Lee Fisher blib...@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
Re: I can't believe how much this sucks
On Tue, Nov 13, 2012 at 1:34 PM, Sanford Staab sanfo...@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 __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: I can't believe how much this sucks
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=782user=guestpass=guest [2] http://rt.openssl.org/Ticket/Display.html?id=1794user=guestpass=guest [3] http://rt.openssl.org/Ticket/Display.html?user=guestpass=guestid=2402 [4] http://rt.openssl.org/Ticket/Display.html?user=guestpass=guestid=2401 [5] http://rt.openssl.org/Ticket/Display.html?id=2697user=guestpass=guest __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: I can't believe how much this sucks
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 Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: I can't believe how much this sucks
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, j...@iastate.edu 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 Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: I can't believe how much this sucks
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. pgpNJNzqoTBIj.pgp Description: PGP signature
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: openssl-users@openssl.org Subject: Re: I can't believe how much this sucks On Tue, Nov 13, 2012 at 2:02 PM, Lee Fisher blib...@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
Re: I can't believe how much this sucks
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: openssl-users@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. (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.
Re: I can't believe how much this sucks
On Tue, Nov 13, 2012 at 3:18 PM, alan buxey a.l.m.bu...@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
RE: I can't believe how much this sucks
EXACTLY! Charles From: owner-openssl-us...@openssl.org [mailto:owner-openssl-us...@openssl.org] On Behalf Of Sanford Staab Sent: Tuesday, November 13, 2012 12:53 PM To: openssl-users@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 mailto:r.ted.by...@gmail.com Sent: Tuesday, November 13, 2012 2:49 PM To: openssl-users@openssl.org Subject: Re: I can't believe how much this sucks On Tue, Nov 13, 2012 at 2:02 PM, Lee Fisher blib...@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
Re: I can't believe how much this sucks
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 Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: I can't believe how much this sucks
On Tue, Nov 13, 2012 at 4:38 PM, alan buxey a.l.m.bu...@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
Re: I can't believe how much this sucks
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 Le 13/11/2012 23:13, Ted Byers a écrit : On Tue, Nov 13, 2012 at 4:38 PM, alan buxey a.l.m.bu...@lboro.ac.uk mailto:a.l.m.bu...@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
Re: I can't believe how much this sucks
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. __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: I can't believe how much this sucks
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. __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
