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_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 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 int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in);
66 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 int EVP_MD_CTX_copy(EVP_MD_CTX *out, EVP_MD_CTX *in);
71 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 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 const EVP_MD *EVP_md_null(void);
94 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 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 void EVP_MD_do_all_provided(OSSL_LIB_CTX *libctx,
103 void (*fn)(EVP_MD *mac, void *arg),
104 void *arg);
105 #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 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 const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx);
124 int (*EVP_MD_CTX_update_fn(EVP_MD_CTX *ctx))(EVP_MD_CTX *ctx,
126 const void *data, size_t count);
127 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 The EVP_MD type is a structure for digest method implementation.
137 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 The returned value must eventually be freed with EVP_MD_free().
144 Fetched EVP_MD structures are reference counted.
146 EVP_MD_up_ref()
148 Increments the reference count for an EVP_MD structure.
149 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 EVP_MD_CTX_new()
155 Allocates and returns a digest context.
156 EVP_MD_CTX_reset()
158 Resets the digest context ctx. This can be used to reuse an
159 already existing context.
160 EVP_MD_CTX_free()
162 Cleans up digest context ctx and frees up the space allocated to
163 it.
164 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 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 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 See "CONTROLS" below for more information, including what
183 translations are being done.
184 EVP_MD_get_params()
186 Retrieves the requested list of params from a MD md. See
187 "PARAMETERS" below for more information.
188 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 EVP_MD_CTX_set_params()
194 Sets the list of params into a MD context ctx. See "PARAMETERS"
195 below for more information.
196 EVP_MD_gettable_params()
198 Get a constant OSSL_PARAM(3) array that describes the retrievable
199 parameters that can be used with EVP_MD_get_params().
200 EVP_MD_gettable_ctx_params(), EVP_MD_CTX_gettable_params()
202 Get a constant OSSL_PARAM(3) array that describes the retrievable
203 parameters that can be used with EVP_MD_CTX_get_params().
204 EVP_MD_gettable_ctx_params() returns the parameters that can be
205 retrieved from the algorithm, whereas EVP_MD_CTX_gettable_params()
206 returns the parameters that can be retrieved in the context's
207 current state.
208 EVP_MD_settable_ctx_params(), EVP_MD_CTX_settable_params()
210 Get a constant OSSL_PARAM(3) array that describes the settable
211 parameters that can be used with EVP_MD_CTX_set_params().
212 EVP_MD_settable_ctx_params() returns the parameters that can be set
213 from the algorithm, whereas EVP_MD_CTX_settable_params() returns
214 the parameters that can be set in the context's current state.
215 EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(),
217 EVP_MD_CTX_test_flags()
218 Sets, clears and tests ctx flags. See "FLAGS" below for more
219 information.
220 EVP_Q_digest() is a quick one-shot digest function.
222 It hashes datalen bytes of data at data using the digest algorithm
223 name, which is fetched using the optional libctx and propq
224 parameters. The digest value is placed in md and its length is
225 written at mdlen if the pointer is not NULL. At most
226 EVP_MAX_MD_SIZE bytes will be written.
227 EVP_Digest()
229 A wrapper around the Digest Init_ex, Update and Final_ex functions.
230 Hashes count bytes of data at data using a digest type from ENGINE
231 impl. The digest value is placed in md and its length is written at
232 size if the pointer is not NULL. At most EVP_MAX_MD_SIZE bytes will
233 be written. If impl is NULL the default implementation of digest
234 type is used.
235 EVP_DigestInit_ex2()
237 Sets up digest context ctx to use a digest type. type is typically
238 supplied by a function such as EVP_sha1(), or a value explicitly
239 fetched with EVP_MD_fetch().
240 The parameters params are set on the context after initialisation.
242 The type parameter can be NULL if ctx has been already initialized
244 with another EVP_DigestInit_ex() call and has not been reset with
245 EVP_MD_CTX_reset().
246 EVP_DigestInit_ex()
248 Sets up digest context ctx to use a digest type. type is typically
249 supplied by a function such as EVP_sha1(), or a value explicitly
250 fetched with EVP_MD_fetch().
251 If impl is non-NULL, its implementation of the digest type is used
253 if there is one, and if not, the default implementation is used.
254 The type parameter can be NULL if ctx has been already initialized
256 with another EVP_DigestInit_ex() call and has not been reset with
257 EVP_MD_CTX_reset().
258 EVP_DigestUpdate()
260 Hashes cnt bytes of data at d into the digest context ctx. This
261 function can be called several times on the same ctx to hash
262 additional data.
263 EVP_DigestFinal_ex()
265 Retrieves the digest value from ctx and places it in md. If the s
266 parameter is not NULL then the number of bytes of data written
267 (i.e. the length of the digest) will be written to the integer at
268 s, at most EVP_MAX_MD_SIZE bytes will be written. After calling
269 EVP_DigestFinal_ex() no additional calls to EVP_DigestUpdate() can
270 be made, but EVP_DigestInit_ex2() can be called to initialize a new
271 digest operation.
272 EVP_DigestFinalXOF()
274 Interfaces to extendable-output functions, XOFs, such as SHAKE128
275 and SHAKE256. It retrieves the digest value from ctx and places it
276 in len-sized md. After calling this function no additional calls
277 to EVP_DigestUpdate() can be made, but EVP_DigestInit_ex2() can be
278 called to initialize a new operation.
279 EVP_MD_CTX_copy_ex()
281 Can be used to copy the message digest state from in to out. This
282 is useful if large amounts of data are to be hashed which only
283 differ in the last few bytes.
284 EVP_DigestInit()
286 Behaves in the same way as EVP_DigestInit_ex2() except it doesn't
287 set any parameters and calls EVP_MD_CTX_reset() so it cannot be
288 used with an type of NULL.
289 EVP_DigestFinal()
291 Similar to EVP_DigestFinal_ex() except after computing the digest
292 the digest context ctx is automatically cleaned up with
293 EVP_MD_CTX_reset().
294 EVP_MD_CTX_copy()
296 Similar to EVP_MD_CTX_copy_ex() except the destination out does not
297 have to be initialized.
298 EVP_MD_is_a()
300 Returns 1 if md is an implementation of an algorithm that's
301 identifiable with name, otherwise 0.
302 If md is a legacy digest (it's the return value from the likes of
304 EVP_sha256() rather than the result of an EVP_MD_fetch()), only
305 cipher names registered with the default library context (see
306 OSSL_LIB_CTX(3)) will be considered.
307 EVP_MD_get0_name(), EVP_MD_CTX_get0_name()
309 Return the name of the given message digest. For fetched message
310 digests with multiple names, only one of them is returned; it's
311 recommended to use EVP_MD_names_do_all() instead.
312 EVP_MD_names_do_all()
314 Traverses all names for the md, and calls fn with each name and
315 data. This is only useful with fetched EVP_MDs.
316 EVP_MD_get0_description()
318 Returns a description of the digest, meant for display and human
319 consumption. The description is at the discretion of the digest
320 implementation.
321 EVP_MD_get0_provider()
323 Returns an OSSL_PROVIDER pointer to the provider that implements
324 the given EVP_MD.
325 EVP_MD_get_size(), EVP_MD_CTX_get_size()
327 Return the size of the message digest when passed an EVP_MD or an
328 EVP_MD_CTX structure, i.e. the size of the hash.
329 EVP_MD_get_block_size(), EVP_MD_CTX_get_block_size()
331 Return the block size of the message digest when passed an EVP_MD
332 or an EVP_MD_CTX structure.
333 EVP_MD_get_type(), EVP_MD_CTX_get_type()
335 Return the NID of the OBJECT IDENTIFIER representing the given
336 message digest when passed an EVP_MD structure. For example,
337 "EVP_MD_get_type(EVP_sha1())" returns NID_sha1. This function is
338 normally used when setting ASN1 OIDs.
339 EVP_MD_CTX_get0_md_data()
341 Return the digest method private data for the passed EVP_MD_CTX.
342 The space is allocated by OpenSSL and has the size originally set
343 with EVP_MD_meth_set_app_datasize().
344 EVP_MD_CTX_get0_md(), EVP_MD_CTX_get1_md()
346 EVP_MD_CTX_get0_md() returns the EVP_MD structure corresponding to
347 the passed EVP_MD_CTX. This will be the same EVP_MD object
348 originally passed to EVP_DigestInit_ex2() (or other similar
349 function) when the EVP_MD_CTX was first initialised. Note that
350 where explicit fetch is in use (see EVP_MD_fetch(3)) the value
351 returned from this function will not have its reference count
352 incremented and therefore it should not be used after the
353 EVP_MD_CTX is freed. EVP_MD_CTX_get1_md() is the same except the
354 ownership is passed to the caller and is from the passed
355 EVP_MD_CTX.
356 EVP_MD_CTX_set_update_fn()
358 Sets the update function for ctx to update. This is the function
359 that is called by EVP_DigestUpdate(). If not set, the update
360 function from the EVP_MD type specified at initialization is used.
361 EVP_MD_CTX_update_fn()
363 Returns the update function for ctx.
364 EVP_MD_get_flags()
366 Returns the md flags. Note that these are different from the
367 EVP_MD_CTX ones. See EVP_MD_meth_set_flags(3) for more information.
368 EVP_MD_get_pkey_type()
370 Returns the NID of the public key signing algorithm associated with
371 this digest. For example EVP_sha1() is associated with RSA so this
372 will return NID_sha1WithRSAEncryption. Since digests and signature
373 algorithms are no longer linked this function is only retained for
374 compatibility reasons.
375 EVP_md_null()
377 A "null" message digest that does nothing: i.e. the hash it returns
378 is of zero length.
379 EVP_get_digestbyname(), EVP_get_digestbynid(), EVP_get_digestbyobj()
381 Returns an EVP_MD structure when passed a digest name, a digest NID
382 or an ASN1_OBJECT structure respectively.
383 The EVP_get_digestbyname() function is present for backwards
385 compatibility with OpenSSL prior to version 3 and is different to
386 the EVP_MD_fetch() function since it does not attempt to "fetch" an
387 implementation of the cipher. Additionally, it only knows about
388 digests that are built-in to OpenSSL and have an associated NID.
389 Similarly EVP_get_digestbynid() and EVP_get_digestbyobj() also
390 return objects without an associated implementation.
391 When the digest objects returned by these functions are used (such
393 as in a call to EVP_DigestInit_ex()) an implementation of the
394 digest will be implicitly fetched from the loaded providers. This
395 fetch could fail if no suitable implementation is available. Use
396 EVP_MD_fetch() instead to explicitly fetch the algorithm and an
397 associated implementation from a provider.
398 See "ALGORITHM FETCHING" in crypto(7) for more information about
400 fetching.
401 The digest objects returned from these functions do not need to be
403 freed with EVP_MD_free().
404 EVP_MD_CTX_get_pkey_ctx()
406 Returns the EVP_PKEY_CTX assigned to ctx. The returned pointer
407 should not be freed by the caller.
408 EVP_MD_CTX_set_pkey_ctx()
410 Assigns an EVP_PKEY_CTX to EVP_MD_CTX. This is usually used to
411 provide a customized EVP_PKEY_CTX to EVP_DigestSignInit(3) or
412 EVP_DigestVerifyInit(3). The pctx passed to this function should be
413 freed by the caller. A NULL pctx pointer is also allowed to clear
414 the EVP_PKEY_CTX assigned to ctx. In such case, freeing the cleared
415 EVP_PKEY_CTX or not depends on how the EVP_PKEY_CTX is created.
416 EVP_MD_do_all_provided()
418 Traverses all messages digests implemented by all activated
419 providers in the given library context libctx, and for each of the
420 implementations, calls the given function fn with the
421 implementation method and the given arg as argument.
422
424 See OSSL_PARAM(3) for information about passing parameters.
425 EVP_MD_CTX_set_params() can be used with the following OSSL_PARAM keys:
427 "xoflen" (OSSL_DIGEST_PARAM_XOFLEN) <unsigned integer>
429 Sets the digest length for extendable output functions. It is used
430 by the SHAKE algorithm and should not exceed what can be given
431 using a size_t.
432 "pad-type" (OSSL_DIGEST_PARAM_PAD_TYPE) <unsigned integer>
434 Sets the padding type. It is used by the MDC2 algorithm.
435 EVP_MD_CTX_get_params() can be used with the following OSSL_PARAM keys:
437 "micalg" (OSSL_PARAM_DIGEST_KEY_MICALG) <UTF8 string>.
439 Gets the digest Message Integrity Check algorithm string. This is
440 used when creating S/MIME multipart/signed messages, as specified
441 in RFC 3851. It may be used by external engines or providers.
442
444 EVP_MD_CTX_ctrl() can be used to send the following standard controls:
445 EVP_MD_CTRL_MICALG
447 Gets the digest Message Integrity Check algorithm string. This is
448 used when creating S/MIME multipart/signed messages, as specified
449 in RFC 3851. The string value is written to p2.
450 When used with a fetched EVP_MD, EVP_MD_CTX_get_params() gets
452 called with an OSSL_PARAM(3) item with the key "micalg"
453 (OSSL_DIGEST_PARAM_MICALG).
454 EVP_MD_CTRL_XOF_LEN
456 This control sets the digest length for extendable output functions
457 to p1. Sending this control directly should not be necessary, the
458 use of EVP_DigestFinalXOF() is preferred. Currently used by SHAKE.
459 When used with a fetched EVP_MD, EVP_MD_CTX_get_params() gets
461 called with an OSSL_PARAM(3) item with the key "xoflen"
462 (OSSL_DIGEST_PARAM_XOFLEN).
463
465 EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags() and
466 EVP_MD_CTX_test_flags() can be used the manipulate and test these
467 EVP_MD_CTX flags:
468 EVP_MD_CTX_FLAG_ONESHOT
470 This flag instructs the digest to optimize for one update only, if
471 possible.
472 EVP_MD_CTX_FLAG_NO_INIT
474 This flag instructs EVP_DigestInit() and similar not to initialise
475 the implementation specific data.
476 EVP_MD_CTX_FLAG_FINALISE
478 Some functions such as EVP_DigestSign only finalise copies of
479 internal contexts so additional data can be included after the
480 finalisation call. This is inefficient if this functionality is
481 not required, and can be disabled with this flag.
482
484 EVP_MD_fetch()
485 Returns a pointer to a EVP_MD for success or NULL for failure.
486 EVP_MD_up_ref()
488 Returns 1 for success or 0 for failure.
489 EVP_Q_digest(), EVP_Digest(), EVP_DigestInit_ex2(),
491 EVP_DigestInit_ex(), EVP_DigestInit(), EVP_DigestUpdate(),
492 EVP_DigestFinal_ex(), EVP_DigestFinalXOF(), and EVP_DigestFinal()
493 return 1 for success and 0 for failure.
494 EVP_MD_CTX_ctrl()
496 Returns 1 if successful or 0 for failure.
497 EVP_MD_CTX_set_params(), EVP_MD_CTX_get_params()
499 Returns 1 if successful or 0 for failure.
500 EVP_MD_CTX_settable_params(), EVP_MD_CTX_gettable_params()
502 Return an array of constant OSSL_PARAM(3)s, or NULL if there is
503 none to get.
504 EVP_MD_CTX_copy_ex()
506 Returns 1 if successful or 0 for failure.
507 EVP_MD_get_type(), EVP_MD_get_pkey_type()
509 Returns the NID of the corresponding OBJECT IDENTIFIER or NID_undef
510 if none exists.
511 EVP_MD_get_size(), EVP_MD_get_block_size(), EVP_MD_CTX_get_size(),
513 EVP_MD_CTX_get_block_size()
514 Returns the digest or block size in bytes or -1 for failure.
515 EVP_md_null()
517 Returns a pointer to the EVP_MD structure of the "null" message
518 digest.
519 EVP_get_digestbyname(), EVP_get_digestbynid(), EVP_get_digestbyobj()
521 Returns either an EVP_MD structure or NULL if an error occurs.
522 EVP_MD_CTX_set_pkey_ctx()
524 This function has no return value.
525 EVP_MD_names_do_all()
527 Returns 1 if the callback was called for all names. A return value
528 of 0 means that the callback was not called for any names.
529
531 The EVP interface to message digests should almost always be used in
532 preference to the low-level interfaces. This is because the code then
533 becomes transparent to the digest used and much more flexible.
534 New applications should use the SHA-2 (such as EVP_sha256(3)) or the
536 SHA-3 digest algorithms (such as EVP_sha3_512(3)). The other digest
537 algorithms are still in common use.
538 For most applications the impl parameter to EVP_DigestInit_ex() will be
540 set to NULL to use the default digest implementation.
541 Ignoring failure returns of EVP_DigestInit_ex(), EVP_DigestInit_ex2(),
543 or EVP_DigestInit() can lead to undefined behavior on subsequent calls
544 updating or finalizing the EVP_MD_CTX such as the EVP_DigestUpdate() or
545 EVP_DigestFinal() functions. The only valid calls on the EVP_MD_CTX
546 when initialization fails are calls that attempt another initialization
547 of the context or release the context.
548 The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy()
550 are obsolete but are retained to maintain compatibility with existing
551 code. New applications should use EVP_DigestInit_ex(),
552 EVP_DigestFinal_ex() and EVP_MD_CTX_copy_ex() because they can
553 efficiently reuse a digest context instead of initializing and cleaning
554 it up on each call and allow non default implementations of digests to
555 be specified.
556 If digest contexts are not cleaned up after use, memory leaks will
558 occur.
559 EVP_MD_CTX_get0_name(), EVP_MD_CTX_get_size(),
561 EVP_MD_CTX_get_block_size(), EVP_MD_CTX_get_type(),
562 EVP_get_digestbynid() and EVP_get_digestbyobj() are defined as macros.
563 EVP_MD_CTX_ctrl() sends commands to message digests for additional
565 configuration or control.
566
568 This example digests the data "Test Message\n" and "Hello World\n",
569 using the digest name passed on the command line.
570 #include <stdio.h>
572 #include <string.h>
573 #include <openssl/evp.h>
574 int main(int argc, char *argv[])
576 {
577 EVP_MD_CTX *mdctx;
578 const EVP_MD *md;
579 char mess1[] = "Test Message\n";
580 char mess2[] = "Hello World\n";
581 unsigned char md_value[EVP_MAX_MD_SIZE];
582 unsigned int md_len, i;
583 if (argv[1] == NULL) {
585 printf("Usage: mdtest digestname\n");
586 exit(1);
587 }
588 md = EVP_get_digestbyname(argv[1]);
590 if (md == NULL) {
591 printf("Unknown message digest %s\n", argv[1]);
592 exit(1);
593 }
594 mdctx = EVP_MD_CTX_new();
596 if (!EVP_DigestInit_ex2(mdctx, md, NULL)) {
597 printf("Message digest initialization failed.\n");
598 EVP_MD_CTX_free(mdctx);
599 exit(1);
600 }
601 if (!EVP_DigestUpdate(mdctx, mess1, strlen(mess1))) {
602 printf("Message digest update failed.\n");
603 EVP_MD_CTX_free(mdctx);
604 exit(1);
605 }
606 if (!EVP_DigestUpdate(mdctx, mess2, strlen(mess2))) {
607 printf("Message digest update failed.\n");
608 EVP_MD_CTX_free(mdctx);
609 exit(1);
610 }
611 if (!EVP_DigestFinal_ex(mdctx, md_value, &md_len)) {
612 printf("Message digest finalization failed.\n");
613 EVP_MD_CTX_free(mdctx);
614 exit(1);
615 }
616 EVP_MD_CTX_free(mdctx);
617 printf("Digest is: ");
619 for (i = 0; i < md_len; i++)
620 printf("%02x", md_value[i]);
621 printf("\n");
622 exit(0);
624 }
625
627 EVP_MD_meth_new(3), openssl-dgst(1), evp(7), OSSL_PROVIDER(3),
628 OSSL_PARAM(3), property(7), "ALGORITHM FETCHING" in crypto(7),
629 provider-digest(7), life_cycle-digest(7)
630 The full list of digest algorithms are provided below.
632 EVP_blake2b512(3), EVP_md2(3), EVP_md4(3), EVP_md5(3), EVP_mdc2(3),
634 EVP_ripemd160(3), EVP_sha1(3), EVP_sha224(3), EVP_sha3_224(3),
635 EVP_sm3(3), EVP_whirlpool(3)
636
638 The EVP_MD_CTX_create() and EVP_MD_CTX_destroy() functions were renamed
639 to EVP_MD_CTX_new() and EVP_MD_CTX_free() in OpenSSL 1.1.0,
640 respectively.
641 The link between digests and signing algorithms was fixed in OpenSSL
643 1.0 and later, so now EVP_sha1() can be used with RSA and DSA.
644 The EVP_dss1() function was removed in OpenSSL 1.1.0.
646 The EVP_MD_CTX_set_pkey_ctx() function was added in OpenSSL 1.1.1.
648 The EVP_Q_digest(), EVP_DigestInit_ex2(), EVP_MD_fetch(),
650 EVP_MD_free(), EVP_MD_up_ref(), EVP_MD_get_params(),
651 EVP_MD_CTX_set_params(), EVP_MD_CTX_get_params(),
652 EVP_MD_gettable_params(), EVP_MD_gettable_ctx_params(),
653 EVP_MD_settable_ctx_params(), EVP_MD_CTX_settable_params() and
654 EVP_MD_CTX_gettable_params() functions were added in OpenSSL 3.0.
655 The EVP_MD_type(), EVP_MD_nid(), EVP_MD_name(), EVP_MD_pkey_type(),
657 EVP_MD_size(), EVP_MD_block_size(), EVP_MD_flags(), EVP_MD_CTX_size(),
658 EVP_MD_CTX_block_size(), EVP_MD_CTX_type(), and EVP_MD_CTX_md_data()
659 functions were renamed to include "get" or "get0" in their names in
660 OpenSSL 3.0, respectively. The old names are kept as non-deprecated
661 alias macros.
662 The EVP_MD_CTX_md() function was deprecated in OpenSSL 3.0; use
664 EVP_MD_CTX_get0_md() instead. EVP_MD_CTX_update_fn() and
665 EVP_MD_CTX_set_update_fn() were deprecated in OpenSSL 3.0.
666
668 Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.
669 Licensed under the Apache License 2.0 (the "License"). You may not use
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 <https://www.openssl.org/source/license.html>.
6743.0.9 2023-07-27 EVP_DIGESTINIT(3ossl)