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