esp_tls: enable psk verification mode, added mqtt example using psk authentication

components/esp-tls/Kconfig

@@ -5,5 +5,16 @@ menu "ESP-TLS"
         help
             Enable support for creating server side SSL/TLS session
 
+    config ESP_TLS_PSK_VERIFICATION
+        bool "Enable PSK verification"
+        select MBEDTLS_PSK_MODES
+        select MBEDTLS_KEY_EXCHANGE_PSK
+        select MBEDTLS_KEY_EXCHANGE_DHE_PSK
+        select MBEDTLS_KEY_EXCHANGE_ECDHE_PSK
+        select MBEDTLS_KEY_EXCHANGE_RSA_PSK
+        default n
+        help
+            Enable support for pre shared key ciphers
+
 endmenu
 

components/esp-tls/esp_tls.c

@@ -426,6 +426,23 @@ static esp_err_t set_client_config(const char *hostname, size_t hostlen, esp_tls
         if (esp_ret != ESP_OK) {
             return esp_ret;
         }
+        mbedtls_ssl_conf_ca_chain(&tls->conf, tls->cacert_ptr, NULL);
+    } else if (cfg->psk_hint_key) {
+#if defined(CONFIG_ESP_TLS_PSK_VERIFICATION)
+        //
+        // PSK encryption mode is configured only if no certificate supplied and psk pointer not null
+        ESP_LOGD(TAG, "ssl psk authentication");
+        ret = mbedtls_ssl_conf_psk(&tls->conf, cfg->psk_hint_key->key, cfg->psk_hint_key->key_size,
+                           (const unsigned char *)cfg->psk_hint_key->hint, strlen(cfg->psk_hint_key->hint));
+        if (ret != 0) {
+            ESP_LOGE(TAG, "mbedtls_ssl_conf_psk returned -0x%x", -ret);
+            ESP_INT_EVENT_TRACKER_CAPTURE(tls->error_handle, ERR_TYPE_MBEDTLS, -ret);
+            return ESP_ERR_MBEDTLS_SSL_CONF_PSK_FAILED;            
+        }
+#else
+        ESP_LOGE(TAG, "psk_hint_key configured but not enabled in menuconfig: Please enable ESP_TLS_PSK_VERIFICATION option");
+        return ESP_ERR_INVALID_STATE;
+#endif
     } else {
         mbedtls_ssl_conf_authmode(&tls->conf, MBEDTLS_SSL_VERIFY_NONE);
     }
@@ -443,7 +460,7 @@ static esp_err_t set_client_config(const char *hostname, size_t hostlen, esp_tls
         };
         esp_err_t esp_ret = set_pki_context(tls, &pki);
         if (esp_ret != ESP_OK) {
-            ESP_LOGE(TAG, "Failed to set server pki context");
+            ESP_LOGE(TAG, "Failed to set client pki context");
             return esp_ret;
         }
     } else if (cfg->clientcert_buf != NULL || cfg->clientkey_buf != NULL) {

components/esp-tls/esp_tls.h

@@ -48,6 +48,7 @@ extern "C" {
 #define ESP_ERR_MBEDTLS_SSL_WRITE_FAILED                  (ESP_ERR_ESP_TLS_BASE + 0x0E)  /*!< mbedtls api returned error */
 #define ESP_ERR_MBEDTLS_PK_PARSE_KEY_FAILED               (ESP_ERR_ESP_TLS_BASE + 0x0F)  /*!< mbedtls api returned failed  */
 #define ESP_ERR_MBEDTLS_SSL_HANDSHAKE_FAILED              (ESP_ERR_ESP_TLS_BASE + 0x10)  /*!< mbedtls api returned failed  */
+#define ESP_ERR_MBEDTLS_SSL_CONF_PSK_FAILED               (ESP_ERR_ESP_TLS_BASE + 0x11)  /*!< mbedtls api returned failed  */
 
 typedef struct esp_tls_last_error* esp_tls_error_handle_t;
 
@@ -76,6 +77,15 @@ typedef enum esp_tls_role {
     ESP_TLS_SERVER,
 } esp_tls_role_t;
 
+/**
+ *  @brief ESP-TLS preshared key and hint structure
+ */
+typedef struct psk_key_hint {
+    const uint8_t* key;                     /*!< key in PSK authentication mode in binary format */
+    const size_t   key_size;                /*!< length of the key */
+    const char* hint;                       /*!< hint in PSK authentication mode in string format */
+} psk_hint_key_t;
+
 /**
  * @brief      ESP-TLS configuration parameters 
  * 
@@ -159,6 +169,11 @@ typedef struct esp_tls_cfg {
                                                  If NULL, server certificate CN must match hostname. */
 
     bool skip_common_name;                  /*!< Skip any validation of server certificate CN field */
+
+    const psk_hint_key_t* psk_hint_key;     /*!< Pointer to PSK hint and key. if not NULL (and certificates are NULL)
+                                                 then PSK authentication is enabled with configured setup.
+                                                 Important note: the pointer must be valid for connection */
+
 } esp_tls_cfg_t;
 
 #ifdef CONFIG_ESP_TLS_SERVER

components/mqtt/esp-mqtt

@@ -1 +1 @@
-Subproject commit dc37d3a065f345a7358b8ff4553db0baceeb8ad6
+Subproject commit 117eef2dad54e0f9e25b3005fcfc18e7695ff29e

components/tcp_transport/include/esp_transport_ssl.h

@@ -16,6 +16,7 @@
 #define _ESP_TRANSPORT_SSL_H_
 
 #include "esp_transport.h"
+#include "esp_tls.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -111,6 +112,20 @@ void esp_transport_ssl_set_client_key_data_der(esp_transport_handle_t t, const c
  */
 void esp_transport_ssl_skip_common_name_check(esp_transport_handle_t t);
 
+/**
+ * @brief      Set PSK key and hint for PSK server/client verification in esp-tls component.
+ *             Important notes:
+ *             - This function stores the pointer to data, rather than making a copy.
+ *             So this data must remain valid until after the connection is cleaned up
+ *             - ESP_TLS_PSK_VERIFICATION config option must be enabled in menuconfig
+ *             - certificate verification takes priority so it must not be configured
+ *             to enable PSK method.
+ *
+ * @param      t             ssl transport
+ * @param[in]  psk_hint_key  psk key and hint structure defined in esp_tls.h
+ */
+void esp_transport_ssl_set_psk_key_hint(esp_transport_handle_t t, const psk_hint_key_t* psk_hint_key);
+
 #ifdef __cplusplus
 }
 #endif

