You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by lh...@apache.org on 2026/08/13 01:47:19 UTC

(pulsar) 04/04: [improve][misc] PIP-478: finish correcting the hostname-verification record

This is an automated email from the ASF dual-hosted git repository.

lhotari pushed a commit to branch lh-pip-478-remove-pip337-v3
in repository https://gitbox.apache.org/repos/asf/pulsar.git

commit fa40bd070d1ce2d4728a77aeeee133050aa627cf
Author: Lari Hotari <lh...@apache.org>
AuthorDate: Thu Aug 13 03:19:06 2026 +0300

    [improve][misc] PIP-478: finish correcting the hostname-verification record
    
    Review found that three of the four CN/SAN passages were corrected and the fourth was not —
    and the one missed is the breaking-change bullet under Backward & Forward Compatibility,
    which is exactly where the other two send compatibility readers. It still announced "SAN
    required" and "a CN-only certificate no longer suffices", contradicting the Security
    Considerations text two sections above. An operator following the document's own routing
    would have reissued fleet certificates for a break that does not exist on the default
    engines.
    
    The bullet now states what actually changes: hostname verification is on by default, a
    matching SAN always suffices, the CN is still consulted on the default engines for a
    certificate carrying no dNSName SAN, and Conscrypt-pinned clients are what tighten.
    
    The mechanism is stated precisely too. Netty's native OpenSSL/BoringSSL engine does not
    verify the hostname itself — it delegates to the Java trust manager — so the JDK's
    HostnameChecker and its CN fallback govern both default engines, not BoringSSL's own
    matching.
    
    Also swept the framing out of the code: the broker TLS support javadoc claimed PIP-478
    turns on "SAN-only verification", and eleven proxy tests plus two certificate-generation
    scripts carried the same phrase, so the corrected record would have been contradicted by
    the next file a reader opened.
    
    Two mislabels found in the same review, pre-existing but adjacent: the trust-manager
    fallback is documented as being for "a provider that offers none (e.g. Conscrypt)", but
    real Conscrypt registers both PKIX factories — the fallback is for a third-party provider,
    and the test stub named "Conscrypt-shaped" models a provider that does not exist. Renamed
    and re-described. The same javadoc still advertised a Conscrypt hostname-verifier
    propagation workaround whose body was removed when Conscrypt 2.6.1 landed.
    
    Assisted-by: Claude Code (Opus 5)
---
 pip/pip-478.md                                                 |  4 ++--
 .../java/org/apache/pulsar/broker/tls/TlsFactorySupport.java   |  2 +-
 .../org/apache/pulsar/client/impl/crypto/MessageCryptoBc.java  |  4 ++--
 .../java/org/apache/pulsar/common/tls/impl/TlsContexts.java    |  4 ++--
 .../java/org/apache/pulsar/common/util/tls/JdkSslContexts.java |  8 ++++----
 .../org/apache/pulsar/common/util/tls/JdkSslContextsTest.java  | 10 ++++++----
 .../pulsar/proxy/server/ProxyKeyStoreTlsTransportTest.java     |  2 +-
 .../pulsar/proxy/server/ProxyKeyStoreTlsWithAuthTest.java      |  2 +-
 .../pulsar/proxy/server/ProxyKeyStoreTlsWithoutAuthTest.java   |  2 +-
 .../org/apache/pulsar/proxy/server/ProxyMutualTlsTest.java     |  2 +-
 .../apache/pulsar/proxy/server/ProxyServiceTlsStarterTest.java |  2 +-
 .../org/apache/pulsar/proxy/server/ProxyTlsFactoryTest.java    |  2 +-
 .../test/java/org/apache/pulsar/proxy/server/ProxyTlsTest.java |  2 +-
 .../apache/pulsar/proxy/server/ProxyWithAuthorizationTest.java |  4 ++--
 .../pulsar/proxy/server/ProxyWithoutServiceDiscoveryTest.java  |  2 +-
 .../pulsar/proxy/server/SslContextFallbackSynthesisTest.java   |  2 +-
 tests/certificate-authority/ec/jks/key_store_generation.txt    |  2 +-
 tests/certificate-authority/generate_keystore.sh               |  2 +-
 18 files changed, 30 insertions(+), 28 deletions(-)

