Package com.ongres.scram.client

Enum ChannelBindingPolicy

java.lang.Object
java.lang.Enum<ChannelBindingPolicy>
com.ongres.scram.client.ChannelBindingPolicy
All Implemented Interfaces:
Serializable, Comparable<ChannelBindingPolicy>
public enum ChannelBindingPolicy extends Enum<ChannelBindingPolicy>
Defines the client-side security policies for negotiating channel binding during a SCRAM authentication execution.

Channel binding protects the authentication flow against active Machine-in-the-Middle (MITM) and session hijacking attacks by cryptographically binding the outer security layer (such as TLS) to the inner SASL/SCRAM authentication layer.

This policy dictates how the ScramClient evaluates available channel binding data against the server's advertised mechanisms (e.g., SCRAM-SHA-256 vs SCRAM-SHA-256-PLUS) during the mechanism negotiation phase, ultimately determining the runtime wire-format gs2-cbind-flag ('n', 'y', or 'p').

Since:
3.3
See Also:

  • Enum Constant Details

    • DISABLE

      public static final ChannelBindingPolicy DISABLE
      Disables channel binding entirely.

      The client will strictly use standard, non-channel-bound SCRAM mechanisms (e.g., SCRAM-SHA-256), even if valid channel binding data or server-supported -PLUS mechanisms are available.

      This policy forces the internal protocol engine to output the 'n' (Client does not support channel binding) GS2 flag. Use this policy primarily for debugging, unencrypted connections, or working around proxy servers or middleboxes that strip channel data.

    • ALLOW

      public static final ChannelBindingPolicy ALLOW
      Permits channel binding if supported by the server, but allows a secure fallback if it is not.

      This is the default recommended behavior for general-purpose applications:

      • If the server advertises a -PLUS mechanism and channel binding data is provided, the negotiation upgrades to channel binding and uses the 'p' GS2 flag.
      • If the server lacks -PLUS support, the client gracefully downgrades to standard SCRAM but transmits the 'y' GS2 flag. This explicitly declares to the server that the client possesses channel binding capabilities, allowing the server to catch and terminate malicious downgrade attacks mid-flight.

    • REQUIRE

      public static final ChannelBindingPolicy REQUIRE
      Enforces strict, non-negotiable channel binding validation.

      The authentication execution will fail immediately during the client initialization phase (throwing an ChannelBindingException) if any of the following boundaries are violated:

      • The server does not explicitly advertise a channel-bound -PLUS mechanism.
      • The client was built without required channel binding type or data (e.g., missing the binding token).

      This policy forces the use of the 'p' GS2 flag and is intended for high-security environments where channel verification is a mandatory operational requirement (e.g., applications requiring strict compliance matching database configurations like PostgreSQL's channel_binding=require).

  • Constructor Details

    • ChannelBindingPolicy

      private ChannelBindingPolicy()

  • Method Details

    • values

      public static ChannelBindingPolicy[] values()
      Returns an array containing the constants of this enum type, in the order they are declared.
      Returns:
      an array containing the constants of this enum type, in the order they are declared

    • valueOf

      public static ChannelBindingPolicy valueOf(String name)
      Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum type has no constant with the specified name
      NullPointerException - if the argument is null