From f1b2807478ba528602bad4227c768082f98821c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lutz=20J=C3=A4nicke?= Date: Fri, 24 Aug 2001 14:29:48 +0000 Subject: [PATCH] More docs. --- doc/ssl/SSL_CTX_set_info_callback.pod | 155 ++++++++++++++++++++++++++ doc/ssl/SSL_alert_type_string.pod | 2 +- doc/ssl/SSL_state_string.pod | 2 +- doc/ssl/ssl.pod | 1 + 4 files changed, 158 insertions(+), 2 deletions(-) create mode 100644 doc/ssl/SSL_CTX_set_info_callback.pod diff --git a/doc/ssl/SSL_CTX_set_info_callback.pod b/doc/ssl/SSL_CTX_set_info_callback.pod new file mode 100644 index 0000000000..15dab2f1b1 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_info_callback.pod @@ -0,0 +1,155 @@ +=pod + +=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 + +=head1 SYNOPSIS + + #include + + void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)()); + void (*SSL_CTX_get_info_callback(SSL_CTX *ctx))(); + + void SSL_set_info_callback(SSL *ssl, void (*callback)()); + void (*SSL_get_info_callback(SSL *ssl))(); + + int (*callback)(); + +=head1 DESCRIPTION + +SSL_CTX_set_info_callback() sets the B function, that can be used to +obtain state information for SSL objects created from B during connection +setup and use. The setting for B is overridden from the setting for +a specific SSL object, if specified. +When B is NULL, not callback function is used. + +SSL_set_info_callback() sets the B function, that can be used to +obtain state information for B during connection setup and use. +When B is NULL, the callback setting currently valid for +B is used. + +SSL_CTX_get_info_callback() returns a pointer to the currently set information +callback function for B. + +SSL_get_info_callback() returns a pointer to the currently set information +callback function for B. + +=head1 NOTES + +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. + +The callback function is called as B. +The B argument specifies information about where (in which context) +the callback function was called. If B is 0, an error condition occured. +If an alert is handled, SSL_CB_ALERT is set and B specifies the alert +information. + +B is a bitmask made up of the following bits: + +=over 4 + +=item SSL_CB_LOOP + +Callback has been called to indicate state change inside a loop. + +=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.) + +=item SSL_CB_READ + +Callback has been called during read operation. + +=item SSL_CB_WRITE + +Callback has been called during write operation. + +=item SSL_CB_ALERT + +Callback has been called due to an alert being sent or received. + +=item SSL_CB_READ_ALERT (SSL_CB_ALERT|SSL_CB_READ) + +=item SSL_CB_WRITE_ALERT (SSL_CB_ALERT|SSL_CB_WRITE) + +=item SSL_CB_ACCEPT_LOOP (SSL_ST_ACCEPT|SSL_CB_LOOP) + +=item SSL_CB_ACCEPT_EXIT (SSL_ST_ACCEPT|SSL_CB_EXIT) + +=item SSL_CB_CONNECT_LOOP (SSL_ST_CONNECT|SSL_CB_LOOP) + +=item SSL_CB_CONNECT_EXIT (SSL_ST_CONNECT|SSL_CB_EXIT) + +=item SSL_CB_HANDSHAKE_START + +Callback has been called because a new handshake is started. + +=item SSL_CB_HANDSHAKE_DONE 0x20 + +Callback has been called because a handshake is finished. + +=back + +The current state information can be obtained using the +L family of functions. + +The B information can be evaluated using the +L family of functions. + +=head1 RETURN VALUES + +SSL_set_info_callback() does not provide diagnostic information. + +SSL_get_info_callback() returns the current setting. + +=head1 EXAMPLES + +The following example callback function prints state strings, information +about alerts being handled and error messages to the B 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)); + } + } + } + +=head1 SEE ALSO + +L, L, +L + +=cut diff --git a/doc/ssl/SSL_alert_type_string.pod b/doc/ssl/SSL_alert_type_string.pod index 4b552399f3..e9acd934a7 100644 --- a/doc/ssl/SSL_alert_type_string.pod +++ b/doc/ssl/SSL_alert_type_string.pod @@ -223,6 +223,6 @@ Probably B does not contain a correct alert message. =head1 SEE ALSO -L +L, L =cut diff --git a/doc/ssl/SSL_state_string.pod b/doc/ssl/SSL_state_string.pod index 39ca5f29fa..b4be1aaa48 100644 --- a/doc/ssl/SSL_state_string.pod +++ b/doc/ssl/SSL_state_string.pod @@ -40,6 +40,6 @@ Detailed description of possible states to be included later. =head1 SEE ALSO -L +L, L =cut diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod index 5cee288442..6845f4f76d 100644 --- a/doc/ssl/ssl.pod +++ b/doc/ssl/ssl.pod @@ -668,6 +668,7 @@ L, L, L, L, +L, L, L, L, -- GitLab