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 ?>
dtls://, dtlsv1.2:// and dtlsv1.3://, client and server.udp:// stream through stream_socket_enable_crypto().dtls:// server shares one UDP socket between all its peers and returns one stream per peer from stream_socket_accept().STREAM_CRYPTO_METHOD_DTLS*.ssl context options: dtls_link_mtu, dtls_max_pending, dtls_pending_timeout, keying_material_label, keying_material_length, inner_stream.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: 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'); } ?>
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" ?>
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))); } ?>
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); ?>
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_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 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); ?>
<?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; ?>
TBD
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.
The PR adds about 30 tests in ext/openssl/tests
udp:// stream;inner_stream;STREAM_CRYPTO_METHOD_DTLS* could clash with user constants with the same names.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 affectedA 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*.
Next PHP 8.x.
stream_type values should add udp_socket/dtls.
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.
None.
TBD
TBD
Primary Vote requiring a 2/3 majority to accept the RFC:
After the RFC is implemented, this section should contain:
None yet.