doc: Add OpenSSL errors to API docs

[j3lamp]

Fixes: #33705

Checklist

• documentation is changed or added
• [ x] commit message follows commit guidelines

[bnoordhuis]

Generally LGTM, thanks.

I'm fairly sure UNABLE_TO_DECRYPT_CERT_SIGNATURE and UNABLE_TO_DECRYPT_CRL_SIGNATURE are never actually returned by openssl even though it lists them as error codes (and node handles them.)

I think HOSTNAME_MISMATCH is also one that's never going to show up because node handles host name verification itself, through tls.checkServerIdentity().

I'll leave it up to you if you want to leave them in or not.

[bnoordhuis]

Suggested change

	The certificate has expired: that is the notAfter date is before the current
	time.
	The certificate has expired: the notAfter date is before the current time.

For consistency with the preceding description.

[bnoordhuis]

Suggested change

	The revocation data have a future issue date.
	The revocation data has a future issue date.

[j3lamp]

Technically "have" is more corerct. I'll reword it to avoid the awkwardness of "data".

[bnoordhuis]

Suggested change

	The certificate chain length is greater than the supplied maximum depth.
	The certificate chain length is greater than the maximum depth.

"supplied" suggests it's configurable but it's not (in node - no binding for X509_STORE_CTX_set_depth().)

[bnoordhuis]

Suggested change

	the basic constrains extension.
	the basic constraints extension.

I'd leave out the bit about v1 vs. v3 certificates. Openssl's docs say this, which IMO is generic yet complete enough:

a CA certificate is invalid. Either it is not a CA or its extensions are not consistent with the supplied purpose.

"The certificate’s signer" is a good clarification but I'm not 100% sure you can't also get it when you manipulate a CA certificate directly. In that case the error is about the certificate itself, not its signer.

[j3lamp]

Okay, I thought that GnuTLS' description was clear, but I am no expert. I'll switch it to OpenSSL's description. (Which is mostly what I used for the rest anyway.)
I'd be more embarrassed about "constrains" if it wasn't wrong in what I copied.

[j3lamp]

I left the three errors that shouldn't be seen simply to keep the list of what errors that node handles and the list that are documented the same. I made the rest of the changes you suggested. Thank you for the thorough review. Oh, I also rebased to avoid conflicts.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/32232/

[PoojaDurgad]

@j3lamp - need a rebase to resolve git conflicts

[DerekNonGeneric]

Would be nice to get this in. Seems good to go.

/cc @Trott

[Trott]

Non-blocking nit: I'd prefer the errors in each subsection be in alphabetical order unless there is a hugely compelling reason like some other obvious logical order. So, for example, CERT_HAS_EXPIRED would come before CERT_NOT_YET_VALID rather than after it.

Looks good to me. The C++ change is a comment only so running Jenkins may be superfluous. If anyone disagrees, we can run Jenkins once it comes out of lockdown (probably in a few hours).

[Mifrill]

Is it worth adding a link to a source like https://www.openssl.org/docs/ or any other authoritative sources to ensure accuracy, since this documentation is always good to verify the content against the official OpenSSL documentation?
Additionally, if there have been any recent updates or changes to these error codes, it's essential to reflect those changes in the documentation, since this PR is open for a while.