diff --git a/pip/pip-478.md b/pip/pip-478.md
index 130a3c4bed35..1d72b216222f 100644
--- a/pip/pip-478.md
+++ b/pip/pip-478.md
@@ -1244,7 +1244,7 @@ New OpenTelemetry instruments:
 - **TLS is secure by default in 5.0.** Hostname verification is **ON by default** for both the v4 and v5 client *and* for every broker / proxy / geo-replication **outbound** (broker-as-client) connection — a peer whose certificate does not match its hostname/SAN is rejected. Concretely, PIP-478 flips these defaults from `false` to `true`: `tlsHostnameVerificationEnable` on the v4 `ClientConfigurationData` (which also flows into the `CLIENT_DEFAULT` `TlsPolicy`), `tlsHostnameVerificationE [...]
 - **Pulsar's own CN-matching machinery is removed.** The custom `TlsHostnameVerifier` and its CN machinery (`SubjectName`, `PublicSuffixMatcher` / `PublicSuffixList`, `DomainType`) are deleted; hostname verification is whatever the configured provider implements under the standard endpoint-identification algorithm `"HTTPS"`.
 
-  Be precise about what that does and does not change. The standard algorithm is **not** SAN-only: per RFC 6125 §6.4.4, the JDK and OpenSSL/BoringSSL engines consult the certificate's CN **when it carries no `dNSName` SAN**, and ignore the CN once any is present. So on the default engines a CN-only certificate is still accepted, before and after this change. What the removal does change is **Conscrypt-pinned clients**: `SecurityUtility`'s static initializer used to install the CN-toleran [...]
+  Be precise about what that does and does not change. The standard algorithm is **not** SAN-only: per RFC 6125 §6.4.4, the CN is consulted **when a certificate carries no `dNSName` SAN**, and ignored once any is present. That holds on both default engines — Netty's native (OpenSSL/BoringSSL) engine does not verify the hostname itself, it delegates to the Java trust manager, so the JDK's `HostnameChecker` and its CN fallback apply there too. So on the default engines a CN-only certificat [...]
 
   This affects **server-hostname** matching only — a *client* certificate's CN is still read as the role token by the broker's `AuthenticationProviderTls`, unchanged.
 - **A configured truststore never silently widens trust.** On the **keystore** axis a configured `trustStorePath` whose store holds zero X.509 certificates **fails the load** instead of resolving to an empty trust list, which the context builders would treat as "not configured" and satisfy with the *platform default* trust store — silently trusting every public CA. This restores the 4.x `KeyStoreSSLContext` behavior (the `TrustManagerFactory` was initialized with the explicit store, so a [...]
@@ -1257,7 +1257,7 @@ New OpenTelemetry instruments:
 
 # Backward & Forward Compatibility
 
-- **BREAKING CHANGE — TLS hostname verification on by default + SAN required (5.0).** A v4 or v5 client — and any broker / proxy / geo-replication **outbound** connection — that connects to a server whose certificate lacks a SubjectAltName matching the target hostname now **fails the TLS handshake**, where 4.x (hostname verification off by default) silently accepted it. Deprecated CN-field matching is also removed, so a CN-only certificate no longer suffices even when its CN names the ho [...]
+- **BREAKING CHANGE — TLS hostname verification on by default (5.0).** A v4 or v5 client — and any broker / proxy / geo-replication **outbound** connection — that connects to a server whose certificate does not match the target hostname now **fails the TLS handshake**, where 4.x (hostname verification off by default) silently accepted it. Matching follows the provider's standard endpoint-identification algorithm: a SubjectAltName matching the hostname always suffices, and on the default  [...]
 - The v5 client is published as a standalone artifact in 5.0.0-M1 (the existing `pulsar-client-v5` and `pulsar-client-api-v5` modules from PIP-466), **unshaded**. The v5 client will not ship a shaded distribution; applications that need shading to resolve a dependency conflict relocate it themselves in their own build, as they would any other dependency (see the plugin-packaging note above).
 - **BREAKING CHANGE — PIP-337 removed (5.0).** PIP-337 is removed from Pulsar in Pulsar 5.0 since retaining it in the code base causes an additional maintenance burden and most users don't use it. Concretely: the `sslFactoryPlugin` / `sslFactoryPluginParams` / `brokerClientSslFactoryPlugin` / `brokerClientSslFactoryPluginParams` **config-file keys are removed** and a stale non-default value is **rejected at broker/proxy startup** (and at client `loadConf`) by a removed-key validation; th [...]
 - **Security-relevant behavior changes (5.0), surfaced here so they aren't buried in the removal inventory:**
diff --git a/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/tls/TlsFactorySupport.java b/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/tls/TlsFactorySupport.java
index c63e78f81935..4d85b4505e1f 100644
--- a/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/tls/TlsFactorySupport.java
+++ b/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/tls/TlsFactorySupport.java
@@ -293,7 +293,7 @@ public final class TlsFactorySupport {
      * is conditional, because a default that breaks a supported platform is not a usable default.
      *
      * <p>This applies to server listeners only. Client-side hostname verification is unaffected: a server
-     * does not verify hostnames, so pinning Conscrypt here cannot interact with the SAN-only verification
+     * does not verify hostnames, so pinning Conscrypt here cannot interact with the hostname verification
      * PIP-478 turns on.
      *
      * @param explicitJsseProvider the configured {@code jsseProvider} (may be null/blank)
diff --git a/pulsar-client-messagecrypto-bc/src/main/java/org/apache/pulsar/client/impl/crypto/MessageCryptoBc.java b/pulsar-client-messagecrypto-bc/src/main/java/org/apache/pulsar/client/impl/crypto/MessageCryptoBc.java
index eb325236a664..7363cc3ecdb0 100644
--- a/pulsar-client-messagecrypto-bc/src/main/java/org/apache/pulsar/client/impl/crypto/MessageCryptoBc.java
+++ b/pulsar-client-messagecrypto-bc/src/main/java/org/apache/pulsar/client/impl/crypto/MessageCryptoBc.java
@@ -95,8 +95,8 @@ public class MessageCryptoBc implements MessageCrypto<MessageMetadata, MessageMe
     // BouncyCastle JCA provider, resolved lazily on first use via the initialization-on-demand holder
     // idiom. Resolution is delegated to JcaProviders.requireBouncyCastleProvider() — the same
     // FIPS-agnostic lookup used elsewhere in Pulsar (e.g. TLS) — so message crypto uses whichever
-    // BouncyCastle provider is
-    // present on the classpath: the non-FIPS "BC" (org.bouncycastle.jce.provider.BouncyCastleProvider)
+    // BouncyCastle provider is present on the classpath: the non-FIPS "BC"
+    // (org.bouncycastle.jce.provider.BouncyCastleProvider)
     // or the FIPS "BCFIPS" (org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider), rather than
     // hardcoding one. The resolved provider is passed directly to the JCA getInstance(...) calls.
     // Deferring the lookup to first use (asymmetric key wrapping with RSA-OAEP/ECIES, or EC key
diff --git a/pulsar-common/src/main/java/org/apache/pulsar/common/tls/impl/TlsContexts.java b/pulsar-common/src/main/java/org/apache/pulsar/common/tls/impl/TlsContexts.java
index e520cdfa344c..984f36cb6fc1 100644
--- a/pulsar-common/src/main/java/org/apache/pulsar/common/tls/impl/TlsContexts.java
+++ b/pulsar-common/src/main/java/org/apache/pulsar/common/tls/impl/TlsContexts.java
@@ -73,7 +73,7 @@ public final class TlsContexts {
     /**
      * The default enabled TLS protocol set, applied whenever the effective protocol list is empty — a policy
      * with no {@code protocols()}, or a synthesized context whose factory companion set none. This preserves
-     * the {@code {TLSv1.3, TLSv1.2}} floor {@code DefaultPulsarSslFactory} forces at engine build:
+     * the {@code {TLSv1.3, TLSv1.2}} floor v4's {@code DefaultPulsarSslFactory} forced at engine build:
      * without it the PIP-478 path would silently defer to the JVM/provider default protocol set, a
      * security-relevant drift on upgrade.
      */
@@ -491,7 +491,7 @@ public final class TlsContexts {
             builder.ciphers(ciphers);
         }
         // Pin the enabled protocols even when the policy configured none, preserving the {TLSv1.3, TLSv1.2}
-        // floor DefaultPulsarSslFactory forces rather than deferring to the provider default.
+        // floor v4's DefaultPulsarSslFactory forced rather than deferring to the provider default.
         String[] enabledProtocols = protocols != null
                 ? protocols.toArray(new String[0])
                 : DEFAULT_ENABLED_PROTOCOLS.toArray(new String[0]);
diff --git a/pulsar-common/src/main/java/org/apache/pulsar/common/util/tls/JdkSslContexts.java b/pulsar-common/src/main/java/org/apache/pulsar/common/util/tls/JdkSslContexts.java
index 93a0fa64096f..b7b736700d83 100644
--- a/pulsar-common/src/main/java/org/apache/pulsar/common/util/tls/JdkSslContexts.java
+++ b/pulsar-common/src/main/java/org/apache/pulsar/common/util/tls/JdkSslContexts.java
@@ -273,8 +273,7 @@ public final class JdkSslContexts {
     /**
      * Build the {@link TrustManager}s for a set of trust anchors, honoring both provider axes: the carrier
      * keystore holding the anchors comes from the pinned JCA provider and the {@code TrustManagerFactory} from
-     * the pinned JSSE provider (algorithm-negotiated as on the key side). Also applies the Conscrypt
-     * hostname-verifier propagation workaround.
+     * the pinned JSSE provider (algorithm-negotiated as on the key side).
      *
      * <p>Exposed for the same reason as {@link #createKeyManagerFactory(PrivateKey, Certificate[], Provider,
      * Provider)}: {@code SslContextBuilder.trustManager(X509Certificate...)} would have Netty build the
@@ -294,8 +293,9 @@ public final class JdkSslContexts {
             return InsecureTrustManagerFactory.INSTANCE.getTrustManagers();
         }
         // Same algorithm negotiation as the key-manager side: prefer the pinned provider's
-        // TrustManagerFactory (BCJSSE registers PKIX, the platform default), fall back to the platform
-        // factory for a provider that offers none (e.g. Conscrypt).
+        // TrustManagerFactory, falling back to the platform factory for a provider that registers none.
+        // Both providers Pulsar can pin do register one — BCJSSE and Conscrypt each offer PKIX — so the
+        // fallback exists for a third-party provider, not for either of them.
         TrustManagerFactory tmf;
         if (provider != null) {
             String algorithm = supportedAlgorithm(provider, "TrustManagerFactory",
diff --git a/pulsar-common/src/test/java/org/apache/pulsar/common/util/tls/JdkSslContextsTest.java b/pulsar-common/src/test/java/org/apache/pulsar/common/util/tls/JdkSslContextsTest.java
index c47c84c8eb31..74e54b003c7c 100644
--- a/pulsar-common/src/test/java/org/apache/pulsar/common/util/tls/JdkSslContextsTest.java
+++ b/pulsar-common/src/test/java/org/apache/pulsar/common/util/tls/JdkSslContextsTest.java
@@ -99,14 +99,16 @@ public class JdkSslContextsTest {
                 .isEqualTo("PKIX");
     }
 
-    // A JSSE provider with no key/trust-manager services at all (Conscrypt) selects no provider algorithm;
+    // A JSSE provider registering no key/trust-manager services selects no provider algorithm; real
+    // Conscrypt is not such a provider (it registers PKIX for both), so this stub stands in for a
+    // third-party one;
     // the caller then falls back to the platform default factory while the SSLContext stays pinned.
     @Test
     public void algorithmNegotiationReturnsNullForProvidersWithoutTheService() {
-        Provider conscryptShaped = new Provider("Conscrypt-shaped", "1.0", "test stub") { };
-        assertThat(JdkSslContexts.supportedAlgorithm(conscryptShaped, "KeyManagerFactory", "SunX509", "PKIX"))
+        Provider noFactoryProvider = new Provider("no-factory-provider", "1.0", "test stub") { };
+        assertThat(JdkSslContexts.supportedAlgorithm(noFactoryProvider, "KeyManagerFactory", "SunX509", "PKIX"))
                 .isNull();
-        assertThat(JdkSslContexts.supportedAlgorithm(conscryptShaped, "TrustManagerFactory", "PKIX", "PKIX"))
+        assertThat(JdkSslContexts.supportedAlgorithm(noFactoryProvider, "TrustManagerFactory", "PKIX", "PKIX"))
                 .isNull();
     }
 
diff --git a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyKeyStoreTlsTransportTest.java b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyKeyStoreTlsTransportTest.java
index c72be85812a3..4c9d106d0bc0 100644
--- a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyKeyStoreTlsTransportTest.java
+++ b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyKeyStoreTlsTransportTest.java
@@ -70,7 +70,7 @@ public class ProxyKeyStoreTlsTransportTest extends MockedPulsarServiceBaseTest {
         proxyConfig.setWebServicePort(Optional.of(0));
         proxyConfig.setWebServicePortTls(Optional.of(0));
         // Advertise over loopback so the proxy service URL host (localhost) matches the keystore server
-        // certificate's SubjectAltName. TLS hostname verification is on by default (PIP-478, SAN-only),
+        // certificate's SubjectAltName. TLS hostname verification is on by default (PIP-478),
         // and the default advertised address resolves to the machine's canonical hostname, which is not
         // in the cert SAN. This keeps hostname verification genuinely enabled. (The broker already
         // advertises localhost via the base test config, so the proxy->broker TLS connection matches too.)
diff --git a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyKeyStoreTlsWithAuthTest.java b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyKeyStoreTlsWithAuthTest.java
index d081c64e167d..8af625572cc9 100644
--- a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyKeyStoreTlsWithAuthTest.java
+++ b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyKeyStoreTlsWithAuthTest.java
@@ -68,7 +68,7 @@ public class ProxyKeyStoreTlsWithAuthTest extends MockedPulsarServiceBaseTest {
         proxyConfig.setWebServicePort(Optional.of(0));
         proxyConfig.setWebServicePortTls(Optional.of(0));
         // Advertise over loopback so the proxy service URL host (localhost) matches the keystore server
-        // certificate's SubjectAltName. TLS hostname verification is on by default (PIP-478, SAN-only),
+        // certificate's SubjectAltName. TLS hostname verification is on by default (PIP-478),
         // and the default advertised address resolves to the machine's canonical hostname, which is not
         // in the cert SAN. This keeps hostname verification genuinely enabled.
         proxyConfig.setAdvertisedAddress("localhost");
diff --git a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyKeyStoreTlsWithoutAuthTest.java b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyKeyStoreTlsWithoutAuthTest.java
index a5dbab28f360..7cb67ed0ecf2 100644
--- a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyKeyStoreTlsWithoutAuthTest.java
+++ b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyKeyStoreTlsWithoutAuthTest.java
@@ -64,7 +64,7 @@ public class ProxyKeyStoreTlsWithoutAuthTest extends MockedPulsarServiceBaseTest
         proxyConfig.setWebServicePort(Optional.of(0));
         proxyConfig.setWebServicePortTls(Optional.of(0));
         // Advertise over loopback so the proxy service URL host (localhost) matches the keystore server
-        // certificate's SubjectAltName. TLS hostname verification is on by default (PIP-478, SAN-only),
+        // certificate's SubjectAltName. TLS hostname verification is on by default (PIP-478),
         // and the default advertised address resolves to the machine's canonical hostname, which is not
         // in the cert SAN. This keeps hostname verification genuinely enabled.
         proxyConfig.setAdvertisedAddress("localhost");
diff --git a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyMutualTlsTest.java b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyMutualTlsTest.java
index 41f1cd832ca1..7fa9a34e5451 100644
--- a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyMutualTlsTest.java
+++ b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyMutualTlsTest.java
@@ -65,7 +65,7 @@ public class ProxyMutualTlsTest extends MockedPulsarServiceBaseTest {
         proxyConfig.setWebServicePortTls(Optional.of(0));
         // Advertise over loopback so the proxy service URL host (localhost) matches the server
         // certificate's SubjectAltName (DNS:localhost, IP:127.0.0.1). TLS hostname verification is on by
-        // default (PIP-478, SAN-only), and the default advertised address resolves to the machine's
+        // default (PIP-478), and the default advertised address resolves to the machine's
         // canonical hostname/IP, which is not in the cert SAN. This keeps hostname verification enabled.
         proxyConfig.setAdvertisedAddress("localhost");
         proxyConfig.setTlsCertificateFilePath(TLS_PROXY_CERT_FILE_PATH);
diff --git a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyServiceTlsStarterTest.java b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyServiceTlsStarterTest.java
index c50bca3e0cd8..87714f96ae68 100644
--- a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyServiceTlsStarterTest.java
+++ b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyServiceTlsStarterTest.java
@@ -78,7 +78,7 @@ public class ProxyServiceTlsStarterTest extends MockedPulsarServiceBaseTest {
         serviceStarter.getConfig().setClusterName(configClusterName);
         // Advertise over loopback so the proxy service URL host (localhost) matches the proxy server
         // certificate's SubjectAltName (proxy.cert.pem carries DNS:localhost, IP:127.0.0.1). TLS hostname
-        // verification is on by default (PIP-478, SAN-only), and the default advertised address (loaded from
+        // verification is on by default (PIP-478), and the default advertised address (loaded from
         // conf/proxy.conf) resolves to the machine's canonical hostname/IP, which is not in the cert SAN.
         serviceStarter.getConfig().setAdvertisedAddress("localhost");
         serviceStarter.start();
diff --git a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyTlsFactoryTest.java b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyTlsFactoryTest.java
index 64f4b4f459c0..cdeea22b0a25 100644
--- a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyTlsFactoryTest.java
+++ b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyTlsFactoryTest.java
@@ -61,7 +61,7 @@ public class ProxyTlsFactoryTest extends MockedPulsarServiceBaseTest {
         proxyConfig.setWebServicePortTls(Optional.of(0));
         // Advertise over loopback so the proxy service URL host (localhost) matches the proxy server
         // certificate's SubjectAltName (proxy.cert.pem carries DNS:localhost, IP:127.0.0.1). TLS hostname
-        // verification is on by default (PIP-478, SAN-only), and the default advertised address resolves
+        // verification is on by default (PIP-478), and the default advertised address resolves
         // to the machine's canonical hostname/IP, which is not in the cert SAN. Keeps verification enabled.
         proxyConfig.setAdvertisedAddress("localhost");
         proxyConfig.setTlsEnabledWithBroker(false);
diff --git a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyTlsTest.java b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyTlsTest.java
index d406016141a2..887f3001d746 100644
--- a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyTlsTest.java
+++ b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyTlsTest.java
@@ -59,7 +59,7 @@ public class ProxyTlsTest extends MockedPulsarServiceBaseTest {
         proxyConfig.setWebServicePortTls(Optional.of(0));
         // Advertise over loopback so the proxy service URL host (localhost) matches the proxy server
         // certificate's SubjectAltName (proxy.cert.pem carries DNS:localhost, IP:127.0.0.1). TLS hostname
-        // verification is on by default (PIP-478, SAN-only), and the default advertised address resolves
+        // verification is on by default (PIP-478), and the default advertised address resolves
         // to the machine's canonical hostname/IP, which is not in the cert SAN. Keeps verification enabled.
         proxyConfig.setAdvertisedAddress("localhost");
         proxyConfig.setTlsEnabledWithBroker(false);
diff --git a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyWithAuthorizationTest.java b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyWithAuthorizationTest.java
index 23925a430e68..9fb634c0d8aa 100644
--- a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyWithAuthorizationTest.java
+++ b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyWithAuthorizationTest.java
@@ -186,7 +186,7 @@ public class ProxyWithAuthorizationTest extends ProducerConsumerBase {
         conf.setProxyRoles(Collections.singleton("Proxy"));
         // Advertise over loopback so the broker service/web URLs the proxy connects to (localhost) match the
         // broker server certificate's SubjectAltName (tls/server-cert.pem carries DNS:localhost, IP:127.0.0.1).
-        // TLS hostname verification is on by default (PIP-478, SAN-only), and the default advertised address
+        // TLS hostname verification is on by default (PIP-478), and the default advertised address
         // resolves to the machine's canonical hostname, which is not in the cert SAN (fails on CI runners).
         conf.setAdvertisedAddress("localhost");
 
@@ -245,7 +245,7 @@ public class ProxyWithAuthorizationTest extends ProducerConsumerBase {
         proxyConfig.setBrokerWebServiceURLTLS(pulsar.getWebServiceAddressTls());
         // Advertise over loopback so the client-facing proxy service URL host (localhost) matches the proxy
         // server certificate's SubjectAltName (tls/server-cert.pem carries DNS:localhost, IP:127.0.0.1). TLS
-        // hostname verification is on by default (PIP-478, SAN-only); the default advertised address resolves
+        // hostname verification is on by default (PIP-478); the default advertised address resolves
         // to the machine's canonical hostname, which is not in the cert SAN (fails on CI runners). The two
         // dedicated hostname-verification tests still fail as intended because their server presents a no-SAN
         // certificate, which cannot match any host regardless of the advertised address.
diff --git a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyWithoutServiceDiscoveryTest.java b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyWithoutServiceDiscoveryTest.java
index 8995b100e383..07a65fcce6e2 100644
--- a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyWithoutServiceDiscoveryTest.java
+++ b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/ProxyWithoutServiceDiscoveryTest.java
@@ -107,7 +107,7 @@ public class ProxyWithoutServiceDiscoveryTest extends ProducerConsumerBase {
         proxyConfig.setWebServicePortTls(Optional.of(0));
         // Advertise over loopback so the client->proxy service URL host (localhost) matches the proxy server
         // certificate's SubjectAltName (proxy.cert.pem carries DNS:localhost, IP:127.0.0.1). TLS hostname
-        // verification is on by default (PIP-478, SAN-only), and the default advertised address resolves to
+        // verification is on by default (PIP-478), and the default advertised address resolves to
         // the machine's canonical hostname/IP, which is not in the cert SAN. This keeps verification enabled.
         proxyConfig.setAdvertisedAddress("localhost");
         proxyConfig.setTlsEnabledWithBroker(true);
diff --git a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/SslContextFallbackSynthesisTest.java b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/SslContextFallbackSynthesisTest.java
index c7434bd41d82..21423d61cf92 100644
--- a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/SslContextFallbackSynthesisTest.java
+++ b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/SslContextFallbackSynthesisTest.java
@@ -95,7 +95,7 @@ public class SslContextFallbackSynthesisTest extends MockedPulsarServiceBaseTest
         proxyConfig.setBrokerProxyAllowedTargetPorts("*");
         // Advertise over loopback so the client->proxy service URL host (localhost) matches the proxy server
         // certificate's SubjectAltName (proxy.cert.pem carries DNS:localhost, IP:127.0.0.1). The client
-        // verifies hostnames (on by default, PIP-478 SAN-only) and the default advertised address resolves
+        // verifies hostnames (on by default, PIP-478) and the default advertised address resolves
         // to the machine's canonical hostname/IP, which is not in the cert SAN.
         proxyConfig.setAdvertisedAddress("localhost");
         proxyConfig.setTlsAllowInsecureConnection(true);
diff --git a/tests/certificate-authority/ec/jks/key_store_generation.txt b/tests/certificate-authority/ec/jks/key_store_generation.txt
index 378b5af898c9..08b7d63c71ce 100644
--- a/tests/certificate-authority/ec/jks/key_store_generation.txt
+++ b/tests/certificate-authority/ec/jks/key_store_generation.txt
@@ -7,7 +7,7 @@ keytool -keystore ca.truststore.jks -alias ca -importcert -file ca.cert.pem -sto
 
 
 # Create server keystore
-# NOTE (Pulsar 5.0 / PIP-478): TLS hostname verification is enabled by default and is SAN-only, so the server
+# NOTE (Pulsar 5.0 / PIP-478): TLS hostname verification is enabled by default, so the server
 # certificate MUST carry a SubjectAltName that matches the connected host (e.g. DNS:localhost / IP:127.0.0.1).
 # The keystore hierarchy has its own CA (this directory's ca.cert.pem / ca.key.pem, trusted via
 # ca.truststore.jks) which is SEPARATE from the PEM hierarchy's CA in the parent directory, so the server
diff --git a/tests/certificate-authority/generate_keystore.sh b/tests/certificate-authority/generate_keystore.sh
index 62836a5b186e..ad547c51e56c 100755
--- a/tests/certificate-authority/generate_keystore.sh
+++ b/tests/certificate-authority/generate_keystore.sh
@@ -28,7 +28,7 @@ COMMON_PARAMS="-storetype JKS -storepass 111111 -keypass 111111 -noprompt"
 
 # generate keystore
 # The broker keystore is presented as a TLS *server* certificate. With TLS hostname verification
-# enabled by default in 5.0 (PIP-478) and CN-based matching removed (SAN-only), the server cert must
+# enabled by default in 5.0 (PIP-478), the server cert must
 # carry a SubjectAltName covering the connected host, otherwise every peer that now verifies hostnames
 # rejects it with "No subject alternative names present". Tests reach the broker/proxy over loopback
 # (advertised address pinned to localhost), so DNS:localhost + IP:127.0.0.1 is sufficient. The client