]>
Commit | Line | Data |
---|---|---|
3cbe1980 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
e72d734d DSH |
5 | EVP_MD_CTX_init, EVP_MD_CTX_create, EVP_DigestInit_ex, EVP_DigestUpdate, |
6 | EVP_DigestFinal_ex, EVP_MD_CTX_cleanup, EVP_MD_CTX_destroy, EVP_MAX_MD_SIZE, | |
aafbe1cc MC |
7 | EVP_MD_CTX_copy_ex, EVP_DigestInit, EVP_DigestFinal, EVP_MD_CTX_copy, EVP_MD_type, |
8 | EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size, | |
9 | EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_md_null, EVP_md2, EVP_md5, EVP_sha, EVP_sha1, | |
10 | EVP_sha224, EVP_sha256, EVP_sha384, EVP_sha512, EVP_dss, EVP_dss1, EVP_mdc2, | |
e1b78bc6 RL |
11 | EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj - |
12 | EVP digest routines | |
3cbe1980 DSH |
13 | |
14 | =head1 SYNOPSIS | |
15 | ||
16 | #include <openssl/evp.h> | |
17 | ||
e72d734d DSH |
18 | void EVP_MD_CTX_init(EVP_MD_CTX *ctx); |
19 | EVP_MD_CTX *EVP_MD_CTX_create(void); | |
20 | ||
21 | int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); | |
109d3123 | 22 | int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); |
e72d734d DSH |
23 | int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, |
24 | unsigned int *s); | |
25 | ||
26 | int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx); | |
27 | void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx); | |
28 | ||
29 | int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in); | |
30 | ||
31 | int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); | |
13588350 | 32 | int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, |
4d524e10 | 33 | unsigned int *s); |
3cbe1980 | 34 | |
e72d734d DSH |
35 | int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); |
36 | ||
5a34fcd7 | 37 | #define EVP_MAX_MD_SIZE 64 /* SHA512 */ |
3cbe1980 | 38 | |
5a34fcd7 DSH |
39 | int EVP_MD_type(const EVP_MD *md); |
40 | int EVP_MD_pkey_type(const EVP_MD *md); | |
41 | int EVP_MD_size(const EVP_MD *md); | |
42 | int EVP_MD_block_size(const EVP_MD *md); | |
3cbe1980 | 43 | |
5a34fcd7 DSH |
44 | const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx); |
45 | #define EVP_MD_CTX_size(e) EVP_MD_size(EVP_MD_CTX_md(e)) | |
3cbe1980 | 46 | #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest) |
72b60351 | 47 | #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest) |
3cbe1980 | 48 | |
13588350 DSH |
49 | const EVP_MD *EVP_md_null(void); |
50 | const EVP_MD *EVP_md2(void); | |
51 | const EVP_MD *EVP_md5(void); | |
52 | const EVP_MD *EVP_sha(void); | |
53 | const EVP_MD *EVP_sha1(void); | |
54 | const EVP_MD *EVP_dss(void); | |
55 | const EVP_MD *EVP_dss1(void); | |
56 | const EVP_MD *EVP_mdc2(void); | |
57 | const EVP_MD *EVP_ripemd160(void); | |
3cbe1980 | 58 | |
5a34fcd7 DSH |
59 | const EVP_MD *EVP_sha224(void); |
60 | const EVP_MD *EVP_sha256(void); | |
61 | const EVP_MD *EVP_sha384(void); | |
62 | const EVP_MD *EVP_sha512(void); | |
63 | ||
3cbe1980 DSH |
64 | const EVP_MD *EVP_get_digestbyname(const char *name); |
65 | #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a)) | |
66 | #define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a)) | |
67 | ||
68 | =head1 DESCRIPTION | |
69 | ||
70 | The EVP digest routines are a high level interface to message digests. | |
71 | ||
11c4c02c | 72 | EVP_MD_CTX_init() initializes digest context B<ctx>. |
e72d734d | 73 | |
11c4c02c | 74 | EVP_MD_CTX_create() allocates, initializes and returns a digest context. |
e72d734d DSH |
75 | |
76 | EVP_DigestInit_ex() sets up digest context B<ctx> to use a digest | |
77 | B<type> from ENGINE B<impl>. B<ctx> must be initialized before calling this | |
78 | function. B<type> will typically be supplied by a functionsuch as EVP_sha1(). | |
79 | If B<impl> is NULL then the default implementation of digest B<type> is used. | |
3cbe1980 | 80 | |
4facdbb5 | 81 | EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the |
c8973693 | 82 | digest context B<ctx>. This function can be called several times on the |
3cbe1980 DSH |
83 | same B<ctx> to hash additional data. |
84 | ||
e72d734d | 85 | EVP_DigestFinal_ex() retrieves the digest value from B<ctx> and places |
3cbe1980 DSH |
86 | it in B<md>. If the B<s> parameter is not NULL then the number of |
87 | bytes of data written (i.e. the length of the digest) will be written | |
88 | to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written. | |
e72d734d DSH |
89 | After calling EVP_DigestFinal_ex() no additional calls to EVP_DigestUpdate() |
90 | can be made, but EVP_DigestInit_ex() can be called to initialize a new | |
3cbe1980 DSH |
91 | digest operation. |
92 | ||
e72d734d DSH |
93 | EVP_MD_CTX_cleanup() cleans up digest context B<ctx>, it should be called |
94 | after a digest context is no longer needed. | |
95 | ||
96 | EVP_MD_CTX_destroy() cleans up digest context B<ctx> and frees up the | |
97 | space allocated to it, it should be called only on a context created | |
98 | using EVP_MD_CTX_create(). | |
99 | ||
100 | EVP_MD_CTX_copy_ex() can be used to copy the message digest state from | |
3cbe1980 | 101 | B<in> to B<out>. This is useful if large amounts of data are to be |
e72d734d DSH |
102 | hashed which only differ in the last few bytes. B<out> must be initialized |
103 | before calling this function. | |
104 | ||
105 | EVP_DigestInit() behaves in the same way as EVP_DigestInit_ex() except | |
106 | the passed context B<ctx> does not have to be initialized, and it always | |
107 | uses the default digest implementation. | |
108 | ||
109 | EVP_DigestFinal() is similar to EVP_DigestFinal_ex() except the digest | |
11c4c02c | 110 | context B<ctx> is automatically cleaned up. |
e72d734d DSH |
111 | |
112 | EVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination | |
113 | B<out> does not have to be initialized. | |
3cbe1980 | 114 | |
4facdbb5 | 115 | EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest |
3cbe1980 DSH |
116 | when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the |
117 | hash. | |
118 | ||
4facdbb5 | 119 | EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the |
3cbe1980 DSH |
120 | message digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure. |
121 | ||
4facdbb5 | 122 | EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER |
3cbe1980 | 123 | representing the given message digest when passed an B<EVP_MD> structure. |
4facdbb5 | 124 | For example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is |
3cbe1980 DSH |
125 | normally used when setting ASN1 OIDs. |
126 | ||
72b60351 | 127 | EVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed |
3cbe1980 DSH |
128 | B<EVP_MD_CTX>. |
129 | ||
4facdbb5 UM |
130 | EVP_MD_pkey_type() returns the NID of the public key signing algorithm associated |
131 | with this digest. For example EVP_sha1() is associated with RSA so this will | |
5a34fcd7 DSH |
132 | return B<NID_sha1WithRSAEncryption>. Since digests and signature algorithms |
133 | are no longer linked this function is only retained for compatibility | |
134 | reasons. | |
3cbe1980 | 135 | |
5a34fcd7 DSH |
136 | EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_sha224(), EVP_sha256(), |
137 | EVP_sha384(), EVP_sha512(), EVP_mdc2() and EVP_ripemd160() return B<EVP_MD> | |
138 | structures for the MD2, MD5, SHA, SHA1, SHA224, SHA256, SHA384, SHA512, MDC2 | |
139 | and RIPEMD160 digest algorithms respectively. | |
3cbe1980 | 140 | |
4facdbb5 | 141 | EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest |
3fa39ed7 DSH |
142 | algorithms but using DSS (DSA) for the signature algorithm. Note: there is |
143 | no need to use these pseudo-digests in OpenSSL 1.0.0 and later, they are | |
144 | however retained for compatibility. | |
3cbe1980 | 145 | |
4facdbb5 | 146 | EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it |
3cbe1980 DSH |
147 | returns is of zero length. |
148 | ||
4facdbb5 | 149 | EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() |
3cbe1980 | 150 | return an B<EVP_MD> structure when passed a digest name, a digest NID or |
c8973693 | 151 | an ASN1_OBJECT structure respectively. The digest table must be initialized |
4facdbb5 | 152 | using, for example, OpenSSL_add_all_digests() for these functions to work. |
3cbe1980 DSH |
153 | |
154 | =head1 RETURN VALUES | |
155 | ||
e72d734d | 156 | EVP_DigestInit_ex(), EVP_DigestUpdate() and EVP_DigestFinal_ex() return 1 for |
13588350 | 157 | success and 0 for failure. |
3cbe1980 | 158 | |
e72d734d | 159 | EVP_MD_CTX_copy_ex() returns 1 if successful or 0 for failure. |
3cbe1980 DSH |
160 | |
161 | EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the | |
162 | corresponding OBJECT IDENTIFIER or NID_undef if none exists. | |
163 | ||
fa6bb85a MC |
164 | EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size() and |
165 | EVP_MD_CTX_block_size() return the digest or block size in bytes. | |
3cbe1980 | 166 | |
3f2b5a88 DSH |
167 | EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(), |
168 | EVP_dss1(), EVP_mdc2() and EVP_ripemd160() return pointers to the | |
169 | corresponding EVP_MD structures. | |
3cbe1980 | 170 | |
4ec19e20 | 171 | EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() |
3cbe1980 DSH |
172 | return either an B<EVP_MD> structure or NULL if an error occurs. |
173 | ||
174 | =head1 NOTES | |
175 | ||
176 | The B<EVP> interface to message digests should almost always be used in | |
177 | preference to the low level interfaces. This is because the code then becomes | |
178 | transparent to the digest used and much more flexible. | |
179 | ||
5a34fcd7 DSH |
180 | New applications should use the SHA2 digest algorithms such as SHA256. |
181 | The other digest algorithms are still in common use. | |
3cbe1980 | 182 | |
e72d734d DSH |
183 | For most applications the B<impl> parameter to EVP_DigestInit_ex() will be |
184 | set to NULL to use the default digest implementation. | |
185 | ||
186 | The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are | |
187 | obsolete but are retained to maintain compatibility with existing code. New | |
188 | applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and | |
189 | EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context | |
190 | instead of initializing and cleaning it up on each call and allow non default | |
191 | implementations of digests to be specified. | |
192 | ||
193 | In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after use | |
194 | memory leaks will occur. | |
13588350 | 195 | |
5a34fcd7 DSH |
196 | Stack allocation of EVP_MD_CTX structures is common, for example: |
197 | ||
198 | EVP_MD_CTX mctx; | |
199 | EVP_MD_CTX_init(&mctx); | |
200 | ||
201 | This will cause binary compatibility issues if the size of EVP_MD_CTX | |
202 | structure changes (this will only happen with a major release of OpenSSL). | |
203 | Applications wishing to avoid this should use EVP_MD_CTX_create() instead: | |
204 | ||
205 | EVP_MD_CTX *mctx; | |
206 | mctx = EVP_MD_CTX_create(); | |
207 | ||
208 | ||
3cbe1980 DSH |
209 | =head1 EXAMPLE |
210 | ||
211 | This example digests the data "Test Message\n" and "Hello World\n", using the | |
212 | digest name passed on the command line. | |
213 | ||
214 | #include <stdio.h> | |
215 | #include <openssl/evp.h> | |
216 | ||
217 | main(int argc, char *argv[]) | |
218 | { | |
5a34fcd7 | 219 | EVP_MD_CTX *mdctx; |
3cbe1980 DSH |
220 | const EVP_MD *md; |
221 | char mess1[] = "Test Message\n"; | |
222 | char mess2[] = "Hello World\n"; | |
223 | unsigned char md_value[EVP_MAX_MD_SIZE]; | |
224 | int md_len, i; | |
225 | ||
226 | OpenSSL_add_all_digests(); | |
227 | ||
228 | if(!argv[1]) { | |
229 | printf("Usage: mdtest digestname\n"); | |
230 | exit(1); | |
231 | } | |
232 | ||
233 | md = EVP_get_digestbyname(argv[1]); | |
234 | ||
235 | if(!md) { | |
236 | printf("Unknown message digest %s\n", argv[1]); | |
237 | exit(1); | |
238 | } | |
239 | ||
5a34fcd7 DSH |
240 | mdctx = EVP_MD_CTX_create(); |
241 | EVP_DigestInit_ex(mdctx, md, NULL); | |
242 | EVP_DigestUpdate(mdctx, mess1, strlen(mess1)); | |
243 | EVP_DigestUpdate(mdctx, mess2, strlen(mess2)); | |
244 | EVP_DigestFinal_ex(mdctx, md_value, &md_len); | |
245 | EVP_MD_CTX_destroy(mdctx); | |
3cbe1980 DSH |
246 | |
247 | printf("Digest is: "); | |
248 | for(i = 0; i < md_len; i++) printf("%02x", md_value[i]); | |
249 | printf("\n"); | |
250 | } | |
251 | ||
3cbe1980 DSH |
252 | =head1 SEE ALSO |
253 | ||
4facdbb5 UM |
254 | L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, |
255 | L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, | |
2edcb4ac | 256 | L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> |
4facdbb5 | 257 | |
3cbe1980 DSH |
258 | =head1 HISTORY |
259 | ||
4facdbb5 UM |
260 | EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() are |
261 | available in all versions of SSLeay and OpenSSL. | |
262 | ||
503f3b1a RL |
263 | EVP_MD_CTX_init(), EVP_MD_CTX_create(), EVP_MD_CTX_copy_ex(), |
264 | EVP_MD_CTX_cleanup(), EVP_MD_CTX_destroy(), EVP_DigestInit_ex() | |
265 | and EVP_DigestFinal_ex() were added in OpenSSL 0.9.7. | |
266 | ||
267 | EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), | |
268 | EVP_dss(), EVP_dss1(), EVP_mdc2() and EVP_ripemd160() were | |
478b50cf | 269 | changed to return truly const EVP_MD * in OpenSSL 0.9.7. |
e72d734d | 270 | |
3fa39ed7 DSH |
271 | The link between digests and signing algorithms was fixed in OpenSSL 1.0 and |
272 | later, so now EVP_sha1() can be used with RSA and DSA, there is no need to | |
273 | use EVP_dss1() any more. | |
274 | ||
275 | OpenSSL 1.0 and later does not include the MD2 digest algorithm in the | |
276 | default configuration due to its security weaknesses. | |
277 | ||
3cbe1980 | 278 | =cut |