DTLS support in ext/openssl View as Markdown

Draft
▴ 0 ▾ 0
community vote
Authors
Gianfrancesco Aurecchia, gianfri@aurecchia.it
Date
2026-11-12
Version
0.1
Implementation
https://github.com/php/php-src/pull/22638
Source
wiki.php.net/rfc/dtls_support_in_ext_openssl

Vote

Add DTLS stream transports to ext/openssl as outlined in the RFC? no votes
Yes · No · Abstain

Discussions on the mailing list

No thread found. Threads are linked to an RFC when their first email links to the RFC page, or when the RFC page links to them.

RFC text

Copied from wiki.php.net, last synchronized Nov 16, 2026 00:46 UTC

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

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():

<?php
 
if (!in_array('dtls', stream_get_transports(), true)) {
    throw new RuntimeException('This PHP build has no DTLS support');
}
 
?>

Client

stream_socket_client() with a dtls scheme creates a connected UDP socket and runs the handshake, exactly as tls:// does over TCP:

<?php
 
$ctx = stream_context_create(['ssl' => [
    '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:

<?php
 
$ctx = stream_context_create(['ssl' => ['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()''

<?php
 
$ctx = stream_context_create(['ssl' => ['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:

<?php
 
$session = null;
$ctx = stream_context_create(['ssl' => [
    '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.

<?php
 
$inner = stream_socket_client('tcp://proxy.example:8080');
// ... CONNECT through the proxy ...
$ctx = stream_context_create(['ssl' => ['inner_stream' => $inner]]);
$tls = stream_socket_client('tls://example.com:443', $errno, $errstr, 5,
    STREAM_CLIENT_CONNECT, $ctx);
 
?>

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

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:

Vote: Add DTLS stream transports to ext/openssl as outlined in the RFC? — Yes: 0 · No: 0 · Abstain: 0 (closed)

Patches and Tests

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

Implementation

After the RFC is implemented, this section should contain:

  1. the version(s) it was merged into
  2. a link to the git commit(s)
  3. a link to the PHP manual entry for the feature

References

Rejected Features

None yet.

Changelog

  • 0.1: Initial draft.