esp-tls: capturing specific errors to be available in tcp_transport and then in application code

components/esp-tls/CMakeLists.txt

@@ -1,4 +1,5 @@
 idf_component_register(SRCS "esp_tls.c"
                     INCLUDE_DIRS "."
+                    PRIVATE_INCLUDE_DIRS "private_include"
                     REQUIRES mbedtls
                     PRIV_REQUIRES lwip nghttp)

components/esp-tls/component.mk

@@ -1,3 +1,3 @@
 COMPONENT_SRCDIRS := .
 
-COMPONENT_ADD_INCLUDEDIRS := .
+COMPONENT_ADD_INCLUDEDIRS := . private_include

components/esp-tls/esp_tls.c

@@ -22,6 +22,7 @@
 
 #include <http_parser.h>
 #include "esp_tls.h"
+#include "esp_tls_error_capture_internal.h"
 #include <errno.h>
 
 static const char *TAG = "esp-tls";
@@ -45,7 +46,7 @@ typedef struct esp_tls_pki_t {
     unsigned int privkey_password_len;
 } esp_tls_pki_t;
 
-static struct addrinfo *resolve_host_name(const char *host, size_t hostlen)
+static esp_err_t resolve_host_name(const char *host, size_t hostlen, struct addrinfo **address_info)
 {
     struct addrinfo hints;
     memset(&hints, 0, sizeof(hints));
@@ -54,18 +55,17 @@ static struct addrinfo *resolve_host_name(const char *host, size_t hostlen)
 
     char *use_host = strndup(host, hostlen);
     if (!use_host) {
-        return NULL;
+        return ESP_ERR_NO_MEM;
     }
 
     ESP_LOGD(TAG, "host:%s: strlen %lu", use_host, (unsigned long)hostlen);
-    struct addrinfo *res;
-    if (getaddrinfo(use_host, NULL, &hints, &res)) {
+    if (getaddrinfo(use_host, NULL, &hints, address_info)) {
         ESP_LOGE(TAG, "couldn't get hostname for :%s:", use_host);
         free(use_host);
-        return NULL;
+        return ESP_ERR_ESP_TLS_CANNOT_RESOLVE_HOSTNAME;
     }
     free(use_host);
-    return res;
+    return ESP_OK;
 }
 
 static ssize_t tcp_read(esp_tls_t *tls, char *data, size_t datalen)
@@ -81,6 +81,7 @@ static ssize_t tls_read(esp_tls_t *tls, char *data, size_t datalen)
             return 0;
         }
         if (ret != MBEDTLS_ERR_SSL_WANT_READ  && ret != MBEDTLS_ERR_SSL_WANT_WRITE) {
+            ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_MBEDTLS, ret);
             ESP_LOGE(TAG, "read error :%d:", ret);
         }
     }
@@ -93,32 +94,35 @@ static void ms_to_timeval(int timeout_ms, struct timeval *tv)
     tv->tv_usec = (timeout_ms % 1000) * 1000;
 }
 
-static int esp_tcp_connect(const char *host, int hostlen, int port, int *sockfd, const esp_tls_cfg_t *cfg)
+static esp_err_t esp_tcp_connect(const char *host, int hostlen, int port, int *sockfd, const esp_tls_t *tls, const esp_tls_cfg_t *cfg)
 {
-    int ret = -1;
-    struct addrinfo *res = resolve_host_name(host, hostlen);
-    if (!res) {
+    esp_err_t ret;
+    struct addrinfo *addrinfo;
+    if ((ret = resolve_host_name(host, hostlen, &addrinfo)) != ESP_OK) {
         return ret;
     }
 
-    int fd = socket(res->ai_family, res->ai_socktype, res->ai_protocol);
+    int fd = socket(addrinfo->ai_family, addrinfo->ai_socktype, addrinfo->ai_protocol);
     if (fd < 0) {
-        ESP_LOGE(TAG, "Failed to create socket (family %d socktype %d protocol %d)", res->ai_family, res->ai_socktype, res->ai_protocol);
+        ESP_LOGE(TAG, "Failed to create socket (family %d socktype %d protocol %d)", addrinfo->ai_family, addrinfo->ai_socktype, addrinfo->ai_protocol);
+        ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_SYSTEM, errno);
+        ret = ESP_ERR_ESP_TLS_CANNOT_CREATE_SOCKET;
         goto err_freeaddr;
     }
 
     void *addr_ptr;
-    if (res->ai_family == AF_INET) {
-        struct sockaddr_in *p = (struct sockaddr_in *)res->ai_addr;
+    if (addrinfo->ai_family == AF_INET) {
+        struct sockaddr_in *p = (struct sockaddr_in *)addrinfo->ai_addr;
         p->sin_port = htons(port);
         addr_ptr = p;
-    } else if (res->ai_family == AF_INET6) {
-        struct sockaddr_in6 *p = (struct sockaddr_in6 *)res->ai_addr;
+    } else if (addrinfo->ai_family == AF_INET6) {
+        struct sockaddr_in6 *p = (struct sockaddr_in6 *)addrinfo->ai_addr;
         p->sin6_port = htons(port);
         p->sin6_family = AF_INET6;
         addr_ptr = p;
     } else {
-        ESP_LOGE(TAG, "Unsupported protocol family %d", res->ai_family);
+        ESP_LOGE(TAG, "Unsupported protocol family %d", addrinfo->ai_family);
+        ret = ESP_ERR_ESP_TLS_UNSUPPORTED_PROTOCOL_FAMILY;
         goto err_freesocket;
     }
 
@@ -134,21 +138,23 @@ static int esp_tcp_connect(const char *host, int hostlen, int port, int *sockfd,
         }
     }
 
-    ret = connect(fd, addr_ptr, res->ai_addrlen);
+    ret = connect(fd, addr_ptr, addrinfo->ai_addrlen);
     if (ret < 0 && !(errno == EINPROGRESS && cfg && cfg->non_block)) {
 
-        ESP_LOGE(TAG, "Failed to connect to host (errno %d)", errno);
+        ESP_LOGE(TAG, "Failed to connnect to host (errno %d)", errno);
+        ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_SYSTEM, errno);
+        ret = ESP_ERR_ESP_TLS_FAILED_CONNECT_TO_HOST;
         goto err_freesocket;
     }
 
     *sockfd = fd;
