5 SSL_CTX_set_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, SSL_get_info_callback - handle information callback for SSL connections
9 #include <openssl/ssl.h>
11 void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)());
12 void (*SSL_CTX_get_info_callback(SSL_CTX *ctx))();
14 void SSL_set_info_callback(SSL *ssl, void (*callback)());
15 void (*SSL_get_info_callback(SSL *ssl))();
21 SSL_CTX_set_info_callback() sets the B<callback> function, that can be used to
22 obtain state information for SSL objects created from B<ctx> during connection
23 setup and use. The setting for B<ctx> is overridden from the setting for
24 a specific SSL object, if specified.
25 When B<callback> is NULL, not callback function is used.
27 SSL_set_info_callback() sets the B<callback> function, that can be used to
28 obtain state information for B<ssl> during connection setup and use.
29 When B<callback> is NULL, the callback setting currently valid for
32 SSL_CTX_get_info_callback() returns a pointer to the currently set information
33 callback function for B<ctx>.
35 SSL_get_info_callback() returns a pointer to the currently set information
36 callback function for B<ssl>.
40 When setting up a connection and during use, it is possible to obtain state
41 information from the SSL/TLS engine. When set, an information callback function
42 is called whenever the state changes, an alert appears, or an error occurs.
44 The callback function is called as B<callback(SSL *ssl, int where, int ret)>.
45 The B<where> argument specifies information about where (in which context)
46 the callback function was called. If B<ret> is 0, an error condition occured.
47 If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert
50 B<where> is a bitmask made up of the following bits:
56 Callback has been called to indicate state change inside a loop.
60 Callback has been called to indicate error exit of a handshake function.
61 (May be soft error with retry option for non-blocking setups.)
65 Callback has been called during read operation.
69 Callback has been called during write operation.
73 Callback has been called due to an alert being sent or received.
75 =item SSL_CB_READ_ALERT (SSL_CB_ALERT|SSL_CB_READ)
77 =item SSL_CB_WRITE_ALERT (SSL_CB_ALERT|SSL_CB_WRITE)
79 =item SSL_CB_ACCEPT_LOOP (SSL_ST_ACCEPT|SSL_CB_LOOP)
81 =item SSL_CB_ACCEPT_EXIT (SSL_ST_ACCEPT|SSL_CB_EXIT)
83 =item SSL_CB_CONNECT_LOOP (SSL_ST_CONNECT|SSL_CB_LOOP)
85 =item SSL_CB_CONNECT_EXIT (SSL_ST_CONNECT|SSL_CB_EXIT)
87 =item SSL_CB_HANDSHAKE_START
89 Callback has been called because a new handshake is started.
91 =item SSL_CB_HANDSHAKE_DONE 0x20
93 Callback has been called because a handshake is finished.
97 The current state information can be obtained using the
98 L<SSL_state_string(3)|SSL_state_string(3)> family of functions.
100 The B<ret> information can be evaluated using the
101 L<SSL_alert_type_string(3)|SSL_alert_type_string(3)> family of functions.
105 SSL_set_info_callback() does not provide diagnostic information.
107 SSL_get_info_callback() returns the current setting.
111 The following example callback function prints state strings, information
112 about alerts being handled and error messages to the B<bio_err> BIO.
114 void apps_ssl_info_callback(SSL *s, int where, int ret)
119 w=where& ~SSL_ST_MASK;
121 if (w & SSL_ST_CONNECT) str="SSL_connect";
122 else if (w & SSL_ST_ACCEPT) str="SSL_accept";
123 else str="undefined";
125 if (where & SSL_CB_LOOP)
127 BIO_printf(bio_err,"%s:%s\n",str,SSL_state_string_long(s));
129 else if (where & SSL_CB_ALERT)
131 str=(where & SSL_CB_READ)?"read":"write";
132 BIO_printf(bio_err,"SSL3 alert %s:%s:%s\n",
134 SSL_alert_type_string_long(ret),
135 SSL_alert_desc_string_long(ret));
137 else if (where & SSL_CB_EXIT)
140 BIO_printf(bio_err,"%s:failed in %s\n",
141 str,SSL_state_string_long(s));
144 BIO_printf(bio_err,"%s:error in %s\n",
145 str,SSL_state_string_long(s));
152 L<ssl(3)|ssl(3)>, L<SSL_state_string(3)|SSL_state_string(3)>,
153 L<SSL_alert_type_string(3)|SSL_alert_type_string(3)>