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(SSL_CTX *ctx))();
  13
  14  void SSL_set_info_callback(SSL *ssl, void (*callback)());
  15  void (*SSL_get_info_callback(SSL *ssl))();
  16
  17  int (*callback)();
  18
  19 =head1 DESCRIPTION
  20
  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.
  26
  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
  30 B<ctx> is used.
  31
  32 SSL_CTX_get_info_callback() returns a pointer to the currently set information
  33 callback function for B<ctx>.
  34
  35 SSL_get_info_callback() returns a pointer to the currently set information
  36 callback function for B<ssl>.
  37
  38 =head1 NOTES
  39
  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.
  43
  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 occurred.
  47 If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert
  48 information.
  49
  50 B<where> is a bitmask made up of the following bits:
  51
  52 =over 4
  53
  54 =item SSL_CB_LOOP
  55
  56 Callback has been called to indicate state change inside a loop.
  57
  58 =item SSL_CB_EXIT
  59
  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.)
  62
  63 =item SSL_CB_READ
  64
  65 Callback has been called during read operation.
  66
  67 =item SSL_CB_WRITE
  68
  69 Callback has been called during write operation.
  70
  71 =item SSL_CB_ALERT
  72
  73 Callback has been called due to an alert being sent or received.
  74
  75 =item SSL_CB_READ_ALERT               (SSL_CB_ALERT|SSL_CB_READ)
  76
  77 =item SSL_CB_WRITE_ALERT              (SSL_CB_ALERT|SSL_CB_WRITE)
  78
  79 =item SSL_CB_ACCEPT_LOOP              (SSL_ST_ACCEPT|SSL_CB_LOOP)
  80
  81 =item SSL_CB_ACCEPT_EXIT              (SSL_ST_ACCEPT|SSL_CB_EXIT)
  82
  83 =item SSL_CB_CONNECT_LOOP             (SSL_ST_CONNECT|SSL_CB_LOOP)
  84
  85 =item SSL_CB_CONNECT_EXIT             (SSL_ST_CONNECT|SSL_CB_EXIT)
  86
  87 =item SSL_CB_HANDSHAKE_START
  88
  89 Callback has been called because a new handshake is started.
  90
  91 =item SSL_CB_HANDSHAKE_DONE           0x20
  92
  93 Callback has been called because a handshake is finished.
  94
  95 =back
  96
  97 The current state information can be obtained using the
  98 L<SSL_state_string(3)|SSL_state_string(3)> family of functions.
  99
 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.
 102
 103 =head1 RETURN VALUES
 104
 105 SSL_set_info_callback() does not provide diagnostic information.
 106
 107 SSL_get_info_callback() returns the current setting.
 108
 109 =head1 EXAMPLES
 110
 111 The following example callback function prints state strings, information
 112 about alerts being handled and error messages to the B<bio_err> BIO.
 113
 114  void apps_ssl_info_callback(SSL *s, int where, int ret)
 115         {
 116         const char *str;
 117         int w;
 118
 119         w=where& ~SSL_ST_MASK;
 120
 121         if (w & SSL_ST_CONNECT) str="SSL_connect";
 122         else if (w & SSL_ST_ACCEPT) str="SSL_accept";
 123         else str="undefined";
 124
 125         if (where & SSL_CB_LOOP)
 126                 {
 127                 BIO_printf(bio_err,"%s:%s\n",str,SSL_state_string_long(s));
 128                 }
 129         else if (where & SSL_CB_ALERT)
 130                 {
 131                 str=(where & SSL_CB_READ)?"read":"write";
 132                 BIO_printf(bio_err,"SSL3 alert %s:%s:%s\n",
 133                         str,
 134                         SSL_alert_type_string_long(ret),
 135                         SSL_alert_desc_string_long(ret));
 136                 }
 137         else if (where & SSL_CB_EXIT)
 138                 {
 139                 if (ret == 0)
 140                         BIO_printf(bio_err,"%s:failed in %s\n",
 141                                 str,SSL_state_string_long(s));
 142                 else if (ret < 0)
 143                         {
 144                         BIO_printf(bio_err,"%s:error in %s\n",
 145                                 str,SSL_state_string_long(s));
 146                         }
 147                 }
 148         }
 149
 150 =head1 SEE ALSO
 151
 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)>
 154
 155 =cut