mbedtls_ssl_read() function

Read at most 'len' application data bytes \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 or #MBEDTLS_ERR_SSL_CLIENT_RECONNECT, 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.

Syntax

from ssl.h:3098

int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len );

Implemented in ssl_tls.c:8263

Arguments

ssl

SSL context

buf

buffer that will hold the data

len

maximum number of bytes to read

Return value

The (positive) number of bytes read if successful. \c 0 if the read end of the underlying transport was closed - in this case you must stop using the context (see below). #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. #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. #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. #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. Another SSL error code - in this case you must stop using the context (see below).

Notes

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! 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.

Examples

mbedtls_ssl_read() is referenced by 6 libraries and example projects.

References

Location	Text
ssl_tls.c:8263	int mbedtls_ssl_read( mbedtls_ssl_context ssl, unsigned char buf, size_t len )
ssl.h:3098	int mbedtls_ssl_read( mbedtls_ssl_context ssl, unsigned char buf, size_t len );