Add openssl_get_channel_binding by Sjord · Pull Request #24035 · php/php-src

Sjord · 2026-10-01T07:14:56Z

Related to #16766

The branch adds a new function to the openssl extension:

openssl_get_channel_binding(
    resource $stream,
    Openssl\ChannelBindingType $channel_binding_type
): ?string

The binding type is selected with a string-backed enum:

namespace Openssl {
    enum ChannelBindingType: string {
        case TlsUnique = 'tls-unique';
        case TlsServerEndPoint = 'tls-server-end-point';
        case TlsExporter = 'tls-exporter';
    }
}

It extracts TLS channel binding data from an established tls:// socket stream. This unblocks SASL channel binding (SCRAM-SHA-*-PLUS per RFC 5802 and RFC 5801) for clients written in PHP, which previously had no way to obtain the binding material that those mechanisms require.

The enum case values are the names from the IANA "Channel Binding" registry. The tls-unique selection semantics follow CPython's _ssl.get_channel_binding(); this proposal additionally supports the other two TLS channel binding types.

Parameter	Type	Description
`stream`	`resource`	An open stream using an openssl transport (`ssl://` / `tls://`). Must be in the connected/active state.
`channel_binding_type`	`Openssl\ChannelBindingType`	One of `TlsUnique`, `TlsServerEndPoint`, or `TlsExporter`. A string such as `"tls-unique"` is not accepted.

Return value

On success, the channel binding data as a binary string.
null when the requested type is not applicable to the connection
(currently: TlsUnique over TLS 1.3, where the type is not defined).

Errors / exceptions

Condition	Exception
`channel_binding_type` is not an `Openssl\ChannelBindingType`	`TypeError`
`stream` is not a stream resource	`TypeError`
`stream` is a stream but has no active TLS transport	`Openssl\OpensslException` — `"Stream does not have transport encryption enabled"`
An OpenSSL call fails while computing the value	`Openssl\OpensslException` — `"Failed to get channel binding data: <OpenSSL error>"`

Code that stores the binding type as a string can map it with Openssl\ChannelBindingType::from($name), which raises ValueError for an unknown name. The enum backing values, like the IANA names, are case-sensitive.

Supported channel binding types

Enum case	Standard	Value	Length	TLS applicability
`TlsUnique` (`tls-unique`)	RFC 5929 §3	The TLS Finished message content (the "tls-unique" channel binding)	length of the Finished message	TLS 1.2 and earlier only; not applicable over TLS 1.3 → returns `null`
`TlsServerEndPoint` (`tls-server-end-point`)	RFC 5929 §4.1	Digest of the server certificate (DER encoding)	size of the chosen digest (32 for SHA-256-signed certs)	All versions where the peer presents a certificate
`TlsExporter` (`tls-exporter`)	RFC 9266 §4 / RFC 5705	32 octets derived from the TLS exporter with label `EXPORTER-Channel-Binding` and an empty context	32	Primarily TLS 1.3 (exporter is defined there); also computed on earlier versions where the exporter is available

Notes on semantics

tls-unique selection. In a full handshake both endpoints transmit a
Finished message; in a resumed handshake only the server does. The
implementation picks between the local SSL_get_finished() and
SSL_get_peer_finished() using is_client ^ SSL_session_reused(), so that the
client and the server always derive the same value. This mirrors the
selection made by CPython's _ssl.get_channel_binding().
tls-server-end-point digest choice. The digest algorithm is taken from
the certificate's own signature algorithm. If that algorithm is MD5 or SHA-1,
or cannot be determined, SHA-256 is used instead (as mandated by
RFC 5929 §4.1). For a SHA-256-signed certificate the result equals
openssl_x509_fingerprint($cert, "sha256", true). On the client side the peer
certificate is used; on the server side the local certificate is used.
tls-exporter. Computed with SSL_export_keying_material() using a 32
octet output, the label EXPORTER-Channel-Binding and an empty context
(RFC 9266 §4 / RFC 5705).

