Merge various improvements from the OpenSSL 1.1 branch,

which is still under a free license.

* document EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags
* document EVP_MD_flags, EVP_MD_CTX_md_data
* document EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx
* correct arg type of EVP_MD_CTX_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type
* more information about EVP_MD_CTX_ctrl
* add missing <string.h> and correct one variable type below EXAMPLES
* two orthographic improvements

with a few wording tweaks by me

1 files changed, 148 insertions, 13 deletions

diff --git a/lib/libcrypto/man/EVP_DigestInit.3 b/lib/libcrypto/man/EVP_DigestInit.3
index ba9d6a04810..08b64b59b24 100644
--- a/lib/libcrypto/man/EVP_DigestInit.3
+++ b/lib/libcrypto/man/EVP_DigestInit.3
@@ -1,6 +1,6 @@
-.\" $OpenBSD: EVP_DigestInit.3,v 1.25 2023/04/23 18:24:01 job Exp $
+.\" $OpenBSD: EVP_DigestInit.3,v 1.26 2023/08/11 18:08:43 schwarze Exp $
 .\" full merge up to: OpenSSL 7f572e95 Dec 2 13:57:04 2015 +0000
-.\" selective merge up to: OpenSSL a95d7574 Jul 2 12:16:38 2017 -0400
+.\" 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:
@@ -19,9 +19,11 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>
-.\" and Richard Levitte <levitte@openssl.org>.
-.\" Copyright (c) 2000-2004, 2009, 2012-2016 The OpenSSL Project.
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>,
+.\" Richard Levitte <levitte@openssl.org>,
+.\" Paul Yang <yang.yang@baishancloud.com>, and
+.\" Antoine Salon <asalon@vmware.com>.
+.\" Copyright (c) 2000-2004, 2009, 2012-2016, 2018, 2019 The OpenSSL Project.
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -68,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: April 23 2023 $
+.Dd $Mdocdate: August 11 2023 $
 .Dt EVP_DIGESTINIT 3
 .Os
 .Sh NAME
@@ -80,6 +82,9 @@
 .Nm EVP_MD_CTX_cleanup ,
 .Nm EVP_MD_CTX_destroy ,
 .Nm EVP_MD_CTX_ctrl ,
+.Nm EVP_MD_CTX_set_flags ,
+.Nm EVP_MD_CTX_clear_flags ,
+.Nm EVP_MD_CTX_test_flags ,
 .Nm EVP_DigestInit_ex ,
 .Nm EVP_DigestUpdate ,
 .Nm EVP_DigestFinal_ex ,
@@ -93,10 +98,14 @@
 .Nm EVP_MD_pkey_type ,
 .Nm EVP_MD_size ,
 .Nm EVP_MD_block_size ,
+.Nm EVP_MD_flags ,
 .Nm EVP_MD_CTX_md ,
 .Nm EVP_MD_CTX_size ,
 .Nm EVP_MD_CTX_block_size ,
 .Nm EVP_MD_CTX_type ,
+.Nm EVP_MD_CTX_md_data ,
+.Nm EVP_MD_CTX_pkey_ctx ,
+.Nm EVP_MD_CTX_set_pkey_ctx ,
 .Nm EVP_md_null ,
 .Nm EVP_md5 ,
 .Nm EVP_md5_sha1 ,
@@ -145,6 +154,21 @@
 .Fa "int p1"
 .Fa "void* p2"
 .Fc
+.Ft void
+.Fo EVP_MD_CTX_set_flags
+.Fa "EVP_MD_CTX *ctx"
+.Fa "int flags"
+.Fc
+.Ft void
+.Fo EVP_MD_CTX_clear_flags
+.Fa "EVP_MD_CTX *ctx"
+.Fa "int flags"
+.Fc
+.Ft int
+.Fo EVP_MD_CTX_test_flags
+.Fa "const EVP_MD_CTX *ctx"
+.Fa "int flags"
+.Fc
 .Ft int
 .Fo EVP_DigestInit_ex
 .Fa "EVP_MD_CTX *ctx"
@@ -210,21 +234,38 @@
 .Fo EVP_MD_block_size
 .Fa "const EVP_MD *md"
 .Fc
+.Ft unsigned long
+.Fo EVP_MD_flags
+.Fa "const EVP_MD *md"
+.Fc
 .Ft const EVP_MD *
 .Fo EVP_MD_CTX_md
 .Fa "const EVP_MD_CTX *ctx"
 .Fc
 .Ft int
 .Fo EVP_MD_CTX_size
-.Fa "const EVP_MD *ctx"
+.Fa "const EVP_MD_CTX *ctx"
 .Fc
 .Ft int
 .Fo EVP_MD_CTX_block_size
-.Fa "const EVP_MD *ctx"
+.Fa "const EVP_MD_CTX *ctx"
 .Fc
 .Ft int
 .Fo EVP_MD_CTX_type
-.Fa "const EVP_MD *ctx"
+.Fa "const EVP_MD_CTX *ctx"
+.Fc
+.Ft void *
+.Fo EVP_MD_CTX_md_data
+.Fa "const EVP_MD_CTX *ctx"
+.Fc
+.Ft EVP_PKEY_CTX *
+.Fo EVP_MD_CTX_pkey_ctx
+.Fa "const EVP_MD_CTX *ctx"
+.Fc
+.Ft void
+.Fo EVP_MD_CTX_set_pkey_ctx
+.Fa "EVP_MD_CTX *ctx"
+.Fa "EVP_PKEY_CTX *pctx"
 .Fc
 .Ft const EVP_MD *
 .Fn EVP_md_null void
