Debian Codegraph @

upstream/debian-unstable/man3/BIO_f_md.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "BIO_F_MD 3SSL"
58 .TH BIO_F_MD 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx \- message digest BIO filter
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 2
68 \& #include <openssl/bio.h>
69 \& #include <openssl/evp.h>
70 \&
71 \& const BIO_METHOD *BIO_f_md(void);
72 \& int BIO_set_md(BIO *b, EVP_MD *md);
73 \& int BIO_get_md(BIO *b, EVP_MD **mdp);
74 \& int BIO_get_md_ctx(BIO *b, EVP_MD_CTX **mdcp);
75 .Ve
76 .SH DESCRIPTION
77 .IX Header "DESCRIPTION"
78 \&\fBBIO_f_md()\fR returns the message digest BIO method. This is a filter
79 BIO that digests any data passed through it. It is a BIO wrapper
80 for the digest routines \fBEVP_DigestInit()\fR, \fBEVP_DigestUpdate()\fR
81 and \fBEVP_DigestFinal()\fR.
82 .PP
83 Any data written or read through a digest BIO using \fBBIO_read_ex()\fR and
84 \&\fBBIO_write_ex()\fR is digested.
85 .PP
86 \&\fBBIO_gets()\fR, if its \fBsize\fR parameter is large enough finishes the
87 digest calculation and returns the digest value. \fBBIO_puts()\fR is
88 not supported.
89 .PP
90 \&\fBBIO_reset()\fR reinitialises a digest BIO.
91 .PP
92 \&\fBBIO_set_md()\fR sets the message digest of BIO \fBb\fR to \fBmd\fR: this
93 must be called to initialize a digest BIO before any data is
94 passed through it. It is a \fBBIO_ctrl()\fR macro.
95 .PP
96 \&\fBBIO_get_md()\fR places a pointer to the digest BIOs digest method
97 in \fBmdp\fR. It is a \fBBIO_ctrl()\fR macro.
98 .PP
99 \&\fBBIO_get_md_ctx()\fR returns the digest BIOs context into \fBmdcp\fR.
100 .SH NOTES
101 .IX Header "NOTES"
102 The context returned by \fBBIO_get_md_ctx()\fR can be used in calls
103 to \fBEVP_DigestFinal()\fR and also the signature routines \fBEVP_SignFinal()\fR
104 and \fBEVP_VerifyFinal()\fR.
105 .PP
106 The context returned by \fBBIO_get_md_ctx()\fR is an internal context
107 structure. Changes made to this context will affect the digest
108 BIO itself and the context pointer will become invalid when the digest
109 BIO is freed.
110 .PP
111 After the digest has been retrieved from a digest BIO it must be
112 reinitialized by calling \fBBIO_reset()\fR, or \fBBIO_set_md()\fR before any more
113 data is passed through it.
114 .PP
115 If an application needs to call \fBBIO_gets()\fR or \fBBIO_puts()\fR through
116 a chain containing digest BIOs then this can be done by prepending
117 a buffering BIO.
118 .PP
119 Calling \fBBIO_get_md_ctx()\fR will return the context and initialize the BIO
120 state. This allows applications to initialize the context externally
121 if the standard calls such as \fBBIO_set_md()\fR are not sufficiently flexible.
122 .SH "RETURN VALUES"
123 .IX Header "RETURN VALUES"
124 \&\fBBIO_f_md()\fR returns the digest BIO method.
125 .PP
126 \&\fBBIO_set_md()\fR, \fBBIO_get_md()\fR and \fBBIO_md_ctx()\fR return 1 for success and
127 <=0 for failure.
128 .SH EXAMPLES
129 .IX Header "EXAMPLES"
130 The following example creates a BIO chain containing an SHA1 and MD5
131 digest BIO and passes the string "Hello World" through it. Error
132 checking has been omitted for clarity.
133 .PP
134 .Vb 2
135 \& BIO *bio, *mdtmp;
136 \& char message[] = "Hello World";
137 \&
138 \& bio = BIO_new(BIO_s_null());
139 \& mdtmp = BIO_new(BIO_f_md());
140 \& BIO_set_md(mdtmp, EVP_sha1());
141 \& /*
142 \& * For BIO_push() we want to append the sink BIO and keep a note of
143 \& * the start of the chain.
144 \& */
145 \& bio = BIO_push(mdtmp, bio);
146 \& mdtmp = BIO_new(BIO_f_md());
147 \& BIO_set_md(mdtmp, EVP_md5());
148 \& bio = BIO_push(mdtmp, bio);
149 \& /* Note: mdtmp can now be discarded */
150 \& BIO_write(bio, message, strlen(message));
151 .Ve
152 .PP
153 The next example digests data by reading through a chain instead:
154 .PP
155 .Vb 3
156 \& BIO *bio, *mdtmp;
157 \& char buf[1024];
158 \& int rdlen;
159 \&
160 \& bio = BIO_new_file(file, "rb");
161 \& mdtmp = BIO_new(BIO_f_md());
162 \& BIO_set_md(mdtmp, EVP_sha1());
163 \& bio = BIO_push(mdtmp, bio);
164 \& mdtmp = BIO_new(BIO_f_md());
165 \& BIO_set_md(mdtmp, EVP_md5());
166 \& bio = BIO_push(mdtmp, bio);
167 \& do {
168 \& rdlen = BIO_read(bio, buf, sizeof(buf));
169 \& /* Might want to do something with the data here */
170 \& } while (rdlen > 0);
171 .Ve
172 .PP
173 This next example retrieves the message digests from a BIO chain and
174 outputs them. This could be used with the examples above.
175 .PP
176 .Vb 4
177 \& BIO *mdtmp;
178 \& unsigned char mdbuf[EVP_MAX_MD_SIZE];
179 \& int mdlen;
180 \& int i;
181 \&
182 \& mdtmp = bio; /* Assume bio has previously been set up */
183 \& do {
184 \& EVP_MD *md;
185 \&
186 \& mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
187 \& if (!mdtmp)
188 \& break;
189 \& BIO_get_md(mdtmp, &md);
190 \& printf("%s digest", OBJ_nid2sn(EVP_MD_get_type(md)));
191 \& mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
192 \& for (i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
193 \& printf("\en");
194 \& mdtmp = BIO_next(mdtmp);
195 \& } while (mdtmp);
196 \&
197 \& BIO_free_all(bio);
198 .Ve
199 .SH BUGS
200 .IX Header "BUGS"
201 The lack of support for \fBBIO_puts()\fR and the non standard behaviour of
202 \&\fBBIO_gets()\fR could be regarded as anomalous. It could be argued that \fBBIO_gets()\fR
203 and \fBBIO_puts()\fR should be passed to the next BIO in the chain and digest
204 the data passed through and that digests should be retrieved using a
205 separate \fBBIO_ctrl()\fR call.
206 .SH HISTORY
207 .IX Header "HISTORY"
208 Before OpenSSL 1.0.0., the call to \fBBIO_get_md_ctx()\fR would only work if the
209 BIO was initialized first.
210 .SH COPYRIGHT
211 .IX Header "COPYRIGHT"
212 Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved.
213 .PP
214 Licensed under the Apache License 2.0 (the "License"). You may not use
215 this file except in compliance with the License. You can obtain a copy
216 in the file LICENSE in the source distribution or at
217 <https://www.openssl.org/source/license.html>.