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_DigestInit_ex
,
EVP_DigestUpdate
,
EVP_DigestFinal_ex
,
EVP_Digest
,
EVP_MD_CTX_copy_ex
,
EVP_DigestInit
,
EVP_DigestFinal
,
EVP_MD_CTX_copy
,
EVP_MD_CTX_md
, EVP_md_null
,
EVP_sha224
, EVP_sha256
,
EVP_sha384
, EVP_sha512
,
EVP_sha512_224
,
EVP_sha512_256
,
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);
int
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_DigestInit_ex
(EVP_MD_CTX
*ctx, const EVP_MD *type, ENGINE
*engine);
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 *engine);
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);
const EVP_MD *
EVP_MD_CTX_md
(const EVP_MD_CTX
*ctx);
const EVP_MD *
EVP_md_null
(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_sha512_224
(void);
const EVP_MD *
EVP_sha512_256
(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_DigestInit_ex
()
sets up the digest context ctx to use a digest
type. The type will typically be
supplied by a function such as
EVP_sha512
().
The ENGINE *engine argument is always ignored and
passing NULL
is recommended.
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 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. The
ENGINE *engine argument is always ignored and passing
NULL
is recommended.
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 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_sha224
(),
EVP_sha256
(),
EVP_sha384
(),
EVP_sha512
(), and
EVP_ripemd160
()
return EVP_MD structures for the SHA224, SHA256,
SHA384, SHA512 and RIPEMD160 digest algorithms respectively.
EVP_sha512_224
()
and
EVP_sha512_256
()
return an EVP_MD structure that provides the truncated
SHA512 variants SHA512/224 and SHA512/256, respectively.
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_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.
The ENGINE *engine argument is always
ignored and passing NULL
is recommended.
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.
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
(),
EVP_MD_CTX_init
(), and
EVP_MD_CTX_cleanup
() always return 1.
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_CTX_md
() returns the
EVP_MD object used by ctx, or
NULL
if ctx is
NULL
or does not have any message digest algorithm
assigned yet.
EVP_md_null
(),
EVP_sha224
(), EVP_sha256
(),
EVP_sha384
(), EVP_sha512
(),
EVP_sha512_224
(),
EVP_sha512_256
(), and
EVP_ripemd160
() return pointers to constant static
objects owned by the library.
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 <string.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]; unsigned 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_MD_CTX_ctrl(3), EVP_MD_nid(3), EVP_PKEY_CTX_set_signature_md(3), EVP_sha1(3), EVP_sha3_224(3), EVP_SignInit(3), EVP_sm3(3), EVP_VerifyInit(3), HMAC(3), OCSP_basic_sign(3), OCSP_request_sign(3), PKCS5_PBKDF2_HMAC(3), PKCS7_sign_add_signer(3), X509_ALGOR_set0(3), X509_digest(3), X509_sign(3)
HISTORY
EVP_DigestInit
(),
EVP_DigestUpdate
(), and
EVP_DigestFinal
() first appeared in SSLeay 0.5.1.
EVP_md_null
() and
EVP_get_digestbyname
() first appeared in SSLeay
0.8.0. EVP_get_digestbynid
() and
EVP_get_digestbyobj
() first appeared in SSLeay
0.8.1. 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_new
(),
EVP_MD_CTX_reset
(), and
EVP_MD_CTX_free
() first appeared in OpenSSL 1.1.0
and have been available since OpenBSD 6.3.
EVP_sha512_224
() and
EVP_sha512_256
() first appeared in OpenSSL 1.1.1 and
have been available since OpenBSD 7.4.