159191Skris=pod 259191Skris 359191Skris=head1 NAME 459191Skris 5109998SmarkmEVP_MD_CTX_init, EVP_MD_CTX_create, EVP_DigestInit_ex, EVP_DigestUpdate, 6109998SmarkmEVP_DigestFinal_ex, EVP_MD_CTX_cleanup, EVP_MD_CTX_destroy, EVP_MAX_MD_SIZE, 7127128SnectarEVP_MD_CTX_copy_ex, EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, 8109998SmarkmEVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type, 9238405SjkimEVP_md_null, EVP_md2, EVP_md5, EVP_sha, EVP_sha1, EVP_sha224, EVP_sha256, 10238405SjkimEVP_sha384, EVP_sha512, EVP_dss, EVP_dss1, EVP_mdc2, 1168651SkrisEVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj - 1268651SkrisEVP digest routines 1359191Skris 1459191Skris=head1 SYNOPSIS 1559191Skris 1659191Skris #include <openssl/evp.h> 1759191Skris 18109998Smarkm void EVP_MD_CTX_init(EVP_MD_CTX *ctx); 19109998Smarkm EVP_MD_CTX *EVP_MD_CTX_create(void); 20109998Smarkm 21109998Smarkm int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); 22160814Ssimon int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); 23109998Smarkm int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, 2459191Skris unsigned int *s); 2559191Skris 26109998Smarkm int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx); 27109998Smarkm void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx); 2859191Skris 29273399Sdelphij int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in); 30109998Smarkm 31109998Smarkm int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); 32109998Smarkm int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, 33109998Smarkm unsigned int *s); 34109998Smarkm 35273399Sdelphij int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); 3659191Skris 37238405Sjkim #define EVP_MAX_MD_SIZE 64 /* SHA512 */ 38109998Smarkm 39238405Sjkim int EVP_MD_type(const EVP_MD *md); 40238405Sjkim int EVP_MD_pkey_type(const EVP_MD *md); 41238405Sjkim int EVP_MD_size(const EVP_MD *md); 42238405Sjkim int EVP_MD_block_size(const EVP_MD *md); 43109998Smarkm 44238405Sjkim const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx); 45238405Sjkim #define EVP_MD_CTX_size(e) EVP_MD_size(EVP_MD_CTX_md(e)) 4659191Skris #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest) 4759191Skris #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest) 4859191Skris 49109998Smarkm const EVP_MD *EVP_md_null(void); 50109998Smarkm const EVP_MD *EVP_md2(void); 51109998Smarkm const EVP_MD *EVP_md5(void); 52109998Smarkm const EVP_MD *EVP_sha(void); 53109998Smarkm const EVP_MD *EVP_sha1(void); 54109998Smarkm const EVP_MD *EVP_dss(void); 55109998Smarkm const EVP_MD *EVP_dss1(void); 56109998Smarkm const EVP_MD *EVP_mdc2(void); 57109998Smarkm const EVP_MD *EVP_ripemd160(void); 5859191Skris 59238405Sjkim const EVP_MD *EVP_sha224(void); 60238405Sjkim const EVP_MD *EVP_sha256(void); 61238405Sjkim const EVP_MD *EVP_sha384(void); 62238405Sjkim const EVP_MD *EVP_sha512(void); 63238405Sjkim 6459191Skris const EVP_MD *EVP_get_digestbyname(const char *name); 6559191Skris #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a)) 6659191Skris #define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a)) 6759191Skris 6859191Skris=head1 DESCRIPTION 6959191Skris 7059191SkrisThe EVP digest routines are a high level interface to message digests. 7159191Skris 72205128SsimonEVP_MD_CTX_init() initializes digest context B<ctx>. 7359191Skris 74205128SsimonEVP_MD_CTX_create() allocates, initializes and returns a digest context. 75109998Smarkm 76109998SmarkmEVP_DigestInit_ex() sets up digest context B<ctx> to use a digest 77109998SmarkmB<type> from ENGINE B<impl>. B<ctx> must be initialized before calling this 78109998Smarkmfunction. B<type> will typically be supplied by a functionsuch as EVP_sha1(). 79109998SmarkmIf B<impl> is NULL then the default implementation of digest B<type> is used. 80109998Smarkm 8159191SkrisEVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the 8268651Skrisdigest context B<ctx>. This function can be called several times on the 8359191Skrissame B<ctx> to hash additional data. 8459191Skris 85109998SmarkmEVP_DigestFinal_ex() retrieves the digest value from B<ctx> and places 8659191Skrisit in B<md>. If the B<s> parameter is not NULL then the number of 8759191Skrisbytes of data written (i.e. the length of the digest) will be written 8859191Skristo the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written. 89109998SmarkmAfter calling EVP_DigestFinal_ex() no additional calls to EVP_DigestUpdate() 90109998Smarkmcan be made, but EVP_DigestInit_ex() can be called to initialize a new 9159191Skrisdigest operation. 9259191Skris 93109998SmarkmEVP_MD_CTX_cleanup() cleans up digest context B<ctx>, it should be called 94109998Smarkmafter a digest context is no longer needed. 95109998Smarkm 96109998SmarkmEVP_MD_CTX_destroy() cleans up digest context B<ctx> and frees up the 97109998Smarkmspace allocated to it, it should be called only on a context created 98109998Smarkmusing EVP_MD_CTX_create(). 99109998Smarkm 100109998SmarkmEVP_MD_CTX_copy_ex() can be used to copy the message digest state from 10159191SkrisB<in> to B<out>. This is useful if large amounts of data are to be 102109998Smarkmhashed which only differ in the last few bytes. B<out> must be initialized 103109998Smarkmbefore calling this function. 10459191Skris 105109998SmarkmEVP_DigestInit() behaves in the same way as EVP_DigestInit_ex() except 106109998Smarkmthe passed context B<ctx> does not have to be initialized, and it always 107109998Smarkmuses the default digest implementation. 108109998Smarkm 109109998SmarkmEVP_DigestFinal() is similar to EVP_DigestFinal_ex() except the digest 110205128Ssimoncontext B<ctx> is automatically cleaned up. 111109998Smarkm 112109998SmarkmEVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination 113109998SmarkmB<out> does not have to be initialized. 114109998Smarkm 11559191SkrisEVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest 11659191Skriswhen passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the 11759191Skrishash. 11859191Skris 11959191SkrisEVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the 12059191Skrismessage digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure. 12159191Skris 12259191SkrisEVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER 12359191Skrisrepresenting the given message digest when passed an B<EVP_MD> structure. 12459191SkrisFor example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is 12559191Skrisnormally used when setting ASN1 OIDs. 12659191Skris 12759191SkrisEVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed 12859191SkrisB<EVP_MD_CTX>. 12959191Skris 13059191SkrisEVP_MD_pkey_type() returns the NID of the public key signing algorithm associated 13159191Skriswith this digest. For example EVP_sha1() is associated with RSA so this will 132238405Sjkimreturn B<NID_sha1WithRSAEncryption>. Since digests and signature algorithms 133238405Sjkimare no longer linked this function is only retained for compatibility 134238405Sjkimreasons. 13559191Skris 136238405SjkimEVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_sha224(), EVP_sha256(), 137238405SjkimEVP_sha384(), EVP_sha512(), EVP_mdc2() and EVP_ripemd160() return B<EVP_MD> 138238405Sjkimstructures for the MD2, MD5, SHA, SHA1, SHA224, SHA256, SHA384, SHA512, MDC2 139273399Sdelphijand RIPEMD160 digest algorithms respectively. 14059191Skris 14159191SkrisEVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest 142273399Sdelphijalgorithms but using DSS (DSA) for the signature algorithm. Note: there is 143238405Sjkimno need to use these pseudo-digests in OpenSSL 1.0.0 and later, they are 144238405Sjkimhowever retained for compatibility. 14559191Skris 14659191SkrisEVP_md_null() is a "null" message digest that does nothing: i.e. the hash it 14759191Skrisreturns is of zero length. 14859191Skris 14959191SkrisEVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() 15059191Skrisreturn an B<EVP_MD> structure when passed a digest name, a digest NID or 15168651Skrisan ASN1_OBJECT structure respectively. The digest table must be initialized 15259191Skrisusing, for example, OpenSSL_add_all_digests() for these functions to work. 15359191Skris 15459191Skris=head1 RETURN VALUES 15559191Skris 156109998SmarkmEVP_DigestInit_ex(), EVP_DigestUpdate() and EVP_DigestFinal_ex() return 1 for 157109998Smarkmsuccess and 0 for failure. 15859191Skris 159109998SmarkmEVP_MD_CTX_copy_ex() returns 1 if successful or 0 for failure. 16059191Skris 16159191SkrisEVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the 16259191Skriscorresponding OBJECT IDENTIFIER or NID_undef if none exists. 16359191Skris 164269686SjkimEVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size() and 165269686SjkimEVP_MD_CTX_block_size() return the digest or block size in bytes. 16659191Skris 16759191SkrisEVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(), 16859191SkrisEVP_dss1(), EVP_mdc2() and EVP_ripemd160() return pointers to the 16959191Skriscorresponding EVP_MD structures. 17059191Skris 17159191SkrisEVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() 17259191Skrisreturn either an B<EVP_MD> structure or NULL if an error occurs. 17359191Skris 17459191Skris=head1 NOTES 17559191Skris 17659191SkrisThe B<EVP> interface to message digests should almost always be used in 17759191Skrispreference to the low level interfaces. This is because the code then becomes 17859191Skristransparent to the digest used and much more flexible. 17959191Skris 180273399SdelphijNew applications should use the SHA2 digest algorithms such as SHA256. 181238405SjkimThe other digest algorithms are still in common use. 18259191Skris 183109998SmarkmFor most applications the B<impl> parameter to EVP_DigestInit_ex() will be 184109998Smarkmset to NULL to use the default digest implementation. 185109998Smarkm 186273399SdelphijThe functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are 187109998Smarkmobsolete but are retained to maintain compatibility with existing code. New 188273399Sdelphijapplications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and 189109998SmarkmEVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context 190109998Smarkminstead of initializing and cleaning it up on each call and allow non default 191109998Smarkmimplementations of digests to be specified. 192109998Smarkm 193109998SmarkmIn OpenSSL 0.9.7 and later if digest contexts are not cleaned up after use 194273399Sdelphijmemory leaks will occur. 195109998Smarkm 196238405SjkimStack allocation of EVP_MD_CTX structures is common, for example: 197238405Sjkim 198238405Sjkim EVP_MD_CTX mctx; 199238405Sjkim EVP_MD_CTX_init(&mctx); 200238405Sjkim 201238405SjkimThis will cause binary compatibility issues if the size of EVP_MD_CTX 202238405Sjkimstructure changes (this will only happen with a major release of OpenSSL). 203238405SjkimApplications wishing to avoid this should use EVP_MD_CTX_create() instead: 204238405Sjkim 205238405Sjkim EVP_MD_CTX *mctx; 206238405Sjkim mctx = EVP_MD_CTX_create(); 207238405Sjkim 208238405Sjkim 20959191Skris=head1 EXAMPLE 21059191Skris 21159191SkrisThis example digests the data "Test Message\n" and "Hello World\n", using the 21259191Skrisdigest name passed on the command line. 21359191Skris 21459191Skris #include <stdio.h> 21559191Skris #include <openssl/evp.h> 21659191Skris 21759191Skris main(int argc, char *argv[]) 21859191Skris { 219238405Sjkim EVP_MD_CTX *mdctx; 22059191Skris const EVP_MD *md; 22159191Skris char mess1[] = "Test Message\n"; 22259191Skris char mess2[] = "Hello World\n"; 22359191Skris unsigned char md_value[EVP_MAX_MD_SIZE]; 22459191Skris int md_len, i; 22559191Skris 22659191Skris OpenSSL_add_all_digests(); 22759191Skris 22859191Skris if(!argv[1]) { 22959191Skris printf("Usage: mdtest digestname\n"); 23059191Skris exit(1); 23159191Skris } 23259191Skris 23359191Skris md = EVP_get_digestbyname(argv[1]); 23459191Skris 23559191Skris if(!md) { 23659191Skris printf("Unknown message digest %s\n", argv[1]); 23759191Skris exit(1); 23859191Skris } 23959191Skris 240238405Sjkim mdctx = EVP_MD_CTX_create(); 241238405Sjkim EVP_DigestInit_ex(mdctx, md, NULL); 242238405Sjkim EVP_DigestUpdate(mdctx, mess1, strlen(mess1)); 243238405Sjkim EVP_DigestUpdate(mdctx, mess2, strlen(mess2)); 244238405Sjkim EVP_DigestFinal_ex(mdctx, md_value, &md_len); 245238405Sjkim EVP_MD_CTX_destroy(mdctx); 24659191Skris 24759191Skris printf("Digest is: "); 248273399Sdelphij for(i = 0; i < md_len; i++) 249273399Sdelphij printf("%02x", md_value[i]); 25059191Skris printf("\n"); 251273399Sdelphij 252273399Sdelphij /* Call this once before exit. */ 253273399Sdelphij EVP_cleanup(); 254273399Sdelphij exit(0); 25559191Skris } 25659191Skris 25759191Skris=head1 SEE ALSO 25859191Skris 259273399SdelphijL<dgst(1)|dgst(1)>, 260273399SdelphijL<evp(3)|evp(3)> 26159191Skris 26259191Skris=head1 HISTORY 26359191Skris 26459191SkrisEVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() are 26559191Skrisavailable in all versions of SSLeay and OpenSSL. 26659191Skris 267109998SmarkmEVP_MD_CTX_init(), EVP_MD_CTX_create(), EVP_MD_CTX_copy_ex(), 268109998SmarkmEVP_MD_CTX_cleanup(), EVP_MD_CTX_destroy(), EVP_DigestInit_ex() 269109998Smarkmand EVP_DigestFinal_ex() were added in OpenSSL 0.9.7. 270109998Smarkm 271109998SmarkmEVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), 272109998SmarkmEVP_dss(), EVP_dss1(), EVP_mdc2() and EVP_ripemd160() were 273109998Smarkmchanged to return truely const EVP_MD * in OpenSSL 0.9.7. 274109998Smarkm 275238405SjkimThe link between digests and signing algorithms was fixed in OpenSSL 1.0 and 276273399Sdelphijlater, so now EVP_sha1() can be used with RSA and DSA; there is no need to 277238405Sjkimuse EVP_dss1() any more. 278238405Sjkim 279238405SjkimOpenSSL 1.0 and later does not include the MD2 digest algorithm in the 280238405Sjkimdefault configuration due to its security weaknesses. 281238405Sjkim 28259191Skris=cut 283