#use wml::openssl-macros area=docs page=EVP_DigestVerifyInit

<title>Documents, EVP_DigestVerifyInit(3)</title>

<h1>EVP_DigestVerifyInit(3)</h1>

#use wml::imp::generic

{:
## What's this? [[s|(<STRONG>[^<].+?)</A>(</STRONG><DD>)|$1$2|sg]]
[[s|<P>\s+<P>|<P>|sg]]
[[s|<P>\s+</|</|sg]]
[[s|<DD>\s*<DT>|<DD>&nbsp;<DT>|sg]]
[[s|<DD>\s*</DL>|<DD>&nbsp;</DL>|sg]]
[[s|\[|&#91;|sg]]
[[s|\]|&#93;|sg]]

<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#NAME">NAME</A>
	<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
	<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
	<LI><A HREF="#RETURN_VALUES">RETURN VALUES</A>
	<LI><A HREF="#NOTES">NOTES</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
	<LI><A HREF="#HISTORY">HISTORY</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="NAME">NAME</A></H1>
<P>
EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal - EVP
signature verification functions

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/evp.h&gt;
</PRE>
<PRE> int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
                        const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
 int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
 int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t siglen);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
The EVP signature routines are a high level interface to digital
signatures.

</P>
<P>
<CODE>EVP_DigestVerifyInit()</CODE> sets up verification context <STRONG>ctx</STRONG> to use digest
<STRONG>type</STRONG> from ENGINE <STRONG>impl</STRONG> and public key <STRONG>pkey</STRONG>. <STRONG>ctx</STRONG> must be initialized with <CODE>EVP_MD_CTX_init()</CODE> before calling this
function. If <STRONG>pctx</STRONG> is not NULL the EVP_PKEY_CTX of the verification operation will be written
to <STRONG>*pctx</STRONG>: this can be used to set alternative verification options.

</P>
<P>
<CODE>EVP_DigestVerifyUpdate()</CODE> hashes <STRONG>cnt</STRONG> bytes of data at <STRONG>d</STRONG> into the verification context <STRONG>ctx</STRONG>. This function can be called several times on the same <STRONG>ctx</STRONG> to include additional data. This function is currently implemented using a
macro.

</P>
<P>
<CODE>EVP_DigestVerifyFinal()</CODE> verifies the data in <STRONG>ctx</STRONG> against the signature in
<STRONG>sig</STRONG> of length <STRONG>siglen</STRONG>.

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>EVP_DigestVerifyInit()</CODE> and
<CODE>EVP_DigestVerifyUpdate()</CODE> return 1 for success and 0 or a
negative value for failure. In particular a return value of -2 indicates
the operation is not supported by the public key algorithm.

</P>
<P>
Unlike other functions the return value 0 from
<CODE>EVP_DigestVerifyFinal()</CODE> only indicates that the signature did
not not verify successfully (that is tbs did not match the original data or
the signature was of invalid form) it is not an indication of a more
serious error.

</P>
<P>
The error codes can be obtained from <A HREF="../crypto/ERR_get_error.html#">ERR_get_error(3)</A>.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
The <STRONG>EVP</STRONG> interface to digital signatures should almost always be used in preference
to the low level interfaces. This is because the code then becomes
transparent to the algorithm used and much more flexible.

</P>
<P>
In previous versions of OpenSSL there was a link between message digest
types and public key algorithms. This meant that ``clone'' digests such as
<CODE>EVP_dss1()</CODE> needed to be used to sign using SHA1 and DSA. This
is no longer necessary and the use of clone digest is now discouraged.

</P>
<P>
For some key types and parameters the random number generator must be
seeded or the operation will fail. 

</P>
<P>
The call to <CODE>EVP_DigestVerifyFinal()</CODE> internally finalizes a
copy of the digest context. This means that calls to
<CODE>EVP_VerifyUpdate()</CODE> and <CODE>EVP_VerifyFinal()</CODE> can be
called later to digest and verify additional data.

</P>
<P>
Since only a copy of the digest context is ever finalized the context must
be cleaned up after use by calling <CODE>EVP_MD_CTX_cleanup()</CODE> or a
memory leak will occur.

</P>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
<A HREF="../crypto/EVP_DigestSignInit.html#">EVP_DigestSignInit(3)</A>,
<A HREF="../crypto/EVP_DigestInit.html#">EVP_DigestInit(3)</A>, <A HREF="../crypto/err.html#">err(3)</A>,
<A HREF="../crypto/evp.html#">evp(3)</A>, <A HREF="../crypto/hmac.html#">hmac(3)</A>, <A HREF="../crypto/md5.html#">md2(3)</A>,
<A HREF="../crypto/md5.html#">md5(3)</A>, <A HREF="../crypto/mdc2.html#">mdc2(3)</A>, <A HREF="../crypto/ripemd.html#">ripemd(3)</A>,
<A HREF="../crypto/sha.html#">sha(3)</A>, <A HREF="../apps/dgst.html#">dgst(1)</A>



</P>
<P>
<HR>
<H1><A NAME="HISTORY">HISTORY</A></H1>
<P>
<CODE>EVP_DigestVerifyInit(),</CODE> <CODE>EVP_DigestVerifyUpdate()</CODE>
and <CODE>EVP_DigestVerifyFinal()</CODE> were first added to OpenSSL 1.0.0.

</P>
:}