components/tcp_transport/transport_ssl.c

@@ -169,6 +169,14 @@ void esp_transport_ssl_enable_global_ca_store(esp_transport_handle_t t)
     }
 }
 
+void esp_transport_ssl_set_psk_key_hint(esp_transport_handle_t t, const psk_hint_key_t* psk_hint_key)
+{
+    transport_ssl_t *ssl = esp_transport_get_context_data(t);
+    if (t && ssl) {
+        ssl->cfg.psk_hint_key =  psk_hint_key;
+    }
+}
+
 void esp_transport_ssl_set_cert_data(esp_transport_handle_t t, const char *data, int len)
 {
     transport_ssl_t *ssl = esp_transport_get_context_data(t);

examples/protocols/mqtt/ssl_psk/CMakeLists.txt

@@ -0,0 +1,10 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+# (Not part of the boilerplate)
+# This example uses an extra component for common functions such as Wi-Fi and Ethernet connection.
+set(EXTRA_COMPONENT_DIRS $ENV{IDF_PATH}/examples/common_components/protocol_examples_common)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(mqtt_ssl_psk)

examples/protocols/mqtt/ssl_psk/Makefile

@@ -0,0 +1,9 @@
+#
+# This is a project Makefile. It is assumed the directory this Makefile resides in is a
+# project subdirectory.
+#
+PROJECT_NAME := mqtt_ssl_psk
+
+EXTRA_COMPONENT_DIRS = $(IDF_PATH)/examples/common_components/protocol_examples_common
+
+include $(IDF_PATH)/make/project.mk

examples/protocols/mqtt/ssl_psk/README.md

@@ -0,0 +1,76 @@
+# ESP-MQTT SSL example with PSK verification 
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+This example connects to a local broker configured to PSK authentication
+
+## How to use example
+
+### Hardware Required
+
+This example can be executed on any ESP32 board, the only required interface is WiFi (or ethernet) to connect to a MQTT 
+broker with preconfigured PSK verification method.
+
+#### Mosquitto settings
+In case of using mosquitto broker, here is how to enable PSK authentication in `mosquitto.config`, 
+```
+psk_hint hint
+psk_file path_to_your_psk_file
+allow_anonymous true
+```
+Note: Last line enables anonymous mode, as this example does not use mqtt username and password.
+
+PSK file then has to contain pairs of hints and keys, as shown below:
+```
+hint:BAD123
+```
+
+Important note: Keys are stored as text hexadecimal values in PSK file, while the example code stores key as plain binary
+as required by MQTT API. (See the example source for details: `"BAD123" -> 0xBA, 0xD1, 0x23`)
+
+### Configure the project
+
+* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system)
+* Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details.
+* When using Make build system, set `Default serial port` under `Serial flasher config`.
+
+### Build and Flash
+
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+```
+I (2160) example_connect: Ethernet Link Up
+I (4650) example_connect: Connected to Ethernet
+I (4650) example_connect: IPv4 address: 192.168.0.1
+I (4650) MQTTS_EXAMPLE: [APP] Free memory: 244792 bytes
+I (4660) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
+D (4670) MQTT_CLIENT: MQTT client_id=ESP32_c6B4F8
+D (4680) MQTT_CLIENT: Core selection disabled
+I (4680) MQTTS_EXAMPLE: Other event id:7
+D (4680) esp-tls: host:192.168.0.2: strlen 13
+D (4700) esp-tls: ssl psk authentication
+D (4700) esp-tls: handshake in progress...
+D (4720) MQTT_CLIENT: Transport connected to mqtts://192.168.0.2:8883
+I (4720) MQTT_CLIENT: Sending MQTT CONNECT message, type: 1, id: 0000
+D (4720) MQTT_CLIENT: mqtt_message_receive: first byte: 0x20
+D (4730) MQTT_CLIENT: mqtt_message_receive: read "remaining length" byte: 0x2
+D (4730) MQTT_CLIENT: mqtt_message_receive: total message length: 4 (already read: 2)
+D (4740) MQTT_CLIENT: mqtt_message_receive: read_len=2
+D (4750) MQTT_CLIENT: mqtt_message_receive: transport_read():4 4
+D (4750) MQTT_CLIENT: Connected
+I (4760) MQTTS_EXAMPLE: MQTT_EVENT_CONNECTED
+D (4760) MQTT_CLIENT: mqtt_enqueue id: 4837, type=8 successful
+D (4770) OUTBOX: ENQUEUE msgid=4837, msg_type=8, len=18, size=18
+D (4770) MQTT_CLIENT: Sent subscribe topic=/topic/qos0, id: 4837, type=8 successful
+I (4780) MQTTS_EXAMPLE: sent subscribe successful, msg_id=4837
+D (4790) MQTT_CLIENT: mqtt_enqueue id: 58982, type=8 successful
+D (4790) OUTBOX: ENQUEUE msgid=58982, msg_type=8, len=18, size=36
+D (4800) MQTT_CLIENT: Sent subscribe topic=/topic/qos1, id: 58982, type=8 successful
+I (4810) MQTTS_EXAMPLE: sent subscribe successful, msg_id=58982
+```
+

