More details about the array returned from openssl_x509_parse

From php/php-src#11918.

The version returned is evidently the raw version number, which is the certificate version number - 1 (so version 3 is version => 2). This follows with the X509 standards and is exactly what OpenSSL itself reports, except that means there can be confusion about what "2" means.

The documentation should clarify that the version is the raw 0-based number and not the certificate's 1-based logical version number...

However, given that PHP is aggregating multiple data points into the one returned array, I think that the documentation should go further and list out exactly what is being returned. The docs do currently say the returned array is "(deliberately) not yet documented, as it is still subject to change", and I think the time for that to happen has come*.

https://github.com/php/php-src/blob/php-8.2.8/ext/openssl/openssl.c#L2036

I'm thinking a table to list the names of the various keys, their values' data types, and any useful commentary warranted about:

• name (string)
• subject (string)
• hash (string) - of hex digits
• issuer (string)
• version (integer) - one less than the "normal" version number
• etc.

The keys and data types are easy to read from the source; the "useful commentary" could take a little more effort, but hopefully a quick glance at the OpenSSL docs for the relevant functions will be enough.

(* What's more, documenting the structure solidifies PHP's natural responsibility towards not breaking BC with arbitrary changes, so this would be A Good Thing.)

Start with the openssl_x509_parse implementation in ext/openssl/openssl.c around line 2036, then consult the OpenSSL documentation for the relevant functions. Document the returned array's keys, value types, and useful commentary, including that version is the raw 0-based certificate version; done means the structure and version semantics are clearly covered.