[improve][misc] PIP-478: remove the superseded PIP-337 TLS stack (not merged to master)

[lhotari]

UPDATE: This PR was merged to a base branch of another PR in a GitHub PR stack, https://docs.github.com/en/pull-requests/how-tos/stacked-pull-requests. The replacement is #26322.

Main Issue: #25890

PIP: #25890

Stacked on #26319 — this PR's base is lh-pip-478-auth-plugins-v3, the Athenz/SASL branch, which is itself based on #26317. Review those first; the diff here shows only this part.

Motivation

With the PIP-478 migration complete — the PulsarTlsFactory SPI, the default file-based factory, the core migration and the v5-native auth inversion all landed — the PIP-337 TLS infrastructure it replaced has no callers left. So does the SecurityUtility monolith that PIP-478 decomposed into the common.util.tls helpers, and the CN-based hostname-matching machinery whose only referent was that monolith.

Removing them is the point of the exercise: PIP-478 justified its breaking changes partly on the maintenance cost of carrying two TLS stacks, and that cost is only actually paid down when the old one goes.

−3239 lines, +23.

Modifications

Three commits, each independently compiling, ordered so the reference graph unwinds cleanly:

1. The PIP-337 factory stack. PulsarSslFactory, DefaultPulsarSslFactory, PulsarSslConfiguration, KeyManagerProxy, TrustManagerProxy, KeyStoreSSLContext, SSLContextValidatorEngine, and the four tests that exist only to exercise them. Each verified unreachable, including by class-name string — the configuration keys that once named the default factory are gone and now sit on the removed-key tolerance lists, which PulsarConfigurationLoaderTest and ConfigurationDataUtilsTest already pin. SecurityUtility.createAutoRefreshSslContextForClient goes with them: it was the sole production referent of the two proxies and had no callers of its own.
2. SecurityUtility. One live consumer remained — message crypto's BouncyCastle provider lookup — which moves to JcaProviders.requireBouncyCastleProvider(). Same FIPS-agnostic resolution (non-FIPS BC or FIPS BCFIPS, whichever is present), same initialization-on-demand timing, so a resolution failure still surfaces at first asymmetric-crypto use rather than at class loading. Conscrypt registration is unaffected: both classes register it in their static initializers.
3. The CN-matching machinery. TlsHostnameVerifier, PublicSuffixMatcher, PublicSuffixList, SubjectName, DomainType.

The compatibility statement, stated carefully

An earlier draft of this change announced that hostname verification becomes SAN-only and a CN-only certificate is no longer accepted. That is false, and shipping it would have been worse than saying nothing: operators would have reissued certificates for a break that does not exist, and the deployments that genuinely do break would have had no warning.

Verified with real JDK handshakes against this repository's own fixtures:

• The default engines still fall back to the CN. Per RFC 6125 §6.4.4 the CN is consulted when a certificate carries no dNSName SAN, and ignored once any is present. This holds on the JDK engine and on Netty's native OpenSSL/BoringSSL engine — the native engine does not verify hostnames itself, it delegates to the Java trust manager, so the JDK's HostnameChecker governs both.
• The real change is Conscrypt-pinned clients. SecurityUtility's static initializer installed the CN-tolerant TlsHostnameVerifier as Conscrypt's process-global default. With it gone, Conscrypt applies its own RFC 2818 verification and rejects a server certificate with no subjectAltName. A deployment is affected only if it names Conscrypt as its client-side JSSE provider and still uses CN-only server certificates; the remedy is to reissue those with the hostname in the SAN. Conscrypt is never the client-side default — it is defaulted only for TlsPurpose.WEB, i.e. server listeners, which do not verify hostnames.

Four documents asserted the wrong claim and are corrected, including the breaking-change bullet under Backward & Forward Compatibility that the other corrected passages route readers to. Eleven test comments and two certificate-generation scripts repeated the phrase and are swept too, so the corrected record is not contradicted by the next file a reader opens.

Deliberately no new "a CN-only certificate must be rejected" test: it would fail today on the default engines, which is the whole point.

What this PR does not remove

An earlier draft also removed ClusterData.brokerClientSslFactoryPlugin / ...Params. That is dropped, because its stated rationale — "factory selection is broker-level" — was refuted by the core migration, which made per-cluster selection real. pip-478.md argues their retention as a deliberate compatibility decision in nine places, one of them promising that a 5.0 broker "preserves it rather than erasing it on rewrite". Removing them would also delete the only operator-facing signal for a stale value, and erase the fields from stored metadata on any peer-cluster or migration update — silently downgrading a 4.x broker in a mixed fleet to the default factory.

Verifying this change

This change is a removal covered by existing tests:

• sanityCheck (all modules, main and test sources) and quickCheck pass — the deletion's correctness is a reference-graph property, and a full compile is what checks it.
• :pulsar-common:test --tests '*tls*' --tests '*Crypto*' — the decomposed helpers and the migrated BouncyCastle lookup.
• AuthenticationTlsHostnameVerificationTest and ProxyWithAuthorizationTest — the two suites carrying SAN-less negative fixtures, which would notice if hostname behaviour moved. Both still pass, and for the same reason as before: they fail on CN mismatch, not on SAN absence.

Deadness was verified independently by review, including reflective and class-name-string loading, with the false positives triaged.

Does this pull request potentially affect one of the following parts:

If the box was checked, please highlight the changes

• Dependencies (add or upgrade a dependency)
• The public API
• The schema
• The default values of configurations
• The threading model
• The binary protocol
• The REST endpoints
• The admin CLI options
• The metrics
• Anything that affects deployment

The public API: thirteen public classes in pulsar-common are removed, all of them the PIP-337 stack or its CN-matching helpers, and all inventoried in PIP-478's removal impact section. InetAddressUtils and NoopHostnameVerifier survive in the same package.

Deployment: see the compatibility statement above — a Conscrypt-pinned client using CN-only server certificates must reissue them.

Documentation

• doc-required
• doc-not-needed
• doc
• doc-complete

The operator-facing consequence is documented in pip-478.md's compatibility section, which this PR corrects.

Matching PR in forked repository

PR in forked repository: lhotari#254

_{Prepared with the assistance of Claude Code (Opus 5).}

[lhotari]

@nodece I created this PR as part of a "stacked PR" (https://docs.github.com/en/pull-requests/how-tos/stacked-pull-requests), however I hadn't yet added it to the stack so it got merged to the base branch of another PR in the stack. The stacked PR for the same content is now in review in #26322

[nodece]

Sorry that I didn't notice this title.

[lhotari]

Sorry that I didn't notice this title.

No worries. It's the first time I tried out this feature and didn't take care that it got linked as a stack on GitHub side and didn't mark the PR as draft.