The last character of inconsistency in my recent commits is hereby
[openssl.git] / doc / ssl / 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(SSL_CTX *ctx))();
13
14  void SSL_set_info_callback(SSL *ssl, void (*callback)());
15  void (*SSL_get_info_callback(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, not 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)|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)|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(3)|ssl(3)>, L<SSL_state_string(3)|SSL_state_string(3)>,
151 L<SSL_alert_type_string(3)|SSL_alert_type_string(3)>
152
153 =cut