evp_rand: documentation

[openssl.git] / doc / man3 / SSL_CTX_set_info_callback.pod

diff --git a/doc/man3/SSL_CTX_set_info_callback.pod b/doc/man3/SSL_CTX_set_info_callback.pod
index f36f217e3bde4dd9a7f8bb42d5f7bbbf960aa9c3..399a83c757fea50509088961ea510d76fc2ba246 100644 (file)
--- a/doc/man3/SSL_CTX_set_info_callback.pod
+++ b/doc/man3/SSL_CTX_set_info_callback.pod
@@ -2,7 +2,11 @@
 
 =head1 NAME
 
-SSL_CTX_set_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, SSL_get_info_callback - handle information callback for SSL connections
+SSL_CTX_set_info_callback,
+SSL_CTX_get_info_callback,
+SSL_set_info_callback,
+SSL_get_info_callback
+- handle information callback for SSL connections
 
 =head1 SYNOPSIS
 
@@ -37,7 +41,8 @@ callback function for B<ssl>.
 
 When setting up a connection and during use, it is possible to obtain state
 information from the SSL/TLS engine. When set, an information callback function
-is called whenever the state changes, an alert appears, or an error occurs.
+is called whenever a significant event occurs such as: the state changes,
+an alert appears, or an error occurs.
 
 The callback function is called as B<callback(SSL *ssl, int where, int ret)>.
 The B<where> argument specifies information about where (in which context)
@@ -45,18 +50,21 @@ the callback function was called. If B<ret> is 0, an error condition occurred.
 If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert
 information.
 
-B<where> is a bitmask made up of the following bits:
+B<where> is a bit-mask made up of the following bits:
 
 =over 4
 
 =item SSL_CB_LOOP
 
-Callback has been called to indicate state change inside a loop.
+Callback has been called to indicate state change or some other significant
+state machine event. This may mean that the callback gets invoked more than once
+per state in some situations.
 
 =item SSL_CB_EXIT
 
-Callback has been called to indicate error exit of a handshake function.
-(May be soft error with retry option for non-blocking setups.)
+Callback has been called to indicate exit of a handshake function. This will
+happen after the end of a handshake, but may happen at other times too such as
+on error or when IO might otherwise block and non-blocking is being used.
 
 =item SSL_CB_READ
 
@@ -84,11 +92,13 @@ Callback has been called due to an alert being sent or received.
 
 =item SSL_CB_HANDSHAKE_START
 
-Callback has been called because a new handshake is started.
+Callback has been called because a new handshake is started. It also occurs when
+resuming a handshake following a pause to handle early data.
 
-=item SSL_CB_HANDSHAKE_DONE           0x20
+=item SSL_CB_HANDSHAKE_DONE
 
-Callback has been called because a handshake is finished.
+Callback has been called because a handshake is finished.  It also occurs if the
+handshake is paused to allow the exchange of early data.
 
 =back
 
@@ -110,51 +120,45 @@ The following example callback function prints state strings, information
 about alerts being handled and error messages to the B<bio_err> BIO.
 
  void apps_ssl_info_callback(SSL *s, int where, int ret)
-        {
-        const char *str;
-        int w;
-
-        w = where & ~SSL_ST_MASK;
-
-        if (w & SSL_ST_CONNECT) str = "SSL_connect";
-        else if (w & SSL_ST_ACCEPT) str = "SSL_accept";
-        else str = "undefined";
-
-        if (where & SSL_CB_LOOP)
-                {
-                BIO_printf(bio_err, "%s:%s\n", str, SSL_state_string_long(s));
-                }
-        else if (where & SSL_CB_ALERT)
-                {
-                str = (where & SSL_CB_READ) ? "read" : "write";
-                BIO_printf(bio_err, "SSL3 alert %s:%s:%s\n",
-                        str,
-                        SSL_alert_type_string_long(ret),
-                        SSL_alert_desc_string_long(ret));
-                }
-        else if (where & SSL_CB_EXIT)
-                {
-                if (ret == 0)
-                        BIO_printf(bio_err, "%s:failed in %s\n",
-                                str, SSL_state_string_long(s));
-                else if (ret < 0)
-                        {
-                        BIO_printf(bio_err, "%s:error in %s\n",
-                                str, SSL_state_string_long(s));
-                        }
-                }
-        }
+ {
+     const char *str;
+     int w = where & ~SSL_ST_MASK;
+
+     if (w & SSL_ST_CONNECT)
+         str = "SSL_connect";
+     else if (w & SSL_ST_ACCEPT)
+         str = "SSL_accept";
+     else
+         str = "undefined";
+
+     if (where & SSL_CB_LOOP) {
+         BIO_printf(bio_err, "%s:%s\n", str, SSL_state_string_long(s));
+     } else if (where & SSL_CB_ALERT) {
+         str = (where & SSL_CB_READ) ? "read" : "write";
+         BIO_printf(bio_err, "SSL3 alert %s:%s:%s\n", str,
+                    SSL_alert_type_string_long(ret),
+                    SSL_alert_desc_string_long(ret));
+     } else if (where & SSL_CB_EXIT) {
+         if (ret == 0) {
+             BIO_printf(bio_err, "%s:failed in %s\n",
+                        str, SSL_state_string_long(s));
+         } else if (ret < 0) {
+             BIO_printf(bio_err, "%s:error in %s\n",
+                        str, SSL_state_string_long(s));
+         }
+     }
+ }
 
 =head1 SEE ALSO
 
-L<ssl(3)>, L<SSL_state_string(3)>,
+L<ssl(7)>, L<SSL_state_string(3)>,
 L<SSL_alert_type_string(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.