crypto/openssl/doc/ssl/SSL_CTX_set_info_callback.pod

   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