NAME
EVPMDCTXinit, EVPMDCTXcreate, EVPDigestInitex, EVPDigestUpdate, EVPDigestFinalex, EVPMDCTXcleanup, EVPMDCTXdestroy, EVPMAXMDSIZE, EVPMDCTXcopyex, EVPMDCTXcopy, EVPMDtype, EVPMDpkeytype, EVPMDsize, EVPMDblocksize, EVPMDCTXmd, EVPMDCTXsize, EVPMDCTXblocksize, EVPMDCTXtype, EVPmdnull, EVPmd2, EVPmd5, EVPsha, EVPsha1, EVPdss, EVPdss1, EVPmdc2, EVPripemd160,EVPgetdigestbyname, EVPgetdigestbynid, EVPgetdigestbyobj - EVP
digest routinesSYNOPSIS
#include
void EVPMDCTXinit(EVPMDCTX *ctx); EVPMDCTX *EVPMDCTXcreate(void); int EVPDigestInitex(EVPMDCTX *ctx, const EVPMD *type, ENGINE *impl); int EVPDigestUpdate(EVPMDCTX *ctx, const void *d, unsigned int cnt); int EVPDigestFinalex(EVPMDCTX *ctx, unsigned char *md, unsigned int *s); int EVPMDCTXcleanup(EVPMDCTX *ctx); void EVPMDCTXdestroy(EVPMDCTX *ctx); int EVPMDCTXcopyex(EVPMDCTX *out,const EVPMDCTX *in); int EVPDigestInit(EVPMDCTX *ctx, const EVPMD *type); int EVPDigestFinal(EVPMDCTX *ctx, unsigned char *md, unsigned int *s); int EVPMDCTXcopy(EVPMDCTX *out,EVPMDCTX *in);#define EVPMAXMDSIZE (16+20) /* The SSLv3 md5+sha1 type */
#define EVPMDtype(e) ((e)->type)
#define EVPMDpkeytype(e) ((e)->pkeytype)
#define EVPMDsize(e) ((e)->mdsize)
#define EVPMDblocksize(e) ((e)->blocksize)
#define EVPMDCTXmd(e) (e)->digest)
#define EVPMDCTXsize(e) EVPMDsize((e)->digest)
#define EVPMDCTXblocksize(e) EVPMDblocksize((e)->digest)
#define EVPMDCTXtype(e) EVPMDtype((e)->digest)
const EVPMD *EVPmdnull(void); const EVPMD *EVPmd2(void); const EVPMD *EVPmd5(void); const EVPMD *EVPsha(void); const EVPMD *EVPsha1(void); const EVPMD *EVPdss(void); const EVPMD *EVPdss1(void); const EVPMD *EVPmdc2(void); const EVPMD *EVPripemd160(void); const EVPMD *EVPgetdigestbyname(const char *name);#define EVPgetdigestbynid(a) EVPgetdigestbyname(OBJnid2sn(a))
#define EVPgetdigestbyobj(a) EVPgetdigestbynid(OBJobj2nid(a))
DESCRIPTION
The EVP digest routines are a high level interface to message digests. EVPMDCTXinit() initializes digest contet ccttxx. EVPMDCTXcreate() allocates, initializes and returns a digest contet. EVPDigestInitex() sets up digest context ccttxx to use a digest ttyyppee from ENGINE iimmppll. ccttxx must be initialized before calling this function. ttyyppee will typically be supplied by a functionsuch as EVPsha1(). If iimmppll is NULL then the default implementation of digest ttyyppee is used. EVPDigestUpdate() hashes ccnntt bytes of data at dd into the digest context ccttxx. This function can be called several times on the same ccttxx to hash additional data. EVPDigestFinalex() retrieves the digest value from ccttxx and places it in mmdd. If the ss 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 ss, at most EEVVPPMMAAXXMMDDSSIIZZEE bytes will be written. After calling EVPDigestFinalex() no additional calls to EVPDigestUpdate() can be made, but EVPDigestInitex() can be called to initialize a new digest operation. EVPMDCTXcleanup() cleans up digest context ccttxx, it should be called after a digest context is no longer needed. EVPMDCTXdestroy() cleans up digest context ccttxx and frees up the space allocated to it, it should be called only on a context created using EVPMDCTXcreate(). EVPMDCTXcopyex() can be used to copy the message digest state from iinn to oouutt. This is useful if large amounts of data are to be hashed which only differ in the last few bytes. oouutt must be initialized before calling this function. EVPDigestInit() behaves in the same way as EVPDigestInitex() except the passed context ccttxx does not have to be initialized, and it always uses the default digest implementation. EVPDigestFinal() is similar to EVPDigestFinalex() except the digest contet ccttxx is automatically cleaned up. EVPMDCTXcopy() is similar to EVPMDCTXcopyex() except the destination oouutt does not have to be initialized. EVPMDsize() and EVPMDCTXsize() return the size of the message digest when passed an EEVVPPMMDD or an EEVVPPMMDDCCTTXX structure, i.e. the size of the hash. EVPMDblocksize() and EVPMDCTXblocksize() return the block size of the message digest when passed an EEVVPPMMDD or an EEVVPPMMDDCCTTXX structure. EVPMDtype() and EVPMDCTXtype() return the NID of the OBJECT IDENTIFIER representing the given message digest when passed an EEVVPPMMDD structure. For example EVPMDtype(EVPsha1()) returns NNIIDDsshhaa11. This function is normally used when setting ASN1 OIDs. EVPMDCTXmd() returns the EEVVPPMMDD structure corresponding to the passed EEVVPPMMDDCCTTXX. EVPMDpkeytype() returns the NID of the public key signing algorithm associated with this digest. For example EVPsha1() is associated with RSA so this will return NNIIDDsshhaa11WWiitthhRRSSAAEEnnccrryyppttiioonn. This "link" between digests and signature algorithms may not be retained in future versions of OpenSSL. EVPmd2(), EVPmd5(), EVPsha(), EVPsha1(), EVPmdc2() and EVPripemd160() return EEVVPPMMDD structures for the MD2, MD5, SHA, SHA1, MDC2 and RIPEMD160 digest algorithms respectively. The associated signature algorithm is RSA in each case. EVPdss() and EVPdss1() return EEVVPPMMDD structures for SHA and SHA1 digest algorithms but using DSS (DSA) for the signature algorithm. EVPmdnull() is a "null" message digest that does nothing: i.e. the hash it returns is of zero length. EVPgetdigestbyname(), EVPgetdigestbynid() and EVPgetdigestbyobj() return an EEVVPPMMDD structure when passed a digest name, a digest NID or an ASN1OBJECT structure respectively. The digest table must be initialized using, for example, OpenSSLaddalldigests() for these functions to work.RETURN VALUES
EVPDigestInitex(), EVPDigestUpdate() and EVPDigestFinalex() return 1 for success and 0 for failure. EVPMDCTXcopyex() returns 1 if successful or 0 for failure. EVPMDtype(), EVPMDpkeytype() and EVPMDtype() return the NID of the corresponding OBJECT IDENTIFIER or NIDundef if none exists. EVPMDsize(), EVPMDblocksize(), EVPMDCTXsize(e), EVPMDsize(), EVPMDCTXblocksize() and EVPMDblocksize() return the digest or block size in bytes. EVPmdnull(), EVPmd2(), EVPmd5(), EVPsha(), EVPsha1(), EVPdss(), EVPdss1(), EVPmdc2() and EVPripemd160() return pointers to the corresponding EVPMD structures. EVPgetdigestbyname(), EVPgetdigestbynid() and EVPgetdigestbyobj() return either an EEVVPPMMDD structure or NULL if an error occurs. NNOOTTEESS The EEVVPP 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. SHA1 is the digest of choice for new applications. The other digest algorithms are still in common use. For most applications the iimmppll parameter to EVPDigestInitex() will be set to NULL to use the default digest implementation. The functions EVPDigestInit(), EVPDigestFinal() and EVPMDCTXcopy() are obsolete but are retained to maintain compatibility with existing code. New applications should use EVPDigestInitex(), EVPDigestFinalex() and EVPMDCTXcopyex() 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. In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after use memory leaks will occur. EEXXAAMMPPLLEE This example digests the data "Test Message\n" and "Hello World\n", using the digest name passed on the command line.#include
#include
main(int argc, char *argv[]) { EVPMDCTX mdctx; const EVPMD *md; char mess1[] = "Test Message\n"; char mess2[] = "Hello World\n"; unsigned char mdvalue[EVPMAXMDSIZE]; int mdlen, i; OpenSSLaddalldigests(); if(!argv[1]) { printf("Usage: mdtest digestname\n"); exit(1); } md = EVPgetdigestbyname(argv[1]); if(!md) {printf("Unknown message digest %s\n", argv[1]);
exit(1); } EVPMDCTXinit(&mdctx); EVPDigestInitex(&mdctx, md, NULL); EVPDigestUpdate(&mdctx, mess1, strlen(mess1)); EVPDigestUpdate(&mdctx, mess2, strlen(mess2)); EVPDigestFinalex(&mdctx, mdvalue, &mdlen); EVPMDCTXcleanup(&mdctx); printf("Digest is: ");for(i = 0; i < mdlen; i++) printf("%02x", mdvalue[i]);
printf("\n"); }BUGS
The link between digests and signing algorithms results in a situation where EVPsha1() must be used with RSA and EVPdss1() must be used with DSS even though they are identical digests.SEE ALSO
evp(3), hmac(3), md2(3), md5(3), mdc2(3), ripemd(3), sha(3), dgst(1) HISTORY EVPDigestInit(), EVPDigestUpdate() and EVPDigestFinal() are available in all versions of SSLeay and OpenSSL. EVPMDCTXinit(), EVPMDCTXcreate(), EVPMDCTXcopyex(), EVPMDCTXcleanup(), EVPMDCTXdestroy(), EVPDigestInitex() and EVPDigestFinalex() were added in OpenSSL 0.9.7. EVPmdnull(), EVPmd2(), EVPmd5(), EVPsha(), EVPsha1(), EVPdss(), EVPdss1(), EVPmdc2() and EVPripemd160() were changed to return truely const EVPMD * in OpenSSL 0.9.7.0.9.7l 2003-09-30 EVPDigestInit(3)