Example

Obtaining a binding on a connected client and using it as the SASL
cb property for a SCRAM-SHA-256-PLUS negotiation:

$ctx = stream_context_create([
    'ssl' => [
        'verify_peer' => true,
    ],
]);
$client = stream_socket_client(
    'tls://example.com:465', $errno, $errstr, 30,
    STREAM_CLIENT_CONNECT, $ctx
);

$cb = openssl_get_channel_binding(
    $client,
    Openssl\ChannelBindingType::TlsUnique,
);
if ($cb === null) {
    // tls-unique is not defined for TLS 1.3; use tls-exporter instead.
    $cb = openssl_get_channel_binding(
        $client,
        Openssl\ChannelBindingType::TlsExporter,
    );
}

// $cb is the raw binding data; base64-encode it for the SCRAM "cb" property.
$scramCb = base64_encode($cb);

Related to php#16766

Neustradamus · 2026-10-02T01:55:07Z

@Sjord: Thanks a lot for your work about Channel Binding!

It will be not possible to backport to previous PHP versions too?

TimWolla · 2026-10-02T08:05:18Z

The branch adds a new function to the openssl extension:

and

stream_get_channel_binding(resource $stream, string $channel_binding_type): ?string

If it's part of OpenSSL, it must have an openssl_ prefix or sit in the Openssl namespace.

Sjord · 2026-10-06T13:22:53Z

I tested this against Prosody and Postgres, which gave me some confidence that this works at least in some situations.

Sjord · 2026-10-14T07:40:08Z

@iluuu1994 Could you take a look at this?

Is it OK to keep the strings ("tls-unique", "tls-server-end-point", "tls-exporter") or do these need to become enums or constants?

Sjord · 2026-10-14T11:42:40Z

Thanks for reviewing, @TimWolla

Neustradamus · 2026-10-24T14:29:36Z

After the merging in master branch, it will be nice to backport it in other PHP branches starting 8.2.x.

The goal is to have a better security with PHP...

Several developers can not test it because it is not for PHP 8.2... :/

iluuu1994 · 2026-10-24T22:47:56Z

New features don't get backported to stable branches, especially not the ones in security-maintenance. Otherwise, what's the point of having different branches at all?

Neustradamus · 2026-10-25T00:48:47Z

@iluuu1994: But this PR adds an important security feature...

It will be nice to add in previous branches to have more security...

Neustradamus · 2026-10-26T18:34:51Z

@LamentXU123, @shivammathur, @ndossche: What do you think?

Security is very important and this feature is needed by a lot of people and projects.

Thanks in advance.

iluuu1994 · 2026-10-26T18:40:54Z

This is disallowed according to our policy.

https://github.com/php/policies/blob/main/release-process.rst

Patch Version Number

New features MUST NOT be added.

Neustradamus · 2026-10-26T18:50:50Z

So PHP 8.6.0 has not been released yet, it can be added into?

iluuu1994 · 2026-10-26T18:51:54Z

No, because 8.6 has reached feature freeze. Anything that conflicts with our policy would need some RFC to overrule the policy.

TimWolla · 2026-10-26T18:58:44Z

this feature is needed by a lot of people and projects.

[citation needed]

Neustradamus · 2026-10-26T21:13:40Z

@TimWolla: A lot of projects have been linked here previously ^

Movim XMPP Social Network (creator @edhelas) can be added too:

https://github.com/movim/movim

There is this biggest ticket too:

State of Play scram-sasl/info#1

TimWolla · 2026-10-26T21:25:26Z

A lot of projects have been linked here previously ^

I do not see how the links support that claim. A barely two-digit number of projects is not “a lot”.

And if this feature was actually so important that it is needed right now, I wonder why no one, including yourself, bothered to implement it in the past 7 years (or whenever the first issue was created).

Neustradamus · 2026-10-26T21:43:18Z

@TimWolla: @fabiang has added the support in the SASL PHP Library linked to this 24035 PHP PR, more details here:

