PHP RFC: DTLS support in ext/openssl

Version: 0.1
Date: 2026-11-12
Author:
- Gianfrancesco Aurecchia, gianfri@aurecchia.it
Status: Draft
Implementation: https://github.com/php/php-src/pull/22638
Discussion thread: tbd
Voting thread: tbd

Introduction

PHP can encrypt TCP streams with TLS, but it has no way to encrypt UDP traffic. DTLS (Datagram TLS,RFC 6347 and RFC 9147) is the standard answer and is used by CoAP/LwM2M (IoT), WebRTC data channels, SIP, VPNs and syslog. Today a PHP application that has to speak DTLS needs an external process or a C extension. This RFC proposes DTLS stream transports in ext/openssl that work like the existing tls:// transports.

<?php
 
$ctx = stream_context_create(['ssl' => ['cafile' => '/etc/ssl/ca.pem']]);
$client = stream_socket_client('dtls://example.com:5684', $errno, $errstr, 5, STREAM_CLIENT_CONNECT, $ctx);
 
fwrite($client, "ping");      // one fwrite() is one DTLS record
echo fread($client, 1500);    // one fread() returns one datagram
 
?>

Proposal

TBD

New transports

New transports: dtls://, dtlsv1.2:// and dtlsv1.3:// (the last one only if OpenSSL supports DTLS 1.3). They can be used for clients and servers.

Transport	Protocol versions
`dtls://`	DTLS 1.2 and DTLS 1.3 (when available)
`dtlsv1.2://`	DTLS 1.2 only
`dtlsv1.3://`	DTLS 1.3 only, registered only when available

DTLS over an existing udp:// stream

Like tcp:// today, udp:// is now provided by ext/openssl, so a udp:// stream can be upgraded with 'stream_socket_enable_crypto()''

<?php
 
$client = stream_socket_client('udp://example.com:5684', $errno, $errstr, 5, STREAM_CLIENT_CONNECT, $ctx);
stream_socket_enable_crypto($client, true, STREAM_CRYPTO_METHOD_DTLS_ANY_CLIENT);
 
?>

Server

TBD

<?php
 
// TBD
 
?>

New constants

<?php
 
const STREAM_CRYPTO_METHOD_DTLSv1_2_CLIENT = UNKNOWN;
const STREAM_CRYPTO_METHOD_DTLSv1_3_CLIENT = UNKNOWN;
const STREAM_CRYPTO_METHOD_DTLS_ANY_CLIENT = UNKNOWN;
const STREAM_CRYPTO_METHOD_DTLSv1_2_SERVER = UNKNOWN;
const STREAM_CRYPTO_METHOD_DTLSv1_3_SERVER = UNKNOWN;
const STREAM_CRYPTO_METHOD_DTLS_ANY_SERVER = UNKNOWN;
 
?>

Examples

TBD

Backward Incompatible Changes

New global constants STREAM_CRYPTO_METHOD_DTLS* could clash with user constants with the same names.
When ext/openssl is loaded, udp:// streams are created by ext/openssl, as tcp:// already is. Their stream_type in stream_get_meta_data() becomes udp_socket/dtls instead of udp_socket, the same way tcp:// streams report tcp_socket/ssl. Code that compares stream_type to udp_socket exactly is affected

A search on github found 143 fila comparing stream_type with 'udp_socket' exactly, like as for symfony/polyfill which would break. No project defines constants named STREAM_CRYPTO_METHOD_DTLS*.

Proposed PHP Version(s)

Next PHP 8.x.

RFC Impact

To the Ecosystem

None.

To Existing Extensions

Only ext/openssl changes, plus small changes to the stream layer (main/streams) so that datagram sockets can be wrapped. The TLS code path is refactored to share the IO loop with DTLS, the existing TLS tests pass unchanged.

To SAPIs

None.

Open Issues

TBD

Future Scope

TBD

Voting Choices

Primary Vote requiring a 2/3 majority to accept the RFC:

Add DTLS stream transports to ext/openssl as outlined in the RFC?
Real name	Yes	No	Abstain
Final result:	0	0	0
This poll has been closed.

Patches and Tests

https://github.com/php/php-src/pull/22638

Implementation

TBD

References

RFC 6347: Datagram Transport Layer Security Version 1.2 https://www.rfc-editor.org/rfc/rfc6347
RFC 9147: The Datagram Transport Layer Security (DTLS) Protocol Version 1.3 https://www.rfc-editor.org/rfc/rfc9147

Rejected Features

None yet.

Changelog

0.1: Initial draft.