1.\" $OpenBSD: EVP_VerifyInit.3,v 1.12 2024/07/21 08:36:43 tb Exp $ 2.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 3.\" selective merge up to: OpenSSL 79b49fb0 Mar 20 10:03:10 2018 +1000 4.\" 5.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 6.\" Copyright (c) 2000, 2001, 2006, 2016 The OpenSSL Project. 7.\" All rights reserved. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in 18.\" the documentation and/or other materials provided with the 19.\" distribution. 20.\" 21.\" 3. All advertising materials mentioning features or use of this 22.\" software must display the following acknowledgment: 23.\" "This product includes software developed by the OpenSSL Project 24.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 25.\" 26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 27.\" endorse or promote products derived from this software without 28.\" prior written permission. For written permission, please contact 29.\" openssl-core@openssl.org. 30.\" 31.\" 5. Products derived from this software may not be called "OpenSSL" 32.\" nor may "OpenSSL" appear in their names without prior written 33.\" permission of the OpenSSL Project. 34.\" 35.\" 6. Redistributions of any form whatsoever must retain the following 36.\" acknowledgment: 37.\" "This product includes software developed by the OpenSSL Project 38.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 39.\" 40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 43.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 51.\" OF THE POSSIBILITY OF SUCH DAMAGE. 52.\" 53.Dd $Mdocdate: July 21 2024 $ 54.Dt EVP_VERIFYINIT 3 55.Os 56.Sh NAME 57.Nm EVP_VerifyInit_ex , 58.Nm EVP_VerifyUpdate , 59.Nm EVP_VerifyFinal , 60.Nm EVP_VerifyInit 61.Nd EVP signature verification functions 62.Sh SYNOPSIS 63.In openssl/evp.h 64.Ft int 65.Fo EVP_VerifyInit_ex 66.Fa "EVP_MD_CTX *ctx" 67.Fa "const EVP_MD *type" 68.Fa "ENGINE *engine" 69.Fc 70.Ft int 71.Fo EVP_VerifyUpdate 72.Fa "EVP_MD_CTX *ctx" 73.Fa "const void *d" 74.Fa "unsigned int cnt" 75.Fc 76.Ft int 77.Fo EVP_VerifyFinal 78.Fa "EVP_MD_CTX *ctx" 79.Fa "unsigned char *sigbuf" 80.Fa "unsigned int siglen" 81.Fa "EVP_PKEY *pkey" 82.Fc 83.Ft int 84.Fo EVP_VerifyInit 85.Fa "EVP_MD_CTX *ctx" 86.Fa "const EVP_MD *type" 87.Fc 88.Sh DESCRIPTION 89The EVP signature verification routines are a high level interface to 90digital signatures. 91.Pp 92.Fn EVP_VerifyInit_ex 93sets up a verification context 94.Fa ctx 95to use the digest 96.Fa type . 97.Fa ctx 98must be initialized by calling 99.Xr EVP_MD_CTX_init 3 100before calling this function. 101The 102.Fa ENGINE *engine 103argument is always ignored and passing 104.Dv NULL 105is recommended. 106.Pp 107.Fn EVP_VerifyUpdate 108hashes 109.Fa cnt 110bytes of data at 111.Fa d 112into the verification context 113.Fa ctx . 114This function can be called several times on the same 115.Fa ctx 116to include additional data. 117.Pp 118.Fn EVP_VerifyFinal 119verifies the data in 120.Fa ctx 121using the public key 122.Fa pkey 123and against the 124.Fa siglen 125bytes at 126.Fa sigbuf . 127.Pp 128.Fn EVP_VerifyInit 129initializes a verification context 130.Fa ctx 131to use the default implementation of digest 132.Fa type . 133.Pp 134The EVP interface to digital signatures should almost always be 135used in preference to the low level interfaces. 136This is because the code then becomes transparent to the algorithm used 137and much more flexible. 138.Pp 139The call to 140.Fn EVP_VerifyFinal 141internally finalizes a copy of the digest context. 142This means that calls to 143.Fn EVP_VerifyUpdate 144and 145.Fn EVP_VerifyFinal 146can be called later to digest and verify additional data. 147.Pp 148Since only a copy of the digest context is ever finalized, the context 149must be cleaned up after use by calling 150.Xr EVP_MD_CTX_free 3 , 151or a memory leak will occur. 152.Pp 153.Fn EVP_VerifyInit_ex , 154.Fn EVP_VerifyUpdate , 155and 156.Fn EVP_VerifyInit 157are implemented as macros. 158.Sh RETURN VALUES 159.Fn EVP_VerifyInit_ex 160and 161.Fn EVP_VerifyUpdate 162return 1 for success and 0 for failure. 163.Pp 164.Fn EVP_VerifyFinal 165returns 1 for a correct signature, 0 for failure, and -1 if some other 166error occurred. 167.Pp 168The error codes can be obtained by 169.Xr ERR_get_error 3 . 170.Sh SEE ALSO 171.Xr evp 3 , 172.Xr EVP_DigestInit 3 , 173.Xr EVP_SignInit 3 174.Sh HISTORY 175.Fn EVP_VerifyInit , 176.Fn EVP_VerifyUpdate , 177and 178.Fn EVP_VerifyFinal 179first appeared in SSLeay 0.5.1 and have been available since 180.Ox 2.4 . 181.Pp 182.Fn EVP_VerifyInit_ex 183first appeared in OpenSSL 0.9.7 and has been available since 184.Ox 3.2 . 185.Sh BUGS 186Older versions of this documentation wrongly stated that calls to 187.Fn EVP_VerifyUpdate 188could not be made after calling 189.Fn EVP_VerifyFinal . 190.Pp 191Since the public key is passed in the call to 192.Xr EVP_SignFinal 3 , 193any error relating to the private key (for example an unsuitable key and 194digest combination) will not be indicated until after potentially large 195amounts of data have been passed through 196.Xr EVP_SignUpdate 3 . 197.Pp 198It is not possible to change the signing parameters using these 199functions. 200.Pp 201The previous two bugs are fixed in the newer functions of the 202.Xr EVP_DigestVerifyInit 3 203family. 204