Table of Contents

PHP RFC: DTLS support in ext/openssl

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

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:

Changes outside ext/openssl are small:

Tests

The PR adds about 30 tests in ext/openssl/tests

Backward Incompatible Changes

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

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

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