In evp.h rev. 1.56 2018/02/17 14:55:31, jsing@ provided

EVP_MD_CTX_new(3), EVP_MD_CTX_reset(3), and EVP_MD_CTX_free(3).
Merge the documentation from OpenSSL, tweaked by me.
Also merge a few other minor improvements from OpenSSL.

While here, improve the order of functions, improve the description
of deprecated functions, fix a few other minor bugs, and remove an
irrelevant warning about binary incompatibility.

1 files changed, 129 insertions, 78 deletions

diff --git a/lib/libcrypto/man/EVP_DigestInit.3 b/lib/libcrypto/man/EVP_DigestInit.3
index c327164bc0a..9e2f3d06658 100644
--- a/lib/libcrypto/man/EVP_DigestInit.3
+++ b/lib/libcrypto/man/EVP_DigestInit.3
@@ -1,8 +1,9 @@
-.\"	$OpenBSD: EVP_DigestInit.3,v 1.6 2017/03/25 17:54:04 schwarze Exp $
-.\"	OpenSSL d2a56999 Sep 24 13:37:16 2016 +0200
-.\"	OpenSSL 7f572e95 Dec 2 13:57:04 2015 +0000
+.\" $OpenBSD: EVP_DigestInit.3,v 1.7 2018/02/18 20:11:16 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
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" This 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.
 .\" All rights reserved.
 .\"
@@ -50,18 +51,21 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 25 2017 $
+.Dd $Mdocdate: February 18 2018 $
 .Dt EVP_DIGESTINIT 3
 .Os
 .Sh NAME
+.Nm EVP_MD_CTX_new ,
+.Nm EVP_MD_CTX_reset ,
+.Nm EVP_MD_CTX_free ,
 .Nm EVP_MD_CTX_init ,
 .Nm EVP_MD_CTX_create ,
+.Nm EVP_MD_CTX_cleanup ,
+.Nm EVP_MD_CTX_destroy ,
 .Nm EVP_MD_CTX_ctrl ,
 .Nm EVP_DigestInit_ex ,
 .Nm EVP_DigestUpdate ,
 .Nm EVP_DigestFinal_ex ,
-.Nm EVP_MD_CTX_cleanup ,
-.Nm EVP_MD_CTX_destroy ,
 .Nm EVP_MD_CTX_copy_ex ,
 .Nm EVP_DigestInit ,
 .Nm EVP_DigestFinal ,
@@ -93,13 +97,31 @@
 .Nd EVP digest routines
 .Sh SYNOPSIS
 .In openssl/evp.h
+.Ft EVP_MD_CTX *
+.Fn EVP_MD_CTX_new void
+.Ft int
+.Fo EVP_MD_CTX_reset
+.Fa "EVP_MD_CTX *ctx"
+.Fc
+.Ft void
+.Fo EVP_MD_CTX_free
+.Fa "EVP_MD_CTX *ctx"
+.Fc
 .Ft void
 .Fo EVP_MD_CTX_init
 .Fa "EVP_MD_CTX *ctx"
 .Fc
 .Ft EVP_MD_CTX *
 .Fn EVP_MD_CTX_create void
+.Ft int
+.Fo EVP_MD_CTX_cleanup
+.Fa "EVP_MD_CTX *ctx"
+.Fc
 .Ft void
+.Fo EVP_MD_CTX_destroy
+.Fa "EVP_MD_CTX *ctx"
+.Fc
+.Ft int
 .Fo EVP_MD_CTX_ctrl
 .Fa "EVP_MD_CTX *ctx"
 .Fa "int cmd"
@@ -125,14 +147,6 @@
 .Fa "unsigned int *s"
 .Fc
 .Ft int
-.Fo EVP_MD_CTX_cleanup
-.Fa "EVP_MD_CTX *ctx"
-.Fc
-.Ft void
-.Fo EVP_MD_CTX_destroy
-.Fa "EVP_MD_CTX *ctx"
-.Fc
-.Ft int
 .Fo EVP_MD_CTX_copy_ex
 .Fa "EVP_MD_CTX *out"
 .Fa "const EVP_MD_CTX *in"
@@ -223,29 +237,57 @@
 .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
