SCRAM-SHA-256-PLUS (Channel Binding): Design Plan

[SeanTAllen]

Design: discussion #72, item #25

Overview

SCRAM-SHA-256-PLUS ties SCRAM authentication to the TLS session by embedding the server's certificate hash into the SCRAM proof. This prevents credential relay attacks where an attacker terminates TLS and forwards the SCRAM exchange to the real server over a different TLS connection.

Change type: Added (new feature). PR label: changelog - added.

Scope

In scope: SCRAM-SHA-256-PLUS with tls-server-end-point channel binding. GS2 y,, downgrade detection. User-configurable channel binding policy.

Out of scope: tls-unique (deprecated in TLS 1.3, not supported by PostgreSQL), tls-exporter (TLS 1.3+ only, not supported by PostgreSQL as of v17), SASLprep normalization (same assumption as existing SCRAM).

Protocol Changes

SCRAM-SHA-256-PLUS differs from SCRAM-SHA-256 in three ways:

1. Mechanism name: SCRAM-SHA-256-PLUS instead of SCRAM-SHA-256
2. GS2 header: p=tls-server-end-point,, instead of n,,
3. Channel binding data in c= field: base64("p=tls-server-end-point,," + cert_hash_bytes) instead of biws (which is base64("n,,"))

The GS2 flag has three states:

