====== 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.