Skip to content

Commit

Permalink
Merge branch 'docs/update_cn_trans_esp_https_ota' into 'master'
Browse files Browse the repository at this point in the history
docs: update cn trans for esp_https_ota

Closes DOC-7732

See merge request espressif/esp-idf!30579
  • Loading branch information
esp-momo committed May 6, 2024
2 parents 7f05633 + a4d0b37 commit 0de1efc
Show file tree
Hide file tree
Showing 2 changed files with 33 additions and 6 deletions.
10 changes: 5 additions & 5 deletions docs/en/api-reference/system/esp_https_ota.rst
Original file line number Diff line number Diff line change
Expand Up @@ -70,29 +70,29 @@ Example that uses advanced ESP_HTTPS_OTA APIs: :example:`system/ota/advanced_htt
OTA Upgrades with Pre-Encrypted Firmware
----------------------------------------

Pre-Encrypted firmware is a completely independent scheme from :doc:`../../security/flash-encryption`. Primary reasons for this are as follows:
Pre-encrypted firmware is a completely independent scheme from :doc:`../../security/flash-encryption`. Primary reasons for this are as follows:

* Flash encryption scheme recommends using per-device unique encryption key that is internally generated. This makes pre-encryption of the firmware on OTA update server infeasible.

* Flash encryption scheme depends on the flash offset and generates different ciphertext for different flash offset. And hence it becomes difficult to manage different OTA update images based on the partition slots like ``ota_0``, ``ota_1`` etc.

* Even for devices where flash encryption is not enabled, it could be requirement that firmware image over OTA is still encrypted in nature.

Pre-Encrypted firmware distribution ensures that the firmware image stays encrypted **in transit** from the server to the device (irrespective of the underlying transport security). First the pre-encrypted software layer will decrypt the firmware (received over network) on device and then re-encrypt the contents using platform flash encryption (if enabled) before writing to flash.
Pre-encrypted firmware distribution ensures that the firmware image stays encrypted **in transit** from the server to the device (irrespective of the underlying transport security). First the pre-encrypted software layer will decrypt the firmware (received over network) on device and then re-encrypt the contents using platform flash encryption (if enabled) before writing to flash.

Design
^^^^^^

* This scheme requires an unique RSA-3072 public-private key pair to be generated first. The public key stays on the OTA update server for encryption purpose and the private key is part of the device (e.g., embedded in firmware) for decryption purpose.
* Pre-Encrypted firmware is encrypted using AES-GCM key which is then appended to the image as header (along with config parameters).
* This scheme requires a unique RSA-3072 public-private key pair to be generated first. The public key stays on the OTA update server for encryption purpose and the private key is part of the device (e.g., embedded in firmware) for decryption purpose.
* Pre-encrypted firmware is encrypted using AES-GCM key which is then appended to the image as header (along with config parameters).
* Further the AES-GCM key gets encrypted using RSA public key and the resultant image gets hosted on the OTA update server.
* On the device side, first the AES-GCM key is retrieved by decrypting the image header using RSA private key available to the device.
* Finally, the contents of the image are decrypted using AES-GCM key (and config parameters) and written to the flash storage.

This whole workflow is managed by an external component `esp_encrypted_image <https://github.com/espressif/idf-extra-components/blob/master/esp_encrypted_img>`_ and it gets plugged into the OTA update framework through decryption callback (:cpp:member:`esp_https_ota_config_t::decrypt_cb`) mechanism.

.. note::
Supported scheme is based on RSA-3072 and the private key on device side must be protected using platform security features.
The supported scheme is based on RSA-3072 and the private key on device side must be protected using platform security features.

Example
^^^^^^^
Expand Down
29 changes: 28 additions & 1 deletion docs/zh_CN/api-reference/system/esp_https_ota.rst
Original file line number Diff line number Diff line change
Expand Up @@ -70,9 +70,36 @@ mbedTLS Rx buffer 的默认大小为 16 KB,但如果将 ``partial_http_downloa
使用预加密固件进行 OTA 升级
----------------------------------------

预加密固件完全独立于 :doc:`../../security/flash-encryption` 方案,主要原因如下:

* flash 加密方案推荐各个设备使用在内部生成的唯一加密密钥,因此在 OTA 更新服务器上预加密固件并不可行。

* flash 加密方案依赖 flash 偏移,会基于不同的 flash 偏移量生成不同的密文,因此根据分区槽(如 ``ota_0``、``ota_1`` 等)来管理不同的 OTA 更新镜像较为困难。

* 即使设备未启用 flash 加密,仍可能要求进行 OTA 的固件镜像保持加密。

无论底层传输安全性如何,预加密固件的分发都能确保固件镜像在从服务器到设备的**传输过程中**保持加密状态。首先,预加密软件层在设备上通过网络接收并解密固件,然后使用平台 flash 加密(如果已启用)重新加密内容,最后写入 flash。

设计
^^^^

* 该方案需首先生成一个唯一的 RSA-3072 公钥—私钥对。公钥保留在 OTA 更新服务器上,用于加密,而私钥作为设备的一部分,例如内嵌于固件中,用于解密。
* 预加密固件使用 AES-GCM 密钥进行加密,并将该密钥(及其配置参数)作为标头附加到镜像中。
* 此外,AES-GCM 密钥使用 RSA 公钥进行加密,生成的镜像会托管到 OTA 更新服务器上。
* 在设备端,首先使用可用的 RSA 私钥解密镜像标头,从而获取 AES-GCM 密钥。
* 最后,使用 AES-GCM 密钥(和配置参数)解密镜像内容,并将其写入 flash。

整个工作流程由外部组件 `esp_encrypted_image <https://github.com/espressif/idf-extra-components/blob/master/esp_encrypted_img>`_ 管理,并通过解密回调 (:cpp:member:`esp_https_ota_config_t::decrypt_cb`) 机制插入到 OTA 更新框架中。

.. note::
该支持方案基于 RSA-3072,必须使用平台安全功能保护设备端的私钥。

示例
^^^^

如需使用预加密的固件进行 OTA 升级,请在组件的菜单配置中启用 :ref:`CONFIG_ESP_HTTPS_OTA_DECRYPT_CB` 选项。

如需查看使用预加密固件进行 OTA 升级的示例,请前往 :example:`system/ota/pre_encrypted_ota`。
如需了解详细的配置流程和说明,请参考示例 :example:`system/ota/pre_encrypted_ota`。


OTA 系统事件
Expand Down

0 comments on commit 0de1efc

Please sign in to comment.