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