Update documentation
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 8ff4539..c04070d 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -1170,6 +1170,11 @@
* the MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED that is expected
* on the first handshake attempt when this is enabled.
*
+ * \note This is also necessary to handle client reconnection from
+ * the same port as described in RFC 6347 section 4.2.8 (only
+ * the variant with cookies is supported currently). See
+ * comments on \c mbedtls_ssl_read() for details.
+ *
* \param conf SSL configuration
* \param f_cookie_write Cookie write callback
* \param f_cookie_check Cookie check callback
@@ -2139,7 +2144,23 @@
*
* \return the number of bytes read, or
* 0 for EOF, or
- * a negative error code.
+ * MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or
+ * MBEDTLS_ERR_SSL_CLIENT_RECONNECT (see below), or
+ * another negative error code.
+ *
+ * \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.
+ * 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 beeen reset internally). Either way, you
+ * should 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!
*/
int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len );