1 .\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
29 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" Escape single quotes in literal strings from groff's Unicode transform.
55 .\" If the F register is turned on, we'll generate index entries on stderr for
56 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
57 .\" entries marked with X<> in POD. Of course, you'll have to process the
58 .\" output yourself in some meaningful fashion.
61 . tm Index:\\$1\t\\n%\t"\\$2"
71 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
72 .\" Fear. Run. Save yourself. No user-serviceable parts.
73 . \" fudge factors for nroff and troff
82 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
88 . \" simple accents for nroff and troff
98 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
99 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
100 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
101 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
102 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
103 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
105 . \" troff and (daisy-wheel) nroff accents
106 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
107 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
108 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
109 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
110 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
111 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
112 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
113 .ds ae a\h'-(\w'a'u*4/10)'e
114 .ds Ae A\h'-(\w'A'u*4/10)'E
115 . \" corrections for vroff
116 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
117 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
118 . \" for low resolution devices (crt and lpr)
119 .if \n(.H>23 .if \n(.V>19 \
132 .\" ========================================================================
134 .IX Title "BIO_f_md 3"
135 .TH BIO_f_md 3 "2010-02-27" "0.9.8m" "OpenSSL"
136 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
137 .\" way too many mistakes in technical documents.
141 BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx \- message digest BIO filter
143 .IX Header "SYNOPSIS"
145 \& #include <openssl/bio.h>
146 \& #include <openssl/evp.h>
148 \& BIO_METHOD * BIO_f_md(void);
149 \& int BIO_set_md(BIO *b,EVP_MD *md);
150 \& int BIO_get_md(BIO *b,EVP_MD **mdp);
151 \& int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp);
154 .IX Header "DESCRIPTION"
155 \&\fIBIO_f_md()\fR returns the message digest \s-1BIO\s0 method. This is a filter
156 \&\s-1BIO\s0 that digests any data passed through it, it is a \s-1BIO\s0 wrapper
157 for the digest routines \fIEVP_DigestInit()\fR, \fIEVP_DigestUpdate()\fR
158 and \fIEVP_DigestFinal()\fR.
160 Any data written or read through a digest \s-1BIO\s0 using \fIBIO_read()\fR and
161 \&\fIBIO_write()\fR is digested.
163 \&\fIBIO_gets()\fR, if its \fBsize\fR parameter is large enough finishes the
164 digest calculation and returns the digest value. \fIBIO_puts()\fR is
167 \&\fIBIO_reset()\fR reinitialises a digest \s-1BIO\s0.
169 \&\fIBIO_set_md()\fR sets the message digest of \s-1BIO\s0 \fBb\fR to \fBmd\fR: this
170 must be called to initialize a digest \s-1BIO\s0 before any data is
171 passed through it. It is a \fIBIO_ctrl()\fR macro.
173 \&\fIBIO_get_md()\fR places the a pointer to the digest BIOs digest method
174 in \fBmdp\fR, it is a \fIBIO_ctrl()\fR macro.
176 \&\fIBIO_get_md_ctx()\fR returns the digest BIOs context into \fBmdcp\fR.
179 The context returned by \fIBIO_get_md_ctx()\fR can be used in calls
180 to \fIEVP_DigestFinal()\fR and also the signature routines \fIEVP_SignFinal()\fR
181 and \fIEVP_VerifyFinal()\fR.
183 The context returned by \fIBIO_get_md_ctx()\fR is an internal context
184 structure. Changes made to this context will affect the digest
185 \&\s-1BIO\s0 itself and the context pointer will become invalid when the digest
186 \&\s-1BIO\s0 is freed.
188 After the digest has been retrieved from a digest \s-1BIO\s0 it must be
189 reinitialized by calling \fIBIO_reset()\fR, or \fIBIO_set_md()\fR before any more
190 data is passed through it.
192 If an application needs to call \fIBIO_gets()\fR or \fIBIO_puts()\fR through
193 a chain containing digest BIOs then this can be done by prepending
194 a buffering \s-1BIO\s0.
196 .IX Header "RETURN VALUES"
197 \&\fIBIO_f_md()\fR returns the digest \s-1BIO\s0 method.
199 \&\fIBIO_set_md()\fR, \fIBIO_get_md()\fR and \fIBIO_md_ctx()\fR return 1 for success and
202 .IX Header "EXAMPLES"
203 The following example creates a \s-1BIO\s0 chain containing an \s-1SHA1\s0 and \s-1MD5\s0
204 digest \s-1BIO\s0 and passes the string \*(L"Hello World\*(R" through it. Error
205 checking has been omitted for clarity.
209 \& char message[] = "Hello World";
210 \& bio = BIO_new(BIO_s_null());
211 \& mdtmp = BIO_new(BIO_f_md());
212 \& BIO_set_md(mdtmp, EVP_sha1());
213 \& /* For BIO_push() we want to append the sink BIO and keep a note of
214 \& * the start of the chain.
216 \& bio = BIO_push(mdtmp, bio);
217 \& mdtmp = BIO_new(BIO_f_md());
218 \& BIO_set_md(mdtmp, EVP_md5());
219 \& bio = BIO_push(mdtmp, bio);
220 \& /* Note: mdtmp can now be discarded */
221 \& BIO_write(bio, message, strlen(message));
224 The next example digests data by reading through a chain instead:
230 \& bio = BIO_new_file(file, "rb");
231 \& mdtmp = BIO_new(BIO_f_md());
232 \& BIO_set_md(mdtmp, EVP_sha1());
233 \& bio = BIO_push(mdtmp, bio);
234 \& mdtmp = BIO_new(BIO_f_md());
235 \& BIO_set_md(mdtmp, EVP_md5());
236 \& bio = BIO_push(mdtmp, bio);
238 \& rdlen = BIO_read(bio, buf, sizeof(buf));
239 \& /* Might want to do something with the data here */
240 \& } while(rdlen > 0);
243 This next example retrieves the message digests from a \s-1BIO\s0 chain and
244 outputs them. This could be used with the examples above.
248 \& unsigned char mdbuf[EVP_MAX_MD_SIZE];
251 \& mdtmp = bio; /* Assume bio has previously been set up */
254 \& mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
256 \& BIO_get_md(mdtmp, &md);
257 \& printf("%s digest", OBJ_nid2sn(EVP_MD_type(md)));
258 \& mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
259 \& for(i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
261 \& mdtmp = BIO_next(mdtmp);
264 \& BIO_free_all(bio);
268 The lack of support for \fIBIO_puts()\fR and the non standard behaviour of
269 \&\fIBIO_gets()\fR could be regarded as anomalous. It could be argued that \fIBIO_gets()\fR
270 and \fIBIO_puts()\fR should be passed to the next \s-1BIO\s0 in the chain and digest
271 the data passed through and that digests should be retrieved using a
272 separate \fIBIO_ctrl()\fR call.
274 .IX Header "SEE ALSO"