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 fbd1c3a..e294060 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -1925,13 +1925,28 @@
* Also used on clients for SNI,
* and for TLS 1.3 session resumption using tickets.
*
- * If this is \p NULL, the peer name verification is skipped,
- * the server_name extension is not sent, and the server name is ignored
- * in TLS 1.3 session resumption using tickets.
+ * 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()` in `ssl_tls.c`.
+ * 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, and the server name is ignored
+ * in TLS 1.3 session resumption using tickets.
*/
char *MBEDTLS_PRIVATE(hostname);
#endif /* MBEDTLS_X509_CRT_PARSE_C */