diff options
Diffstat (limited to 'src/lib/libssl/doc/SSL_CTX_set_info_callback.3')
-rw-r--r-- | src/lib/libssl/doc/SSL_CTX_set_info_callback.3 | 167 |
1 files changed, 0 insertions, 167 deletions
diff --git a/src/lib/libssl/doc/SSL_CTX_set_info_callback.3 b/src/lib/libssl/doc/SSL_CTX_set_info_callback.3 deleted file mode 100644 index 24ee74dda9..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_info_callback.3 +++ /dev/null | |||
@@ -1,167 +0,0 @@ | |||
1 | .\" | ||
2 | .\" $OpenBSD: SSL_CTX_set_info_callback.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ | ||
3 | .\" | ||
4 | .Dd $Mdocdate: December 2 2014 $ | ||
5 | .Dt SSL_CTX_SET_INFO_CALLBACK 3 | ||
6 | .Os | ||
7 | .Sh NAME | ||
8 | .Nm SSL_CTX_set_info_callback , | ||
9 | .Nm SSL_CTX_get_info_callback , | ||
10 | .Nm SSL_set_info_callback , | ||
11 | .Nm SSL_get_info_callback | ||
12 | .Nd handle information callback for SSL connections | ||
13 | .Sh SYNOPSIS | ||
14 | .In openssl/ssl.h | ||
15 | .Ft void | ||
16 | .Fn SSL_CTX_set_info_callback "SSL_CTX *ctx" "void (*callback)()" | ||
17 | .Ft void | ||
18 | .Fn "(*SSL_CTX_get_info_callback(const SSL_CTX *ctx))" | ||
19 | .Ft void | ||
20 | .Fn SSL_set_info_callback "SSL *ssl" "void (*callback)()" | ||
21 | .Ft void | ||
22 | .Fn "(*SSL_get_info_callback(const SSL *ssl))" | ||
23 | .Sh DESCRIPTION | ||
24 | .Fn SSL_CTX_set_info_callback | ||
25 | sets the | ||
26 | .Fa callback | ||
27 | function that can be used to obtain state information for SSL objects created | ||
28 | from | ||
29 | .Fa ctx | ||
30 | during connection setup and use. | ||
31 | The setting for | ||
32 | .Fa ctx | ||
33 | is overridden from the setting for a specific SSL object, if specified. | ||
34 | When | ||
35 | .Fa callback | ||
36 | is | ||
37 | .Dv NULL , | ||
38 | no callback function is used. | ||
39 | .Pp | ||
40 | .Fn SSL_set_info_callback | ||
41 | sets the | ||
42 | .Fa callback | ||
43 | function that can be used to | ||
44 | obtain state information for | ||
45 | .Fa ssl | ||
46 | during connection setup and use. | ||
47 | When | ||
48 | .Fa callback | ||
49 | is | ||
50 | .Dv NULL , | ||
51 | the callback setting currently valid for | ||
52 | .Fa ctx | ||
53 | is used. | ||
54 | .Pp | ||
55 | .Fn SSL_CTX_get_info_callback | ||
56 | returns a pointer to the currently set information callback function for | ||
57 | .Fa ctx . | ||
58 | .Pp | ||
59 | .Fn SSL_get_info_callback | ||
60 | returns a pointer to the currently set information callback function for | ||
61 | .Fa ssl . | ||
62 | .Sh NOTES | ||
63 | When setting up a connection and during use, | ||
64 | it is possible to obtain state information from the SSL/TLS engine. | ||
65 | When set, an information callback function is called whenever the state changes, | ||
66 | an alert appears, or an error occurs. | ||
67 | .Pp | ||
68 | The callback function is called as | ||
69 | .Fn callback "SSL *ssl" "int where" "int ret" . | ||
70 | The | ||
71 | .Fa where | ||
72 | argument specifies information about where (in which context) | ||
73 | the callback function was called. | ||
74 | If | ||
75 | .Fa ret | ||
76 | is 0, an error condition occurred. | ||
77 | If an alert is handled, | ||
78 | .Dv SSL_CB_ALERT | ||
79 | is set and | ||
80 | .Fa ret | ||
81 | specifies the alert information. | ||
82 | .Pp | ||
83 | .Fa where | ||
84 | is a bitmask made up of the following bits: | ||
85 | .Bl -tag -width Ds | ||
86 | .It Dv SSL_CB_LOOP | ||
87 | Callback has been called to indicate state change inside a loop. | ||
88 | .It Dv SSL_CB_EXIT | ||
89 | Callback has been called to indicate error exit of a handshake function. | ||
90 | (May be soft error with retry option for non-blocking setups.) | ||
91 | .It Dv SSL_CB_READ | ||
92 | Callback has been called during read operation. | ||
93 | .It Dv SSL_CB_WRITE | ||
94 | Callback has been called during write operation. | ||
95 | .It Dv SSL_CB_ALERT | ||
96 | Callback has been called due to an alert being sent or received. | ||
97 | .It Dv SSL_CB_READ_ALERT | ||
98 | .It Dv SSL_CB_WRITE_ALERT | ||
99 | .It Dv SSL_CB_ACCEPT_LOOP | ||
100 | .It Dv SSL_CB_ACCEPT_EXIT | ||
101 | .It Dv SSL_CB_CONNECT_LOOP | ||
102 | .It Dv SSL_CB_CONNECT_EXIT | ||
103 | .It Dv SSL_CB_HANDSHAKE_START | ||
104 | Callback has been called because a new handshake is started. | ||
105 | .It Dv SSL_CB_HANDSHAKE_DONE | ||
106 | Callback has been called because a handshake is finished. | ||
107 | .El | ||
108 | .Pp | ||
109 | The current state information can be obtained using the | ||
110 | .Xr SSL_state_string 3 | ||
111 | family of functions. | ||
112 | .Pp | ||
113 | The | ||
114 | .Fa ret | ||
115 | information can be evaluated using the | ||
116 | .Xr SSL_alert_type_string 3 | ||
117 | family of functions. | ||
118 | .Sh RETURN VALUES | ||
119 | .Fn SSL_set_info_callback | ||
120 | does not provide diagnostic information. | ||
121 | .Pp | ||
122 | .Fn SSL_get_info_callback | ||
123 | returns the current setting. | ||
124 | .Sh EXAMPLES | ||
125 | The following example callback function prints state strings, | ||
126 | information about alerts being handled and error messages to the | ||
127 | .Va bio_err | ||
128 | .Vt BIO . | ||
129 | .Bd -literal | ||
130 | void | ||
131 | apps_ssl_info_callback(SSL *s, int where, int ret) | ||
132 | { | ||
133 | const char *str; | ||
134 | int w; | ||
135 | |||
136 | w = where & ~SSL_ST_MASK; | ||
137 | |||
138 | if (w & SSL_ST_CONNECT) | ||
139 | str = "SSL_connect"; | ||
140 | else if (w & SSL_ST_ACCEPT) | ||
141 | str = "SSL_accept"; | ||
142 | else | ||
143 | str = "undefined"; | ||
144 | |||
145 | if (where & SSL_CB_LOOP) { | ||
146 | BIO_printf(bio_err, "%s:%s\en", str, | ||
147 | SSL_state_string_long(s)); | ||
148 | } else if (where & SSL_CB_ALERT) { | ||
149 | str = (where & SSL_CB_READ) ? "read" : "write"; | ||
150 | BIO_printf(bio_err, "SSL3 alert %s:%s:%s\en", str, | ||
151 | SSL_alert_type_string_long(ret), | ||
152 | SSL_alert_desc_string_long(ret)); | ||
153 | } else if (where & SSL_CB_EXIT) { | ||
154 | if (ret == 0) | ||
155 | BIO_printf(bio_err, "%s:failed in %s\en", | ||
156 | str, SSL_state_string_long(s)); | ||
157 | else if (ret < 0) { | ||
158 | BIO_printf(bio_err, "%s:error in %s\en", | ||
159 | str, SSL_state_string_long(s)); | ||
160 | } | ||
161 | } | ||
162 | } | ||
163 | .Ed | ||
164 | .Sh SEE ALSO | ||
165 | .Xr ssl 3 , | ||
166 | .Xr SSL_alert_type_string 3 , | ||
167 | .Xr SSL_state_string 3 | ||