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