Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / BIO_f_md.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
74dab6c2
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH BIO_f_md 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
74dab6c2
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
74dab6c2
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc 190.SH "NAME"
74dab6c2 191BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx \- message digest BIO filter
984263bc 192.SH "SYNOPSIS"
74dab6c2 193.PP
984263bc
MD
194.Vb 2
195\& #include <openssl/bio.h>
196\& #include <openssl/evp.h>
197.Ve
198.Vb 4
199\& BIO_METHOD * BIO_f_md(void);
200\& int BIO_set_md(BIO *b,EVP_MD *md);
201\& int BIO_get_md(BIO *b,EVP_MD **mdp);
202\& int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp);
203.Ve
204.SH "DESCRIPTION"
74dab6c2
JR
205\fIBIO_f_md()\fR returns the message digest BIO method. This is a filter
206BIO that digests any data passed through it, it is a BIO wrapper
984263bc
MD
207for the digest routines \fIEVP_DigestInit()\fR, \fIEVP_DigestUpdate()\fR
208and \fIEVP_DigestFinal()\fR.
209.PP
74dab6c2
JR
210Any data written or read through a digest BIO using \fIBIO_read()\fR and
211\fIBIO_write()\fR is digested.
984263bc 212.PP
74dab6c2 213\fIBIO_gets()\fR, if its \fBsize\fR parameter is large enough finishes the
984263bc
MD
214digest calculation and returns the digest value. \fIBIO_puts()\fR is
215not supported.
216.PP
74dab6c2 217\fIBIO_reset()\fR reinitialises a digest BIO.
984263bc 218.PP
74dab6c2
JR
219\fIBIO_set_md()\fR sets the message digest of BIO \fBb\fR to \fBmd\fR: this
220must be called to initialize a digest BIO before any data is
984263bc
MD
221passed through it. It is a \fIBIO_ctrl()\fR macro.
222.PP
74dab6c2 223\fIBIO_get_md()\fR places the a pointer to the digest BIOs digest method
984263bc
MD
224in \fBmdp\fR, it is a \fIBIO_ctrl()\fR macro.
225.PP
74dab6c2 226\fIBIO_get_md_ctx()\fR returns the digest BIOs context into \fBmdcp\fR.
984263bc 227.SH "NOTES"
984263bc
MD
228The context returned by \fIBIO_get_md_ctx()\fR can be used in calls
229to \fIEVP_DigestFinal()\fR and also the signature routines \fIEVP_SignFinal()\fR
230and \fIEVP_VerifyFinal()\fR.
231.PP
232The context returned by \fIBIO_get_md_ctx()\fR is an internal context
233structure. Changes made to this context will affect the digest
74dab6c2
JR
234BIO itself and the context pointer will become invalid when the digest
235BIO is freed.
984263bc 236.PP
74dab6c2 237After the digest has been retrieved from a digest BIO it must be
984263bc
MD
238reinitialized by calling \fIBIO_reset()\fR, or \fIBIO_set_md()\fR before any more
239data is passed through it.
240.PP
241If an application needs to call \fIBIO_gets()\fR or \fIBIO_puts()\fR through
242a chain containing digest BIOs then this can be done by prepending
74dab6c2 243a buffering BIO.
984263bc 244.SH "RETURN VALUES"
74dab6c2 245\fIBIO_f_md()\fR returns the digest BIO method.
984263bc 246.PP
74dab6c2 247\fIBIO_set_md()\fR, \fIBIO_get_md()\fR and \fIBIO_md_ctx()\fR return 1 for success and
984263bc
MD
2480 for failure.
249.SH "EXAMPLES"
74dab6c2
JR
250The following example creates a BIO chain containing an SHA1 and MD5
251digest BIO and passes the string \*(L"Hello World\*(R" through it. Error
984263bc
MD
252checking has been omitted for clarity.
253.PP
254.Vb 14
255\& BIO *bio, *mdtmp;
256\& char message[] = "Hello World";
257\& bio = BIO_new(BIO_s_null());
258\& mdtmp = BIO_new(BIO_f_md());
259\& BIO_set_md(mdtmp, EVP_sha1());
260\& /* For BIO_push() we want to append the sink BIO and keep a note of
261\& * the start of the chain.
262\& */
263\& bio = BIO_push(mdtmp, bio);
264\& mdtmp = BIO_new(BIO_f_md());
265\& BIO_set_md(mdtmp, EVP_md5());
266\& bio = BIO_push(mdtmp, bio);
267\& /* Note: mdtmp can now be discarded */
268\& BIO_write(bio, message, strlen(message));
269.Ve
270The next example digests data by reading through a chain instead:
271.PP
272.Vb 14
273\& BIO *bio, *mdtmp;
274\& char buf[1024];
275\& int rdlen;
276\& bio = BIO_new_file(file, "rb");
277\& mdtmp = BIO_new(BIO_f_md());
278\& BIO_set_md(mdtmp, EVP_sha1());
279\& bio = BIO_push(mdtmp, bio);
280\& mdtmp = BIO_new(BIO_f_md());
281\& BIO_set_md(mdtmp, EVP_md5());
282\& bio = BIO_push(mdtmp, bio);
283\& do {
284\& rdlen = BIO_read(bio, buf, sizeof(buf));
285\& /* Might want to do something with the data here */
286\& } while(rdlen > 0);
287.Ve
74dab6c2 288This next example retrieves the message digests from a BIO chain and
984263bc
MD
289outputs them. This could be used with the examples above.
290.PP
291.Vb 16
292\& BIO *mdtmp;
293\& unsigned char mdbuf[EVP_MAX_MD_SIZE];
294\& int mdlen;
295\& int i;
296\& mdtmp = bio; /* Assume bio has previously been set up */
297\& do {
298\& EVP_MD *md;
299\& mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
300\& if(!mdtmp) break;
301\& BIO_get_md(mdtmp, &md);
302\& printf("%s digest", OBJ_nid2sn(EVP_MD_type(md)));
303\& mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
304\& for(i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
305\& printf("\en");
306\& mdtmp = BIO_next(mdtmp);
307\& } while(mdtmp);
308.Ve
309.Vb 1
310\& BIO_free_all(bio);
311.Ve
312.SH "BUGS"
984263bc 313The lack of support for \fIBIO_puts()\fR and the non standard behaviour of
74dab6c2
JR
314\fIBIO_gets()\fR could be regarded as anomalous. It could be argued that \fIBIO_gets()\fR
315and \fIBIO_puts()\fR should be passed to the next BIO in the chain and digest
984263bc
MD
316the data passed through and that digests should be retrieved using a
317separate \fIBIO_ctrl()\fR call.
318.SH "SEE ALSO"
74dab6c2
JR
319TBA
320
321.rn }` ''
322.IX Title "BIO_f_md 3"
323.IX Name "BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter"
324
325.IX Header "NAME"
326
327.IX Header "SYNOPSIS"
328
329.IX Header "DESCRIPTION"
330
331.IX Header "NOTES"
332
333.IX Header "RETURN VALUES"
334
335.IX Header "EXAMPLES"
336
337.IX Header "BUGS"
338
984263bc 339.IX Header "SEE ALSO"
74dab6c2 340