DH parameter reading in OPENSSL 3

[Mark H. Wood]

On Wed, Jul 13, 2022 at 06:45:48PM +0200, Dirk Stöcker wrote:
> The openssl documentation may be logical for someone who knows all the 
> parts and how they work together, but for everybody else it's a large 
> glob of isolated files which you simply can't bring together. You have 
> pages which sometimes describe dozens of functions which seldom have 
> examples and at least for me they don't help.
> 
> My initial TLS implementation took me days (although I do nothing except 
> loading the parameters (key,cert,chain) and setup the stuff). Mostly I 
> only got that done looking at the openssl tools and how they do it. AFTER 
> you know how the code looks like the documentation helps but not to 
> getting to this state. Essentially for me the documentation thus always 
> was only a means to verify that the examples I used actually are correct 
> and not written by somebody who also doesn't understand it.

This sounds like trying to build something given a Reference Manual
but no Programmer's Guide.

The Reference Manual describes each function, data structure, and file
format in full detail.  It's essential for understanding individual
operations but says nothing about orchestrating them to perform
higher-level tasks.  It's just a complete list of fully-described
features.  As you said, this is where you go to understand code that
already exists or that you have already designed and are writing now.

The Programmer's Guide discusses the logical organization of the
package, how typical higher-level tasks might use individual features
of the package in sequence, which features go together, which are
similar but distinct, and generally what are good ways to think about
working with the product.  IOW it describes many common things that
you can accomplish using those features.  This is where you go for
basic understanding of how to organize a new design in terms of the
available features of the package.

A developer who is not already working with the product on a daily
basis will probably start in the Programmer's Guide when creating a
new design, and have both open when coding.  That's my experience,
anyway.  One more familiar with the package will have less need for
the Guide, but it never becomes entirely unnecessary.

These two ways of thinking about a product are complementary, and a
developer shifts between these modes of thought often while working.

I agree that a Migration Guide will, after a brief discussion of the
high-level differences between old and new, consist mostly of "if you
did task T that way before, now you should do it something like this"
for many values of T drawn from the Programmer's Guide.

-- 
Mark H. Wood
Lead Technology Analyst

University Library
Indiana University - Purdue University Indianapolis
755 W. Michigan Street
Indianapolis, IN 46202
317-274-0749
www.ulib.iupui.edu
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 195 bytes
Desc: not available
URL: <https://mta.openssl.org/pipermail/openssl-users/attachments/20220714/5397fcef/attachment.sig>