lib/libssl/man/SSL_CTX_set_info_callback.3

   1 .\"     $OpenBSD: SSL_CTX_set_info_callback.3,v 1.2 2016/11/30 18:29:14 schwarze Exp $
   2 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
   3 .\"
   4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
   5 .\" Copyright (c) 2001, 2005, 2014 The OpenSSL Project.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in
  16 .\"    the documentation and/or other materials provided with the
  17 .\"    distribution.
  18 .\"
  19 .\" 3. All advertising materials mentioning features or use of this
  20 .\"    software must display the following acknowledgment:
  21 .\"    "This product includes software developed by the OpenSSL Project
  22 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  23 .\"
  24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  25 .\"    endorse or promote products derived from this software without
  26 .\"    prior written permission. For written permission, please contact
  27 .\"    openssl-core@openssl.org.
  28 .\"
  29 .\" 5. Products derived from this software may not be called "OpenSSL"
  30 .\"    nor may "OpenSSL" appear in their names without prior written
  31 .\"    permission of the OpenSSL Project.
  32 .\"
  33 .\" 6. Redistributions of any form whatsoever must retain the following
  34 .\"    acknowledgment:
  35 .\"    "This product includes software developed by the OpenSSL Project
  36 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  37 .\"
  38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  41 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  50 .\"
  51 .Dd $Mdocdate: November 30 2016 $
  52 .Dt SSL_CTX_SET_INFO_CALLBACK 3
  53 .Os
  54 .Sh NAME
  55 .Nm SSL_CTX_set_info_callback ,
  56 .Nm SSL_CTX_get_info_callback ,
  57 .Nm SSL_set_info_callback ,
  58 .Nm SSL_get_info_callback
  59 .Nd handle information callback for SSL connections
  60 .Sh SYNOPSIS
  61 .In openssl/ssl.h
  62 .Ft void
  63 .Fo SSL_CTX_set_info_callback
  64 .Fa "SSL_CTX *ctx"
  65 .Fa "void (*callback)(const SSL *ssl, int where, int ret)"
  66 .Fc
  67 .Ft void
  68 .Fo "(*SSL_CTX_get_info_callback(const SSL_CTX *ctx))"
  69 .Fa "const SSL *ssl"
  70 .Fa "int where"
  71 .Fa "int ret"
  72 .Fc
  73 .Ft void
  74 .Fo SSL_set_info_callback
  75 .Fa "SSL *ssl"
  76 .Fa "void (*callback)(const SSL *ssl, int where, int ret)"
  77 .Fc
  78 .Ft void
  79 .Fo "(*SSL_get_info_callback(const SSL *ssl))"
  80 .Fa "const SSL *ssl"
  81 .Fa "int where"
  82 .Fa "int ret"
  83 .Fc
  84 .Sh DESCRIPTION
  85 .Fn SSL_CTX_set_info_callback
  86 sets the
  87 .Fa callback
  88 function that can be used to obtain state information for SSL objects created
  89 from
  90 .Fa ctx
  91 during connection setup and use.
  92 The setting for
  93 .Fa ctx
  94 is overridden from the setting for a specific SSL object, if specified.
  95 When
  96 .Fa callback
  97 is
  98 .Dv NULL ,
  99 no callback function is used.
 100 .Pp
 101 .Fn SSL_set_info_callback
 102 sets the
 103 .Fa callback
 104 function that can be used to
 105 obtain state information for
 106 .Fa ssl
 107 during connection setup and use.
 108 When
 109 .Fa callback
 110 is
 111 .Dv NULL ,
 112 the callback setting currently valid for
 113 .Fa ctx
 114 is used.
 115 .Pp
 116 .Fn SSL_CTX_get_info_callback
 117 returns a pointer to the currently set information callback function for
 118 .Fa ctx .
 119 .Pp
 120 .Fn SSL_get_info_callback
 121 returns a pointer to the currently set information callback function for
 122 .Fa ssl .
 123 .Pp
 124 When setting up a connection and during use,
 125 it is possible to obtain state information from the SSL/TLS engine.
 126 When set, an information callback function is called whenever the state changes,
 127 an alert appears, or an error occurs.
 128 .Pp
 129 The callback function is called as
 130 .Fn callback "SSL *ssl" "int where" "int ret" .
 131 The
 132 .Fa where
 133 argument specifies information about where (in which context)
 134 the callback function was called.
 135 If
 136 .Fa ret
 137 is 0, an error condition occurred.
 138 If an alert is handled,
 139 .Dv SSL_CB_ALERT
 140 is set and
 141 .Fa ret
 142 specifies the alert information.
 143 .Pp
 144 .Fa where
 145 is a bitmask made up of the following bits:
 146 .Bl -tag -width Ds
 147 .It Dv SSL_CB_LOOP
 148 Callback has been called to indicate state change inside a loop.
 149 .It Dv SSL_CB_EXIT
 150 Callback has been called to indicate error exit of a handshake function.
 151 (May be soft error with retry option for non-blocking setups.)
 152 .It Dv SSL_CB_READ
 153 Callback has been called during read operation.
 154 .It Dv SSL_CB_WRITE
 155 Callback has been called during write operation.
 156 .It Dv SSL_CB_ALERT
 157 Callback has been called due to an alert being sent or received.
 158 .It Dv SSL_CB_READ_ALERT
 159 .It Dv SSL_CB_WRITE_ALERT
 160 .It Dv SSL_CB_ACCEPT_LOOP
 161 .It Dv SSL_CB_ACCEPT_EXIT
 162 .It Dv SSL_CB_CONNECT_LOOP
 163 .It Dv SSL_CB_CONNECT_EXIT
 164 .It Dv SSL_CB_HANDSHAKE_START
 165 Callback has been called because a new handshake is started.
 166 .It Dv SSL_CB_HANDSHAKE_DONE
 167 Callback has been called because a handshake is finished.
 168 .El
 169 .Pp
 170 The current state information can be obtained using the
 171 .Xr SSL_state_string 3
 172 family of functions.
 173 .Pp
 174 The
 175 .Fa ret
 176 information can be evaluated using the
 177 .Xr SSL_alert_type_string 3
 178 family of functions.
 179 .Sh RETURN VALUES
 180 .Fn SSL_CTX_get_info_callback
 181 and
 182 .Fn SSL_get_info_callback
 183 return a pointer to the current callback or
 184 .Dv NULL
 185 if none is set.
 186 .Sh EXAMPLES
 187 The following example callback function prints state strings,
 188 information about alerts being handled and error messages to the
 189 .Va bio_err
 190 .Vt BIO .
 191 .Bd -literal
 192 void
 193 apps_ssl_info_callback(SSL *s, int where, int ret)
 194 {
 195         const char *str;
 196         int w;
 197
 198         w = where & ~SSL_ST_MASK;
 199
 200         if (w & SSL_ST_CONNECT)
 201                 str = "SSL_connect";
 202         else if (w & SSL_ST_ACCEPT)
 203                 str = "SSL_accept";
 204         else
 205                 str = "undefined";
 206
 207         if (where & SSL_CB_LOOP) {
 208                 BIO_printf(bio_err, "%s:%s\en", str,
 209                     SSL_state_string_long(s));
 210         } else if (where & SSL_CB_ALERT) {
 211                 str = (where & SSL_CB_READ) ? "read" : "write";
 212                 BIO_printf(bio_err, "SSL3 alert %s:%s:%s\en", str,
 213                         SSL_alert_type_string_long(ret),
 214                         SSL_alert_desc_string_long(ret));
 215         } else if (where & SSL_CB_EXIT) {
 216                 if (ret == 0)
 217                         BIO_printf(bio_err, "%s:failed in %s\en",
 218                                 str, SSL_state_string_long(s));
 219                 else if (ret < 0) {
 220                         BIO_printf(bio_err, "%s:error in %s\en",
 221                                 str, SSL_state_string_long(s));
 222                 }
 223         }
 224 }
 225 .Ed
 226 .Sh SEE ALSO
 227 .Xr ssl 3 ,
 228 .Xr SSL_alert_type_string 3 ,
 229 .Xr SSL_state_string 3