# RFC: DTLS support in ext/openssl

- Status: Draft
- Authors: Gianfrancesco Aurecchia, gianfri@aurecchia.it
- Date: 2026-11-12
- Version: 0.1
- Implementation: https://github.com/php/php-src/pull/22638
- Original: https://wiki.php.net/rfc/dtls_support_in_ext_openssl
- Page: https://externals.io/rfc/dtls_support_in_ext_openssl
- More for agents: search with https://externals.io/search.md?q={query} · RFCs at https://externals.io/rfc.md · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

## Votes

### Add DTLS stream transports to ext/openssl as outlined in the RFC? (closed)

Yes: 0 · No: 0 · Abstain: 0

## Discussions on the mailing list

No thread found.

---

## Introduction

PHP can encrypt TCP streams with TLS, but it has no way to encrypt UDP traffic. DTLS (Datagram TLS,[RFC 6347](https://www.rfc-editor.org/info/rfc6347/) and [RFC 9147](https://www.rfc-editor.org/info/rfc9147/)) 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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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

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