====== 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,[[https://www.rfc-editor.org/info/rfc6347/|RFC 6347]] and [[https://www.rfc-editor.org/info/rfc9147/|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.
['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 =====
==== Summary ====
* New transports ''dtls://'', ''dtlsv1.2://'' and ''dtlsv1.3://'', client and server.
* DTLS on an existing ''udp://'' stream through ''stream_socket_enable_crypto()''.
* A ''dtls://'' server shares one UDP socket between all its peers and returns one stream per peer from ''stream_socket_accept()''.
* Six new constants ''STREAM_CRYPTO_METHOD_DTLS*''.
* New ''ssl'' context options: ''dtls_link_mtu'', ''dtls_max_pending'', ''dtls_pending_timeout'', ''keying_material_label'', ''keying_material_length'', ''inner_stream''.
* All the existing ''ssl'' context options, ''Openssl\Session'' and the stream functions work for DTLS as they do for TLS.
No new functions or classes are added.
==== 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 |
Applications check for them with ''stream_get_transports()'':
==== Client ====
''stream_socket_client()'' with a ''dtls'' scheme creates a connected UDP socket and runs the handshake, exactly as ''tls://'' does over TCP:
[
'cafile' => '/etc/ssl/ca.pem',
'peer_name' => 'example.com',
]]);
$client = stream_socket_client('dtls://example.com:5684', $errno, $errstr, 5,
STREAM_CLIENT_CONNECT, $ctx);
if ($client === false) {
die("DTLS connection failed: $errstr\n");
}
var_dump(stream_get_meta_data($client)['crypto']['protocol']); // "DTLSv1.2" or "DTLSv1.3"
?>
==== Server ====
A ''dtls://'' server uses one UDP socket for all its peers. ''stream_socket_accept()'' returns one stream per peer once its handshake is complete. The server:
['local_cert' => '/path/server.pem']]);
$s = stream_socket_server('dtls://0.0.0.0:4433', $errno, $errstr,
STREAM_SERVER_BIND | STREAM_SERVER_LISTEN, $ctx);
while ($peer = stream_socket_accept($s, 5, $addr)) {
fwrite($peer, strtoupper(fread($peer, 1500)));
}
?>
==== 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()''
['cafile' => '/path/ca.pem']]);
$c = stream_socket_client('dtls://example.com:4433', $errno, $errstr, 5,
STREAM_CLIENT_CONNECT, $ctx);
fwrite($c, $datagram);
$reply = fread($c, 1500);
?>
==== Context options ====
All existing ''ssl'' context options (''verify_peer'', ''cafile'', ''local_cert'', ''peer_fingerprint'', ''ciphers'', ''session_*'', ...) apply to DTLS as they do to TLS. New options:
^ Option ^ Type ^ Default ^ Description ^
| ''dtls_link_mtu'' | int | discovered by OpenSSL | MTU of the link. Records and handshake fragments are sized to fit it. |
| ''dtls_max_pending'' | int | 256 | Server: maximum number of handshakes in progress. Peers that have not returned a valid cookie are dropped first when the limit is reached. |
| ''dtls_pending_timeout'' | int | 30 | Server: seconds after which a handshake that has not completed, or a completed peer not yet accepted, is dropped. |
| ''keying_material_label'' | string | none | Label for the RFC 5705 exporter (for example ''EXTRACTOR-dtls_srtp''). |
| ''keying_material_length'' | int | none | Length of the exported keying material, 1 to 1024 bytes. |
| ''inner_stream'' | resource | none | A stream that carries the ciphertext instead of a socket of its own. Works for TLS and DTLS. |
When both ''keying_material_*'' options are set, ''stream_get_meta_data()['crypto']['keying_material']'' contains the exported bytes. The two keying material options and ''inner_stream'' are also available for ''tls://''.
==== Session resumption ====
''session_data'', ''session_new_cb'', ''session_get_cb'', ''session_remove_cb'', ''session_cache'', ''session_timeout'', ''session_id_context'' and ''Openssl\Session'' work for DTLS as for TLS, on the client and on the server:
[
'cafile' => '/etc/ssl/ca.pem',
'session_new_cb' => function ($stream, Openssl\Session $s) use (&$session) {
$session = $s;
},
]]);
$client = stream_socket_client('dtls://example:5684', $errno, $errstr, 5,
STREAM_CLIENT_CONNECT, $ctx);
fclose($client);
// later: resume the session
$ctx = stream_context_create(['ssl' => [
'cafile' => '/etc/ssl/ca.pem',
'session_data' => $session,
]]);
$client = stream_socket_client('dtls://example:5684', $errno, $errstr, 5,
STREAM_CLIENT_CONNECT, $ctx);
var_dump(stream_get_meta_data($client)['crypto']['session_reused']); // bool(true)
?>
==== inner_stream ====
''inner_stream'' lets TLS or DTLS run over any PHP stream: a proxy tunnel, a user stream wrapper, a stream that is already TLS. The crypto stream does not connect anything itself; it reads and writes ciphertext through the given stream.
['inner_stream' => $inner]]);
$tls = stream_socket_client('tls://example.com:443', $errno, $errstr, 5,
STREAM_CLIENT_CONNECT, $ctx);
?>
==== New constants ====
==== Examples ====
TBD
==== Implementation overview ====
The cahnges touches mainly ext/openssl. It is split by layer, so that TLS and DTLS share the same code wherever possible:
* ''xp_bio.c'': the ciphertext transport. OpenSSL reads records from a receive queue and writes into a send queue, through a custom BIO. The stream moves ciphertext between these queues and the transport (its own socket, the shared socket of a DTLS server, or the ''inner_stream'') around each SSL call.
* ''xp_ssl.c'': one stream implementation for TLS and DTLS. The datagram schemes select the DTLS methods and version range; option handling, verification, sessions and metadata are shared. The TLS code was refactored to use the new IO loop.
* ''xp_dtls.c'': dtls necessity: routing, cookie exchange, pending peers, accept queue.
Changes outside ext/openssl are small:
* ''main/streams'': ''php_netstream_data_t'' gets an ''is_dgram'' flag, so that the generic socket operations treat a socket created by ext/openssl as UDP;
* ''main/streams/php_stream_transport.h'' and ''ext/standard/file.stub.php'': the new constants;
* ''ext/sockets/tests/bug_export_stream_type.phpt'': updated for the new ''stream_type''.
==== Tests ====
The PR adds about 30 tests in ''ext/openssl/tests''
* basic client and server, DTLS 1.2 and DTLS 1.3;
* verification, peer name, fingerprints, client certificates, encrypted keys;
* non-blocking mode and timeouts;
* session resumption on client and server, for DTLS 1.2 and DTLS 1.3;
* upgrade of a ''udp://'' stream;
* ''inner_stream'';
* callbacks closing their own stream.
===== 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 ====
* Stubs and IDEs need the six new constants and the new context options.
* Static analysers that know the ''stream_type'' values should add ''udp_socket/dtls''.
==== 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:
* Yes
* No
* Abstain
===== Patches and Tests =====
https://github.com/php/php-src/pull/22638
===== Implementation =====
After the RFC is implemented, this section should contain:
- the version(s) it was merged into
- a link to the git commit(s)
- a link to the PHP manual entry for the feature
===== 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.