client-v2: satisfy SonarCloud quality gate for cipher-suite selection

Clears the two new-code quality-gate conditions introduced by the cipher-suite
change on this branch:

- Security rating (java:S5527): scope a @SuppressWarnings on the intentional
  trust-all HostnameVerifier. It is used only for SSLMode.TRUST/VERIFY_CA (the
  user explicitly opted out of hostname verification) or a custom SNI; STRICT
  keeps the default verifying behaviour via a null verifier, so secure-by-default
  verification is preserved. SonarCloud only flagged it because the restructure
  moved the pre-existing line into new code.
- New-code coverage: add CustomSSLConnectionFactory unit tests that assert the
  configured cipher suites are forwarded to the base socket factory, that the
  legacy 3-arg constructor applies no restriction, and the existing SNI handling
  in prepareSocket. This covers the previously-uncovered legacy constructor.

Also adds the missing CHANGELOG entry for the feature.

Fixes: #2882

Author: polyglotAI-bot

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 [Release Migration Guide](docs/releases/0_11_0.md)
 
+### New Features
+
+- **[client-v2, jdbc-v2]** Added TLS cipher suite selection. `Client.Builder.setSSLCipherSuites(String...)` (client-v2)
+  and the comma-separated `ssl_cipher_suites` connection property (client-v2 and jdbc-v2) restrict the cipher suites
+  enabled on secure connections; when unset, the JVM defaults are used. Cipher-suite selection is independent of the
+  trust configuration and `ssl_mode`. (https://github.com/ClickHouse/clickhouse-java/issues/2882)
+
 ### Bug Fixes 
 
 - **[client-v2]** Fixed container query parameters being sent unquoted, so `Client.query(sql, params, settings)` binding

client-v2/src/main/java/com/clickhouse/client/api/internal/HttpAPIClientHelper.java

@@ -296,6 +296,10 @@ public CloseableHttpClient createHttpClient(boolean initSslContext, Map<String,
                 // Skip hostname verification only for trust-all modes or when a custom SNI is used (the
                 // connection hostname would not match the certificate); otherwise a null verifier makes the
                 // factory fall back to the JDK/HttpClient default verifier, keeping STRICT verification.
+                // java:S5527 - the permissive verifier is applied only for SSLMode.TRUST/VERIFY_CA (where the
+                // user has explicitly opted out of hostname verification) or a custom SNI; STRICT keeps the
+                // default verifying behaviour, so secure-by-default hostname verification is preserved.
+                @SuppressWarnings("java:S5527")
                 HostnameVerifier hostnameVerifier = trustAllHostnames || hasSNI ? (hostname, session) -> true : null;
                 sslConnectionSocketFactory = new CustomSSLConnectionFactory(socketSNI, sslContext, hostnameVerifier,
                         enabledCipherSuites);
@@ -1074,6 +1078,7 @@ public static class CustomSSLConnectionFactory extends SSLConnectionSocketFactor
 
         private final SNIHostName defaultSNI;
 
+        // Retained for backward compatibility; delegates with no cipher-suite restriction (JVM defaults).
         public CustomSSLConnectionFactory(String defaultSNI, SSLContext sslContext, HostnameVerifier hostnameVerifier) {
             this(defaultSNI, sslContext, hostnameVerifier, null);
         }

client-v2/src/test/java/com/clickhouse/client/api/internal/HttpAPIClientHelperTest.java

@@ -1,5 +1,93 @@
-package com.clickhouse.client.api.internal;
-
-public class HttpAPIClientHelperTest {
-
-}
+package com.clickhouse.client.api.internal;
+
+import com.clickhouse.client.api.internal.HttpAPIClientHelper.CustomSSLConnectionFactory;
+import org.apache.hc.client5.http.ssl.SSLConnectionSocketFactory;
+import org.mockito.ArgumentCaptor;
+import org.testng.annotations.Test;
+
+import javax.net.ssl.SNIHostName;
+import javax.net.ssl.SNIServerName;
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.SSLParameters;
+import javax.net.ssl.SSLSocket;
+import java.lang.reflect.Field;
+import java.util.List;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+import static org.testng.Assert.assertEquals;
+import static org.testng.Assert.assertNull;
+
+public class HttpAPIClientHelperTest {
+
+    /**
+     * The configured cipher suites must be forwarded to the base {@link SSLConnectionSocketFactory}, which is
+     * what enables them on each secure connection. This is the core of the cipher-suite feature.
+     */
+    @Test
+    public void testCipherSuiteConstructorForwardsSuitesToBaseFactory() throws Exception {
+        String[] suites = {"TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256"};
+        CustomSSLConnectionFactory factory = new CustomSSLConnectionFactory(
+                null, SSLContext.getDefault(), (hostname, session) -> true, suites);
+
+        assertEquals(baseSupportedCipherSuites(factory), suites,
+                "configured cipher suites must reach the base socket factory that enables them per connection");
+    }
+
+    /**
+     * The three-argument constructor is retained for backward compatibility and must delegate with no cipher
+     * restriction, so callers that do not configure cipher suites keep the JVM defaults.
+     */
+    @Test
+    public void testLegacyConstructorAppliesNoCipherRestriction() throws Exception {
+        CustomSSLConnectionFactory factory = new CustomSSLConnectionFactory(
+                "legacy.example.com", SSLContext.getDefault(), (hostname, session) -> true);
+
+        assertNull(baseSupportedCipherSuites(factory),
+                "the legacy constructor must not restrict cipher suites");
+    }
+
+    /**
+     * A configured SNI host is applied to every prepared socket via the standard SSL parameters.
+     */
+    @Test
+    public void testConfiguredSniAppliedToPreparedSocket() throws Exception {
+        CustomSSLConnectionFactory factory = new CustomSSLConnectionFactory(
+                "sni.example.com", SSLContext.getDefault(), (hostname, session) -> true, null);
+
+        SSLSocket socket = mock(SSLSocket.class);
+        when(socket.getSSLParameters()).thenReturn(new SSLParameters());
+
+        factory.prepareSocket(socket, null);
+
+        ArgumentCaptor<SSLParameters> params = ArgumentCaptor.forClass(SSLParameters.class);
+        verify(socket).setSSLParameters(params.capture());
+        List<SNIServerName> serverNames = params.getValue().getServerNames();
+        assertEquals(serverNames.size(), 1, "the configured SNI host must be applied to the socket");
+        assertEquals(((SNIHostName) serverNames.get(0)).getAsciiName(), "sni.example.com");
+    }
+
+    /**
+     * A blank SNI is treated as unset: the socket's SSL parameters must be left untouched so the defaults
+     * (and any cipher suites the base factory already applied) are preserved.
+     */
+    @Test
+    public void testBlankSniLeavesSocketParametersUntouched() throws Exception {
+        CustomSSLConnectionFactory factory = new CustomSSLConnectionFactory(
+                "  ", SSLContext.getDefault(), (hostname, session) -> true, null);
+
+        SSLSocket socket = mock(SSLSocket.class);
+        factory.prepareSocket(socket, null);
+
+        verify(socket, never()).setSSLParameters(any());
+    }
+
+    private static String[] baseSupportedCipherSuites(CustomSSLConnectionFactory factory) throws Exception {
+        Field field = SSLConnectionSocketFactory.class.getDeclaredField("supportedCipherSuites");
+        field.setAccessible(true);
+        return (String[]) field.get(factory);
+    }
+}