xref: /openssl/doc/man3/BIO_f_md.pod (revision aa3347ba)
1=pod
2
3=head1 NAME
4
5BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter
6
7=head1 SYNOPSIS
8
9=for openssl multiple includes
10
11 #include <openssl/bio.h>
12 #include <openssl/evp.h>
13
14 const BIO_METHOD *BIO_f_md(void);
15 int BIO_set_md(BIO *b, EVP_MD *md);
16 int BIO_get_md(BIO *b, EVP_MD **mdp);
17 int BIO_get_md_ctx(BIO *b, EVP_MD_CTX **mdcp);
18
19=head1 DESCRIPTION
20
21BIO_f_md() returns the message digest BIO method. This is a filter
22BIO that digests any data passed through it.  It is a BIO wrapper
23for the digest routines EVP_DigestInit(), EVP_DigestUpdate()
24and EVP_DigestFinal().
25
26Any data written or read through a digest BIO using BIO_read_ex() and
27BIO_write_ex() is digested.
28
29BIO_gets(), if its B<size> parameter is large enough finishes the
30digest calculation and returns the digest value. BIO_puts() is
31not supported.
32
33BIO_reset() reinitialises a digest BIO.
34
35BIO_set_md() sets the message digest of BIO B<b> to B<md>: this
36must be called to initialize a digest BIO before any data is
37passed through it. It is a BIO_ctrl() macro.
38
39BIO_get_md() places a pointer to the digest BIOs digest method
40in B<mdp>.  It is a BIO_ctrl() macro.
41
42BIO_get_md_ctx() returns the digest BIOs context into B<mdcp>.
43
44=head1 NOTES
45
46The context returned by BIO_get_md_ctx() can be used in calls
47to EVP_DigestFinal() and also the signature routines EVP_SignFinal()
48and EVP_VerifyFinal().
49
50The context returned by BIO_get_md_ctx() is an internal context
51structure. Changes made to this context will affect the digest
52BIO itself and the context pointer will become invalid when the digest
53BIO is freed.
54
55After the digest has been retrieved from a digest BIO it must be
56reinitialized by calling BIO_reset(), or BIO_set_md() before any more
57data is passed through it.
58
59If an application needs to call BIO_gets() or BIO_puts() through
60a chain containing digest BIOs then this can be done by prepending
61a buffering BIO.
62
63Calling BIO_get_md_ctx() will return the context and initialize the BIO
64state. This allows applications to initialize the context externally
65if the standard calls such as BIO_set_md() are not sufficiently flexible.
66
67=head1 RETURN VALUES
68
69BIO_f_md() returns the digest BIO method.
70
71BIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and
72<=0 for failure.
73
74=head1 EXAMPLES
75
76The following example creates a BIO chain containing an SHA1 and MD5
77digest BIO and passes the string "Hello World" through it. Error
78checking has been omitted for clarity.
79
80 BIO *bio, *mdtmp;
81 char message[] = "Hello World";
82
83 bio = BIO_new(BIO_s_null());
84 mdtmp = BIO_new(BIO_f_md());
85 BIO_set_md(mdtmp, EVP_sha1());
86 /*
87  * For BIO_push() we want to append the sink BIO and keep a note of
88  * the start of the chain.
89  */
90 bio = BIO_push(mdtmp, bio);
91 mdtmp = BIO_new(BIO_f_md());
92 BIO_set_md(mdtmp, EVP_md5());
93 bio = BIO_push(mdtmp, bio);
94 /* Note: mdtmp can now be discarded */
95 BIO_write(bio, message, strlen(message));
96
97The next example digests data by reading through a chain instead:
98
99 BIO *bio, *mdtmp;
100 char buf[1024];
101 int rdlen;
102
103 bio = BIO_new_file(file, "rb");
104 mdtmp = BIO_new(BIO_f_md());
105 BIO_set_md(mdtmp, EVP_sha1());
106 bio = BIO_push(mdtmp, bio);
107 mdtmp = BIO_new(BIO_f_md());
108 BIO_set_md(mdtmp, EVP_md5());
109 bio = BIO_push(mdtmp, bio);
110 do {
111     rdlen = BIO_read(bio, buf, sizeof(buf));
112     /* Might want to do something with the data here */
113 } while (rdlen > 0);
114
115This next example retrieves the message digests from a BIO chain and
116outputs them. This could be used with the examples above.
117
118 BIO *mdtmp;
119 unsigned char mdbuf[EVP_MAX_MD_SIZE];
120 int mdlen;
121 int i;
122
123 mdtmp = bio;   /* Assume bio has previously been set up */
124 do {
125     EVP_MD *md;
126
127     mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
128     if (!mdtmp)
129         break;
130     BIO_get_md(mdtmp, &md);
131     printf("%s digest", OBJ_nid2sn(EVP_MD_get_type(md)));
132     mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
133     for (i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
134     printf("\n");
135     mdtmp = BIO_next(mdtmp);
136 } while (mdtmp);
137
138 BIO_free_all(bio);
139
140=head1 BUGS
141
142The lack of support for BIO_puts() and the non standard behaviour of
143BIO_gets() could be regarded as anomalous. It could be argued that BIO_gets()
144and BIO_puts() should be passed to the next BIO in the chain and digest
145the data passed through and that digests should be retrieved using a
146separate BIO_ctrl() call.
147
148=head1 HISTORY
149
150Before OpenSSL 1.0.0., the call to BIO_get_md_ctx() would only work if the
151BIO was initialized first.
152
153=head1 COPYRIGHT
154
155Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
156
157Licensed under the Apache License 2.0 (the "License").  You may not use
158this file except in compliance with the License.  You can obtain a copy
159in the file LICENSE in the source distribution or at
160L<https://www.openssl.org/source/license.html>.
161
162=cut
163