]>
Commit | Line | Data |
---|---|---|
3cbe1980 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
25191fff | 5 | EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy_ex, |
a9cf71a3 RL |
6 | EVP_MD_CTX_ctrl, EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, |
7 | EVP_MD_CTX_test_flags, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate, | |
cd8d1456 AP |
8 | EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal, |
9 | EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, | |
10 | EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size, | |
a9cf71a3 RL |
11 | EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_MD_CTX_md_data, |
12 | EVP_md_null, | |
bbda8ce9 | 13 | EVP_get_digestbyname, EVP_get_digestbynid, |
675f4cee PY |
14 | EVP_get_digestbyobj, |
15 | EVP_MD_CTX_set_pkey_ctx - EVP digest routines | |
3cbe1980 DSH |
16 | |
17 | =head1 SYNOPSIS | |
18 | ||
19 | #include <openssl/evp.h> | |
20 | ||
25191fff RL |
21 | EVP_MD_CTX *EVP_MD_CTX_new(void); |
22 | int EVP_MD_CTX_reset(EVP_MD_CTX *ctx); | |
23 | void EVP_MD_CTX_free(EVP_MD_CTX *ctx); | |
52ad5b60 | 24 | void EVP_MD_CTX_ctrl(EVP_MD_CTX *ctx, int cmd, int p1, void* p2); |
a9cf71a3 RL |
25 | void EVP_MD_CTX_set_flags(EVP_MD_CTX *ctx, int flags); |
26 | void EVP_MD_CTX_clear_flags(EVP_MD_CTX *ctx, int flags); | |
27 | int EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, int flags); | |
e72d734d DSH |
28 | |
29 | int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); | |
109d3123 | 30 | int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); |
e9b77246 | 31 | int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s); |
cd8d1456 | 32 | int EVP_DigestFinalXOF(EVP_MD_CTX *ctx, unsigned char *md, size_t len); |
e72d734d | 33 | |
aebb9aac | 34 | int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in); |
e72d734d DSH |
35 | |
36 | int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); | |
e9b77246 | 37 | int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s); |
3cbe1980 | 38 | |
aebb9aac | 39 | int EVP_MD_CTX_copy(EVP_MD_CTX *out, EVP_MD_CTX *in); |
e72d734d | 40 | |
5a34fcd7 | 41 | int EVP_MD_type(const EVP_MD *md); |
05ea606a | 42 | int EVP_MD_pkey_type(const EVP_MD *md); |
5a34fcd7 DSH |
43 | int EVP_MD_size(const EVP_MD *md); |
44 | int EVP_MD_block_size(const EVP_MD *md); | |
3cbe1980 | 45 | |
5a34fcd7 | 46 | const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx); |
25191fff RL |
47 | int EVP_MD_CTX_size(const EVP_MD *ctx); |
48 | int EVP_MD_CTX_block_size(const EVP_MD *ctx); | |
49 | int EVP_MD_CTX_type(const EVP_MD *ctx); | |
a9cf71a3 | 50 | void *EVP_MD_CTX_md_data(const EVP_MD_CTX *ctx); |
3cbe1980 | 51 | |
13588350 | 52 | const EVP_MD *EVP_md_null(void); |
e4adad92 | 53 | |
3cbe1980 | 54 | const EVP_MD *EVP_get_digestbyname(const char *name); |
25191fff RL |
55 | const EVP_MD *EVP_get_digestbynid(int type); |
56 | const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o); | |
3cbe1980 | 57 | |
675f4cee PY |
58 | void EVP_MD_CTX_set_pkey_ctx(EVP_MD_CTX *ctx, EVP_PKEY_CTX *pctx); |
59 | ||
3cbe1980 DSH |
60 | =head1 DESCRIPTION |
61 | ||
c7497f34 RS |
62 | The EVP digest routines are a high level interface to message digests, |
63 | and should be used instead of the cipher-specific functions. | |
3cbe1980 | 64 | |
bbda8ce9 | 65 | =over 4 |
25191fff | 66 | |
bbda8ce9 | 67 | =item EVP_MD_CTX_new() |
e72d734d | 68 | |
b45497c3 | 69 | Allocates and returns a digest context. |
e72d734d | 70 | |
bbda8ce9 | 71 | =item EVP_MD_CTX_reset() |
52ad5b60 | 72 | |
bbda8ce9 RT |
73 | Resets the digest context B<ctx>. This can be used to reuse an already |
74 | existing context. | |
3cbe1980 | 75 | |
bbda8ce9 | 76 | =item EVP_MD_CTX_free() |
3cbe1980 | 77 | |
bbda8ce9 | 78 | Cleans up digest context B<ctx> and frees up the space allocated to it. |
3cbe1980 | 79 | |
bbda8ce9 RT |
80 | =item EVP_MD_CTX_ctrl() |
81 | ||
82 | Performs digest-specific control actions on context B<ctx>. | |
83 | ||
a9cf71a3 RL |
84 | =item EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), EVP_MD_CTX_test_flags() |
85 | ||
86 | Sets, clears and tests B<ctx> flags. See L</FLAGS> below for more information. | |
87 | ||
bbda8ce9 RT |
88 | =item EVP_DigestInit_ex() |
89 | ||
90 | Sets up digest context B<ctx> to use a digest B<type> from ENGINE B<impl>. | |
b45497c3 P |
91 | B<type> will typically be supplied by a function such as EVP_sha1(). If |
92 | B<impl> is NULL then the default implementation of digest B<type> is used. | |
bbda8ce9 RT |
93 | |
94 | =item EVP_DigestUpdate() | |
95 | ||
96 | Hashes B<cnt> bytes of data at B<d> into the digest context B<ctx>. This | |
97 | function can be called several times on the same B<ctx> to hash additional | |
98 | data. | |
99 | ||
100 | =item EVP_DigestFinal_ex() | |
101 | ||
102 | Retrieves the digest value from B<ctx> and places it in B<md>. If the B<s> | |
103 | parameter is not NULL then the number of bytes of data written (i.e. the | |
104 | length of the digest) will be written to the integer at B<s>, at most | |
105 | B<EVP_MAX_MD_SIZE> bytes will be written. After calling EVP_DigestFinal_ex() | |
cd8d1456 | 106 | no additional calls to EVP_DigestUpdate() can be made, but |
bbda8ce9 RT |
107 | EVP_DigestInit_ex() can be called to initialize a new digest operation. |
108 | ||
109 | =item EVP_DigestFinalXOF() | |
110 | ||
111 | Interfaces to extendable-output functions, XOFs, such as SHAKE128 and SHAKE256. | |
112 | It retrieves the digest value from B<ctx> and places it in B<len>-sized <B>md. | |
113 | After calling this function no additional calls to EVP_DigestUpdate() can be | |
114 | made, but EVP_DigestInit_ex() can be called to initialize a new operation. | |
115 | ||
116 | =item EVP_MD_CTX_copy_ex() | |
117 | ||
118 | Can be used to copy the message digest state from B<in> to B<out>. This is | |
119 | useful if large amounts of data are to be hashed which only differ in the last | |
b45497c3 | 120 | few bytes. |
bbda8ce9 RT |
121 | |
122 | =item EVP_DigestInit() | |
123 | ||
b45497c3 P |
124 | Behaves in the same way as EVP_DigestInit_ex() except it always uses the |
125 | default digest implementation. | |
bbda8ce9 RT |
126 | |
127 | =item EVP_DigestFinal() | |
128 | ||
129 | Similar to EVP_DigestFinal_ex() except the digest context B<ctx> is | |
130 | automatically cleaned up. | |
131 | ||
132 | =item EVP_MD_CTX_copy() | |
cd8d1456 | 133 | |
bbda8ce9 RT |
134 | Similar to EVP_MD_CTX_copy_ex() except the destination B<out> does not have to |
135 | be initialized. | |
e72d734d | 136 | |
bbda8ce9 RT |
137 | =item EVP_MD_size(), |
138 | EVP_MD_CTX_size() | |
e72d734d | 139 | |
bbda8ce9 RT |
140 | Return the size of the message digest when passed an B<EVP_MD> or an |
141 | B<EVP_MD_CTX> structure, i.e. the size of the hash. | |
e72d734d | 142 | |
bbda8ce9 RT |
143 | =item EVP_MD_block_size(), |
144 | EVP_MD_CTX_block_size() | |
3cbe1980 | 145 | |
bbda8ce9 RT |
146 | Return the block size of the message digest when passed an B<EVP_MD> or an |
147 | B<EVP_MD_CTX> structure. | |
3cbe1980 | 148 | |
bbda8ce9 RT |
149 | =item EVP_MD_type(), |
150 | EVP_MD_CTX_type() | |
3cbe1980 | 151 | |
bbda8ce9 RT |
152 | Return the NID of the OBJECT IDENTIFIER representing the given message digest |
153 | when passed an B<EVP_MD> structure. For example, C<EVP_MD_type(EVP_sha1())> | |
154 | returns B<NID_sha1>. This function is normally used when setting ASN1 OIDs. | |
3cbe1980 | 155 | |
a9cf71a3 RL |
156 | =item EVP_MD_CTX_md_data() |
157 | ||
158 | Return the digest method private data for the passed B<EVP_MD_CTX>. | |
159 | The space is allocated by OpenSSL and has the size originally set with | |
160 | EVP_MD_meth_set_app_datasize(). | |
161 | ||
bbda8ce9 | 162 | =item EVP_MD_CTX_md() |
3cbe1980 | 163 | |
bbda8ce9 | 164 | Returns the B<EVP_MD> structure corresponding to the passed B<EVP_MD_CTX>. |
3cbe1980 | 165 | |
bbda8ce9 | 166 | =item EVP_MD_pkey_type() |
3cbe1980 | 167 | |
bbda8ce9 RT |
168 | Returns the NID of the public key signing algorithm associated with this |
169 | digest. For example EVP_sha1() is associated with RSA so this will return | |
170 | B<NID_sha1WithRSAEncryption>. Since digests and signature algorithms are no | |
171 | longer linked this function is only retained for compatibility reasons. | |
3cbe1980 | 172 | |
bbda8ce9 RT |
173 | =item EVP_md_null() |
174 | ||
175 | A "null" message digest that does nothing: i.e. the hash it returns is of zero | |
176 | length. | |
177 | ||
178 | =item EVP_get_digestbyname(), | |
179 | EVP_get_digestbynid(), | |
180 | EVP_get_digestbyobj() | |
181 | ||
182 | Returns an B<EVP_MD> structure when passed a digest name, a digest B<NID> or an | |
183 | B<ASN1_OBJECT> structure respectively. | |
184 | ||
675f4cee PY |
185 | =item EVP_MD_CTX_set_pkey_ctx() |
186 | ||
187 | Assigns an B<EVP_PKEY_CTX> to B<EVP_MD_CTX>. This is usually used to provide | |
188 | a customzied B<EVP_PKEY_CTX> to L<EVP_DigestSignInit(3)> or | |
189 | L<EVP_DigestVerifyInit(3)>. The B<EVP_PKEY_CTX> passed to this function should | |
190 | be freed by the caller. | |
191 | ||
bbda8ce9 | 192 | =back |
3cbe1980 | 193 | |
a9cf71a3 RL |
194 | =head1 FLAGS |
195 | ||
196 | EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags() and EVP_MD_CTX_test_flags() | |
197 | can be used the manipulate and test these B<EVP_MD_CTX> flags: | |
198 | ||
199 | =over 4 | |
200 | ||
201 | =item EVP_MD_CTX_FLAG_ONESHOT | |
202 | ||
203 | This flag instructs the digest to optimize for one update only, if possible. | |
204 | ||
205 | =for comment EVP_MD_CTX_FLAG_CLEANED is internal, don't mention it | |
206 | ||
207 | =for comment EVP_MD_CTX_FLAG_REUSE is internal, don't mention it | |
208 | ||
209 | =for comment We currently avoid documenting flags that are only bit holder: | |
210 | EVP_MD_CTX_FLAG_NON_FIPS_ALLOW, EVP_MD_CTX_FLAGS_PAD_* | |
211 | ||
212 | =item EVP_MD_CTX_FLAG_NO_INIT | |
213 | ||
214 | This flag instructs EVP_DigestInit() and similar not to initialise the | |
215 | implementation specific data. | |
216 | ||
217 | =item EVP_MD_CTX_FLAG_FINALISE | |
218 | ||
219 | Some functions such as EVP_DigestSign only finalise copies of internal | |
220 | contexts so additional data can be included after the finalisation call. | |
221 | This is inefficient if this functionality is not required, and can be | |
222 | disabled with this flag. | |
223 | ||
224 | =back | |
225 | ||
3cbe1980 DSH |
226 | =head1 RETURN VALUES |
227 | ||
bbda8ce9 RT |
228 | =over 4 |
229 | ||
230 | =item EVP_DigestInit_ex(), | |
231 | EVP_DigestUpdate(), | |
232 | EVP_DigestFinal_ex() | |
233 | ||
234 | Returns 1 for | |
13588350 | 235 | success and 0 for failure. |
3cbe1980 | 236 | |
bbda8ce9 RT |
237 | =item EVP_MD_CTX_ctrl() |
238 | ||
239 | Returns 1 if successful or 0 for failure. | |
240 | ||
241 | =item EVP_MD_CTX_copy_ex() | |
52ad5b60 | 242 | |
bbda8ce9 | 243 | Returns 1 if successful or 0 for failure. |
3cbe1980 | 244 | |
bbda8ce9 RT |
245 | =item EVP_MD_type(), |
246 | EVP_MD_pkey_type(), | |
247 | EVP_MD_type() | |
3cbe1980 | 248 | |
bbda8ce9 RT |
249 | Returns the NID of the corresponding OBJECT IDENTIFIER or NID_undef if none |
250 | exists. | |
3cbe1980 | 251 | |
bbda8ce9 RT |
252 | =item EVP_MD_size(), |
253 | EVP_MD_block_size(), | |
254 | EVP_MD_CTX_size(), | |
255 | EVP_MD_CTX_block_size() | |
3cbe1980 | 256 | |
bbda8ce9 RT |
257 | Returns the digest or block size in bytes. |
258 | ||
259 | =item EVP_md_null() | |
260 | ||
261 | Returns a pointer to the B<EVP_MD> structure of the "null" message digest. | |
262 | ||
263 | =item EVP_get_digestbyname(), | |
264 | EVP_get_digestbynid(), | |
265 | EVP_get_digestbyobj() | |
266 | ||
267 | Returns either an B<EVP_MD> structure or NULL if an error occurs. | |
268 | ||
675f4cee PY |
269 | =item EVP_MD_CTX_set_pkey_ctx() |
270 | ||
271 | This function has no return value. | |
272 | ||
bbda8ce9 | 273 | =back |
3cbe1980 DSH |
274 | |
275 | =head1 NOTES | |
276 | ||
277 | The B<EVP> interface to message digests should almost always be used in | |
278 | preference to the low level interfaces. This is because the code then becomes | |
279 | transparent to the digest used and much more flexible. | |
280 | ||
bbda8ce9 | 281 | New applications should use the SHA-2 (such as L<EVP_sha256(3)>) or the SHA-3 |
89f66fe2 | 282 | digest algorithms (such as L<EVP_sha3_512(3)>). The other digest algorithms |
283 | are still in common use. | |
3cbe1980 | 284 | |
e72d734d DSH |
285 | For most applications the B<impl> parameter to EVP_DigestInit_ex() will be |
286 | set to NULL to use the default digest implementation. | |
287 | ||
7b3e11c5 | 288 | The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are |
e72d734d | 289 | obsolete but are retained to maintain compatibility with existing code. New |
7b3e11c5 | 290 | applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and |
e72d734d DSH |
291 | EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context |
292 | instead of initializing and cleaning it up on each call and allow non default | |
293 | implementations of digests to be specified. | |
294 | ||
fa332bba | 295 | If digest contexts are not cleaned up after use, |
7b3e11c5 | 296 | memory leaks will occur. |
13588350 | 297 | |
25191fff RL |
298 | EVP_MD_CTX_size(), EVP_MD_CTX_block_size(), EVP_MD_CTX_type(), |
299 | EVP_get_digestbynid() and EVP_get_digestbyobj() are defined as | |
300 | macros. | |
5a34fcd7 | 301 | |
52ad5b60 TS |
302 | EVP_MD_CTX_ctrl() sends commands to message digests for additional configuration |
303 | or control. | |
5a34fcd7 | 304 | |
3cbe1980 DSH |
305 | =head1 EXAMPLE |
306 | ||
307 | This example digests the data "Test Message\n" and "Hello World\n", using the | |
308 | digest name passed on the command line. | |
309 | ||
310 | #include <stdio.h> | |
311 | #include <openssl/evp.h> | |
312 | ||
313 | main(int argc, char *argv[]) | |
314 | { | |
2947af32 BB |
315 | EVP_MD_CTX *mdctx; |
316 | const EVP_MD *md; | |
317 | char mess1[] = "Test Message\n"; | |
318 | char mess2[] = "Hello World\n"; | |
319 | unsigned char md_value[EVP_MAX_MD_SIZE]; | |
320 | int md_len, i; | |
321 | ||
322 | if (argv[1] == NULL) { | |
323 | printf("Usage: mdtest digestname\n"); | |
324 | exit(1); | |
325 | } | |
326 | ||
327 | md = EVP_get_digestbyname(argv[1]); | |
328 | if (md == NULL) { | |
329 | printf("Unknown message digest %s\n", argv[1]); | |
330 | exit(1); | |
331 | } | |
332 | ||
333 | mdctx = EVP_MD_CTX_new(); | |
334 | EVP_DigestInit_ex(mdctx, md, NULL); | |
335 | EVP_DigestUpdate(mdctx, mess1, strlen(mess1)); | |
336 | EVP_DigestUpdate(mdctx, mess2, strlen(mess2)); | |
337 | EVP_DigestFinal_ex(mdctx, md_value, &md_len); | |
338 | EVP_MD_CTX_free(mdctx); | |
339 | ||
340 | printf("Digest is: "); | |
341 | for (i = 0; i < md_len; i++) | |
342 | printf("%02x", md_value[i]); | |
343 | printf("\n"); | |
344 | ||
345 | exit(0); | |
3cbe1980 DSH |
346 | } |
347 | ||
3cbe1980 DSH |
348 | =head1 SEE ALSO |
349 | ||
9b86974e | 350 | L<dgst(1)>, |
b97fdb57 | 351 | L<evp(7)> |
4facdbb5 | 352 | |
bbda8ce9 RT |
353 | The full list of digest algorithms are provided below. |
354 | ||
355 | L<EVP_blake2b512(3)>, | |
356 | L<EVP_md2(3)>, | |
357 | L<EVP_md4(3)>, | |
358 | L<EVP_md5(3)>, | |
359 | L<EVP_mdc2(3)>, | |
360 | L<EVP_ripemd160(3)>, | |
361 | L<EVP_sha1(3)>, | |
362 | L<EVP_sha224(3)>, | |
363 | L<EVP_sha3_224(3)>, | |
67e247fa | 364 | L<EVP_sm3(3)>, |
bbda8ce9 RT |
365 | L<EVP_whirlpool(3)> |
366 | ||
3cbe1980 DSH |
367 | =head1 HISTORY |
368 | ||
25191fff | 369 | EVP_MD_CTX_create() and EVP_MD_CTX_destroy() were renamed to |
a95d7574 | 370 | EVP_MD_CTX_new() and EVP_MD_CTX_free() in OpenSSL 1.1.0. |
25191fff | 371 | |
3fa39ed7 | 372 | The link between digests and signing algorithms was fixed in OpenSSL 1.0 and |
a95d7574 RS |
373 | later, so now EVP_sha1() can be used with RSA and DSA. |
374 | ||
bbda8ce9 | 375 | EVP_dss1() was removed in OpenSSL 1.1.0. |
3fa39ed7 | 376 | |
675f4cee PY |
377 | EVP_MD_CTX_set_pkey_ctx() is added in 1.1.1. |
378 | ||
e2f92610 RS |
379 | =head1 COPYRIGHT |
380 | ||
0d664759 | 381 | Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
382 | |
383 | Licensed under the OpenSSL license (the "License"). You may not use | |
384 | this file except in compliance with the License. You can obtain a copy | |
385 | in the file LICENSE in the source distribution or at | |
386 | L<https://www.openssl.org/source/license.html>. | |
387 | ||
388 | =cut |