CJ Holmes wrote:
>
> >On Thu, Dec 23, 1999 at 11:53:16AM -0600, Leland V. Lammert wrote:
> > > As a toolkit, OpenSSL can only be used *directly* by a programmer
> > > that knows C/C++, and in that case documentation is not required, as
> > > the programmer has the experience to use the toolkit directly.
> >
> >As a programmer using OpenSSL, I have to say that this statement is false.
>
> I don't normally like to post "me too" messages, but...
>
> What he said!
>
> OpenSSL is a great example of everything that is right about
> OpenSource software. It provides a very good, flexible solution for
> a complex problem. The contributions of many talented people make it
> an excellent resource, and reading the source is a very interesting
> education.
>
> But the state of the API documentation is dismal. Much of what does
> exist is dated, incomplete, or simply not useful. To say that
> OpenSSL should only be used by people who can understand the source
> code seems to imply that we should replace one computing priesthood
> -- the commercial software vendors -- with another -- people with
> enough training and experience to understand some rather difficult
> material.
>
Well I don't like to say "me too" either but I have to agree.
Eric for whatever reason decided not to write much documentation. The
rest of us now need to analyse the source code to document it.
As some may have noticed I've started documenting the 'openssl' commands
in the latest snapshots. This is because these were IMHO a priority
because the documentation was in a worse state than anything else and
the various options probably get asked about more than anything else.
While doing this I learnt that several options don't work or behave in
an inconsistent and/or non sensical manner or do rather questionable
things. So I ended up not only documenting but also fixing the code as
well.
One of the issues is that applications wherever possible should not
directly access structure elements. There should be functions that do
this instead.
If you look at how certificate and certificate request fields are
handled in 'req' in official releases you'll see that they are handled
in a largely ad hoc way with various hacks to fix up the type of the
string that aren't correct in some cases. In particular you can end up
with illegal IA5Strings in certificate fields and BMPStrings and
UTF8Strings aren't used at all.
Attribute handling in certificate requests is even worse, the structure
is populated manually. What we really need is an attribute handling
library which is what I'm currently writing.
This will mean that documentation will take longer than I initially
thought but the utilities should be in a much healthier state at the end
of it.
Steve.
--
Dr Stephen N. Henson. http://www.drh-consultancy.demon.co.uk/
Personal Email: [EMAIL PROTECTED]
Senior crypto engineer, Celo Communications: http://www.celocom.com/
Core developer of the OpenSSL project: http://www.openssl.org/
Business Email: [EMAIL PROTECTED] PGP key: via homepage.
______________________________________________________________________
OpenSSL Project http://www.openssl.org
User Support Mailing List [EMAIL PROTECTED]
Automated List Manager [EMAIL PROTECTED]
