1.Dd $Mdocdate: September 9 2015 $ 2.Dt BIO_F_MD 3 3.Os 4.Sh NAME 5.Nm BIO_f_md , 6.Nm BIO_set_md , 7.Nm BIO_get_md , 8.Nm BIO_get_md_ctx 9.Nd message digest BIO filter 10.Sh SYNOPSIS 11.In openssl/bio.h 12.In openssl/evp.h 13.Ft BIO_METHOD * 14.Fo BIO_f_md 15.Fa void 16.Fc 17.Ft int 18.Fo BIO_set_md 19.Fa "BIO *b" 20.Fa "EVP_MD *md" 21.Fc 22.Ft int 23.Fo BIO_get_md 24.Fa "BIO *b" 25.Fa "EVP_MD **mdp" 26.Fc 27.Ft int 28.Fo BIO_get_md_ctx 29.Fa "BIO *b" 30.Fa "EVP_MD_CTX **mdcp" 31.Fc 32.Sh DESCRIPTION 33.Fn BIO_f_md 34returns the message digest BIO method. 35This is a filter BIO that digests any data passed through it. 36It is a BIO wrapper for the digest routines 37.Fn EVP_DigestInit , 38.Fn EVP_DigestUpdate , 39and 40.Fn EVP_DigestFinal . 41.Pp 42Any data written or read through a digest BIO using 43.Xr BIO_read 3 44and 45.Xr BIO_write 3 46is digested. 47.Pp 48.Xr BIO_gets 3 , 49if its 50.Sy size 51parameter is large enough, 52finishes the digest calculation and returns the digest value. 53.Xr BIO_puts 3 54is 55not supported. 56.Pp 57.Xr BIO_reset 3 58reinitialises a digest BIO. 59.Pp 60.Fn BIO_set_md 61sets the message digest of BIO 62.Fa b 63to 64.Fa md : 65this must be called to initialize a digest BIO 66before any data is passed through it. 67It is a 68.Xr BIO_ctrl 3 69macro. 70.Pp 71.Fn BIO_get_md 72places the a pointer to the digest BIOs digest method in 73.Fa mdp . 74It is a 75.Xr BIO_ctrl 3 76macro. 77.Pp 78.Fn BIO_get_md_ctx 79returns the digest BIOs context in 80.Fa mdcp . 81.Sh NOTES 82The context returned by 83.Fn BIO_get_md_ctx 84can be used in calls to 85.Xr EVP_DigestFinal 3 86and also in the signature routines 87.Xr EVP_SignFinal 3 88and 89.Xr EVP_VerifyFinal 3 . 90.Pp 91The context returned by 92.Fn BIO_get_md_ctx 93is an internal context structure. 94Changes made to this context will affect the digest BIO itself, and 95the context pointer will become invalid when the digest BIO is freed. 96.Pp 97After the digest has been retrieved from a digest BIO, 98it must be reinitialized by calling 99.Xr BIO_reset 3 100or 101.Fn BIO_set_md 102before any more data is passed through it. 103.Pp 104If an application needs to call 105.Xr BIO_gets 3 106or 107.Xr BIO_puts 3 108through a chain containing digest BIOs, 109then this can be done by prepending a buffering BIO. 110.Pp 111Before OpenSSL 1.0.0 the call to 112.Fn BIO_get_md_ctx 113would only work if the BIO had been initialized for example by calling 114.Fn BIO_set_md . 115In OpenSSL 1.0.0 and later the context is always returned 116and the BIO is state is set to initialized. 117This allows applications to initialize the context externally 118if the standard calls such as 119.Fn BIO_set_md 120are not sufficiently flexible. 121.Sh RETURN VALUES 122.Fn BIO_f_md 123returns the digest BIO method. 124.Pp 125.Fn BIO_set_md , 126.Fn BIO_get_md , 127and 128.Fn BIO_get_md_ctx 129return 1 for success and 0 for failure. 130.Sh EXAMPLES 131The following example creates a BIO chain containing an SHA1 and MD5 132digest BIO and passes the string "Hello World" through it. 133Error checking has been omitted for clarity. 134.Bd -literal -offset 2n 135BIO *bio, *mdtmp; 136const char message[] = "Hello World"; 137bio = BIO_new(BIO_s_null()); 138mdtmp = BIO_new(BIO_f_md()); 139BIO_set_md(mdtmp, EVP_sha1()); 140/* 141 * For BIO_push() we want to append the sink BIO 142 * and keep a note of the start of the chain. 143 */ 144bio = BIO_push(mdtmp, bio); 145mdtmp = BIO_new(BIO_f_md()); 146BIO_set_md(mdtmp, EVP_md5()); 147bio = BIO_push(mdtmp, bio); 148/* Note: mdtmp can now be discarded */ 149BIO_write(bio, message, strlen(message)); 150.Ed 151.Pp 152The next example digests data by reading through a chain instead: 153.Bd -literal -offset 2n 154BIO *bio, *mdtmp; 155char buf[1024]; 156int rdlen; 157 158bio = BIO_new_file(file, "rb"); 159mdtmp = BIO_new(BIO_f_md()); 160BIO_set_md(mdtmp, EVP_sha1()); 161bio = BIO_push(mdtmp, bio); 162mdtmp = BIO_new(BIO_f_md()); 163BIO_set_md(mdtmp, EVP_md5()); 164bio = BIO_push(mdtmp, bio); 165do { 166 rdlen = BIO_read(bio, buf, sizeof(buf)); 167 /* Might want to do something with the data here */ 168} while (rdlen > 0); 169.Ed 170.Pp 171This next example retrieves the message digests from a BIO chain 172and outputs them. 173This could be used with the examples above. 174.Bd -literal -offset 2n 175BIO *mdtmp; 176unsigned char mdbuf[EVP_MAX_MD_SIZE]; 177int mdlen; 178int i; 179 180mdtmp = bio; /* Assume bio has previously been set up */ 181do { 182 EVP_MD *md; 183 mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD); 184 if (!mdtmp) 185 break; 186 BIO_get_md(mdtmp, &md); 187 printf("%s digest", OBJ_nid2sn(EVP_MD_type(md))); 188 mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE); 189 for(i = 0; i < mdlen; i++) 190 printf(":%02X", mdbuf[i]); 191 printf("\en"); 192 mdtmp = BIO_next(mdtmp); 193} while(mdtmp); 194BIO_free_all(bio); 195.Ed 196.Sh BUGS 197The lack of support for 198.Xr BIO_puts 3 199and the non standard behaviour of 200.Xr BIO_gets 3 201could be regarded as anomalous. 202It could be argued that 203.Xr BIO_gets 3 204and 205.Xr BIO_puts 3 206should be passed to the next BIO in the chain and digest the data 207passed through and that digests should be retrieved using a separate 208.Xr BIO_ctrl 3 209call. 210