Difference between revisions of "EVP Message Digests"

From OpenSSLWiki
Jump to navigationJump to search
(Clarified wording)
m (Add info on EVP_MD_CTX_create and EVP_MD_CTX_destroy from OpenSSL 1.0.2.)
 
(10 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
{{DocInclude
 +
|Name=Message Digests
 +
|Url=http://wiki.openssl.org/index.php/Manual:Evp(3)
 +
|Include=evp.h}}
 +
 
A Message Digest or Hash Function takes any arbitrary message (with any content or length) as an input and provides a fixed size hash value as a result. Specifically the function exhibits the following properties:
 
A Message Digest or Hash Function takes any arbitrary message (with any content or length) as an input and provides a fixed size hash value as a result. Specifically the function exhibits the following properties:
 
* It is simple to create a hash value for any given message
 
* It is simple to create a hash value for any given message
Line 5: Line 10:
 
* It is infeasible to find two messages that result in the same hash
 
* It is infeasible to find two messages that result in the same hash
  
The OpenSSL library supports a wide number of different hash functions including the popular SHA-2 set of hash functions (i.e. SHA-224, SHA-256, SHA-384 and SHA-512).
+
The OpenSSL library supports a wide number of different hash functions including the popular [[:Category:SHA-2]] set of hash functions (i.e. [[SHA-224]], [[SHA-256]], [[SHA-384]] and [[SHA-512]]).
  
 
==An Example use of a Hash Function==
 
==An Example use of a Hash Function==
Line 19: Line 24:
  
 
<pre>
 
<pre>
void digest_message(unsigned char *message, unsigned char **digest, unsigned int *digest_len)
+
void digest_message(const unsigned char *message, size_t message_len, unsigned char **digest, unsigned int *digest_len)
 
{
 
{
 
EVP_MD_CTX *mdctx;
 
EVP_MD_CTX *mdctx;
  
if((mdctx = EVP_MD_CTX_create()) == NULL)
+
if((mdctx = EVP_MD_CTX_new()) == NULL)
 
handleErrors();
 
handleErrors();
  
Line 29: Line 34:
 
handleErrors();
 
handleErrors();
  
if(1 != EVP_DigestUpdate(mdctx, message, strlen(message)))
+
if(1 != EVP_DigestUpdate(mdctx, message, message_len))
 
handleErrors();
 
handleErrors();
  
Line 38: Line 43:
 
handleErrors();
 
handleErrors();
  
EVP_MD_CTX_destroy(mdctx);
+
EVP_MD_CTX_free(mdctx);
 
}
 
}
 
</pre>
 
</pre>
 +
 +
If you need to support both OpenSSL 1.0.x and OpenSSL 1.1.x, then use a <tt>define</tt> for <tt>EVP_MD_CTX_new</tt> and <tt>EVP_MD_CTX_free</tt> as shown below.
 +
 +
<pre>#if OPENSSL_VERSION_NUMBER < 0x10100000L
 +
#  define EVP_MD_CTX_new  EVP_MD_CTX_create
 +
#  define EVP_MD_CTX_free  EVP_MD_CTX_destroy
 +
#endif
 +
</pre>
 +
 +
Refer to the OpenSSL manual page for further details [[Manual:EVP_DigestInit(3)]]
  
 
==See also==
 
==See also==
 
* [[EVP]]
 
* [[EVP]]
 
* [[Libcrypto API]]
 
* [[Libcrypto API]]
 +
* [[EVP Symmetric Encryption and Decryption]]
 +
* [[EVP Authenticated Encryption and Decryption]]
 +
* [[EVP Asymmetric Encryption and Decryption of an Envelope]]
 +
* [[EVP Key Agreement]]
 +
* [[EVP Key and Parameter Generation]]
 +
 +
[[Category:Crypto API]]
 +
[[Category:C level]]
 +
[[Category:Examples]]

Latest revision as of 01:51, 12 January 2022

Message Digests
Documentation
#include <openssl/evp.h>

A Message Digest or Hash Function takes any arbitrary message (with any content or length) as an input and provides a fixed size hash value as a result. Specifically the function exhibits the following properties:

  • It is simple to create a hash value for any given message
  • It is computationally infeasible to calculate a message from any given hash (i.e. the function is one-way)
  • It is infeasible to modify a message without also modifying the hash value
  • It is infeasible to find two messages that result in the same hash

The OpenSSL library supports a wide number of different hash functions including the popular Category:SHA-2 set of hash functions (i.e. SHA-224, SHA-256, SHA-384 and SHA-512).

An Example use of a Hash Function[edit]

Using an OpenSSL message digest/hash function, consists of the following steps:

  • Create a Message Digest context
  • Initialise the context by identifying the algorithm to be used (built-in algorithms are defined in evp.h)
  • Provide the message whose digest needs to be calculated. Messages can be divided into sections and provided over a number of calls to the library if necessary
  • Caclulate the digest
  • Clean up the context if no longer required

Message digest algorithms are identified using an EVP_MD object. These are built-in to the library and obtained through appropriate library calls (e.g. such as EVP_sha256() or EVP_sha512()).

void digest_message(const unsigned char *message, size_t message_len, unsigned char **digest, unsigned int *digest_len)
{
	EVP_MD_CTX *mdctx;

	if((mdctx = EVP_MD_CTX_new()) == NULL)
		handleErrors();

	if(1 != EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL))
		handleErrors();

	if(1 != EVP_DigestUpdate(mdctx, message, message_len))
		handleErrors();

	if((*digest = (unsigned char *)OPENSSL_malloc(EVP_MD_size(EVP_sha256()))) == NULL)
		handleErrors();

	if(1 != EVP_DigestFinal_ex(mdctx, *digest, digest_len))
		handleErrors();

	EVP_MD_CTX_free(mdctx);
}

If you need to support both OpenSSL 1.0.x and OpenSSL 1.1.x, then use a define for EVP_MD_CTX_new and EVP_MD_CTX_free as shown below.

#if OPENSSL_VERSION_NUMBER < 0x10100000L
#  define EVP_MD_CTX_new   EVP_MD_CTX_create
#  define EVP_MD_CTX_free  EVP_MD_CTX_destroy
#endif

Refer to the OpenSSL manual page for further details Manual:EVP_DigestInit(3)

See also[edit]