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
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index cc00070..87ea00d 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -1794,15 +1794,23 @@
#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 or MBEDTLS_ERR_SSL_ALLOC_FAILED
+ * \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.
+ *
*/
int mbedtls_ssl_set_hostname( mbedtls_ssl_context *ssl, const char *hostname );
#endif /* MBEDTLS_X509_CRT_PARSE_C */