EVP_DigestInit.pod revision 68651
159191Skris=pod 259191Skris 359191Skris=head1 NAME 459191Skris 568651SkrisEVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal, EVP_MAX_MD_SIZE, 668651SkrisEVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, 768651SkrisEVP_MD_CTX_md, EVP_MD_CTX_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type, 868651SkrisEVP_md_null, EVP_md2, EVP_md5, EVP_sha, EVP_sha1, EVP_dss, EVP_dss1, EVP_mdc2, 968651SkrisEVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj - 1068651SkrisEVP digest routines 1159191Skris 1259191Skris=head1 SYNOPSIS 1359191Skris 1459191Skris #include <openssl/evp.h> 1559191Skris 1659191Skris void EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); 1759191Skris void EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); 1859191Skris void EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, 1959191Skris unsigned int *s); 2059191Skris 2159191Skris #define EVP_MAX_MD_SIZE (16+20) /* The SSLv3 md5+sha1 type */ 2259191Skris 2359191Skris int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); 2459191Skris 2559191Skris #define EVP_MD_type(e) ((e)->type) 2659191Skris #define EVP_MD_pkey_type(e) ((e)->pkey_type) 2759191Skris #define EVP_MD_size(e) ((e)->md_size) 2859191Skris #define EVP_MD_block_size(e) ((e)->block_size) 2959191Skris 3059191Skris #define EVP_MD_CTX_md(e) (e)->digest) 3159191Skris #define EVP_MD_CTX_size(e) EVP_MD_size((e)->digest) 3259191Skris #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest) 3359191Skris #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest) 3459191Skris 3559191Skris EVP_MD *EVP_md_null(void); 3659191Skris EVP_MD *EVP_md2(void); 3759191Skris EVP_MD *EVP_md5(void); 3859191Skris EVP_MD *EVP_sha(void); 3959191Skris EVP_MD *EVP_sha1(void); 4059191Skris EVP_MD *EVP_dss(void); 4159191Skris EVP_MD *EVP_dss1(void); 4259191Skris EVP_MD *EVP_mdc2(void); 4359191Skris EVP_MD *EVP_ripemd160(void); 4459191Skris 4559191Skris const EVP_MD *EVP_get_digestbyname(const char *name); 4659191Skris #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a)) 4759191Skris #define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a)) 4859191Skris 4959191Skris=head1 DESCRIPTION 5059191Skris 5159191SkrisThe EVP digest routines are a high level interface to message digests. 5259191Skris 5368651SkrisEVP_DigestInit() initializes a digest context B<ctx> to use a digest 5459191SkrisB<type>: this will typically be supplied by a function such as 5559191SkrisEVP_sha1(). 5659191Skris 5759191SkrisEVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the 5868651Skrisdigest context B<ctx>. This function can be called several times on the 5959191Skrissame B<ctx> to hash additional data. 6059191Skris 6159191SkrisEVP_DigestFinal() retrieves the digest value from B<ctx> and places 6259191Skrisit in B<md>. If the B<s> parameter is not NULL then the number of 6359191Skrisbytes of data written (i.e. the length of the digest) will be written 6459191Skristo the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written. 6559191SkrisAfter calling EVP_DigestFinal() no additional calls to EVP_DigestUpdate() 6668651Skriscan be made, but EVP_DigestInit() can be called to initialize a new 6759191Skrisdigest operation. 6859191Skris 6959191SkrisEVP_MD_CTX_copy() can be used to copy the message digest state from 7059191SkrisB<in> to B<out>. This is useful if large amounts of data are to be 7159191Skrishashed which only differ in the last few bytes. 7259191Skris 7359191SkrisEVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest 7459191Skriswhen passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the 7559191Skrishash. 7659191Skris 7759191SkrisEVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the 7859191Skrismessage digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure. 7959191Skris 8059191SkrisEVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER 8159191Skrisrepresenting the given message digest when passed an B<EVP_MD> structure. 8259191SkrisFor example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is 8359191Skrisnormally used when setting ASN1 OIDs. 8459191Skris 8559191SkrisEVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed 8659191SkrisB<EVP_MD_CTX>. 8759191Skris 8859191SkrisEVP_MD_pkey_type() returns the NID of the public key signing algorithm associated 8959191Skriswith this digest. For example EVP_sha1() is associated with RSA so this will 9059191Skrisreturn B<NID_sha1WithRSAEncryption>. This "link" between digests and signature 9159191Skrisalgorithms may not be retained in future versions of OpenSSL. 9259191Skris 9359191SkrisEVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_mdc2() and EVP_ripemd160() 9459191Skrisreturn B<EVP_MD> structures for the MD2, MD5, SHA, SHA1, MDC2 and RIPEMD160 digest 9559191Skrisalgorithms respectively. The associated signature algorithm is RSA in each case. 9659191Skris 9759191SkrisEVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest 9859191Skrisalgorithms but using DSS (DSA) for the signature algorithm. 9959191Skris 10059191SkrisEVP_md_null() is a "null" message digest that does nothing: i.e. the hash it 10159191Skrisreturns is of zero length. 10259191Skris 10359191SkrisEVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() 10459191Skrisreturn an B<EVP_MD> structure when passed a digest name, a digest NID or 10568651Skrisan ASN1_OBJECT structure respectively. The digest table must be initialized 10659191Skrisusing, for example, OpenSSL_add_all_digests() for these functions to work. 10759191Skris 10859191Skris=head1 RETURN VALUES 10959191Skris 11059191SkrisEVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() do not return values. 11159191Skris 11259191SkrisEVP_MD_CTX_copy() returns 1 if successful or 0 for failure. 11359191Skris 11459191SkrisEVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the 11559191Skriscorresponding OBJECT IDENTIFIER or NID_undef if none exists. 11659191Skris 11759191SkrisEVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size(e), EVP_MD_size(), 11859191SkrisEVP_MD_CTX_block_size() and EVP_MD_block_size() return the digest or block 11959191Skrissize in bytes. 12059191Skris 12159191SkrisEVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(), 12259191SkrisEVP_dss1(), EVP_mdc2() and EVP_ripemd160() return pointers to the 12359191Skriscorresponding EVP_MD structures. 12459191Skris 12559191SkrisEVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() 12659191Skrisreturn either an B<EVP_MD> structure or NULL if an error occurs. 12759191Skris 12859191Skris=head1 NOTES 12959191Skris 13059191SkrisThe B<EVP> interface to message digests should almost always be used in 13159191Skrispreference to the low level interfaces. This is because the code then becomes 13259191Skristransparent to the digest used and much more flexible. 13359191Skris 13459191SkrisSHA1 is the digest of choice for new applications. The other digest algorithms 13559191Skrisare still in common use. 13659191Skris 13759191Skris=head1 EXAMPLE 13859191Skris 13959191SkrisThis example digests the data "Test Message\n" and "Hello World\n", using the 14059191Skrisdigest name passed on the command line. 14159191Skris 14259191Skris #include <stdio.h> 14359191Skris #include <openssl/evp.h> 14459191Skris 14559191Skris main(int argc, char *argv[]) 14659191Skris { 14759191Skris EVP_MD_CTX mdctx; 14859191Skris const EVP_MD *md; 14959191Skris char mess1[] = "Test Message\n"; 15059191Skris char mess2[] = "Hello World\n"; 15159191Skris unsigned char md_value[EVP_MAX_MD_SIZE]; 15259191Skris int md_len, i; 15359191Skris 15459191Skris OpenSSL_add_all_digests(); 15559191Skris 15659191Skris if(!argv[1]) { 15759191Skris printf("Usage: mdtest digestname\n"); 15859191Skris exit(1); 15959191Skris } 16059191Skris 16159191Skris md = EVP_get_digestbyname(argv[1]); 16259191Skris 16359191Skris if(!md) { 16459191Skris printf("Unknown message digest %s\n", argv[1]); 16559191Skris exit(1); 16659191Skris } 16759191Skris 16859191Skris EVP_DigestInit(&mdctx, md); 16959191Skris EVP_DigestUpdate(&mdctx, mess1, strlen(mess1)); 17059191Skris EVP_DigestUpdate(&mdctx, mess2, strlen(mess2)); 17159191Skris EVP_DigestFinal(&mdctx, md_value, &md_len); 17259191Skris 17359191Skris printf("Digest is: "); 17459191Skris for(i = 0; i < md_len; i++) printf("%02x", md_value[i]); 17559191Skris printf("\n"); 17659191Skris } 17759191Skris 17859191Skris=head1 BUGS 17959191Skris 18059191SkrisSeveral of the functions do not return values: maybe they should. Although the 18159191Skrisinternal digest operations will never fail some future hardware based operations 18259191Skrismight. 18359191Skris 18459191SkrisThe link between digests and signing algorithms results in a situation where 18559191SkrisEVP_sha1() must be used with RSA and EVP_dss1() must be used with DSS 18659191Skriseven though they are identical digests. 18759191Skris 18859191SkrisThe size of an B<EVP_MD_CTX> structure is determined at compile time: this results 18959191Skrisin code that must be recompiled if the size of B<EVP_MD_CTX> increases. 19059191Skris 19159191Skris=head1 SEE ALSO 19259191Skris 19359191SkrisL<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, 19459191SkrisL<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, 19559191SkrisL<sha(3)|sha(3)>, L<digest(1)|digest(1)> 19659191Skris 19759191Skris=head1 HISTORY 19859191Skris 19959191SkrisEVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() are 20059191Skrisavailable in all versions of SSLeay and OpenSSL. 20159191Skris 20259191Skris=cut 203