Document the need to call mbedtls_ssl_set_hostname
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 0fe2399..3154024 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -3948,6 +3948,16 @@
*
* \note Maximum hostname length #MBEDTLS_SSL_MAX_HOST_NAME_LEN.
*
+ * \note If the hostname is \c NULL on a client, then the server
+ * is not authenticated: it only needs to have a valid
+ * certificate, not a certificate matching its name.
+ * Therefore you should always call this function on a client,
+ * unless the connection is set up to only allow
+ * pre-shared keys, or in scenarios where server
+ * impersonation is not a concern. See the documentation of
+ * #MBEDTLS_ERR_SSL_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME
+ * for more details.
+ *
* \return 0 if successful, #MBEDTLS_ERR_SSL_ALLOC_FAILED on
* allocation failure, #MBEDTLS_ERR_SSL_BAD_INPUT_DATA on
* too long input hostname.