1.\" $OpenBSD: EVP_DigestVerifyInit.3,v 1.8 2019/06/10 14:58:48 schwarze 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: June 10 2019 $ 53.Dt EVP_DIGESTVERIFYINIT 3 54.Os 55.Sh NAME 56.Nm EVP_DigestVerifyInit , 57.Nm EVP_DigestVerifyUpdate , 58.Nm EVP_DigestVerifyFinal 59.Nd EVP signature verification functions 60.Sh SYNOPSIS 61.In openssl/evp.h 62.Ft int 63.Fo EVP_DigestVerifyInit 64.Fa "EVP_MD_CTX *ctx" 65.Fa "EVP_PKEY_CTX **pctx" 66.Fa "const EVP_MD *type" 67.Fa "ENGINE *e" 68.Fa "EVP_PKEY *pkey" 69.Fc 70.Ft int 71.Fo EVP_DigestVerifyUpdate 72.Fa "EVP_MD_CTX *ctx" 73.Fa "const void *d" 74.Fa "size_t cnt" 75.Fc 76.Ft int 77.Fo EVP_DigestVerifyFinal 78.Fa "EVP_MD_CTX *ctx" 79.Fa "const unsigned char *sig" 80.Fa "size_t siglen" 81.Fc 82.Sh DESCRIPTION 83The EVP signature routines are a high level interface to digital 84signatures. 85.Pp 86.Fn EVP_DigestVerifyInit 87sets up verification context 88.Fa ctx 89to use digest 90.Fa type 91from 92.Vt ENGINE 93.Fa e 94and public key 95.Fa pkey . 96.Fa ctx 97must be initialized with 98.Xr EVP_MD_CTX_init 3 99before calling this function. 100If 101.Fa pctx 102is not 103.Dv NULL , 104the 105.Vt EVP_PKEY_CTX 106of the verification operation will be written to 107.Pf * Fa pctx : 108this can be used to set alternative verification options. 109.Pp 110.Fn EVP_DigestVerifyUpdate 111hashes 112.Fa cnt 113bytes of data at 114.Fa d 115into the verification context 116.Fa ctx . 117This function can be called several times on the same 118.Fa ctx 119to include additional data. 120This function is currently implemented using a macro. 121.Pp 122.Fn EVP_DigestVerifyFinal 123verifies the data in 124.Fa ctx 125against the signature in 126.Fa sig 127of length 128.Fa siglen . 129.Pp 130The EVP interface to digital signatures should almost always be 131used in preference to the low level interfaces. 132This is because the code then becomes transparent to the algorithm used 133and much more flexible. 134.Pp 135In previous versions of OpenSSL, there was a link between message digest 136types and public key algorithms. 137This meant that "clone" digests such as 138.Xr EVP_dss1 3 139needed to be used to sign using SHA1 and DSA. 140This is no longer necessary and the use of clone digest is now 141discouraged. 142.Pp 143The call to 144.Fn EVP_DigestVerifyFinal 145internally finalizes a copy of the digest context. 146This means that 147.Xr EVP_VerifyUpdate 3 148and 149.Xr EVP_VerifyFinal 3 150can be called later to digest and verify additional data. 151.Pp 152Since only a copy of the digest context is ever finalized, the context 153must be cleaned up after use by calling 154.Xr EVP_MD_CTX_free 3 155or a memory leak will occur. 156.Sh RETURN VALUES 157.Fn EVP_DigestVerifyInit 158and 159.Fn EVP_DigestVerifyUpdate 160return 1 for success and 0 or a negative value for failure. 161In particular a return value of -2 indicates the operation is not 162supported by the public key algorithm. 163.Pp 164.Fn EVP_DigestVerifyFinal 165returns 1 for success; any other value indicates failure. 166A return value of 0 indicates that the signature did not verify 167successfully (that is, the signature did not match the original 168data or the signature had an invalid form), while other values 169indicate a more serious error (and sometimes also indicate an invalid 170signature form). 171.Pp 172The error codes can be obtained from 173.Xr ERR_get_error 3 . 174.Sh SEE ALSO 175.Xr evp 3 , 176.Xr EVP_DigestInit 3 , 177.Xr EVP_DigestSignInit 3 , 178.Xr EVP_PKEY_meth_set_verifyctx 3 179.Sh HISTORY 180.Fn EVP_DigestVerifyInit , 181.Fn EVP_DigestVerifyUpdate , 182and 183.Fn EVP_DigestVerifyFinal 184first appeared in OpenSSL 1.0.0 and have been available since 185.Ox 4.9 . 186