Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:126393
Precedence: bulk
MIME-Version: 1.0
References: <CAKws9z2-e8YnGbdpp0BJvEBEiEsqHQMzyAo+Vee4naXy5mK40w@mail.gmail.com>
In-Reply-To: <CAKws9z2-e8YnGbdpp0BJvEBEiEsqHQMzyAo+Vee4naXy5mK40w@mail.gmail.com>
Date: Thu, 13 Feb 2025 15:12:36 +0000
Message-ID: <CAGBsUrdKR+xYuuwNenz9yTkvfeh-Ox90shO8oPJdofVRr=QQXA@mail.gmail.com>
Subject: Re: [PHP-DEV] Update OpenSSL Extension to Support KEMs
To: Paragon Initiative Enterprises Security Team <security@paragonie.com>
Cc: PHP Internals <internals@lists.php.net>
Content-Type: text/plain; charset="UTF-8"
From: tekiela246@gmail.com (Kamil Tekiela)

I have no issue with adding more functions to the OpenSSL extension,
but they need to be very clearly documented and have an obvious API.
Cryptic names such as $pk or $sk cannot be used. While I really hate
array return types, if you must use it then it must be clearly
documented. It cannot just be "shared secret (typically 32 bytes)".
What does "typically" even mean? I assume the type for both would be a
string, but that's not obvious.

The OpenSSL documentation is in pretty bad shape. Many functions are
poorly documented and there are barely any examples. While I am sure
there are people who know how to use it, it's a complete mystery to me
and I presume many others.