SSL_CTX_set_info_callback.pod revision 302408
1=pod 2 3=head1 NAME 4 5SSL_CTX_set_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, SSL_get_info_callback - handle information callback for SSL connections 6 7=head1 SYNOPSIS 8 9 #include <openssl/ssl.h> 10 11 void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)()); 12 void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))(); 13 14 void SSL_set_info_callback(SSL *ssl, void (*callback)()); 15 void (*SSL_get_info_callback(const SSL *ssl))(); 16 17=head1 DESCRIPTION 18 19SSL_CTX_set_info_callback() sets the B<callback> function, that can be used to 20obtain state information for SSL objects created from B<ctx> during connection 21setup and use. The setting for B<ctx> is overridden from the setting for 22a specific SSL object, if specified. 23When B<callback> is NULL, not callback function is used. 24 25SSL_set_info_callback() sets the B<callback> function, that can be used to 26obtain state information for B<ssl> during connection setup and use. 27When B<callback> is NULL, the callback setting currently valid for 28B<ctx> is used. 29 30SSL_CTX_get_info_callback() returns a pointer to the currently set information 31callback function for B<ctx>. 32 33SSL_get_info_callback() returns a pointer to the currently set information 34callback function for B<ssl>. 35 36=head1 NOTES 37 38When setting up a connection and during use, it is possible to obtain state 39information from the SSL/TLS engine. When set, an information callback function 40is called whenever the state changes, an alert appears, or an error occurs. 41 42The callback function is called as B<callback(SSL *ssl, int where, int ret)>. 43The B<where> argument specifies information about where (in which context) 44the callback function was called. If B<ret> is 0, an error condition occurred. 45If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert 46information. 47 48B<where> is a bitmask made up of the following bits: 49 50=over 4 51 52=item SSL_CB_LOOP 53 54Callback has been called to indicate state change inside a loop. 55 56=item SSL_CB_EXIT 57 58Callback has been called to indicate error exit of a handshake function. 59(May be soft error with retry option for non-blocking setups.) 60 61=item SSL_CB_READ 62 63Callback has been called during read operation. 64 65=item SSL_CB_WRITE 66 67Callback has been called during write operation. 68 69=item SSL_CB_ALERT 70 71Callback has been called due to an alert being sent or received. 72 73=item SSL_CB_READ_ALERT (SSL_CB_ALERT|SSL_CB_READ) 74 75=item SSL_CB_WRITE_ALERT (SSL_CB_ALERT|SSL_CB_WRITE) 76 77=item SSL_CB_ACCEPT_LOOP (SSL_ST_ACCEPT|SSL_CB_LOOP) 78 79=item SSL_CB_ACCEPT_EXIT (SSL_ST_ACCEPT|SSL_CB_EXIT) 80 81=item SSL_CB_CONNECT_LOOP (SSL_ST_CONNECT|SSL_CB_LOOP) 82 83=item SSL_CB_CONNECT_EXIT (SSL_ST_CONNECT|SSL_CB_EXIT) 84 85=item SSL_CB_HANDSHAKE_START 86 87Callback has been called because a new handshake is started. 88 89=item SSL_CB_HANDSHAKE_DONE 0x20 90 91Callback has been called because a handshake is finished. 92 93=back 94 95The current state information can be obtained using the 96L<SSL_state_string(3)|SSL_state_string(3)> family of functions. 97 98The B<ret> information can be evaluated using the 99L<SSL_alert_type_string(3)|SSL_alert_type_string(3)> family of functions. 100 101=head1 RETURN VALUES 102 103SSL_set_info_callback() does not provide diagnostic information. 104 105SSL_get_info_callback() returns the current setting. 106 107=head1 EXAMPLES 108 109The following example callback function prints state strings, information 110about alerts being handled and error messages to the B<bio_err> BIO. 111 112 void apps_ssl_info_callback(SSL *s, int where, int ret) 113 { 114 const char *str; 115 int w; 116 117 w=where& ~SSL_ST_MASK; 118 119 if (w & SSL_ST_CONNECT) str="SSL_connect"; 120 else if (w & SSL_ST_ACCEPT) str="SSL_accept"; 121 else str="undefined"; 122 123 if (where & SSL_CB_LOOP) 124 { 125 BIO_printf(bio_err,"%s:%s\n",str,SSL_state_string_long(s)); 126 } 127 else if (where & SSL_CB_ALERT) 128 { 129 str=(where & SSL_CB_READ)?"read":"write"; 130 BIO_printf(bio_err,"SSL3 alert %s:%s:%s\n", 131 str, 132 SSL_alert_type_string_long(ret), 133 SSL_alert_desc_string_long(ret)); 134 } 135 else if (where & SSL_CB_EXIT) 136 { 137 if (ret == 0) 138 BIO_printf(bio_err,"%s:failed in %s\n", 139 str,SSL_state_string_long(s)); 140 else if (ret < 0) 141 { 142 BIO_printf(bio_err,"%s:error in %s\n", 143 str,SSL_state_string_long(s)); 144 } 145 } 146 } 147 148=head1 SEE ALSO 149 150L<ssl(3)|ssl(3)>, L<SSL_state_string(3)|SSL_state_string(3)>, 151L<SSL_alert_type_string(3)|SSL_alert_type_string(3)> 152 153=cut 154