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