1. Tweak the descriptions of EVP_MD_CTX_ctrl(3), EVP_MD_CTX_set_flags(3),

EVP_MD_CTX_clear_flags(3), EVP_MD_CTX_test_flags(3), and the atrocious
EVP_MD_CTX_set_pkey_ctx(3) for precision.
2. Tweak the description of EVP_MD_type(3) and EVP_MD_CTX_type(3)
for conciseness.
3. Add a few missing HISTORY bits.

1 files changed, 107 insertions, 52 deletions

diff --git a/src/lib/libcrypto/man/EVP_DigestInit.3 b/src/lib/libcrypto/man/EVP_DigestInit.3
index 08b64b59b2..6c75adcc98 100644
--- a/src/lib/libcrypto/man/EVP_DigestInit.3
+++ b/src/lib/libcrypto/man/EVP_DigestInit.3
@@ -1,11 +1,11 @@
-.\" $OpenBSD: EVP_DigestInit.3,v 1.26 2023/08/11 18:08:43 schwarze Exp $
+.\" $OpenBSD: EVP_DigestInit.3,v 1.27 2023/08/12 16:12:19 schwarze Exp $
 .\" full merge up to: OpenSSL 7f572e95 Dec 2 13:57:04 2015 +0000
 .\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
 .\"
-.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2019, 2023 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -70,7 +70,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 11 2023 $
+.Dd $Mdocdate: August 12 2023 $
 .Dt EVP_DIGESTINIT 3
 .Os
 .Sh NAME
@@ -150,7 +150,7 @@
 .Ft int
 .Fo EVP_MD_CTX_ctrl
 .Fa "EVP_MD_CTX *ctx"
-.Fa "int cmd"
+.Fa "int command"
 .Fa "int p1"
 .Fa "void* p2"
 .Fc
@@ -339,43 +339,67 @@ and
 respectively.
 .Pp
 .Fn EVP_MD_CTX_ctrl
-performs digest-specific control actions on the context
-.Fa ctx .
-The control command is indicated in
-.Fa cmd
-and any additional arguments in
+performs the digest-specific control
+.Fa command
+with the command-specific arguments
 .Fa p1
 and
-.Fa p2 .
-.Fn EVP_MD_CTX_ctrl
-must be called after
-.Fn EVP_DigestInit_ex .
-Other restrictions may apply depending on the control type
+.Fa p2
+on
+.Fa ctx ,
+which needs to already be set up with
+.Fn EVP_DigestInit_ex
+before calling this function.
+Other restrictions may apply depending on the control
+.Fa command
 and digest implementation.
 .Pp
 If the
-.Fa cmd
+.Fa command
 is
 .Dv EVP_MD_CTRL_MICALG ,
-the digest Message Integrity Check algorithm string is written to
-.Pf * p2 .
-This is used when creating S/MIME multipart/signed messages
-as specified in RFC 3851.
-.Pp
-.Fn EVP_MD_CTX_set_flags ,
-.Fn EVP_MD_CTX_clear_flags ,
-and
-.Fn EVP_MD_CTX_test_flags
-set, clear and test the following
+.Fa p1
+is ignored and
+.Fa p2
+is an output argument of the type
+.Fa "char **p2" .
+A string specifying the digest Message Integrity Check algorithm
+is allocated and a pointer to this string is returned in
+.Pf * Fa p2 .
+It is the responsibility of the caller to
+.Xr free 3
+.Pf * Fa p2
+when it is no longer needed.
+This
+.Fa command
+is used by
+.Xr SMIME_write_ASN1 3
+when creating S/MIME multipart/signed messages as specified in RFC 3851.
+.Pp
+.Fn EVP_MD_CTX_set_flags
+sets and
+.Fn EVP_MD_CTX_clear_flags
+clears all the flag bits in
 .Fa ctx
-flags:
+that are set in the
+.Fa flags
+argument.
+.Fn EVP_MD_CTX_test_flags
+tests which of the flag bits that are set in the
+.Fa flags
+argument are also set in
+.Fa ctx .
+Possible flag bits are:
 .Bl -tag -width Ds -offset 2n
 .It Dv EVP_MD_CTX_FLAG_NO_INIT
 Instruct
-.Fn EVP_DigestInit
-and similar functions not to initialise the implementation specific data.
+.Fn EVP_DigestInit_ex
+and functions calling it not to initialise the internal data
+that is specific to the digest method and its implementation.
 .It Dv EVP_MD_CTX_FLAG_ONESHOT
 Instruct the digest to optimize for one update only, if possible.
+For digest algorithms built into the library, this flag usually
+has no effect.
 .El
 .Pp
 .Fn EVP_DigestInit_ex
@@ -508,19 +532,15 @@ or an
 .Vt EVP_MD_CTX
 structure.
 .Pp