-    freeaddrinfo(res);
-    return 0;
+    freeaddrinfo(addrinfo);
+    return ESP_OK;
 
 err_freesocket:
     close(fd);
 err_freeaddr:
-    freeaddrinfo(res);
+    freeaddrinfo(addrinfo);
     return ret;
 }
 
@@ -186,6 +192,7 @@ esp_err_t esp_tls_set_global_ca_store(const unsigned char *cacert_pem_buf, const
         return ESP_FAIL;
     } else if (ret > 0) {
         ESP_LOGE(TAG, "mbedtls_x509_crt_parse was partly successful. No. of failed certificates: %d", ret);
+        return ESP_ERR_MBEDTLS_CERT_PARTLY_OK;
     }
     return ESP_OK;
 }
@@ -209,6 +216,7 @@ static void verify_certificate(esp_tls_t *tls)
     char buf[100];
     if ((flags = mbedtls_ssl_get_verify_result(&tls->ssl)) != 0) {
         ESP_LOGI(TAG, "Failed to verify peer certificate!");
+        ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_MBEDTLS_CERT_FLAGS, flags);
         bzero(buf, sizeof(buf));
         mbedtls_x509_crt_verify_info(buf, sizeof(buf), "  ! ", flags);
         ESP_LOGI(TAG, "verification info: %s", buf);
@@ -239,20 +247,20 @@ static void mbedtls_cleanup(esp_tls_t *tls)
     mbedtls_ssl_free(&tls->ssl);
 }
 
-static int set_global_ca_store(esp_tls_t *tls)
+static esp_err_t set_global_ca_store(esp_tls_t *tls)
 {
     assert(tls);
     if (global_cacert == NULL) {
         ESP_LOGE(TAG, "global_cacert is NULL");
-        return -1;
+        return ESP_ERR_INVALID_STATE;
     }
     tls->cacert_ptr = global_cacert;
     mbedtls_ssl_conf_authmode(&tls->conf, MBEDTLS_SSL_VERIFY_REQUIRED);
     mbedtls_ssl_conf_ca_chain(&tls->conf, tls->cacert_ptr, NULL);
-    return 0;
+    return ESP_OK;
 }
 
-static int set_ca_cert(esp_tls_t *tls, const unsigned char *cacert, size_t cacert_len)
+static esp_err_t set_ca_cert(esp_tls_t *tls, const unsigned char *cacert, size_t cacert_len)
 {
     assert(tls);
     tls->cacert_ptr = &tls->cacert;
@@ -260,14 +268,15 @@ static int set_ca_cert(esp_tls_t *tls, const unsigned char *cacert, size_t cacer
     int ret = mbedtls_x509_crt_parse(tls->cacert_ptr, cacert, cacert_len);
     if (ret < 0) {
         ESP_LOGE(TAG, "mbedtls_x509_crt_parse returned -0x%x", -ret);
-        return ret;
+        ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_MBEDTLS, -ret);
+        return ESP_ERR_MBEDTLS_X509_CRT_PARSE_FAILED;
     }
     mbedtls_ssl_conf_authmode(&tls->conf, MBEDTLS_SSL_VERIFY_REQUIRED);
     mbedtls_ssl_conf_ca_chain(&tls->conf, tls->cacert_ptr, NULL);
-    return 0;
+    return ESP_OK;
 }
 
-static int set_pki_context(esp_tls_t *tls, const esp_tls_pki_t *pki)
+static esp_err_t set_pki_context(esp_tls_t *tls, const esp_tls_pki_t *pki)
 {
     assert(tls);
     assert(pki);
@@ -284,39 +293,44 @@ static int set_pki_context(esp_tls_t *tls, const esp_tls_pki_t *pki)
         ret = mbedtls_x509_crt_parse(pki->public_cert, pki->publiccert_pem_buf, pki->publiccert_pem_bytes);
         if (ret < 0) {
             ESP_LOGE(TAG, "mbedtls_x509_crt_parse returned -0x%x", -ret);
-            return ret;
+            ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_MBEDTLS, -ret);
+            return ESP_ERR_MBEDTLS_X509_CRT_PARSE_FAILED;
         }
 
         ret = mbedtls_pk_parse_key(pki->pk_key, pki->privkey_pem_buf, pki->privkey_pem_bytes,
                   NULL, 0);
         if (ret < 0) {
             ESP_LOGE(TAG, "mbedtls_pk_parse_keyfile returned -0x%x", -ret);
-            return ret;
+            ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_MBEDTLS, -ret);
+            return ESP_ERR_MBEDTLS_PK_PARSE_KEY_FAILED;
         }
 
         ret = mbedtls_ssl_conf_own_cert(&tls->conf, pki->public_cert, pki->pk_key);
         if (ret < 0) {
             ESP_LOGE(TAG, "mbedtls_ssl_conf_own_cert returned -0x%x", -ret);
-            return ret;
+            ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_MBEDTLS, -ret);
+            return ESP_ERR_MBEDTLS_SSL_CONF_OWN_CERT_FAILED;
         }
     } else {
         return ESP_ERR_INVALID_ARG;
     }
-    return 0;
+    return ESP_OK;
 }
 
 #ifdef CONFIG_ESP_TLS_SERVER
