Function esp_idf_svc::hal::sys::mbedtls_ssl_handshake

pub unsafe extern "C" fn mbedtls_ssl_handshake(
    ssl: *mut mbedtls_ssl_context,
) -> i32

\brief Perform the SSL handshake

\param ssl SSL context

\return \c 0 if successful. \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_HELLO_VERIFY_REQUIRED if DTLS is in use and the client did not demonstrate reachability yet - in this case you must stop using the context (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 \c 0, #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE, #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS 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 If DTLS is in use, then you may choose to handle #MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED specially for logging purposes, as it is an expected return value rather than an actual error, but you still need to reset/free the context.

\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 is not true for a successful handshake, in which case the datagram of the underlying transport that is currently being processed might or might not contain further DTLS records.

\note If the context is configured to allow TLS 1.3, or if #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto subsystem must have been initialized by calling psa_crypto_init() before calling this function.