1.\" $OpenBSD: EVP_DigestInit.3,v 1.15 2018/03/27 17:35:50 schwarze Exp $ 2.\" full merge up to: OpenSSL 7f572e95 Dec 2 13:57:04 2015 +0000 3.\" selective merge up to: OpenSSL a95d7574 Jul 2 12:16:38 2017 -0400 4.\" 5.\" This file was written by Dr. Stephen Henson <steve@openssl.org> 6.\" and Richard Levitte <levitte@openssl.org>. 7.\" Copyright (c) 2000-2004, 2009, 2012-2016 The OpenSSL Project. 8.\" All rights reserved. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 17.\" 2. Redistributions in binary form must reproduce the above copyright 18.\" notice, this list of conditions and the following disclaimer in 19.\" the documentation and/or other materials provided with the 20.\" distribution. 21.\" 22.\" 3. All advertising materials mentioning features or use of this 23.\" software must display the following acknowledgment: 24.\" "This product includes software developed by the OpenSSL Project 25.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 26.\" 27.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 28.\" endorse or promote products derived from this software without 29.\" prior written permission. For written permission, please contact 30.\" openssl-core@openssl.org. 31.\" 32.\" 5. Products derived from this software may not be called "OpenSSL" 33.\" nor may "OpenSSL" appear in their names without prior written 34.\" permission of the OpenSSL Project. 35.\" 36.\" 6. Redistributions of any form whatsoever must retain the following 37.\" acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 40.\" 41.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 42.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 43.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 44.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 45.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 46.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 47.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 48.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 49.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 50.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 51.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 52.\" OF THE POSSIBILITY OF SUCH DAMAGE. 53.\" 54.Dd $Mdocdate: March 27 2018 $ 55.Dt EVP_DIGESTINIT 3 56.Os 57.Sh NAME 58.Nm EVP_MD_CTX_new , 59.Nm EVP_MD_CTX_reset , 60.Nm EVP_MD_CTX_free , 61.Nm EVP_MD_CTX_init , 62.Nm EVP_MD_CTX_create , 63.Nm EVP_MD_CTX_cleanup , 64.Nm EVP_MD_CTX_destroy , 65.Nm EVP_MD_CTX_ctrl , 66.Nm EVP_DigestInit_ex , 67.Nm EVP_DigestUpdate , 68.Nm EVP_DigestFinal_ex , 69.Nm EVP_MD_CTX_copy_ex , 70.Nm EVP_DigestInit , 71.Nm EVP_DigestFinal , 72.Nm EVP_MD_CTX_copy , 73.Nm EVP_MAX_MD_SIZE , 74.Nm EVP_MD_type , 75.Nm EVP_MD_pkey_type , 76.Nm EVP_MD_size , 77.Nm EVP_MD_block_size , 78.Nm EVP_MD_CTX_md , 79.Nm EVP_MD_CTX_size , 80.Nm EVP_MD_CTX_block_size , 81.Nm EVP_MD_CTX_type , 82.Nm EVP_md_null , 83.Nm EVP_md5 , 84.Nm EVP_md5_sha1 , 85.Nm EVP_sha1 , 86.Nm EVP_sha224 , 87.Nm EVP_sha256 , 88.Nm EVP_sha384 , 89.Nm EVP_sha512 , 90.Nm EVP_dss , 91.Nm EVP_dss1 , 92.Nm EVP_ripemd160 , 93.Nm EVP_get_digestbyname , 94.Nm EVP_get_digestbynid , 95.Nm EVP_get_digestbyobj 96.Nd EVP digest routines 97.Sh SYNOPSIS 98.In openssl/evp.h 99.Ft EVP_MD_CTX * 100.Fn EVP_MD_CTX_new void 101.Ft int 102.Fo EVP_MD_CTX_reset 103.Fa "EVP_MD_CTX *ctx" 104.Fc 105.Ft void 106.Fo EVP_MD_CTX_free 107.Fa "EVP_MD_CTX *ctx" 108.Fc 109.Ft void 110.Fo EVP_MD_CTX_init 111.Fa "EVP_MD_CTX *ctx" 112.Fc 113.Ft EVP_MD_CTX * 114.Fn EVP_MD_CTX_create void 115.Ft int 116.Fo EVP_MD_CTX_cleanup 117.Fa "EVP_MD_CTX *ctx" 118.Fc 119.Ft void 120.Fo EVP_MD_CTX_destroy 121.Fa "EVP_MD_CTX *ctx" 122.Fc 123.Ft int 124.Fo EVP_MD_CTX_ctrl 125.Fa "EVP_MD_CTX *ctx" 126.Fa "int cmd" 127.Fa "int p1" 128.Fa "void* p2" 129.Fc 130.Ft int 131.Fo EVP_DigestInit_ex 132.Fa "EVP_MD_CTX *ctx" 133.Fa "const EVP_MD *type" 134.Fa "ENGINE *impl" 135.Fc 136.Ft int 137.Fo EVP_DigestUpdate 138.Fa "EVP_MD_CTX *ctx" 139.Fa "const void *d" 140.Fa "size_t cnt" 141.Fc 142.Ft int 143.Fo EVP_DigestFinal_ex 144.Fa "EVP_MD_CTX *ctx" 145.Fa "unsigned char *md" 146.Fa "unsigned int *s" 147.Fc 148.Ft int 149.Fo EVP_MD_CTX_copy_ex 150.Fa "EVP_MD_CTX *out" 151.Fa "const EVP_MD_CTX *in" 152.Fc 153.Ft int 154.Fo EVP_DigestInit 155.Fa "EVP_MD_CTX *ctx" 156.Fa "const EVP_MD *type" 157.Fc 158.Ft int 159.Fo EVP_DigestFinal 160.Fa "EVP_MD_CTX *ctx" 161.Fa "unsigned char *md" 162.Fa "unsigned int *s" 163.Fc 164.Ft int 165.Fo EVP_MD_CTX_copy 166.Fa "EVP_MD_CTX *out" 167.Fa "EVP_MD_CTX *in" 168.Fc 169.Fd #define EVP_MAX_MD_SIZE 64 /* SHA512 */ 170.Ft int 171.Fo EVP_MD_type 172.Fa "const EVP_MD *md" 173.Fc 174.Ft int 175.Fo EVP_MD_pkey_type 176.Fa "const EVP_MD *md" 177.Fc 178.Ft int 179.Fo EVP_MD_size 180.Fa "const EVP_MD *md" 181.Fc 182.Ft int 183.Fo EVP_MD_block_size 184.Fa "const EVP_MD *md" 185.Fc 186.Ft const EVP_MD * 187.Fo EVP_MD_CTX_md 188.Fa "const EVP_MD_CTX *ctx" 189.Fc 190.Ft int 191.Fo EVP_MD_CTX_size 192.Fa "const EVP_MD *ctx" 193.Fc 194.Ft int 195.Fo EVP_MD_CTX_block_size 196.Fa "const EVP_MD *ctx" 197.Fc 198.Ft int 199.Fo EVP_MD_CTX_type 200.Fa "const EVP_MD *ctx" 201.Fc 202.Ft const EVP_MD * 203.Fn EVP_md_null void 204.Ft const EVP_MD * 205.Fn EVP_md5 void 206.Ft const EVP_MD * 207.Fn EVP_md5_sha1 void 208.Ft const EVP_MD * 209.Fn EVP_sha1 void 210.Ft const EVP_MD * 211.Fn EVP_sha224 void 212.Ft const EVP_MD * 213.Fn EVP_sha256 void 214.Ft const EVP_MD * 215.Fn EVP_sha384 void 216.Ft const EVP_MD * 217.Fn EVP_sha512 void 218.Ft const EVP_MD * 219.Fn EVP_dss void 220.Ft const EVP_MD * 221.Fn EVP_dss1 void 222.Ft const EVP_MD * 223.Fn EVP_ripemd160 void 224.Ft const EVP_MD * 225.Fo EVP_get_digestbyname 226.Fa "const char *name" 227.Fc 228.Ft const EVP_MD * 229.Fo EVP_get_digestbynid 230.Fa "int type" 231.Fc 232.Ft const EVP_MD * 233.Fo EVP_get_digestbyobj 234.Fa "const ASN1_OBJECT *o" 235.Fc 236.Sh DESCRIPTION 237The EVP digest routines are a high level interface to message digests 238and should be used instead of the cipher-specific functions. 239.Pp 240.Fn EVP_MD_CTX_new 241allocates a new, empty digest context. 242.Pp 243.Fn EVP_MD_CTX_reset 244cleans up 245.Fa ctx 246and resets it to the state it had after 247.Fn EVP_MD_CTX_new , 248such that it can be reused. 249It is also suitable for digest contexts on the stack that were 250used and are no longer needed. 251.Pp 252.Fn EVP_MD_CTX_free 253cleans up 254.Fa ctx 255and frees the space allocated to it. 256.Pp 257.Fn EVP_MD_CTX_init 258is a deprecated function to clear a digest context on the stack 259before use. 260Do not use it on a digest context returned from 261.Fn EVP_MD_CTX_new 262or one one that was already used. 263.Pp 264.Fn EVP_MD_CTX_create , 265.Fn EVP_MD_CTX_cleanup , 266and 267.Fn EVP_MD_CTX_destroy 268are deprecated aliases for 269.Fn EVP_MD_CTX_new , 270.Fn EVP_MD_CTX_reset , 271and 272.Fn EVP_MD_CTX_free , 273respectively. 274.Pp 275.Fn EVP_MD_CTX_ctrl 276performs digest-specific control actions on the context 277.Fa ctx . 278.Pp 279.Fn EVP_DigestInit_ex 280sets up the digest context 281.Fa ctx 282to use a digest 283.Fa type 284from 285.Vt ENGINE 286.Fa impl . 287The 288.Fa type 289will typically be supplied by a function such as 290.Fn EVP_sha1 . 291If 292.Fa impl 293is 294.Dv NULL , 295then the default implementation of digest 296.Fa type 297is used. 298If 299.Fa ctx 300points to an unused object on the stack, it must be initialized with 301.Fn EVP_MD_CTX_init 302before calling this function. 303.Pp 304.Fn EVP_DigestUpdate 305hashes 306.Fa cnt 307bytes of data at 308.Fa d 309into the digest context 310.Fa ctx . 311This function can be called several times on the same 312.Fa ctx 313to hash additional data. 314.Pp 315.Fn EVP_DigestFinal_ex 316retrieves the digest value from 317.Fa ctx 318and places it in 319.Fa md . 320If the 321.Fa s 322parameter is not 323.Dv NULL , 324then the number of bytes of data written (i.e. the length of the 325digest) will be written to the integer at 326.Fa s ; 327at most 328.Dv EVP_MAX_MD_SIZE 329bytes will be written. 330After calling 331.Fn EVP_DigestFinal_ex , 332no additional calls to 333.Fn EVP_DigestUpdate 334can be made, but 335.Fn EVP_DigestInit_ex 336can be called to initialize a new digest operation. 337.Pp 338.Fn EVP_MD_CTX_copy_ex 339can be used to copy the message digest state from 340.Fa in 341to 342.Fa out . 343This is useful if large amounts of data are to be hashed which only 344differ in the last few bytes. 345If 346.Fa out 347points to an unused object on the stack, it must be initialized with 348.Fn EVP_MD_CTX_init 349before calling this function. 350.Pp 351.Fn EVP_DigestInit 352is a deprecated function behaving like 353.Fn EVP_DigestInit_ex 354except that it always uses the default digest implementation 355and that it requires 356.Fn EVP_MD_CTX_reset 357before it can be used on a context that was already used. 358.Pp 359.Fn EVP_DigestFinal 360is a deprecated function behaving like 361.Fn EVP_DigestFinal_ex 362except that the digest context 363.Fa ctx 364is automatically cleaned up after use by calling 365.Fn EVP_MD_CTX_reset 366internally. 367.Pp 368.Fn EVP_MD_CTX_copy 369is a deprecated function behaving like 370.Fn EVP_MD_CTX_copy_ex 371except that it requires 372.Fn EVP_MD_CTX_reset 373before a context that was already used can be passed as 374.Fa out . 375.Pp 376.Fn EVP_MD_size 377and 378.Fn EVP_MD_CTX_size 379return the size of the message digest when passed an 380.Vt EVP_MD 381or an 382.Vt EVP_MD_CTX 383structure, i.e. the size of the hash. 384.Pp 385.Fn EVP_MD_block_size 386and 387.Fn EVP_MD_CTX_block_size 388return the block size of the message digest when passed an 389.Vt EVP_MD 390or an 391.Vt EVP_MD_CTX 392structure. 393.Pp 394.Fn EVP_MD_type 395and 396.Fn EVP_MD_CTX_type 397return the NID of the OBJECT IDENTIFIER representing the given message 398digest when passed an 399.Vt EVP_MD 400structure. 401For example 402.Fn EVP_MD_type EVP_sha1() 403returns 404.Dv NID_sha1 . 405This function is normally used when setting ASN.1 OIDs. 406.Pp 407.Fn EVP_MD_pkey_type 408returns the NID of the public key signing algorithm associated with this 409digest. 410For example 411.Fn EVP_sha1 412is associated with RSA so this will return 413.Dv NID_sha1WithRSAEncryption . 414Since digests and signature algorithms are no longer linked this 415function is only retained for compatibility reasons. 416.Pp 417.Fn EVP_md5 , 418.Fn EVP_sha1 , 419.Fn EVP_sha224 , 420.Fn EVP_sha256 , 421.Fn EVP_sha384 , 422.Fn EVP_sha512 , 423and 424.Fn EVP_ripemd160 425return 426.Vt EVP_MD 427structures for the MD5, SHA1, SHA224, SHA256, SHA384, SHA512 and 428RIPEMD160 digest algorithms respectively. 429.Pp 430.Fn EVP_md5_sha1 431returns an 432.Vt EVP_MD 433structure that provides concatenated MD5 and SHA1 message digests. 434.Pp 435.Fn EVP_dss 436and 437.Fn EVP_dss1 438return 439.Vt EVP_MD 440structures for SHA1 digest algorithms but using DSS (DSA) for the 441signature algorithm. 442Note: there is no need to use these pseudo-digests in OpenSSL 1.0.0 and 443later; they are however retained for compatibility. 444.Pp 445.Fn EVP_md_null 446is a "null" message digest that does nothing: 447i.e. the hash it returns is of zero length. 448.Pp 449.Fn EVP_get_digestbyname , 450.Fn EVP_get_digestbynid , 451and 452.Fn EVP_get_digestbyobj 453return an 454.Vt EVP_MD 455structure when passed a digest name, a digest NID, or an ASN1_OBJECT 456structure respectively. 457The digest table must be initialized using, for example, 458.Xr OpenSSL_add_all_digests 3 459for these functions to work. 460.Pp 461.Fn EVP_MD_CTX_size , 462.Fn EVP_MD_CTX_block_size , 463.Fn EVP_MD_CTX_type , 464.Fn EVP_get_digestbynid , 465and 466.Fn EVP_get_digestbyobj 467are implemented as macros. 468.Pp 469The EVP interface to message digests should almost always be used 470in preference to the low level interfaces. 471This is because the code then becomes transparent to the digest used and 472much more flexible. 473.Pp 474New applications should use the SHA2 digest algorithms such as SHA256. 475The other digest algorithms are still in common use. 476.Pp 477For most applications the 478.Fa impl 479parameter to 480.Fn EVP_DigestInit_ex 481will be set to NULL to use the default digest implementation. 482.Pp 483The functions 484.Fn EVP_DigestInit , 485.Fn EVP_DigestFinal , 486and 487.Fn EVP_MD_CTX_copy 488are obsolete but are retained to maintain compatibility with existing 489code. 490New applications should use 491.Fn EVP_DigestInit_ex , 492.Fn EVP_DigestFinal_ex , 493and 494.Fn EVP_MD_CTX_copy_ex 495because they can efficiently reuse a digest context instead of 496initializing and cleaning it up on each call and allow non-default 497implementations of digests to be specified. 498.Pp 499If digest contexts are not cleaned up after use, memory leaks will occur. 500.Sh RETURN VALUES 501.Fn EVP_MD_CTX_new 502and 503.Fn EVP_MD_CTX_create 504return the new 505.Vt EVP_MD_CTX 506object or 507.Dv NULL 508for failure. 509.Pp 510.Fn EVP_MD_CTX_reset 511and 512.Fn EVP_MD_CTX_cleanup 513always return 1. 514.Pp 515.Fn EVP_MD_CTX_ctrl , 516.Fn EVP_DigestInit_ex , 517.Fn EVP_DigestUpdate , 518.Fn EVP_DigestFinal_ex , 519.Fn EVP_MD_CTX_copy_ex , 520.Fn EVP_DigestInit , 521.Fn EVP_DigestFinal , 522and 523.Fn EVP_MD_CTX_copy 524return 1 for success or 0 for failure. 525.Pp 526.Fn EVP_MD_type , 527.Fn EVP_MD_pkey_type , 528and 529.Fn EVP_MD_CTX_type 530return the NID of the corresponding OBJECT IDENTIFIER or 531.Dv NID_undef 532if none exists. 533.Pp 534.Fn EVP_MD_size , 535.Fn EVP_MD_block_size , 536.Fn EVP_MD_CTX_size , 537and 538.Fn EVP_MD_CTX_block_size 539return the digest or block size in bytes. 540.Pp 541.Fn EVP_MD_CTX_md 542returns the 543.Vt EVP_MD 544object used by 545.Fa ctx , 546or 547.Dv NULL 548if 549.Fa ctx 550is 551.Dv NULL . 552.Pp 553.Fn EVP_md_null , 554.Fn EVP_md5 , 555.Fn EVP_md5_sha1 , 556.Fn EVP_sha1 , 557.Fn EVP_dss , 558.Fn EVP_dss1 , 559and 560.Fn EVP_ripemd160 561return pointers to the corresponding 562.Vt EVP_MD 563structures. 564.Pp 565.Fn EVP_get_digestbyname , 566.Fn EVP_get_digestbynid , 567and 568.Fn EVP_get_digestbyobj 569return either an 570.Vt EVP_MD 571structure or 572.Dv NULL 573if an error occurs. 574.Sh EXAMPLES 575This example digests the data "Test Message\en" and "Hello World\en", 576using the digest name passed on the command line. 577.Bd -literal -offset indent 578#include <stdio.h> 579#include <openssl/evp.h> 580 581int 582main(int argc, char *argv[]) 583{ 584 EVP_MD_CTX *mdctx; 585 const EVP_MD *md; 586 const char mess1[] = "Test Message\en"; 587 const char mess2[] = "Hello World\en"; 588 unsigned char md_value[EVP_MAX_MD_SIZE]; 589 int md_len, i; 590 591 OpenSSL_add_all_digests(); 592 593 if (argc <= 1) { 594 printf("Usage: mdtest digestname\en"); 595 exit(1); 596 } 597 598 md = EVP_get_digestbyname(argv[1]); 599 if (md == NULL) { 600 printf("Unknown message digest %s\en", argv[1]); 601 exit(1); 602 } 603 604 mdctx = EVP_MD_CTX_new(); 605 EVP_DigestInit_ex(mdctx, md, NULL); 606 EVP_DigestUpdate(mdctx, mess1, strlen(mess1)); 607 EVP_DigestUpdate(mdctx, mess2, strlen(mess2)); 608 EVP_DigestFinal_ex(mdctx, md_value, &md_len); 609 EVP_MD_CTX_free(mdctx); 610 611 printf("Digest is: "); 612 for(i = 0; i < md_len; i++) 613 printf("%02x", md_value[i]); 614 printf("\en"); 615 616 return 0; 617} 618.Ed 619.Sh SEE ALSO 620.Xr evp 3 621.Sh HISTORY 622.Fn EVP_DigestInit , 623.Fn EVP_DigestUpdate , 624.Fn EVP_DigestFinal , 625.Dv EVP_MAX_MD_SIZE , 626.Fn EVP_md5 , 627and 628.Fn EVP_sha1 629first appeared in SSLeay 0.5.1. 630.Fn EVP_dss 631and 632.Fn EVP_dss1 633first appeared in SSLeay 0.6.0. 634.Fn EVP_MD_size 635first appeared in SSLeay 0.6.6. 636.Fn EVP_MD_CTX_size , 637.Fn EVP_MD_CTX_type , 638.Fn EVP_md_null , 639and 640.Fn EVP_get_digestbyname 641first appeared in SSLeay 0.8.0. 642.Fn EVP_MD_type , 643.Fn EVP_MD_pkey_type , 644.Fn EVP_get_digestbynid , 645and 646.Fn EVP_get_digestbyobj 647first appeared in SSLeay 0.8.1. 648.Fn EVP_MD_block_size , 649.Fn EVP_MD_CTX_size , 650.Fn EVP_MD_CTX_block_size , 651.Fn EVP_rc4_40 , 652.Fn EVP_rc2_40_cbc , 653and 654.Fn EVP_ripemd160 655first appeared in SSLeay 0.9.0. 656All these functions have been available since 657.Ox 2.4 . 658.Pp 659.Fn EVP_MD_CTX_copy 660first appeared in OpenSSL 0.9.2b and has been available since 661.Ox 2.6 . 662.Pp 663.Fn EVP_MD_CTX_md 664first appeared in OpenSSL 0.9.5 and has been available since 665.Ox 2.7 . 666.Pp 667.Fn EVP_MD_CTX_init , 668.Fn EVP_MD_CTX_create , 669.Fn EVP_MD_CTX_cleanup , 670.Fn EVP_MD_CTX_destroy , 671.Fn EVP_DigestInit_ex , 672.Fn EVP_DigestFinal_ex , 673and 674.Fn EVP_MD_CTX_copy_ex 675first appeared in OpenSSL 0.9.7 and have been available since 676.Ox 3.2 . 677.Pp 678.Fn EVP_sha224 , 679.Fn EVP_sha256 , 680.Fn EVP_sha384 , 681and 682.Fn EVP_sha512 683first appeared in OpenSSL 0.9.7h and 0.9.8a 684and have been available since 685.Ox 4.0 . 686.Pp 687.Fn EVP_MD_CTX_ctrl 688first appeared in OpenSSL 1.1.0 and has been available since 689.Ox 5.7 . 690.Pp 691.Fn EVP_MD_CTX_new , 692.Fn EVP_MD_CTX_reset , 693.Fn EVP_MD_CTX_free , 694and 695.Fn EVP_md5_sha1 696first appeared in OpenSSL 1.1.0 and have been available since 697.Ox 6.3 . 698.Pp 699The link between digests and signing algorithms was fixed in OpenSSL 1.0 700and later, so now 701.Fn EVP_sha1 702can be used with RSA and DSA; there is no need to use 703.Fn EVP_dss1 704any more. 705