1.\" $OpenBSD: EVP_VerifyInit.3,v 1.2 2016/11/06 15:52:50 jmc Exp $ 2.\" 3.Dd $Mdocdate: November 6 2016 $ 4.Dt EVP_VERIFYINIT 3 5.Os 6.Sh NAME 7.Nm EVP_VerifyInit , 8.Nm EVP_VerifyUpdate , 9.Nm EVP_VerifyFinal 10.Nd EVP signature verification functions 11.Sh SYNOPSIS 12.In openssl/evp.h 13.Ft int 14.Fo EVP_VerifyInit_ex 15.Fa "EVP_MD_CTX *ctx" 16.Fa "const EVP_MD *type" 17.Fa "ENGINE *impl" 18.Fc 19.Ft int 20.Fo EVP_VerifyUpdate 21.Fa "EVP_MD_CTX *ctx" 22.Fa "const void *d" 23.Fa "unsigned int cnt" 24.Fc 25.Ft int 26.Fo EVP_VerifyFinal 27.Fa "EVP_MD_CTX *ctx" 28.Fa "unsigned char *sigbuf" 29.Fa "unsigned int siglen" 30.Fa "EVP_PKEY *pkey" 31.Fc 32.Ft int 33.Fo EVP_VerifyInit 34.Fa "EVP_MD_CTX *ctx" 35.Fa "const EVP_MD *type" 36.Fc 37.Sh DESCRIPTION 38The EVP signature verification routines are a high level interface to 39digital signatures. 40.Pp 41.Fn EVP_VerifyInit_ex 42sets up a verification context 43.Fa ctx 44to use the digest 45.Fa type 46from 47.Vt ENGINE 48.Fa impl . 49.Fa ctx 50must be initialized by calling 51.Xr EVP_MD_CTX_init 3 52before calling this function. 53.Pp 54.Fn EVP_VerifyUpdate 55hashes 56.Fa cnt 57bytes of data at 58.Fa d 59into the verification context 60.Fa ctx . 61This function can be called several times on the same 62.Fa ctx 63to include additional data. 64.Pp 65.Fn EVP_VerifyFinal 66verifies the data in 67.Fa ctx 68using the public key 69.Fa pkey 70and against the 71.Fa siglen 72bytes at 73.Fa sigbuf . 74.Pp 75.Fn EVP_VerifyInit 76initializes a verification context 77.Fa ctx 78to use the default implementation of digest 79.Fa type . 80.Pp 81The EVP interface to digital signatures should almost always be 82used in preference to the low level interfaces. 83This is because the code then becomes transparent to the algorithm used 84and much more flexible. 85.Pp 86Due to the link between message digests and public key algorithms, the 87correct digest algorithm must be used with the correct public key type. 88A list of algorithms and associated public key algorithms appears in 89.Xr EVP_DigestInit 3 . 90.Pp 91The call to 92.Fn EVP_VerifyFinal 93internally finalizes a copy of the digest context. 94This means that calls to 95.Fn EVP_VerifyUpdate 96and 97.Fn EVP_VerifyFinal 98can be called later to digest and verify additional data. 99.Pp 100Since only a copy of the digest context is ever finalized, the context 101must be cleaned up after use by calling 102.Xr EVP_MD_CTX_cleanup 3 , 103or a memory leak will occur. 104.Sh RETURN VALUES 105.Fn EVP_VerifyInit_ex 106and 107.Fn EVP_VerifyUpdate 108return 1 for success and 0 for failure. 109.Pp 110.Fn EVP_VerifyFinal 111returns 1 for a correct signature, 0 for failure, and -1 if some other 112error occurred. 113.Pp 114The error codes can be obtained by 115.Xr ERR_get_error 3 . 116.Sh SEE ALSO 117.Xr ERR 3 , 118.Xr evp 3 , 119.Xr EVP_DigestInit 3 , 120.Xr EVP_SignInit 3 121.Sh HISTORY 122.Fn EVP_VerifyInit , 123.Fn EVP_VerifyUpdate , 124and 125.Fn EVP_VerifyFinal 126are available in all versions of SSLeay and OpenSSL. 127.Pp 128.Fn EVP_VerifyInit_ex 129was added in OpenSSL 0.9.7. 130.Sh BUGS 131Older versions of this documentation wrongly stated that calls to 132.Fn EVP_VerifyUpdate 133could not be made after calling 134.Fn EVP_VerifyFinal . 135.Pp 136Since the public key is passed in the call to 137.Xr EVP_SignFinal 3 , 138any error relating to the private key (for example an unsuitable key and 139digest combination) will not be indicated until after potentially large 140amounts of data have been passed through 141.Xr EVP_SignUpdate 3 . 142.Pp 143It is not possible to change the signing parameters using these 144functions. 145.Pp 146The previous two bugs are fixed in the newer functions of the 147.Xr EVP_DigestVerifyInit 3 148family. 149