openssl之EVP系列之8---EVP_Digest系列函数详解

openssl之EVP系列之8---EVP_Digest系列函数详解
    ---根据openssl doc/crypto/EVP_DigestInit.pod翻译和自己的理解写成
    （作者：DragonKing, Mail: [e-mail] ,发布于： 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。