@@ -261,7 +302,7 @@
 .Fa "const ASN1_OBJECT *o"
 .Fc
 .Sh DESCRIPTION
-The EVP digest routines are a high level interface to message digests
+The EVP digest routines are a high-level interface to message digests
 and should be used instead of the cipher-specific functions.
 .Pp
 .Fn EVP_MD_CTX_new
@@ -300,6 +341,42 @@ respectively.
 .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
+.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
+and digest implementation.
+.Pp
+If the
+.Fa cmd
+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 ctx
+flags:
+.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.
+.It Dv EVP_MD_CTX_FLAG_ONESHOT
+Instruct the digest to optimize for one update only, if possible.
+.El
 .Pp
 .Fn EVP_DigestInit_ex
 sets up the digest context
@@ -431,7 +508,8 @@ or an
 .Vt EVP_MD_CTX
 structure.
 .Pp
-.Fn EVP_MD_type
+.Fn EVP_MD_type ,
+.Fn EVP_MD_pkey_type ,
 and
 .Fn EVP_MD_CTX_type
 return the NID of the OBJECT IDENTIFIER representing the given message
@@ -444,6 +522,23 @@ returns
 .Dv NID_sha1 .
 This function is normally used when setting ASN.1 OIDs.
 .Pp
+.Fn EVP_MD_CTX_md_data
+returns the digest method private data of
+.Fa ctx .
+The space was allocated and its size set with
+.Xr EVP_MD_meth_set_app_datasize 3 .
+.Pp
+.Fn EVP_MD_flags
+returns the
+.Fa md
+flags.
+These are different from the
+.Vt EVP_MD_CTX
+ones.
+See
+.Xr EVP_MD_meth_set_flags 3
+for more information.
+.Pp
 .Fn EVP_MD_pkey_type
 returns the NID of the public key signing algorithm associated with this
 digest.
@@ -454,6 +549,40 @@ is associated with RSA so this will return
 Since digests and signature algorithms are no longer linked, this
 function is only retained for compatibility reasons.
 .Pp
+.Fn EVP_MD_CTX_pkey_ctx
+returns the
+.Vt EVP_PKEY_CTX
+assigned to
+.Fa ctx .
+The returned pointer should not be freed by the caller.
+.Pp
+.Fn EVP_MD_CTX_set_pkey_ctx
+assigns
+.Fa pctx
+to
+.Fa ctx .
+This is usually used to provide a customized
+.Vt EVP_PKEY_CTX
+to
+.Xr EVP_DigestSignInit 3
+or
+.Xr EVP_DigestVerifyInit 3 .
+The
+.Fa pctx
+passed to this function should be freed by the caller.
+A
+.Dv NULL
+.Fa pctx
+pointer is also allowed to clear the
+.Vt EVP_PKEY_CTX
+assigned to
+.Fa ctx .
+In this case, freeing the cleared
+.Vt EVP_PKEY_CTX
+or not depends on how the
+.Vt EVP_PKEY_CTX
+was created.
+.Pp
 .Fn EVP_md5 ,
 .Fn EVP_sha1 ,
 .Fn EVP_sha224 ,
@@ -502,7 +631,7 @@ and
 are implemented as macros.
 .Pp
 The EVP interface to message digests should almost always be used
-in preference to the low level interfaces.
+in preference to the low-level interfaces.
 This is because the code then becomes transparent to the digest used and
 much more flexible.
 .Pp
@@ -610,6 +739,7 @@ This example digests the data "Test Message\en" and "Hello World\en",
 using the digest name passed on the command line.
 .Bd -literal -offset indent
 #include <stdio.h>
+#include <string.h>
 #include <openssl/evp.h>
 
 int
@@ -620,7 +750,7 @@ main(int argc, char *argv[])
 	const char mess1[] = "Test Message\en";
 	const char mess2[] = "Hello World\en";
 	unsigned char md_value[EVP_MAX_MD_SIZE];
-	int md_len, i;
+	unsigned int md_len, i;
 
 	if (argc <= 1) {
 		printf("Usage: mdtest digestname\en");
@@ -655,6 +785,7 @@ main(int argc, char *argv[])
 .Xr EVP_BytesToKey 3 ,
 .Xr EVP_DigestSignInit 3 ,
 .Xr EVP_DigestVerifyInit 3 ,
+.Xr EVP_MD_meth_new 3 ,
 .Xr EVP_PKEY_CTX_set_signature_md 3 ,
 .Xr EVP_PKEY_meth_set_signctx 3 ,
 .Xr EVP_SignInit 3 ,
@@ -750,6 +881,10 @@ and
 first appeared in OpenSSL 1.1.0 and have been available since
 .Ox 6.3 .
 .Pp
+.Fn EVP_MD_CTX_set_pkey_ctx
+first appeared in OpenSSL 1.1.1 and has been available since
+.Ox 7.1 .
+.Pp
 The link between digests and signing algorithms was fixed in OpenSSL 1.0
 and later, so now
 .Fn EVP_sha1