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