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