esp_encrypted_img: Add pre_encrypted_ota example to the component

.build-test-rules.yml

@@ -47,3 +47,7 @@ esp_lcd_qemu_rgb/examples/lcd_qemu_rgb_panel:
   enable:
     - if: ((IDF_VERSION_MAJOR == 5 and IDF_VERSION_MINOR >= 3) or (IDF_VERSION_MAJOR > 5)) and (IDF_TARGET in ["esp32", "esp32c3"])
       reason: Example is meant to be run under QEMU, which currently only supports ESP32 and ESP32-C3
+esp_encrypted_img/examples/pre_encrypted_ota:
+  enable:
+    - if: IDF_VERSION_MAJOR > 4 and INCLUDE_DEFAULT == 1
+      reason: Example uses esp_encrypted_img component which was introduced in IDF v5.0

.github/workflows/build_and_run_examples.yml

@@ -61,7 +61,7 @@ jobs:
       - name: Install Python packages
         env:
           PIP_EXTRA_INDEX_URL: "https://dl.espressif.com/pypi/"
-        run: pip install --only-binary cryptography pytest-embedded pytest-embedded-serial-esp pytest-embedded-idf
+        run: pip install --only-binary cryptography pytest-embedded pytest-embedded-serial-esp pytest-embedded-idf rangehttpserver
       - name: Run examples
         run: pytest --target=${{ matrix.idf_target }} -m generic --build-dir=build_${{ matrix.idf_target }} --ignore=usb --ignore=test_app
 
@@ -90,6 +90,6 @@ jobs:
       - name: Install Python packages
         env:
           PIP_EXTRA_INDEX_URL: "https://dl.espressif.com/pypi/"
-        run: pip install --only-binary cryptography pytest-embedded pytest-embedded-serial-esp pytest-embedded-idf
+        run: pip install --only-binary cryptography pytest-embedded pytest-embedded-serial-esp pytest-embedded-idf rangehttpserver
       - name: Run examples
         run: pytest --target=${{ matrix.idf_target }} -m ethernet --build-dir=build_${{ matrix.idf_target }} --ignore=usb --ignore=test_app

esp_encrypted_img/examples/pre_encrypted_ota/CMakeLists.txt

@@ -0,0 +1,8 @@
+# For more information about build system see
+# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html
+# The following five 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.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(pre_encrypted_ota)

esp_encrypted_img/examples/pre_encrypted_ota/README.md

