From: schwarze Date: Sun, 18 Feb 2018 20:11:16 +0000 (+0000) Subject: In evp.h rev. 1.56 2018/02/17 14:55:31, jsing@ provided X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=6b8038413d2fa17d0592387141a1e1abfd536a9f;p=openbsd 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. --- 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 . +.\" This file was written by Dr. Stephen Henson +.\" and Richard Levitte . .\" 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