-.Fn EVP_MD_type ,
-.Fn EVP_MD_pkey_type ,
+.Fn EVP_MD_type
 and
 .Fn EVP_MD_CTX_type
-return the NID of the OBJECT IDENTIFIER representing the given message
-digest when passed an
-.Vt EVP_MD
-structure.
+return the NID of the OBJECT IDENTIFIER representing the message digest.
 For example
 .Fn EVP_MD_type EVP_sha1()
 returns
 .Dv NID_sha1 .
-This function is normally used when setting ASN.1 OIDs.
+These functions are normally used when setting ASN.1 OIDs.
 .Pp
 .Fn EVP_MD_CTX_md_data
 returns the digest method private data of
@@ -561,27 +581,43 @@ assigns
 .Fa pctx
 to
 .Fa ctx .
-This is usually used to provide a customized
+This is normally used to provide a customized
 .Vt EVP_PKEY_CTX
 to
 .Xr EVP_DigestSignInit 3
 or
 .Xr EVP_DigestVerifyInit 3 .
-The
+The caller retains ownership of the
 .Fa pctx
-passed to this function should be freed by the caller.
-A
+passed to this function and is responsible for freeing it
+when it is no longer needed.
+.Pp
+If the
+.Fa ctx
+already contains a
+.Vt EVP_PKEY_CTX
+when this function is called, that old
+.Vt EVP_PKEY_CTX
+is freed if it was created internally, but if it was also installed with
+.Fn EVP_MD_CTX_set_pkey_ctx ,
+the pointer to the old
+.Vt EVP_PKEY_CTX
+is merely replaced by the new pointer and ownership of the old
+.Vt EVP_PKEY_CTX
+remains with the previous caller.
+.Pp
+Passing a
 .Dv NULL
+pointer for the
 .Fa pctx
-pointer is also allowed to clear the
-.Vt EVP_PKEY_CTX
-assigned to
-.Fa ctx .
-In this case, freeing the cleared
+argument is also allowed.
+In that case, any
 .Vt EVP_PKEY_CTX
-or not depends on how the
+already assigned to
+.Fa ctx
+is dissociated from it as described above, but no new
 .Vt EVP_PKEY_CTX
-was created.
+is assigned.
 .Pp
 .Fn EVP_md5 ,
 .Fn EVP_sha1 ,
@@ -688,6 +724,12 @@ and
 .Fn EVP_MD_CTX_copy
 return 1 for success or 0 for failure.
 .Pp
+.Fn EVP_MD_CTX_test_flags
+returns the bitwise OR of the
+.Fa flags
+argument and the flags set in
+.Fa ctx .
+.Pp
 .Fn EVP_MD_type ,
 .Fn EVP_MD_pkey_type ,
 and
@@ -846,6 +888,9 @@ first appeared in OpenSSL 0.9.5 and has been available since
 .Fn EVP_MD_CTX_create ,
 .Fn EVP_MD_CTX_cleanup ,
 .Fn EVP_MD_CTX_destroy ,
+.Fn EVP_MD_CTX_set_flags ,
+.Fn EVP_MD_CTX_clear_flags ,
+.Fn EVP_MD_CTX_test_flags ,
 .Fn EVP_DigestInit_ex ,
 .Fn EVP_DigestFinal_ex ,
 .Fn EVP_Digest ,
@@ -863,11 +908,10 @@ first appeared in OpenSSL 0.9.7h and 0.9.8a
 and have been available since
 .Ox 4.0 .
 .Pp
-.Fn EVP_sha512_224
-and
-.Fn EVP_sha512_256
-first appeared in OpenSSL 1.1.1 and has been available since
-.Ox 7.4 .
+.Fn EVP_MD_flags
+first appeared in OpenSSL 1.0.0
+and has been available since
+.Ox 4.9 .
 .Pp
 .Fn EVP_MD_CTX_ctrl
 first appeared in OpenSSL 1.1.0 and has been available since
@@ -881,10 +925,21 @@ and
 first appeared in OpenSSL 1.1.0 and have been available since
 .Ox 6.3 .
 .Pp
+.Fn EVP_MD_CTX_md_data
+and
+.Fn EVP_MD_CTX_pkey_ctx
+first appeared in OpenSSL 1.1.0 and
 .Fn EVP_MD_CTX_set_pkey_ctx
-first appeared in OpenSSL 1.1.1 and has been available since
+in OpenSSL 1.1.1.
+These functions have been available since
 .Ox 7.1 .
 .Pp
+.Fn EVP_sha512_224
+and
+.Fn EVP_sha512_256
+first appeared in OpenSSL 1.1.1 and have been available since
+.Ox 7.4 .
+.Pp
 The link between digests and signing algorithms was fixed in OpenSSL 1.0
 and later, so now
 .Fn EVP_sha1