crypto(7) no longer exists; EVP_*(3) point to a five-level manual chase instead of EVP_MD-*(7)

[nabijaczleweli]

I'd wanted to fix

but crypto(7) doesn't exist anymore:

$ git show d5b7d0a6a2c7263c4bc22a9403e05bc80d324f9a --stat
commit d5b7d0a6a2c7263c4bc22a9403e05bc80d324f9a
Author: Matt Caswell <matt@openssl.org>
Date:   Thu Jul 13 15:02:40 2023 +0100

    Incorporate the crypto man page into the OpenSSL guide

    Some content has been moved out into the general libraries introduction.
    Reformat and fill in some gaps with what remains.

    Reviewed-by: Hugo Landau <hlandau@openssl.org>
    Reviewed-by: Tim Hudson <tjh@openssl.org>
    Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
    Reviewed-by: Anton Arapov <anton@openssl.org>
    (Merged from https://github.com/openssl/openssl/pull/21560)

 doc/man7/crypto.pod                            | 580 ---------------------------------------------------------------------------------------------------------------------
 doc/man7/ossl-guide-libcrypto-introduction.pod | 398 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 398 insertions(+), 580 deletions(-)

and yet git grep crypto\(7 yields precisely 100 lines. Not great. Trivial fix, this is patch 1.

---

Earlier today I finally buckled and tried to find out what the

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_MD_fetch(3) instead. See "Performance" in crypto(7) for further information.

paragraph means.

This took me 5 (five!) manuals:

• EVP_sha1(3)
• crypto(7)
• EVP_MD_fetch(3) (but not there! don't read that!)
• OSSL_PROVIDER-default(7)
• EVP_MD-SHA1(7)

just to find out what I'm supposed to give EVP_MD_fetch() (well okay, SHA was easy, but what "providers" call BLAKE2 was too nebulous to guess). Which is not great, considering these are supposed to be replacing the EVP_* functions, but what you're supposed to be replacing it with is deadass buried. Thus I made the paragraphs that contained "and should consider using" be

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_MD_fetch(3) with EVP_MD-BLAKE2(7) instead. See "Performance" in ossl-guide-libcrypto-introduction(7) for further information.

Which, I think, is useful to the developer instead of damning them for using the "legacy" function with no obvious recourse. This is patch 2.

[t8m]

@nabijaczleweli The first commit is not needed. The crypto(7) manpage still exists as a link to the guide. See for example: https://www.openssl.org/docs/manmaster/man7/crypto.html

[t8m]

Unfortunately this is also outside of what would be acceptable with CLA: trivial. Would you be willing to sign a regular CLA?
https://www.openssl.org/policies/cla.html

[nabijaczleweli]

That wasn't immediately obvious to me, the crypto.7 alias doesn't get created with just make all (but make install does make /usr/local/share/man/man7/crypto.7ossl, so that checks out). Patch 1 dropped.

"CLA: trivial" stanza dropped, ICLA mailed to legal@ as <pnojsdlcsdow2cpjktdndxcmc3fuvtfssg6jtao7chnh43ykig@tarta.nabijaczleweli.xyz>

[mattcaswell]

This looks good to me.

[openssl-machine]

This pull request is ready to merge

[mattcaswell]

Pushed to master/3.1/3.0. Thanks!