lib/libssl/man/SSL_get_error.3

   1 .\"     $OpenBSD: SSL_get_error.3,v 1.2 2016/12/03 08:54:21 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: December 3 2016 $
  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 .In openssl/ssl.h
  59 .Ft int
  60 .Fn SSL_get_error "const SSL *ssl" "int ret"
  61 .Sh DESCRIPTION
  62 .Fn SSL_get_error
  63 returns a result code (suitable for the C
  64 .Dq switch
  65 statement) for a preceding call to
  66 .Xr SSL_connect 3 ,
  67 .Xr SSL_accept 3 ,
  68 .Xr SSL_do_handshake 3 ,
  69 .Xr SSL_read 3 ,
  70 .Xr SSL_peek 3 ,
  71 or
  72 .Xr SSL_write 3
  73 on
  74 .Fa ssl .
  75 The value returned by that TLS/SSL I/O function must be passed to
  76 .Fn SSL_get_error
  77 in parameter
  78 .Fa ret .
  79 .Pp
  80 In addition to
  81 .Fa ssl
  82 and
  83 .Fa ret ,
  84 .Fn SSL_get_error
  85 inspects the current thread's OpenSSL error queue.
  86 Thus,
  87 .Fn SSL_get_error
  88 must be used in the same thread that performed the TLS/SSL I/O operation,
  89 and no other OpenSSL function calls should appear in between.
  90 The current thread's error queue must be empty before the TLS/SSL I/O operation
  91 is attempted, or
  92 .Fn SSL_get_error
  93 will not work reliably.
  94 .Sh RETURN VALUES
  95 The following return values can currently occur:
  96 .Bl -tag -width Ds
  97 .It Dv SSL_ERROR_NONE
  98 The TLS/SSL I/O operation completed.
  99 This result code is returned if and only if
 100 .Fa ret
 101 < 0.
 102 .It Dv SSL_ERROR_ZERO_RETURN
 103 The TLS/SSL connection has been closed.
 104 If the protocol version is SSL 3.0 or TLS 1.0, this result code is returned
 105 only if a closure alert has occurred in the protocol, i.e., if the connection
 106 has been closed cleanly.
 107 Note that in this case
 108 .Dv SSL_ERROR_ZERO_RETURN
 109 does not necessarily indicate that the underlying transport has been closed.
 110 .It Dv SSL_ERROR_WANT_READ , Dv SSL_ERROR_WANT_WRITE
 111 The operation did not complete;
 112 the same TLS/SSL I/O function should be called again later.
 113 If, by then, the underlying
 114 .Vt BIO
 115 has data available for reading (if the result code is
 116 .Dv SSL_ERROR_WANT_READ )
 117 or allows writing data
 118 .Pq Dv SSL_ERROR_WANT_WRITE ,
 119 then some TLS/SSL protocol progress will take place,
 120 i.e., at least part of a TLS/SSL record will be read or written.
 121 Note that the retry may again lead to a
 122 .Dv SSL_ERROR_WANT_READ
 123 or
 124 .Dv SSL_ERROR_WANT_WRITE
 125 condition.
 126 There is no fixed upper limit for the number of iterations that may be
 127 necessary until progress becomes visible at application protocol level.
 128 .Pp
 129 For socket
 130 .Fa BIO Ns
 131 s (e.g., when
 132 .Fn SSL_set_fd
 133 was used),
 134 .Xr select 2
 135 or
 136 .Xr poll 2
 137 on the underlying socket can be used to find out when the TLS/SSL I/O function
 138 should be retried.
 139 .Pp
 140 Caveat: Any TLS/SSL I/O function can lead to either of
 141 .Dv SSL_ERROR_WANT_READ
 142 and
 143 .Dv SSL_ERROR_WANT_WRITE .
 144 In particular,
 145 .Xr SSL_read 3
 146 or
 147 .Xr SSL_peek 3
 148 may want to write data and
 149 .Xr SSL_write 3
 150 may want
 151 to read data.
 152 This is mainly because TLS/SSL handshakes may occur at any time during the
 153 protocol (initiated by either the client or the server);
 154 .Xr SSL_read 3 ,
 155 .Xr SSL_peek 3 ,
 156 and
 157 .Xr SSL_write 3
 158 will handle any pending handshakes.
 159 .It Dv SSL_ERROR_WANT_CONNECT , Dv SSL_ERROR_WANT_ACCEPT
 160 The operation did not complete; the same TLS/SSL I/O function should be
 161 called again later.
 162 The underlying BIO was not connected yet to the peer and the call would block
 163 in
 164 .Xr connect 2 Ns / Ns
 165 .Xr accept 2 .
 166 The SSL function should be
 167 called again when the connection is established.
 168 These messages can only appear with a
 169 .Xr BIO_s_connect 3
 170 or
 171 .Xr BIO_s_accept 3
 172 .Vt BIO ,
 173 respectively.
 174 In order to find out when the connection has been successfully established,
 175 on many platforms
 176 .Xr select 2
 177 or
 178 .Xr poll 2
 179 for writing on the socket file descriptor can be used.
 180 .It Dv SSL_ERROR_WANT_X509_LOOKUP
 181 The operation did not complete because an application callback set by
 182 .Xr SSL_CTX_set_client_cert_cb 3
 183 has asked to be called again.
 184 The TLS/SSL I/O function should be called again later.
 185 Details depend on the application.
 186 .It Dv SSL_ERROR_SYSCALL
 187 Some I/O error occurred.
 188 The OpenSSL error queue may contain more information on the error.
 189 If the error queue is empty (i.e.,
 190 .Fn ERR_get_error
 191 returns 0),
 192 .Fa ret
 193 can be used to find out more about the error:
 194 If
 195 .Fa ret
 196 == 0, an
 197 .Dv EOF
 198 was observed that violates the protocol.
 199 If
 200 .Fa ret
 201 == \(mi1, the underlying
 202 .Vt BIO
 203 reported an
 204 I/O error (for socket I/O on Unix systems, consult
 205 .Dv errno
 206 for details).
 207 .It Dv SSL_ERROR_SSL
 208 A failure in the SSL library occurred, usually a protocol error.
 209 The OpenSSL error queue contains more information on the error.
 210 .El
 211 .Sh SEE ALSO
 212 .Xr err 3 ,
 213 .Xr ssl 3
 214 .Sh HISTORY
 215 .Fn SSL_get_error
 216 was added in SSLeay 0.8.