tlsSocket.getPeerCertificate() doesn't document format of valid_from / valid_to

[roy-work]

Affected URL(s)

https://nodejs.org/api/tls.html#tlssocketgetpeercertificatedetailed

Description of the problem

The "Certificate object" returned from getPeerCertificate is merely documented as,

valid_from <string> The date-time the certificate is valid from.
valid_to <string> The date-time the certificate is valid to.

First, these would be better as Dates, but I'm assuming that such a change cannot be made, as it would be a breaking change.

In lieu of that … the documentation should specify what format these strings are in. Unfortunately, it appears that these strings are in the format:

Mar 25 18:18:52 2025 GMT

which isn't in any standardized format I'm aware of. It appears to be the output of ASN1_TIME_print from OpenSSL.

It would be nice to note at least that much; maybe, an example of the output?

---

Since this necessitates anyone wanting to use the data for more than printing to write a parser, I'll also note the following:

OpenSSL's documentation also doesn't really document this format, instead only saying,

The ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() functions print the time structure s to BIO b in human readable format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example "Feb 3 00:55:52 2015 GMT", which does not include a newline. If the time structure has invalid format it prints out "Bad time value" and returns an error. The output for generalized time may include a fractional part following the second.

Note that the example in the documentation is wrong; AFAICT with examples, that would output Feb 3 00:55:52 2015 GMT, not Feb 3 00:55:52 2015 GMT.

ASN1_TIME_print seems to be equivalent to calling ASN1_TIME_print_ex with flags set to ASN1_DTFLGS_RFC822 (but don't let the name fool you, it's not RFC 822 format, which is like 25 Mar 25, which matches nothing seen thus far…)

So DD = "space padded" day number, and the [GMT] is concerning, so I dug into OpenSSL's code to see in what circumstances it would be omitted.

The exact code is in ossl_asn1_time_print_ex in OpenSSL, but to save anyone the time, one of two format strings get used:

GenerializedTime = "%s %2d %02d:%02d:%02d%.*s %d%s",
        UTC time = "%s %2d %02d:%02d:%02d %d%s"

With those replacements being 3-char month, day, hour:min:sec, (fractional sec, only for GeneralizedTime), year, and then " GMT" or ""; if the datetime is in GMT, then " GMT", if it's not, then "" — (and the string is thus mangled; AFAICT the underlying data has a UTC offset, it's just not printed!)

Cf. openssl/openssl#26313 — I've asked if OpenSSL can't also document this a little more, too.