1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter 6*2175Sjp161948 7*2175Sjp161948=head1 SYNOPSIS 8*2175Sjp161948 9*2175Sjp161948 #include <openssl/bio.h> 10*2175Sjp161948 #include <openssl/evp.h> 11*2175Sjp161948 12*2175Sjp161948 BIO_METHOD * BIO_f_md(void); 13*2175Sjp161948 int BIO_set_md(BIO *b,EVP_MD *md); 14*2175Sjp161948 int BIO_get_md(BIO *b,EVP_MD **mdp); 15*2175Sjp161948 int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp); 16*2175Sjp161948 17*2175Sjp161948=head1 DESCRIPTION 18*2175Sjp161948 19*2175Sjp161948BIO_f_md() returns the message digest BIO method. This is a filter 20*2175Sjp161948BIO that digests any data passed through it, it is a BIO wrapper 21*2175Sjp161948for the digest routines EVP_DigestInit(), EVP_DigestUpdate() 22*2175Sjp161948and EVP_DigestFinal(). 23*2175Sjp161948 24*2175Sjp161948Any data written or read through a digest BIO using BIO_read() and 25*2175Sjp161948BIO_write() is digested. 26*2175Sjp161948 27*2175Sjp161948BIO_gets(), if its B<size> parameter is large enough finishes the 28*2175Sjp161948digest calculation and returns the digest value. BIO_puts() is 29*2175Sjp161948not supported. 30*2175Sjp161948 31*2175Sjp161948BIO_reset() reinitialises a digest BIO. 32*2175Sjp161948 33*2175Sjp161948BIO_set_md() sets the message digest of BIO B<b> to B<md>: this 34*2175Sjp161948must be called to initialize a digest BIO before any data is 35*2175Sjp161948passed through it. It is a BIO_ctrl() macro. 36*2175Sjp161948 37*2175Sjp161948BIO_get_md() places the a pointer to the digest BIOs digest method 38*2175Sjp161948in B<mdp>, it is a BIO_ctrl() macro. 39*2175Sjp161948 40*2175Sjp161948BIO_get_md_ctx() returns the digest BIOs context into B<mdcp>. 41*2175Sjp161948 42*2175Sjp161948=head1 NOTES 43*2175Sjp161948 44*2175Sjp161948The context returned by BIO_get_md_ctx() can be used in calls 45*2175Sjp161948to EVP_DigestFinal() and also the signature routines EVP_SignFinal() 46*2175Sjp161948and EVP_VerifyFinal(). 47*2175Sjp161948 48*2175Sjp161948The context returned by BIO_get_md_ctx() is an internal context 49*2175Sjp161948structure. Changes made to this context will affect the digest 50*2175Sjp161948BIO itself and the context pointer will become invalid when the digest 51*2175Sjp161948BIO is freed. 52*2175Sjp161948 53*2175Sjp161948After the digest has been retrieved from a digest BIO it must be 54*2175Sjp161948reinitialized by calling BIO_reset(), or BIO_set_md() before any more 55*2175Sjp161948data is passed through it. 56*2175Sjp161948 57*2175Sjp161948If an application needs to call BIO_gets() or BIO_puts() through 58*2175Sjp161948a chain containing digest BIOs then this can be done by prepending 59*2175Sjp161948a buffering BIO. 60*2175Sjp161948 61*2175Sjp161948=head1 RETURN VALUES 62*2175Sjp161948 63*2175Sjp161948BIO_f_md() returns the digest BIO method. 64*2175Sjp161948 65*2175Sjp161948BIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and 66*2175Sjp1619480 for failure. 67*2175Sjp161948 68*2175Sjp161948=head1 EXAMPLES 69*2175Sjp161948 70*2175Sjp161948The following example creates a BIO chain containing an SHA1 and MD5 71*2175Sjp161948digest BIO and passes the string "Hello World" through it. Error 72*2175Sjp161948checking has been omitted for clarity. 73*2175Sjp161948 74*2175Sjp161948 BIO *bio, *mdtmp; 75*2175Sjp161948 char message[] = "Hello World"; 76*2175Sjp161948 bio = BIO_new(BIO_s_null()); 77*2175Sjp161948 mdtmp = BIO_new(BIO_f_md()); 78*2175Sjp161948 BIO_set_md(mdtmp, EVP_sha1()); 79*2175Sjp161948 /* For BIO_push() we want to append the sink BIO and keep a note of 80*2175Sjp161948 * the start of the chain. 81*2175Sjp161948 */ 82*2175Sjp161948 bio = BIO_push(mdtmp, bio); 83*2175Sjp161948 mdtmp = BIO_new(BIO_f_md()); 84*2175Sjp161948 BIO_set_md(mdtmp, EVP_md5()); 85*2175Sjp161948 bio = BIO_push(mdtmp, bio); 86*2175Sjp161948 /* Note: mdtmp can now be discarded */ 87*2175Sjp161948 BIO_write(bio, message, strlen(message)); 88*2175Sjp161948 89*2175Sjp161948The next example digests data by reading through a chain instead: 90*2175Sjp161948 91*2175Sjp161948 BIO *bio, *mdtmp; 92*2175Sjp161948 char buf[1024]; 93*2175Sjp161948 int rdlen; 94*2175Sjp161948 bio = BIO_new_file(file, "rb"); 95*2175Sjp161948 mdtmp = BIO_new(BIO_f_md()); 96*2175Sjp161948 BIO_set_md(mdtmp, EVP_sha1()); 97*2175Sjp161948 bio = BIO_push(mdtmp, bio); 98*2175Sjp161948 mdtmp = BIO_new(BIO_f_md()); 99*2175Sjp161948 BIO_set_md(mdtmp, EVP_md5()); 100*2175Sjp161948 bio = BIO_push(mdtmp, bio); 101*2175Sjp161948 do { 102*2175Sjp161948 rdlen = BIO_read(bio, buf, sizeof(buf)); 103*2175Sjp161948 /* Might want to do something with the data here */ 104*2175Sjp161948 } while(rdlen > 0); 105*2175Sjp161948 106*2175Sjp161948This next example retrieves the message digests from a BIO chain and 107*2175Sjp161948outputs them. This could be used with the examples above. 108*2175Sjp161948 109*2175Sjp161948 BIO *mdtmp; 110*2175Sjp161948 unsigned char mdbuf[EVP_MAX_MD_SIZE]; 111*2175Sjp161948 int mdlen; 112*2175Sjp161948 int i; 113*2175Sjp161948 mdtmp = bio; /* Assume bio has previously been set up */ 114*2175Sjp161948 do { 115*2175Sjp161948 EVP_MD *md; 116*2175Sjp161948 mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD); 117*2175Sjp161948 if(!mdtmp) break; 118*2175Sjp161948 BIO_get_md(mdtmp, &md); 119*2175Sjp161948 printf("%s digest", OBJ_nid2sn(EVP_MD_type(md))); 120*2175Sjp161948 mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE); 121*2175Sjp161948 for(i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]); 122*2175Sjp161948 printf("\n"); 123*2175Sjp161948 mdtmp = BIO_next(mdtmp); 124*2175Sjp161948 } while(mdtmp); 125*2175Sjp161948 126*2175Sjp161948 BIO_free_all(bio); 127*2175Sjp161948 128*2175Sjp161948=head1 BUGS 129*2175Sjp161948 130*2175Sjp161948The lack of support for BIO_puts() and the non standard behaviour of 131*2175Sjp161948BIO_gets() could be regarded as anomalous. It could be argued that BIO_gets() 132*2175Sjp161948and BIO_puts() should be passed to the next BIO in the chain and digest 133*2175Sjp161948the data passed through and that digests should be retrieved using a 134*2175Sjp161948separate BIO_ctrl() call. 135*2175Sjp161948 136*2175Sjp161948=head1 SEE ALSO 137*2175Sjp161948 138*2175Sjp161948TBA 139