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

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

<h1>SSL_CTX_set_cert_verify_callback(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="#NOTES">NOTES</A>
	<LI><A HREF="#WARNINGS">WARNINGS</A>
	<LI><A HREF="#BUGS">BUGS</A>
	<LI><A HREF="#RETURN_VALUES">RETURN VALUES</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>
SSL_CTX_set_cert_verify_callback - set peer certificate verification
procedure

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/ssl.h&gt;
</PRE>
<PRE> void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx, int (*callback)(X509_STORE_CTX *,void *), void *arg);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
<CODE>SSL_CTX_set_cert_verify_callback()</CODE> sets the verification
callback function for
<EM>ctx</EM>. SSL objects that are created from <EM>ctx</EM> inherit the setting valid at the time when <A HREF="../ssl/SSL_new.html#">SSL_new(3)</A> is called.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
Whenever a certificate is verified during a SSL/TLS handshake, a
verification function is called. If the application does not explicitly
specify a verification callback function, the built-in verification
function is used. If a verification callback <EM>callback</EM> is specified via <CODE>SSL_CTX_set_cert_verify_callback(),</CODE> the
supplied callback function is called instead. By setting <EM>callback</EM> to NULL, the default behaviour is restored.

</P>
<P>
When the verification must be performed, <EM>callback</EM> will be called with the arguments <CODE>callback(X509_STORE_CTX</CODE>
*x509_store_ctx, void *arg). The argument <EM>arg</EM> is specified by the application when setting <EM>callback</EM>.

</P>
<P>
<EM>callback</EM> should return 1 to indicate verification success and 0 to indicate
verification failure. If SSL_VERIFY_PEER is set and <EM>callback</EM>
returns 0, the handshake will fail. As the verification procedure may allow
to continue the connection in case of failure (by always returning 1) the
verification result must be set in any case using the <STRONG>error</STRONG>
member of <EM>x509_store_ctx</EM> so that the calling application will be informed about the detailed result
of the verification procedure! 

</P>
<P>
Within <EM>x509_store_ctx</EM>, <EM>callback</EM> has access to the <EM>verify_callback</EM>
function set using <A HREF="../ssl/SSL_CTX_set_verify.html#">SSL_CTX_set_verify(3)</A>.

</P>
<P>
<HR>
<H1><A NAME="WARNINGS">WARNINGS</A></H1>
<P>
Do not mix the verification callback described in this function with the
<STRONG>verify_callback</STRONG> function called during the verification process. The latter is set using
the <A HREF="../ssl/SSL_CTX_set_verify.html#">SSL_CTX_set_verify(3)</A>
family of functions.

</P>
<P>
Providing a complete verification procedure including certificate purpose
settings etc is a complex task. The built-in procedure is quite powerful
and in most cases it should be sufficient to modify its behaviour using the <STRONG>verify_callback</STRONG> function.

</P>
<P>
<HR>
<H1><A NAME="BUGS">BUGS</A></H1>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>SSL_CTX_set_cert_verify_callback()</CODE> does not provide diagnostic
information.

</P>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
<A HREF="../ssl/ssl.html#">ssl(3)</A>, <A HREF="../ssl/SSL_CTX_set_verify.html#">SSL_CTX_set_verify(3)</A>,
<A HREF="../ssl/SSL_get_verify_result.html#">SSL_get_verify_result(3)</A>,
<A HREF="../ssl/SSL_CTX_load_verify_locations.html#">SSL_CTX_load_verify_locations(3)</A>



</P>
<P>
<HR>
<H1><A NAME="HISTORY">HISTORY</A></H1>
<P>
Previous to OpenSSL 0.9.7, the <EM>arg</EM> argument to <STRONG>SSL_CTX_set_cert_verify_callback</STRONG>
was ignored, and <EM>callback</EM> was called simply as int (*callback)(X509_STORE_CTX *) To compile software
written for previous versions of OpenSSL, a dummy argument will have to be
added to <EM>callback</EM>.

</P>
:}