SSL_read 3 2002-06-09 0.9.9-dev OpenSSL

NAME

SSL_read - read bytes from a TLS/SSL connection.

LIBRARY

libcrypto, -lcrypto

SYNOPSIS


 #include 


 int SSL_read(SSL *ssl, void *buf, int num);

DESCRIPTION

_S_S_L___r_e_a_d_(_) tries to read nnuumm bytes from the specified ssssll into the buffer bbuuff.

NOTES

If necessary, _S_S_L___r_e_a_d_(_) will negotiate a TLS/SSL session, if not already explicitly performed by _S_S_L___c_o_n_n_e_c_t(3) or _S_S_L___a_c_c_e_p_t(3). If the peer requests a re-negotiation, it will be performed transparently during the _S_S_L___r_e_a_d_(_) operation. The behaviour of _S_S_L___r_e_a_d_(_) depends on the underlying BIO.

For the transparent negotiation to succeed, the ssssll must have been initialized to client or server mode. This is being done by calling _S_S_L___s_e_t___c_o_n_n_e_c_t___s_t_a_t_e(3) or _S_S_L___s_e_t___a_c_c_e_p_t___s_t_a_t_e_(_) before the first call to an _S_S_L___r_e_a_d_(_) or _S_S_L___w_r_i_t_e(3) function.

_S_S_L___r_e_a_d_(_) works based on the SSL/TLS records. The data are received in records (with a maximum record size of 16kB for SSLv3/TLSv1). Only when a record has been completely received, it can be processed (decryption and check of integrity). Therefore data that was not retrieved at the last call of _S_S_L___r_e_a_d_(_) can still be buffered inside the SSL layer and will be retrieved on the next call to _S_S_L___r_e_a_d_(_). If nnuumm is higher than the number of bytes buffered, _S_S_L___r_e_a_d_(_) will return with the bytes buffered. If no more bytes are in the buffer, _S_S_L___r_e_a_d_(_) will trigger the processing of the next record. Only when the record has been received and processed completely, _S_S_L___r_e_a_d_(_) will return reporting success. At most the contents of the record will be returned. As the size of an SSL/TLS record may exceed the maximum packet size of the underlying transport (e.g. TCP), it may be necessary to read several packets from the transport layer before the record is complete and _S_S_L___r_e_a_d_(_) can succeed.

If the underlying BIO is bblloocckkiinngg, _S_S_L___r_e_a_d_(_) will only return, once the read operation has been finished or an error occurred, except when a renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur. This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the _S_S_L___C_T_X___s_e_t___m_o_d_e(3) call.

If the underlying BIO is nnoonn--bblloocckkiinngg, _S_S_L___r_e_a_d_(_) will also return when the underlying BIO could not satisfy the needs of _S_S_L___r_e_a_d_(_) to continue the operation. In this case a call to _S_S_L___g_e_t___e_r_r_o_r(3) with the return value of _S_S_L___r_e_a_d_(_) will yield SSSSLL__EERRRROORR__WWAANNTT__RREEAADD or SSSSLL__EERRRROORR__WWAANNTT__WWRRIITTEE. As at any time a re-negotiation is possible, a call to _S_S_L___r_e_a_d_(_) can also cause write operations! The calling process then must repeat the call after taking appropriate action to satisfy the needs of _S_S_L___r_e_a_d_(_). The action depends on the underlying BIO. When using a non-blocking socket, nothing is to be done, but _s_e_l_e_c_t_(_) can be used to check for the required condition. When using a buffering BIO, like a BIO pair, data must be written into or retrieved out of the BIO before being able to continue.

WARNING

When an _S_S_L___r_e_a_d_(_) operation has to be repeated because of SSSSLL__EERRRROORR__WWAANNTT__RREEAADD or SSSSLL__EERRRROORR__WWAANNTT__WWRRIITTEE, it must be repeated with the same arguments.

RETURN VALUES

The following return values can occur:
>0 The read operation was successful; the return value is the number of
bytes actually read from the TLS/SSL connection.
0 The read operation was not successful. The reason may either be a clean
shutdown due to a "close notify" alert sent by the peer (in which case the SSL_RECEIVED_SHUTDOWN flag in the ssl shutdown state is set (see _S_S_L___s_h_u_t_d_o_w_n(3), _S_S_L___s_e_t___s_h_u_t_d_o_w_n(3)). It is also possible, that the peer simply shut down the underlying transport and the shutdown is incomplete. Call _S_S_L___g_e_t___e_r_r_o_r_(_) with the return value rreett to find out, whether an error occurred or the connection was shut down cleanly (SSL_ERROR_ZERO_RETURN).

SSLv2 (deprecated) does not support a shutdown alert protocol, so it can only be detected, whether the underlying connection was closed. It cannot be checked, whether the closure was initiated by the peer or by something else.
<0 The read operation was not successful, because either an error occurred
or action must be taken by the calling process. Call _S_S_L___g_e_t___e_r_r_o_r_(_) with the return value rreett to find out the reason.

SEE ALSO

_S_S_L___g_e_t___e_r_r_o_r(3), _S_S_L___w_r_i_t_e(3), _S_S_L___C_T_X___s_e_t___m_o_d_e(3), _S_S_L___C_T_X___n_e_w(3), _S_S_L___c_o_n_n_e_c_t(3), _S_S_L___a_c_c_e_p_t(3) _S_S_L___s_e_t___c_o_n_n_e_c_t___s_t_a_t_e(3), _S_S_L___s_h_u_t_d_o_w_n(3), _S_S_L___s_e_t___s_h_u_t_d_o_w_n(3), _s_s_l(3), _o_p_e_n_s_s_l___b_i_o(3)