From 11f2683c27d9d5562f60798eab0a6e9427e0f936 Mon Sep 17 00:00:00 2001 From: Mahavir Jain Date: Fri, 18 Nov 2022 14:03:10 +0530 Subject: [PATCH] docs: add chapter about overall "security" area guide List down considerations for the following areas: - Hardware security - Network security - Product security Also added brief explanation about "Security Policy" for ESP-IDF. Closes IDF-1565 --- docs/docs_not_updated/esp32c6.txt | 1 + docs/en/api-guides/index.rst | 1 + docs/en/api-reference/peripherals/hmac.rst | 2 + .../provisioning/provisioning.rst | 2 + docs/en/api-reference/system/efuse.rst | 2 + .../en/api-reference/system/esp_https_ota.rst | 2 + docs/en/api-reference/system/ota.rst | 2 + docs/en/security/security.rst | 246 ++++++++++++++++++ docs/zh_CN/api-guides/index.rst | 1 + docs/zh_CN/api-reference/system/ota.rst | 2 + docs/zh_CN/security/security.rst | 1 + 11 files changed, 262 insertions(+) create mode 100644 docs/en/security/security.rst create mode 100644 docs/zh_CN/security/security.rst diff --git a/docs/docs_not_updated/esp32c6.txt b/docs/docs_not_updated/esp32c6.txt index ad6c69f528..cd6a087ccc 100644 --- a/docs/docs_not_updated/esp32c6.txt +++ b/docs/docs_not_updated/esp32c6.txt @@ -205,5 +205,6 @@ api-reference/protocols/esp_tls api-reference/protocols/index security security/flash-encryption +security/security security/secure-boot-v2 security/secure-boot-v1 diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index 0263ec26dd..ee7f9859f5 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -35,6 +35,7 @@ API Guides performance/index reproducible-builds :not esp32c6: RF_calibration + ../security/security :esp32: ../security/secure-boot-v1 ../security/secure-boot-v2 thread-local-storage diff --git a/docs/en/api-reference/peripherals/hmac.rst b/docs/en/api-reference/peripherals/hmac.rst index 4833de919b..fb9bdc0a0e 100644 --- a/docs/en/api-reference/peripherals/hmac.rst +++ b/docs/en/api-reference/peripherals/hmac.rst @@ -82,6 +82,8 @@ The calculation of the HMAC and its hand-over to the DS component happen interna For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *Digital Signature (DS)* [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. +.. _hmac_for_enabling_jtag: + HMAC for Enabling JTAG ^^^^^^^^^^^^^^^^^^^^^^ Key Purpose values: 6, 5 diff --git a/docs/en/api-reference/provisioning/provisioning.rst b/docs/en/api-reference/provisioning/provisioning.rst index d4f373f943..9954b87864 100644 --- a/docs/en/api-reference/provisioning/provisioning.rst +++ b/docs/en/api-reference/provisioning/provisioning.rst @@ -97,6 +97,8 @@ It relies on the base layer called :doc:`protocomm` (Protocol Communication) whi Application creates a protocomm instance which is mapped to a specific transport and specific security scheme. Each transport in the protocomm has a concept of an "end-point" which corresponds to logical channel for communication for specific type of information. For example security handshake happens on a different endpoint than the Wi-Fi configuration endpoint. Each end-point is identified using a string and depending on the transport internal representation of the end-point changes. In case of SoftAP+HTTP transport the end-point corresponds to URI whereas in case of BLE the end-point corresponds to GATT characteristic with specific UUID. Developers can create custom end-points and implement handler for the data that is received or sent over the same end-point. +.. _provisioning_security_schemes: + Security Schemes >>>>>>>>>>>>>>>> At present, unified provisioning supports the following security schemes: diff --git a/docs/en/api-reference/system/efuse.rst b/docs/en/api-reference/system/efuse.rst index 3e28e20f2b..e9c12805c0 100644 --- a/docs/en/api-reference/system/efuse.rst +++ b/docs/en/api-reference/system/efuse.rst @@ -247,6 +247,8 @@ To write some fields into one block, or different blocks in one time, you need t FOR TESTING ONLY (NOT RECOMMENDED): You can ignore or suppress errors that violate encoding scheme data in order to burn the necessary bits in the eFuse block. +.. _efuse_API: + eFuse API --------- diff --git a/docs/en/api-reference/system/esp_https_ota.rst b/docs/en/api-reference/system/esp_https_ota.rst index 55a346aa63..2ea4a623e5 100644 --- a/docs/en/api-reference/system/esp_https_ota.rst +++ b/docs/en/api-reference/system/esp_https_ota.rst @@ -61,6 +61,8 @@ Advanced APIs Example that uses advanced ESP_HTTPS_OTA APIs: :example:`system/ota/advanced_https_ota`. +.. _ota_updates_pre-encrypted-firmware: + OTA Upgrades with Pre-Encrypted Firmware ---------------------------------------- diff --git a/docs/en/api-reference/system/ota.rst b/docs/en/api-reference/system/ota.rst index c3880de464..2aa30bf8c1 100644 --- a/docs/en/api-reference/system/ota.rst +++ b/docs/en/api-reference/system/ota.rst @@ -60,6 +60,8 @@ If :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` option is not enabled (by defaul An option in Kconfig :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` allows you to track the first boot of a new application. In this case, the application must confirm its operability by calling :cpp:func:`esp_ota_mark_app_valid_cancel_rollback` function, otherwise the application will be rolled back upon reboot. It allows you to control the operability of the application during the boot phase. Thus, a new application has only one attempt to boot successfully. +.. _ota_rollback: + Rollback Process ^^^^^^^^^^^^^^^^ diff --git a/docs/en/security/security.rst b/docs/en/security/security.rst new file mode 100644 index 0000000000..1b01126606 --- /dev/null +++ b/docs/en/security/security.rst @@ -0,0 +1,246 @@ +Security +======== + +This guide provides an overview of the overall security features available in Espressif solutions. It is highly recommended to consider this guide while designing the products with Espressif platform and ESP-IDF software stack from the **"security"** perspective. + +Goals +----- + +High level security goals are as follows: + +#. Preventing untrusted code execution +#. Protecting the identity and integrity of the code stored in the off-chip flash memory +#. Securing device identity +#. Secure storage for confidential data +#. Authenticated and encrypted communication from the device + +Platform Security +----------------- + +.. _secure_boot-guide: + +Secure Boot +~~~~~~~~~~~ + +Secure Boot feature ensures that only authenticated software can execute on the device. Secure boot process forms chain of trust by verifying all *mutable* software entities involved in the :doc:`ESP-IDF boot process <../api-guides/startup>`. Signature verification happens during both boot-up as well as OTA updates. + +Please refer to the :doc:`Secure Boot (v2) Guide ` for detailed documentation about this feature. + +.. only:: esp32 + + For ESP32 before ECO3, please refer to :doc:`Secure Boot (v1) Guide `. + +.. important:: + + It is highly recommended that a secure boot feature be enabled on all production devices. + +Secure Boot Best Practices +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Generate the signing key on a system with a quality source of entropy. +* Always keep the signing key private. A leak of this key will compromise the Secure Boot system. +* Do not allow any third party to observe any aspects of the key generation or signing process using espsecure.py. Both processes are vulnerable to timing or other side-channel attacks. +* Ensure that all security eFuses have been correctly programmed, includes disabling of the debug interfaces, non-required boot mediums (e.g., UART DL mode) etc. + + +.. _flash_enc-guide: + +Flash Encryption +~~~~~~~~~~~~~~~~ + +Flash Encryption feature helps to encrypt the contents on the off-chip flash memory and thus provides the *"confidentiality"* aspect to the software or data stored in the flash memory. + +Please refer to the :doc:`Flash Encryption Guide ` for detailed documentation about this feature. + +.. only:: SOC_SPIRAM_SUPPORTED and not esp32 + + If {IDF_TARGET_NAME} has external SPI RAM interfaced, then its contents would also be encrypted/decrypted through the MMU's flash cache, provided Flash Encryption is enabled. This provides an additional safety layer for the data stored in the SPI RAM and hence configuration like ``CONFIG_MBEDTLS_EXTERNAL_MEM_ALLOC`` can be safely enabled in this case. + +Flash Encryption Best Practices +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* It is recommended to use Flash Encryption release mode for the production use-cases. +* It is recommended to have a unique flash encryption key per device. +* Enable :ref:`secure_boot-guide` as an extra layer of protection, and to prevent an attacker from selectively corrupting any part of the flash before boot. + + +.. only:: SOC_DIG_SIGN_SUPPORTED + + Device Identity + ~~~~~~~~~~~~~~~ + + Digital Signature Peripheral in {IDF_TARGET_NAME} produces hardware accelerated RSA digital signatures (with assistance of HMAC), without the RSA private key being accessible by software. This allows the private key to be kept secured on the device without anyone other than the device hardware being able to access it. + + This peripheral can help to establish the "Secure Device Identity" to the remote endpoint, e.g., in the case of TLS mutual authentication based on RSA cipher scheme. + + Please refer to the :doc:`DS Peripheral Guide <../api-reference/peripherals/ds>` for detailed documentation. + +.. only:: SOC_MEMPROT_SUPPORTED + + Memory Protection + ~~~~~~~~~~~~~~~~~ + + {IDF_TARGET_NAME} supports "Memory Protection" scheme (either through architecture or special peripheral like PMS) which provides an ability to enforce and monitor permission attributes to memory (and peripherals in some cases). ESP-IDF application startup code configures the permissions attributes like Read/Write access on data memories and Read/Execute access on instruction memories using this peripheral. If there is any attempt made that breaks these permission attributes (e.g., a write operation to instruction memory region) then a violation interrupt is raised, and it results in system panic. + + This feature depends on the config option :ref:`CONFIG_ESP_SYSTEM_MEMPROT_FEATURE` and it is kept default enabled. Please note that the API for this feature is ``private`` and used exclusively by ESP-IDF code only. + + .. note:: This feature can help to prevent the possibility of remote code injection due to the existing vulnerabilities in the software. + +Debug Interfaces +~~~~~~~~~~~~~~~~ + +JTAG +^^^^ + +.. list:: + + - JTAG interfaces stays disabled if any of the security features are enabled, please refer to :ref:`jtag-debugging-security-features` for more information. + - JTAG interface can also be disabled in the absence of any other security features using :ref:`efuse_API`. + :SOC_HMAC_SUPPORTED: - {IDF_TARGET_NAME} supports soft disabling the JTAG interface and it can be re-enabled by programming a secret key through HMAC. (:ref:`hmac_for_enabling_jtag`) + +UART DL Mode +^^^^^^^^^^^^ + +.. only:: esp32 + + For ESP32 ECO3 case, UART Download mode stays disabled if any of the security features are enabled in their release configuration. Alternatively, it can also be disabled by calling :cpp:func:`esp_efuse_disable_rom_download_mode` at runtime. + + .. important:: + If UART Download mode is disabled then ``esptool`` can not work on the device. + +.. only:: not esp32 + + In {IDF_TARGET_NAME}, Secure UART Download mode gets activated if any of the security features are enabled. + + * Secure UART Download mode can also be enabled by calling :cpp:func:`esp_efuse_enable_rom_secure_download_mode`. + * This mode does not allow any arbitrary code to execute if downloaded through the UART download mode. + * It also limits the available commands in Download mode to basic flash read and write, plus a command to return a summary of currently enabled security features. + * To disable Download Mode entirely select the :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` to "Permanently disable ROM Download Mode (recommended)" or call :cpp:func:`esp_efuse_disable_rom_download_mode` at runtime. + + .. important:: + In Secure UART Download mode, ``esptool`` can only work with the argument ``--no-stub``. + +.. only:: SOC_WIFI_SUPPORTED + + Network Security + ---------------- + + Wi-Fi + ~~~~~ + + In addition to the traditional security methods (WEP/WPA-TKIP/WPA2-CCMP), Wi-Fi driver in ESP-IDF also supports additional state-of-the-art security protocols. Please refer to the :doc:`Wi-Fi Security <../api-guides/wifi-security>` for detailed documentation. + + TLS (Transport Layer Security) + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + It is recommended to use TLS (Transport Layer Security) in all external communications, e.g., cloud communication, OTA updates etc. from the ESP device. ESP-IDF supports :doc:`mbedTLS <../api-reference/protocols/mbedtls>` as the official TLS stack. + + TLS is default integrated in :doc:`ESP HTTP Client <../api-reference/protocols/esp_http_client>`, :doc:`ESP HTTPS Server <../api-reference/protocols/esp_https_server>` and several other components that ship with ESP-IDF. + + .. note:: + It is recommended to use ESP-IDF protocol components in their default configuration which has been ensured to be secure. Disabling HTTPS and similar security critical configurations should be avoided. + + ESP-TLS Abstraction + ^^^^^^^^^^^^^^^^^^^ + + ESP-IDF provides an abstraction layer for most used TLS functionalities and hence it is recommended that an application makes use of the API exposed by :doc:`ESP-TLS <../api-reference/protocols/esp_tls>`. + + :ref:`esp_tls_server_verification` section highlights diverse ways in which the identity of server could be established on the device side. + + ESP Certificate Bundle + ^^^^^^^^^^^^^^^^^^^^^^ + + The :doc:`ESP x509 Certificate Bundle <../api-reference/protocols/esp_crt_bundle>` API provides an easy way to include a bundle of custom x509 root certificates for TLS server verification. The certificate bundle is the easiest way to verify the identity of almost all standard TLS servers. + + .. important:: + It is highly recommended to verify the identity of the server (based on X.509 certificates) to avoid establishing communication with the *fake* server. + + +Product Security +---------------- + +Secure Provisioning +~~~~~~~~~~~~~~~~~~~ + +Secure Provisioning refers to a process of secure on-boarding of the ESP device on to the Wi-Fi network. This mechanism also allows provision of additional custom configuration data during the initial provisioning phase from the provisioning entity (e.g., Smartphone). + +ESP-IDF provides various security schemes to establish a secure session between ESP and the provisioning entity, they are highlighted at :ref:`provisioning_security_schemes`. + +Please refer to the :doc:`Wi-Fi Provisioning <../api-reference/provisioning/wifi_provisioning>` documentation for details and example code for this feature. + +.. note:: + + Espressif provides Android and iOS Phone Apps along with their sources so that it could be easy to further customize them as per the product requirement. + +Secure OTA (Over-the-air) Updates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- OTA Updates must happen over secure transport, e.g., HTTPS. +- ESP-IDF provides a simplified abstraction layer :doc:`ESP HTTPS OTA <../api-reference/system/esp_https_ota>` for this. +- If :ref:`secure_boot-guide` is enabled then server should host the signed application image. +- If :ref:`flash_enc-guide` is enabled then no additional steps are required on the server side, encryption shall be taken care on the device itself during flash write. +- OTA update :ref:`ota_rollback` can help to switch the application as ``active`` only after its functionality has been verified. + + +Anti-Rollback Protection +^^^^^^^^^^^^^^^^^^^^^^^^ + +Anti-rollback protection feature ensures that device only executes application that meets the security version criteria as stored in its eFuse. So even though the application is trusted and signed by legitimate key it may contain some revoked security feature or credential and hence device must reject any such application. + +ESP-IDF allows this feature for the application only and it's managed through 2nd stage bootloader. The security version is stored in the device eFuse and it's compared against the application image header during both bootup and over-the-air updates. + +Please see more information to enable this feature in the :ref:`anti-rollback` guide. + +Encrypted Firmware Distribution +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Encrypted firmware distribution during over-the-air updates ensure that the application stays encrypted **in transit** from server to the the device. This can act as an additional layer of protection on top of the TLS communication during OTA updates and protect the identity of the application. + +Please see working example for this documented in :ref:`ota_updates_pre-encrypted-firmware` section. + +Secure Storage +~~~~~~~~~~~~~~ + +Secure storage refers to the application specific data that can be stored in a secure manner on the device (off-chip flash memory). This is typically read-write flash partition and holds device specific configuration data e.g., Wi-Fi credentials. + +ESP-IDF provides "NVS (Non-volatile Storage)" management component which allows encrypted data partitions. This feature is tied with the platform :ref:`flash_enc-guide` feature described earlier. + +Please refer to the :ref:`NVS Encryption ` for detailed documentation on the working and instructions to enable this feature. + +.. important:: + + By default, ESP-IDF components writes the device specific data into the default NVS partition (includes Wi-Fi credentials too) and it is recommended to protect this data using "NVS Encryption" feature. + +Secure Device Control +~~~~~~~~~~~~~~~~~~~~~ + +ESP-IDF provides capability to control an ESP device over ``Wi-Fi + HTTP`` or ``BLE`` in a secure manner using ESP Local Control component. + +Please refer to the :doc:`ESP Local Control <../api-reference/protocols/esp_local_ctrl>` for detailed documentation about this feature. + +Security Policy +--------------- + +ESP-IDF GitHub repository has attached `Security Policy Brief`_. + +Advisories +~~~~~~~~~~ + +- Espressif publishes critical `Security Advisories`_ on the website, this includes both hardware and software related. +- ESP-IDF software components specific advisories are published through the `GitHub repository`_. + +Software Updates +~~~~~~~~~~~~~~~~ + +Critical security issues in the ESP-IDF components, 3rd party libraries are fixed as and when we find them or when they are reported to us. Gradually, we make the fixes available in all applicable release branches in ESP-IDF. + +Applicable security issues and CVEs for the ESP-IDF components, 3rd party libraries are mentioned in the ESP-IDF release notes. + +.. important:: + + We recommend periodically updating to the latest bugfix version of the ESP-IDF release to have all critical security fixes available. + + +.. _`Security Policy Brief`: https://github.com/espressif/esp-idf/blob/master/SECURITY.md +.. _`Security Advisories`: https://www.espressif.com/en/support/documents/advisories +.. _`GitHub repository`: https://github.com/espressif/esp-idf/security/advisories diff --git a/docs/zh_CN/api-guides/index.rst b/docs/zh_CN/api-guides/index.rst index f8a03f5f48..e7097e4ca2 100644 --- a/docs/zh_CN/api-guides/index.rst +++ b/docs/zh_CN/api-guides/index.rst @@ -31,6 +31,7 @@ API 指南 partition-tables performance/index :not esp32c6: RF_calibration + ../security/security :esp32: ../security/secure-boot-v1 ../security/secure-boot-v2 :SOC_SPIRAM_SUPPORTED: external-ram diff --git a/docs/zh_CN/api-reference/system/ota.rst b/docs/zh_CN/api-reference/system/ota.rst index 4792215fc9..9d54fd0b07 100644 --- a/docs/zh_CN/api-reference/system/ota.rst +++ b/docs/zh_CN/api-reference/system/ota.rst @@ -60,6 +60,8 @@ OTA 数据分区是两个 0x2000 字节大小的 flash 扇区，防止写入时 Kconfig 中的 :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` 可以帮助用户追踪新版应用程序的第一次启动。应用程序需调用 :cpp:func:`esp_ota_mark_app_valid_cancel_rollback` 函数确认可以运行，否则将会在重启时回滚至旧版本。该功能可让用户在启动阶段控制应用程序的可操作性。新版应用程序仅有一次机会尝试是否能成功启动。 +.. _ota_rollback: + 回滚过程 ^^^^^^^^ diff --git a/docs/zh_CN/security/security.rst b/docs/zh_CN/security/security.rst new file mode 100644 index 0000000000..ef0e2cf3be --- /dev/null +++ b/docs/zh_CN/security/security.rst @@ -0,0 +1 @@ +.. include:: ../../en/security/security.rst