mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Docs: add CN translation for security/security.rst
This commit is contained in:
Doc-intern2
caixinying-git
parent
64a01af42d
commit
37af2b7a22
@ -1,14 +1,16 @@
|
||||
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.
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
This guide provides an overview of the overall security features available in various Espressif solutions. It is highly recommended to consider this guide while designing the products with the Espressif platform and the ESP-IDF software stack from the **security** perspective.
|
||||
|
||||
Goals
|
||||
-----
|
||||
|
||||
High level security goals are as follows:
|
||||
|
||||
#. Preventing untrusted code execution
|
||||
#. Preventing untrustworthy code from being executed
|
||||
#. Protecting the identity and integrity of the code stored in the off-chip flash memory
|
||||
#. Securing device identity
|
||||
#. Secure storage for confidential data
|
||||
@ -22,25 +24,25 @@ Platform Security
|
||||
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.
|
||||
The Secure Boot feature ensures that only authenticated software can execute on the device. The Secure Boot process forms a chain of trust by verifying all **mutable** software entities involved in the :doc:`../api-guides/startup`. Signature verification happens during both boot-up as well as in OTA updates.
|
||||
|
||||
Please refer to the :doc:`Secure Boot (v2) Guide <secure-boot-v2>` for detailed documentation about this feature.
|
||||
Please refer to :doc:`secure-boot-v2` for detailed documentation about this feature.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
For ESP32 before ECO3, please refer to :doc:`Secure Boot (v1) Guide <secure-boot-v1>`.
|
||||
For ESP32 before ECO3, please refer to :doc:`secure-boot-v1`.
|
||||
|
||||
.. important::
|
||||
|
||||
It is highly recommended that a secure boot feature be enabled on all production devices.
|
||||
It is highly recommended that Secure Boot 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.
|
||||
* 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, including disabling of the debug interfaces, non-required boot mediums (e.g., UART DL mode), etc.
|
||||
|
||||
|
||||
.. _flash_enc-guide:
|
||||
@ -48,18 +50,18 @@ Secure Boot Best Practices
|
||||
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.
|
||||
The 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 <flash-encryption>` for detailed documentation about this feature.
|
||||
Please refer to :doc:`flash-encryption` for detailed information 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.
|
||||
If {IDF_TARGET_NAME} is connected to an external SPI RAM, the contents written to or read from the SPI RAM will also be encrypted and decrypted respectively (via the MMU's flash cache, provided that FLash Encryption is enabled). This provides an additional safety layer for the data stored in SPI RAM, hence configurations 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 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.
|
||||
|
||||
@ -69,22 +71,24 @@ Flash Encryption Best Practices
|
||||
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.
|
||||
The Digital Signature peripheral in {IDF_TARGET_NAME} produces hardware-accelerated RSA digital signatures with the 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.
|
||||
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 the RSA cipher scheme.
|
||||
|
||||
Please refer to the :doc:`DS Peripheral Guide <../api-reference/peripherals/ds>` for detailed documentation.
|
||||
Please refer to the :doc:`../api-reference/peripherals/ds` for detailed documentation.
|
||||
|
||||
.. only:: SOC_MEMPROT_SUPPORTED or SOC_CPU_IDRAM_SPLIT_USING_PMP
|
||||
|
||||
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.
|
||||
{IDF_TARGET_NAME} supports the **Memory Protection** scheme, either through architecture or special peripheral like PMS, which provides an ability to enforce and monitor permission attributes to memory and, in some cases, peripherals. ESP-IDF application startup code configures the permissions attributes like Read/Write access on data memories and Read/Execute access on instruction memories using the relevant 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.
|
||||
This feature depends on the config option :ref:`CONFIG_ESP_SYSTEM_MEMPROT_FEATURE` and it is kept enabled by default. 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.
|
||||
.. note::
|
||||
|
||||
This feature can help to prevent the possibility of remote code injection due to the existing vulnerabilities in the software.
|
||||
|
||||
.. only:: SOC_CRYPTO_DPA_PROTECTION_SUPPORTED
|
||||
|
||||
@ -92,9 +96,12 @@ Flash Encryption Best Practices
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
{IDF_TARGET_NAME} has support for protection mechanisms against the Differential Power Analysis related security attacks. DPA protection dynamically adjusts the clock frequency of the crypto peripherals, thereby blurring the power consumption trajectory during its operation. Based on the configured DPA security level, the clock variation range changes. Please refer to the TRM for more details on this topic.
|
||||
|
||||
:ref:`CONFIG_ESP_CRYPTO_DPA_PROTECTION_LEVEL` can help to select the DPA level. Higher level means better security, but it can also have an associated performance impact. By default, the lowest DPA level is kept enabled but it can be modified based on the security requirement.
|
||||
|
||||
.. note:: Please note that hardware :doc:`RNG <../api-reference/system/random>` must be enabled for DPA protection to work correctly.
|
||||
.. note::
|
||||
|
||||
Please note that hardware :doc:`RNG <../api-reference/system/random>` must be enabled for DPA protection to work correctly.
|
||||
|
||||
Debug Interfaces
|
||||
~~~~~~~~~~~~~~~~
|
||||
@ -104,19 +111,20 @@ 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 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
|
||||
^^^^^^^^^^^^
|
||||
UART Download 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.
|
||||
|
||||
If UART Download mode is disabled then ``esptool.py`` can not work on the device.
|
||||
|
||||
.. only:: SOC_SUPPORTS_SECURE_DL_MODE
|
||||
|
||||
@ -124,11 +132,12 @@ UART DL Mode
|
||||
|
||||
* 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 update SPI config, changing baud rate, basic flash write and a command to return a summary of currently enabled security features (`get_security_info`).
|
||||
* 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.
|
||||
* It also limits the available commands in Download mode to update SPI config, e.g., changing baud rate, basic flash write, and the command to return a summary of currently enabled security features (``get_security_info``).
|
||||
* To disable Download Mode entirely, select the :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` to the recommended option ``Permanently disable ROM Download Mode`` 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``.
|
||||
|
||||
In Secure UART Download mode, ``esptool.py`` can only work with the argument ``--no-stub``.
|
||||
|
||||
.. only:: SOC_WIFI_SUPPORTED
|
||||
|
||||
@ -138,32 +147,34 @@ UART DL Mode
|
||||
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.
|
||||
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:`../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.
|
||||
It is recommended to use TLS (Transport Layer Security) in all external communications (e.g., cloud communication, OTA updates) from the ESP device. ESP-IDF supports :doc:`../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.
|
||||
TLS is default integrated in :doc:`../api-reference/protocols/esp_http_client`, :doc:`../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.
|
||||
|
||||
It is recommended to use the ESP-IDF protocol components in their default configuration, which has been ensured to be secure. Disabling of 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>`.
|
||||
ESP-IDF provides an abstraction layer for the most-used TLS functionalities. Hence, it is recommended that an application uses the API exposed by :doc:`../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.
|
||||
The :doc:`../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.
|
||||
|
||||
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
|
||||
@ -172,84 +183,79 @@ 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).
|
||||
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.
|
||||
Please refer to the :doc:`../api-reference/provisioning/wifi_provisioning` documentation for details and the 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.
|
||||
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.
|
||||
- ESP-IDF provides a simplified abstraction layer :doc:`../api-reference/system/esp_https_ota` for this.
|
||||
- If :ref:`secure_boot-guide` is enabled, then the 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.
|
||||
Anti-rollback protection feature ensures that device only executes the 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. 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.
|
||||
ESP-IDF allows this feature for the application only and it is managed through 2nd stage bootloader. The security version is stored in the device eFuse and it is 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.
|
||||
Encrypted firmware distribution during over-the-air updates ensures that the application stays encrypted **in transit** from the 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.
|
||||
Secure storage refers to the application-specific data that can be stored in a secure manner on the device, i.e., off-chip flash memory. This is typically a 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.
|
||||
ESP-IDF provides the **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.
|
||||
|
||||
.. only:: SOC_HMAC_SUPPORTED
|
||||
|
||||
This feature can also be used independent of the platform :ref:`flash_enc-guide` feature with the help of the {IDF_TARGET_NAME} HMAC peripheral.
|
||||
|
||||
|
||||
Please refer to the :doc:`NVS Encryption <../api-reference/storage/nvs_encryption>` for detailed documentation on the working and instructions to enable this feature.
|
||||
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.
|
||||
By default, ESP-IDF components writes the device specific data into the default NVS partition, including 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.
|
||||
Please refer to the :doc:`../api-reference/protocols/esp_local_ctrl` for detailed documentation about this feature.
|
||||
|
||||
Security Policy
|
||||
---------------
|
||||
|
||||
ESP-IDF GitHub repository has attached `Security Policy Brief`_.
|
||||
The 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`_.
|
||||
- Espressif publishes critical `Security Advisories`_, which includes security advisories regarding both hardware and software.
|
||||
- The specific advisories of the ESP-IDF software components 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.
|
||||
Critical security issues in the ESP-IDF components, and third-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.
|
||||
Applicable security issues and CVEs for the ESP-IDF components, third-party libraries are mentioned in the ESP-IDF release notes.
|
||||
|
||||
.. important::
|
||||
|
||||
|
||||
@ -1 +1,267 @@
|
||||
.. include:: ../../en/security/security.rst
|
||||
安全
|
||||
====
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
本指南概述了乐鑫解决方案中可用的整体安全功能。从 **安全** 角度考虑，强烈建议在使用乐鑫平台和 ESP-IDF 软件栈设计产品时参考本指南。
|
||||
|
||||
目标
|
||||
----
|
||||
|
||||
高级安全目标包括：
|
||||
|
||||
#. 防止执行不受信任的代码
|
||||
#. 保护存储在外部 flash 中代码的可信度和完整性
|
||||
#. 保护设备身份
|
||||
#. 安全存储机密数据
|
||||
#. 设备身份验证与加密通信
|
||||
|
||||
平台安全
|
||||
---------
|
||||
|
||||
.. _secure_boot-guide:
|
||||
|
||||
安全启动
|
||||
~~~~~~~~
|
||||
|
||||
安全启动功能可以确保设备仅执行通过身份认证的软件。安全启动时，会验证 :doc:`../api-guides/startup` 中所涉及的所有 **可变** 软件实体，形成信任链。设备启动以及 OTA 更新过程中都会进行签名认证。
|
||||
|
||||
关于安全启动功能的更多详情，请参阅 :doc:`secure-boot-v2`。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
关于 ESP32 在发布 ECO3 前的安全启动功能，请参阅 :doc:`secure-boot-v1`。
|
||||
|
||||
.. important::
|
||||
|
||||
强烈建议在所有生产设备上启用安全启动功能。
|
||||
|
||||
安全启动最佳实践
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
* 在具备高质量熵源的系统上生成签名密钥。
|
||||
* 签名密钥始终保密；签名密钥泄露会危及安全启动系统。
|
||||
* 禁止第三方使用 ``espsecure.py`` 观察密钥生成或签名过程的相关细节，这两个过程都容易受到时序攻击或其他侧信道攻击的影响。
|
||||
* 确保正确烧录所有安全性 eFuse，包括禁用调试接口以及非必需的启动介质（例如 UART 下载模式）等。
|
||||
|
||||
|
||||
.. _flash_enc-guide:
|
||||
|
||||
flash 加密
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
flash 加密功能可以加密外部 flash 中的内容，从而保护存储在 flash 中软件或数据的 **机密性** 。
|
||||
|
||||
关于该功能的更多详情，请参阅 :doc:`flash-encryption`。
|
||||
|
||||
.. only:: SOC_SPIRAM_SUPPORTED and not esp32
|
||||
|
||||
如果 {IDF_TARGET_NAME} 连接了外部 SPI RAM，那么写入或读取到 SPI RAM 的内容将会分别进行加密和解密。当启用 flash 加密时，上述过程将通过 MMU 的 flash 缓存实现。以上加密和解密过程为存储在 SPI RAM 中的数据提供了额外的安全层，有助于安全地启用 ``CONFIG_MBEDTLS_EXTERNAL_MEM_ALLOC`` 等特定配置选项。
|
||||
|
||||
flash 加密最佳实践
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* 建议在生产环境中使用 flash 加密的发布模式。
|
||||
* 建议为每个设备生成唯一的 flash 加密密钥。
|
||||
* 启用 :ref:`secure_boot-guide` 作为额外保护层，防止 flash 在启动前遭受恶意攻击。
|
||||
|
||||
|
||||
.. only:: SOC_DIG_SIGN_SUPPORTED
|
||||
|
||||
设备身份
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
在 {IDF_TARGET_NAME} 中，数字签名外设借助硬件加速，通过 HMAC 算法生成 RSA 数字签名。RSA 私钥仅限设备硬件访问，软件无法获取，保证了设备上存储密钥的安全性。
|
||||
|
||||
数字签名外设可以建立与远程终端之间的 **安全设备身份**，如基于 RSA 加密算法的 TLS 双向认证。
|
||||
|
||||
更多详情请参阅 :doc:`../api-reference/peripherals/ds`。
|
||||
|
||||
.. only:: SOC_MEMPROT_SUPPORTED or SOC_CPU_IDRAM_SPLIT_USING_PMP
|
||||
|
||||
内存保护
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
{IDF_TARGET_NAME} 可以通过架构或 PMS 等特定外设实现 **内存保护**，强制执行和监控内存以及某些外设的权限属性。使用相应外设，ESP-IDF 应用程序启动代码可以配置数据内存的读取/写入权限以及指令内存的读取/执行权限。如有任何操作尝试违反这些权限属性，如写入指令内存区域，将触发违规中断，导致系统 panic。
|
||||
|
||||
使用该功能需启用配置选项 :ref:`CONFIG_ESP_SYSTEM_MEMPROT_FEATURE`，该选项默认启用。请注意，该功能的 API 是 **私有** 的，仅供 ESP-IDF 代码使用。
|
||||
|
||||
.. note::
|
||||
|
||||
内存保护功能可以防止因软件漏洞导致的远程代码注入。
|
||||
|
||||
.. only:: SOC_CRYPTO_DPA_PROTECTION_SUPPORTED
|
||||
|
||||
差分功耗分析 (DPA) 保护
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
{IDF_TARGET_NAME} 支持针对 DPA 相关安全攻击的保护机制。DPA 保护通过动态调整加密外设的时钟频率，在其运行期间模糊了功耗消耗记录。时钟变化范围会根据配置的 DPA 安全级别改变。更多详情请参阅技术参考手册。
|
||||
|
||||
通过 :ref:`CONFIG_ESP_CRYPTO_DPA_PROTECTION_LEVEL` 可以调整 DPA 级别。级别越高安全性越强，但也可能会影响性能。默认启用最低级别 DPA 保护，可以根据安全需求修改。
|
||||
|
||||
.. note::
|
||||
|
||||
请注意，为确保 DPA 保护正常工作，必须启用硬件 :doc:`RNG <../api-reference/system/random>`。
|
||||
|
||||
调试接口
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
JTAG
|
||||
^^^^
|
||||
|
||||
.. list::
|
||||
|
||||
- 如果启用了任一安全功能，则 JTAG 接口将保持禁用。更多详情请参阅 :ref:`jtag-debugging-security-features`。
|
||||
- 如果不启用其他安全功能，也可以使用 :ref:`efuse_API` 禁用 JTAG 接口。
|
||||
:SOC_HMAC_SUPPORTED: - {IDF_TARGET_NAME} 支持软禁用 JTAG 接口，并且可以通过 HMAC 烧录密钥重新启用，请参阅 :ref:`hmac_for_enabling_jtag`。
|
||||
|
||||
UART 下载模式
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
对于 ESP32 ECO3，如果在发布配置中启用了任一安全功能，UART 下载模式将保持禁用。也可以在运行时调用 :cpp:func:`esp_efuse_disable_rom_download_mode` 禁用该模式。
|
||||
|
||||
.. important::
|
||||
|
||||
如果禁用了 UART 下载模式，则无法在设备上使用 ``esptool.py``。
|
||||
|
||||
.. only:: SOC_SUPPORTS_SECURE_DL_MODE
|
||||
|
||||
{IDF_TARGET_NAME} 中，如果启用了任一安全功能，则会激活安全 UART 下载模式。
|
||||
|
||||
* 要启用安全 UART 下载模式，也可以调用 :cpp:func:`esp_efuse_enable_rom_secure_download_mode`。
|
||||
* 该模式下，禁止执行通过 UART 下载模式下载的任意代码。
|
||||
* 该模式将限制部分涉及更新 SPI 配置的命令，如更改波特率、基本的 flash 写入以及通过 ``get_security_info`` 返回当前启用的安全功能摘要。
|
||||
* 要完全禁用安全 UART 下载模式，可以将 :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` 设置为建议选项 ``Permanently disable ROM Download Mode``，或者在运行时调用 :cpp:func:`esp_efuse_disable_rom_download_mode`。
|
||||
|
||||
.. important::
|
||||
|
||||
安全 UART 下载模式下，仅支持使用 ``--no-stub`` 参数调用 ``esptool.py``。
|
||||
|
||||
.. only:: SOC_WIFI_SUPPORTED
|
||||
|
||||
网络安全
|
||||
--------------------
|
||||
|
||||
Wi-Fi
|
||||
~~~~~
|
||||
|
||||
除传统安全协议 WEP/WPA-TKIP/WPA2-CCMP 外，ESP-IDF 的 Wi-Fi 驱动程序还支持其他先进的安全协议。详情请参阅 :doc:`../api-guides/wifi-security`。
|
||||
|
||||
TLS（传输层安全性协议）
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
建议在 ESP 设备的所有外部通信中使用 TLS，如云通信、OTA 更新等。:doc:`mbedTLS <../api-reference/protocols/mbedtls>` 是 ESP-IDF 官方支持的 TLS 协议栈。
|
||||
|
||||
TLS 默认集成在 :doc:`../api-reference/protocols/esp_http_client`、 :doc:`../api-reference/protocols/esp_https_server` 和其他几个 ESP-IDF 预置的组件中。
|
||||
|
||||
.. note::
|
||||
|
||||
推荐使用 ESP-IDF 协议组件已确认安全的默认配置。请勿禁用 HTTPS 和类似的安全相关配置。
|
||||
|
||||
ESP-TLS 抽象层
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
ESP-IDF 为最常用的 TLS 功能提供了一个抽象层，因此，建议应用程序使用由 :doc:`../api-reference/protocols/esp_tls` 提供的 API。
|
||||
|
||||
:ref:`esp_tls_server_verification` 部分着重描述了在设备端建立服务器身份的多种方式。
|
||||
|
||||
ESP 证书捆绑包
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
调用 :doc:`../api-reference/protocols/esp_crt_bundle` API 即可包含一组自定义 x509 根证书，用于验证 TLS 服务器。对于绝大部分的标准 TLS 服务器，都可以使用证书捆绑包轻松验证服务器身份。
|
||||
|
||||
.. important::
|
||||
|
||||
强烈建议基于 X.509 证书验证服务器身份，谨防与 **伪造** 服务器建立通信。
|
||||
|
||||
|
||||
产品安全
|
||||
----------------
|
||||
|
||||
安全配网
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
安全配网是指将 ESP 设备安全接入 Wi-Fi 网络的过程。该机制还支持在初始配网阶段从配网实体（如智能手机等）获取额外的自定义配置数据。
|
||||
|
||||
ESP-IDF 提供了多种安全方案，可以在 ESP 设备和配网实体之间建立安全会话，具体方案请参阅 :ref:`provisioning_security_schemes`。
|
||||
|
||||
关于该功能的更多详情和代码示例，请参阅 :doc:`../api-reference/provisioning/wifi_provisioning`。
|
||||
|
||||
.. note::
|
||||
|
||||
乐鑫提供了 Android 和 iOS 手机应用程序及其源代码，以便进一步根据产品需求定制安全配网方案。
|
||||
|
||||
安全 OTA 更新
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- OTA 更新必须通过安全传输进行，如 HTTPS。
|
||||
- ESP-IDF 为此提供了一个简化的抽象层，即 :doc:`../api-reference/system/esp_https_ota`。
|
||||
- 如果启用了 :ref:`secure_boot-guide`，则服务器应托管已签名的应用程序镜像。
|
||||
- 如果启用了 :ref:`flash_enc-guide`，则服务器端不需要额外操作，在 flash 写入时，设备将自动加密。
|
||||
- OTA 更新的 :ref:`ota_rollback` 可以在验证完应用程序的功能后，再将应用程序切换为 ``active`` 状态。
|
||||
|
||||
|
||||
防回滚保护
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
防回滚保护功能确保设备仅执行特定版本的应用程序，即应满足设备 eFuse 存储的安全版本条件。因此，即使已由合法密钥信任和签名，应用程序可能包含已撤销的安全功能或凭据，因此设备必须拒绝执行此类应用程序。
|
||||
|
||||
ESP-IDF 仅支持在应用程序使用该功能，并通过二级引导加载程序管理。安全版本存储在设备 eFuse 中，并在启动时和 OTA 更新期间与应用程序镜像头进行比较。
|
||||
|
||||
关于启用此功能的更多详情，请参阅 :ref:`anti-rollback`。
|
||||
|
||||
加密固件分发
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
OTA 更新期间，使用加密的固件分发，可以确保在从服务器 **传输** 到设备的过程中，应用程序保持加密。OTA 更新期间，这可以作为在 TLS 通信之上的额外保护层，保护应用程序身份。
|
||||
|
||||
关于加密固件分发的工作示例，请参阅 :ref:`ota_updates_pre-encrypted-firmware`。
|
||||
|
||||
安全存储
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
安全存储指在设备上以安全方式存储应用程序的特定数据，即将数据存储在外部 flash 中。外部 flash 通常是可读写的 flash 分区，用于存储设备特定的配置数据，如 Wi-Fi 凭据。
|
||||
|
||||
ESP-IDF 提供了 **NVS（非易失性存储）** 管理组件，允许加密数据分区。该功能与上文提到的 :ref:`flash_enc-guide` 平台功能相关。
|
||||
|
||||
关于该功能的工作原理和启用说明，请参阅 :ref:`nvs_encryption`。
|
||||
|
||||
.. important::
|
||||
|
||||
ESP-IDF 组件会默认将 Wi-Fi 证书等设备特定数据写入 NVS 默认分区，建议使用 **NVS 加密** 功能来保护这些数据。
|
||||
|
||||
安全设备控制
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
ESP-IDF 提供了 ESP 本地控制组件，可以通过 ``Wi-Fi + HTTP`` 或 ``BLE`` 安全地控制 ESP 设备。
|
||||
|
||||
关于该功能的更多详情，请参阅 :doc:`../api-reference/protocols/esp_local_ctrl`。
|
||||
|
||||
安全策略
|
||||
---------------
|
||||
|
||||
ESP-IDF GitHub 代码库内含 `安全政策介绍`_。
|
||||
|
||||
公告
|
||||
~~~~~~~~~~
|
||||
|
||||
- 乐鑫会发布重要 `安全公告`_ ，包括硬件和软件相关公告。
|
||||
- ESP-IDF 软件组件的相关安全公告会发布在 `GitHub 仓库`_ 。
|
||||
|
||||
软件更新
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
ESP-IDF 会及时处理针对组件和第三方库的相关报告，并修复关键安全问题。修复内容会逐步同步到 ESP-IDF 的所有适用版本分支中。
|
||||
|
||||
ESP-IDF 的发布说明将涵盖各 ESP-IDF 组件和第三方库的相应安全问题和 CVE 编号。
|
||||
|
||||
.. important::
|
||||
|
||||
为获取所有关键安全修复，建议定期更新到 ESP-IDF 的最新 Bugfix 版本。
|
||||
|
||||
|
||||
.. _`安全政策介绍`: https://github.com/espressif/esp-idf/blob/master/SECURITY.md
|
||||
.. _`安全公告`: https://www.espressif.com/en/support/documents/advisories
|
||||
.. _`GitHub 仓库`: https://github.com/espressif/esp-idf/security/advisories
|
||||
|
||||
Loading…
Reference in New Issue
Block a user