1EVP_DIGESTINIT(3ossl)               OpenSSL              EVP_DIGESTINIT(3ossl)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

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

PARAMETERS

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

CONTROLS

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

FLAGS

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

RETURN VALUES

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

NOTES

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

EXAMPLES

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

SEE ALSO

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

HISTORY

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-11-01             EVP_DIGESTINIT(3ossl)
Impressum