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