From f928f1d505b17ca456cefb9329b5cfca2139a96d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dan=20=C4=8Cerm=C3=A1k?= <dcermak@suse.com>
Date: Wed, 27 Jan 2021 10:59:53 +0100
Subject: [PATCH] Document the x509 error codes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Dan Čermák <dcermak@suse.com>
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
---
 doc/api/tls.md              | 42 +++++++++++++++++++++++++++++++++++++
 src/crypto/crypto_common.cc |  2 ++
 2 files changed, 44 insertions(+)

diff --git a/doc/api/tls.md b/doc/api/tls.md
index 2c8414f2988c9c..695e429b139efd 100644
--- 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
index abf4600f9f1707..1b863a1241edb3 100644
--- 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)