From b48ef9cce9fabbd14dc2cc35e7b1110ff6f94bb0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Thu, 28 May 2015 15:24:25 +0200 Subject: [PATCH] Improve documentation about HelloVerifyRequest --- include/mbedtls/ssl.h | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index e77b4120f..bb68d76c3 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -1141,7 +1141,7 @@ typedef int mbedtls_ssl_cookie_check_t( void *ctx, * \brief Register callbacks for DTLS cookies * (Server only. DTLS only.) * - * Default: dummy callbacks that fail, to force you to + * Default: dummy callbacks that fail, in order to force you to * register working callbacks (and initialize their context). * * To disable HelloVerifyRequest, register NULL callbacks. @@ -1151,6 +1151,10 @@ typedef int mbedtls_ssl_cookie_check_t( void *ctx, * Only disable if you known this can't happen in your * particular environment. * + * \note See comments on \c mbedtls_ssl_handshake() about handling + * the MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED that is expected + * on the first handshake attempt when this is enabled. + * * \param conf SSL configuration * \param f_cookie_write Cookie write callback * \param f_cookie_check Cookie check callback @@ -1980,6 +1984,13 @@ int mbedtls_ssl_get_session( const mbedtls_ssl_context *ssl, mbedtls_ssl_session * * \return 0 if successful, MBEDTLS_ERR_SSL_WANT_READ, * MBEDTLS_ERR_SSL_WANT_WRITE, or a specific SSL error code. + * + * \note If this function returns non-zero, 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. + * If DTLS is in use, then you may choose to handle + * MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED specially for logging + * purposes, but you still need to reset/free the context. */ int mbedtls_ssl_handshake( mbedtls_ssl_context *ssl );