168651Skris=pod 268651Skris 368651Skris=head1 NAME 468651Skris 568651SkrisBIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter 668651Skris 768651Skris=head1 SYNOPSIS 868651Skris 968651Skris #include <openssl/bio.h> 1068651Skris #include <openssl/evp.h> 1168651Skris 1268651Skris BIO_METHOD * BIO_f_md(void); 1368651Skris int BIO_set_md(BIO *b,EVP_MD *md); 1468651Skris int BIO_get_md(BIO *b,EVP_MD **mdp); 1568651Skris int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp); 1668651Skris 1768651Skris=head1 DESCRIPTION 1868651Skris 1968651SkrisBIO_f_md() returns the message digest BIO method. This is a filter 2068651SkrisBIO that digests any data passed through it, it is a BIO wrapper 2168651Skrisfor the digest routines EVP_DigestInit(), EVP_DigestUpdate() 2268651Skrisand EVP_DigestFinal(). 2368651Skris 2468651SkrisAny data written or read through a digest BIO using BIO_read() and 2568651SkrisBIO_write() is digested. 2668651Skris 2768651SkrisBIO_gets(), if its B<size> parameter is large enough finishes the 2868651Skrisdigest calculation and returns the digest value. BIO_puts() is 2968651Skrisnot supported. 3068651Skris 31109998SmarkmBIO_reset() reinitialises a digest BIO. 3268651Skris 3368651SkrisBIO_set_md() sets the message digest of BIO B<b> to B<md>: this 3468651Skrismust be called to initialize a digest BIO before any data is 3568651Skrispassed through it. It is a BIO_ctrl() macro. 3668651Skris 3768651SkrisBIO_get_md() places the a pointer to the digest BIOs digest method 3868651Skrisin B<mdp>, it is a BIO_ctrl() macro. 3968651Skris 4068651SkrisBIO_get_md_ctx() returns the digest BIOs context into B<mdcp>. 4168651Skris 4268651Skris=head1 NOTES 4368651Skris 4468651SkrisThe context returned by BIO_get_md_ctx() can be used in calls 4568651Skristo EVP_DigestFinal() and also the signature routines EVP_SignFinal() 4668651Skrisand EVP_VerifyFinal(). 4768651Skris 4868651SkrisThe context returned by BIO_get_md_ctx() is an internal context 4968651Skrisstructure. Changes made to this context will affect the digest 5068651SkrisBIO itself and the context pointer will become invalid when the digest 5168651SkrisBIO is freed. 5268651Skris 5368651SkrisAfter the digest has been retrieved from a digest BIO it must be 5468651Skrisreinitialized by calling BIO_reset(), or BIO_set_md() before any more 5568651Skrisdata is passed through it. 5668651Skris 5768651SkrisIf an application needs to call BIO_gets() or BIO_puts() through 5868651Skrisa chain containing digest BIOs then this can be done by prepending 5968651Skrisa buffering BIO. 6068651Skris 61238405SjkimBefore OpenSSL 1.0.0 the call to BIO_get_md_ctx() would only work if the BIO 62238405Sjkimhad been initialized for example by calling BIO_set_md() ). In OpenSSL 63238405Sjkim1.0.0 and later the context is always returned and the BIO is state is set 64238405Sjkimto initialized. This allows applications to initialize the context externally 65238405Sjkimif the standard calls such as BIO_set_md() are not sufficiently flexible. 66238405Sjkim 6768651Skris=head1 RETURN VALUES 6868651Skris 6968651SkrisBIO_f_md() returns the digest BIO method. 7068651Skris 7168651SkrisBIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and 7268651Skris0 for failure. 7368651Skris 7468651Skris=head1 EXAMPLES 7568651Skris 7668651SkrisThe following example creates a BIO chain containing an SHA1 and MD5 7768651Skrisdigest BIO and passes the string "Hello World" through it. Error 7868651Skrischecking has been omitted for clarity. 7968651Skris 8068651Skris BIO *bio, *mdtmp; 8168651Skris char message[] = "Hello World"; 8268651Skris bio = BIO_new(BIO_s_null()); 8368651Skris mdtmp = BIO_new(BIO_f_md()); 8468651Skris BIO_set_md(mdtmp, EVP_sha1()); 8568651Skris /* For BIO_push() we want to append the sink BIO and keep a note of 8668651Skris * the start of the chain. 8768651Skris */ 8868651Skris bio = BIO_push(mdtmp, bio); 8968651Skris mdtmp = BIO_new(BIO_f_md()); 9068651Skris BIO_set_md(mdtmp, EVP_md5()); 9168651Skris bio = BIO_push(mdtmp, bio); 9268651Skris /* Note: mdtmp can now be discarded */ 9368651Skris BIO_write(bio, message, strlen(message)); 9468651Skris 9568651SkrisThe next example digests data by reading through a chain instead: 9668651Skris 9768651Skris BIO *bio, *mdtmp; 9868651Skris char buf[1024]; 9968651Skris int rdlen; 10068651Skris bio = BIO_new_file(file, "rb"); 10168651Skris mdtmp = BIO_new(BIO_f_md()); 10268651Skris BIO_set_md(mdtmp, EVP_sha1()); 10368651Skris bio = BIO_push(mdtmp, bio); 10468651Skris mdtmp = BIO_new(BIO_f_md()); 10568651Skris BIO_set_md(mdtmp, EVP_md5()); 10668651Skris bio = BIO_push(mdtmp, bio); 10768651Skris do { 10868651Skris rdlen = BIO_read(bio, buf, sizeof(buf)); 10968651Skris /* Might want to do something with the data here */ 11068651Skris } while(rdlen > 0); 11168651Skris 11268651SkrisThis next example retrieves the message digests from a BIO chain and 11368651Skrisoutputs them. This could be used with the examples above. 11468651Skris 11568651Skris BIO *mdtmp; 11668651Skris unsigned char mdbuf[EVP_MAX_MD_SIZE]; 11768651Skris int mdlen; 11868651Skris int i; 11968651Skris mdtmp = bio; /* Assume bio has previously been set up */ 12068651Skris do { 12168651Skris EVP_MD *md; 12268651Skris mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD); 12368651Skris if(!mdtmp) break; 12468651Skris BIO_get_md(mdtmp, &md); 12568651Skris printf("%s digest", OBJ_nid2sn(EVP_MD_type(md))); 12668651Skris mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE); 12768651Skris for(i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]); 12868651Skris printf("\n"); 12968651Skris mdtmp = BIO_next(mdtmp); 13068651Skris } while(mdtmp); 13168651Skris 13268651Skris BIO_free_all(bio); 13368651Skris 13468651Skris=head1 BUGS 13568651Skris 13668651SkrisThe lack of support for BIO_puts() and the non standard behaviour of 13768651SkrisBIO_gets() could be regarded as anomalous. It could be argued that BIO_gets() 13868651Skrisand BIO_puts() should be passed to the next BIO in the chain and digest 13968651Skristhe data passed through and that digests should be retrieved using a 14068651Skrisseparate BIO_ctrl() call. 14168651Skris 14268651Skris=head1 SEE ALSO 14368651Skris 14468651SkrisTBA 145