More docs.
[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  int (*callback)();
18
19 =head1 DESCRIPTION
20
21 SSL_CTX_set_info_callback() sets the B<callback> function, that can be used to
22 obtain state information for SSL objects created from B<ctx> during connection
23 setup and use. The setting for B<ctx> is overridden from the setting for
24 a specific SSL object, if specified.
25 When B<callback> is NULL, not callback function is used.
26
27 SSL_set_info_callback() sets the B<callback> function, that can be used to
28 obtain state information for B<ssl> during connection setup and use.
29 When B<callback> is NULL, the callback setting currently valid for
30 B<ctx> is used.
31
32 SSL_CTX_get_info_callback() returns a pointer to the currently set information
33 callback function for B<ctx>.
34
35 SSL_get_info_callback() returns a pointer to the currently set information
36 callback function for B<ssl>.
37
38 =head1 NOTES
39
40 When setting up a connection and during use, it is possible to obtain state
41 information from the SSL/TLS engine. When set, an information callback function
42 is called whenever the state changes, an alert appears, or an error occurs.
43
44 The callback function is called as B<callback(SSL *ssl, int where, int ret)>.
45 The B<where> argument specifies information about where (in which context)
46 the callback function was called. If B<ret> is 0, an error condition occured.
47 If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert
48 information.
49
50 B<where> is a bitmask made up of the following bits:
51
52 =over 4
53
54 =item SSL_CB_LOOP
55
56 Callback has been called to indicate state change inside a loop.
57
58 =item SSL_CB_EXIT
59
60 Callback has been called to indicate error exit of a handshake function.
61 (May be soft error with retry option for non-blocking setups.)
62
63 =item SSL_CB_READ
64
65 Callback has been called during read operation.
66
67 =item SSL_CB_WRITE
68
69 Callback has been called during write operation.
70
71 =item SSL_CB_ALERT
72
73 Callback has been called due to an alert being sent or received.
74
75 =item SSL_CB_READ_ALERT               (SSL_CB_ALERT|SSL_CB_READ)
76
77 =item SSL_CB_WRITE_ALERT              (SSL_CB_ALERT|SSL_CB_WRITE)
78
79 =item SSL_CB_ACCEPT_LOOP              (SSL_ST_ACCEPT|SSL_CB_LOOP)
80
81 =item SSL_CB_ACCEPT_EXIT              (SSL_ST_ACCEPT|SSL_CB_EXIT)
82
83 =item SSL_CB_CONNECT_LOOP             (SSL_ST_CONNECT|SSL_CB_LOOP)
84
85 =item SSL_CB_CONNECT_EXIT             (SSL_ST_CONNECT|SSL_CB_EXIT)
86
87 =item SSL_CB_HANDSHAKE_START
88
89 Callback has been called because a new handshake is started.
90
91 =item SSL_CB_HANDSHAKE_DONE           0x20
92
93 Callback has been called because a handshake is finished.
94
95 =back
96
97 The current state information can be obtained using the
98 L<SSL_state_string(3)|SSL_state_string(3)> family of functions.
99
100 The B<ret> information can be evaluated using the
101 L<SSL_alert_type_string(3)|SSL_alert_type_string(3)> family of functions.
102
103 =head1 RETURN VALUES
104
105 SSL_set_info_callback() does not provide diagnostic information.
106
107 SSL_get_info_callback() returns the current setting.
108
109 =head1 EXAMPLES
110
111 The following example callback function prints state strings, information
112 about alerts being handled and error messages to the B<bio_err> BIO.
113
114  void apps_ssl_info_callback(SSL *s, int where, int ret)
115         {
116         const char *str;
117         int w;
118
119         w=where& ~SSL_ST_MASK;
120
121         if (w & SSL_ST_CONNECT) str="SSL_connect";
122         else if (w & SSL_ST_ACCEPT) str="SSL_accept";
123         else str="undefined";
124
125         if (where & SSL_CB_LOOP)
126                 {
127                 BIO_printf(bio_err,"%s:%s\n",str,SSL_state_string_long(s));
128                 }
129         else if (where & SSL_CB_ALERT)
130                 {
131                 str=(where & SSL_CB_READ)?"read":"write";
132                 BIO_printf(bio_err,"SSL3 alert %s:%s:%s\n",
133                         str,
134                         SSL_alert_type_string_long(ret),
135                         SSL_alert_desc_string_long(ret));
136                 }
137         else if (where & SSL_CB_EXIT)
138                 {
139                 if (ret == 0)
140                         BIO_printf(bio_err,"%s:failed in %s\n",
141                                 str,SSL_state_string_long(s));
142                 else if (ret < 0)
143                         {
144                         BIO_printf(bio_err,"%s:error in %s\n",
145                                 str,SSL_state_string_long(s));
146                         }
147                 }
148         }
149
150 =head1 SEE ALSO
151
152 L<ssl(3)|ssl(3)>, L<SSL_state_string(3)|SSL_state_string(3)>,
153 L<SSL_alert_type_string(3)|SSL_alert_type_string(3)>
154
155 =cut