doc/man3/EVP_DigestInit.pod

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