examples/protocols/mqtt/ssl_psk/main/CMakeLists.txt

@@ -0,0 +1,4 @@
+set(COMPONENT_SRCS "app_main.c")
+set(COMPONENT_ADD_INCLUDEDIRS ".")
+
+register_component()

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

@@ -0,0 +1,141 @@
+/* MQTT over SSL Example
+
+   This example code is in the Public Domain (or CC0 licensed, at your option.)
+
+   Unless required by applicable law or agreed to in writing, this
+   software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+   CONDITIONS OF ANY KIND, either express or implied.
+*/
+
+#include <stdio.h>
+#include <stdint.h>
+#include <stddef.h>
+#include <string.h>
+#include "esp_wifi.h"
+#include "esp_system.h"
+#include "nvs_flash.h"
+#include "esp_event.h"
+#include "tcpip_adapter.h"
+#include "protocol_examples_common.h"
+
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/semphr.h"
+#include "freertos/queue.h"
+
+#include "lwip/sockets.h"
+#include "lwip/dns.h"
+#include "lwip/netdb.h"
+
+#include "esp_log.h"
+#include "mqtt_client.h"
+#include "esp_tls.h"
+
+/*
+ * Add here URI of mqtt broker which supports PSK authentication
+ */
+#define EXAMPLE_BROKER_URI "mqtts://192.168.0.2"
+
+static const char *TAG = "MQTTS_EXAMPLE";
+
+/*
+ * Define psk key and hint as defined in mqtt broker
+ * example for mosquitto server, content of psk_file:
+ * hint:BAD123
+ *
+ */
+static const uint8_t s_key[] = { 0xBA, 0xD1, 0x23 };
+
+static const psk_hint_key_t psk_hint_key = {
+        .key = s_key,
+        .key_size = sizeof(s_key),
+        .hint = "hint"
+        };
+
+static esp_err_t mqtt_event_handler(esp_mqtt_event_handle_t event)
+{
+    esp_mqtt_client_handle_t client = event->client;
+    int msg_id;
+    // your_context_t *context = event->context;
+    switch (event->event_id) {
+        case MQTT_EVENT_CONNECTED:
+            ESP_LOGI(TAG, "MQTT_EVENT_CONNECTED");
+            msg_id = esp_mqtt_client_subscribe(client, "/topic/qos0", 0);
+            ESP_LOGI(TAG, "sent subscribe successful, msg_id=%d", msg_id);
+
+            msg_id = esp_mqtt_client_subscribe(client, "/topic/qos1", 1);
+            ESP_LOGI(TAG, "sent subscribe successful, msg_id=%d", msg_id);
+
+            msg_id = esp_mqtt_client_unsubscribe(client, "/topic/qos1");
+            ESP_LOGI(TAG, "sent unsubscribe successful, msg_id=%d", msg_id);
+            break;
+        case MQTT_EVENT_DISCONNECTED:
+            ESP_LOGI(TAG, "MQTT_EVENT_DISCONNECTED");
+            break;
+
+        case MQTT_EVENT_SUBSCRIBED:
+            ESP_LOGI(TAG, "MQTT_EVENT_SUBSCRIBED, msg_id=%d", event->msg_id);
+            msg_id = esp_mqtt_client_publish(client, "/topic/qos0", "data", 0, 0, 0);
+            ESP_LOGI(TAG, "sent publish successful, msg_id=%d", msg_id);
+            break;
+        case MQTT_EVENT_UNSUBSCRIBED:
+            ESP_LOGI(TAG, "MQTT_EVENT_UNSUBSCRIBED, msg_id=%d", event->msg_id);
+            break;
+        case MQTT_EVENT_PUBLISHED:
+            ESP_LOGI(TAG, "MQTT_EVENT_PUBLISHED, msg_id=%d", event->msg_id);
+            break;
+        case MQTT_EVENT_DATA:
+            ESP_LOGI(TAG, "MQTT_EVENT_DATA");
+            printf("TOPIC=%.*s\r\n", event->topic_len, event->topic);
+            printf("DATA=%.*s\r\n", event->data_len, event->data);
+            break;
+        case MQTT_EVENT_ERROR:
+            ESP_LOGI(TAG, "MQTT_EVENT_ERROR");
+            break;
+        default:
+            ESP_LOGI(TAG, "Other event id:%d", event->event_id);
+            break;
+    }
+    return ESP_OK;
+}
+
+
+static void mqtt_app_start(void)
+{
+    const esp_mqtt_client_config_t mqtt_cfg = {
+        .uri = EXAMPLE_BROKER_URI,
+        .event_handle = mqtt_event_handler,
+        .psk_hint_key = &psk_hint_key,
+    };
+
+    ESP_LOGI(TAG, "[APP] Free memory: %d bytes", esp_get_free_heap_size());
+    esp_mqtt_client_handle_t client = esp_mqtt_client_init(&mqtt_cfg);
+    esp_mqtt_client_start(client);
+}
+
+void app_main(void)
+{
+    ESP_LOGI(TAG, "[APP] Startup..");
+    ESP_LOGI(TAG, "[APP] Free memory: %d bytes", esp_get_free_heap_size());
+    ESP_LOGI(TAG, "[APP] IDF version: %s", esp_get_idf_version());
+
+    esp_log_level_set("*", ESP_LOG_INFO);
+    esp_log_level_set("MQTT_CLIENT", ESP_LOG_VERBOSE);
+    esp_log_level_set("TRANSPORT_TCP", ESP_LOG_VERBOSE);
+    esp_log_level_set("TRANSPORT_SSL", ESP_LOG_VERBOSE);
+    esp_log_level_set("esp-tls", ESP_LOG_VERBOSE);
+    esp_log_level_set("TRANSPORT", ESP_LOG_VERBOSE);
+    esp_log_level_set("OUTBOX", ESP_LOG_VERBOSE);
+
+    ESP_ERROR_CHECK(nvs_flash_init());
+    tcpip_adapter_init();
+    ESP_ERROR_CHECK(esp_event_loop_create_default());
+
+    /* This helper function configures Wi-Fi or Ethernet, as selected in menuconfig.
+     * Read "Establishing Wi-Fi or Ethernet Connection" section in
+     * examples/protocols/README.md for more information about this function.
+     */
+    ESP_ERROR_CHECK(example_connect());
+
+    mqtt_app_start();
+}

examples/protocols/mqtt/ssl_psk/sdkconfig.defaults

@@ -0,0 +1 @@
+CONFIG_ESP_TLS_PSK_VERIFICATION=y