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