From 63f958df772f763dfd5b6d0506f9cac9ed34c34e Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 13 Feb 2025 13:46:03 +0100 Subject: [PATCH] Create error code for mbedtls_ssl_set_hostname not called Signed-off-by: Gilles Peskine --- include/mbedtls/error.h | 2 +- include/mbedtls/ssl.h | 32 ++++++++++++++++++++++++++++++++ library/error.c | 2 ++ 3 files changed, 35 insertions(+), 1 deletion(-) diff --git a/include/mbedtls/error.h b/include/mbedtls/error.h index 7a183733ee..fd0ac76321 100644 --- a/include/mbedtls/error.h +++ b/include/mbedtls/error.h @@ -92,7 +92,7 @@ * ECP 4 10 (Started from top) * MD 5 5 * HKDF 5 1 (Started from top) - * SSL 5 2 (Started from 0x5F00) + * SSL 5 3 (Started from 0x5F00) * CIPHER 6 8 (Started from 0x6080) * SSL 6 24 (Started from top, plus 0x6000) * SSL 7 32 diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index 447a293535..4b3a67c48d 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -183,6 +183,38 @@ #define MBEDTLS_ERR_SSL_BAD_CONFIG -0x5E80 /** Cache entry not found */ #define MBEDTLS_ERR_SSL_CACHE_ENTRY_NOT_FOUND -0x5E00 +/** Attempt to verify a certificate without an expected hostname. + * This is usually insecure. + * + * In TLS clients, when a client authenticates a server through its + * certificate, the client normally checks three things: + * - the certificate chain must be valid; + * - the chain must start from a trusted CA; + * - the certificate must cover the server name that is expected by the client. + * + * Omitting any of these checks is generally insecure, and can allow a + * malicious server to impersonate a legitimate server. + * + * The third check may be safely skipped in some unusual scenarios, + * such as networks where eavesdropping is a risk but not active attacks, + * or a private PKI where the client equally trusts all servers that are + * accredited by the root CA. + * + * You should call mbedtls_ssl_set_hostname() with the expected server name + * before starting a TLS handshake on a client (unless the client is + * set up to only use PSK-based authentication, which does not rely on the + * host name). If you have determined that server name verification is not + * required for security in your scenario, call mbedtls_ssl_set_hostname() + * with \p NULL as the server name. + * + * This error is raised if all of the following conditions are met: + * + * - A TLS client is configured with the authentication mode + * #MBEDTLS_SSL_VERIFY_REQUIRED (default). + * - Certificate authentication is enabled. + * - The client does not call mbedtls_ssl_set_hostname(). + */ +#define MBEDTLS_ERR_SSL_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME -0x5D80 /* * Various constants diff --git a/library/error.c b/library/error.c index cb7ad57e45..dc7590461c 100644 --- a/library/error.c +++ b/library/error.c @@ -508,6 +508,8 @@ const char *mbedtls_high_level_strerr(int error_code) return( "SSL - Invalid value in SSL config" ); case -(MBEDTLS_ERR_SSL_CACHE_ENTRY_NOT_FOUND): return( "SSL - Cache entry not found" ); + case -(MBEDTLS_ERR_SSL_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME): + return( "SSL - Attempt to verify a certificate without an expected hostname. This is usually insecure. In TLS clients, when a client authenticates a server through its certificate, the client normally checks three things: - the certificate chain must be valid; - the chain must start from a trusted CA; - the certificate must cover the server name that is expected by the client. Omitting any of these checks is generally insecure, and can allow a malicious server to impersonate a legitimate server. The third check may be safely skipped in some unusual scenarios, such as networks where eavesdropping is a risk but not active attacks, or a private PKI where the client equally trusts all servers that are accredited by the root CA. You should call mbedtls_ssl_set_hostname() with the expected server name before starting a TLS handshake on a client (unless the client is set up to only use PSK-based authentication, which does not rely on the host name). If you have determined that server name verification is not required for security in your scenario, call mbedtls_ssl_set_hostname() with \\p NULL as the server name. This error is raised if all of the following conditions are met: - A TLS client is configured with the authentication mode #MBEDTLS_SSL_VERIFY_REQUIRED (default). - Certificate authentication is enabled. - The client does not call mbedtls_ssl_set_hostname()" ); #endif /* MBEDTLS_SSL_TLS_C */ #if defined(MBEDTLS_X509_USE_C) || defined(MBEDTLS_X509_CREATE_C)