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