[openssl-users] minor documentation errors

[Ben Humpert]

2015-05-09 21:47 GMT+02:00 Salz, Rich <rsalz at akamai.com>:
>
>> After getting into building and especially configuring my own CA again I'm
>> nearly at the end and I've noticed some errors in the documentation I want
>> to report.
>
> I like the "again" :)

Yeah, once upon a time I had done a comprehensive configuration with a
Root CA and two Signing CAs and wrote down the command lines I need to
use but then I didn't even touched it for over four years so I only
had few memories. A good PKI tutorial and my files helped me getting
into it again quickly.

>> 1) On https://www.openssl.org/docs/apps/ca.html for the -md option not all
>> possible values (sha256, sha384, etc.) are list but just md5, sha1 and mdc2
>> 2) On https://www.openssl.org/docs/apps/req.html for the -[digest] option
>> not all possible values are listed
>> 4) On https://www.openssl.org/docs/apps/req.html for the default_md
>> option not all possible values are listed (shouldn't this reference the -[digest]
>> option)
>> 5) On https://www.openssl.org/docs/apps/x509.html not all available
>> options are listed in -md2|-md5|-sha1|-mdc2
>
> Getting this correct is incredibly painful, as it depends on the configuration options chosen when building openssl, and right now the manpages are not affected by the config.  Our plan for this is to say "any supported digest."   That will be updated in a couple of days, and then pushed to the website in hour or so later.

I see. I thought about mentioning "get a list of supported (message)
digests by using the command > openssl list-message-digest-commands <
in the doc but after I tried that command I just got md4, md5, rmd160,
sha, sha1 but since I was able to create a sha-256 with the -sha256
command option I guess it's just the wrong command to get a list of
supported digest?

I also tried openssl list-message-digest-algorithms and that shows
SHA512, SHA256, whirlpool (I like that one) and more. However I don't
think that it shows the correct names of supported options
(case-sensitive?). Additionally some options are listed twice like
DSA, DSA-SHA, MD4, MD5. Is that a bug too?

While being on it I also issued openssl list-cipher-algorithms and
here all entries are listed twice. The output gives a list which
contains of list (B) appended to list (A). List (A) has 93 unique
entries and shows aliases uppercase (eg. CAMELLIA256 =>
CAMELLIA-256-CBC). List (B) has 100 entries, 97 of them are unique.
Aliases are shown lowercase (camellia256 => CAMELLIA-256-CBC). The
additional entries are id-aes128-GCM, id-aes192-GCM, id-aes256-GCM and
blowfish => BF-CBC while the three aes ones are listed twice (once
correctly between AES-xxx-ECB and and AES-xxx-OFB once incorrectly
between DESX-CBC and rc2 => RC2-CBC).

>> I also would like to ask if there's a newer version (or subtree) of openssl that
>> is cleaned up.
>
> I don't know what you mean by this.

Well I just asked because if that would've been planned I would've
liked to participate in that process. What I meant was a version
that's cleaned up of superseded / deprecated commands and has a more
logical structure or command names, eg. no CA command and not three
different ways of getting the same result. It's simple enough for
doing simple stuff like quickly getting a self-signed certificate and
just gets a little bit more complicated than it has so be when you
begin with complex stuff. But I don't have a problem with how it's
done now :)

>> Currently there are many ways of creating a CSR, signing a
>> certificate, etc. I think this is confusing everybody.
>
> The CA script is a wrapper around the various commands, and is reasonable.  But we're not planning on removing any of the current mechanisms.  Ivan Ristic has a really great, free, OpenSSL cookbook that might be useful: https://www.feistyduck.com/books/openssl-cookbook/

Thanks for that like. I'll definitely cook some delicious meals with that ;)