Merge branch 'bugfix/esp_https_ota_breaking_changes' into 'master'

esp_https_ota: Update esp_https_ota() to support OTA updates with encrypted images

See merge request espressif/esp-idf!17312

components/esp_https_ota/include/esp_https_ota.h

@@ -53,9 +53,9 @@ typedef struct {
  * reads image data from HTTP stream and writes it to OTA partition and
  * finishes HTTPS OTA Firmware upgrade operation.
  * This API supports URL redirection, but if CA cert of URLs differ then it
- * should be appended to `cert_pem` member of `config`.
+ * should be appended to `cert_pem` member of `ota_config->http_config`.
  *
- * @param[in]  config       pointer to esp_http_client_config_t structure.
+ * @param[in]  ota_config       pointer to esp_https_ota_config_t structure.
  *
  * @note     This API handles the entire OTA operation, so if this API is being used
  *           then no other APIs from `esp_https_ota` component should be called.
@@ -72,7 +72,7 @@ typedef struct {
  *    - ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed.
  *    - For other return codes, refer OTA documentation in esp-idf's app_update component.
  */
-esp_err_t esp_https_ota(const esp_http_client_config_t *config);
+esp_err_t esp_https_ota(const esp_https_ota_config_t *ota_config);
 
 /**
  * @brief    Start HTTPS OTA Firmware upgrade
@@ -99,7 +99,7 @@ esp_err_t esp_https_ota(const esp_http_client_config_t *config);
  *    - For other return codes, refer documentation in app_update component and esp_http_client
  *      component in esp-idf.
  */
-esp_err_t esp_https_ota_begin(esp_https_ota_config_t *ota_config, esp_https_ota_handle_t *handle);
+esp_err_t esp_https_ota_begin(const esp_https_ota_config_t *ota_config, esp_https_ota_handle_t *handle);
 
 /**
  * @brief    Read image data from HTTP stream and write it to OTA partition

components/esp_https_ota/src/esp_https_ota.c

@@ -191,13 +191,13 @@ static esp_err_t _ota_write(esp_https_ota_t *https_ota_handle, const void *buffe
     return err;
 }
 
-static bool is_server_verification_enabled(esp_https_ota_config_t *ota_config) {
+static bool is_server_verification_enabled(const esp_https_ota_config_t *ota_config) {
     return  (ota_config->http_config->cert_pem
             || ota_config->http_config->use_global_ca_store
             || ota_config->http_config->crt_bundle_attach != NULL);
 }
 
-esp_err_t esp_https_ota_begin(esp_https_ota_config_t *ota_config, esp_https_ota_handle_t *handle)
+esp_err_t esp_https_ota_begin(const esp_https_ota_config_t *ota_config, esp_https_ota_handle_t *handle)
 {
     esp_err_t err;
 
@@ -648,19 +648,15 @@ int esp_https_ota_get_image_size(esp_https_ota_handle_t https_ota_handle)
     return handle->image_length;
 }
 
-esp_err_t esp_https_ota(const esp_http_client_config_t *config)
+esp_err_t esp_https_ota(const esp_https_ota_config_t *ota_config)
 {
-    if (!config) {
-        ESP_LOGE(TAG, "esp_http_client config not found");
+    if (ota_config == NULL || ota_config->http_config == NULL) {
+        ESP_LOGE(TAG, "esp_https_ota: Invalid argument");
         return ESP_ERR_INVALID_ARG;
     }
 
-    esp_https_ota_config_t ota_config = {
-        .http_config = config,
-    };
-
     esp_https_ota_handle_t https_ota_handle = NULL;
-    esp_err_t err = esp_https_ota_begin(&ota_config, &https_ota_handle);
+    esp_err_t err = esp_https_ota_begin(ota_config, &https_ota_handle);
     if (https_ota_handle == NULL) {
         return ESP_FAIL;
     }

docs/en/api-reference/system/esp_https_ota.rst

@@ -20,7 +20,10 @@ Application Example
                 .url = CONFIG_FIRMWARE_UPGRADE_URL,
                 .cert_pem = (char *)server_cert_pem_start,
             };
-            esp_err_t ret = esp_https_ota(&config);
+            esp_https_ota_config_t ota_config = {
+                .http_config = &config,
+            };
+            esp_err_t ret = esp_https_ota(&ota_config);
             if (ret == ESP_OK) {
                 esp_restart();
             } else {
@@ -47,6 +50,21 @@ Signature Verification
 
 For additional security, signature of OTA firmware images can be verified. For that, refer :ref:`secure-ota-updates`
 
+Advanced APIs
+-------------
+
+``esp_https_ota`` also provides advanced APIs which can be used if more information and control is needed during the OTA process.
+
+Example that uses advanced ESP_HTTPS_OTA APIs: :example:`system/ota/advanced_https_ota`.
+
+
+OTA Upgrades with Pre-Encrypted Firmware
+----------------------------------------
+
+To perform OTA upgrades with Pre-Encrypted Firmware, please enable :ref:`CONFIG_ESP_HTTPS_OTA_DECRYPT_CB` in component menuconfig.
+
+Example that performs OTA upgrade with Pre-Encrypted Firmware: :example:`system/ota/pre_encrypted_ota`.
+
 API Reference
 -------------
 

docs/en/migration-guides/protocols.rst

@@ -72,3 +72,12 @@ Names of variables holding different certs in :cpp:type:`httpd_ssl_config_t` str
     * :cpp:member:`servercert_len` variable inherits role of :cpp:member:`cacert_len` variable
     * :cpp:member:`cacert_pem` variable inherits role of :cpp:member:`client_verify_cert_pem` variable
     * :cpp:member:`cacert_len` variable inherits role of :cpp:member:`client_verify_cert_len` variable
+
+
+ESP HTTPS OTA
+--------------
+
+Breaking Changes (Summary)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- The function :cpp:func:`esp_https_ota()` now requires pointer to :cpp:type:`esp_https_ota_config_t` as argument instead of pointer to :cpp:type:`esp_http_client_config_t`.

examples/system/ota/simple_ota_example/main/simple_ota_example.c

@@ -121,8 +121,11 @@ void simple_ota_example_task(void *pvParameter)
     config.skip_cert_common_name_check = true;
 #endif
 
+    esp_https_ota_config_t ota_config = {
+        .http_config = &config,
+    };
     ESP_LOGI(TAG, "Attempting to download update from %s", config.url);
-    esp_err_t ret = esp_https_ota(&config);
+    esp_err_t ret = esp_https_ota(&ota_config);
     if (ret == ESP_OK) {
         esp_restart();
     } else {