-.\" $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.
.\"
.\" 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 ,
.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"
.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"
.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 .
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
.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
.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
.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.
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.
.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 ,
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
.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
projects / openbsd / commitdiff