Re: [RFC idea] DTLS support in ext/openssl (Openssl\Dtls)

Hi Rowan, Thanks, this is exactly the kind of API-shaping feedback I was hoping for. Things I'm happy to take: - Certificate and key as 'OpenSSLCertificate' / 'OpenSSLAsymmetricKey' objects rather than PEM strings: yes, that aligns with the rest of ext/openssl. I'd probably still accept PEM as a convenience, but make the objects the primary form. - Returning 'null' rather than 'false' for an expected empty result (no datagram pending, no application data yet): agreed, null is clearer there. On the enums (the handshake state, and digest selection): I like enums, and personally I'd reach for them too. My hesitation is that I'd rather not diverge from how ext/openssl is consolidated today: the extension exposes this kind of thing as integer constants ('OPENSSL_ALGO_*', 'OPENSSL_*') and selects digests by name (string), not through enums. Introducing enums just for DTLS would create a new convention in one corner of the extension. Whether ext/openssl should move towards enums more broadly feels like a maintainer-level decision, and Jakub's feedback would be valuable there; he may well already be considering something along these lines. I'd keep that question separate from this proposal, so the DTLS work doesn't hinge on a wider style change, and for now follow the extension's existing convention. On a 'DtlsDatagram' value object vs raw strings: here I'd lean towards keeping raw strings, for two reasons. First, 'feed()' and 'pull()' sit on the hot path (one call per packet), so wrapping every datagram in an object adds allocation for what is essentially a byte buffer. Second, binary I/O across PHP (fread/fwrite, the socket and stream functions, the openssl_* functions) is consistently done with strings, so a datagram object would be a bit of an outlier; PHP strings already are the byte-buffer type. I'm open if there's a concrete benefit I'm missing, for example carrying metadata alongside the bytes. On direction: Jakub suggested also exposing a 'dtls://' stream wrapper alongside the low-level engine, which I think is a good idea. I'm waiting for his feedback on that before settling the overall shape. Your points apply to the engine/class surface either way, and I'll fold the agreed ones in. Thanks again for the careful read. Gianfrancesco Il giorno mer 24 giu 2026 alle ore 23:08 Rowan Tommins [IMSoP] < imsop.php@rwec.co.uk> ha scritto: > Hi Gianfrancesco, > > I don't have any expertise of the actual protocol, but do have an opinion > on the PHP surface design. I apologise if the below feels too much like > bikeshedding... > > > On 24 June 2026 12:45:05 BST, Gianfrancesco Aurecchia < > gianfri.aur@gmail.com> wrote: > > Should the constructor also accept > > OpenSSLCertificate/OpenSSLAsymmetricKey > > objects in addition to PEM? > > I would say *instead of* a string. Accepting a string means the > constructor has to document the expected format, produce appropriate parse > errors, etc; accepting an object reduces that to a standard type check. And > if the user already has an object, serialising it and then reparsing it is > duplicated effort. > > In general, I would prefer a design which used "real" types throughout > instead of strings and ints, except where performance is critical: > > > > public const int HANDSHAKE_ERROR = -1; > > public const int HANDSHAKE_CONTINUE = 0; > > public const int HANDSHAKE_FINISHED = 1; > > > These should be cases on an enum; probably unbacked, unless there's some > reason applications need to work with these integer codes. > > > > public function getFingerprint(?string $digestAlgo = null): string > > > Perhaps the supported algorithms could be an enum as well, backed by > string. > > > > public function feed(string $datagram): int {} > > public function pull(): ?string {} > > > If $datagram has to be in a specific format, would a lightweight > DtlsDatagram object be useful? Again, it would delegate the > parsing/validation to a specific factory, and give flexibility for extra > ways of creating or reusing material without going via strings and > revalidating. > > > > public function read(): string|false {} > > public function exportKeys(string $label, int $length): > >string|false {} > > > If the false case here is an expected condition, like EOF, "?string" might > be better. If it's just a signal for unexpected errors, throwing an > exception would be better. > > > Hopefully someone with more knowledge of the problem space can comment > more on the core idea. > > Thanks, > > Rowan Tommins > [IMSoP] >