@@ -0,0 +1,49 @@
+| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C6 | ESP32-S2 | ESP32-S3 |
+| ----------------- | ----- | -------- | -------- | -------- | -------- | -------- |
+
+# Encrypted Binary OTA
+
+This example demonstrates OTA updates with pre-encrypted binary using `esp_encrypted_img` component's APIs and tool.
+
+Pre-encrypted firmware binary must be hosted on OTA update server.
+This firmware will be fetched and then decrypted on device before being flashed.
+This allows firmware to remain `confidential` on the OTA update channel irrespective of underlying transport (e.g., non-TLS).
+
+## ESP Encrypted Image Abstraction Layer
+
+This example uses `esp_encrypted_img` component hosted at [idf-extra-components/esp_encrypted_img](https://github.com/espressif/idf-extra-components/blob/master/esp_encrypted_img) and available though the [IDF component manager](https://components.espressif.com/component/espressif/esp_encrypted_img).
+
+Please refer to its documentation [here](https://github.com/espressif/idf-extra-components/blob/master/esp_encrypted_img/README.md) for more details.
+
+
+## How to use the example
+
+To create self-signed certificate and key, refer to README.md in upper level 'examples' directory. This certificate should be flashed with binary as it will be used for connection with server.
+
+### Creating RSA key for encryption
+
+You can generate a public and private RSA key pair using following commands:
+
+`openssl genrsa -out rsa_key/private.pem 3072`
+
+This generates a 3072-bit RSA key pair, and writes them to a file.
+
+Private key is required for decryption process and is used as input to the `esp_encrypted_img` component. Private key can either be embedded into the firmware or stored in NVS.
+
+Encrypted image generation tool will derive public key (from private key) and use it for encryption purpose.
+
+* **NOTE:** We highly recommend the use of flash encryption or NVS encryption to protect the RSA Private Key on the device.
+* **NOTE:** RSA key provided in the example is for demonstration purpose only. We recommend to create a new key for production applications.
+
+## Build and Flash example
+
+```
+idf.py build flash
+```
+
+* An encrypted image is automatically generated by build system. Upload the generated encrypted image (`build/pre_encrypted_ota_secure.bin`) to a server for performing OTA update.
+
+
+## Configuration
+
+Refer the README.md in the parent directory for the setup details.

esp_encrypted_img/examples/pre_encrypted_ota/main/CMakeLists.txt

@@ -0,0 +1,8 @@
+idf_build_get_property(project_dir PROJECT_DIR)
+idf_component_register(SRCS "pre_encrypted_ota.c"
+                    INCLUDE_DIRS "."
+                    EMBED_TXTFILES ${project_dir}/server_certs/ca_cert.pem
+                                   ${project_dir}/rsa_key/private.pem)
+
+create_esp_enc_img(${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}.bin
+    ${project_dir}/rsa_key/private.pem ${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}_secure.bin app)

esp_encrypted_img/examples/pre_encrypted_ota/main/Kconfig.projbuild

@@ -0,0 +1,45 @@
+menu "Example Configuration"
+
+    config EXAMPLE_FIRMWARE_UPGRADE_URL
+        string "firmware upgrade url endpoint"
+        default "https://192.168.0.3:8070/hello_world.bin"
+        help
+            URL of server which hosts the encrypted firmware image.
+
+    config EXAMPLE_FIRMWARE_UPGRADE_URL_FROM_STDIN
+        bool
+        default y if EXAMPLE_FIRMWARE_UPGRADE_URL = "FROM_STDIN"
+
+    config EXAMPLE_SKIP_COMMON_NAME_CHECK
+        bool "Skip server certificate CN fieldcheck"
+        default n
+        help
+            This allows you to skip the validation of OTA server certificate CN field.
+
+    config EXAMPLE_SKIP_VERSION_CHECK
+        bool "Skip firmware version check"
+        default n
+        help
+            This allows you to skip the firmware version check.
+
+    config EXAMPLE_OTA_RECV_TIMEOUT
+        int "OTA Receive Timeout"
+        default 5000
+        help
+            Maximum time for reception
+
+    config EXAMPLE_ENABLE_PARTIAL_HTTP_DOWNLOAD
+        bool "Enable partial HTTP download"
+        default n
+        help
+            This enables use of Range header in esp_https_ota component.
+            Firmware image will be downloaded over multiple HTTP requests.
+
+    config EXAMPLE_HTTP_REQUEST_SIZE
+        int "HTTP request size"
+        default MBEDTLS_SSL_IN_CONTENT_LEN
+        depends on EXAMPLE_ENABLE_PARTIAL_HTTP_DOWNLOAD
+        help
+            This options specifies HTTP request size. Number of bytes specified
+            in this option will be downloaded in single HTTP request.
+endmenu

esp_encrypted_img/examples/pre_encrypted_ota/main/idf_component.yml

@@ -0,0 +1,9 @@
+## IDF Component Manager Manifest File
+version: "1.0.0"
+description: Pre Encrypted OTA Example
+dependencies:
+  espressif/esp_encrypted_img:
+    version: "^2.0.1"
+    override_path: '../../../'
+  protocol_examples_common:
+    path: ${IDF_PATH}/examples/common_components/protocol_examples_common

esp_encrypted_img/examples/pre_encrypted_ota/main/pre_encrypted_ota.c

@@ -0,0 +1,227 @@
+/*
+ * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+/* Pre Encrypted HTTPS OTA 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 <string.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/event_groups.h"
+#include "esp_system.h"
+#include "esp_event.h"
+#include "esp_log.h"
+#include "esp_ota_ops.h"
+#include "esp_http_client.h"
+#include "esp_https_ota.h"
+#include "nvs.h"
+#include "nvs_flash.h"
+#include "protocol_examples_common.h"
+#include "esp_encrypted_img.h"
+
+#if CONFIG_EXAMPLE_CONNECT_WIFI
+#include "esp_wifi.h"
+#endif
+
+static const char *TAG = "pre_encrypted_ota_example";
+extern const char server_cert_pem_start[] asm("_binary_ca_cert_pem_start");
+extern const char server_cert_pem_end[] asm("_binary_ca_cert_pem_end");
+
+extern const char rsa_private_pem_start[] asm("_binary_private_pem_start");
+extern const char rsa_private_pem_end[]   asm("_binary_private_pem_end");
+
+#define OTA_URL_SIZE 256
+
+static esp_err_t validate_image_header(esp_app_desc_t *new_app_info)
+{
+    if (new_app_info == NULL) {
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    const esp_partition_t *running = esp_ota_get_running_partition();
+    esp_app_desc_t running_app_info;
+    if (esp_ota_get_partition_description(running, &running_app_info) == ESP_OK) {
+        ESP_LOGI(TAG, "Running firmware version: %s", running_app_info.version);
+    }
+
+#ifndef CONFIG_EXAMPLE_SKIP_VERSION_CHECK
+    if (memcmp(new_app_info->version, running_app_info.version, sizeof(new_app_info->version)) == 0) {
+        ESP_LOGW(TAG, "Current running version is the same as a new. We will not continue the update.");
+        return ESP_FAIL;
+    }
+#endif
+    return ESP_OK;
+}
+
+static esp_err_t _decrypt_cb(decrypt_cb_arg_t *args, void *user_ctx)
+{
+    if (args == NULL || user_ctx == NULL) {
+        ESP_LOGE(TAG, "_decrypt_cb: Invalid argument");
+        return ESP_ERR_INVALID_ARG;
+    }
+    esp_err_t err;
+    pre_enc_decrypt_arg_t pargs = {};
+    pargs.data_in = args->data_in;
+    pargs.data_in_len = args->data_in_len;
+    err = esp_encrypted_img_decrypt_data((esp_decrypt_handle_t *)user_ctx, &pargs);
+    if (err != ESP_OK && err != ESP_ERR_NOT_FINISHED) {
+        return err;
+    }
+
+    static bool is_image_verified = false;
+    if (pargs.data_out_len > 0) {
+        args->data_out = pargs.data_out;
+        args->data_out_len = pargs.data_out_len;
+        if (!is_image_verified) {
+            is_image_verified = true;
+            const int app_desc_offset = sizeof(esp_image_header_t) + sizeof(esp_image_segment_header_t);
+            // It is unlikely to not have App Descriptor available in first iteration of decrypt callback.
+            assert(args->data_out_len >= app_desc_offset + sizeof(esp_app_desc_t));
+            esp_app_desc_t *app_info = (esp_app_desc_t *) &args->data_out[app_desc_offset];
+            err = validate_image_header(app_info);
+            if (err != ESP_OK) {
+                free(pargs.data_out);
+            }
+            return err;
+        }
+    } else {
+        args->data_out_len = 0;
+    }
+
+    return ESP_OK;
+}
+
+void pre_encrypted_ota_task(void *pvParameter)
+{
+    ESP_LOGI(TAG, "Starting Pre Encrypted OTA example");
+
+    esp_err_t ota_finish_err = ESP_OK;
+    esp_http_client_config_t config = {
+        .url = CONFIG_EXAMPLE_FIRMWARE_UPGRADE_URL,
+        .cert_pem = server_cert_pem_start,
+        .timeout_ms = CONFIG_EXAMPLE_OTA_RECV_TIMEOUT,
+        .keep_alive_enable = true,
+    };
+    esp_decrypt_cfg_t cfg = {};
+    cfg.rsa_priv_key = rsa_private_pem_start;
+    cfg.rsa_priv_key_len = rsa_private_pem_end - rsa_private_pem_start;
+    esp_decrypt_handle_t decrypt_handle = esp_encrypted_img_decrypt_start(&cfg);
+    if (!decrypt_handle) {
+        ESP_LOGE(TAG, "OTA upgrade failed");
+        vTaskDelete(NULL);
+    }
+
+#ifdef CONFIG_EXAMPLE_FIRMWARE_UPGRADE_URL_FROM_STDIN
+    char url_buf[OTA_URL_SIZE];
+    if (strcmp(config.url, "FROM_STDIN") == 0) {
+        example_configure_stdin_stdout();
+        fgets(url_buf, OTA_URL_SIZE, stdin);
+        int len = strlen(url_buf);
+        url_buf[len - 1] = '\0';
+        config.url = url_buf;
+    } else {
+        ESP_LOGE(TAG, "Configuration mismatch: wrong firmware upgrade image url");
+        abort();
+    }
+#endif
+
+#ifdef CONFIG_EXAMPLE_SKIP_COMMON_NAME_CHECK
+    config.skip_cert_common_name_check = true;
+#endif
+
+    esp_https_ota_config_t ota_config = {
+        .http_config = &config,
+#ifdef CONFIG_EXAMPLE_ENABLE_PARTIAL_HTTP_DOWNLOAD
+        .partial_http_download = true,
+        .max_http_request_size = CONFIG_EXAMPLE_HTTP_REQUEST_SIZE,
+#endif
+        .decrypt_cb = _decrypt_cb,
+        .decrypt_user_ctx = (void *)decrypt_handle,
+        .enc_img_header_size = esp_encrypted_img_get_header_size(),
+    };
+
+    esp_https_ota_handle_t https_ota_handle = NULL;
+    esp_err_t err = esp_https_ota_begin(&ota_config, &https_ota_handle);
+    if (err != ESP_OK) {
+        ESP_LOGE(TAG, "ESP HTTPS OTA Begin failed");
+        vTaskDelete(NULL);
+    }
+
+    while (1) {
+        err = esp_https_ota_perform(https_ota_handle);
+        if (err != ESP_ERR_HTTPS_OTA_IN_PROGRESS) {
+            break;
+        }
+        // esp_https_ota_perform returns after every read operation which gives user the ability to
+        // monitor the status of OTA upgrade by calling esp_https_ota_get_image_len_read, which gives length of image
+        // data read so far.
+        ESP_LOGD(TAG, "Image bytes read: %d", esp_https_ota_get_image_len_read(https_ota_handle));
+    }
+
+    if (!esp_https_ota_is_complete_data_received(https_ota_handle)) {
+        // the OTA image was not completely received and user can customise the response to this situation.
+        ESP_LOGE(TAG, "Complete data was not received.");
+    } else {
+        err = esp_encrypted_img_decrypt_end(decrypt_handle);
+        if (err != ESP_OK) {
+            goto ota_end;
+        }
+        ota_finish_err = esp_https_ota_finish(https_ota_handle);
+        if ((err == ESP_OK) && (ota_finish_err == ESP_OK)) {
+            ESP_LOGI(TAG, "ESP_HTTPS_OTA upgrade successful. Rebooting ...");
+            vTaskDelay(1000 / portTICK_PERIOD_MS);
+            esp_restart();
+        } else {
+            if (ota_finish_err == ESP_ERR_OTA_VALIDATE_FAILED) {
+                ESP_LOGE(TAG, "Image validation failed, image is corrupted");
+            }
+            ESP_LOGE(TAG, "ESP_HTTPS_OTA upgrade failed 0x%x", ota_finish_err);
+            vTaskDelete(NULL);
+        }
+    }
+
+ota_end:
+    esp_https_ota_abort(https_ota_handle);
+    ESP_LOGE(TAG, "ESP_HTTPS_OTA upgrade failed");
+    vTaskDelete(NULL);
+}
+
+void app_main(void)
+{
+    // Initialize NVS.
+    esp_err_t err = nvs_flash_init();
+    if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND) {
+        // 1.OTA app partition table has a smaller NVS partition size than the non-OTA
+        // partition table. This size mismatch may cause NVS initialization to fail.
+        // 2.NVS partition contains data in new format and cannot be recognized by this version of code.
+        // If this happens, we erase NVS partition and initialize NVS again.
+        ESP_ERROR_CHECK(nvs_flash_erase());
+        err = nvs_flash_init();
+    }
+    ESP_ERROR_CHECK( err );
+
+    ESP_ERROR_CHECK(esp_netif_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());
+
+#if CONFIG_EXAMPLE_CONNECT_WIFI
+    /* Ensure to disable any WiFi power save mode, this allows best throughput
+     * and hence timings for overall OTA operation.
+     */
+    esp_wifi_set_ps(WIFI_PS_NONE);
+#endif // CONFIG_EXAMPLE_CONNECT_WIFI
+
+    xTaskCreate(&pre_encrypted_ota_task, "pre_encrypted_ota_task", 1024 * 8, NULL, 5, NULL);
+}