doc/man3/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, no 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)> family of functions.
  97
  98 The B<ret> information can be evaluated using the
  99 L<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 = where & ~SSL_ST_MASK;
 116
 117      if (w & SSL_ST_CONNECT)
 118          str = "SSL_connect";
 119      else if (w & SSL_ST_ACCEPT)
 120          str = "SSL_accept";
 121      else
 122          str = "undefined";
 123
 124      if (where & SSL_CB_LOOP) {
 125          BIO_printf(bio_err, "%s:%s\n", str, SSL_state_string_long(s));
 126      } else if (where & SSL_CB_ALERT) {
 127          str = (where & SSL_CB_READ) ? "read" : "write";
 128          BIO_printf(bio_err, "SSL3 alert %s:%s:%s\n", str,
 129                     SSL_alert_type_string_long(ret),
 130                     SSL_alert_desc_string_long(ret));
 131      } else if (where & SSL_CB_EXIT) {
 132          if (ret == 0) {
 133              BIO_printf(bio_err, "%s:failed in %s\n",
 134                         str, SSL_state_string_long(s));
 135          } else if (ret < 0) {
 136              BIO_printf(bio_err, "%s:error in %s\n",
 137                         str, SSL_state_string_long(s));
 138          }
 139      }
 140  }
 141
 142 =head1 SEE ALSO
 143
 144 L<ssl(7)>, L<SSL_state_string(3)>,
 145 L<SSL_alert_type_string(3)>
 146
 147 =head1 COPYRIGHT
 148
 149 Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
 150
 151 Licensed under the OpenSSL license (the "License").  You may not use
 152 this file except in compliance with the License.  You can obtain a copy
 153 in the file LICENSE in the source distribution or at
 154 L<https://www.openssl.org/source/license.html>.
 155
 156 =cut