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 40291721SjkimEVP_DigestVerifyFinal() returns 1 for success; any other value indicates 41291721Sjkimfailure. A return value of zero indicates that the signature did not verify 42291721Sjkimsuccessfully (that is, tbs did not match the original data or the signature had 43291721Sjkiman invalid form), while other values indicate a more serious error (and 44291721Sjkimsometimes also indicate an invalid signature form). 45238384Sjkim 46238384SjkimThe error codes can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. 47238384Sjkim 48238384Sjkim=head1 NOTES 49238384Sjkim 50238384SjkimThe B<EVP> interface to digital signatures should almost always be used in 51238384Sjkimpreference to the low level interfaces. This is because the code then becomes 52238384Sjkimtransparent to the algorithm used and much more flexible. 53238384Sjkim 54238384SjkimIn previous versions of OpenSSL there was a link between message digest types 55238384Sjkimand public key algorithms. This meant that "clone" digests such as EVP_dss1() 56238384Sjkimneeded to be used to sign using SHA1 and DSA. This is no longer necessary and 57238384Sjkimthe use of clone digest is now discouraged. 58238384Sjkim 59238384SjkimFor some key types and parameters the random number generator must be seeded 60238384Sjkimor the operation will fail. 61238384Sjkim 62238384SjkimThe call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest 63273149Sjkimcontext. This means that EVP_VerifyUpdate() and EVP_VerifyFinal() can 64238384Sjkimbe called later to digest and verify additional data. 65238384Sjkim 66238384SjkimSince only a copy of the digest context is ever finalized the context must 67238384Sjkimbe cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak 68238384Sjkimwill occur. 69238384Sjkim 70238384Sjkim=head1 SEE ALSO 71238384Sjkim 72238384SjkimL<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)>, 73238384SjkimL<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, 74238384SjkimL<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, 75238384SjkimL<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, 76238384SjkimL<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> 77238384Sjkim 78238384Sjkim=head1 HISTORY 79238384Sjkim 80238384SjkimEVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal() 81238384Sjkimwere first added to OpenSSL 1.0.0. 82238384Sjkim 83238384Sjkim=cut 84