+allocates a new, empty digest context.
+.Pp
+.Fn EVP_MD_CTX_reset
+cleans up
+.Fa ctx
+and resets it to the state it had after
+.Fn EVP_MD_CTX_new ,
+such that it can be reused.
+It is also suitable for digest contexts on the stack that were
+used and are no longer needed.
+.Pp
+.Fn EVP_MD_CTX_free
+cleans up
+.Fa ctx
+and frees the space allocated to it.
 .Pp
 .Fn EVP_MD_CTX_init
-initializes the digest context
-.Fa ctx .
+is a deprecated function to clear a digest context on the stack
+before use.
+Do not use it on a digest context returned from
+.Fn EVP_MD_CTX_new
+or one one that was already used.
 .Pp
-.Fn EVP_MD_CTX_create
-allocates, initializes, and returns a digest context.
+.Fn EVP_MD_CTX_create ,
+.Fn EVP_MD_CTX_cleanup ,
+and
+.Fn EVP_MD_CTX_destroy
+are deprecated aliases for
+.Fn EVP_MD_CTX_new ,
+.Fn EVP_MD_CTX_reset ,
+and
+.Fn EVP_MD_CTX_free ,
+respectively.
 .Pp
 .Fn EVP_MD_CTX_ctrl
 performs digest-specific control actions on the context
 .Fa ctx .
 .Pp
 .Fn EVP_DigestInit_ex
-sets up digest context
+sets up the digest context
 .Fa ctx
 to use a digest
 .Fa type
 from
 .Vt ENGINE
 .Fa impl .
-.Fa ctx
-must be initialized before calling this function.
+The
 .Fa type
 will typically be supplied by a function such as
 .Fn EVP_sha1 .
@@ -256,6 +298,11 @@ is
 then the default implementation of digest
 .Fa type
 is used.
+If
+.Fa ctx
+points to an unused object on the stack, it must be initialized with
+.Fn EVP_MD_CTX_init
+before calling this function.
 .Pp
 .Fn EVP_DigestUpdate
 hashes
@@ -291,18 +338,6 @@ can be made, but
 .Fn EVP_DigestInit_ex
 can be called to initialize a new digest operation.
 .Pp
-.Fn EVP_MD_CTX_cleanup
-cleans up the digest context
-.Fa ctx .
-It should be called after a digest context is no longer needed.
-.Pp
-.Fn EVP_MD_CTX_destroy
-cleans up the digest context
-.Fa ctx
-and frees up the space allocated to it.
-It should be called only on a context created using
-.Fn EVP_MD_CTX_create .
-.Pp
 .Fn EVP_MD_CTX_copy_ex
 can be used to copy the message digest state from
 .Fa in
@@ -310,30 +345,36 @@ to
 .Fa out .
 This is useful if large amounts of data are to be hashed which only
 differ in the last few bytes.
+If
 .Fa out
-must be initialized before calling this function.
+points to an unused object on the stack, it must be initialized with
+.Fn EVP_MD_CTX_init
+before calling this function.
 .Pp
 .Fn EVP_DigestInit
-behaves in the same way as
+is a deprecated function behaving like
 .Fn EVP_DigestInit_ex
-except the passed context
-.Fa ctx
-does not have to be initialized, and it always uses the default digest
-implementation.
+except that it always uses the default digest implementation
+and that it requires
+.Fn EVP_MD_CTX_reset
+before it can be used on a context that was already used.
 .Pp
 .Fn EVP_DigestFinal
-is similar to
+is a deprecated function behaving like
 .Fn EVP_DigestFinal_ex
-except the digest context
+except that the digest context
 .Fa ctx
-is automatically cleaned up.
+is automatically cleaned up after use by calling
+.Fn EVP_MD_CTX_reset
+internally.
 .Pp
 .Fn EVP_MD_CTX_copy
-is similar to
+is a deprecated function behaving like
 .Fn EVP_MD_CTX_copy_ex
-except the destination
-.Fa out
-does not have to be initialized.
+except that it requires
+.Fn EVP_MD_CTX_reset
+before a context that was already used can be passed as
+.Fa out .
 .Pp
 .Fn EVP_MD_size
 and
@@ -366,12 +407,6 @@ returns
 .Dv NID_sha1 .
 This function is normally used when setting ASN.1 OIDs.
 .Pp
