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