Function esp_idf_svc::sys::mbedtls_ssl_read

pub unsafe extern "C" fn mbedtls_ssl_read(
    ssl: *mut mbedtls_ssl_context,
    buf: *mut u8,
    len: usize,
) -> i32

\brief Read at most ‘len’ application data bytes

\param ssl SSL context \param buf buffer that will hold the data \param len maximum number of bytes to read

\return The (positive) number of bytes read if successful. \return \c 0 if the read end of the underlying transport was closed without sending a CloseNotify beforehand, which might happen because of various reasons (internal error of an underlying stack, non-conformant peer not sending a CloseNotify and such) - in this case you must stop using the context (see below). \return #MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY if the underlying transport is still functional, but the peer has acknowledged to not send anything anymore. \return #MBEDTLS_ERR_SSL_WANT_READ or #MBEDTLS_ERR_SSL_WANT_WRITE if the handshake is incomplete and waiting for data to be available for reading from or writing to the underlying transport - in this case you must call this function again when the underlying transport is ready for the operation. \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous operation is in progress (see mbedtls_ssl_conf_async_private_cb()) - in this case you must call this function again when the operation is ready. \return #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic operation is in progress (see mbedtls_ecp_set_max_ops()) - in this case you must call this function again to complete the handshake when you’re done attending other tasks. \return #MBEDTLS_ERR_SSL_CLIENT_RECONNECT if we’re at the server side of a DTLS connection and the client is initiating a new connection using the same source port. See below. \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as defined in RFC 8446 (TLS 1.3 specification), has been received as part of the handshake. This is server specific and may occur only if the early data feature has been enabled on server (see mbedtls_ssl_conf_early_data() documentation). You must call mbedtls_ssl_read_early_data() to read the early data before resuming the handshake. \return Another SSL error code - in this case you must stop using the context (see below).

\warning If this function returns something other than a positive value, #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE, #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, #MBEDTLS_ERR_SSL_CLIENT_RECONNECT or #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA, you must stop using the SSL context for reading or writing, and either free it or call \c mbedtls_ssl_session_reset() on it before re-using it for a new connection; the current connection must be closed.

\note When this function returns #MBEDTLS_ERR_SSL_CLIENT_RECONNECT (which can only happen server-side), it means that a client is initiating a new connection using the same source port. You can either treat that as a connection close and wait for the client to resend a ClientHello, or directly continue with \c mbedtls_ssl_handshake() with the same context (as it has been reset internally). Either way, you must make sure this is seen by the application as a new connection: application state, if any, should be reset, and most importantly the identity of the client must be checked again. WARNING: not validating the identity of the client again, or not transmitting the new identity to the application layer, would allow authentication bypass!

\note Remarks regarding event-driven DTLS: - If the function returns #MBEDTLS_ERR_SSL_WANT_READ, no datagram from the underlying transport layer is currently being processed, and it is safe to idle until the timer or the underlying transport signal a new event. - This function may return MBEDTLS_ERR_SSL_WANT_READ even if data was initially available on the underlying transport, as this data may have been only e.g. duplicated messages or a renegotiation request. Therefore, you must be prepared to receive MBEDTLS_ERR_SSL_WANT_READ even when reacting to an incoming-data event from the underlying transport. - On success, the datagram of the underlying transport that is currently being processed may contain further DTLS records. You should call \c mbedtls_ssl_check_pending to check for remaining records.