1.\" $OpenBSD: EVP_DigestInit.3,v 1.33 2024/03/19 17:34:05 tb 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: March 19 2024 $ 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_DigestInit_ex , 85.Nm EVP_DigestUpdate , 86.Nm EVP_DigestFinal_ex , 87.Nm EVP_Digest , 88.Nm EVP_MD_CTX_copy_ex , 89.Nm EVP_DigestInit , 90.Nm EVP_DigestFinal , 91.Nm EVP_MD_CTX_copy , 92.Nm EVP_MD_CTX_md , 93.Nm EVP_md_null , 94.Nm EVP_sha224 , 95.Nm EVP_sha256 , 96.Nm EVP_sha384 , 97.Nm EVP_sha512 , 98.Nm EVP_sha512_224 , 99.Nm EVP_sha512_256 , 100.Nm EVP_ripemd160 , 101.Nm EVP_get_digestbyname , 102.Nm EVP_get_digestbynid , 103.Nm EVP_get_digestbyobj 104.Nd EVP digest routines 105.Sh SYNOPSIS 106.In openssl/evp.h 107.Ft EVP_MD_CTX * 108.Fn EVP_MD_CTX_new void 109.Ft int 110.Fo EVP_MD_CTX_reset 111.Fa "EVP_MD_CTX *ctx" 112.Fc 113.Ft void 114.Fo EVP_MD_CTX_free 115.Fa "EVP_MD_CTX *ctx" 116.Fc 117.Ft void 118.Fo EVP_MD_CTX_init 119.Fa "EVP_MD_CTX *ctx" 120.Fc 121.Ft EVP_MD_CTX * 122.Fn EVP_MD_CTX_create void 123.Ft int 124.Fo EVP_MD_CTX_cleanup 125.Fa "EVP_MD_CTX *ctx" 126.Fc 127.Ft void 128.Fo EVP_MD_CTX_destroy 129.Fa "EVP_MD_CTX *ctx" 130.Fc 131.Ft int 132.Fo EVP_DigestInit_ex 133.Fa "EVP_MD_CTX *ctx" 134.Fa "const EVP_MD *type" 135.Fa "ENGINE *impl" 136.Fc 137.Ft int 138.Fo EVP_DigestUpdate 139.Fa "EVP_MD_CTX *ctx" 140.Fa "const void *d" 141.Fa "size_t cnt" 142.Fc 143.Ft int 144.Fo EVP_DigestFinal_ex 145.Fa "EVP_MD_CTX *ctx" 146.Fa "unsigned char *md" 147.Fa "unsigned int *s" 148.Fc 149.Ft int 150.Fo EVP_Digest 151.Fa "const void *d" 152.Fa "size_t cnt" 153.Fa "unsigned char *md" 154.Fa "unsigned int *s" 155.Fa "const EVP_MD *type" 156.Fa "ENGINE *impl" 157.Fc 158.Ft int 159.Fo EVP_MD_CTX_copy_ex 160.Fa "EVP_MD_CTX *out" 161.Fa "const EVP_MD_CTX *in" 162.Fc 163.Ft int 164.Fo EVP_DigestInit 165.Fa "EVP_MD_CTX *ctx" 166.Fa "const EVP_MD *type" 167.Fc 168.Ft int 169.Fo EVP_DigestFinal 170.Fa "EVP_MD_CTX *ctx" 171.Fa "unsigned char *md" 172.Fa "unsigned int *s" 173.Fc 174.Ft int 175.Fo EVP_MD_CTX_copy 176.Fa "EVP_MD_CTX *out" 177.Fa "EVP_MD_CTX *in" 178.Fc 179.Ft const EVP_MD * 180.Fo EVP_MD_CTX_md 181.Fa "const EVP_MD_CTX *ctx" 182.Fc 183.Ft const EVP_MD * 184.Fn EVP_md_null void 185.Ft const EVP_MD * 186.Fn EVP_sha224 void 187.Ft const EVP_MD * 188.Fn EVP_sha256 void 189.Ft const EVP_MD * 190.Fn EVP_sha384 void 191.Ft const EVP_MD * 192.Fn EVP_sha512 void 193.Ft const EVP_MD * 194.Fn EVP_sha512_224 void 195.Ft const EVP_MD * 196.Fn EVP_sha512_256 void 197.Ft const EVP_MD * 198.Fn EVP_ripemd160 void 199.Ft const EVP_MD * 200.Fo EVP_get_digestbyname 201.Fa "const char *name" 202.Fc 203.Ft const EVP_MD * 204.Fo EVP_get_digestbynid 205.Fa "int type" 206.Fc 207.Ft const EVP_MD * 208.Fo EVP_get_digestbyobj 209.Fa "const ASN1_OBJECT *o" 210.Fc 211.Sh DESCRIPTION 212The EVP digest routines are a high-level interface to message digests 213and should be used instead of the cipher-specific functions. 214.Pp 215.Fn EVP_MD_CTX_new 216allocates a new, empty digest context. 217.Pp 218.Fn EVP_MD_CTX_reset 219cleans up 220.Fa ctx 221and resets it to the state it had after 222.Fn EVP_MD_CTX_new , 223such that it can be reused. 224.Pp 225.Fn EVP_MD_CTX_free 226cleans up 227.Fa ctx 228and frees the space allocated to it. 229.Pp 230.Fn EVP_MD_CTX_init 231is a deprecated function to clear a digest context on the stack 232before use. 233Do not use it on a digest context returned from 234.Fn EVP_MD_CTX_new 235or one that was already used. 236.Pp 237.Fn EVP_MD_CTX_create , 238.Fn EVP_MD_CTX_cleanup , 239and 240.Fn EVP_MD_CTX_destroy 241are deprecated aliases for 242.Fn EVP_MD_CTX_new , 243.Fn EVP_MD_CTX_reset , 244and 245.Fn EVP_MD_CTX_free , 246respectively. 247.Pp 248.Fn EVP_DigestInit_ex 249sets up the digest context 250.Fa ctx 251to use a digest 252.Fa type 253from 254.Vt ENGINE 255.Fa impl . 256The 257.Fa type 258will typically be supplied by a function such as 259.Fn EVP_sha512 . 260If 261.Fa impl 262is 263.Dv NULL , 264then the default implementation of digest 265.Fa type 266is used. 267.Pp 268.Fn EVP_DigestUpdate 269hashes 270.Fa cnt 271bytes of data at 272.Fa d 273into the digest context 274.Fa ctx . 275This function can be called several times on the same 276.Fa ctx 277to hash additional data. 278.Pp 279.Fn EVP_DigestFinal_ex 280retrieves the digest value from 281.Fa ctx 282and places it in 283.Fa md . 284If the 285.Fa s 286parameter is not 287.Dv NULL , 288then the number of bytes of data written (i.e. the length of the 289digest) will be written to the integer at 290.Fa s ; 291at most 292.Dv EVP_MAX_MD_SIZE 293bytes will be written. 294After calling 295.Fn EVP_DigestFinal_ex , 296no additional calls to 297.Fn EVP_DigestUpdate 298can be made, but 299.Fn EVP_DigestInit_ex 300can be called to initialize a new digest operation. 301.Pp 302.Fn EVP_Digest 303is a simple wrapper function to hash 304.Fa cnt 305bytes of data at 306.Fa d 307using the digest 308.Fa type 309from 310.Vt ENGINE 311.Fa impl 312in a one-shot operation and place the digest value into 313.Fa md , 314and, unless 315.Fa s 316is 317.Dv NULL , 318the length of the digest in bytes into 319.Pf * Fa s . 320This wrapper uses a temporary digest context and passes its arguments to 321.Fn EVP_DigestInit_ex , 322.Fn EVP_DigestUpdate , 323and 324.Fn EVP_DigestFinal_ex 325internally. 326.Pp 327.Fn EVP_MD_CTX_copy_ex 328can be used to copy the message digest state from 329.Fa in 330to 331.Fa out . 332This is useful if large amounts of data are to be hashed which only 333differ in the last few bytes. 334.Pp 335.Fn EVP_DigestInit 336is a deprecated function behaving like 337.Fn EVP_DigestInit_ex 338except that it always uses the default digest implementation 339and that it requires 340.Fn EVP_MD_CTX_reset 341before it can be used on a context that was already used. 342.Pp 343.Fn EVP_DigestFinal 344is a deprecated function behaving like 345.Fn EVP_DigestFinal_ex 346except that the digest context 347.Fa ctx 348is automatically cleaned up after use by calling 349.Fn EVP_MD_CTX_reset 350internally. 351.Pp 352.Fn EVP_MD_CTX_copy 353is a deprecated function behaving like 354.Fn EVP_MD_CTX_copy_ex 355except that it requires 356.Fn EVP_MD_CTX_reset 357before a context that was already used can be passed as 358.Fa out . 359.Pp 360.Fn EVP_sha224 , 361.Fn EVP_sha256 , 362.Fn EVP_sha384 , 363.Fn EVP_sha512 , 364and 365.Fn EVP_ripemd160 366return 367.Vt EVP_MD 368structures for the SHA224, SHA256, SHA384, SHA512 and 369RIPEMD160 digest algorithms respectively. 370.Pp 371.Fn EVP_sha512_224 372and 373.Fn EVP_sha512_256 374return an 375.Vt EVP_MD 376structure that provides the truncated SHA512 variants SHA512/224 and SHA512/256, 377respectively. 378.Pp 379.Fn EVP_md_null 380is a "null" message digest that does nothing: 381i.e. the hash it returns is of zero length. 382.Pp 383.Fn EVP_get_digestbyname , 384.Fn EVP_get_digestbynid , 385and 386.Fn EVP_get_digestbyobj 387return an 388.Vt EVP_MD 389structure when passed a digest name, a digest NID, or an ASN1_OBJECT 390structure respectively. 391.Pp 392.Fn EVP_get_digestbynid 393and 394.Fn EVP_get_digestbyobj 395are implemented as macros. 396.Pp 397The EVP interface to message digests should almost always be used 398in preference to the low-level interfaces. 399This is because the code then becomes transparent to the digest used and 400much more flexible. 401.Pp 402For most applications the 403.Fa impl 404parameter to 405.Fn EVP_DigestInit_ex 406will be set to NULL to use the default digest implementation. 407.Pp 408The functions 409.Fn EVP_DigestInit , 410.Fn EVP_DigestFinal , 411and 412.Fn EVP_MD_CTX_copy 413are obsolete but are retained to maintain compatibility with existing 414code. 415New applications should use 416.Fn EVP_DigestInit_ex , 417.Fn EVP_DigestFinal_ex , 418and 419.Fn EVP_MD_CTX_copy_ex 420because they can efficiently reuse a digest context instead of 421initializing and cleaning it up on each call and allow non-default 422implementations of digests to be specified. 423.Pp 424If digest contexts are not cleaned up after use, memory leaks will occur. 425.Sh RETURN VALUES 426.Fn EVP_MD_CTX_new 427and 428.Fn EVP_MD_CTX_create 429return the new 430.Vt EVP_MD_CTX 431object or 432.Dv NULL 433for failure. 434.Pp 435.Fn EVP_MD_CTX_reset 436and 437.Fn EVP_MD_CTX_cleanup 438always return 1. 439.Pp 440.Fn EVP_DigestInit_ex , 441.Fn EVP_DigestUpdate , 442.Fn EVP_DigestFinal_ex , 443.Fn EVP_Digest , 444.Fn EVP_MD_CTX_copy_ex , 445.Fn EVP_DigestInit , 446.Fn EVP_DigestFinal , 447and 448.Fn EVP_MD_CTX_copy 449return 1 for success or 0 for failure. 450.Pp 451.Fn EVP_MD_CTX_md 452returns the 453.Vt EVP_MD 454object used by 455.Fa ctx , 456or 457.Dv NULL 458if 459.Fa ctx 460is 461.Dv NULL 462or does not have any message digest algorithm assigned yet. 463.Pp 464.Fn EVP_md_null , 465.Fn EVP_sha224 , 466.Fn EVP_sha256 , 467.Fn EVP_sha384 , 468.Fn EVP_sha512 , 469.Fn EVP_sha512_224 , 470.Fn EVP_sha512_256 , 471and 472.Fn EVP_ripemd160 473return pointers to constant static objects owned by the library. 474.Pp 475.Fn EVP_get_digestbyname , 476.Fn EVP_get_digestbynid , 477and 478.Fn EVP_get_digestbyobj 479return either an 480.Vt EVP_MD 481structure or 482.Dv NULL 483if an error occurs. 484.Sh EXAMPLES 485This example digests the data "Test Message\en" and "Hello World\en", 486using the digest name passed on the command line. 487.Bd -literal -offset indent 488#include <stdio.h> 489#include <string.h> 490#include <openssl/evp.h> 491 492int 493main(int argc, char *argv[]) 494{ 495 EVP_MD_CTX *mdctx; 496 const EVP_MD *md; 497 const char mess1[] = "Test Message\en"; 498 const char mess2[] = "Hello World\en"; 499 unsigned char md_value[EVP_MAX_MD_SIZE]; 500 unsigned int md_len, i; 501 502 if (argc <= 1) { 503 printf("Usage: mdtest digestname\en"); 504 exit(1); 505 } 506 507 md = EVP_get_digestbyname(argv[1]); 508 if (md == NULL) { 509 printf("Unknown message digest %s\en", argv[1]); 510 exit(1); 511 } 512 513 mdctx = EVP_MD_CTX_new(); 514 EVP_DigestInit_ex(mdctx, md, NULL); 515 EVP_DigestUpdate(mdctx, mess1, strlen(mess1)); 516 EVP_DigestUpdate(mdctx, mess2, strlen(mess2)); 517 EVP_DigestFinal_ex(mdctx, md_value, &md_len); 518 EVP_MD_CTX_free(mdctx); 519 520 printf("Digest is: "); 521 for(i = 0; i < md_len; i++) 522 printf("%02x", md_value[i]); 523 printf("\en"); 524 525 return 0; 526} 527.Ed 528.Sh SEE ALSO 529.Xr BIO_f_md 3 , 530.Xr CMAC_Init 3 , 531.Xr evp 3 , 532.Xr EVP_BytesToKey 3 , 533.Xr EVP_DigestSignInit 3 , 534.Xr EVP_DigestVerifyInit 3 , 535.Xr EVP_MD_CTX_ctrl 3 , 536.Xr EVP_MD_nid 3 , 537.Xr EVP_PKEY_CTX_set_signature_md 3 , 538.Xr EVP_PKEY_meth_set_signctx 3 , 539.Xr EVP_sha1 3 , 540.Xr EVP_sha3_224 3 , 541.Xr EVP_SignInit 3 , 542.Xr EVP_sm3 3 , 543.Xr EVP_VerifyInit 3 , 544.Xr EVP_whirlpool 3 , 545.Xr HMAC 3 , 546.Xr OCSP_basic_sign 3 , 547.Xr OCSP_request_sign 3 , 548.Xr PKCS5_PBKDF2_HMAC 3 , 549.Xr PKCS7_sign_add_signer 3 , 550.Xr X509_ALGOR_set0 3 , 551.Xr X509_digest 3 , 552.Xr X509_sign 3 553.Sh HISTORY 554.Fn EVP_DigestInit , 555.Fn EVP_DigestUpdate , 556and 557.Fn EVP_DigestFinal 558first appeared in SSLeay 0.5.1. 559.Fn EVP_md_null 560and 561.Fn EVP_get_digestbyname 562first appeared in SSLeay 0.8.0. 563.Fn EVP_get_digestbynid 564and 565.Fn EVP_get_digestbyobj 566first appeared in SSLeay 0.8.1. 567.Fn EVP_ripemd160 568first appeared in SSLeay 0.9.0. 569All these functions have been available since 570.Ox 2.4 . 571.Pp 572.Fn EVP_MD_CTX_copy 573first appeared in OpenSSL 0.9.2b and has been available since 574.Ox 2.6 . 575.Pp 576.Fn EVP_MD_CTX_md 577first appeared in OpenSSL 0.9.5 and has been available since 578.Ox 2.7 . 579.Pp 580.Fn EVP_MD_CTX_init , 581.Fn EVP_MD_CTX_create , 582.Fn EVP_MD_CTX_cleanup , 583.Fn EVP_MD_CTX_destroy , 584.Fn EVP_DigestInit_ex , 585.Fn EVP_DigestFinal_ex , 586.Fn EVP_Digest , 587and 588.Fn EVP_MD_CTX_copy_ex 589first appeared in OpenSSL 0.9.7 and have been available since 590.Ox 3.2 . 591.Pp 592.Fn EVP_sha224 , 593.Fn EVP_sha256 , 594.Fn EVP_sha384 , 595and 596.Fn EVP_sha512 597first appeared in OpenSSL 0.9.7h and 0.9.8a 598and have been available since 599.Ox 4.0 . 600.Pp 601.Fn EVP_MD_CTX_new , 602.Fn EVP_MD_CTX_reset , 603and 604.Fn EVP_MD_CTX_free 605first appeared in OpenSSL 1.1.0 and have been available since 606.Ox 6.3 . 607.Pp 608.Fn EVP_sha512_224 609and 610.Fn EVP_sha512_256 611first appeared in OpenSSL 1.1.1 and have been available since 612.Ox 7.4 . 613