GH-1319: [JDBC] Add hostnameOverride connection property for TLS certificate verification and SNI (#1363)

## What's Changed

Adds an optional `hostnameOverride` connection property to the Flight
SQL JDBC driver. When TLS is enabled, the driver verifies the server
certificate against this hostname and sends it for SNI and as the gRPC
`:authority`, instead of using the host in the JDBC URL. This lets the
driver connect with full certificate verification through SSH tunnels,
port-forwarding, private endpoints, or IP addresses that don't match the
server certificate. Today the only option in those cases is
`disableCertificateVerification=true`.

- New property `hostnameOverride` (string, default unset) in
`ArrowFlightConnectionProperty`, passed from `ArrowFlightConnection` to
`ArrowFlightSqlClientHandler.Builder`.
- `Builder.build()` calls `NettyClientBuilder.overrideHostname(...)`
when encryption is on. The property is ignored when
`useEncryption=false`, and a blank value is treated as unset.
- Extra endpoint locations in `getStreams()`: the override is applied
only when the endpoint host and port match the original connection (host
compared case-insensitively, IPv6 brackets ignored). Endpoints at any
other location, or any endpoint when the original connection isn't
encrypted, are verified against their own hostname, as they are today.
This logic is in `Builder.getHostnameOverrideForEndpoint(URI)` so it can
be unit-tested.
- Documented in `docs/source/flight_sql_jdbc_driver.rst` next to
`tlsRootCerts`.

Example:

```
jdbc:arrow-flight-sql://192.0.2.10:443?useEncryption=true&tlsRootCerts=/path/ca.pem&hostnameOverride=flight.example.com
```

## Tests

- New `ConnectionTlsHostnameOverrideTest`. It uses the existing test
certificate, which is issued for `localhost` and has no IP SAN. Its
servers bind to `127.0.0.1` and the tests connect there, so they don't
depend on how `localhost` resolves. Failure cases assert that the cause
is a `CertificateException`, not just any `SQLException`:
- without the property, the connection fails (`No subject alternative
names present`);
- with `hostnameOverride=localhost`, set in the URL or in `Properties`,
it succeeds with full verification;
- a non-matching override fails, which shows verification uses the
override;
  - a blank `hostnameOverride=` behaves as unset;
  - the property is ignored for unencrypted connections;
- a partitioned query whose endpoint is at the connection's host and
port succeeds, which shows the override reaches endpoint clients;
- a partitioned query whose endpoint is on the connection's IP but a
different port fails, which shows the override is not applied there.
- `ArrowFlightSqlClientHandlerBuilderTest`: the default is unset and the
builder copy keeps the value. The endpoint rule is covered for same host
and port, different port, no port, different case, IPv6 with and without
brackets, different host, unencrypted connection, blank value, and no
override set.
- `ArrowFlightConnectionConfigImplTest`: the property is parsed.

This change is additive and has no breaking changes.

Closes #1319.

---------

Co-authored-by: Fred Park <parkfrex@amazon.com>

Author: fredjoonpark

docs/source/flight_sql_jdbc_driver.rst

@@ -118,6 +118,17 @@ case-sensitive. The supported parameters are:
      - Path to PEM-encoded root certificates for TLS - use this as
        an alternative to ``trustStore``
 
+   * - hostnameOverride
+     - null
+     - When TLS is enabled, the hostname to verify the server certificate
+       against and to send for SNI and as the gRPC ``:authority`` header,
+       instead of **HOSTNAME**. Use this when
+       connecting through a tunnel, a private endpoint, or an IP address
+       that does not match the server certificate. Endpoints returned by
+       the server are only verified against this hostname if they are on
+       the same host and port as the connection. Ignored when
+       ``useEncryption`` is false.
+
    * - clientCertificate
      - null
      - Path to PEM-encoded client mTLS certificate when the Flight

flight/flight-sql-jdbc-core/src/main/java/org/apache/arrow/driver/jdbc/ArrowFlightConnection.java

@@ -119,6 +119,7 @@ private static ArrowFlightSqlClientHandler createNewClientHandler(
           .withBufferAllocator(allocator)
           .withEncryption(config.useEncryption())
           .withDisableCertificateVerification(config.getDisableCertificateVerification())
+          .withHostnameOverride(config.getHostnameOverride())
           .withToken(config.getToken())
           .withCallOptions(config.toCallOption())
           .withRetainCookies(config.retainCookies())

flight/flight-sql-jdbc-core/src/main/java/org/apache/arrow/driver/jdbc/client/ArrowFlightSqlClientHandler.java

@@ -188,6 +188,7 @@ public List<CloseableEndpointStreamPair> getStreams(final FlightInfo flightInfo)
                     .withHost(endpointUri.getHost())
                     .withPort(endpointUri.getPort())
                     .withEncryption(endpointUri.getScheme().equals(LocationSchemes.GRPC_TLS))
+                    .withHostnameOverride(builder.getHostnameOverrideForEndpoint(endpointUri))
                     .withClientCache(flightClientCache)
                     .withConnectTimeout(builder.connectTimeout);
 
@@ -677,6 +678,8 @@ public static final class Builder {
 
     @VisibleForTesting boolean disableCertificateVerification;
 
+    @VisibleForTesting @Nullable String hostnameOverride;
+
     @VisibleForTesting boolean useSystemTrustStore = true;
 
     @VisibleForTesting String tlsRootCertificatesPath;
@@ -732,6 +735,7 @@ public Builder() {}
       this.token = original.token;
       this.useEncryption = original.useEncryption;
       this.disableCertificateVerification = original.disableCertificateVerification;
+      this.hostnameOverride = original.hostnameOverride;
       this.useSystemTrustStore = original.useSystemTrustStore;
       this.tlsRootCertificatesPath = original.tlsRootCertificatesPath;
       this.clientCertificatePath = original.clientCertificatePath;
@@ -840,6 +844,54 @@ public Builder withDisableCertificateVerification(
       return this;
     }
 
+    /**
+     * Sets the hostname to use for TLS certificate verification and SNI instead of the host this
+     * handler connects to. It is also sent as the gRPC authority ({@code :authority} header).
+     * Ignored when encryption is disabled.
+     *
+     * @param hostnameOverride the hostname to verify the server certificate against, or null or
+     *     blank to use the host.
+     * @return this instance.
+     */
+    public Builder withHostnameOverride(@Nullable final String hostnameOverride) {
+      final String trimmed = hostnameOverride == null ? null : hostnameOverride.trim();
+      this.hostnameOverride = trimmed == null || trimmed.isEmpty() ? null : trimmed;
+      return this;
+    }
+
+    /**
+     * Gets the hostname override to use when connecting to an endpoint location. The override is
+     * only valid for the host and port it was configured for, so endpoints at any other location
+     * are verified against their own hostname. Like the override itself, it is ignored when the
+     * original connection does not use encryption.
+     *
+     * @param endpointUri the endpoint location.
+     * @return the hostname override if the endpoint is on the original host and port, otherwise
+     *     null.
+     */
+    @VisibleForTesting
+    @Nullable String getHostnameOverrideForEndpoint(final URI endpointUri) {
+      final String endpointHost = stripBrackets(endpointUri.getHost());
+      if (!useEncryption
+          || hostnameOverride == null
+          || endpointHost == null
+          || endpointUri.getPort() != port
+          || !endpointHost.equalsIgnoreCase(stripBrackets(host))) {
+        return null;
+      }
+      return hostnameOverride;
+    }
+
+    /**
+     * Strips the brackets from an IPv6 literal. {@link URI#getHost()} keeps them, but a host set
+     * through properties may not have them.
+     */
+    private static @Nullable String stripBrackets(@Nullable final String host) {
+      return host != null && host.startsWith("[") && host.endsWith("]")
+          ? host.substring(1, host.length() - 1)
+          : host;
+    }
+
     /**
      * Sets whether to use the certificates from the operating system.
      *
@@ -1070,6 +1122,10 @@ public ArrowFlightSqlClientHandler build() throws SQLException {
         clientBuilder.location(location);
 
         if (useEncryption) {
+          if (hostnameOverride != null) {
+            clientBuilder.overrideHostname(hostnameOverride);
+          }
+
           if (disableCertificateVerification) {
             clientBuilder.verifyServer(false);
           } else {

flight/flight-sql-jdbc-core/src/main/java/org/apache/arrow/driver/jdbc/utils/ArrowFlightConnectionConfigImpl.java

@@ -112,6 +112,15 @@ public String getTlsRootCertificatesPath() {
     return ArrowFlightConnectionProperty.TLS_ROOT_CERTS.getString(properties);
   }
 
+  /**
+   * Gets the hostname to use for TLS certificate verification and SNI instead of the host.
+   *
+   * @return the hostname override, or null if not set.
+   */
+  public String getHostnameOverride() {
+    return ArrowFlightConnectionProperty.HOSTNAME_OVERRIDE.getString(properties);
+  }
+
   public String getClientCertificatePath() {
     return ArrowFlightConnectionProperty.CLIENT_CERTIFICATE.getString(properties);
   }
@@ -258,6 +267,7 @@ public enum ArrowFlightConnectionProperty implements ConnectionProperty {
     TRUST_STORE_PASSWORD("trustStorePassword", null, Type.STRING, false),
     USE_SYSTEM_TRUST_STORE("useSystemTrustStore", true, Type.BOOLEAN, false),
     TLS_ROOT_CERTS("tlsRootCerts", null, Type.STRING, false),
+    HOSTNAME_OVERRIDE("hostnameOverride", null, Type.STRING, false),
     CLIENT_CERTIFICATE("clientCertificate", null, Type.STRING, false),
     CLIENT_KEY("clientKey", null, Type.STRING, false),
     THREAD_POOL_SIZE("threadPoolSize", 1, Type.NUMBER, false),