1: =pod
    2: 
    3: =head1 NAME
    4: 
    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
    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: 
   19: SSL_CTX_set_info_callback() sets the B<callback> function, that can be used to
   20: obtain state information for SSL objects created from B<ctx> during connection
   21: setup and use. The setting for B<ctx> is overridden from the setting for
   22: a specific SSL object, if specified.
   23: When B<callback> is NULL, not callback function is used.
   24: 
   25: SSL_set_info_callback() sets the B<callback> function, that can be used to
   26: obtain state information for B<ssl> during connection setup and use.
   27: When B<callback> is NULL, the callback setting currently valid for
   28: B<ctx> is used.
   29: 
   30: SSL_CTX_get_info_callback() returns a pointer to the currently set information
   31: callback function for B<ctx>.
   32: 
   33: SSL_get_info_callback() returns a pointer to the currently set information
   34: callback function for B<ssl>.
   35: 
   36: =head1 NOTES
   37: 
   38: When setting up a connection and during use, it is possible to obtain state
   39: information from the SSL/TLS engine. When set, an information callback function
   40: is called whenever the state changes, an alert appears, or an error occurs.
   41: 
   42: The callback function is called as B<callback(SSL *ssl, int where, int ret)>.
   43: The B<where> argument specifies information about where (in which context)
   44: the callback function was called. If B<ret> is 0, an error condition occurred.
   45: If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert
   46: information.
   47: 
   48: B<where> is a bitmask made up of the following bits:
   49: 
   50: =over 4
   51: 
   52: =item SSL_CB_LOOP
   53: 
   54: Callback has been called to indicate state change inside a loop.
   55: 
   56: =item SSL_CB_EXIT
   57: 
   58: Callback 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: 
   63: Callback has been called during read operation.
   64: 
   65: =item SSL_CB_WRITE
   66: 
   67: Callback has been called during write operation.
   68: 
   69: =item SSL_CB_ALERT
   70: 
   71: Callback 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: 
   87: Callback has been called because a new handshake is started.
   88: 
   89: =item SSL_CB_HANDSHAKE_DONE           0x20
   90: 
   91: Callback has been called because a handshake is finished.
   92: 
   93: =back
   94: 
   95: The current state information can be obtained using the
   96: L<SSL_state_string(3)|SSL_state_string(3)> family of functions.
   97: 
   98: The B<ret> information can be evaluated using the
   99: L<SSL_alert_type_string(3)|SSL_alert_type_string(3)> family of functions.
  100: 
  101: =head1 RETURN VALUES
  102: 
  103: SSL_set_info_callback() does not provide diagnostic information.
  104: 
  105: SSL_get_info_callback() returns the current setting.
  106: 
  107: =head1 EXAMPLES
  108: 
  109: The following example callback function prints state strings, information
  110: about 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: 
  150: L<ssl(3)|ssl(3)>, L<SSL_state_string(3)|SSL_state_string(3)>,
  151: L<SSL_alert_type_string(3)|SSL_alert_type_string(3)>
  152: 
  153: =cut