Document the x509 error codes

dcermak · aduh95 · dcermak · commit f928f1d505b1 · 2021-01-27T12:23:21.000+01:00
Signed-off-by: Dan &#268;erm&aacute;k &lt;dcermak@suse.com&gt;
Co-authored-by: Antoine du Hamel &lt;duhamelantoine1995@gmail.com&gt;
diff --git a/doc/api/tls.md b/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 a {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
diff --git a/src/crypto/crypto_common.cc b/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)
