Expand and rectify the documentation of mbedtls_ssl_context::hostname
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index e837f4c..541fcc8 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -1442,12 +1442,27 @@
*
* Also used on clients for SNI.
*
- * If this is \p NULL, the peer name verification is skipped, and
- * the server_name extension is not sent.
+ * The value of this field can be:
+ * - \p NULL in a newly initialized or reset context.
+ * - A heap-allocated copy of the last value passed to
+ * mbedtls_ssl_set_hostname(), if the last call had a non-null
+ * \p hostname argument.
+ * - A special value to indicate that mbedtls_ssl_set_hostname()
+ * was called with \p NULL (as opposed to never having been called).
+ * See `mbedtls_ssl_get_hostname_pointer()` in `ssl_tls.c`.
*
- * This can be a special value to indicate that mbedtls_ssl_set_hostname()
- * has been called with \p NULL, as opposed to never having been called.
- * See mbedtls_ssl_get_hostname_pointer().
+ * If this field contains the value \p NULL and the configuration option
+ * #MBEDTLS_SSL_CLI_ALLOW_WEAK_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME
+ * is unset, on a TLS client, attempting to verify a server certificate
+ * results in the error
+ * #MBEDTLS_ERR_SSL_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME.
+ *
+ * If this field contains the special value described above, or if
+ * the value is \p NULL and the configuration option
+ * #MBEDTLS_SSL_CLI_ALLOW_WEAK_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME
+ * is set, then the peer name verification is skipped, which may be
+ * insecure, especially on a client. Furthermore, on a client, the
+ * server_name extension is not sent.
*/
char *hostname;
#endif /* MBEDTLS_X509_CRT_PARSE_C */