summaryrefslogtreecommitdiff
path: root/src/lib/libssl/doc/SSL_CTX_set_info_callback.3
diff options
context:
space:
mode:
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.3167
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
25sets the
26.Fa callback
27function that can be used to obtain state information for SSL objects created
28from
29.Fa ctx
30during connection setup and use.
31The setting for
32.Fa ctx
33is overridden from the setting for a specific SSL object, if specified.
34When
35.Fa callback
36is
37.Dv NULL ,
38no callback function is used.
39.Pp
40.Fn SSL_set_info_callback
41sets the
42.Fa callback
43function that can be used to
44obtain state information for
45.Fa ssl
46during connection setup and use.
47When
48.Fa callback
49is
50.Dv NULL ,
51the callback setting currently valid for
52.Fa ctx
53is used.
54.Pp
55.Fn SSL_CTX_get_info_callback
56returns a pointer to the currently set information callback function for
57.Fa ctx .
58.Pp
59.Fn SSL_get_info_callback
60returns a pointer to the currently set information callback function for
61.Fa ssl .
62.Sh NOTES
63When setting up a connection and during use,
64it is possible to obtain state information from the SSL/TLS engine.
65When set, an information callback function is called whenever the state changes,
66an alert appears, or an error occurs.
67.Pp
68The callback function is called as
69.Fn callback "SSL *ssl" "int where" "int ret" .
70The
71.Fa where
72argument specifies information about where (in which context)
73the callback function was called.
74If
75.Fa ret
76is 0, an error condition occurred.
77If an alert is handled,
78.Dv SSL_CB_ALERT
79is set and
80.Fa ret
81specifies the alert information.
82.Pp
83.Fa where
84is a bitmask made up of the following bits:
85.Bl -tag -width Ds
86.It Dv SSL_CB_LOOP
87Callback has been called to indicate state change inside a loop.
88.It Dv SSL_CB_EXIT
89Callback 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
92Callback has been called during read operation.
93.It Dv SSL_CB_WRITE
94Callback has been called during write operation.
95.It Dv SSL_CB_ALERT
96Callback 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
104Callback has been called because a new handshake is started.
105.It Dv SSL_CB_HANDSHAKE_DONE
106Callback has been called because a handshake is finished.
107.El
108.Pp
109The current state information can be obtained using the
110.Xr SSL_state_string 3
111family of functions.
112.Pp
113The
114.Fa ret
115information can be evaluated using the
116.Xr SSL_alert_type_string 3
117family of functions.
118.Sh RETURN VALUES
119.Fn SSL_set_info_callback
120does not provide diagnostic information.
121.Pp
122.Fn SSL_get_info_callback
123returns the current setting.
124.Sh EXAMPLES
125The following example callback function prints state strings,
126information about alerts being handled and error messages to the
127.Va bio_err
128.Vt BIO .
129.Bd -literal
130void
131apps_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