1238384Sjkim=pod 2238384Sjkim 3238384Sjkim=head1 NAME 4238384Sjkim 5238384SjkimEVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal - EVP signature verification functions 6238384Sjkim 7238384Sjkim=head1 SYNOPSIS 8238384Sjkim 9238384Sjkim #include <openssl/evp.h> 10238384Sjkim 11238384Sjkim int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, 12238384Sjkim const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); 13238384Sjkim int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); 14238384Sjkim int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t siglen); 15238384Sjkim 16238384Sjkim=head1 DESCRIPTION 17238384Sjkim 18238384SjkimThe EVP signature routines are a high level interface to digital signatures. 19238384Sjkim 20238384SjkimEVP_DigestVerifyInit() sets up verification context B<ctx> to use digest 21238384SjkimB<type> from ENGINE B<impl> and public key B<pkey>. B<ctx> must be initialized 22238384Sjkimwith EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL the 23238384SjkimEVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this 24238384Sjkimcan be used to set alternative verification options. 25238384Sjkim 26238384SjkimEVP_DigestVerifyUpdate() hashes B<cnt> bytes of data at B<d> into the 27238384Sjkimverification context B<ctx>. This function can be called several times on the 28238384Sjkimsame B<ctx> to include additional data. This function is currently implemented 29238384Sjkimusing a macro. 30238384Sjkim 31238384SjkimEVP_DigestVerifyFinal() verifies the data in B<ctx> against the signature in 32238384SjkimB<sig> of length B<siglen>. 33238384Sjkim 34238384Sjkim=head1 RETURN VALUES 35238384Sjkim 36238384SjkimEVP_DigestVerifyInit() and EVP_DigestVerifyUpdate() return 1 for success and 0 37238384Sjkimor a negative value for failure. In particular a return value of -2 indicates 38238384Sjkimthe operation is not supported by the public key algorithm. 39238384Sjkim 40238384SjkimUnlike other functions the return value 0 from EVP_DigestVerifyFinal() only 41273399Sdelphijindicates that the signature did not verify successfully (that is tbs did 42238384Sjkimnot match the original data or the signature was of invalid form) it is not an 43238384Sjkimindication of a more serious error. 44238384Sjkim 45238384SjkimThe error codes can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. 46238384Sjkim 47238384Sjkim=head1 NOTES 48238384Sjkim 49238384SjkimThe B<EVP> interface to digital signatures should almost always be used in 50238384Sjkimpreference to the low level interfaces. This is because the code then becomes 51238384Sjkimtransparent to the algorithm used and much more flexible. 52238384Sjkim 53238384SjkimIn previous versions of OpenSSL there was a link between message digest types 54238384Sjkimand public key algorithms. This meant that "clone" digests such as EVP_dss1() 55238384Sjkimneeded to be used to sign using SHA1 and DSA. This is no longer necessary and 56238384Sjkimthe use of clone digest is now discouraged. 57238384Sjkim 58238384SjkimFor some key types and parameters the random number generator must be seeded 59238384Sjkimor the operation will fail. 60238384Sjkim 61238384SjkimThe call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest 62273399Sdelphijcontext. This means that EVP_VerifyUpdate() and EVP_VerifyFinal() can 63238384Sjkimbe called later to digest and verify additional data. 64238384Sjkim 65238384SjkimSince only a copy of the digest context is ever finalized the context must 66238384Sjkimbe cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak 67238384Sjkimwill occur. 68238384Sjkim 69238384Sjkim=head1 SEE ALSO 70238384Sjkim 71238384SjkimL<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)>, 72238384SjkimL<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, 73238384SjkimL<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, 74238384SjkimL<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, 75238384SjkimL<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> 76238384Sjkim 77238384Sjkim=head1 HISTORY 78238384Sjkim 79238384SjkimEVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal() 80238384Sjkimwere first added to OpenSSL 1.0.0. 81238384Sjkim 82238384Sjkim=cut 83