1.\" $OpenBSD: EVP_DigestInit.3,v 1.28 2023/08/14 14:22:32 schwarze Exp $ 2.\" full merge up to: OpenSSL 7f572e95 Dec 2 13:57:04 2015 +0000 3.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 4.\" 5.\" This file is a derived work. 6.\" The changes are covered by the following Copyright and license: 7.\" 8.\" Copyright (c) 2019, 2023 Ingo Schwarze <schwarze@openbsd.org> 9.\" 10.\" Permission to use, copy, modify, and distribute this software for any 11.\" purpose with or without fee is hereby granted, provided that the above 12.\" copyright notice and this permission notice appear in all copies. 13.\" 14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 21.\" 22.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>, 23.\" Richard Levitte <levitte@openssl.org>, 24.\" Paul Yang <yang.yang@baishancloud.com>, and 25.\" Antoine Salon <asalon@vmware.com>. 26.\" Copyright (c) 2000-2004, 2009, 2012-2016, 2018, 2019 The OpenSSL Project. 27.\" All rights reserved. 28.\" 29.\" Redistribution and use in source and binary forms, with or without 30.\" modification, are permitted provided that the following conditions 31.\" are met: 32.\" 33.\" 1. Redistributions of source code must retain the above copyright 34.\" notice, this list of conditions and the following disclaimer. 35.\" 36.\" 2. Redistributions in binary form must reproduce the above copyright 37.\" notice, this list of conditions and the following disclaimer in 38.\" the documentation and/or other materials provided with the 39.\" distribution. 40.\" 41.\" 3. All advertising materials mentioning features or use of this 42.\" software must display the following acknowledgment: 43.\" "This product includes software developed by the OpenSSL Project 44.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 45.\" 46.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 47.\" endorse or promote products derived from this software without 48.\" prior written permission. For written permission, please contact 49.\" openssl-core@openssl.org. 50.\" 51.\" 5. Products derived from this software may not be called "OpenSSL" 52.\" nor may "OpenSSL" appear in their names without prior written 53.\" permission of the OpenSSL Project. 54.\" 55.\" 6. Redistributions of any form whatsoever must retain the following 56.\" acknowledgment: 57.\" "This product includes software developed by the OpenSSL Project 58.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 59.\" 60.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 61.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 62.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 63.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 64.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 65.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 66.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 67.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 68.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 69.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 70.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 71.\" OF THE POSSIBILITY OF SUCH DAMAGE. 72.\" 73.Dd $Mdocdate: August 14 2023 $ 74.Dt EVP_DIGESTINIT 3 75.Os 76.Sh NAME 77.Nm EVP_MD_CTX_new , 78.Nm EVP_MD_CTX_reset , 79.Nm EVP_MD_CTX_free , 80.Nm EVP_MD_CTX_init , 81.Nm EVP_MD_CTX_create , 82.Nm EVP_MD_CTX_cleanup , 83.Nm EVP_MD_CTX_destroy , 84.Nm EVP_MD_CTX_ctrl , 85.Nm EVP_MD_CTX_set_flags , 86.Nm EVP_MD_CTX_clear_flags , 87.Nm EVP_MD_CTX_test_flags , 88.Nm EVP_DigestInit_ex , 89.Nm EVP_DigestUpdate , 90.Nm EVP_DigestFinal_ex , 91.Nm EVP_Digest , 92.Nm EVP_MD_CTX_copy_ex , 93.Nm EVP_DigestInit , 94.Nm EVP_DigestFinal , 95.Nm EVP_MD_CTX_copy , 96.Nm EVP_MAX_MD_SIZE , 97.Nm EVP_MD_type , 98.Nm EVP_MD_pkey_type , 99.Nm EVP_MD_size , 100.Nm EVP_MD_block_size , 101.Nm EVP_MD_flags , 102.Nm EVP_MD_CTX_md , 103.Nm EVP_MD_CTX_size , 104.Nm EVP_MD_CTX_block_size , 105.Nm EVP_MD_CTX_type , 106.Nm EVP_MD_CTX_md_data , 107.Nm EVP_MD_CTX_pkey_ctx , 108.Nm EVP_MD_CTX_set_pkey_ctx , 109.Nm EVP_md_null , 110.Nm EVP_md5 , 111.Nm EVP_md5_sha1 , 112.Nm EVP_sha1 , 113.Nm EVP_sha224 , 114.Nm EVP_sha256 , 115.Nm EVP_sha384 , 116.Nm EVP_sha512 , 117.Nm EVP_sha512_224 , 118.Nm EVP_sha512_256 , 119.Nm EVP_ripemd160 , 120.Nm EVP_get_digestbyname , 121.Nm EVP_get_digestbynid , 122.Nm EVP_get_digestbyobj 123.Nd EVP digest routines 124.Sh SYNOPSIS 125.In openssl/evp.h 126.Ft EVP_MD_CTX * 127.Fn EVP_MD_CTX_new void 128.Ft int 129.Fo EVP_MD_CTX_reset 130.Fa "EVP_MD_CTX *ctx" 131.Fc 132.Ft void 133.Fo EVP_MD_CTX_free 134.Fa "EVP_MD_CTX *ctx" 135.Fc 136.Ft void 137.Fo EVP_MD_CTX_init 138.Fa "EVP_MD_CTX *ctx" 139.Fc 140.Ft EVP_MD_CTX * 141.Fn EVP_MD_CTX_create void 142.Ft int 143.Fo EVP_MD_CTX_cleanup 144.Fa "EVP_MD_CTX *ctx" 145.Fc 146.Ft void 147.Fo EVP_MD_CTX_destroy 148.Fa "EVP_MD_CTX *ctx" 149.Fc 150.Ft int 151.Fo EVP_MD_CTX_ctrl 152.Fa "EVP_MD_CTX *ctx" 153.Fa "int command" 154.Fa "int p1" 155.Fa "void* p2" 156.Fc 157.Ft void 158.Fo EVP_MD_CTX_set_flags 159.Fa "EVP_MD_CTX *ctx" 160.Fa "int flags" 161.Fc 162.Ft void 163.Fo EVP_MD_CTX_clear_flags 164.Fa "EVP_MD_CTX *ctx" 165.Fa "int flags" 166.Fc 167.Ft int 168.Fo EVP_MD_CTX_test_flags 169.Fa "const EVP_MD_CTX *ctx" 170.Fa "int flags" 171.Fc 172.Ft int 173.Fo EVP_DigestInit_ex 174.Fa "EVP_MD_CTX *ctx" 175.Fa "const EVP_MD *type" 176.Fa "ENGINE *impl" 177.Fc 178.Ft int 179.Fo EVP_DigestUpdate 180.Fa "EVP_MD_CTX *ctx" 181.Fa "const void *d" 182.Fa "size_t cnt" 183.Fc 184.Ft int 185.Fo EVP_DigestFinal_ex 186.Fa "EVP_MD_CTX *ctx" 187.Fa "unsigned char *md" 188.Fa "unsigned int *s" 189.Fc 190.Ft int 191.Fo EVP_Digest 192.Fa "const void *d" 193.Fa "size_t cnt" 194.Fa "unsigned char *md" 195.Fa "unsigned int *s" 196.Fa "const EVP_MD *type" 197.Fa "ENGINE *impl" 198.Fc 199.Ft int 200.Fo EVP_MD_CTX_copy_ex 201.Fa "EVP_MD_CTX *out" 202.Fa "const EVP_MD_CTX *in" 203.Fc 204.Ft int 205.Fo EVP_DigestInit 206.Fa "EVP_MD_CTX *ctx" 207.Fa "const EVP_MD *type" 208.Fc 209.Ft int 210.Fo EVP_DigestFinal 211.Fa "EVP_MD_CTX *ctx" 212.Fa "unsigned char *md" 213.Fa "unsigned int *s" 214.Fc 215.Ft int 216.Fo EVP_MD_CTX_copy 217.Fa "EVP_MD_CTX *out" 218.Fa "EVP_MD_CTX *in" 219.Fc 220.Fd #define EVP_MAX_MD_SIZE 64 /* SHA512 */ 221.Ft int 222.Fo EVP_MD_type 223.Fa "const EVP_MD *md" 224.Fc 225.Ft int 226.Fo EVP_MD_pkey_type 227.Fa "const EVP_MD *md" 228.Fc 229.Ft int 230.Fo EVP_MD_size 231.Fa "const EVP_MD *md" 232.Fc 233.Ft int 234.Fo EVP_MD_block_size 235.Fa "const EVP_MD *md" 236.Fc 237.Ft unsigned long 238.Fo EVP_MD_flags 239.Fa "const EVP_MD *md" 240.Fc 241.Ft const EVP_MD * 242.Fo EVP_MD_CTX_md 243.Fa "const EVP_MD_CTX *ctx" 244.Fc 245.Ft int 246.Fo EVP_MD_CTX_size 247.Fa "const EVP_MD_CTX *ctx" 248.Fc 249.Ft int 250.Fo EVP_MD_CTX_block_size 251.Fa "const EVP_MD_CTX *ctx" 252.Fc 253.Ft int 254.Fo EVP_MD_CTX_type 255.Fa "const EVP_MD_CTX *ctx" 256.Fc 257.Ft void * 258.Fo EVP_MD_CTX_md_data 259.Fa "const EVP_MD_CTX *ctx" 260.Fc 261.Ft EVP_PKEY_CTX * 262.Fo EVP_MD_CTX_pkey_ctx 263.Fa "const EVP_MD_CTX *ctx" 264.Fc 265.Ft void 266.Fo EVP_MD_CTX_set_pkey_ctx 267.Fa "EVP_MD_CTX *ctx" 268.Fa "EVP_PKEY_CTX *pctx" 269.Fc 270.Ft const EVP_MD * 271.Fn EVP_md_null void 272.Ft const EVP_MD * 273.Fn EVP_md5 void 274.Ft const EVP_MD * 275.Fn EVP_md5_sha1 void 276.Ft const EVP_MD * 277.Fn EVP_sha1 void 278.Ft const EVP_MD * 279.Fn EVP_sha224 void 280.Ft const EVP_MD * 281.Fn EVP_sha256 void 282.Ft const EVP_MD * 283.Fn EVP_sha384 void 284.Ft const EVP_MD * 285.Fn EVP_sha512 void 286.Ft const EVP_MD * 287.Fn EVP_sha512_224 void 288.Ft const EVP_MD * 289.Fn EVP_sha512_256 void 290.Ft const EVP_MD * 291.Fn EVP_ripemd160 void 292.Ft const EVP_MD * 293.Fo EVP_get_digestbyname 294.Fa "const char *name" 295.Fc 296.Ft const EVP_MD * 297.Fo EVP_get_digestbynid 298.Fa "int type" 299.Fc 300.Ft const EVP_MD * 301.Fo EVP_get_digestbyobj 302.Fa "const ASN1_OBJECT *o" 303.Fc 304.Sh DESCRIPTION 305The EVP digest routines are a high-level interface to message digests 306and should be used instead of the cipher-specific functions. 307.Pp 308.Fn EVP_MD_CTX_new 309allocates a new, empty digest context. 310.Pp 311.Fn EVP_MD_CTX_reset 312cleans up 313.Fa ctx 314and resets it to the state it had after 315.Fn EVP_MD_CTX_new , 316such that it can be reused. 317.Pp 318.Fn EVP_MD_CTX_free 319cleans up 320.Fa ctx 321and frees the space allocated to it. 322.Pp 323.Fn EVP_MD_CTX_init 324is a deprecated function to clear a digest context on the stack 325before use. 326Do not use it on a digest context returned from 327.Fn EVP_MD_CTX_new 328or one that was already used. 329.Pp 330.Fn EVP_MD_CTX_create , 331.Fn EVP_MD_CTX_cleanup , 332and 333.Fn EVP_MD_CTX_destroy 334are deprecated aliases for 335.Fn EVP_MD_CTX_new , 336.Fn EVP_MD_CTX_reset , 337and 338.Fn EVP_MD_CTX_free , 339respectively. 340.Pp 341.Fn EVP_MD_CTX_ctrl 342performs the digest-specific control 343.Fa command 344with the command-specific arguments 345.Fa p1 346and 347.Fa p2 348on 349.Fa ctx , 350which needs to already be set up with 351.Fn EVP_DigestInit_ex 352before calling this function. 353Other restrictions may apply depending on the control 354.Fa command 355and digest implementation. 356.Pp 357If the 358.Fa command 359is 360.Dv EVP_MD_CTRL_MICALG , 361.Fa p1 362is ignored and 363.Fa p2 364is an output argument of the type 365.Fa "char **p2" . 366A string specifying the digest Message Integrity Check algorithm 367is allocated and a pointer to this string is returned in 368.Pf * Fa p2 . 369It is the responsibility of the caller to 370.Xr free 3 371.Pf * Fa p2 372when it is no longer needed. 373This 374.Fa command 375is used by 376.Xr SMIME_write_ASN1 3 377when creating S/MIME multipart/signed messages as specified in RFC 3851. 378.Pp 379.Fn EVP_MD_CTX_set_flags 380sets and 381.Fn EVP_MD_CTX_clear_flags 382clears all the flag bits in 383.Fa ctx 384that are set in the 385.Fa flags 386argument. 387.Fn EVP_MD_CTX_test_flags 388tests which of the flag bits that are set in the 389.Fa flags 390argument are also set in 391.Fa ctx . 392Possible flag bits are: 393.Bl -tag -width Ds -offset 2n 394.It Dv EVP_MD_CTX_FLAG_NO_INIT 395Instruct 396.Fn EVP_DigestInit_ex 397and functions calling it not to initialise the internal data 398that is specific to the digest method and its implementation. 399.It Dv EVP_MD_CTX_FLAG_ONESHOT 400Instruct the digest to optimize for one update only, if possible. 401For digest algorithms built into the library, this flag usually 402has no effect. 403.El 404.Pp 405.Fn EVP_DigestInit_ex 406sets up the digest context 407.Fa ctx 408to use a digest 409.Fa type 410from 411.Vt ENGINE 412.Fa impl . 413The 414.Fa type 415will typically be supplied by a function such as 416.Fn EVP_sha1 . 417If 418.Fa impl 419is 420.Dv NULL , 421then the default implementation of digest 422.Fa type 423is used. 424.Pp 425.Fn EVP_DigestUpdate 426hashes 427.Fa cnt 428bytes of data at 429.Fa d 430into the digest context 431.Fa ctx . 432This function can be called several times on the same 433.Fa ctx 434to hash additional data. 435.Pp 436.Fn EVP_DigestFinal_ex 437retrieves the digest value from 438.Fa ctx 439and places it in 440.Fa md . 441If the 442.Fa s 443parameter is not 444.Dv NULL , 445then the number of bytes of data written (i.e. the length of the 446digest) will be written to the integer at 447.Fa s ; 448at most 449.Dv EVP_MAX_MD_SIZE 450bytes will be written. 451After calling 452.Fn EVP_DigestFinal_ex , 453no additional calls to 454.Fn EVP_DigestUpdate 455can be made, but 456.Fn EVP_DigestInit_ex 457can be called to initialize a new digest operation. 458.Pp 459.Fn EVP_Digest 460is a simple wrapper function to hash 461.Fa cnt 462bytes of data at 463.Fa d 464using the digest 465.Fa type 466from 467.Vt ENGINE 468.Fa impl 469in a one-shot operation and place the digest value into 470.Fa md , 471and, unless 472.Fa s 473is 474.Dv NULL , 475the length of the digest in bytes into 476.Pf * Fa s . 477This wrapper uses a temporary digest context and passes its arguments to 478.Fn EVP_DigestInit_ex , 479.Fn EVP_DigestUpdate , 480and 481.Fn EVP_DigestFinal_ex 482internally. 483.Pp 484.Fn EVP_MD_CTX_copy_ex 485can be used to copy the message digest state from 486.Fa in 487to 488.Fa out . 489This is useful if large amounts of data are to be hashed which only 490differ in the last few bytes. 491.Pp 492.Fn EVP_DigestInit 493is a deprecated function behaving like 494.Fn EVP_DigestInit_ex 495except that it always uses the default digest implementation 496and that it requires 497.Fn EVP_MD_CTX_reset 498before it can be used on a context that was already used. 499.Pp 500.Fn EVP_DigestFinal 501is a deprecated function behaving like 502.Fn EVP_DigestFinal_ex 503except that the digest context 504.Fa ctx 505is automatically cleaned up after use by calling 506.Fn EVP_MD_CTX_reset 507internally. 508.Pp 509.Fn EVP_MD_CTX_copy 510is a deprecated function behaving like 511.Fn EVP_MD_CTX_copy_ex 512except that it requires 513.Fn EVP_MD_CTX_reset 514before a context that was already used can be passed as 515.Fa out . 516.Pp 517.Fn EVP_MD_size 518and 519.Fn EVP_MD_CTX_size 520return the size of the message digest when passed an 521.Vt EVP_MD 522or an 523.Vt EVP_MD_CTX 524structure, i.e. the size of the hash. 525.Pp 526.Fn EVP_MD_block_size 527and 528.Fn EVP_MD_CTX_block_size 529return the block size of the message digest when passed an 530.Vt EVP_MD 531or an 532.Vt EVP_MD_CTX 533structure. 534.Pp 535.Fn EVP_MD_type 536and 537.Fn EVP_MD_CTX_type 538return the NID of the OBJECT IDENTIFIER representing the message digest. 539For example 540.Fn EVP_MD_type EVP_sha1() 541returns 542.Dv NID_sha1 . 543These functions are normally used when setting ASN.1 OIDs. 544.Pp 545.Fn EVP_MD_CTX_md_data 546returns the digest method private data of 547.Fa ctx . 548The space was allocated and its size set with 549.Xr EVP_MD_meth_set_app_datasize 3 . 550.Pp 551.Fn EVP_MD_flags 552returns the 553.Fa md 554flags. 555These are different from the 556.Vt EVP_MD_CTX 557ones. 558See 559.Xr EVP_MD_meth_set_flags 3 560for more information. 561.Pp 562.Fn EVP_MD_pkey_type 563returns the NID of the public key signing algorithm associated with this 564digest. 565For example 566.Fn EVP_sha1 567is associated with RSA so this will return 568.Dv NID_sha1WithRSAEncryption . 569Since digests and signature algorithms are no longer linked, this 570function is only retained for compatibility reasons. 571.Pp 572.Fn EVP_MD_CTX_pkey_ctx 573returns the 574.Vt EVP_PKEY_CTX 575assigned to 576.Fa ctx . 577The returned pointer should not be freed by the caller. 578.Pp 579.Fn EVP_MD_CTX_set_pkey_ctx 580assigns 581.Fa pctx 582to 583.Fa ctx . 584This is normally used to provide a customized 585.Vt EVP_PKEY_CTX 586to 587.Xr EVP_DigestSignInit 3 588or 589.Xr EVP_DigestVerifyInit 3 . 590The caller retains ownership of the 591.Fa pctx 592passed to this function and is responsible for freeing it 593when it is no longer needed. 594.Pp 595If the 596.Fa ctx 597already contains a 598.Vt EVP_PKEY_CTX 599when this function is called, that old 600.Vt EVP_PKEY_CTX 601is freed if it was created internally, but if it was also installed with 602.Fn EVP_MD_CTX_set_pkey_ctx , 603the pointer to the old 604.Vt EVP_PKEY_CTX 605is merely replaced by the new pointer and ownership of the old 606.Vt EVP_PKEY_CTX 607remains with the previous caller. 608.Pp 609Passing a 610.Dv NULL 611pointer for the 612.Fa pctx 613argument is also allowed. 614In that case, any 615.Vt EVP_PKEY_CTX 616already assigned to 617.Fa ctx 618is dissociated from it as described above, but no new 619.Vt EVP_PKEY_CTX 620is assigned. 621.Pp 622.Fn EVP_md5 , 623.Fn EVP_sha1 , 624.Fn EVP_sha224 , 625.Fn EVP_sha256 , 626.Fn EVP_sha384 , 627.Fn EVP_sha512 , 628and 629.Fn EVP_ripemd160 630return 631.Vt EVP_MD 632structures for the MD5, SHA1, SHA224, SHA256, SHA384, SHA512 and 633RIPEMD160 digest algorithms respectively. 634.Pp 635.Fn EVP_sha512_224 636and 637.Fn EVP_sha512_256 638return an 639.Vt EVP_MD 640structure that provides the truncated SHA512 variants SHA512/224 and SHA512/256, 641respectively. 642.Pp 643.Fn EVP_md5_sha1 644returns an 645.Vt EVP_MD 646structure that provides concatenated MD5 and SHA1 message digests. 647.Pp 648.Fn EVP_md_null 649is a "null" message digest that does nothing: 650i.e. the hash it returns is of zero length. 651.Pp 652.Fn EVP_get_digestbyname , 653.Fn EVP_get_digestbynid , 654and 655.Fn EVP_get_digestbyobj 656return an 657.Vt EVP_MD 658structure when passed a digest name, a digest NID, or an ASN1_OBJECT 659structure respectively. 660.Pp 661.Fn EVP_MD_CTX_size , 662.Fn EVP_MD_CTX_block_size , 663.Fn EVP_MD_CTX_type , 664.Fn EVP_get_digestbynid , 665and 666.Fn EVP_get_digestbyobj 667are implemented as macros. 668.Pp 669The EVP interface to message digests should almost always be used 670in preference to the low-level interfaces. 671This is because the code then becomes transparent to the digest used and 672much more flexible. 673.Pp 674New applications should use the SHA2 digest algorithms such as SHA256. 675The other digest algorithms are still in common use. 676.Pp 677For most applications the 678.Fa impl 679parameter to 680.Fn EVP_DigestInit_ex 681will be set to NULL to use the default digest implementation. 682.Pp 683The functions 684.Fn EVP_DigestInit , 685.Fn EVP_DigestFinal , 686and 687.Fn EVP_MD_CTX_copy 688are obsolete but are retained to maintain compatibility with existing 689code. 690New applications should use 691.Fn EVP_DigestInit_ex , 692.Fn EVP_DigestFinal_ex , 693and 694.Fn EVP_MD_CTX_copy_ex 695because they can efficiently reuse a digest context instead of 696initializing and cleaning it up on each call and allow non-default 697implementations of digests to be specified. 698.Pp 699If digest contexts are not cleaned up after use, memory leaks will occur. 700.Sh RETURN VALUES 701.Fn EVP_MD_CTX_new 702and 703.Fn EVP_MD_CTX_create 704return the new 705.Vt EVP_MD_CTX 706object or 707.Dv NULL 708for failure. 709.Pp 710.Fn EVP_MD_CTX_reset 711and 712.Fn EVP_MD_CTX_cleanup 713always return 1. 714.Pp 715.Fn EVP_MD_CTX_ctrl , 716.Fn EVP_DigestInit_ex , 717.Fn EVP_DigestUpdate , 718.Fn EVP_DigestFinal_ex , 719.Fn EVP_Digest , 720.Fn EVP_MD_CTX_copy_ex , 721.Fn EVP_DigestInit , 722.Fn EVP_DigestFinal , 723and 724.Fn EVP_MD_CTX_copy 725return 1 for success or 0 for failure. 726.Pp 727.Fn EVP_MD_CTX_test_flags 728returns the bitwise OR of the 729.Fa flags 730argument and the flags set in 731.Fa ctx . 732.Pp 733.Fn EVP_MD_type , 734.Fn EVP_MD_pkey_type , 735and 736.Fn EVP_MD_CTX_type 737return the NID of the corresponding OBJECT IDENTIFIER or 738.Dv NID_undef 739if none exists. 740.Pp 741.Fn EVP_MD_size , 742.Fn EVP_MD_block_size , 743.Fn EVP_MD_CTX_size , 744and 745.Fn EVP_MD_CTX_block_size 746return the digest or block size in bytes. 747.Pp 748.Fn EVP_MD_CTX_md 749returns the 750.Vt EVP_MD 751object used by 752.Fa ctx , 753or 754.Dv NULL 755if 756.Fa ctx 757is 758.Dv NULL . 759.Pp 760.Fn EVP_md_null , 761.Fn EVP_md5 , 762.Fn EVP_md5_sha1 , 763.Fn EVP_sha1 , 764and 765.Fn EVP_ripemd160 766return pointers to the corresponding 767.Vt EVP_MD 768structures. 769.Pp 770.Fn EVP_get_digestbyname , 771.Fn EVP_get_digestbynid , 772and 773.Fn EVP_get_digestbyobj 774return either an 775.Vt EVP_MD 776structure or 777.Dv NULL 778if an error occurs. 779.Sh EXAMPLES 780This example digests the data "Test Message\en" and "Hello World\en", 781using the digest name passed on the command line. 782.Bd -literal -offset indent 783#include <stdio.h> 784#include <string.h> 785#include <openssl/evp.h> 786 787int 788main(int argc, char *argv[]) 789{ 790 EVP_MD_CTX *mdctx; 791 const EVP_MD *md; 792 const char mess1[] = "Test Message\en"; 793 const char mess2[] = "Hello World\en"; 794 unsigned char md_value[EVP_MAX_MD_SIZE]; 795 unsigned int md_len, i; 796 797 if (argc <= 1) { 798 printf("Usage: mdtest digestname\en"); 799 exit(1); 800 } 801 802 md = EVP_get_digestbyname(argv[1]); 803 if (md == NULL) { 804 printf("Unknown message digest %s\en", argv[1]); 805 exit(1); 806 } 807 808 mdctx = EVP_MD_CTX_new(); 809 EVP_DigestInit_ex(mdctx, md, NULL); 810 EVP_DigestUpdate(mdctx, mess1, strlen(mess1)); 811 EVP_DigestUpdate(mdctx, mess2, strlen(mess2)); 812 EVP_DigestFinal_ex(mdctx, md_value, &md_len); 813 EVP_MD_CTX_free(mdctx); 814 815 printf("Digest is: "); 816 for(i = 0; i < md_len; i++) 817 printf("%02x", md_value[i]); 818 printf("\en"); 819 820 return 0; 821} 822.Ed 823.Sh SEE ALSO 824.Xr BIO_f_md 3 , 825.Xr CMAC_Init 3 , 826.Xr evp 3 , 827.Xr EVP_BytesToKey 3 , 828.Xr EVP_DigestSignInit 3 , 829.Xr EVP_DigestVerifyInit 3 , 830.Xr EVP_MD_meth_new 3 , 831.Xr EVP_PKEY_CTX_set_signature_md 3 , 832.Xr EVP_PKEY_meth_set_signctx 3 , 833.Xr EVP_sha3_224 3 , 834.Xr EVP_SignInit 3 , 835.Xr EVP_sm3 3 , 836.Xr EVP_VerifyInit 3 , 837.Xr EVP_whirlpool 3 , 838.Xr HMAC 3 , 839.Xr OCSP_basic_sign 3 , 840.Xr OCSP_request_sign 3 , 841.Xr PKCS5_PBKDF2_HMAC 3 , 842.Xr PKCS7_sign_add_signer 3 , 843.Xr X509_ALGOR_set_md 3 , 844.Xr X509_digest 3 , 845.Xr X509_sign 3 846.Sh HISTORY 847.Fn EVP_DigestInit , 848.Fn EVP_DigestUpdate , 849.Fn EVP_DigestFinal , 850.Dv EVP_MAX_MD_SIZE , 851.Fn EVP_md5 , 852and 853.Fn EVP_sha1 854first appeared in SSLeay 0.5.1. 855.Fn EVP_MD_size 856first appeared in SSLeay 0.6.6. 857.Fn EVP_MD_CTX_size , 858.Fn EVP_MD_CTX_type , 859.Fn EVP_md_null , 860and 861.Fn EVP_get_digestbyname 862first appeared in SSLeay 0.8.0. 863.Fn EVP_MD_type , 864.Fn EVP_MD_pkey_type , 865.Fn EVP_get_digestbynid , 866and 867.Fn EVP_get_digestbyobj 868first appeared in SSLeay 0.8.1. 869.Fn EVP_MD_block_size , 870.Fn EVP_MD_CTX_size , 871.Fn EVP_MD_CTX_block_size , 872.Fn EVP_rc4_40 , 873.Fn EVP_rc2_40_cbc , 874and 875.Fn EVP_ripemd160 876first appeared in SSLeay 0.9.0. 877All these functions have been available since 878.Ox 2.4 . 879.Pp 880.Fn EVP_MD_CTX_copy 881first appeared in OpenSSL 0.9.2b and has been available since 882.Ox 2.6 . 883.Pp 884.Fn EVP_MD_CTX_md 885first appeared in OpenSSL 0.9.5 and has been available since 886.Ox 2.7 . 887.Pp 888.Fn EVP_MD_CTX_init , 889.Fn EVP_MD_CTX_create , 890.Fn EVP_MD_CTX_cleanup , 891.Fn EVP_MD_CTX_destroy , 892.Fn EVP_MD_CTX_set_flags , 893.Fn EVP_MD_CTX_clear_flags , 894.Fn EVP_MD_CTX_test_flags , 895.Fn EVP_DigestInit_ex , 896.Fn EVP_DigestFinal_ex , 897.Fn EVP_Digest , 898and 899.Fn EVP_MD_CTX_copy_ex 900first appeared in OpenSSL 0.9.7 and have been available since 901.Ox 3.2 . 902.Pp 903.Fn EVP_sha224 , 904.Fn EVP_sha256 , 905.Fn EVP_sha384 , 906and 907.Fn EVP_sha512 908first appeared in OpenSSL 0.9.7h and 0.9.8a 909and have been available since 910.Ox 4.0 . 911.Pp 912.Fn EVP_MD_flags 913first appeared in OpenSSL 1.0.0 914and has been available since 915.Ox 4.9 . 916.Pp 917.Fn EVP_MD_CTX_ctrl 918first appeared in OpenSSL 1.1.0 and has been available since 919.Ox 5.7 . 920.Pp 921.Fn EVP_MD_CTX_new , 922.Fn EVP_MD_CTX_reset , 923.Fn EVP_MD_CTX_free , 924and 925.Fn EVP_md5_sha1 926first appeared in OpenSSL 1.1.0 and have been available since 927.Ox 6.3 . 928.Pp 929.Fn EVP_MD_CTX_md_data 930and 931.Fn EVP_MD_CTX_pkey_ctx 932first appeared in OpenSSL 1.1.0 and 933.Fn EVP_MD_CTX_set_pkey_ctx 934in OpenSSL 1.1.1. 935These functions have been available since 936.Ox 7.1 . 937.Pp 938.Fn EVP_sha512_224 939and 940.Fn EVP_sha512_256 941first appeared in OpenSSL 1.1.1 and have been available since 942.Ox 7.4 . 943.Pp 944The link between digests and signing algorithms was fixed in OpenSSL 1.0 945and later, so now 946.Fn EVP_sha1 947can be used with RSA and DSA. 948