feat: support channel binding configuration in PgConnectOptions

Introduce support for configuring channel binding mechanisms during the
SCRAM-SHA-256-PLUS authentication handshake. This allows users to enforce,
prefer, or disable channel binding securely.

- Add channelBinding property and getters/setters to PgConnectOptions
- Update PgConnectionUriParser to parse 'channel_binding' from connection URIs
- Store channel binding preference in Netty Channel attributes during initialization
- Propagate the configuration to ScramAuthentication to negotiate -PLUS variants
- Fail the connection handshake if a mismatch or unsupported negotiation occurs

Signed-off-by: Jorge Solorzano <jorsol@gmail.com>

Author: jorsol

vertx-pg-client/pom.xml

@@ -51,7 +51,7 @@
     <dependency>
       <groupId>com.ongres.scram</groupId>
       <artifactId>scram-client</artifactId>
-      <version>3.2</version>
+      <version>3.4</version>
     </dependency>
 
     <!-- Testing purposes -->

vertx-pg-client/src/main/java/io/vertx/pgclient/ChannelBinding.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2026 Contributors to the Eclipse Foundation
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+ */
+package io.vertx.pgclient;
+
+import io.vertx.codegen.annotations.VertxGen;
+
+/**
+ * The different values for the Channel Binding parameter provide different levels of
+ * protection. Channel binding is a method for the server to authenticate itself to the client.
+ * It is only supported over SSL connections with PostgreSQL 11 or later servers using the
+ * SCRAM authentication method.
+ *
+ * @see <a href=
+ *      "https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-CHANNEL-BINDING">
+ *      libpq channel_binding</a>
+ */
+@VertxGen
+public enum ChannelBinding {
+
+  /**
+   * Prevents the use of channel binding
+   */
+  DISABLE("disable"),
+
+  /**
+   * Means that the client will choose channel binding if available.
+   */
+  PREFER("prefer"),
+
+  /**
+   * Means that the connection must employ channel binding.
+   */
+  REQUIRE("require");
+
+  public static final ChannelBinding[] VALUES = ChannelBinding.values();
+
+  public final String value;
+
+  ChannelBinding(String value) {
+    this.value = value;
+  }
+
+  public static ChannelBinding of(String value) {
+    for (ChannelBinding channelBinding : VALUES) {
+      if (channelBinding.value.equalsIgnoreCase(value)) {
+        return channelBinding;
+      }
+    }
+
+    throw new IllegalArgumentException("Could not find an appropriate Channel Binding mode for the value [" + value + "].");
+  }
+}

vertx-pg-client/src/main/java/io/vertx/pgclient/PgConnectOptions.java

@@ -99,6 +99,9 @@ public static PgConnectOptions fromEnv() {
     if (getenv("PGSSLNEGOTIATION") != null) {
       pgConnectOptions.setSslNegotiation(SslNegotiation.of(getenv("PGSSLNEGOTIATION")));
     }
+    if (getenv(" PGCHANNELBINDING") != null) {
+      pgConnectOptions.setChannelBinding(ChannelBinding.of(getenv(" PGCHANNELBINDING")));
+    }
     return pgConnectOptions;
   }
 
