NAME
EVP_MD_CTX_new,
EVP_MD_CTX_reset,
EVP_MD_CTX_free,
EVP_MD_CTX_init,
EVP_MD_CTX_create,
EVP_MD_CTX_cleanup,
EVP_MD_CTX_destroy,
EVP_MD_CTX_ctrl,
EVP_DigestInit_ex,
EVP_DigestUpdate,
EVP_DigestFinal_ex,
EVP_Digest,
EVP_MD_CTX_copy_ex,
EVP_DigestInit,
EVP_DigestFinal,
EVP_MD_CTX_copy,
EVP_MAX_MD_SIZE,
EVP_MD_type,
EVP_MD_pkey_type,
EVP_MD_size,
EVP_MD_block_size,
EVP_MD_CTX_md,
EVP_MD_CTX_size,
EVP_MD_CTX_block_size,
EVP_MD_CTX_type,
EVP_md_null, EVP_md5,
EVP_md5_sha1, EVP_sha1,
EVP_sha224, EVP_sha256,
EVP_sha384, EVP_sha512,
EVP_ripemd160,
EVP_get_digestbyname,
EVP_get_digestbynid,
EVP_get_digestbyobj —
EVP digest routines
SYNOPSIS
#include
<openssl/evp.h>
EVP_MD_CTX *
EVP_MD_CTX_new(void);
int
EVP_MD_CTX_reset(EVP_MD_CTX
*ctx);
void
EVP_MD_CTX_free(EVP_MD_CTX
*ctx);
void
EVP_MD_CTX_init(EVP_MD_CTX
*ctx);
EVP_MD_CTX *
EVP_MD_CTX_create(void);
int
EVP_MD_CTX_cleanup(EVP_MD_CTX
*ctx);
void
EVP_MD_CTX_destroy(EVP_MD_CTX
*ctx);
int
EVP_MD_CTX_ctrl(EVP_MD_CTX *ctx,
int cmd, int p1,
void* p2);
int
EVP_DigestInit_ex(EVP_MD_CTX
*ctx, const EVP_MD *type, ENGINE
*impl);
int
EVP_DigestUpdate(EVP_MD_CTX
*ctx, const void *d, size_t
cnt);
int
EVP_DigestFinal_ex(EVP_MD_CTX
*ctx, unsigned char *md,
unsigned int *s);
int
EVP_Digest(const void *d,
size_t cnt, unsigned char *md,
unsigned int *s, const EVP_MD
*type, ENGINE *impl);
int
EVP_MD_CTX_copy_ex(EVP_MD_CTX
*out, const EVP_MD_CTX *in);
int
EVP_DigestInit(EVP_MD_CTX *ctx,
const EVP_MD *type);
int
EVP_DigestFinal(EVP_MD_CTX *ctx,
unsigned char *md, unsigned int
*s);
int
EVP_MD_CTX_copy(EVP_MD_CTX *out,
EVP_MD_CTX *in);
#define EVP_MAX_MD_SIZE 64 /* SHA512
*/
int
EVP_MD_type(const EVP_MD
*md);
int
EVP_MD_pkey_type(const EVP_MD
*md);
int
EVP_MD_size(const EVP_MD
*md);
int
EVP_MD_block_size(const EVP_MD
*md);
const EVP_MD *
EVP_MD_CTX_md(const EVP_MD_CTX
*ctx);
int
EVP_MD_CTX_size(const EVP_MD
*ctx);
int
EVP_MD_CTX_block_size(const EVP_MD
*ctx);
int
EVP_MD_CTX_type(const EVP_MD
*ctx);
const EVP_MD *
EVP_md_null(void);
const EVP_MD *
EVP_md5(void);
const EVP_MD *
EVP_md5_sha1(void);
const EVP_MD *
EVP_sha1(void);
const EVP_MD *
EVP_sha224(void);
const EVP_MD *
EVP_sha256(void);
const EVP_MD *
EVP_sha384(void);
const EVP_MD *
EVP_sha512(void);
const EVP_MD *
EVP_ripemd160(void);
const EVP_MD *
EVP_get_digestbyname(const char
*name);
const EVP_MD *
EVP_get_digestbynid(int
type);
const EVP_MD *
EVP_get_digestbyobj(const ASN1_OBJECT
*o);
DESCRIPTION
The EVP digest routines are a high level interface to message digests and should be used instead of the cipher-specific functions.
EVP_MD_CTX_new()
allocates a new, empty digest context.
EVP_MD_CTX_reset()
cleans up ctx and resets it to the state it had after
EVP_MD_CTX_new(), such that it can be reused.
EVP_MD_CTX_free()
cleans up ctx and frees the space allocated to it.
EVP_MD_CTX_init()
is a deprecated function to clear a digest context on the stack before use.
Do not use it on a digest context returned from
EVP_MD_CTX_new() or one that was already used.
EVP_MD_CTX_create(),
EVP_MD_CTX_cleanup(),
and
EVP_MD_CTX_destroy()
are deprecated aliases for EVP_MD_CTX_new(),
EVP_MD_CTX_reset(), and
EVP_MD_CTX_free(), respectively.
EVP_MD_CTX_ctrl()
performs digest-specific control actions on the context
ctx.
EVP_DigestInit_ex()
sets up the digest context ctx to use a digest
type from ENGINE
impl. The type will typically be
supplied by a function such as
EVP_sha1().
If impl is NULL, then the
default implementation of digest type is used.
EVP_DigestUpdate()
hashes cnt bytes of data at d
into the digest context ctx. This function can be
called several times on the same ctx to hash
additional data.
EVP_DigestFinal_ex()
retrieves the digest value from ctx and places it in
md. If the s parameter is not
NULL, then the number of bytes of data written (i.e.
the length of the digest) will be written to the integer at
s; at most EVP_MAX_MD_SIZE
bytes will be written. After calling
EVP_DigestFinal_ex(), no additional calls to
EVP_DigestUpdate() can be made, but
EVP_DigestInit_ex() can be called to initialize a
new digest operation.
EVP_Digest()
is a simple wrapper function to hash cnt bytes of data
at d using the digest type from
ENGINE impl in a one-shot
operation and place the digest value into md, and,
unless s is NULL, the length
of the digest in bytes into *s. This wrapper uses a
temporary digest context and passes its arguments to
EVP_DigestInit_ex(),
EVP_DigestUpdate(), and
EVP_DigestFinal_ex() internally.
EVP_MD_CTX_copy_ex()
can be used to copy the message digest state from in
to out. This is useful if large amounts of data are to
be hashed which only differ in the last few bytes.
EVP_DigestInit()
is a deprecated function behaving like
EVP_DigestInit_ex() except that it always uses the
default digest implementation and that it requires
EVP_MD_CTX_reset() before it can be used on a
context that was already used.
EVP_DigestFinal()
is a deprecated function behaving like
EVP_DigestFinal_ex() except that the digest context
ctx is automatically cleaned up after use by calling
EVP_MD_CTX_reset() internally.
EVP_MD_CTX_copy()
is a deprecated function behaving like
EVP_MD_CTX_copy_ex() except that it requires
EVP_MD_CTX_reset() before a context that was already
used can be passed as out.
EVP_MD_size()
and EVP_MD_CTX_size() return the size of the message
digest when passed an EVP_MD or an
EVP_MD_CTX structure, i.e. the size of the hash.
EVP_MD_block_size()
and
EVP_MD_CTX_block_size()
return the block size of the message digest when passed an
EVP_MD or an EVP_MD_CTX
structure.
EVP_MD_type()
and
EVP_MD_CTX_type()
return the NID of the OBJECT IDENTIFIER representing the given message
digest when passed an EVP_MD structure. For example
EVP_MD_type(EVP_sha1())
returns NID_sha1. This function is normally used
when setting ASN.1 OIDs.
EVP_MD_pkey_type()
returns the NID of the public key signing algorithm associated with this
digest. For example
EVP_sha1()
is associated with RSA so this will return
NID_sha1WithRSAEncryption. Since digests and
signature algorithms are no longer linked, this function is only retained
for compatibility reasons.
EVP_md5(),
EVP_sha1(),
EVP_sha224(),
EVP_sha256(),
EVP_sha384(),
EVP_sha512(),
and
EVP_ripemd160()
return EVP_MD structures for the MD5, SHA1, SHA224,
SHA256, SHA384, SHA512 and RIPEMD160 digest algorithms respectively.
EVP_md5_sha1()
returns an EVP_MD structure that provides concatenated
MD5 and SHA1 message digests.
EVP_md_null()
is a "null" message digest that does nothing: i.e. the hash it
returns is of zero length.
EVP_get_digestbyname(),
EVP_get_digestbynid(),
and
EVP_get_digestbyobj()
return an EVP_MD structure when passed a digest name,
a digest NID, or an ASN1_OBJECT structure respectively.
EVP_MD_CTX_size(),
EVP_MD_CTX_block_size(),
EVP_MD_CTX_type(),
EVP_get_digestbynid(), and
EVP_get_digestbyobj() are implemented as macros.
The EVP interface to message digests should almost always be used in preference to the low level interfaces. This is because the code then becomes transparent to the digest used and much more flexible.
New applications should use the SHA2 digest algorithms such as SHA256. The other digest algorithms are still in common use.
For most applications the
impl parameter to
EVP_DigestInit_ex()
will be set to NULL to use the default digest implementation.
The functions
EVP_DigestInit(),
EVP_DigestFinal(), and
EVP_MD_CTX_copy() are obsolete but are retained to
maintain compatibility with existing code. New applications should use
EVP_DigestInit_ex(),
EVP_DigestFinal_ex(), and
EVP_MD_CTX_copy_ex() 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.
If digest contexts are not cleaned up after use, memory leaks will occur.
RETURN VALUES
EVP_MD_CTX_new() and
EVP_MD_CTX_create() return the new
EVP_MD_CTX object or NULL for
failure.
EVP_MD_CTX_reset() and
EVP_MD_CTX_cleanup() always return 1.
EVP_MD_CTX_ctrl(),
EVP_DigestInit_ex(),
EVP_DigestUpdate(),
EVP_DigestFinal_ex(),
EVP_Digest(),
EVP_MD_CTX_copy_ex(),
EVP_DigestInit(),
EVP_DigestFinal(), and
EVP_MD_CTX_copy() return 1 for success or 0 for
failure.
EVP_MD_type(),
EVP_MD_pkey_type(), and
EVP_MD_CTX_type() return the NID of the
corresponding OBJECT IDENTIFIER or NID_undef if none
exists.
EVP_MD_size(),
EVP_MD_block_size(),
EVP_MD_CTX_size(), and
EVP_MD_CTX_block_size() return the digest or block
size in bytes.
EVP_MD_CTX_md() returns the
EVP_MD object used by ctx, or
NULL if ctx is
NULL.
EVP_md_null(),
EVP_md5(), EVP_md5_sha1(),
EVP_sha1(), and
EVP_ripemd160() return pointers to the corresponding
EVP_MD structures.
EVP_get_digestbyname(),
EVP_get_digestbynid(), and
EVP_get_digestbyobj() return either an
EVP_MD structure or NULL if an
error occurs.
EXAMPLES
This example digests the data "Test Message\n" and "Hello World\n", using the digest name passed on the command line.
#include <stdio.h>
#include <openssl/evp.h>
int
main(int argc, char *argv[])
{
EVP_MD_CTX *mdctx;
const EVP_MD *md;
const char mess1[] = "Test Message\n";
const char mess2[] = "Hello World\n";
unsigned char md_value[EVP_MAX_MD_SIZE];
int md_len, i;
if (argc <= 1) {
printf("Usage: mdtest digestname\n");
exit(1);
}
md = EVP_get_digestbyname(argv[1]);
if (md == NULL) {
printf("Unknown message digest %s\n", argv[1]);
exit(1);
}
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_free(mdctx);
printf("Digest is: ");
for(i = 0; i < md_len; i++)
printf("%02x", md_value[i]);
printf("\n");
return 0;
}
SEE ALSO
BIO_f_md(3), CMAC_Init(3), evp(3), EVP_BytesToKey(3), EVP_DigestSignInit(3), EVP_DigestVerifyInit(3), EVP_PKEY_CTX_set_signature_md(3), EVP_PKEY_meth_set_signctx(3), EVP_SignInit(3), EVP_sm3(3), EVP_VerifyInit(3), EVP_whirlpool(3), HMAC(3), OCSP_basic_sign(3), OCSP_request_sign(3), PKCS5_PBKDF2_HMAC(3), PKCS7_sign_add_signer(3), X509_ALGOR_set_md(3), X509_digest(3), X509_sign(3)
HISTORY
EVP_DigestInit(),
EVP_DigestUpdate(),
EVP_DigestFinal(),
EVP_MAX_MD_SIZE, EVP_md5(),
and EVP_sha1() first appeared in SSLeay 0.5.1.
EVP_MD_size() first appeared in SSLeay 0.6.6.
EVP_MD_CTX_size(),
EVP_MD_CTX_type(),
EVP_md_null(), and
EVP_get_digestbyname() first appeared in SSLeay
0.8.0. EVP_MD_type(),
EVP_MD_pkey_type(),
EVP_get_digestbynid(), and
EVP_get_digestbyobj() first appeared in SSLeay
0.8.1. EVP_MD_block_size(),
EVP_MD_CTX_size(),
EVP_MD_CTX_block_size(),
EVP_rc4_40(),
EVP_rc2_40_cbc(), and
EVP_ripemd160() first appeared in SSLeay 0.9.0. All
these functions have been available since OpenBSD
2.4.
EVP_MD_CTX_copy() first appeared in
OpenSSL 0.9.2b and has been available since OpenBSD
2.6.
EVP_MD_CTX_md() first appeared in OpenSSL
0.9.5 and has been available since OpenBSD 2.7.
EVP_MD_CTX_init(),
EVP_MD_CTX_create(),
EVP_MD_CTX_cleanup(),
EVP_MD_CTX_destroy(),
EVP_DigestInit_ex(),
EVP_DigestFinal_ex(),
EVP_Digest(), and
EVP_MD_CTX_copy_ex() first appeared in OpenSSL 0.9.7
and have been available since OpenBSD 3.2.
EVP_sha224(),
EVP_sha256(), EVP_sha384(),
and EVP_sha512() first appeared in OpenSSL 0.9.7h
and 0.9.8a and have been available since OpenBSD
4.0.
EVP_MD_CTX_ctrl() first appeared in
OpenSSL 1.1.0 and has been available since OpenBSD
5.7.
EVP_MD_CTX_new(),
EVP_MD_CTX_reset(),
EVP_MD_CTX_free(), and
EVP_md5_sha1() first appeared in OpenSSL 1.1.0 and
have been available since OpenBSD 6.3.
The link between digests and signing algorithms was fixed in
OpenSSL 1.0 and later, so now EVP_sha1() can be used
with RSA and DSA.