]>
Commit | Line | Data |
---|---|---|
3cbe1980 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
3fd70262 | 5 | EVP_MD_fetch, EVP_MD_up_ref, EVP_MD_free, |
ae3ff60e | 6 | EVP_MD_get_params, EVP_MD_gettable_params, |
37842dfa | 7 | EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy, |
ae3ff60e RL |
8 | EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl, |
9 | EVP_MD_CTX_set_params, EVP_MD_CTX_get_params, | |
e6879a31 | 10 | EVP_MD_settable_ctx_params, EVP_MD_gettable_ctx_params, |
ae3ff60e | 11 | EVP_MD_CTX_settable_params, EVP_MD_CTX_gettable_params, |
d5e5e2ff | 12 | EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags, |
37842dfa | 13 | EVP_Digest, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate, |
cd8d1456 | 14 | EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal, |
f651c727 | 15 | EVP_MD_is_a, EVP_MD_name, EVP_MD_names_do_all, EVP_MD_provider, |
37842dfa | 16 | EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_flags, |
c750bc08 | 17 | EVP_MD_CTX_name, |
37842dfa AS |
18 | EVP_MD_CTX_md, EVP_MD_CTX_type, EVP_MD_CTX_size, EVP_MD_CTX_block_size, |
19 | EVP_MD_CTX_md_data, EVP_MD_CTX_update_fn, EVP_MD_CTX_set_update_fn, | |
a9cf71a3 | 20 | EVP_md_null, |
37842dfa | 21 | EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj, |
c540f00f | 22 | EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx, |
251e610c | 23 | EVP_MD_do_all_provided |
c540f00f | 24 | - EVP digest routines |
3cbe1980 DSH |
25 | |
26 | =head1 SYNOPSIS | |
27 | ||
28 | #include <openssl/evp.h> | |
29 | ||
2cafb1df RL |
30 | EVP_MD *EVP_MD_fetch(OPENSSL_CTX *ctx, const char *algorithm, |
31 | const char *properties); | |
3fd70262 RL |
32 | int EVP_MD_up_ref(EVP_MD *md); |
33 | void EVP_MD_free(EVP_MD *md); | |
ae3ff60e RL |
34 | int EVP_MD_get_params(const EVP_MD *digest, OSSL_PARAM params[]); |
35 | const OSSL_PARAM *EVP_MD_gettable_params(const EVP_MD *digest); | |
25191fff RL |
36 | EVP_MD_CTX *EVP_MD_CTX_new(void); |
37 | int EVP_MD_CTX_reset(EVP_MD_CTX *ctx); | |
38 | void EVP_MD_CTX_free(EVP_MD_CTX *ctx); | |
52ad5b60 | 39 | void EVP_MD_CTX_ctrl(EVP_MD_CTX *ctx, int cmd, int p1, void* p2); |
4e7991b4 | 40 | int EVP_MD_CTX_get_params(EVP_MD_CTX *ctx, OSSL_PARAM params[]); |
d5e5e2ff | 41 | int EVP_MD_CTX_set_params(EVP_MD_CTX *ctx, const OSSL_PARAM params[]); |
e6879a31 MC |
42 | const OSSL_PARAM *EVP_MD_settable_ctx_params(const EVP_MD *md); |
43 | const OSSL_PARAM *EVP_MD_gettable_ctx_params(const EVP_MD *md); | |
44 | const OSSL_PARAM *EVP_MD_CTX_settable_params(EVP_MD_CTX *ctx); | |
45 | const OSSL_PARAM *EVP_MD_CTX_gettable_params(EVP_MD_CTX *ctx); | |
a9cf71a3 RL |
46 | void EVP_MD_CTX_set_flags(EVP_MD_CTX *ctx, int flags); |
47 | void EVP_MD_CTX_clear_flags(EVP_MD_CTX *ctx, int flags); | |
48 | int EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, int flags); | |
e72d734d | 49 | |
37842dfa AS |
50 | int EVP_Digest(const void *data, size_t count, unsigned char *md, |
51 | unsigned int *size, const EVP_MD *type, ENGINE *impl); | |
e72d734d | 52 | int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); |
109d3123 | 53 | int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); |
e9b77246 | 54 | int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s); |
cd8d1456 | 55 | int EVP_DigestFinalXOF(EVP_MD_CTX *ctx, unsigned char *md, size_t len); |
e72d734d | 56 | |
aebb9aac | 57 | int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in); |
e72d734d DSH |
58 | |
59 | int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); | |
e9b77246 | 60 | int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s); |
3cbe1980 | 61 | |
aebb9aac | 62 | int EVP_MD_CTX_copy(EVP_MD_CTX *out, EVP_MD_CTX *in); |
e72d734d | 63 | |
c750bc08 | 64 | const char *EVP_MD_name(const EVP_MD *md); |
251e610c | 65 | int EVP_MD_is_a(const EVP_MD *md, const char *name); |
f651c727 RL |
66 | void EVP_MD_names_do_all(const EVP_MD *md, |
67 | void (*fn)(const char *name, void *data), | |
68 | void *data); | |
1d2622d4 | 69 | const OSSL_PROVIDER *EVP_MD_provider(const EVP_MD *md); |
5a34fcd7 | 70 | int EVP_MD_type(const EVP_MD *md); |
05ea606a | 71 | int EVP_MD_pkey_type(const EVP_MD *md); |
5a34fcd7 DSH |
72 | int EVP_MD_size(const EVP_MD *md); |
73 | int EVP_MD_block_size(const EVP_MD *md); | |
37842dfa | 74 | unsigned long EVP_MD_flags(const EVP_MD *md); |
3cbe1980 | 75 | |
5a34fcd7 | 76 | const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx); |
c750bc08 | 77 | const char *EVP_MD_CTX_name(const EVP_MD_CTX *ctx); |
7c2a981f RL |
78 | int EVP_MD_CTX_size(const EVP_MD_CTX *ctx); |
79 | int EVP_MD_CTX_block_size(const EVP_MD_CTX *ctx); | |
80 | int EVP_MD_CTX_type(const EVP_MD_CTX *ctx); | |
a9cf71a3 | 81 | void *EVP_MD_CTX_md_data(const EVP_MD_CTX *ctx); |
37842dfa AS |
82 | int (*EVP_MD_CTX_update_fn(EVP_MD_CTX *ctx))(EVP_MD_CTX *ctx, |
83 | const void *data, size_t count); | |
84 | void EVP_MD_CTX_set_update_fn(EVP_MD_CTX *ctx, | |
85 | int (*update)(EVP_MD_CTX *ctx, | |
86 | const void *data, size_t count)); | |
3cbe1980 | 87 | |
13588350 | 88 | const EVP_MD *EVP_md_null(void); |
e4adad92 | 89 | |
3cbe1980 | 90 | const EVP_MD *EVP_get_digestbyname(const char *name); |
25191fff RL |
91 | const EVP_MD *EVP_get_digestbynid(int type); |
92 | const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o); | |
3cbe1980 | 93 | |
37842dfa | 94 | EVP_PKEY_CTX *EVP_MD_CTX_pkey_ctx(const EVP_MD_CTX *ctx); |
675f4cee PY |
95 | void EVP_MD_CTX_set_pkey_ctx(EVP_MD_CTX *ctx, EVP_PKEY_CTX *pctx); |
96 | ||
251e610c RL |
97 | void EVP_MD_do_all_provided(OPENSSL_CTX *libctx, |
98 | void (*fn)(EVP_MD *mac, void *arg), | |
99 | void *arg); | |
c540f00f | 100 | |
3cbe1980 DSH |
101 | =head1 DESCRIPTION |
102 | ||
c7497f34 | 103 | The EVP digest routines are a high level interface to message digests, |
3fd70262 RL |
104 | and should be used instead of the digest-specific functions. |
105 | ||
106 | The B<EVP_MD> type is a structure for digest method implementation. | |
3cbe1980 | 107 | |
bbda8ce9 | 108 | =over 4 |
25191fff | 109 | |
2cafb1df RL |
110 | =item EVP_MD_fetch() |
111 | ||
112 | Fetches the digest implementation for the given B<algorithm> from any | |
113 | provider offering it, within the criteria given by the B<properties>. | |
114 | See L<provider(7)/Fetching algorithms> for further information. | |
115 | ||
3fd70262 RL |
116 | The returned value must eventually be freed with EVP_MD_free(). |
117 | ||
118 | Fetched B<EVP_MD> structures are reference counted. | |
119 | ||
120 | =item EVP_MD_up_ref() | |
121 | ||
122 | Increments the reference count for an B<EVP_MD> structure. | |
123 | ||
124 | =item EVP_MD_free() | |
125 | ||
126 | Decrements the reference count for the fetched B<EVP_MD> structure. | |
127 | If the reference count drops to 0 then the structure is freed. | |
2cafb1df | 128 | |
bbda8ce9 | 129 | =item EVP_MD_CTX_new() |
e72d734d | 130 | |
b45497c3 | 131 | Allocates and returns a digest context. |
e72d734d | 132 | |
bbda8ce9 | 133 | =item EVP_MD_CTX_reset() |
52ad5b60 | 134 | |
bbda8ce9 RT |
135 | Resets the digest context B<ctx>. This can be used to reuse an already |
136 | existing context. | |
3cbe1980 | 137 | |
bbda8ce9 | 138 | =item EVP_MD_CTX_free() |
3cbe1980 | 139 | |
bbda8ce9 | 140 | Cleans up digest context B<ctx> and frees up the space allocated to it. |
3cbe1980 | 141 | |
bbda8ce9 RT |
142 | =item EVP_MD_CTX_ctrl() |
143 | ||
83b4a243 | 144 | This is a legacy method. EVP_MD_CTX_set_params() and EVP_MD_CTX_get_params() |
d5e5e2ff SL |
145 | is the mechanism that should be used to set and get parameters that are used by |
146 | providers. | |
37842dfa AS |
147 | Performs digest-specific control actions on context B<ctx>. The control command |
148 | is indicated in B<cmd> and any additional arguments in B<p1> and B<p2>. | |
149 | EVP_MD_CTX_ctrl() must be called after EVP_DigestInit_ex(). Other restrictions | |
150 | may apply depending on the control type and digest implementation. | |
151 | See L</CONTROLS> below for more information. | |
bbda8ce9 | 152 | |
ae3ff60e RL |
153 | =item EVP_MD_get_params() |
154 | ||
155 | Retrieves the requested list of B<params> from a MD B<md>. | |
2710e8a8 | 156 | See L</PARAMETERS> below for more information. |
ae3ff60e RL |
157 | |
158 | =item EVP_MD_CTX_get_params() | |
d5e5e2ff SL |
159 | |
160 | Retrieves the requested list of B<params> from a MD context B<ctx>. | |
2710e8a8 | 161 | See L</PARAMETERS> below for more information. |
d5e5e2ff | 162 | |
ae3ff60e | 163 | =item EVP_MD_CTX_set_params() |
d5e5e2ff | 164 | |
ae3ff60e | 165 | Sets the list of B<params> into a MD context B<ctx>. |
2710e8a8 | 166 | See L</PARAMETERS> below for more information. |
d5e5e2ff | 167 | |
e6879a31 MC |
168 | =item EVP_MD_gettable_params(), EVP_MD_gettable_ctx_params(), |
169 | EVP_MD_settable_ctx_params(), EVP_MD_CTX_gettable_params(), | |
ae3ff60e RL |
170 | EVP_MD_CTX_settable_params() |
171 | ||
172 | Get a B<OSSL_PARAM> array that describes the retrievable and settable | |
e6879a31 MC |
173 | parameters. EVP_MD_gettable_params() returns parameters that can be used with |
174 | EVP_MD_get_params(). EVP_MD_gettable_ctx_params() and | |
175 | EVP_MD_CTX_gettable_params() return parameters that can be used with | |
176 | EVP_MD_CTX_get_params(). EVP_MD_settable_ctx_params() and | |
177 | EVP_MD_CTX_settable_params() return parameters that can be used with | |
178 | EVP_MD_CTX_set_params(). | |
ae3ff60e RL |
179 | See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. |
180 | ||
a9cf71a3 RL |
181 | =item EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), EVP_MD_CTX_test_flags() |
182 | ||
183 | Sets, clears and tests B<ctx> flags. See L</FLAGS> below for more information. | |
184 | ||
37842dfa AS |
185 | =item EVP_Digest() |
186 | ||
187 | A wrapper around the Digest Init_ex, Update and Final_ex functions. | |
188 | Hashes B<count> bytes of data at B<data> using a digest B<type> from ENGINE | |
189 | B<impl>. The digest value is placed in B<md> and its length is written at B<size> | |
190 | if the pointer is not NULL. At most B<EVP_MAX_MD_SIZE> bytes will be written. | |
191 | If B<impl> is NULL the default implementation of digest B<type> is used. | |
192 | ||
bbda8ce9 RT |
193 | =item EVP_DigestInit_ex() |
194 | ||
2cafb1df RL |
195 | Sets up digest context B<ctx> to use a digest B<type>. |
196 | B<type> is typically supplied by a function such as EVP_sha1(), or a | |
197 | value explicitly fetched with EVP_MD_fetch(). | |
198 | ||
199 | If B<impl> is non-NULL, its implementation of the digest B<type> is used if | |
200 | there is one, and if not, the default implementation is used. | |
bbda8ce9 RT |
201 | |
202 | =item EVP_DigestUpdate() | |
203 | ||
204 | Hashes B<cnt> bytes of data at B<d> into the digest context B<ctx>. This | |
205 | function can be called several times on the same B<ctx> to hash additional | |
206 | data. | |
207 | ||
208 | =item EVP_DigestFinal_ex() | |
209 | ||
210 | Retrieves the digest value from B<ctx> and places it in B<md>. If the B<s> | |
211 | parameter is not NULL then the number of bytes of data written (i.e. the | |
212 | length of the digest) will be written to the integer at B<s>, at most | |
213 | B<EVP_MAX_MD_SIZE> bytes will be written. After calling EVP_DigestFinal_ex() | |
cd8d1456 | 214 | no additional calls to EVP_DigestUpdate() can be made, but |
bbda8ce9 RT |
215 | EVP_DigestInit_ex() can be called to initialize a new digest operation. |
216 | ||
217 | =item EVP_DigestFinalXOF() | |
218 | ||
219 | Interfaces to extendable-output functions, XOFs, such as SHAKE128 and SHAKE256. | |
220 | It retrieves the digest value from B<ctx> and places it in B<len>-sized <B>md. | |
221 | After calling this function no additional calls to EVP_DigestUpdate() can be | |
222 | made, but EVP_DigestInit_ex() can be called to initialize a new operation. | |
223 | ||
224 | =item EVP_MD_CTX_copy_ex() | |
225 | ||
226 | Can be used to copy the message digest state from B<in> to B<out>. This is | |
227 | useful if large amounts of data are to be hashed which only differ in the last | |
b45497c3 | 228 | few bytes. |
bbda8ce9 RT |
229 | |
230 | =item EVP_DigestInit() | |
231 | ||
b45497c3 | 232 | Behaves in the same way as EVP_DigestInit_ex() except it always uses the |
091aab66 | 233 | default digest implementation and calls EVP_MD_CTX_reset(). |
bbda8ce9 RT |
234 | |
235 | =item EVP_DigestFinal() | |
236 | ||
237 | Similar to EVP_DigestFinal_ex() except the digest context B<ctx> is | |
238 | automatically cleaned up. | |
239 | ||
240 | =item EVP_MD_CTX_copy() | |
cd8d1456 | 241 | |
bbda8ce9 RT |
242 | Similar to EVP_MD_CTX_copy_ex() except the destination B<out> does not have to |
243 | be initialized. | |
e72d734d | 244 | |
251e610c RL |
245 | =item EVP_MD_is_a() |
246 | ||
247 | Returns 1 if I<md> is an implementation of an algorithm that's | |
248 | identifiable with I<name>, otherwise 0. | |
249 | ||
c750bc08 RL |
250 | =item EVP_MD_name(), |
251 | EVP_MD_CTX_name() | |
252 | ||
251e610c | 253 | Return the name of the given message digest. For fetched message |
f651c727 RL |
254 | digests with multiple names, only one of them is returned; it's |
255 | recommended to use EVP_MD_names_do_all() instead. | |
256 | ||
257 | =item EVP_MD_names_do_all() | |
258 | ||
259 | Traverses all names for the I<md>, and calls I<fn> with each name and | |
260 | I<data>. This is only useful with fetched B<EVP_MD>s. | |
c750bc08 | 261 | |
1d2622d4 RL |
262 | =item EVP_MD_provider() |
263 | ||
264 | Returns an B<OSSL_PROVIDER> pointer to the provider that implements the given | |
265 | B<EVP_MD>. | |
266 | ||
bbda8ce9 RT |
267 | =item EVP_MD_size(), |
268 | EVP_MD_CTX_size() | |
e72d734d | 269 | |
bbda8ce9 RT |
270 | Return the size of the message digest when passed an B<EVP_MD> or an |
271 | B<EVP_MD_CTX> structure, i.e. the size of the hash. | |
e72d734d | 272 | |
bbda8ce9 RT |
273 | =item EVP_MD_block_size(), |
274 | EVP_MD_CTX_block_size() | |
3cbe1980 | 275 | |
bbda8ce9 RT |
276 | Return the block size of the message digest when passed an B<EVP_MD> or an |
277 | B<EVP_MD_CTX> structure. | |
3cbe1980 | 278 | |
bbda8ce9 RT |
279 | =item EVP_MD_type(), |
280 | EVP_MD_CTX_type() | |
3cbe1980 | 281 | |
bbda8ce9 RT |
282 | Return the NID of the OBJECT IDENTIFIER representing the given message digest |
283 | when passed an B<EVP_MD> structure. For example, C<EVP_MD_type(EVP_sha1())> | |
284 | returns B<NID_sha1>. This function is normally used when setting ASN1 OIDs. | |
3cbe1980 | 285 | |
a9cf71a3 RL |
286 | =item EVP_MD_CTX_md_data() |
287 | ||
288 | Return the digest method private data for the passed B<EVP_MD_CTX>. | |
289 | The space is allocated by OpenSSL and has the size originally set with | |
290 | EVP_MD_meth_set_app_datasize(). | |
291 | ||
bbda8ce9 | 292 | =item EVP_MD_CTX_md() |
3cbe1980 | 293 | |
b7c913c8 MC |
294 | Returns the B<EVP_MD> structure corresponding to the passed B<EVP_MD_CTX>. This |
295 | will be the same B<EVP_MD> object originally passed to EVP_DigestInit_ex() (or | |
296 | other similar function) when the EVP_MD_CTX was first initialised. Note that | |
297 | where explicit fetch is in use (see L<EVP_MD_fetch(3)>) the value returned from | |
298 | this function will not have its reference count incremented and therefore it | |
299 | should not be used after the EVP_MD_CTX is freed. | |
3cbe1980 | 300 | |
37842dfa AS |
301 | =item EVP_MD_CTX_set_update_fn() |
302 | ||
303 | Sets the update function for B<ctx> to B<update>. | |
304 | This is the function that is called by EVP_DigestUpdate. If not set, the | |
305 | update function from the B<EVP_MD> type specified at initialization is used. | |
306 | ||
307 | =item EVP_MD_CTX_update_fn() | |
308 | ||
309 | Returns the update function for B<ctx>. | |
310 | ||
311 | =item EVP_MD_flags() | |
312 | ||
313 | Returns the B<md> flags. Note that these are different from the B<EVP_MD_CTX> | |
314 | ones. See L<EVP_MD_meth_set_flags(3)> for more information. | |
315 | ||
bbda8ce9 | 316 | =item EVP_MD_pkey_type() |
3cbe1980 | 317 | |
bbda8ce9 RT |
318 | Returns the NID of the public key signing algorithm associated with this |
319 | digest. For example EVP_sha1() is associated with RSA so this will return | |
320 | B<NID_sha1WithRSAEncryption>. Since digests and signature algorithms are no | |
321 | longer linked this function is only retained for compatibility reasons. | |
3cbe1980 | 322 | |
bbda8ce9 RT |
323 | =item EVP_md_null() |
324 | ||
325 | A "null" message digest that does nothing: i.e. the hash it returns is of zero | |
326 | length. | |
327 | ||
328 | =item EVP_get_digestbyname(), | |
329 | EVP_get_digestbynid(), | |
330 | EVP_get_digestbyobj() | |
331 | ||
332 | Returns an B<EVP_MD> structure when passed a digest name, a digest B<NID> or an | |
333 | B<ASN1_OBJECT> structure respectively. | |
334 | ||
37842dfa AS |
335 | =item EVP_MD_CTX_pkey_ctx() |
336 | ||
337 | Returns the B<EVP_PKEY_CTX> assigned to B<ctx>. The returned pointer should not | |
338 | be freed by the caller. | |
339 | ||
675f4cee PY |
340 | =item EVP_MD_CTX_set_pkey_ctx() |
341 | ||
342 | Assigns an B<EVP_PKEY_CTX> to B<EVP_MD_CTX>. This is usually used to provide | |
37842dfa | 343 | a customized B<EVP_PKEY_CTX> to L<EVP_DigestSignInit(3)> or |
81c79453 | 344 | L<EVP_DigestVerifyInit(3)>. The B<pctx> passed to this function should be freed |
f922dac8 | 345 | by the caller. A NULL B<pctx> pointer is also allowed to clear the B<EVP_PKEY_CTX> |
81c79453 PY |
346 | assigned to B<ctx>. In such case, freeing the cleared B<EVP_PKEY_CTX> or not |
347 | depends on how the B<EVP_PKEY_CTX> is created. | |
675f4cee | 348 | |
251e610c | 349 | =item EVP_MD_do_all_provided() |
c540f00f RL |
350 | |
351 | Traverses all messages digests implemented by all activated providers | |
352 | in the given library context I<libctx>, and for each of the implementations, | |
353 | calls the given function I<fn> with the implementation method and the given | |
354 | I<arg> as argument. | |
355 | ||
bbda8ce9 | 356 | =back |
3cbe1980 | 357 | |
2710e8a8 | 358 | =head1 PARAMETERS |
d5e5e2ff SL |
359 | |
360 | See L<OSSL_PARAM(3)> for information about passing parameters. | |
361 | ||
362 | EVP_MD_CTX_set_params() can be used with the following OSSL_PARAM keys: | |
363 | ||
364 | =over 4 | |
365 | ||
0c452a51 | 366 | =item "xoflen" (B<OSSL_PARAM_DIGEST_KEY_XOFLEN>) <unsigned integer> |
d5e5e2ff SL |
367 | |
368 | Sets the digest length for extendable output functions. | |
7b6b194b P |
369 | It is used by the SHAKE algorithm and should not exceed what can be given |
370 | using a B<size_t>. | |
d5e5e2ff | 371 | |
0c452a51 | 372 | =item "pad_type" (B<OSSL_PARAM_DIGEST_KEY_PAD_TYPE>) <integer> |
d5e5e2ff SL |
373 | |
374 | Sets the pad type. | |
375 | It is used by the MDC2 algorithm. | |
376 | ||
377 | =back | |
378 | ||
379 | EVP_MD_CTX_get_params() can be used with the following OSSL_PARAM keys: | |
380 | ||
381 | =over 4 | |
382 | ||
0c452a51 | 383 | =item "micalg" (B<OSSL_PARAM_DIGEST_KEY_MICALG>) <UTF8 string>. |
d5e5e2ff SL |
384 | |
385 | Gets the digest Message Integrity Check algorithm string. This is used when | |
386 | creating S/MIME multipart/signed messages, as specified in RFC 3851. | |
387 | It may be used by external engines or providers. | |
388 | ||
389 | =back | |
390 | ||
37842dfa AS |
391 | =head1 CONTROLS |
392 | ||
393 | EVP_MD_CTX_ctrl() can be used to send the following standard controls: | |
394 | ||
395 | =over 4 | |
396 | ||
397 | =item EVP_MD_CTRL_MICALG | |
398 | ||
399 | Gets the digest Message Integrity Check algorithm string. This is used when | |
400 | creating S/MIME multipart/signed messages, as specified in RFC 3851. | |
401 | The string value is written to B<p2>. | |
402 | ||
403 | =item EVP_MD_CTRL_XOF_LEN | |
404 | ||
405 | This control sets the digest length for extendable output functions to B<p1>. | |
406 | Sending this control directly should not be necessary, the use of | |
407 | C<EVP_DigestFinalXOF()> is preferred. | |
408 | Currently used by SHAKE. | |
409 | ||
410 | =back | |
411 | ||
a9cf71a3 RL |
412 | =head1 FLAGS |
413 | ||
414 | EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags() and EVP_MD_CTX_test_flags() | |
415 | can be used the manipulate and test these B<EVP_MD_CTX> flags: | |
416 | ||
417 | =over 4 | |
418 | ||
419 | =item EVP_MD_CTX_FLAG_ONESHOT | |
420 | ||
421 | This flag instructs the digest to optimize for one update only, if possible. | |
422 | ||
423 | =for comment EVP_MD_CTX_FLAG_CLEANED is internal, don't mention it | |
424 | ||
425 | =for comment EVP_MD_CTX_FLAG_REUSE is internal, don't mention it | |
426 | ||
427 | =for comment We currently avoid documenting flags that are only bit holder: | |
428 | EVP_MD_CTX_FLAG_NON_FIPS_ALLOW, EVP_MD_CTX_FLAGS_PAD_* | |
429 | ||
430 | =item EVP_MD_CTX_FLAG_NO_INIT | |
431 | ||
432 | This flag instructs EVP_DigestInit() and similar not to initialise the | |
433 | implementation specific data. | |
434 | ||
435 | =item EVP_MD_CTX_FLAG_FINALISE | |
436 | ||
437 | Some functions such as EVP_DigestSign only finalise copies of internal | |
438 | contexts so additional data can be included after the finalisation call. | |
439 | This is inefficient if this functionality is not required, and can be | |
440 | disabled with this flag. | |
441 | ||
442 | =back | |
443 | ||
3cbe1980 DSH |
444 | =head1 RETURN VALUES |
445 | ||
bbda8ce9 RT |
446 | =over 4 |
447 | ||
2cafb1df RL |
448 | =item EVP_MD_fetch() |
449 | ||
450 | Returns a pointer to a B<EVP_MD> for success or NULL for failure. | |
451 | ||
3fd70262 RL |
452 | =item EVP_MD_up_ref() |
453 | ||
454 | Returns 1 for success or 0 for failure. | |
455 | ||
bbda8ce9 RT |
456 | =item EVP_DigestInit_ex(), |
457 | EVP_DigestUpdate(), | |
458 | EVP_DigestFinal_ex() | |
459 | ||
460 | Returns 1 for | |
13588350 | 461 | success and 0 for failure. |
3cbe1980 | 462 | |
bbda8ce9 RT |
463 | =item EVP_MD_CTX_ctrl() |
464 | ||
465 | Returns 1 if successful or 0 for failure. | |
466 | ||
d5e5e2ff SL |
467 | =item EVP_MD_CTX_set_params(), |
468 | EVP_MD_CTX_get_params() | |
469 | ||
470 | Returns 1 if successful or 0 for failure. | |
471 | ||
ae3ff60e RL |
472 | =item EVP_MD_CTX_settable_params(), |
473 | EVP_MD_CTX_gettable_params() | |
474 | ||
475 | Return an array of constant B<OSSL_PARAM>s, or NULL if there is none | |
476 | to get. | |
477 | ||
bbda8ce9 | 478 | =item EVP_MD_CTX_copy_ex() |
52ad5b60 | 479 | |
bbda8ce9 | 480 | Returns 1 if successful or 0 for failure. |
3cbe1980 | 481 | |
bbda8ce9 | 482 | =item EVP_MD_type(), |
37842dfa | 483 | EVP_MD_pkey_type() |
3cbe1980 | 484 | |
bbda8ce9 RT |
485 | Returns the NID of the corresponding OBJECT IDENTIFIER or NID_undef if none |
486 | exists. | |
3cbe1980 | 487 | |
bbda8ce9 RT |
488 | =item EVP_MD_size(), |
489 | EVP_MD_block_size(), | |
490 | EVP_MD_CTX_size(), | |
491 | EVP_MD_CTX_block_size() | |
3cbe1980 | 492 | |
bbda8ce9 RT |
493 | Returns the digest or block size in bytes. |
494 | ||
495 | =item EVP_md_null() | |
496 | ||
497 | Returns a pointer to the B<EVP_MD> structure of the "null" message digest. | |
498 | ||
499 | =item EVP_get_digestbyname(), | |
500 | EVP_get_digestbynid(), | |
501 | EVP_get_digestbyobj() | |
502 | ||
503 | Returns either an B<EVP_MD> structure or NULL if an error occurs. | |
504 | ||
675f4cee PY |
505 | =item EVP_MD_CTX_set_pkey_ctx() |
506 | ||
507 | This function has no return value. | |
508 | ||
bbda8ce9 | 509 | =back |
3cbe1980 DSH |
510 | |
511 | =head1 NOTES | |
512 | ||
513 | The B<EVP> interface to message digests should almost always be used in | |
514 | preference to the low level interfaces. This is because the code then becomes | |
515 | transparent to the digest used and much more flexible. | |
516 | ||
bbda8ce9 | 517 | New applications should use the SHA-2 (such as L<EVP_sha256(3)>) or the SHA-3 |
89f66fe2 | 518 | digest algorithms (such as L<EVP_sha3_512(3)>). The other digest algorithms |
519 | are still in common use. | |
3cbe1980 | 520 | |
e72d734d DSH |
521 | For most applications the B<impl> parameter to EVP_DigestInit_ex() will be |
522 | set to NULL to use the default digest implementation. | |
523 | ||
7b3e11c5 | 524 | The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are |
e72d734d | 525 | obsolete but are retained to maintain compatibility with existing code. New |
7b3e11c5 | 526 | applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and |
e72d734d DSH |
527 | EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context |
528 | instead of initializing and cleaning it up on each call and allow non default | |
529 | implementations of digests to be specified. | |
530 | ||
fa332bba | 531 | If digest contexts are not cleaned up after use, |
7b3e11c5 | 532 | memory leaks will occur. |
13588350 | 533 | |
c750bc08 RL |
534 | EVP_MD_CTX_name(), EVP_MD_CTX_size(), EVP_MD_CTX_block_size(), |
535 | EVP_MD_CTX_type(), EVP_get_digestbynid() and EVP_get_digestbyobj() are defined | |
536 | as macros. | |
5a34fcd7 | 537 | |
52ad5b60 TS |
538 | EVP_MD_CTX_ctrl() sends commands to message digests for additional configuration |
539 | or control. | |
5a34fcd7 | 540 | |
cda77422 | 541 | =head1 EXAMPLES |
3cbe1980 DSH |
542 | |
543 | This example digests the data "Test Message\n" and "Hello World\n", using the | |
544 | digest name passed on the command line. | |
545 | ||
546 | #include <stdio.h> | |
19ac1bf2 | 547 | #include <string.h> |
3cbe1980 DSH |
548 | #include <openssl/evp.h> |
549 | ||
19ac1bf2 | 550 | int main(int argc, char *argv[]) |
3cbe1980 | 551 | { |
2947af32 BB |
552 | EVP_MD_CTX *mdctx; |
553 | const EVP_MD *md; | |
554 | char mess1[] = "Test Message\n"; | |
555 | char mess2[] = "Hello World\n"; | |
556 | unsigned char md_value[EVP_MAX_MD_SIZE]; | |
19ac1bf2 | 557 | unsigned int md_len, i; |
2947af32 BB |
558 | |
559 | if (argv[1] == NULL) { | |
560 | printf("Usage: mdtest digestname\n"); | |
561 | exit(1); | |
562 | } | |
563 | ||
564 | md = EVP_get_digestbyname(argv[1]); | |
565 | if (md == NULL) { | |
566 | printf("Unknown message digest %s\n", argv[1]); | |
567 | exit(1); | |
568 | } | |
569 | ||
570 | mdctx = EVP_MD_CTX_new(); | |
571 | EVP_DigestInit_ex(mdctx, md, NULL); | |
572 | EVP_DigestUpdate(mdctx, mess1, strlen(mess1)); | |
573 | EVP_DigestUpdate(mdctx, mess2, strlen(mess2)); | |
574 | EVP_DigestFinal_ex(mdctx, md_value, &md_len); | |
575 | EVP_MD_CTX_free(mdctx); | |
576 | ||
577 | printf("Digest is: "); | |
578 | for (i = 0; i < md_len; i++) | |
579 | printf("%02x", md_value[i]); | |
580 | printf("\n"); | |
581 | ||
582 | exit(0); | |
3cbe1980 DSH |
583 | } |
584 | ||
3cbe1980 DSH |
585 | =head1 SEE ALSO |
586 | ||
37842dfa | 587 | L<EVP_MD_meth_new(3)>, |
9b86974e | 588 | L<dgst(1)>, |
d5e5e2ff SL |
589 | L<evp(7)>, |
590 | L<OSSL_PROVIDER(3)>, | |
591 | L<OSSL_PARAM(3)> | |
4facdbb5 | 592 | |
bbda8ce9 RT |
593 | The full list of digest algorithms are provided below. |
594 | ||
595 | L<EVP_blake2b512(3)>, | |
596 | L<EVP_md2(3)>, | |
597 | L<EVP_md4(3)>, | |
598 | L<EVP_md5(3)>, | |
599 | L<EVP_mdc2(3)>, | |
600 | L<EVP_ripemd160(3)>, | |
601 | L<EVP_sha1(3)>, | |
602 | L<EVP_sha224(3)>, | |
603 | L<EVP_sha3_224(3)>, | |
67e247fa | 604 | L<EVP_sm3(3)>, |
bbda8ce9 | 605 | L<EVP_whirlpool(3)> |
2cafb1df | 606 | L<provider(7)/Fetching algorithms> |
bbda8ce9 | 607 | |
3cbe1980 DSH |
608 | =head1 HISTORY |
609 | ||
fc5ecadd DMSP |
610 | The EVP_MD_CTX_create() and EVP_MD_CTX_destroy() functions were renamed to |
611 | EVP_MD_CTX_new() and EVP_MD_CTX_free() in OpenSSL 1.1.0, respectively. | |
25191fff | 612 | |
3fa39ed7 | 613 | The link between digests and signing algorithms was fixed in OpenSSL 1.0 and |
a95d7574 RS |
614 | later, so now EVP_sha1() can be used with RSA and DSA. |
615 | ||
fc5ecadd | 616 | The EVP_dss1() function was removed in OpenSSL 1.1.0. |
3fa39ed7 | 617 | |
fc5ecadd | 618 | The EVP_MD_CTX_set_pkey_ctx() function was added in 1.1.1. |
675f4cee | 619 | |
3fd70262 RL |
620 | The EVP_MD_fetch(), EVP_MD_free(), EVP_MD_up_ref(), EVP_MD_CTX_set_params() |
621 | and EVP_MD_CTX_get_params() functions were added in 3.0. | |
d5e5e2ff | 622 | |
e2f92610 RS |
623 | =head1 COPYRIGHT |
624 | ||
d5e5e2ff | 625 | Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 626 | |
4746f25a | 627 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
628 | this file except in compliance with the License. You can obtain a copy |
629 | in the file LICENSE in the source distribution or at | |
630 | L<https://www.openssl.org/source/license.html>. | |
631 | ||
632 | =cut |