-static int set_server_config(esp_tls_cfg_server_t *cfg, esp_tls_t *tls)
+static esp_err_t set_server_config(esp_tls_cfg_server_t *cfg, esp_tls_t *tls)
 {
     assert(cfg != NULL);
     assert(tls != NULL);
     int ret;
+    esp_err_t esp_ret;
     if ((ret = mbedtls_ssl_config_defaults(&tls->conf,
                     MBEDTLS_SSL_IS_SERVER,
                     MBEDTLS_SSL_TRANSPORT_STREAM,
                     MBEDTLS_SSL_PRESET_DEFAULT)) != 0) {
         ESP_LOGE(TAG, "mbedtls_ssl_config_defaults returned %d", ret);
-        return ret;
+        ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_MBEDTLS, -ret);
+        return ESP_ERR_MBEDTLS_SSL_CONFIG_DEFAULTS_FAILED;
     }
 
 #ifdef CONFIG_MBEDTLS_SSL_ALPN
@@ -326,9 +340,9 @@ static int set_server_config(esp_tls_cfg_server_t *cfg, esp_tls_t *tls)
 #endif
 
     if (cfg->cacert_pem_buf != NULL) {
-        ret = set_ca_cert(tls, cfg->cacert_pem_buf, cfg->cacert_pem_bytes);
-        if (ret != 0) {
-            return ret;
+        esp_ret = set_ca_cert(tls, cfg->cacert_pem_buf, cfg->cacert_pem_bytes);
+        if (esp_ret != ESP_OK) {
+            return esp_ret;
         }
     } else {
         mbedtls_ssl_conf_authmode(&tls->conf, MBEDTLS_SSL_VERIFY_NONE);
@@ -345,20 +359,20 @@ static int set_server_config(esp_tls_cfg_server_t *cfg, esp_tls_t *tls)
             .privkey_password = cfg->serverkey_password,
             .privkey_password_len = cfg->serverkey_password_len,
         };
-        ret = set_pki_context(tls, &pki);
-        if (ret != 0) {
+        esp_ret = set_pki_context(tls, &pki);
+        if (esp_ret != ESP_OK) {
             ESP_LOGE(TAG, "Failed to set server pki context");
-            return ret;
+            return esp_ret;
         }
     } else {
         ESP_LOGE(TAG, "Missing server certificate and/or key");
-        return -1;
+        return ESP_ERR_INVALID_STATE;
     }
-    return 0;
+    return ESP_OK;
 }
 #endif /* ! CONFIG_ESP_TLS_SERVER */
 
-static int set_client_config(const char *hostname, size_t hostlen, esp_tls_cfg_t *cfg, esp_tls_t *tls)
+static esp_err_t set_client_config(const char *hostname, size_t hostlen, esp_tls_cfg_t *cfg, esp_tls_t *tls)
 {
     assert(cfg != NULL);
     assert(tls != NULL);
@@ -372,13 +386,14 @@ static int set_client_config(const char *hostname, size_t hostlen, esp_tls_cfg_t
         }
 
         if (use_host == NULL) {
-            return -1;
+            return ESP_ERR_NO_MEM;
         }
         /* Hostname set here should match CN in server certificate */
         if ((ret = mbedtls_ssl_set_hostname(&tls->ssl, use_host)) != 0) {
             ESP_LOGE(TAG, "mbedtls_ssl_set_hostname returned -0x%x", -ret);
+            ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_MBEDTLS, -ret);
             free(use_host);
-            return ret;
+            return ESP_ERR_MBEDTLS_SSL_SET_HOSTNAME_FAILED;
         }
         free(use_host);
     }
@@ -387,25 +402,29 @@ static int set_client_config(const char *hostname, size_t hostlen, esp_tls_cfg_t
                     MBEDTLS_SSL_IS_CLIENT,
                     MBEDTLS_SSL_TRANSPORT_STREAM,
                     MBEDTLS_SSL_PRESET_DEFAULT)) != 0) {
-        ESP_LOGE(TAG, "mbedtls_ssl_config_defaults returned %d", ret);
-        return ret;
+        ESP_LOGE(TAG, "mbedtls_ssl_config_defaults returned -0x%x", -ret);
+        ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_MBEDTLS, -ret);
+        return ESP_ERR_MBEDTLS_SSL_CONFIG_DEFAULTS_FAILED;
     }
 
 #ifdef CONFIG_MBEDTLS_SSL_ALPN
     if (cfg->alpn_protos) {
-        mbedtls_ssl_conf_alpn_protocols(&tls->conf, cfg->alpn_protos);
+        if ((ret =mbedtls_ssl_conf_alpn_protocols(&tls->conf, cfg->alpn_protos) != 0)) {
+            ESP_LOGE(TAG, "mbedtls_ssl_conf_alpn_protocols returned -0x%x", -ret);
+            ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_MBEDTLS, -ret);
+            return ESP_ERR_MBEDTLS_SSL_CONF_ALPN_PROTOCOLS_FAILED;
+        }
     }
 #endif
