1.\" $OpenBSD: EVP_DigestVerifyInit.3,v 1.17 2024/12/06 14:27:49 schwarze Exp $ 2.\" full merge up to OpenSSL f097e875 Aug 23 11:37:22 2018 +0100 3.\" selective merge up to 24a535ea Sep 22 13:14:20 2020 +0100 4.\" 5.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 6.\" Copyright (c) 2006, 2009, 2014, 2015, 2016, 2017 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: December 6 2024 $ 54.Dt EVP_DIGESTVERIFYINIT 3 55.Os 56.Sh NAME 57.Nm EVP_DigestVerifyInit , 58.Nm EVP_DigestVerifyUpdate , 59.Nm EVP_DigestVerifyFinal , 60.Nm EVP_DigestVerify 61.Nd EVP signature verification functions 62.Sh SYNOPSIS 63.In openssl/evp.h 64.Ft int 65.Fo EVP_DigestVerifyInit 66.Fa "EVP_MD_CTX *ctx" 67.Fa "EVP_PKEY_CTX **pctx" 68.Fa "const EVP_MD *type" 69.Fa "ENGINE *engine" 70.Fa "EVP_PKEY *pkey" 71.Fc 72.Ft int 73.Fo EVP_DigestVerifyUpdate 74.Fa "EVP_MD_CTX *ctx" 75.Fa "const void *d" 76.Fa "size_t cnt" 77.Fc 78.Ft int 79.Fo EVP_DigestVerifyFinal 80.Fa "EVP_MD_CTX *ctx" 81.Fa "const unsigned char *sig" 82.Fa "size_t siglen" 83.Fc 84.Ft int 85.Fo EVP_DigestVerify 86.Fa "EVP_MD_CTX *ctx" 87.Fa "const unsigned char *sig" 88.Fa "size_t siglen" 89.Fa "const unsigned char *tbs" 90.Fa "size_t *tbslen" 91.Fc 92.Sh DESCRIPTION 93The EVP signature routines are a high-level interface to digital 94signatures. 95.Pp 96.Fn EVP_DigestVerifyInit 97sets up the verification context 98.Fa ctx 99to use the digest 100.Fa type 101and the public key 102.Fa pkey . 103Before calling this function, obtain 104.Fa ctx 105from 106.Xr EVP_MD_CTX_new 3 107or call 108.Xr EVP_MD_CTX_reset 3 109on it. 110The 111.Fa engine 112argument is always ignored and passing 113.Dv NULL 114is recommended. 115.Pp 116If 117.Fa pctx 118is not 119.Dv NULL , 120any pointer passed in as 121.Pf * Fa pctx 122is ignored and overwritten by an internal pointer to the 123.Vt EVP_PKEY_CTX 124used by the verification operation: 125this can be used to set alternative signing options. 126The returned 127.Vt EVP_PKEY_CTX 128must not be freed by the application. 129It is freed automatically when the 130.Vt EVP_MD_CTX 131is freed. 132.Pp 133.Fn EVP_DigestVerifyUpdate 134hashes 135.Fa cnt 136bytes of data at 137.Fa d 138into the verification context 139.Fa ctx . 140This function can be called several times on the same 141.Fa ctx 142to include additional data. 143This function is currently implemented using a macro. 144.Pp 145.Fn EVP_DigestVerifyFinal 146verifies the data in 147.Fa ctx 148against the signature in 149.Fa sig 150of length 151.Fa siglen . 152.Pp 153.Fn EVP_DigestVerify 154verifies 155.Fa tbslen 156bytes at 157.Fa tbs 158against the signature in 159.Fa sig 160of length 161.Fa siglen . 162.Fn EVP_DigestVerify 163is a one shot operation which verifies a single block of data 164in one function call. 165For algorithms that support streaming it is equivalent to calling 166.Fn EVP_DigestVerifyUpdate 167and 168.Fn EVP_DigestVerifyFinal . 169.\" For algorithms which do not support streaming 170.\" (e.g. PureEdDSA) 171.\" it is the only way to verify data. 172.Pp 173The EVP interface to digital signatures should almost always be 174used in preference to the low-level interfaces. 175This is because the code then becomes transparent to the algorithm used 176and much more flexible. 177.Pp 178The call to 179.Fn EVP_DigestVerifyFinal 180internally finalizes a copy of the digest context. 181This means that 182.Xr EVP_VerifyUpdate 3 183and 184.Xr EVP_VerifyFinal 3 185can be called later to digest and verify additional data. 186.Pp 187Since only a copy of the digest context is ever finalized, the context 188must be cleaned up after use by calling 189.Xr EVP_MD_CTX_free 3 190or a memory leak will occur. 191.Sh RETURN VALUES 192.Fn EVP_DigestVerifyInit 193and 194.Fn EVP_DigestVerifyUpdate 195return 1 for success and 0 for failure. 196.Pp 197.Fn EVP_DigestVerifyFinal 198and 199.Fn EVP_DigestVerify 200return 1 for success; any other value indicates failure. 201A return value of 0 indicates that the signature did not verify 202successfully (that is, the signature did not match the original 203data or the signature had an invalid form), while other values 204indicate a more serious error (and sometimes also indicate an invalid 205signature form). 206.Pp 207The error codes can be obtained from 208.Xr ERR_get_error 3 . 209.Sh SEE ALSO 210.Xr evp 3 , 211.Xr EVP_DigestInit 3 , 212.Xr EVP_DigestSignInit 3 213.Sh HISTORY 214.Fn EVP_DigestVerifyInit , 215.Fn EVP_DigestVerifyUpdate , 216and 217.Fn EVP_DigestVerifyFinal 218first appeared in OpenSSL 1.0.0 and have been available since 219.Ox 4.9 . 220.Pp 221.Fn EVP_DigestVerify 222first appeared in OpenSSL 1.1.1 and has been available since 223.Ox 7.0 . 224