• n,, — client does not support channel binding (plaintext connection, or channel binding disabled)
• y,, — client supports channel binding but is not using it (TLS active, server doesn't offer PLUS, or cert extraction failed). Enables server-side downgrade detection per RFC 5802 Section 6.
• p=tls-server-end-point,, — client is using channel binding

The crypto (PBKDF2, HMAC, proof computation) is identical. Only the AuthMessage changes because the c= field contains different data, producing a different proof.

Channel Binding Data Computation (RFC 5929 Section 4.1)

The tls-server-end-point channel binding value is the hash of the server's DER-encoded certificate. The hash algorithm is determined by the certificate's signature algorithm:

• If the cert's signature uses MD5 or SHA-1: use SHA-256
• Otherwise: use the cert's own signature hash algorithm

This matches libpq's pgtls_get_peer_certificate_hash() implementation, which uses X509_get_signature_nid + OBJ_find_sigid_algs to determine the hash, then X509_digest to compute it.

Mechanism Selection

Given the client's TLS state, channel binding policy, and server's mechanism list:

TLS active	CB data available	Server offers PLUS	Server offers base	ChannelBinding	Result
no	no	*	yes	Prefer	SCRAM-SHA-256 with n,,
no	no	*	yes	Disable	SCRAM-SHA-256 with n,,
no	no	*	*	Require	Fail: ChannelBindingRequired
yes	yes	yes	*	Prefer	SCRAM-SHA-256-PLUS with p=tls-server-end-point,,
yes	yes	no	yes	Prefer	SCRAM-SHA-256 with y,,
yes	yes	yes	*	Require	SCRAM-SHA-256-PLUS with p=tls-server-end-point,,
yes	yes	no	*	Require	Fail: ChannelBindingRequired
yes	yes	*	*	Disable	SCRAM-SHA-256 with n,,
yes	no	*	yes	Prefer	SCRAM-SHA-256 with y,,
yes	no	*	*	Require	Fail: ChannelBindingRequired
yes	no	*	*	Disable	SCRAM-SHA-256 with n,,
*	*	—	—	*	Fail: UnsupportedAuthenticationMethod (no supported mechanism)

"CB data available" can be false even on TLS if certificate extraction fails (e.g., server sends no certificate, which shouldn't happen with PostgreSQL but is defensively handled).

Three-Phase Dependency Chain

Phase 1: ponylang/ssl — Add channel binding data extraction

New method on SSL in ssl/net/ssl.pony:

fun ref tls_server_end_point_channel_binding(): (Array[U8] val | None)

Returns the tls-server-end-point channel binding value (hash of server cert DER), or None if no peer certificate is available.

Implementation:

1. Call SSL_get_peer_certificate / SSL_get1_peer_certificate (already FFI-declared, platform-branched) to get the server cert
2. Call X509_get_signature_nid(cert) to get the signature algorithm NID
3. Call OBJ_find_sigid_algs(sig_nid, &hash_nid, NULL) to extract the hash algorithm NID
4. If hash NID is MD5 (NID_md5 = 4) or SHA-1 (NID_sha1 = 64), replace with SHA-256 (NID_sha256 = 672) per RFC 5929
5. Call EVP_get_digestbynid(hash_nid) to get the digest method
6. Allocate a 64-byte buffer (max digest size) and call X509_digest(cert, md, buf, &len) to compute the hash
7. Free the certificate with X509_free (already declared)
8. Return the hash bytes as Array[U8] val, truncated to actual length

New FFI declarations:

use @X509_get_signature_nid[I32](cert: Pointer[X509])
use @OBJ_find_sigid_algs[I32](sig_nid: I32, hash_nid: Pointer[I32],
  enc_nid: Pointer[None])
use @EVP_get_digestbynid[Pointer[None]](nid: I32)
use @X509_digest[I32](cert: Pointer[X509], md: Pointer[None],
  buf: Pointer[U8], len: Pointer[U32])

Design rationale: Encapsulating the full RFC 5929 computation (cert extraction + algorithm selection + hashing) at the SSL level keeps all OpenSSL FFI in one package and prevents consumers from needing to know about hash algorithm selection. This is safer than exposing raw peer_certificate_der() which would push the algorithm-selection responsibility to each consumer.

Testing: Unit test with a client-server TLS pair using the existing test cert/key infrastructure. Verify the method returns a non-None value of the expected length (32 bytes for SHA-256-signed certs). Verify against a manually computed expected hash.

Phase 2: ponylang/lori — Expose channel binding from TCPConnection

New method on TCPConnection in lori/tcp_connection.pony:

fun ref tls_server_end_point_channel_binding(): (Array[U8] val | None) =>
  match _ssl
  | let ssl: SSL ref =>
    ssl.tls_server_end_point_channel_binding()
  else
    None
  end

Returns None for plaintext connections. Delegates to SSL for TLS connections. Only meaningful after TLS handshake completes — before then, SSL_get_peer_certificate returns null, so the method naturally returns None.

Testing: Verify None for plaintext connections, non-None for post-handshake TLS connections.

Phase 3: ponylang/postgres — Implement SCRAM-SHA-256-PLUS

Step 3a: New public types

postgres/channel_binding.pony — new file:

primitive ChannelBindingPrefer
  """
  Use channel binding when available. Selects SCRAM-SHA-256-PLUS over
  SCRAM-SHA-256 when the connection is TLS and the server offers the PLUS
  mechanism. Falls back to SCRAM-SHA-256 with 'y,,' GS2 header for downgrade
  detection when channel binding is not possible. This is the default.
  """

primitive ChannelBindingRequire
  """
  Require channel binding. Authentication fails with `ChannelBindingRequired`
  if the connection is not using TLS, the server certificate is unavailable,
  or the server does not offer SCRAM-SHA-256-PLUS.
  """

primitive ChannelBindingDisable
  """
  Never use channel binding. Always selects SCRAM-SHA-256 with the 'n,,' GS2
  header, even when the PLUS mechanism is available.
  """

type ChannelBinding is
  (ChannelBindingPrefer | ChannelBindingRequire | ChannelBindingDisable)

Modified ServerConnectInfo — add channel_binding field defaulting to ChannelBindingPrefer:

class val ServerConnectInfo
  // ... existing fields ...
  let channel_binding: ChannelBinding

  new val create(auth': lori.TCPConnectAuth, host': String, service': String,
    ssl_mode': SSLMode = SSLDisabled,
    connection_timeout': (lori.ConnectionTimeout | None) = None,
    channel_binding': ChannelBinding = ChannelBindingPrefer)
  =>
    // ...
    channel_binding = channel_binding'

New error variant in AuthenticationFailureReason:

primitive ChannelBindingRequired
  """
  Channel binding was required but could not be performed. Either the
  connection is not using TLS, the server certificate was unavailable,
  or the server did not offer SCRAM-SHA-256-PLUS.
  """

Step 3b: Parameterize _ScramSha256

Replace hardcoded "n,," and "biws" with parameters. Add methods:

• gs2_header(channel_binding_data: (Array[U8] val | None), server_offers_plus: Bool, channel_binding: ChannelBinding): String — returns the GS2 header string based on the decision matrix
• channel_binding_response(gs2_header: String, channel_binding_data: (Array[U8] val | None)): String — returns the base64-encoded c= value: base64(gs2_header + channel_binding_bytes) for PLUS, or base64(gs2_header) for non-PLUS
• Modify client_first_message(nonce, gs2_header) to accept the GS2 header
• Modify client_final_message_without_proof(combined_nonce, channel_binding_response) to accept the channel binding response
• Modify compute_proof(...) to accept the channel binding response and use it in the AuthMessage

The existing non-PLUS behavior is preserved when gs2_header = "n,," and channel_binding_response = "biws".

Step 3c: Thread ChannelBinding and _tls_active through the state machine

Thread the ChannelBinding preference through existing states the same way codec_registry is threaded:

_SessionUnopened → _SessionSSLNegotiating/_SessionConnected → _AuthenticableState → _SessionSCRAMAuthenticating

Add _channel_binding: ChannelBinding field to _SessionUnopened, _SessionSSLNegotiating, and _SessionConnected. The _ConnectableState trait gets a channel_binding() accessor.

Add _tls_active: Bool field to _SessionConnected to track whether TLS actually completed. This is needed because cb_data being None on a TLS connection (cert extraction failed) is different from cb_data being None on a plaintext connection — the former requires y,, GS2 header for downgrade detection, the latter uses n,,. Set as follows:

• _ConnectableState.on_connected() with SSLDisabled: _tls_active = false
• _SessionSSLNegotiating.on_tls_ready() → _proceed_to_connected(s, true): _tls_active = true
• _SessionSSLNegotiating plaintext fallback (SSLPreferred, server refused) → _proceed_to_connected(s, false): _tls_active = false

_proceed_to_connected gains a tls_active: Bool parameter to distinguish the two call paths. Currently both paths call the same method with identical arguments — the new parameter lets _SessionConnected know whether TLS actually completed.

The _AuthenticableState trait gets a tls_active() accessor.

Step 3d: Extract channel binding data on-demand

In _AuthenticableState.on_authentication_sasl(), extract channel binding data by calling s._connection().tls_server_end_point_channel_binding(). This works because:

• s._connection() is already accessible in this method (used at line 3050)
• The TLS handshake is complete by the time SASL auth is requested
• No new fields needed on intermediate states for the binding data itself

If the call returns None on a TLS connection (cert extraction failed), treat it as "TLS active but no CB data" — use y,, for Prefer, fail for Require.

Step 3e: Mechanism selection in on_authentication_sasl()

Replace the current simple "SCRAM-SHA-256" mechanism check with the full decision matrix from the table above.

Call sites that need parameterization:

1. _FrontendMessage.sasl_initial_response("SCRAM-SHA-256", response) at session.pony line 3050-3051 — mechanism string must be "SCRAM-SHA-256-PLUS" or "SCRAM-SHA-256" based on selection
2. _ScramSha256.client_first_message(nonce) — must accept the GS2 header parameter
3. _SessionSCRAMAuthenticating constructor (session.pony line 654) — must accept the channel binding response string

Note: client_first_message_bare (n=,r=<nonce>) does NOT change between PLUS and non-PLUS — only the GS2 header prefix that wraps it changes. The bare part is always n=,r=<nonce> per RFC 5802.

The selection logic:

cb_data = s._connection().tls_server_end_point_channel_binding()
is_tls = tls_active()
plus_offered = mechanisms contains "SCRAM-SHA-256-PLUS"
base_offered = mechanisms contains "SCRAM-SHA-256"

match channel_binding()
| ChannelBindingRequire =>
  if (cb_data isnt None) and plus_offered then
    use PLUS with "p=tls-server-end-point,,"
  else
    fail with ChannelBindingRequired
  end
| ChannelBindingPrefer =>
  if (cb_data isnt None) and plus_offered then
    use PLUS with "p=tls-server-end-point,,"
  elseif base_offered then
    if is_tls then use base with "y,," else use base with "n,," end
  else
    fail with UnsupportedAuthenticationMethod
  end
| ChannelBindingDisable =>
  if base_offered then
    use base with "n,,"
  else
    fail with UnsupportedAuthenticationMethod
  end
end

Note on SSLPreferred + ChannelBindingRequire: if the server refuses SSL and the connection falls back to plaintext, tls_active is false and cb_data is None, so SASL auth will correctly fail with ChannelBindingRequired. This is expected behavior — the user asked for both "try SSL" and "require channel binding", and the latter can't be satisfied without TLS.

Step 3f: Update _SessionSCRAMAuthenticating

Add constructor parameter and field:

• _channel_binding_response: String — precomputed base64 value for the c= field, passed from on_authentication_sasl() at construction time

Current constructor (line 654) takes client_nonce, client_first_bare, password, codec_registry. Add channel_binding_response parameter.

In on_authentication_sasl_continue(), pass _channel_binding_response to compute_proof() and client_final_message_without_proof() instead of hardcoded "biws".

Step 3g: _CancelSender — no changes needed

Cancel protocol sends a CancelRequest message, not SASL authentication. The cancel connection may use TLS but never authenticates.

Testing

Unit tests (no PostgreSQL needed)

GS2 header generation (_test_scram.pony):

• n,, when no CB data (plaintext)
• y,, when TLS active + CB data available + server doesn't offer PLUS
• y,, when TLS active + CB data unavailable (cert extraction failed)
• p=tls-server-end-point,, when TLS active + CB data available + server offers PLUS
• n,, when TLS active + ChannelBindingDisable

Channel binding response:

• biws = base64("n,,") for no binding
• eSws = base64("y,,") for downgrade detection
• Correct base64 of "p=tls-server-end-point,," + cert_hash_bytes for PLUS

Proof computation with channel binding:

• Use known inputs (password, nonces, salt, iterations, CB data) and verify proof differs from non-PLUS case
• Verify AuthMessage contains the channel binding response, not biws

Mechanism selection decision matrix:

• Test all rows of the mechanism selection table as a pure function
• Counterfactual: for y,, cases, break assertion to verify downgrade detection is actually tested

Channel binding data computation (property-based):

• For random byte arrays of length 32, verify channel_binding_response("p=tls-server-end-point,,", data) base64-decodes to "p=tls-server-end-point,," + data
• Verify different CB data always produces different response values

All new test classes use \nodoc\ on declarations per project convention.

Mock server protocol tests (ports 7724-7730, next available above current max 7723)

All mock server tests must explicitly close/dispose TCP listeners and connections to avoid CI timeouts (Pony runtime won't exit while actors with live I/O resources exist).

_TestSCRAMPLUSSuccess (port 7724): Mock SCRAM-PLUS handshake with injected CB data. Mock server offers both mechanisms, verifies client selects PLUS and sends correct GS2 header + channel binding response.

_TestSCRAMPLUSDowngradeYFlag (port 7725): Mock server offers only SCRAM-SHA-256 (not PLUS). Plaintext connection. Verify client uses n,, (no TLS, so no downgrade flag).

_TestSCRAMPLUSServerVerificationFailed (port 7726): PLUS handshake where mock sends wrong server signature. Verify pg_session_authentication_failed with ServerVerificationFailed.

_TestSCRAMPLUSOnlyNoCBData (port 7727): Mock offers only PLUS, client has no CB data. Verify pg_session_authentication_failed with UnsupportedAuthenticationMethod.

_TestSCRAMPLUSRequireFails (port 7728): Mock offers only base SCRAM, client has CB data + ChannelBindingRequire. Verify ChannelBindingRequired.

_TestSCRAMPLUSTLSFullStack (port 7729): TLS mock server (using test cert/key) + SCRAM-PLUS exchange. Validates the full pipeline: TLS handshake → cert extraction → hash computation → SCRAM-PLUS proof. This is the single most important test — it exercises the entire dependency chain.

Integration tests (against real PostgreSQL containers)

_TestSSLSCRAMPLUSAuthenticate: Connect to SSL container (port 5433) with SSLRequired + ChannelBindingPrefer. Verify authentication succeeds. PostgreSQL 14.5 automatically offers PLUS over SSL with scram-sha-256 auth.

_TestSSLSCRAMPLUSQuery: Connect with channel binding, execute query, verify results.

_TestSSLSCRAMPLUSRequired: Connect with ChannelBindingRequire over SSL. Verify success.

_TestSCRAMPLUSRequireNoSSL: Connect to plain container (port 5432) with ChannelBindingRequire. Verify ChannelBindingRequired failure.

_TestSCRAMPLUSDisableOverSSL: Connect to SSL container with ChannelBindingDisable. Verify authentication still succeeds (uses plain SCRAM-SHA-256).

Build and run:

make unit-tests ssl=3.0.x                              # unit tests
make test-one t=TestSCRAMPLUSSuccess ssl=3.0.x         # single test
make start-pg-containers && make integration-tests ssl=3.0.x  # integration

CI infrastructure

No container changes needed. PostgreSQL 14.5 with scram-sha-256 auth automatically offers SCRAM-SHA-256-PLUS on SSL connections. Empirical verification needed (Phase 0 below).

Documentation updates

• CLAUDE.md: Add ChannelBinding to public API types, add ChannelBindingRequired to AuthenticationFailureReason union, update authentication section to include SCRAM-SHA-256-PLUS, update state machine to document channel binding data flow
• Package docstring in postgres.pony: Add channel binding to supported features
• Update ssl-query example to show ChannelBindingRequire usage
• Update examples/README.md
• Release notes file

Implementation Phases

Phase 0: Empirical verification (before any code)

1. Start SSL containers, add debug print to on_authentication_sasl() to confirm PostgreSQL 14.5 advertises SCRAM-SHA-256-PLUS over SSL
2. Verify SSL_get_peer_certificate returns non-null cert even with set_client_verify(false) (existing test containers don't verify client certs)

Phase 1: ponylang/ssl PR

• Add tls_server_end_point_channel_binding() to SSL
• New FFI declarations (X509_get_signature_nid, OBJ_find_sigid_algs, EVP_get_digestbynid, X509_digest)
• Unit tests
• Verify FFI works on OpenSSL 3.0.x, 1.1.x, and LibreSSL

Phase 2: ponylang/lori PR

• Add tls_server_end_point_channel_binding() to TCPConnection
• Unit tests

Phase 3: ponylang/postgres PR

• Update corral.json dependencies, make clean
• Add ChannelBinding types, ChannelBindingRequired error variant
• Add channel_binding to ServerConnectInfo
• Parameterize _ScramSha256, implement mechanism selection
• Thread ChannelBinding and _tls_active through state machine
• All unit, mock, and integration tests
• CLAUDE.md, docstring, example, and release notes updates

Design Decisions

Decision 1: Channel binding type — tls-server-end-point only

Choice: Support only tls-server-end-point.
Alternatives: tls-unique (deprecated in TLS 1.3), tls-exporter (TLS 1.3+ only, not supported by PostgreSQL).
Confidence: High. PostgreSQL exclusively uses tls-server-end-point for SCRAM-SHA-256-PLUS.

Decision 2: Hash algorithm — RFC 5929 compliant, not hardcoded SHA-256

Choice: Use the certificate's signature hash algorithm with SHA-256 as floor (MD5/SHA-1 → SHA-256).
Alternatives: Always SHA-256 (simpler, covers 99%+ of certs).
Confidence: High. This matches libpq's pgtls_get_peer_certificate_hash() and is the RFC-correct behavior. The complexity is encapsulated in the ssl package.

Decision 3: SSL package API — specific tls_server_end_point_channel_binding(), not general peer_certificate_der()

Choice: Return the computed hash, not raw DER bytes.
Alternatives: peer_certificate_der() — more general, lets caller choose hash.
Confidence: High. Encapsulates RFC 5929 algorithm selection. Prevents consumers from using the wrong hash. A general cert API can be added later if needed.

Decision 4: Public API — ChannelBinding type on ServerConnectInfo

Choice: Three primitives (ChannelBindingPrefer/Require/Disable) on ServerConnectInfo, defaulting to ChannelBindingPrefer.
Alternatives: (a) No public API, always automatic. (b) On SSLMode variants.
Confidence: High. Require is essential for security-conscious deployments. Disable is essential for pgbouncer/proxy users. These map to libpq's channel_binding parameter. Orthogonal to SSLMode (transport vs auth concern). Default of Prefer is secure-by-default without breaking existing code.

Decision 5: Channel binding data extraction — on-demand in on_authentication_sasl()

Choice: Call s._connection().tls_server_end_point_channel_binding() at SASL auth time.
Alternatives: Extract in _SessionSSLNegotiating.on_tls_ready() and thread through intermediate states.
Confidence: High. Simpler — avoids adding fields to intermediate states. The connection is accessible and TLS handshake is complete by auth time.

Decision 6: Parameterize _ScramSha256 rather than duplicate

Choice: Add parameters to existing methods for GS2 header and channel binding data.
Alternatives: Separate _ScramSha256Plus primitive.
Confidence: High. The crypto is identical between PLUS and non-PLUS. Only the GS2 header and c= value differ.

Decision 7: _CancelSender — no changes

Choice: No modifications to _CancelSender.
Confidence: High. Cancel protocol uses CancelRequest, not SASL authentication.

Decision 8: Duplicate @SHA256 FFI in ssl/net rather than cross-package import

Choice: If @SHA256 is needed directly in ssl/net, declare it there rather than importing ssl/crypto.
Alternatives: use "../crypto" cross-package import.
Confidence: High. No existing file in the ssl library uses cross-package imports. With the X509_digest approach, this may not even be needed (the digest is computed by OpenSSL internally).

Open Questions

1. Upstream API shape: Is SSL.tls_server_end_point_channel_binding() the right method name and return type for ponylang/ssl?

2. LibreSSL FFI compatibility: X509_get_signature_nid, OBJ_find_sigid_algs, EVP_get_digestbynid, X509_digest need verification across OpenSSL 1.1.x, 3.0.x, and LibreSSL. LibreSSL sometimes diverges on less common APIs.

3. AuthenticationFailureReason expansion: Adding ChannelBindingRequired to this union type is technically a breaking change for exhaustive matches in user code. Is this acceptable, or should it be a separate error path?

4. Phase 0 empirical verification: We assume PostgreSQL 14.5 advertises SCRAM-SHA-256-PLUS on SSL connections and that SSL_get_peer_certificate works with set_client_verify(false). Both are highly likely but need verification.

5. i2d_X509 FFI pointer semantics in Pony: If the X509_digest approach requires intermediate steps, the i2d_X509 two-call pattern (first for length, second to write) requires addressof on a local Pointer[U8] variable. This FFI pattern needs empirical verification. However, X509_digest may avoid this entirely by computing the hash internally.