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;
 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(7)>, L<SSL_state_string(3)>,
 151 L<SSL_alert_type_string(3)>
 152
 153 =head1 COPYRIGHT
 154
 155 Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
 156
 157 Licensed under the OpenSSL license (the "License").  You may not use
 158 this file except in compliance with the License.  You can obtain a copy
 159 in the file LICENSE in the source distribution or at
 160 L<https://www.openssl.org/source/license.html>.
 161
 162 =cut