Make documentation more explicit on TLS errors
fixes #358
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 810409c..8fd0ee9 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -2167,7 +2167,8 @@
* \note If this function returns something other than 0 or
* MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
* becomes unusable, and you should either free it or call
- * \c mbedtls_ssl_session_reset() on it before re-using it.
+ * \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
@@ -2183,6 +2184,12 @@
* the following state after execution of this function.
* Do not call this function if state is MBEDTLS_SSL_HANDSHAKE_OVER.
*
+ * \note If this function returns something other than 0 or
+ * MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
+ * becomes unusable, and you should 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.
+ *
* \param ssl SSL context
*
* \return 0 if successful, or
@@ -2201,6 +2208,12 @@
* \param ssl SSL context
*
* \return 0 if successful, or any mbedtls_ssl_handshake() return value.
+ *
+ * \note If this function returns something other than 0 or
+ * MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
+ * becomes unusable, and you should 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.
*/
int mbedtls_ssl_renegotiate( mbedtls_ssl_context *ssl );
#endif /* MBEDTLS_SSL_RENEGOTIATION */
@@ -2218,6 +2231,13 @@
* MBEDTLS_ERR_SSL_CLIENT_RECONNECT (see below), or
* another negative error code.
*
+ * \note If this function returns something other than a positive
+ * value or MBEDTLS_ERR_SSL_WANT_READ/WRITE or
+ * MBEDTLS_ERR_SSL_CLIENT_RECONNECT, then the ssl context
+ * becomes unusable, and you should 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 return 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.
@@ -2251,6 +2271,12 @@
* or MBEDTLS_ERR_SSL_WANT_WRITE of MBEDTLS_ERR_SSL_WANT_READ,
* or another negative error code.
*
+ * \note If this function returns something other than a positive
+ * value or MBEDTLS_ERR_SSL_WANT_READ/WRITE, the ssl context
+ * becomes unusable, and you should 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_WANT_WRITE/READ,
* it must be called later with the *same* arguments,
* until it returns a positive value.
@@ -2274,6 +2300,12 @@
* \param message The alert message (SSL_ALERT_MSG_*)
*
* \return 0 if successful, or a specific SSL error code.
+ *
+ * \note If this function returns something other than 0 or
+ * MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
+ * becomes unusable, and you should 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.
*/
int mbedtls_ssl_send_alert_message( mbedtls_ssl_context *ssl,
unsigned char level,
@@ -2282,6 +2314,14 @@
* \brief Notify the peer that the connection is being closed
*
* \param ssl SSL context
+ *
+ * \return 0 if successful, or a specific SSL error code.
+ *
+ * \note If this function returns something other than 0 or
+ * MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
+ * becomes unusable, and you should 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.
*/
int mbedtls_ssl_close_notify( mbedtls_ssl_context *ssl );