-
     if (cfg->use_global_ca_store == true) {
-        ret = set_global_ca_store(tls);
-        if (ret < 0) {
-            return ret;
+        esp_err_t esp_ret = set_global_ca_store(tls);
+        if (esp_ret != ESP_OK) {
+            return esp_ret;
         }
     } else if (cfg->cacert_pem_buf != NULL) {
-        ret = set_ca_cert(tls, cfg->cacert_pem_buf, cfg->cacert_pem_bytes);
-        if (ret < 0) {
-            return ret;
+        esp_err_t esp_ret = set_ca_cert(tls, cfg->cacert_pem_buf, cfg->cacert_pem_bytes);
+        if (esp_ret != ESP_OK) {
+            return esp_ret;
         }
     } else {
         mbedtls_ssl_conf_authmode(&tls->conf, MBEDTLS_SSL_VERIFY_NONE);
@@ -422,23 +441,24 @@ static int set_client_config(const char *hostname, size_t hostlen, esp_tls_cfg_t
             .privkey_password = cfg->clientkey_password,
             .privkey_password_len = cfg->clientkey_password_len,
         };
-        ret = set_pki_context(tls, &pki);
-        if (ret < 0) {
+        esp_err_t esp_ret = set_pki_context(tls, &pki);
+        if (esp_ret != ESP_OK) {
             ESP_LOGE(TAG, "Failed to set server pki context");
-            return ret;
+            return esp_ret;
         }
     } else if (cfg->clientcert_pem_buf != NULL || cfg->clientkey_pem_buf != NULL) {
         ESP_LOGE(TAG, "You have to provide both clientcert_pem_buf and clientkey_pem_buf for mutual authentication");
-        return -1;
+        return ESP_ERR_INVALID_STATE;
     }
-    return 0;
+    return ESP_OK;
 }
 
-static int create_ssl_handle(const char *hostname, size_t hostlen, const void *cfg, esp_tls_t *tls)
+static esp_err_t create_ssl_handle(const char *hostname, size_t hostlen, const void *cfg, esp_tls_t *tls)
 {
     assert(cfg != NULL);
     assert(tls != NULL);
     int ret;
+    esp_err_t esp_ret;
     tls->server_fd.fd = tls->sockfd;
     mbedtls_ssl_init(&tls->ssl);
     mbedtls_ctr_drbg_init(&tls->ctr_drbg);
@@ -446,15 +466,15 @@ static int create_ssl_handle(const char *hostname, size_t hostlen, const void *c
     mbedtls_entropy_init(&tls->entropy);
 
     if (tls->role == ESP_TLS_CLIENT) {
-        ret = set_client_config(hostname, hostlen, (esp_tls_cfg_t *)cfg, tls);
-        if (ret != 0) {
+        esp_ret = set_client_config(hostname, hostlen, (esp_tls_cfg_t *)cfg, tls);
+        if (esp_ret != ESP_OK) {
             ESP_LOGE(TAG, "Failed to set client configurations");
             goto exit;
         }
 #ifdef CONFIG_ESP_TLS_SERVER
     } else if (tls->role == ESP_TLS_SERVER) {
-        ret = set_server_config((esp_tls_cfg_server_t *) cfg, tls);
-        if (ret != 0) {
+        esp_ret = set_server_config((esp_tls_cfg_server_t *) cfg, tls);
+        if (esp_ret != 0) {
             ESP_LOGE(TAG, "Failed to set server configurations");
             goto exit;
         }
@@ -463,7 +483,9 @@ static int create_ssl_handle(const char *hostname, size_t hostlen, const void *c
 
     if ((ret = mbedtls_ctr_drbg_seed(&tls->ctr_drbg,
                     mbedtls_entropy_func, &tls->entropy, NULL, 0)) != 0) {
-        ESP_LOGE(TAG, "mbedtls_ctr_drbg_seed returned %d", ret);
+        ESP_LOGE(TAG, "mbedtls_ctr_drbg_seed returned -0x%x", -ret);
+        ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_MBEDTLS, -ret);
+        esp_ret = ESP_ERR_MBEDTLS_CTR_DRBG_SEED_FAILED;
         goto exit;
     }
 
@@ -475,14 +497,16 @@ static int create_ssl_handle(const char *hostname, size_t hostlen, const void *c
 
     if ((ret = mbedtls_ssl_setup(&tls->ssl, &tls->conf)) != 0) {
         ESP_LOGE(TAG, "mbedtls_ssl_setup returned -0x%x", -ret);
+        ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_MBEDTLS, -ret);
+        esp_ret = ESP_ERR_MBEDTLS_SSL_SETUP_FAILED;
         goto exit;
     }
     mbedtls_ssl_set_bio(&tls->ssl, &tls->server_fd, mbedtls_net_send, mbedtls_net_recv, NULL);
 
-    return 0;
+    return ESP_OK;
 exit:
     mbedtls_cleanup(tls);
-    return ret;
+    return esp_ret;
 }
 
 /**
@@ -497,6 +521,7 @@ void esp_tls_conn_delete(esp_tls_t *tls)
         } else if (tls->sockfd >= 0) {
             close(tls->sockfd);
         }
+        free(tls->error_handle);
         free(tls);
     }
 };
@@ -511,6 +536,8 @@ static ssize_t tls_write(esp_tls_t *tls, const char *data, size_t datalen)
     ssize_t ret = mbedtls_ssl_write(&tls->ssl, (unsigned char*) data, datalen);
     if (ret < 0) {
         if (ret != MBEDTLS_ERR_SSL_WANT_READ  && ret != MBEDTLS_ERR_SSL_WANT_WRITE) {
+            ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_MBEDTLS, -ret);
+            ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_ESP, ESP_ERR_MBEDTLS_SSL_WRITE_FAILED);
             ESP_LOGE(TAG, "write error :%d:", ret);
         }
     }
@@ -523,6 +550,9 @@ static int esp_tls_low_level_conn(const char *hostname, int hostlen, int port, c
         ESP_LOGE(TAG, "empty esp_tls parameter");
         return -1;
     }
+    esp_err_t esp_ret;
+    int ret;
+
     /* These states are used to keep a tab on connection progress in case of non-blocking connect,
     and in case of blocking connect these cases will get executed one after the other */
     switch (tls->conn_state) {
@@ -532,8 +562,8 @@ static int esp_tls_low_level_conn(const char *hostname, int hostlen, int port, c
                 mbedtls_net_init(&tls->server_fd);
                 tls->is_tls = true;
             }
-            int ret = esp_tcp_connect(hostname, hostlen, port, &tls->sockfd, cfg);
-            if (ret < 0) {
+            if ((esp_ret = esp_tcp_connect(hostname, hostlen, port, &tls->sockfd, tls, cfg)) != ESP_OK) {
+                ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_ESP, esp_ret);
                 return -1;
             }
             if (!cfg) {
@@ -568,15 +598,18 @@ static int esp_tls_low_level_conn(const char *hostname, int hostlen, int port, c
                     /* pending error check */
                     if (getsockopt(tls->sockfd, SOL_SOCKET, SO_ERROR, &error, &len) < 0) {
                         ESP_LOGD(TAG, "Non blocking connect failed");
+                        ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_SYSTEM, errno);
+                        ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_ESP, ESP_ERR_ESP_TLS_SOCKET_SETOPT_FAILED);
                         tls->conn_state = ESP_TLS_FAIL;
                         return -1;
                     }
                 }
             }
             /* By now, the connection has been established */
-            ret = create_ssl_handle(hostname, hostlen, cfg, tls);
-            if (ret != 0) {
-                ESP_LOGD(TAG, "create_ssl_handshake failed");
+            esp_ret = create_ssl_handle(hostname, hostlen, cfg, tls);
+            if (esp_ret != ESP_OK) {
+                ESP_LOGE(TAG, "create_ssl_handle failed");
+                ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_ESP, esp_ret);
                 tls->conn_state = ESP_TLS_FAIL;
                 return -1;
             }
@@ -593,6 +626,8 @@ static int esp_tls_low_level_conn(const char *hostname, int hostlen, int port, c
             } else {
                 if (ret != MBEDTLS_ERR_SSL_WANT_READ && ret != MBEDTLS_ERR_SSL_WANT_WRITE) {
                     ESP_LOGE(TAG, "mbedtls_ssl_handshake returned -0x%x", -ret);
+                    ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_MBEDTLS, ret);
+                    ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_ESP, ESP_ERR_MBEDTLS_SSL_HANDSHAKE_FAILED);
                     if (cfg->cacert_pem_buf != NULL || cfg->use_global_ca_store == true) {
                         /* This is to check whether handshake failed due to invalid certificate*/
                         verify_certificate(tls);
@@ -618,22 +653,17 @@ static int esp_tls_low_level_conn(const char *hostname, int hostlen, int port, c
 /**
  * @brief      Create a new TLS/SSL connection
  */
-esp_tls_t *esp_tls_conn_new(const char *hostname, int hostlen, int port, const esp_tls_cfg_t *cfg)
+int esp_tls_conn_new(const char *hostname, int hostlen, int port, const esp_tls_cfg_t *cfg, esp_tls_t *tls)
 {
-    esp_tls_t *tls = (esp_tls_t *)calloc(1, sizeof(esp_tls_t));
-    if (!tls) {
-        return NULL;
-    }
     /* esp_tls_conn_new() API establishes connection in a blocking manner thus this loop ensures that esp_tls_conn_new()
        API returns only after connection is established unless there is an error*/
     while (1) {
         int ret = esp_tls_low_level_conn(hostname, hostlen, port, cfg, tls);
         if (ret == 1) {
-            return tls;
+            return ret;
         } else if (ret == -1) {
-            esp_tls_conn_delete(tls);
             ESP_LOGE(TAG, "Failed to open new connection");
-            return NULL;
+            return -1;
         }
     }
     return NULL;
@@ -670,17 +700,21 @@ esp_tls_t *esp_tls_conn_http_new(const char *url, const esp_tls_cfg_t *cfg)
     struct http_parser_url u;
     http_parser_url_init(&u);
     http_parser_parse_url(url, strlen(url), 0, &u);
-
+    esp_tls_t *tls = esp_tls_init();
+    if (!tls) return NULL;
     /* Connect to host */
-    return esp_tls_conn_new(&url[u.field_data[UF_HOST].off], u.field_data[UF_HOST].len,
-			    get_port(url, &u), cfg);
+    if (esp_tls_conn_new(&url[u.field_data[UF_HOST].off], u.field_data[UF_HOST].len,
+                     get_port(url, &u), cfg, tls) == 1) {
+        return tls;
+    }
+    return NULL;
 }
 
-size_t esp_tls_get_bytes_avail(esp_tls_t *tls)
+ssize_t esp_tls_get_bytes_avail(esp_tls_t *tls)
 {
     if (!tls) {
         ESP_LOGE(TAG, "empty arg passed to esp_tls_get_bytes_avail()");
-        return ESP_FAIL;
+        return -1;
     }
     return mbedtls_ssl_get_bytes_avail(&tls->ssl);
 }
@@ -711,14 +745,16 @@ int esp_tls_server_session_create(esp_tls_cfg_server_t *cfg, int sockfd, esp_tls
     }
     tls->role = ESP_TLS_SERVER;
     tls->sockfd = sockfd;
-    int ret = create_ssl_handle(NULL, 0, cfg, tls);
-    if (ret != 0) {
-        ESP_LOGD(TAG, "create_ssl_handle failed");
+    esp_err_t esp_ret = create_ssl_handle(NULL, 0, cfg, tls);
+    if (esp_ret != ESP_OK) {
+        ESP_LOGE(TAG, "create_ssl_handle failed");
+        ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_ESP, esp_ret);
         tls->conn_state = ESP_TLS_FAIL;
-        return ret;
+        return -1;
     }
     tls->read = tls_read;
     tls->write = tls_write;
+    int ret;
     while ((ret = mbedtls_ssl_handshake(&tls->ssl)) != 0) {
         if (ret != MBEDTLS_ERR_SSL_WANT_READ && ret != MBEDTLS_ERR_SSL_WANT_WRITE) {
             ESP_LOGE(TAG, "mbedtls_ssl_handshake returned %d", ret);
@@ -739,3 +775,26 @@ void esp_tls_server_session_delete(esp_tls_t *tls)
     }
 };
 #endif /* ! CONFIG_ESP_TLS_SERVER */
+
+esp_tls_t *esp_tls_init()
+{
+    esp_tls_t *tls = (esp_tls_t *)calloc(1, sizeof(esp_tls_t));
+    if (!tls) {
+        return NULL;
+    }
+    tls->error_handle = calloc(1, sizeof(esp_err_t));
+    tls->server_fd.fd = tls->sockfd = -1;
+    return tls;
+}
+
+esp_err_t esp_tls_get_and_clear_last_error(esp_tls_t* tls)
+{
+    if (tls && tls->error_handle) {
+        esp_err_t last_err = tls->error_handle->last_error;
+        if (last_err != ESP_OK) {
+            tls->error_handle->last_error = ESP_OK;
+            return last_err;
+        }
+    }
+    return ESP_OK;
+}

components/esp-tls/esp_tls.h

@@ -31,6 +31,26 @@
 extern "C" {
 #endif
 
+#define ESP_ERR_ESP_TLS_BASE           0x8000             /*!< Starting number of ESP-TLS error codes */
+#define ESP_ERR_ESP_TLS_CANNOT_RESOLVE_HOSTNAME           (ESP_ERR_ESP_TLS_BASE + 0x01)  /*!< Error if hostname couldn't be resolved upon tls connection */
+#define ESP_ERR_ESP_TLS_CANNOT_CREATE_SOCKET              (ESP_ERR_ESP_TLS_BASE + 0x02)  /*!< Failed to create socket */
+#define ESP_ERR_ESP_TLS_UNSUPPORTED_PROTOCOL_FAMILY       (ESP_ERR_ESP_TLS_BASE + 0x03)  /*!< Unsupported protocol family */
+#define ESP_ERR_ESP_TLS_FAILED_CONNECT_TO_HOST            (ESP_ERR_ESP_TLS_BASE + 0x04)  /*!< Failed to connnect to host */
+#define ESP_ERR_ESP_TLS_SOCKET_SETOPT_FAILED              (ESP_ERR_ESP_TLS_BASE + 0x05)  /*!< failed to set socket option */
+#define ESP_ERR_MBEDTLS_CERT_PARTLY_OK                    (ESP_ERR_ESP_TLS_BASE + 0x06)  /*!< embedtls parse certificates was partly successful */
+#define ESP_ERR_MBEDTLS_CTR_DRBG_SEED_FAILED              (ESP_ERR_ESP_TLS_BASE + 0x07)  /*!< embedtls api returned failed  */
+#define ESP_ERR_MBEDTLS_SSL_SET_HOSTNAME_FAILED           (ESP_ERR_ESP_TLS_BASE + 0x08)  /*!< embedtls api returned failed  */
+#define ESP_ERR_MBEDTLS_SSL_CONFIG_DEFAULTS_FAILED        (ESP_ERR_ESP_TLS_BASE + 0x09)  /*!< embedtls api returned failed  */
+#define ESP_ERR_MBEDTLS_SSL_CONF_ALPN_PROTOCOLS_FAILED    (ESP_ERR_ESP_TLS_BASE + 0x0A)  /*!< embedtls api returned failed  */
+#define ESP_ERR_MBEDTLS_X509_CRT_PARSE_FAILED             (ESP_ERR_ESP_TLS_BASE + 0x0B)  /*!< embedtls api returned failed  */
+#define ESP_ERR_MBEDTLS_SSL_CONF_OWN_CERT_FAILED          (ESP_ERR_ESP_TLS_BASE + 0x0C)  /*!< embedtls api returned failed  */
+#define ESP_ERR_MBEDTLS_SSL_SETUP_FAILED                  (ESP_ERR_ESP_TLS_BASE + 0x0D)  /*!< embedtls api returned failed  */
+#define ESP_ERR_MBEDTLS_SSL_WRITE_FAILED                  (ESP_ERR_ESP_TLS_BASE + 0x0E)  /*!< embedtls api returned failed  */
+#define ESP_ERR_MBEDTLS_PK_PARSE_KEY_FAILED               (ESP_ERR_ESP_TLS_BASE + 0x0F)  /*!< embedtls api returned failed  */
+#define ESP_ERR_MBEDTLS_SSL_HANDSHAKE_FAILED              (ESP_ERR_ESP_TLS_BASE + 0x10)  /*!< embedtls api returned failed  */
+
+typedef struct esp_error_private* esp_error_handle_t;
+
 /**
  *  @brief ESP-TLS Connection State
  */
@@ -186,8 +206,22 @@ typedef struct esp_tls {
     esp_tls_role_t role;                                                        /*!< esp-tls role
                                                                                      - ESP_TLS_CLIENT
                                                                                      - ESP_TLS_SERVER */
+
+    esp_error_handle_t error_handle;                                            /*!< handle to internal error descriptor */
+
 } esp_tls_t;
 
+
+/**
+ * @brief      Create TLS connection
+ *
+ * This function allocates and initializes esp-tls structure handle.
+ *
+ * @return      tls     Pointer to esp-tls as esp-tls handle if successfully initialized,
+ *                      NULL if allocation error
+ */
+esp_tls_t *esp_tls_init();
+
 /**
  * @brief      Create a new blocking TLS/SSL connection
  *
@@ -200,9 +234,14 @@ typedef struct esp_tls {
  *                       non-TLS connection, keep this NULL. For TLS connection,
  *                       a pass pointer to esp_tls_cfg_t. At a minimum, this
  *                       structure should be zero-initialized.
- * @return pointer to esp_tls_t, or NULL if connection couldn't be opened.
+ * @param[in]  tls       Pointer to esp-tls as esp-tls handle.
+ *
+ * @return
+ *             - -1      If connection establishment fails.
+ *             -  1      If connection establishment is successful.
+ *             -  0      Reserved for connection state is in progress.
  */
-esp_tls_t *esp_tls_conn_new(const char *hostname, int hostlen, int port, const esp_tls_cfg_t *cfg);
+int esp_tls_conn_new(const char *hostname, int hostlen, int port, const esp_tls_cfg_t *cfg, esp_tls_t *tls);
 
 /**
  * @brief      Create a new blocking TLS/SSL connection with a given "HTTP" url
@@ -317,7 +356,7 @@ void esp_tls_conn_delete(esp_tls_t *tls);
  *            - bytes available in the application data
  *              record read buffer
  */
-size_t esp_tls_get_bytes_avail(esp_tls_t *tls);
+ssize_t esp_tls_get_bytes_avail(esp_tls_t *tls);
 
 /**
  * @brief      Create a global CA store, initially empty.
@@ -373,6 +412,17 @@ mbedtls_x509_crt *esp_tls_get_global_ca_store();
  */
 void esp_tls_free_global_ca_store();
 
+/**
+ * @brief      Returns last error in esp_tls (if any) and clears it.
+ *
+ * @param[in]  tls  pointer to esp-tls as esp-tls handle.
+ *
+ * @return
+ *            - ESP_OK if no error occurred
+ *            - specific error code (based on ESP_ERR_ESP_TLS_BASE) otherwise
+ */
+esp_err_t esp_tls_get_and_clear_last_error(esp_tls_t* tls);
+
 #ifdef CONFIG_ESP_TLS_SERVER
 /**
  * @brief      Create TLS/SSL server session

components/esp-tls/private_include/esp_tls_error_capture_internal.h

@@ -0,0 +1,48 @@
+// Copyright 2017-2019 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef __ESP_TLS_ERROR_CAPTURE_INTERNAL_H__
+#define __ESP_TLS_ERROR_CAPTURE_INTERNAL_H__
+/**
+* Note: this is an implementation placeholder for error logger.
+* This version is internal to esp-tls component and only saves single esp_err of last occurred error
+*/
+
+
+/**
+* Definition of different types/sources of error codes reported
+* from different components
+*/
+typedef enum {
+    ERR_TYPE_UNKNOWN = 0,
+    ERR_TYPE_SYSTEM,
+    ERR_TYPE_MBEDTLS,
+    ERR_TYPE_MBEDTLS_CERT_FLAGS,
+    ERR_TYPE_ESP,
+} err_type_t;
+
+/**
+* Internal structure for error description
+* - contains only the last error of esp_err_t in this implementation
+*/
+typedef struct esp_error_private {
+    esp_err_t last_error;
+} esp_error_private_t;
+
+/**
+ * Error tracker logging macro, this implementation only saves the ERR_TYPE_ESP error, other types are ignored
+ */
+#define ESP_INT_EVENT_TRACKER_CAPTURE(h, type, code)    do { if (h && type==ERR_TYPE_ESP) { h->last_error = code; } } while (0)
+
+#endif //__ESP_TLS_ERROR_CAPTURE_INTERNAL_H__

components/mqtt/esp-mqtt

@@ -1 +1 @@
-Subproject commit 11f884623bd32cb4269f24f47847f5d046da93f5
+Subproject commit 65bf2255d74c79e3c6abe3e3f791ba8d42efdee3

components/tcp_transport/include/esp_transport.h

@@ -22,7 +22,7 @@ extern "C" {
 #endif
 
 
-typedef struct esp_transport_list_t* esp_transport_list_handle_t;
+typedef struct esp_transport_internal* esp_transport_list_handle_t;
 typedef struct esp_transport_item_t* esp_transport_handle_t;
 
 typedef int (*connect_func)(esp_transport_handle_t t, const char *host, int port, int timeout_ms);
@@ -298,6 +298,25 @@ esp_err_t esp_transport_set_async_connect_func(esp_transport_handle_t t, connect
  */
 esp_err_t esp_transport_set_parent_transport_func(esp_transport_handle_t t, payload_transfer_func _parent_transport);
 
+/**
+ * @brief      Returns last error in esp_tls (if any) and clears it.
+ *
+ * @param[in]  A transport handle
+ *
+ * @return
+ *            - ESP_OK if no error occurred
+ *            - specific error code (based on ESP_ERR_ESP_TLS_BASE) otherwise
+  */
+esp_err_t get_and_clear_last_error(esp_transport_handle_t t);
+
+/**
+ * @brief      Sets error to common transport handle
+ *
+ * @param[in]  A transport handle
+ *
+ */
+void esp_transport_set_error(esp_transport_handle_t t, esp_err_t err);
+
 #ifdef __cplusplus
 }
 #endif

components/tcp_transport/transport.c

@@ -41,7 +41,8 @@ struct esp_transport_item_t {
     poll_func       _poll_write;    /*!< Poll and write */
     trans_func      _destroy;       /*!< Destroy and free transport */
     connect_async_func _connect_async;      /*!< non-blocking connect function of this transport */
-    payload_transfer_func  _parent_transfer;       /*!< Function returning underlying transport layer */
+    payload_transfer_func  _parent_transfer;        /*!< Function returning underlying transport layer */
+    esp_err_t* error_handle;                         /*!< Pointer to the last error */
 
     STAILQ_ENTRY(esp_transport_item_t) next;
 };
@@ -52,6 +53,14 @@ struct esp_transport_item_t {
  */
 STAILQ_HEAD(esp_transport_list_t, esp_transport_item_t);
 
+/**
+ * Internal transport structure holding list of transports and other data common to all transports
+ */
+typedef struct esp_transport_internal {
+    struct esp_transport_list_t list;                      /*!< List of transports */
+    esp_err_t* error_handle;                               /*!< Pointer to the error tracker if enabled  */
+} esp_transport_internal_t;
+
 static esp_transport_handle_t esp_transport_get_default_parent(esp_transport_handle_t t)
 {
     /*
@@ -62,34 +71,37 @@ static esp_transport_handle_t esp_transport_get_default_parent(esp_transport_han
 
 esp_transport_list_handle_t esp_transport_list_init()
 {
-    esp_transport_list_handle_t list = calloc(1, sizeof(struct esp_transport_list_t));
-    ESP_TRANSPORT_MEM_CHECK(TAG, list, return NULL);
-    STAILQ_INIT(list);
-    return list;
+    esp_transport_list_handle_t transport = calloc(1, sizeof(esp_transport_internal_t));
+    ESP_TRANSPORT_MEM_CHECK(TAG, transport, return NULL);
+    STAILQ_INIT(&transport->list);
+    transport->error_handle = calloc(1, sizeof(esp_err_t));
+    return transport;
 }
 
-esp_err_t esp_transport_list_add(esp_transport_list_handle_t list, esp_transport_handle_t t, const char *scheme)
+esp_err_t esp_transport_list_add(esp_transport_list_handle_t h, esp_transport_handle_t t, const char *scheme)
 {
-    if (list == NULL || t == NULL) {
+    if (h == NULL || t == NULL) {
         return ESP_ERR_INVALID_ARG;
     }
     t->scheme = calloc(1, strlen(scheme) + 1);
     ESP_TRANSPORT_MEM_CHECK(TAG, t->scheme, return ESP_ERR_NO_MEM);
     strcpy(t->scheme, scheme);
-    STAILQ_INSERT_TAIL(list, t, next);
+    STAILQ_INSERT_TAIL(&h->list, t, next);
+    // Each transport in a list to share the same error tracker
+    t->error_handle =  h->error_handle;
     return ESP_OK;
 }
 
-esp_transport_handle_t esp_transport_list_get_transport(esp_transport_list_handle_t list, const char *scheme)
+esp_transport_handle_t esp_transport_list_get_transport(esp_transport_list_handle_t h, const char *scheme)
 {
-    if (!list) {
+    if (!h) {
         return NULL;
     }
     if (scheme == NULL) {
-        return STAILQ_FIRST(list);
+        return STAILQ_FIRST(&h->list);
     }
     esp_transport_handle_t item;
-    STAILQ_FOREACH(item, list, next) {
+    STAILQ_FOREACH(item, &h->list, next) {
         if (strcasecmp(item->scheme, scheme) == 0) {
             return item;
         }
@@ -97,16 +109,17 @@ esp_transport_handle_t esp_transport_list_get_transport(esp_transport_list_handl
     return NULL;
 }
 
-esp_err_t esp_transport_list_destroy(esp_transport_list_handle_t list)
+esp_err_t esp_transport_list_destroy(esp_transport_list_handle_t h)
 {
-    esp_transport_list_clean(list);
-    free(list);
+    esp_transport_list_clean(h);
+    free(h->error_handle);
+    free(h);
     return ESP_OK;
 }
 
-esp_err_t esp_transport_list_clean(esp_transport_list_handle_t list)
+esp_err_t esp_transport_list_clean(esp_transport_list_handle_t h)
 {
-    esp_transport_handle_t item = STAILQ_FIRST(list);
+    esp_transport_handle_t item = STAILQ_FIRST(&h->list);
     esp_transport_handle_t tmp;
     while (item != NULL) {
         tmp = STAILQ_NEXT(item, next);
@@ -116,7 +129,7 @@ esp_err_t esp_transport_list_clean(esp_transport_list_handle_t list)
         esp_transport_destroy(item);
         item = tmp;
     }
-    STAILQ_INIT(list);
+    STAILQ_INIT(&h->list);
     return ESP_OK;
 }
 
@@ -277,3 +290,18 @@ esp_err_t esp_transport_set_parent_transport_func(esp_transport_handle_t t, payl
     t->_parent_transfer = _parent_transport;
     return ESP_OK;
 }
+
+esp_err_t get_and_clear_last_error(esp_transport_handle_t t)
+{
+    esp_err_t err = *(t->error_handle);
+    *(t->error_handle) = 0;
+    return err;
+}
+
+void esp_transport_set_error(esp_transport_handle_t t, esp_err_t err)
+{
+    if (t)  {
+        *t->error_handle = err;
+    }
+    return NULL;
+}

components/tcp_transport/transport_ssl.c

@@ -51,7 +51,7 @@ static int ssl_connect_async(esp_transport_handle_t t, const char *host, int por
         ssl->cfg.timeout_ms = timeout_ms;
         ssl->cfg.non_block = true;
         ssl->ssl_initialized = true;
-        ssl->tls = calloc(1, sizeof(esp_tls_t));
+        ssl->tls = esp_tls_init();
         if (!ssl->tls) {
             return -1;
         }
@@ -69,9 +69,12 @@ static int ssl_connect(esp_transport_handle_t t, const char *host, int port, int
 
     ssl->cfg.timeout_ms = timeout_ms;
     ssl->ssl_initialized = true;
-    ssl->tls = esp_tls_conn_new(host, strlen(host), port, &ssl->cfg);
-    if (!ssl->tls) {
+    ssl->tls = esp_tls_init();
+    if (esp_tls_conn_new(host, strlen(host), port, &ssl->cfg, ssl->tls) < 0) {
         ESP_LOGE(TAG, "Failed to open a new connection");
+        esp_transport_set_error(t, esp_tls_get_and_clear_last_error(ssl->tls));
+        esp_tls_conn_delete(ssl->tls);
+        ssl->tls = NULL;
         return -1;
     }
     return 0;
@@ -112,7 +115,7 @@ static int ssl_write(esp_transport_handle_t t, const char *buffer, int len, int
     ret = esp_tls_conn_write(ssl->tls, (const unsigned char *) buffer, len);
     if (ret < 0) {
         ESP_LOGE(TAG, "esp_tls_conn_write error, errno=%s", strerror(errno));
-        return -1;
+        esp_transport_set_error(t, esp_tls_get_and_clear_last_error(ssl->tls));
     }
     return ret;
 }
@@ -130,7 +133,7 @@ static int ssl_read(esp_transport_handle_t t, char *buffer, int len, int timeout
     ret = esp_tls_conn_read(ssl->tls, (unsigned char *)buffer, len);
     if (ret < 0) {
         ESP_LOGE(TAG, "esp_tls_conn_read error, errno=%s", strerror(errno));
-        return -1;
+        esp_transport_set_error(t, esp_tls_get_and_clear_last_error(ssl->tls));
     }
     if (ret == 0) {
         ret = -1;

examples/protocols/mqtt/ssl/main/app_main.c

@@ -79,6 +79,7 @@ static esp_err_t mqtt_event_handler_cb(esp_mqtt_event_handle_t event)
             break;
         case MQTT_EVENT_ERROR:
             ESP_LOGI(TAG, "MQTT_EVENT_ERROR");
+            ESP_LOGI(TAG, "Error code: 0x%x", event->last_err);
             break;
         default:
             ESP_LOGI(TAG, "Other event id:%d", event->event_id);