openssl之EVP系列之8---EVP_Digest系列函数具体解释

openssl之EVP系列之8---EVP_Digest系列函数具体解释
    ---依据openssl doc/crypto/EVP_DigestInit.pod翻译和自己的理解写成
    （作者：DragonKing, Mail: wzhah@263.net ,公布于：http://openssl.126.com 之openssl专业论坛,版本号：openssl-0.9.7）
    EVP_Digest系列提供了与EVP_Encrypt系列相似的函数，定义例如以下（openssl/evp.h）：
    
     void EVP_MD_CTX_init(EVP_MD_CTX *ctx);
     EVP_MD_CTX *EVP_MD_CTX_create(void);
    
     int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
     int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
     int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md,
     unsigned int *s);
    
     int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx);
     void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx);
    
     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); 
    
     #define EVP_MAX_MD_SIZE (16+20) /* The SSLv3 md5+sha1 type */
    
     #define EVP_MD_type(e) ((e)->type)
     #define EVP_MD_pkey_type(e) ((e)->pkey_type)
     #define EVP_MD_size(e) ((e)->md_size)
     #define EVP_MD_block_size(e) ((e)->block_size)
    
     #define EVP_MD_CTX_md(e) (e)->digest)
     #define EVP_MD_CTX_size(e) EVP_MD_size((e)->digest)
     #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest)
     #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest)
    【EVP_MD_CTX_init】
    该函数初始化一个EVP_MD_CTX结构。
    【EVP_MD_CTX_create】
    该函数创建一个EVP_MD_CTX结构，分配内存并进行初始化，返回该结构。

    【EVP_DigestInit_ex】
    该函数使用參数impl所指向的ENGINE设置该信息摘要结构体，參数ctx在调用本函数之前必须经过初始化。參数type通常是使用象EVP_sha1这种函数的返回值。假设impl为NULL。那么就会使用缺省实现的信息摘要函数。

大多数应用程序里面impl是设置为NULL的。

操作成功返回1，否则返回0。
    【EVP_DigestUpdate】
    该函数将參数d中的cnt字节数据进行信息摘要到ctx结构中去。该函数能够被调用多次。用以对很多其它的数据进行信息摘要。操作成功返回1，否则返回0。
    【EVP_DigestFinal_ex】
    本函数将ctx结构中的摘要信息数据返回到參数md中，假设參数s不是NULL，那么摘要数据的长度（字节）就会被写入到參数s中，大多数情况瞎，写入的值是EVP_MAX_MD_SIZE。在调用本函数后。不能使用同样的ctx结构调用EVP_DigestUpdate再进行数据的信息摘要操作,可是假设调用EVP_DigestInit_ex函数又一次初始化后能够进行新的信息摘要操作。操作成功返回1，否则返回0。

    【EVP_MD_CTX_cleanup】
    清除一个信息摘要结构，该函数应该在一个信息摘要结构使用后不再须要的时候调用。
    【EVP_MD_CTX_destroy】
    清除信息摘要结构并释放全部分配的内存空间，仅仅有使用EVP_MD_CTX_create函数创建的信息摘要结构才干使用该函数进行释放。
    【EVP_MD_CTX_copy_ex】
    该函数能够用来将信息摘要数据从in结构复制到out结构中。假设有大量的数据须要进行信息摘要。并且这些数据仅仅有最后几个字节不同的时候，使用该函数就显得特别实用。节省时间。当中，out结构必须在调用本函数之前进行初始化。操作成功返回1。否则返回0。

    【EVP_DigestInit】
    该函数功能跟EVP_DigestInit_ex函数同样，可是ctx參数能够不用初始化，并且该函数仅仅使用缺省实现的算法。

    【EVP_DigestFinal】
    该函数功能跟EVP_DigestFinal_ex函数同样，可是ctx结构会自己主动清除。一般来说，如今新的程序应该使用EVP_DigestInit_ex和EVP_DigestFinal_ex函数。由于这些函数能够在使用完一个EVP_MD_CTX结构后，不用又一次声明和初始化该结构就能使用它进行新的数据处理，并且新的带_ex的函数也能够使用非缺省的实现算法库。

    【EVP_MD_CTX_copy】
    该函数跟EVP_MD_CTX_copy_ex函数功能同样，可是out參数能够不用初始化。
    【EVP_MD_size和EVP_MD_CTX_size】
    这两个函数返回结构里面摘要信息的长度。
    【EVP_MD_block_size和EVP_MD_CTX_block_size】
    这两个函数返回摘要信息块处理的长度。
    【EVP_MD_type和EVP_MD_CTX_type】
    这两个函数返回信息摘要结构算法的NID。比如。EVP_MD_type(EVP_sha1())返回NID_sha1。该函数通常在设置ASN1 OID的时候使用。假设算法不存在。返回NID_undef。

    【EVP_MD_CTX_md】
    该函数返回给定EVP_MD_CTX结构里面的EVP_MD结构。
    【EVP_MD_pkey_type】
    该函数返回信息摘要结构里面公钥签名算法的NID。比如，假设EVP_sha1是使用RSA签名算法，那么就会返回NID_sha1WithRSAEncryption。
    【EVP_md2、EVP_md5、EVP_sha、EVP_sha1、EVP_mdc2和EVP_ripemd160】
    这些函数返回对应名字的EVP_MD结构，它们都使用RSA算法作为签名算法。在新的程序里，一般推荐使用sha1算法。
    【EVP_dss和EVP_dss1】
    这两个函数返回的EVP_MD结构分别使用sha和sha1信息摘要算法，可是签名算法使用DSS（DSA）。
    【EVP_md_null】
    该函数返回的信息摘要结构不作不论什么事情，返回的摘要信息长度为0。
    【EVP_get_digestbyname、EVP_get_digestbynid和EVP_get_digestbyobj】
    这三个函数分别依据给定的算法名称、算法NID以及ASN1_OBJECT结构返回一个对应的EVP_MD算法结构。

摘要算法在使用之前必须进行初始化，如使用Openssl_add_all_digests进行初始化。假设调用不成功，返回NULL。