From 60862773e8de188d3cc6b81d0c0ec19ffabbe15b 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>
---
 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..6d3206c3be3ea0 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)