]>
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"; | |
e9b77246 | 82 | |
5fd0cd9a DSH |
83 | bio = BIO_new(BIO_s_null()); |
84 | mdtmp = BIO_new(BIO_f_md()); | |
85 | BIO_set_md(mdtmp, EVP_sha1()); | |
2947af32 BB |
86 | /* |
87 | * For BIO_push() we want to append the sink BIO and keep a note of | |
5fd0cd9a DSH |
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 | ||
97 | The next example digests data by reading through a chain instead: | |
98 | ||
99 | BIO *bio, *mdtmp; | |
100 | char buf[1024]; | |
101 | int rdlen; | |
e9b77246 | 102 | |
5fd0cd9a DSH |
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 { | |
2947af32 BB |
111 | rdlen = BIO_read(bio, buf, sizeof(buf)); |
112 | /* Might want to do something with the data here */ | |
2f8e53d7 | 113 | } while (rdlen > 0); |
5fd0cd9a DSH |
114 | |
115 | This next example retrieves the message digests from a BIO chain and | |
116 | outputs 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; | |
e9b77246 | 122 | |
1bc74519 | 123 | mdtmp = bio; /* Assume bio has previously been set up */ |
5fd0cd9a | 124 | do { |
2947af32 | 125 | EVP_MD *md; |
e9b77246 | 126 | |
2947af32 BB |
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_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); | |
2f8e53d7 | 136 | } while (mdtmp); |
5fd0cd9a DSH |
137 | |
138 | BIO_free_all(bio); | |
139 | ||
140 | =head1 BUGS | |
141 | ||
acb5b343 | 142 | The lack of support for BIO_puts() and the non standard behaviour of |
5fd0cd9a DSH |
143 | BIO_gets() could be regarded as anomalous. It could be argued that BIO_gets() |
144 | and BIO_puts() should be passed to the next BIO in the chain and digest | |
145 | the data passed through and that digests should be retrieved using a | |
146 | separate BIO_ctrl() call. | |
147 | ||
a528d4f0 RS |
148 | =head1 HISTORY |
149 | ||
150 | Before OpenSSL 1.0.0., the call to BIO_get_md_ctx() would only work if the | |
151 | BIO was initialized first. | |
152 | ||
e2f92610 RS |
153 | =head1 COPYRIGHT |
154 | ||
155 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
156 | ||
157 | Licensed under the OpenSSL license (the "License"). You may not use | |
158 | this file except in compliance with the License. You can obtain a copy | |
159 | in the file LICENSE in the source distribution or at | |
160 | L<https://www.openssl.org/source/license.html>. | |
161 | ||
162 | =cut |