-.Fn EVP_MD_CTX_md
-returns the
-.Vt EVP_MD
-structure corresponding to the passed
-.Vt EVP_MD_CTX .
-.Pp
 .Fn EVP_MD_pkey_type
 returns the NID of the public key signing algorithm associated with this
 digest.
@@ -465,40 +500,37 @@ because they can efficiently reuse a digest context instead of
 initializing and cleaning it up on each call and allow non-default
 implementations of digests to be specified.
 .Pp
-In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after
-use memory leaks will occur.
-.Pp
-Stack allocation of
+If digest contexts are not cleaned up after use, memory leaks will occur.
+.Sh RETURN VALUES
+.Fn EVP_MD_CTX_new
+and
+.Fn EVP_MD_CTX_create
+return the new
 .Vt EVP_MD_CTX
-structures is common, for example:
-.Bd -literal -offset indent
-EVP_MD_CTX mctx;
-EVP_MD_CTX_init(&mctx);
-.Ed
+object or
+.Dv NULL
+for failure.
+.Pp
+.Fn EVP_MD_CTX_reset
+and
+.Fn EVP_MD_CTX_cleanup
+always return 1.
 .Pp
-This will cause binary compatibility issues if the size of
-.Vt EVP_MD_CTX
-structure changes (this will only happen with a major release of OpenSSL).
-Applications wishing to avoid this should use
-.Fn EVP_MD_CTX_create
-instead:
-.Bd -literal -offset indent
-EVP_MD_CTX *mctx;
-mctx = EVP_MD_CTX_create();
-.Ed
-.Sh RETURN VALUES
 .Fn EVP_MD_CTX_ctrl ,
 .Fn EVP_DigestInit_ex ,
 .Fn EVP_DigestUpdate ,
 .Fn EVP_DigestFinal_ex ,
+.Fn EVP_MD_CTX_copy_ex ,
+.Fn EVP_DigestInit ,
+.Fn EVP_DigestFinal ,
 and
-.Fn EVP_MD_CTX_copy_ex
+.Fn EVP_MD_CTX_copy
 return 1 for success or 0 for failure.
 .Pp
 .Fn EVP_MD_type ,
 .Fn EVP_MD_pkey_type ,
 and
-.Fn EVP_MD_type
+.Fn EVP_MD_CTX_type
 return the NID of the corresponding OBJECT IDENTIFIER or
 .Dv NID_undef
 if none exists.
@@ -510,6 +542,18 @@ and
 .Fn EVP_MD_CTX_block_size
 return the digest or block size in bytes.
 .Pp
+.Fn EVP_MD_CTX_md
+returns the
+.Vt EVP_MD
+object used by
+.Fa ctx ,
+or
+.Dv NULL
+if
+.Fa ctx
+is
+.Dv NULL .
+.Pp
 .Fn EVP_md_null ,
 .Fn EVP_md2 ,
 .Fn EVP_md5 ,
@@ -562,17 +606,19 @@ main(int argc, char *argv[])
 		exit(1);
 	}
 
-	mdctx = EVP_MD_CTX_create();
+	mdctx = EVP_MD_CTX_new();
 	EVP_DigestInit_ex(mdctx, md, NULL);
 	EVP_DigestUpdate(mdctx, mess1, strlen(mess1));
 	EVP_DigestUpdate(mdctx, mess2, strlen(mess2));
 	EVP_DigestFinal_ex(mdctx, md_value, &md_len);
-	EVP_MD_CTX_destroy(mdctx);
+	EVP_MD_CTX_free(mdctx);
 
 	printf("Digest is: ");
 	for(i = 0; i < md_len; i++)
 		printf("%02x", md_value[i]);
 	printf("\en");
+
+	return 0;
 }
 .Ed
 .Sh SEE ALSO
@@ -606,6 +652,11 @@ were changed to return truly const
 .Vt EVP_MD
 pointers in OpenSSL 0.9.7.
 .Pp
+.Fn EVP_MD_CTX_new
+and
+.Fn EVP_MD_CTX_free
+first appeared in OpenSSL 1.1.0.
+.Pp
 The link between digests and signing algorithms was fixed in OpenSSL 1.0
 and later, so now
 .Fn EVP_sha1