From 4f563e7d90d01d86277831994fe2abdca5899b19 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 20 Feb 2025 17:39:52 +0100 Subject: [PATCH] Expand and rectify the documentation of mbedtls_ssl_context::hostname Signed-off-by: Gilles Peskine --- include/mbedtls/ssl.h | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index fbd1c3a8cf..e294060efa 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -1925,13 +1925,28 @@ struct mbedtls_ssl_context { * 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 */