enhanced ssl certificate error message (#914)

## Description
<!-- Provide a brief summary of the changes made and the issue they aim
to address.-->
This PR implements improved SSL handshake error messages for certificate
path failures. Previously, users received error messages like "Error
while establishing a connection in databricks" or "PKIX path building
failed: sun.security.provider.certpath.SunCertPathBuilderException:
unable to find valid certification path to requested target" when
encountering SSL certificate validation issues. The newer implementation
provides suggestions to users with actionable guidance for resolving SSL
certificate issues as shown below.

```
Unable to find certification path to requested target in truststore: /path/to/truststore.jks

SSL Error: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Details: TLS handshake failure due to TLS Certificate of server being connected is not in the configured truststore.

Next steps:
- Make sure that the connection string has the appropriate Databricks workspace FQDN.
- Verify the configured truststore path and make sure the required certificates are imported.
  .   PEM certificate chain of the warehouse endpoint can be fetched using "openssl s_client -connect <workspace>:443 -showcerts"
  .   Reference KB article with troubleshooting steps.
```

## Testing
<!-- Describe how the changes have been tested-->
### Unit Tests:
- **`testCreateSessionWithSSLCertificatePathError()`** - Tests SSL error
detection using Mockito to mock `DatabricksError` with
`SSLHandshakeException` cause
- **`testCreateSessionWithNonSSLError()`** - Ensures non-SSL errors
still return generic messages
- All existing tests continue to pass


## Additional Notes to the Reviewer
<!-- Share any additional context or insights that may help the reviewer
understand the changes better. This could include challenges faced,
limitations, or compromises made during the development process.
Also, mention any areas of the code that you would like the reviewer to
focus on specifically. -->

---------

Signed-off-by: Sreekanth Vadigi <[email protected]>

Author: sreekanth-db

NEXT_CHANGELOG.md

@@ -13,6 +13,7 @@
 
 ### Updated
 - Column name support for JDBC ResultSet operations is now case-insensitive
+- Enhanced SSL certificate path validation error messages to provide actionable troubleshooting steps.
 
 ### Fixed
 - Fixed Bouncy Castle registration conflicts by using local provider instance instead of global security registration.

src/main/java/com/databricks/jdbc/dbclient/impl/sqlexec/DatabricksSdkClient.java

@@ -42,10 +42,13 @@
 import com.google.common.annotations.VisibleForTesting;
 import java.io.IOException;
 import java.math.BigDecimal;
+import java.net.URL;
 import java.sql.SQLException;
 import java.time.Instant;
 import java.util.*;
 import java.util.stream.Collectors;
+import java.util.stream.Stream;
+import javax.net.ssl.SSLHandshakeException;
 
 /** Implementation of IDatabricksClient interface using Databricks Java SDK. */
 public class DatabricksSdkClient implements IDatabricksClient {
@@ -121,7 +124,7 @@ public ImmutableSessionInfo createSession(
       if (e.getStatusCode() == TEMPORARY_REDIRECT_STATUS_CODE) {
         throw new DatabricksTemporaryRedirectException(TEMPORARY_REDIRECT_EXCEPTION);
       }
-      String errorReason = "Error while establishing a connection in databricks";
+      String errorReason = buildErrorMessage(e);
       throw new DatabricksSQLException(errorReason, e, DatabricksDriverErrorCode.CONNECTION_ERROR);
     } catch (IOException e) {
       String errorMessage = "Error while processing the request via the sdk client";
@@ -549,4 +552,56 @@ private ExecuteStatementResponse wrapGetStatementResponse(
         .setManifest(getStatementResponse.getManifest())
         .setResult(getStatementResponse.getResult());
   }
+
+  /**
+   * Builds actionable error messages for SSL handshake failures. Returns a generic message if the
+   * error is not SSL-related.
+   */
+  private String buildErrorMessage(DatabricksError e) {
+
+    boolean isSSLException =
+        Stream.iterate(e.getCause(), Objects::nonNull, Throwable::getCause)
+            .anyMatch(cause -> cause instanceof SSLHandshakeException);
+
+    boolean isCertificatePathError =
+        e.getMessage().contains("PKIX path building failed")
+            || e.getMessage().contains("unable to find valid certification path");
+
+    if (isSSLException && isCertificatePathError) {
+      return buildSSLCertificatePathErrorMessage(e);
+    }
+
+    return "Error while establishing a connection in databricks";
+  }
+
+  /** Builds the SSL certificate path error message with actionable steps. */
+  private String buildSSLCertificatePathErrorMessage(DatabricksError e) {
+
+    String customTruststorePathMessage = "";
+    if (connectionContext != null && connectionContext.getSSLTrustStore() != null) {
+      customTruststorePathMessage = " in truststore: " + connectionContext.getSSLTrustStore();
+    }
+
+    // Get the actual workspace hostname for the openssl command
+    // by removing protocol and port from host url
+    String workspaceHostname = "<workspace>";
+    try {
+      if (connectionContext != null && connectionContext.getHostUrl() != null) {
+        workspaceHostname = new URL(connectionContext.getHostUrl()).getHost();
+      }
+    } catch (Exception ex) {
+      LOGGER.debug("Could not retrieve workspace hostname for error message", ex);
+    }
+
+    return String.format(
+        "Unable to find certification path to requested target%s\n\n"
+            + "SSL Error: %s\n\n"
+            + "Details: TLS handshake failure due to TLS Certificate of server being connected is not in the configured truststore.\n\n"
+            + "Next steps:\n"
+            + "- Make sure that the connection string has the appropriate Databricks workspace FQDN.\n\n"
+            + "- Verify the configured truststore path and make sure the required certificates are imported.\n"
+            + "  .   PEM certificate chain of the warehouse endpoint can be fetched using \"openssl s_client -connect %s:443 -showcerts\"\n"
+            + "  .   Reference KB article with troubleshooting steps.\n",
+        customTruststorePathMessage, e.getMessage(), workspaceHostname);
+  }
 }

src/test/java/com/databricks/jdbc/dbclient/impl/common/ConfiguratorUtilsTest.java

@@ -96,7 +96,7 @@ private static void createEmptyStore(String filePath, String storeType, String p
    * @param alias The alias for the certificate entry
    * @param isKeyStore Whether this is a keystore (with private key) or truststore (cert only)
    */
-  private static void createDummyStore(
+  public static void createDummyStore(
       String filePath, String storeType, String password, String alias, boolean isKeyStore)
       throws Exception {
     KeyStore keyStore = KeyStore.getInstance(storeType);

src/test/java/com/databricks/jdbc/dbclient/impl/sqlexec/DatabricksSdkClientTest.java

@@ -9,13 +9,16 @@
 import static org.junit.jupiter.api.Assertions.*;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.*;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
 
 import com.databricks.jdbc.api.impl.*;
 import com.databricks.jdbc.api.internal.IDatabricksConnectionContext;
 import com.databricks.jdbc.common.IDatabricksComputeResource;
 import com.databricks.jdbc.common.StatementType;
 import com.databricks.jdbc.common.Warehouse;
 import com.databricks.jdbc.common.util.DatabricksTypeUtil;
+import com.databricks.jdbc.dbclient.impl.common.ConfiguratorUtilsTest;
 import com.databricks.jdbc.dbclient.impl.common.StatementId;
 import com.databricks.jdbc.exception.DatabricksSQLException;
 import com.databricks.jdbc.exception.DatabricksTemporaryRedirectException;
@@ -31,9 +34,11 @@
 import com.databricks.sdk.core.DatabricksError;
 import com.databricks.sdk.core.http.Request;
 import com.databricks.sdk.service.sql.*;
+import java.io.File;
 import java.io.IOException;
 import java.math.BigDecimal;
 import java.util.*;
+import javax.net.ssl.SSLHandshakeException;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
 import org.mockito.Mock;
@@ -52,6 +57,8 @@ public class DatabricksSdkClientTest {
       "SELECT * FROM orders WHERE user_id = ? AND shard = ? AND region_code = ? AND namespace = ?";
   private static final String JDBC_URL =
       "jdbc:databricks://sample-host.18.azuredatabricks.net:4423/default;transportMode=http;ssl=1;AuthMech=3;httpPath=/sql/1.0/warehouses/99999999;";
+  private static final String DEFAULT_KEYSTORE_PASSWORD = "changeit";
+
   private static final Map<String, String> headers =
       new HashMap<>() {
         {
@@ -497,6 +504,82 @@ public void testNullValue() throws DatabricksSQLException {
     assertNull(result.getValue());
   }
 
+  @Test
+  public void testCreateSessionWithSSLCertificatePathError() throws Exception {
+
+    File wrongTrustStore = File.createTempFile("wrong-trust-store", ".jks");
+    wrongTrustStore.deleteOnExit();
+    ConfiguratorUtilsTest.createDummyStore(
+        wrongTrustStore.getAbsolutePath(), "JKS", DEFAULT_KEYSTORE_PASSWORD, "wrong-ca", false);
+
+    SSLHandshakeException sslException =
+        new SSLHandshakeException(
+            "PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target");
+
+    DatabricksError sslError = mock(DatabricksError.class);
+    when(sslError.getMessage()).thenReturn(sslException.getMessage());
+    when(sslError.getCause()).thenReturn(sslException);
+
+    when(apiClient.execute(any(Request.class), eq(CreateSessionResponse.class)))
+        .thenThrow(sslError);
+
+    Properties props = new Properties();
+    props.setProperty("SSLTrustStore", wrongTrustStore.getAbsolutePath());
+    props.setProperty("SSLTrustStorePwd", DEFAULT_KEYSTORE_PASSWORD);
+    props.setProperty("SSLTrustStoreType", "JKS");
+
+    IDatabricksConnectionContext connectionContext =
+        DatabricksConnectionContext.parse(JDBC_URL, props);
+    DatabricksSdkClient databricksSdkClient =
+        new DatabricksSdkClient(connectionContext, statementExecutionService, apiClient);
+
+    // Assert that createSession throws a DatabricksSQLException with actionable error message
+    DatabricksSQLException exception =
+        assertThrows(
+            DatabricksSQLException.class,
+            () -> databricksSdkClient.createSession(warehouse, null, null, null));
+
+    String errorMessage = exception.getMessage();
+
+    // Verify that we get the exact SSL error message
+    String expectedErrorMessage =
+        String.format(
+            "Unable to find certification path to requested target in truststore: %s\n\n"
+                + "SSL Error: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target\n\n"
+                + "Details: TLS handshake failure due to TLS Certificate of server being connected is not in the configured truststore.\n\n"
+                + "Next steps:\n"
+                + "- Make sure that the connection string has the appropriate Databricks workspace FQDN.\n\n"
+                + "- Verify the configured truststore path and make sure the required certificates are imported.\n"
+                + "  .   PEM certificate chain of the warehouse endpoint can be fetched using \"openssl s_client -connect sample-host.18.azuredatabricks.net:443 -showcerts\"\n"
+                + "  .   Reference KB article with troubleshooting steps.\n",
+            wrongTrustStore.getAbsolutePath());
+    assertEquals(expectedErrorMessage, errorMessage);
+
+    // Clean up
+    wrongTrustStore.delete();
+  }
+
+  @Test
+  public void testCreateSessionWithNonSSLError() throws IOException, DatabricksSQLException {
+
+    DatabricksError nonSSLError = new DatabricksError("500", "Some other error", 500);
+    when(apiClient.execute(any(Request.class), eq(CreateSessionResponse.class)))
+        .thenThrow(nonSSLError);
+
+    IDatabricksConnectionContext connectionContext =
+        DatabricksConnectionContext.parse(JDBC_URL, new Properties());
+    DatabricksSdkClient databricksSdkClient =
+        new DatabricksSdkClient(connectionContext, statementExecutionService, apiClient);
+
+    DatabricksSQLException exception =
+        assertThrows(
+            DatabricksSQLException.class,
+            () -> databricksSdkClient.createSession(warehouse, null, null, null));
+
+    String errorMessage = exception.getMessage();
+    assertEquals("Error while establishing a connection in databricks", errorMessage);
+  }
+
   private static ImmutableSqlParameter getSqlParam(
       int parameterIndex, Object x, String databricksType) {
     return ImmutableSqlParameter.builder()