@@ -110,6 +113,7 @@ public static PgConnectOptions fromEnv() {
   public static final int DEFAULT_PIPELINING_LIMIT = 256;
   public static final SslMode DEFAULT_SSLMODE = SslMode.DISABLE;
   public static final SslNegotiation DEFAULT_SSL_NEGOTIATION = SslNegotiation.POSTGRES;
+  public static final ChannelBinding DEFAULT_CHANNEL_BINDING = ChannelBinding.PREFER;
   public static final boolean DEFAULT_USE_LAYER_7_PROXY = false;
   public static final Map<String, String> DEFAULT_PROPERTIES;
 
@@ -125,6 +129,7 @@ public static PgConnectOptions fromEnv() {
   private int pipeliningLimit = DEFAULT_PIPELINING_LIMIT;
   private SslMode sslMode = DEFAULT_SSLMODE;
   private SslNegotiation sslNegotiation = DEFAULT_SSL_NEGOTIATION;
+  private ChannelBinding channelBinding = DEFAULT_CHANNEL_BINDING;
   private boolean useLayer7Proxy = DEFAULT_USE_LAYER_7_PROXY;
 
   public PgConnectOptions() {
@@ -143,6 +148,7 @@ public PgConnectOptions(SqlConnectOptions other) {
       pipeliningLimit = opts.pipeliningLimit;
       sslMode = opts.sslMode;
       sslNegotiation = opts.sslNegotiation;
+      channelBinding = opts.channelBinding;
     }
   }
 
@@ -151,6 +157,7 @@ public PgConnectOptions(PgConnectOptions other) {
     pipeliningLimit = other.pipeliningLimit;
     sslMode = other.sslMode;
     sslNegotiation = other.sslNegotiation;
+    channelBinding = other.channelBinding;
   }
 
   @Override
@@ -258,6 +265,24 @@ public PgConnectOptions setSslNegotiation(SslNegotiation sslNegotiation) {
     return this;
   }
 
+  /**
+   * @return the value of current Channel Binding mode
+   */
+  public ChannelBinding getChannelBinding() {
+    return channelBinding;
+  }
+
+  /**
+   * Set {@link ChannelBinding} for the client, this option controls the client's use of channel binding.
+   *
+   * @param channelBinding the channel binding mode
+   * @return a reference to this, so the API can be used fluently
+   */
+  public PgConnectOptions setChannelBinding(ChannelBinding channelBinding) {
+    this.channelBinding = channelBinding;
+    return this;
+  }
+
   /**
    * @return whether the client interacts with a layer 7 proxy instead of a server
    */
@@ -342,6 +367,7 @@ public boolean equals(Object o) {
     if (pipeliningLimit != that.pipeliningLimit) return false;
     if (sslMode != that.sslMode) return false;
     if (sslNegotiation != that.sslNegotiation) return false;
+    if (channelBinding != that.channelBinding) return false;
 
     return true;
   }
@@ -352,6 +378,7 @@ public int hashCode() {
     result = 31 * result + pipeliningLimit;
     result = 31 * result + sslMode.hashCode();
     result = 31 * result + sslNegotiation.hashCode();
+    result = 31 * result + channelBinding.hashCode();
     return result;
   }
 

vertx-pg-client/src/main/java/io/vertx/pgclient/impl/PgConnectionUriParser.java

@@ -11,6 +11,7 @@
 package io.vertx.pgclient.impl;
 
 import io.vertx.core.json.JsonObject;
+import io.vertx.pgclient.ChannelBinding;
 import io.vertx.pgclient.SslMode;
 import io.vertx.pgclient.SslNegotiation;
 
@@ -183,6 +184,9 @@ private static void parseParameters(String parametersInfo, JsonObject configurat
           case "sslnegotiation":
             configuration.put("sslNegotiation", SslNegotiation.of(value));
             break;
+          case "channel_binding":
+            configuration.put("channelBinding", ChannelBinding.of(value));
+            break;
           default:
             properties.put(key, value);
             break;

vertx-pg-client/src/main/java/io/vertx/pgclient/impl/PgSocketConnection.java

@@ -19,6 +19,7 @@
 
 import io.netty.channel.ChannelPipeline;
 import io.netty.handler.codec.DecoderException;
+import io.netty.util.AttributeKey;
 import io.vertx.core.*;
 import io.vertx.core.buffer.Buffer;
 import io.vertx.core.net.ClientSSLOptions;
@@ -81,6 +82,11 @@ protected PgConnectOptions connectOptions() {
   @Override
   public void init() {
     codec = new PgCodec(useLayer7Proxy);
+
+    socket.channelHandlerContext().channel()
+        .attr(AttributeKey.valueOf("channel_binding"))
+        .set(connectOptions.getChannelBinding());
+
     ChannelPipeline pipeline = socket.channelHandlerContext().pipeline();
     pipeline.addBefore("handler", "codec", codec);
     super.init();

vertx-pg-client/src/main/java/io/vertx/pgclient/impl/auth/scram/ScramSessionImpl.java

@@ -17,27 +17,33 @@
 
 package io.vertx.pgclient.impl.auth.scram;
 
+import java.nio.charset.StandardCharsets;
+import java.security.NoSuchAlgorithmException;
+import java.security.cert.Certificate;
+import java.security.cert.CertificateEncodingException;
+import java.security.cert.X509Certificate;
+import java.util.ArrayList;
+import java.util.List;
+
+import javax.net.ssl.SSLException;
+import javax.net.ssl.SSLSession;
+
+import com.ongres.scram.client.ChannelBindingPolicy;
 import com.ongres.scram.client.ScramClient;
 import com.ongres.scram.common.StringPreparation;
 import com.ongres.scram.common.exception.ScramInvalidServerSignatureException;
 import com.ongres.scram.common.exception.ScramParseException;
 import com.ongres.scram.common.exception.ScramServerErrorException;
 import com.ongres.scram.common.util.TlsServerEndpoint;
+
 import io.netty.buffer.ByteBuf;
 import io.netty.channel.ChannelHandlerContext;
 import io.netty.handler.ssl.SslHandler;
+import io.netty.util.AttributeKey;
+import io.vertx.pgclient.ChannelBinding;
 import io.vertx.pgclient.impl.codec.ScramClientInitialMessage;
 import io.vertx.pgclient.impl.util.Util;
 
-import javax.net.ssl.SSLException;
-import javax.net.ssl.SSLSession;
-import java.nio.charset.StandardCharsets;
-import java.security.cert.Certificate;
-import java.security.cert.CertificateEncodingException;
-import java.security.cert.X509Certificate;
-import java.util.ArrayList;
-import java.util.List;
-
 public class ScramSessionImpl implements ScramSession {
 
   private final String username;
@@ -51,9 +57,10 @@ public ScramSessionImpl(String username, char[] password) {
 
   /*
    * The client selects one of the supported mechanisms from the list,
-   *  and sends a SASLInitialResponse message to the server.
+   * and sends a SASLInitialResponse message to the server.
+   *
    * The message includes the name of the selected mechanism, and
-   *  an optional Initial Client Response, if the selected mechanism uses that.
+   * an optional Initial Client Response, if the selected mechanism uses that.
    */
   public ScramClientInitialMessage createInitialSaslMessage(ByteBuf in, ChannelHandlerContext ctx) {
     List<String> mechanisms = new ArrayList<>();
@@ -63,17 +70,13 @@ public ScramClientInitialMessage createInitialSaslMessage(ByteBuf in, ChannelHan
       mechanisms.add(mechanism);
     }
 
-    if (mechanisms.isEmpty()) {
-      throw new UnsupportedOperationException("SASL Authentication : the server returned no mechanism");
-    }
-
-    byte[] channelBindingData = extractChannelBindingData(ctx);
     this.scramClient = ScramClient.builder()
         .advertisedMechanisms(mechanisms)
         .username(username) // ignored by the server, use startup message
         .password(password)
         .stringPreparation(StringPreparation.POSTGRESQL_PREPARATION)
-        .channelBinding(TlsServerEndpoint.TLS_SERVER_END_POINT, channelBindingData)
+        .channelBindingPolicy(getChannelBindingPolicy(ctx))
+        .channelBinding(TlsServerEndpoint.TLS_SERVER_END_POINT, extractChannelBindingData(ctx))
         .build();
 
     return new ScramClientInitialMessage(scramClient.clientFirstMessage().toString(),
@@ -83,10 +86,10 @@ public ScramClientInitialMessage createInitialSaslMessage(ByteBuf in, ChannelHan
   /*
    * One or more server-challenge and client-response message will follow.
    * Each server-challenge is sent in an AuthenticationSASLContinue message,
-   *   followed by a response from client in an SASLResponse message.
+   * followed by a response from client in an SASLResponse message.
    * The particulars of the messages are mechanism specific.
    */
-  public String receiveServerFirstMessage(ByteBuf in)  {
+  public String receiveServerFirstMessage(ByteBuf in) {
     String serverFirstMessage = in.readCharSequence(in.readableBytes(), StandardCharsets.UTF_8).toString();
 
     try {
@@ -100,11 +103,11 @@ public String receiveServerFirstMessage(ByteBuf in)  {
 
   /*
    * Finally, when the authentication exchange is completed successfully,
-   *   the server sends an AuthenticationSASLFinal message, followed immediately by an AuthenticationOk message.
+   * the server sends an AuthenticationSASLFinal message, followed immediately by an AuthenticationOk message.
    * The AuthenticationSASLFinal contains additional server-to-client data,
-   *   whose content is particular to the selected authentication mechanism.
+   * whose content is particular to the selected authentication mechanism.
    * If the authentication mechanism doesn't use additional data that's sent at completion,
-   *   the AuthenticationSASLFinal message is not sent
+   * the AuthenticationSASLFinal message is not sent
    */
   public void checkServerFinalMessage(ByteBuf in) {
     String serverFinalMessage = in.readCharSequence(in.readableBytes(), StandardCharsets.UTF_8).toString();
@@ -128,15 +131,32 @@ private byte[] extractChannelBindingData(ChannelHandlerContext ctx) {
             Certificate peerCert = certificates[0]; // First certificate is the peer's certificate
             if (peerCert instanceof X509Certificate) {
               X509Certificate cert = (X509Certificate) peerCert;
-              return TlsServerEndpoint.getChannelBindingData(cert);
+              return TlsServerEndpoint.getChannelBindingHash(cert);
             }
           }
-        } catch (CertificateEncodingException | SSLException e) {
-          // Cannot extract X509Certificate from SSL session
-          // handle as no channel binding available
+        } catch (CertificateEncodingException | SSLException | NoSuchAlgorithmException e) {
+          if (getChannelBindingPolicy(ctx) == ChannelBindingPolicy.REQUIRE) {
+            throw new UnsupportedOperationException(e);
+          }
         }
       }
     }
     return new byte[0]; // handle as no channel binding available
   }
+
+  private static ChannelBindingPolicy getChannelBindingPolicy(ChannelHandlerContext ctx) {
+    ChannelBinding channelBinding = (ChannelBinding) ctx.channel()
+        .attr(AttributeKey.valueOf("channel_binding"))
+        .get();
+    switch (channelBinding) {
+      case DISABLE:
+        return ChannelBindingPolicy.DISABLE;
+      case PREFER:
+        return ChannelBindingPolicy.ALLOW;
+      case REQUIRE:
+        return ChannelBindingPolicy.REQUIRE;
+      default:
+        throw new IllegalArgumentException("Invalid channel binding value");
+    }
+  }
 }

vertx-pg-client/src/test/java/io/vertx/tests/pgclient/PgConnectOptionsTest.java

@@ -11,6 +11,7 @@
 package io.vertx.tests.pgclient;
 
 import io.vertx.core.json.JsonObject;
+import io.vertx.pgclient.ChannelBinding;
 import io.vertx.pgclient.PgConnectOptions;
 import io.vertx.pgclient.SslMode;
 import io.vertx.pgclient.SslNegotiation;
@@ -167,6 +168,19 @@ public void testValidUriSslNegotiationDirect() {
     assertEquals(expectedConfiguration, actualConfiguration);
   }
 
+  @Test
+  public void testValidUriChannelBindingRequire() {
+    connectionUri = "postgresql://user@myhost?channel_binding=require";
+    actualConfiguration = PgConnectOptions.fromUri(connectionUri);
+
+    expectedConfiguration = new PgConnectOptions()
+      .setHost("myhost")
+      .setUser("user")
+      .setChannelBinding(ChannelBinding.REQUIRE);
+
+    assertEquals(expectedConfiguration, actualConfiguration);
+  }
+
   @Test
   public void testValidUri11() {
     connectionUri = "postgresql://user@myhost?application_name=myapp";