xref: /openbsd-src/lib/libssl/man/SSL_get_error.3 (revision f1a3c524c21bf4122aaccb0a497f91f0df230141)
1*f1a3c524Sschwarze.\"
2*f1a3c524Sschwarze.\"	$OpenBSD: SSL_get_error.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $
3*f1a3c524Sschwarze.\"
4*f1a3c524Sschwarze.Dd $Mdocdate: November 5 2016 $
5*f1a3c524Sschwarze.Dt SSL_GET_ERROR 3
6*f1a3c524Sschwarze.Os
7*f1a3c524Sschwarze.Sh NAME
8*f1a3c524Sschwarze.Nm SSL_get_error
9*f1a3c524Sschwarze.Nd obtain result code for TLS/SSL I/O operation
10*f1a3c524Sschwarze.Sh SYNOPSIS
11*f1a3c524Sschwarze.In openssl/ssl.h
12*f1a3c524Sschwarze.Ft int
13*f1a3c524Sschwarze.Fn SSL_get_error "const SSL *ssl" "int ret"
14*f1a3c524Sschwarze.Sh DESCRIPTION
15*f1a3c524Sschwarze.Fn SSL_get_error
16*f1a3c524Sschwarzereturns a result code (suitable for the C
17*f1a3c524Sschwarze.Dq switch
18*f1a3c524Sschwarzestatement) for a preceding call to
19*f1a3c524Sschwarze.Xr SSL_connect 3 ,
20*f1a3c524Sschwarze.Xr SSL_accept 3 ,
21*f1a3c524Sschwarze.Xr SSL_do_handshake 3 ,
22*f1a3c524Sschwarze.Xr SSL_read 3 ,
23*f1a3c524Sschwarze.Xr SSL_peek 3 ,
24*f1a3c524Sschwarzeor
25*f1a3c524Sschwarze.Xr SSL_write 3
26*f1a3c524Sschwarzeon
27*f1a3c524Sschwarze.Fa ssl .
28*f1a3c524SschwarzeThe value returned by that TLS/SSL I/O function must be passed to
29*f1a3c524Sschwarze.Fn SSL_get_error
30*f1a3c524Sschwarzein parameter
31*f1a3c524Sschwarze.Fa ret .
32*f1a3c524Sschwarze.Pp
33*f1a3c524SschwarzeIn addition to
34*f1a3c524Sschwarze.Fa ssl
35*f1a3c524Sschwarzeand
36*f1a3c524Sschwarze.Fa ret ,
37*f1a3c524Sschwarze.Fn SSL_get_error
38*f1a3c524Sschwarzeinspects the current thread's OpenSSL error queue.
39*f1a3c524SschwarzeThus,
40*f1a3c524Sschwarze.Fn SSL_get_error
41*f1a3c524Sschwarzemust be used in the same thread that performed the TLS/SSL I/O operation,
42*f1a3c524Sschwarzeand no other OpenSSL function calls should appear in between.
43*f1a3c524SschwarzeThe current thread's error queue must be empty before the TLS/SSL I/O operation
44*f1a3c524Sschwarzeis attempted, or
45*f1a3c524Sschwarze.Fn SSL_get_error
46*f1a3c524Sschwarzewill not work reliably.
47*f1a3c524Sschwarze.Sh RETURN VALUES
48*f1a3c524SschwarzeThe following return values can currently occur:
49*f1a3c524Sschwarze.Bl -tag -width Ds
50*f1a3c524Sschwarze.It Dv SSL_ERROR_NONE
51*f1a3c524SschwarzeThe TLS/SSL I/O operation completed.
52*f1a3c524SschwarzeThis result code is returned if and only if
53*f1a3c524Sschwarze.Fa ret
54*f1a3c524Sschwarze< 0.
55*f1a3c524Sschwarze.It Dv SSL_ERROR_ZERO_RETURN
56*f1a3c524SschwarzeThe TLS/SSL connection has been closed.
57*f1a3c524SschwarzeIf the protocol version is SSL 3.0 or TLS 1.0, this result code is returned
58*f1a3c524Sschwarzeonly if a closure alert has occurred in the protocol, i.e., if the connection
59*f1a3c524Sschwarzehas been closed cleanly.
60*f1a3c524SschwarzeNote that in this case
61*f1a3c524Sschwarze.Dv SSL_ERROR_ZERO_RETURN
62*f1a3c524Sschwarzedoes not necessarily indicate that the underlying transport has been closed.
63*f1a3c524Sschwarze.It Dv SSL_ERROR_WANT_READ , Dv SSL_ERROR_WANT_WRITE
64*f1a3c524SschwarzeThe operation did not complete;
65*f1a3c524Sschwarzethe same TLS/SSL I/O function should be called again later.
66*f1a3c524SschwarzeIf, by then, the underlying
67*f1a3c524Sschwarze.Vt BIO
68*f1a3c524Sschwarzehas data available for reading (if the result code is
69*f1a3c524Sschwarze.Dv SSL_ERROR_WANT_READ )
70*f1a3c524Sschwarzeor allows writing data
71*f1a3c524Sschwarze.Pq Dv SSL_ERROR_WANT_WRITE ,
72*f1a3c524Sschwarzethen some TLS/SSL protocol progress will take place,
73*f1a3c524Sschwarzei.e., at least part of a TLS/SSL record will be read or written.
74*f1a3c524SschwarzeNote that the retry may again lead to a
75*f1a3c524Sschwarze.Dv SSL_ERROR_WANT_READ
76*f1a3c524Sschwarzeor
77*f1a3c524Sschwarze.Dv SSL_ERROR_WANT_WRITE
78*f1a3c524Sschwarzecondition.
79*f1a3c524SschwarzeThere is no fixed upper limit for the number of iterations that may be
80*f1a3c524Sschwarzenecessary until progress becomes visible at application protocol level.
81*f1a3c524Sschwarze.Pp
82*f1a3c524SschwarzeFor socket
83*f1a3c524Sschwarze.Fa BIO Ns
84*f1a3c524Sschwarzes (e.g., when
85*f1a3c524Sschwarze.Fn SSL_set_fd
86*f1a3c524Sschwarzewas used),
87*f1a3c524Sschwarze.Xr select 2
88*f1a3c524Sschwarzeor
89*f1a3c524Sschwarze.Xr poll 2
90*f1a3c524Sschwarzeon the underlying socket can be used to find out when the TLS/SSL I/O function
91*f1a3c524Sschwarzeshould be retried.
92*f1a3c524Sschwarze.Pp
93*f1a3c524SschwarzeCaveat: Any TLS/SSL I/O function can lead to either of
94*f1a3c524Sschwarze.Dv SSL_ERROR_WANT_READ
95*f1a3c524Sschwarzeand
96*f1a3c524Sschwarze.Dv SSL_ERROR_WANT_WRITE .
97*f1a3c524SschwarzeIn particular,
98*f1a3c524Sschwarze.Xr SSL_read 3
99*f1a3c524Sschwarzeor
100*f1a3c524Sschwarze.Xr SSL_peek 3
101*f1a3c524Sschwarzemay want to write data and
102*f1a3c524Sschwarze.Xr SSL_write 3
103*f1a3c524Sschwarzemay want
104*f1a3c524Sschwarzeto read data.
105*f1a3c524SschwarzeThis is mainly because TLS/SSL handshakes may occur at any time during the
106*f1a3c524Sschwarzeprotocol (initiated by either the client or the server);
107*f1a3c524Sschwarze.Xr SSL_read 3 ,
108*f1a3c524Sschwarze.Xr SSL_peek 3 ,
109*f1a3c524Sschwarzeand
110*f1a3c524Sschwarze.Xr SSL_write 3
111*f1a3c524Sschwarzewill handle any pending handshakes.
112*f1a3c524Sschwarze.It Dv SSL_ERROR_WANT_CONNECT , Dv SSL_ERROR_WANT_ACCEPT
113*f1a3c524SschwarzeThe operation did not complete; the same TLS/SSL I/O function should be
114*f1a3c524Sschwarzecalled again later.
115*f1a3c524SschwarzeThe underlying BIO was not connected yet to the peer and the call would block
116*f1a3c524Sschwarzein
117*f1a3c524Sschwarze.Xr connect 2 Ns / Ns
118*f1a3c524Sschwarze.Xr accept 2 .
119*f1a3c524SschwarzeThe SSL function should be
120*f1a3c524Sschwarzecalled again when the connection is established.
121*f1a3c524SschwarzeThese messages can only appear with a
122*f1a3c524Sschwarze.Xr BIO_s_connect 3
123*f1a3c524Sschwarzeor
124*f1a3c524Sschwarze.Xr BIO_s_accept 3
125*f1a3c524Sschwarze.Vt BIO ,
126*f1a3c524Sschwarzerespectively.
127*f1a3c524SschwarzeIn order to find out when the connection has been successfully established,
128*f1a3c524Sschwarzeon many platforms
129*f1a3c524Sschwarze.Xr select 2
130*f1a3c524Sschwarzeor
131*f1a3c524Sschwarze.Xr poll 2
132*f1a3c524Sschwarzefor writing on the socket file descriptor can be used.
133*f1a3c524Sschwarze.It Dv SSL_ERROR_WANT_X509_LOOKUP
134*f1a3c524SschwarzeThe operation did not complete because an application callback set by
135*f1a3c524Sschwarze.Xr SSL_CTX_set_client_cert_cb 3
136*f1a3c524Sschwarzehas asked to be called again.
137*f1a3c524SschwarzeThe TLS/SSL I/O function should be called again later.
138*f1a3c524SschwarzeDetails depend on the application.
139*f1a3c524Sschwarze.It Dv SSL_ERROR_SYSCALL
140*f1a3c524SschwarzeSome I/O error occurred.
141*f1a3c524SschwarzeThe OpenSSL error queue may contain more information on the error.
142*f1a3c524SschwarzeIf the error queue is empty (i.e.,
143*f1a3c524Sschwarze.Fn ERR_get_error
144*f1a3c524Sschwarzereturns 0),
145*f1a3c524Sschwarze.Fa ret
146*f1a3c524Sschwarzecan be used to find out more about the error:
147*f1a3c524SschwarzeIf
148*f1a3c524Sschwarze.Fa ret
149*f1a3c524Sschwarze== 0, an
150*f1a3c524Sschwarze.Dv EOF
151*f1a3c524Sschwarzewas observed that violates the protocol.
152*f1a3c524SschwarzeIf
153*f1a3c524Sschwarze.Fa ret
154*f1a3c524Sschwarze== \(mi1, the underlying
155*f1a3c524Sschwarze.Vt BIO
156*f1a3c524Sschwarzereported an
157*f1a3c524SschwarzeI/O error (for socket I/O on Unix systems, consult
158*f1a3c524Sschwarze.Dv errno
159*f1a3c524Sschwarzefor details).
160*f1a3c524Sschwarze.It Dv SSL_ERROR_SSL
161*f1a3c524SschwarzeA failure in the SSL library occurred, usually a protocol error.
162*f1a3c524SschwarzeThe OpenSSL error queue contains more information on the error.
163*f1a3c524Sschwarze.El
164*f1a3c524Sschwarze.Sh SEE ALSO
165*f1a3c524Sschwarze.Xr err 3 ,
166*f1a3c524Sschwarze.Xr ssl 3
167*f1a3c524Sschwarze.Sh HISTORY
168*f1a3c524Sschwarze.Fn SSL_get_error
169*f1a3c524Sschwarzewas added in SSLeay 0.8.
170