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