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

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

<h1>SSL_CTX_set_info_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="#RETURN_VALUES">RETURN VALUES</A>
	<LI><A HREF="#EXAMPLES">EXAMPLES</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="NAME">NAME</A></H1>
<P>
SSL_CTX_set_info_callback, SSL_CTX_get_info_callback,
SSL_set_info_callback, SSL_get_info_callback - handle information callback
for SSL connections

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/ssl.h&gt;
</PRE>
<PRE> void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)());
 void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))();
</PRE>
<PRE> void SSL_set_info_callback(SSL *ssl, void (*callback)());
 void (*SSL_get_info_callback(const SSL *ssl))();
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
<CODE>SSL_CTX_set_info_callback()</CODE> sets the <STRONG>callback</STRONG> function, that can be used to obtain state information for SSL objects
created from <STRONG>ctx</STRONG> during connection setup and use. The setting for <STRONG>ctx</STRONG> is overridden from the setting for a specific SSL object, if specified.
When <STRONG>callback</STRONG> is NULL, not callback function is used.

</P>
<P>
<CODE>SSL_set_info_callback()</CODE> sets the <STRONG>callback</STRONG> function, that can be used to obtain state information for <STRONG>ssl</STRONG> during connection setup and use. When <STRONG>callback</STRONG> is NULL, the callback setting currently valid for
<STRONG>ctx</STRONG> is used.

</P>
<P>
<CODE>SSL_CTX_get_info_callback()</CODE> returns a pointer to the currently
set information callback function for <STRONG>ctx</STRONG>.

</P>
<P>
<CODE>SSL_get_info_callback()</CODE> returns a pointer to the currently set
information callback function for <STRONG>ssl</STRONG>.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
When setting up a connection and during use, it is possible to obtain state
information from the SSL/TLS engine. When set, an information callback
function is called whenever the state changes, an alert appears, or an
error occurs.

</P>
<P>
The callback function is called as <STRONG>callback(SSL *ssl, int where, int ret)</STRONG>. The <STRONG>where</STRONG> argument specifies information about where (in which context) the callback
function was called. If <STRONG>ret</STRONG> is 0, an error condition occurred. If an alert is handled, SSL_CB_ALERT is
set and <STRONG>ret</STRONG> specifies the alert information.

</P>
<P>
<STRONG>where</STRONG> is a bitmask made up of the following bits:

</P>
<DL>
<DT><STRONG><A NAME="item_SSL_CB_LOOP">SSL_CB_LOOP</A></STRONG><DD>
<P>
Callback has been called to indicate state change inside a loop.

</P>
<DT><STRONG><A NAME="item_SSL_CB_EXIT">SSL_CB_EXIT</A></STRONG><DD>
<P>
Callback has been called to indicate error exit of a handshake function.
(May be soft error with retry option for non-blocking setups.)

</P>
<DT><STRONG><A NAME="item_SSL_CB_READ">SSL_CB_READ</A></STRONG><DD>
<P>
Callback has been called during read operation.

</P>
<DT><STRONG><A NAME="item_SSL_CB_WRITE">SSL_CB_WRITE</A></STRONG><DD>
<P>
Callback has been called during write operation.

</P>
<DT><STRONG><A NAME="item_SSL_CB_ALERT">SSL_CB_ALERT</A></STRONG><DD>
<P>
Callback has been called due to an alert being sent or received.

</P>
<DT><STRONG><A NAME="item_SSL_CB_READ_ALERT">SSL_CB_READ_ALERT               (SSL_CB_ALERT|SSL_CB_READ)</A></STRONG><DD>
<DT><STRONG><A NAME="item_SSL_CB_WRITE_ALERT">SSL_CB_WRITE_ALERT              (SSL_CB_ALERT|SSL_CB_WRITE)</A></STRONG><DD>
<DT><STRONG><A NAME="item_SSL_CB_ACCEPT_LOOP">SSL_CB_ACCEPT_LOOP              (SSL_ST_ACCEPT|SSL_CB_LOOP)</A></STRONG><DD>
<DT><STRONG><A NAME="item_SSL_CB_ACCEPT_EXIT">SSL_CB_ACCEPT_EXIT              (SSL_ST_ACCEPT|SSL_CB_EXIT)</A></STRONG><DD>
<DT><STRONG><A NAME="item_SSL_CB_CONNECT_LOOP">SSL_CB_CONNECT_LOOP             (SSL_ST_CONNECT|SSL_CB_LOOP)</A></STRONG><DD>
<DT><STRONG><A NAME="item_SSL_CB_CONNECT_EXIT">SSL_CB_CONNECT_EXIT             (SSL_ST_CONNECT|SSL_CB_EXIT)</A></STRONG><DD>
<DT><STRONG><A NAME="item_SSL_CB_HANDSHAKE_START">SSL_CB_HANDSHAKE_START</A></STRONG><DD>
<P>
Callback has been called because a new handshake is started.

</P>
<DT><STRONG><A NAME="item_SSL_CB_HANDSHAKE_DONE">SSL_CB_HANDSHAKE_DONE           0x20</A></STRONG><DD>
<P>
Callback has been called because a handshake is finished.

</P>
</DL>
<P>
The current state information can be obtained using the
<A HREF="../ssl/SSL_state_string.html#">SSL_state_string(3)</A> family of functions.

</P>
<P>
The <STRONG>ret</STRONG> information can be evaluated using the
<A HREF="../ssl/SSL_alert_type_string.html#">SSL_alert_type_string(3)</A> family of functions.

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

</P>
<P>
<CODE>SSL_get_info_callback()</CODE> returns the current setting.

</P>
<P>
<HR>
<H1><A NAME="EXAMPLES">EXAMPLES</A></H1>
<P>
The following example callback function prints state strings, information
about alerts being handled and error messages to the <STRONG>bio_err</STRONG> BIO.

</P>
<PRE> void apps_ssl_info_callback(SSL *s, int where, int ret)
        {
        const char *str;
        int w;
</PRE>
<PRE>        w=where&amp; ~SSL_ST_MASK;
</PRE>
<PRE>        if (w &amp; SSL_ST_CONNECT) str=&quot;SSL_connect&quot;;
        else if (w &amp; SSL_ST_ACCEPT) str=&quot;SSL_accept&quot;;
        else str=&quot;undefined&quot;;
</PRE>
<PRE>        if (where &amp; SSL_CB_LOOP)
                {
                BIO_printf(bio_err,&quot;%s:%s\n&quot;,str,SSL_state_string_long(s));
                }
        else if (where &amp; SSL_CB_ALERT)
                {
                str=(where &amp; SSL_CB_READ)?&quot;read&quot;:&quot;write&quot;;
                BIO_printf(bio_err,&quot;SSL3 alert %s:%s:%s\n&quot;,
                        str,
                        SSL_alert_type_string_long(ret),
                        SSL_alert_desc_string_long(ret));
                }
        else if (where &amp; SSL_CB_EXIT)
                {
                if (ret == 0)
                        BIO_printf(bio_err,&quot;%s:failed in %s\n&quot;,
                                str,SSL_state_string_long(s));
                else if (ret &lt; 0)
                        {
                        BIO_printf(bio_err,&quot;%s:error in %s\n&quot;,
                                str,SSL_state_string_long(s));
                        }
                }
        }
</PRE>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
<A HREF="../ssl/ssl.html#">ssl(3)</A>, <A HREF="../ssl/SSL_state_string.html#">SSL_state_string(3)</A>,
<A HREF="../ssl/SSL_alert_type_string.html#">SSL_alert_type_string(3)</A>



</P>
:}