More details about PHP softwares/projects here:

Add support for SCRAM-SHA-*-PLUS channel binding in PHP streams (e.g., tls-unique, tls-exporter) #16766
Add support for SCRAM-SHA-*-PLUS channel binding in PHP streams (e.g., tls-unique, tls-exporter) #16766 (comment)

2025-02-03: About PHP, SCRAM has been added in, people wait for -PLUS variants:

PEAR Auth_SASL/Auth_SASL2/Net_SMTP (used by a lot of projects like Roundcube etc.)
SnappyMail
SquirelMail
Horde

For example, some tickets about it:

Sjord · 2026-10-27T09:42:17Z

I changed the channel_binding_type to a enum. I also wrote an RFC: PHP RFC: openssl_get_channel_binding()

TimWolla · 2026-10-28T14:21:01Z

+			return PHP_OPENSSL_CHANNEL_BINDING_RESULT_ERROR;
+		}
+		*out = zend_string_init((char *)buf, 32, 0);
+		return *out != NULL ? PHP_OPENSSL_CHANNEL_BINDING_RESULT_OK : PHP_OPENSSL_CHANNEL_BINDING_RESULT_ERROR;


zend_string_init() guarantees a non-NULL return (only zend_string_finit() can fail).

TimWolla · 2026-10-28T14:21:08Z

+				(const unsigned char *)"", 0, 1) != 1) {
+			return PHP_OPENSSL_CHANNEL_BINDING_RESULT_ERROR;
+		}
+		*out = zend_string_init((char *)buf, 32, 0);


Suggested change

*out = zend_string_init((char *)buf, 32, 0);

*out = zend_string_init((char *)buf, 32, false);

TimWolla · 2026-10-28T14:21:36Z

+	unsigned char buf[EVP_MAX_MD_SIZE];
+	size_t len = 0;
+	php_openssl_netstream_data_t *sslsock;
+	SSL *ssl;


Move down declarations as far as possible (applies everywhere).

TimWolla · 2026-10-28T14:21:47Z

