SSL_CTX_set_info_callback.pod revision 160814
189837Skris=pod 289837Skris 389837Skris=head1 NAME 489837Skris 589837SkrisSSL_CTX_set_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, SSL_get_info_callback - handle information callback for SSL connections 689837Skris 789837Skris=head1 SYNOPSIS 889837Skris 989837Skris #include <openssl/ssl.h> 1089837Skris 1189837Skris void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)()); 12160814Ssimon void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))(); 1389837Skris 1489837Skris void SSL_set_info_callback(SSL *ssl, void (*callback)()); 15160814Ssimon void (*SSL_get_info_callback(const SSL *ssl))(); 1689837Skris 1789837Skris=head1 DESCRIPTION 1889837Skris 1989837SkrisSSL_CTX_set_info_callback() sets the B<callback> function, that can be used to 2089837Skrisobtain state information for SSL objects created from B<ctx> during connection 2189837Skrissetup and use. The setting for B<ctx> is overridden from the setting for 2289837Skrisa specific SSL object, if specified. 2389837SkrisWhen B<callback> is NULL, not callback function is used. 2489837Skris 2589837SkrisSSL_set_info_callback() sets the B<callback> function, that can be used to 2689837Skrisobtain state information for B<ssl> during connection setup and use. 2789837SkrisWhen B<callback> is NULL, the callback setting currently valid for 2889837SkrisB<ctx> is used. 2989837Skris 3089837SkrisSSL_CTX_get_info_callback() returns a pointer to the currently set information 3189837Skriscallback function for B<ctx>. 3289837Skris 3389837SkrisSSL_get_info_callback() returns a pointer to the currently set information 3489837Skriscallback function for B<ssl>. 3589837Skris 3689837Skris=head1 NOTES 3789837Skris 3889837SkrisWhen setting up a connection and during use, it is possible to obtain state 3989837Skrisinformation from the SSL/TLS engine. When set, an information callback function 4089837Skrisis called whenever the state changes, an alert appears, or an error occurs. 4189837Skris 4289837SkrisThe callback function is called as B<callback(SSL *ssl, int where, int ret)>. 4389837SkrisThe B<where> argument specifies information about where (in which context) 4489837Skristhe callback function was called. If B<ret> is 0, an error condition occurred. 4589837SkrisIf an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert 4689837Skrisinformation. 4789837Skris 4889837SkrisB<where> is a bitmask made up of the following bits: 4989837Skris 5089837Skris=over 4 5189837Skris 5289837Skris=item SSL_CB_LOOP 5389837Skris 5489837SkrisCallback has been called to indicate state change inside a loop. 5589837Skris 5689837Skris=item SSL_CB_EXIT 5789837Skris 5889837SkrisCallback has been called to indicate error exit of a handshake function. 5989837Skris(May be soft error with retry option for non-blocking setups.) 6089837Skris 6189837Skris=item SSL_CB_READ 6289837Skris 6389837SkrisCallback has been called during read operation. 6489837Skris 6589837Skris=item SSL_CB_WRITE 6689837Skris 6789837SkrisCallback has been called during write operation. 6889837Skris 6989837Skris=item SSL_CB_ALERT 7089837Skris 7189837SkrisCallback has been called due to an alert being sent or received. 7289837Skris 7389837Skris=item SSL_CB_READ_ALERT (SSL_CB_ALERT|SSL_CB_READ) 7489837Skris 7589837Skris=item SSL_CB_WRITE_ALERT (SSL_CB_ALERT|SSL_CB_WRITE) 7689837Skris 7789837Skris=item SSL_CB_ACCEPT_LOOP (SSL_ST_ACCEPT|SSL_CB_LOOP) 7889837Skris 7989837Skris=item SSL_CB_ACCEPT_EXIT (SSL_ST_ACCEPT|SSL_CB_EXIT) 8089837Skris 8189837Skris=item SSL_CB_CONNECT_LOOP (SSL_ST_CONNECT|SSL_CB_LOOP) 8289837Skris 8389837Skris=item SSL_CB_CONNECT_EXIT (SSL_ST_CONNECT|SSL_CB_EXIT) 8489837Skris 8589837Skris=item SSL_CB_HANDSHAKE_START 8689837Skris 8789837SkrisCallback has been called because a new handshake is started. 8889837Skris 8989837Skris=item SSL_CB_HANDSHAKE_DONE 0x20 9089837Skris 9189837SkrisCallback has been called because a handshake is finished. 9289837Skris 9389837Skris=back 9489837Skris 9589837SkrisThe current state information can be obtained using the 9689837SkrisL<SSL_state_string(3)|SSL_state_string(3)> family of functions. 9789837Skris 9889837SkrisThe B<ret> information can be evaluated using the 9989837SkrisL<SSL_alert_type_string(3)|SSL_alert_type_string(3)> family of functions. 10089837Skris 10189837Skris=head1 RETURN VALUES 10289837Skris 10389837SkrisSSL_set_info_callback() does not provide diagnostic information. 10489837Skris 10589837SkrisSSL_get_info_callback() returns the current setting. 10689837Skris 10789837Skris=head1 EXAMPLES 10889837Skris 10989837SkrisThe following example callback function prints state strings, information 11089837Skrisabout alerts being handled and error messages to the B<bio_err> BIO. 11189837Skris 11289837Skris void apps_ssl_info_callback(SSL *s, int where, int ret) 11389837Skris { 11489837Skris const char *str; 11589837Skris int w; 11689837Skris 11789837Skris w=where& ~SSL_ST_MASK; 11889837Skris 11989837Skris if (w & SSL_ST_CONNECT) str="SSL_connect"; 12089837Skris else if (w & SSL_ST_ACCEPT) str="SSL_accept"; 12189837Skris else str="undefined"; 12289837Skris 12389837Skris if (where & SSL_CB_LOOP) 12489837Skris { 12589837Skris BIO_printf(bio_err,"%s:%s\n",str,SSL_state_string_long(s)); 12689837Skris } 12789837Skris else if (where & SSL_CB_ALERT) 12889837Skris { 12989837Skris str=(where & SSL_CB_READ)?"read":"write"; 13089837Skris BIO_printf(bio_err,"SSL3 alert %s:%s:%s\n", 13189837Skris str, 13289837Skris SSL_alert_type_string_long(ret), 13389837Skris SSL_alert_desc_string_long(ret)); 13489837Skris } 13589837Skris else if (where & SSL_CB_EXIT) 13689837Skris { 13789837Skris if (ret == 0) 13889837Skris BIO_printf(bio_err,"%s:failed in %s\n", 13989837Skris str,SSL_state_string_long(s)); 14089837Skris else if (ret < 0) 14189837Skris { 14289837Skris BIO_printf(bio_err,"%s:error in %s\n", 14389837Skris str,SSL_state_string_long(s)); 14489837Skris } 14589837Skris } 14689837Skris } 14789837Skris 14889837Skris=head1 SEE ALSO 14989837Skris 15089837SkrisL<ssl(3)|ssl(3)>, L<SSL_state_string(3)|SSL_state_string(3)>, 15189837SkrisL<SSL_alert_type_string(3)|SSL_alert_type_string(3)> 15289837Skris 15389837Skris=cut 154