doc: document x509 error codes

Signed-off-by: Dan Čermák <dcermak@suse.com>
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
Co-authored-by: James M Snell <jasnell@gmail.com>

PR-URL: #37096
Fixes: #29342
Fixes: #29342
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>

Author: dcermak

doc/api/tls.md

@@ -370,6 +370,48 @@ The first 3 are enabled by default. The last 2 `CCM`-based suites are supported
 by TLSv1.3 because they may be more performant on constrained systems, but they
 are not enabled by default since they offer less security.
 
+## X509 Certificate Error codes
+
+Multiple functions can fail due to certificate errors that are reported by
+OpenSSL. In such a case, the function provides an {Error} via its callback that
+has the property `code` which can take one of the following values:
+
+<!--
+values are taken from src/crypto/crypto_common.cc
+description are taken from deps/openssl/openssl/crypto/x509/x509_txt.c
+-->
+* `'UNABLE_TO_GET_ISSUER_CERT'`: Unable to get issuer certificate.
+* `'UNABLE_TO_GET_CRL'`: Unable to get certificate CRL.
+* `'UNABLE_TO_DECRYPT_CERT_SIGNATURE'`: Unable to decrypt certificate's
+  signature.
+* `'UNABLE_TO_DECRYPT_CRL_SIGNATURE'`: Unable to decrypt CRL's signature.
+* `'UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY'`: Unable to decode issuer public key.
+* `'CERT_SIGNATURE_FAILURE'`: Certificate signature failure.
+* `'CRL_SIGNATURE_FAILURE'`: CRL signature failure.
+* `'CERT_NOT_YET_VALID'`: Certificate is not yet valid.
+* `'CERT_HAS_EXPIRED'`: Certificate has expired.
+* `'CRL_NOT_YET_VALID'`: CRL is not yet valid.
+* `'CRL_HAS_EXPIRED'`: CRL has expired.
+* `'ERROR_IN_CERT_NOT_BEFORE_FIELD'`: Format error in certificate's notBefore
+  field.
+* `'ERROR_IN_CERT_NOT_AFTER_FIELD'`: Format error in certificate's notAfter
+  field.
+* `'ERROR_IN_CRL_LAST_UPDATE_FIELD'`: Format error in CRL's lastUpdate field.
+* `'ERROR_IN_CRL_NEXT_UPDATE_FIELD'`: Format error in CRL's nextUpdate field.
+* `'OUT_OF_MEM'`: Out of memory.
+* `'DEPTH_ZERO_SELF_SIGNED_CERT'`: Self signed certificate.
+* `'SELF_SIGNED_CERT_IN_CHAIN'`: Self signed certificate in certificate chain.
+* `'UNABLE_TO_GET_ISSUER_CERT_LOCALLY'`: Unable to get local issuer certificate.
+* `'UNABLE_TO_VERIFY_LEAF_SIGNATURE'`: Unable to verify the first certificate.
+* `'CERT_CHAIN_TOO_LONG'`: Certificate chain too long.
+* `'CERT_REVOKED'`: Certificate revoked.
+* `'INVALID_CA'`: Invalid CA certificate.
+* `'PATH_LENGTH_EXCEEDED'`: Path length constraint exceeded.
+* `'INVALID_PURPOSE'`: Unsupported certificate purpose.
+* `'CERT_UNTRUSTED'`: Certificate not trusted.
+* `'CERT_REJECTED'`: Certificate rejected.
+* `'HOSTNAME_MISMATCH'`: Hostname mismatch.
+
 ## Class: `tls.CryptoStream`
 <!-- YAML
 added: v0.3.4

src/crypto/crypto_common.cc

@@ -297,6 +297,8 @@ const char* X509ErrorCode(long err) {  // NOLINT(runtime/int)
   const char* code = "UNSPECIFIED";
 #define CASE_X509_ERR(CODE) case X509_V_ERR_##CODE: code = #CODE; break;
   switch (err) {
+    // if you modify anything in here, *please* update the respective section in
+    // doc/api/tls.md as well
     CASE_X509_ERR(UNABLE_TO_GET_ISSUER_CERT)
     CASE_X509_ERR(UNABLE_TO_GET_CRL)
     CASE_X509_ERR(UNABLE_TO_DECRYPT_CERT_SIGNATURE)