1.\" $OpenBSD: EVP_VerifyInit.3,v 1.11 2023/11/16 20:27:43 schwarze 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: November 16 2023 $ 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 *impl" 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 97from 98.Vt ENGINE 99.Fa impl . 100.Fa ctx 101must be initialized by calling 102.Xr EVP_MD_CTX_init 3 103before calling this function. 104.Pp 105.Fn EVP_VerifyUpdate 106hashes 107.Fa cnt 108bytes of data at 109.Fa d 110into the verification context 111.Fa ctx . 112This function can be called several times on the same 113.Fa ctx 114to include additional data. 115.Pp 116.Fn EVP_VerifyFinal 117verifies the data in 118.Fa ctx 119using the public key 120.Fa pkey 121and against the 122.Fa siglen 123bytes at 124.Fa sigbuf . 125.Pp 126.Fn EVP_VerifyInit 127initializes a verification context 128.Fa ctx 129to use the default implementation of digest 130.Fa type . 131.Pp 132The EVP interface to digital signatures should almost always be 133used in preference to the low level interfaces. 134This is because the code then becomes transparent to the algorithm used 135and much more flexible. 136.Pp 137The call to 138.Fn EVP_VerifyFinal 139internally finalizes a copy of the digest context. 140This means that calls to 141.Fn EVP_VerifyUpdate 142and 143.Fn EVP_VerifyFinal 144can be called later to digest and verify additional data. 145.Pp 146Since only a copy of the digest context is ever finalized, the context 147must be cleaned up after use by calling 148.Xr EVP_MD_CTX_free 3 , 149or a memory leak will occur. 150.Pp 151.Fn EVP_VerifyInit_ex , 152.Fn EVP_VerifyUpdate , 153and 154.Fn EVP_VerifyInit 155are implemented as macros. 156.Sh RETURN VALUES 157.Fn EVP_VerifyInit_ex 158and 159.Fn EVP_VerifyUpdate 160return 1 for success and 0 for failure. 161.Pp 162.Fn EVP_VerifyFinal 163returns 1 for a correct signature, 0 for failure, and -1 if some other 164error occurred. 165.Pp 166The error codes can be obtained by 167.Xr ERR_get_error 3 . 168.Sh SEE ALSO 169.Xr evp 3 , 170.Xr EVP_DigestInit 3 , 171.Xr EVP_SignInit 3 172.Sh HISTORY 173.Fn EVP_VerifyInit , 174.Fn EVP_VerifyUpdate , 175and 176.Fn EVP_VerifyFinal 177first appeared in SSLeay 0.5.1 and have been available since 178.Ox 2.4 . 179.Pp 180.Fn EVP_VerifyInit_ex 181first appeared in OpenSSL 0.9.7 and has been available since 182.Ox 3.2 . 183.Sh BUGS 184Older versions of this documentation wrongly stated that calls to 185.Fn EVP_VerifyUpdate 186could not be made after calling 187.Fn EVP_VerifyFinal . 188.Pp 189Since the public key is passed in the call to 190.Xr EVP_SignFinal 3 , 191any error relating to the private key (for example an unsuitable key and 192digest combination) will not be indicated until after potentially large 193amounts of data have been passed through 194.Xr EVP_SignUpdate 3 . 195.Pp 196It is not possible to change the signing parameters using these 197functions. 198.Pp 199The previous two bugs are fixed in the newer functions of the 200.Xr EVP_DigestVerifyInit 3 201family. 202