+ * stream PHP_OPENSSL_CHANNEL_BINDING_RESULT_NOT_TLS is returned, and if an OpenSSL call fails
+ * PHP_OPENSSL_CHANNEL_BINDING_RESULT_ERROR is returned; in both of these cases *out is set to NULL.
+ */
+php_openssl_channel_binding_result php_openssl_netstream_get_channel_binding( /* {{{ */


Suggested change

php_openssl_channel_binding_result php_openssl_netstream_get_channel_binding( /* {{{ */

php_openssl_channel_binding_result php_openssl_netstream_get_channel_binding(

These are not used in new code.

TimWolla · 2026-10-28T14:22:03Z

+		return *out != NULL ? PHP_OPENSSL_CHANNEL_BINDING_RESULT_OK : PHP_OPENSSL_CHANNEL_BINDING_RESULT_ERROR;
+
+	default:
+		return PHP_OPENSSL_CHANNEL_BINDING_RESULT_ERROR;


ZEND_UNREACHABLE()

Instead of returning null.

Add stream_get_channel_binding

5d63d1d

Related to php#16766

github-actions Bot added the Extension: openssl label Oct 1, 2026

Sjord mentioned this pull request Oct 1, 2026

Add support for SCRAM-SHA-*-PLUS channel binding in PHP streams (e.g., tls-unique, tls-exporter) #16766

Open

Sjord commented Oct 1, 2026

View reviewed changes

Comment thread ext/openssl/tests/stream_get_channel_binding_errors.phpt Resolved

Comment thread ext/openssl/xp_ssl.c Resolved

Sjord added 3 commits October 1, 2026 08:18

Use tls-server-end-point instead of tls-server-endpoint

9291795

Remove parameter list switch for X509_get_signature_info

30820f9

Add stream_get_channel_binding to zend optimizer

da5405b

github-actions Bot added the Category: Optimizer label Oct 1, 2026

Sjord added 2 commits October 1, 2026 09:46

Fix stream_get_channel_binding stub

fb8217b

Fix arginfo

e932f54

This was referenced Oct 2, 2026

RFC 9266: Channel Bindings for TLS 1.3 support fabiang/sasl#11

Open

State of Play scram-sasl/info#1

Open

This was referenced Oct 2, 2026

SCRAM-SHA-1(-PLUS) + SCRAM-SHA-256(-PLUS) + SCRAM-SHA-512(-PLUS) supports roundcube/roundcubemail#6917

Open

SCRAM-SHA-1(-PLUS) + SCRAM-SHA-256(-PLUS) supports cypht-org/cypht#354

Open

Rename to openssl_get_channel_binding

f57f3e2

Sjord changed the title ~~Add stream_get_channel_binding~~ Add openssl_get_channel_binding Oct 5, 2026

Move PHP function to openssl.c, don't throw SPL exceptions

8bd3d4c

Sjord marked this pull request as ready for review October 7, 2026 07:19

Sjord requested review from bukka, dstogov and kocsismate as code owners October 7, 2026 07:19

TimWolla reviewed Oct 14, 2026

View reviewed changes

Comment thread ext/openssl/xp_ssl.c Resolved

Comment thread ext/openssl/php_openssl.h Resolved

Comment thread ext/openssl/openssl.c Resolved

Comment thread ext/openssl/xp_ssl.c Resolved

Comment thread ext/openssl/openssl.c Resolved

Consistently use enum's as type, correctly name values

93f0e0a

TimWolla reviewed Oct 14, 2026

View reviewed changes

Comment thread ext/openssl/php_openssl.h Resolved

Comment thread ext/openssl/php_openssl.h Resolved

Remove reserved _t suffix

28e5556

Neustradamus mentioned this pull request Oct 24, 2026

SCRAM-SHA-***(-PLUS) supports fabiang/sasl#4

Open

Use enum instead of string for channel type

7d1e8b5

TimWolla reviewed Oct 28, 2026

View reviewed changes

Sjord force-pushed the stream_get_channel_binding branch from da9073f to 035b582 Compare October 30, 2026 12:35

Throw exception when channel binding is not supported

81098e1

Instead of returning null.

Sjord force-pushed the stream_get_channel_binding branch from 035b582 to 81098e1 Compare October 30, 2026 13:32

	out = zend_string_init((char )buf, 32, 0);
	out = zend_string_init((char )buf, 32, false);

	php_openssl_channel_binding_result php_openssl_netstream_get_channel_binding( /* {{{ */
	php_openssl_channel_binding_result php_openssl_netstream_get_channel_binding(

Conversation

Sjord commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Return value

Errors / exceptions

Supported channel binding types

Notes on semantics

Example

Uh oh!

Uh oh!

Uh oh!

Neustradamus commented Oct 2, 2026

Uh oh!

TimWolla commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Sjord commented Oct 6, 2026

Uh oh!

Sjord commented Oct 14, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Sjord commented Oct 14, 2026

Uh oh!

Neustradamus commented Oct 24, 2026

Uh oh!

iluuu1994 commented Oct 24, 2026

Uh oh!

Neustradamus commented Oct 25, 2026

Uh oh!

Neustradamus commented Oct 26, 2026

Uh oh!

iluuu1994 commented Oct 26, 2026

Uh oh!

Neustradamus commented Oct 26, 2026

Uh oh!

iluuu1994 commented Oct 26, 2026

Uh oh!

TimWolla commented Oct 26, 2026

Uh oh!

Neustradamus commented Oct 26, 2026

Uh oh!

TimWolla commented Oct 26, 2026

Uh oh!

Neustradamus commented Oct 26, 2026

Uh oh!

Sjord commented Oct 27, 2026

Uh oh!

TimWolla Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

TimWolla Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

TimWolla Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

TimWolla Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

TimWolla Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Sjord commented Oct 1, 2026 •

edited

Loading

TimWolla commented Oct 2, 2026 •

edited

Loading