jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: SSL_get_error.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $
2.\" OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400
3.\"
4.\" This file was written by Bodo Moeller <bodo@openssl.org>.
5.\" Copyright (c) 2000, 2001, 2002, 2005 The OpenSSL Project. All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\"
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\"
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in
16.\" the documentation and/or other materials provided with the
17.\" distribution.
18.\"
19.\" 3. All advertising materials mentioning features or use of this
20.\" software must display the following acknowledgment:
21.\" "This product includes software developed by the OpenSSL Project
22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23.\"
24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25.\" endorse or promote products derived from this software without
26.\" prior written permission. For written permission, please contact
27.\" openssl-core@openssl.org.
28.\"
29.\" 5. Products derived from this software may not be called "OpenSSL"
30.\" nor may "OpenSSL" appear in their names without prior written
31.\" permission of the OpenSSL Project.
32.\"
33.\" 6. Redistributions of any form whatsoever must retain the following
34.\" acknowledgment:
35.\" "This product includes software developed by the OpenSSL Project
36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37.\"
38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49.\" OF THE POSSIBILITY OF SUCH DAMAGE.
50.\"
51.Dd $Mdocdate: June 8 2025 $
52.Dt SSL_GET_ERROR 3
53.Os
54.Sh NAME
55.Nm SSL_get_error
56.Nd obtain result code for TLS/SSL I/O operation
57.Sh SYNOPSIS
58.Lb libssl libcrypto
59.In openssl/ssl.h
60.Ft int
61.Fn SSL_get_error "const SSL *ssl" "int ret"
62.Sh DESCRIPTION
63.Fn SSL_get_error
64returns a result code (suitable for the C
65.Dq switch
66statement) for a preceding call to
67.Xr SSL_connect 3 ,
68.Xr SSL_accept 3 ,
69.Xr SSL_do_handshake 3 ,
70.Xr SSL_read 3 ,
71.Xr SSL_peek 3 ,
72or
73.Xr SSL_write 3
74on
75.Fa ssl .
76The value returned by that TLS/SSL I/O function must be passed to
77.Fn SSL_get_error
78in parameter
79.Fa ret .
80.Pp
81In addition to
82.Fa ssl
83and
84.Fa ret ,
85.Fn SSL_get_error
86inspects the current thread's OpenSSL error queue.
87Thus,
88.Fn SSL_get_error
89must be used in the same thread that performed the TLS/SSL I/O operation,
90and no other OpenSSL function calls should appear in between.
91The current thread's error queue must be empty before the TLS/SSL I/O operation
92is attempted, or
93.Fn SSL_get_error
94will not work reliably.
95.Sh RETURN VALUES
96The following return values can currently occur:
97.Bl -tag -width Ds
98.It Dv SSL_ERROR_NONE
99The TLS/SSL I/O operation completed.
100This result code is returned if and only if
101.Fa ret
102> 0.
103.It Dv SSL_ERROR_ZERO_RETURN
104The TLS/SSL connection has been closed.
105If the protocol version is SSL 3.0 or TLS 1.0, this result code is returned
106only if a closure alert has occurred in the protocol, i.e., if the connection
107has been closed cleanly.
108Note that in this case
109.Dv SSL_ERROR_ZERO_RETURN
110does not necessarily indicate that the underlying transport has been closed.
111.It Dv SSL_ERROR_WANT_READ , Dv SSL_ERROR_WANT_WRITE
112The operation did not complete;
113the same TLS/SSL I/O function should be called again later.
114If, by then, the underlying
115.Vt BIO
116has data available for reading (if the result code is
117.Dv SSL_ERROR_WANT_READ )
118or allows writing data
119.Pq Dv SSL_ERROR_WANT_WRITE ,
120then some TLS/SSL protocol progress will take place,
121i.e., at least part of a TLS/SSL record will be read or written.
122Note that the retry may again lead to a
123.Dv SSL_ERROR_WANT_READ
124or
125.Dv SSL_ERROR_WANT_WRITE
126condition.
127There is no fixed upper limit for the number of iterations that may be
128necessary until progress becomes visible at application protocol level.
129.Pp
130For socket
131.Fa BIO Ns
132s (e.g., when
133.Fn SSL_set_fd
134was used),
135.Xr select 2
136or
137.Xr poll 2
138on the underlying socket can be used to find out when the TLS/SSL I/O function
139should be retried.
140.Pp
141Caveat: Any TLS/SSL I/O function can lead to either of
142.Dv SSL_ERROR_WANT_READ
143and
144.Dv SSL_ERROR_WANT_WRITE .
145In particular,
146.Xr SSL_read 3
147or
148.Xr SSL_peek 3
149may want to write data and
150.Xr SSL_write 3
151may want
152to read data.
153This is mainly because TLS/SSL handshakes may occur at any time during the
154protocol (initiated by either the client or the server);
155.Xr SSL_read 3 ,
156.Xr SSL_peek 3 ,
157and
158.Xr SSL_write 3
159will handle any pending handshakes.
160.It Dv SSL_ERROR_WANT_CONNECT , Dv SSL_ERROR_WANT_ACCEPT
161The operation did not complete; the same TLS/SSL I/O function should be
162called again later.
163The underlying BIO was not connected yet to the peer and the call would block
164in
165.Xr connect 2 Ns / Ns
166.Xr accept 2 .
167The SSL function should be
168called again when the connection is established.
169These messages can only appear with a
170.Xr BIO_s_connect 3
171or
172.Xr BIO_s_accept 3
173.Vt BIO ,
174respectively.
175In order to find out when the connection has been successfully established,
176on many platforms
177.Xr select 2
178or
179.Xr poll 2
180for writing on the socket file descriptor can be used.
181.It Dv SSL_ERROR_WANT_X509_LOOKUP
182The operation did not complete because an application callback set by
183.Xr SSL_CTX_set_client_cert_cb 3
184has asked to be called again.
185The TLS/SSL I/O function should be called again later.
186Details depend on the application.
187.It Dv SSL_ERROR_SYSCALL
188Some I/O error occurred.
189The OpenSSL error queue may contain more information on the error.
190If the error queue is empty (i.e.,
191.Fn ERR_get_error
192returns 0),
193.Fa ret
194can be used to find out more about the error:
195If
196.Fa ret
197== 0, an
198.Dv EOF
199was observed that violates the protocol.
200If
201.Fa ret
202== \(mi1, the underlying
203.Vt BIO
204reported an
205I/O error (for socket I/O on Unix systems, consult
206.Dv errno
207for details).
208.It Dv SSL_ERROR_SSL
209A failure in the SSL library occurred, usually a protocol error.
210The OpenSSL error queue contains more information on the error.
211.El
212.Sh SEE ALSO
213.Xr err 3 ,
214.Xr ssl 3
215.Sh HISTORY
216.Fn SSL_get_error
217first appeared in SSLeay 0.8.0 and have been available since
218.Ox 2.4 .