SSL async callbacks documentation: clarify resource cleanup
Clarify when resume must clean up resources and when cancel is called.
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index ec9018a..a839e84 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -576,7 +576,7 @@
*
* This function may call mbedtls_ssl_set_async_operation_data()
* to store an operation context for later retrieval
- * by the resume callback.
+ * by the resume or cancel callback.
*
* \note For RSA signatures, this function must produce output
* that is consistent with PKCS#1 v1.5 in the same way as
@@ -653,7 +653,7 @@
*
* This function may call mbedtls_ssl_set_async_operation_data()
* to store an operation context for later retrieval
- * by the resume callback.
+ * by the resume or cancel callback.
*
* \warning RSA decryption as used in TLS is subject to a potential
* timing side channel attack first discovered by Bleichenbacher
@@ -716,6 +716,10 @@
* It may call mbedtls_ssl_set_async_operation_data() to modify
* this context.
*
+ * Note that when this function returns a status other than
+ * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, it must free any
+ * resources associated with the operation.
+ *
* \param ssl The SSL connection instance. It should not be
* modified other than via
* mbedtls_ssl_set_async_operation_data().
@@ -745,7 +749,12 @@
* \brief Callback type: cancel external operation.
*
* This callback is called if an SSL connection is closed
- * while an asynchronous operation is in progress.
+ * while an asynchronous operation is in progress. Note that
+ * this callback is not called if the
+ * ::mbedtls_ssl_async_resume_t callback has run and has
+ * returned a value other than
+ * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, since in that case
+ * the asynchronous operation has already completed.
*
* This function may call mbedtls_ssl_get_async_operation_data()
* to retrieve an operation context set by the start callback.