From 0446a39744fb4f6eeb1936a464ea3890fc4e7bcc Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Fri, 7 Apr 2017 12:59:32 +0100 Subject: [PATCH] Enhance documentation of mbedtls_ssl_set_hostname (1) Add missing error condition (2) Specify allowance and effect of of NULL hostname parameter (3) Describe effect of function on failure --- include/mbedtls/ssl.h | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index cc0007006..87ea00dbb 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -1794,15 +1794,23 @@ void mbedtls_ssl_conf_sig_hashes( mbedtls_ssl_config *conf, #if defined(MBEDTLS_X509_CRT_PARSE_C) /** - * \brief Set the hostname to check against the received server - * certificate. It sets the ServerName TLS extension too, - * if the extension is enabled. - * (client-side only) + * \brief Set or reset the hostname to check against the received + * server certificate. It sets the ServerName TLS extension, + * too, if that extension is enabled. (client-side only) * * \param ssl SSL context - * \param hostname the server hostname + * \param hostname the server hostname, may be NULL to clear hostname + + * \note Maximum hostname length MBEDTLS_SSL_MAX_HOST_NAME_LEN. + * + * \return 0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED on + * allocation failure, MBEDTLS_ERR_BAD_INPUT_DATA on + * too long input hostname. + * + * \post Hostname set to the one provided on success (cleared + * when NULL). On allocation failure hostname is cleared. + * On too long input failure, old hostname is unchanged. * - * \return 0 if successful or MBEDTLS_ERR_SSL_ALLOC_FAILED */ int mbedtls_ssl_set_hostname( mbedtls_ssl_context *ssl, const char *hostname ); #endif /* MBEDTLS_X509_CRT_PARSE_C */