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
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 ESP-IDF boot process. Signature verification happens during both boot-up as well as OTA updates.
Please refer to the Secure Boot (v2) Guide for detailed documentation about this feature.
For ESP32 before ECO3, please refer to Secure Boot (v1) Guide.
重要
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 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 Flash Encryption Guide for detailed documentation about this feature.
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 Secure Boot as an extra layer of protection, and to prevent an attacker from selectively corrupting any part of the flash before boot.
Debug Interfaces
JTAG
JTAG interfaces stays disabled if any of the security features are enabled, please refer to JTAG 与 flash 加密和安全引导 for more information.
JTAG interface can also be disabled in the absence of any other security features using eFuse API.
UART DL Mode
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 esp_efuse_disable_rom_download_mode() at runtime.
重要
If UART Download mode is disabled then esptool can not work on the device.
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 Wi-Fi 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 mbedTLS as the official TLS stack.
TLS is default integrated in ESP HTTP Client, ESP HTTPS Server and several other components that ship with ESP-IDF.
备注
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 ESP-TLS.
TLS Server verification section highlights diverse ways in which the identity of server could be established on the device side.
ESP Certificate Bundle
The ESP x509 Certificate 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.
重要
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 安全方案.
Please refer to the Wi-Fi Provisioning documentation for details and example code for this feature.
备注
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 ESP HTTPS OTA for this.
If Secure Boot is enabled then server should host the signed application image.
If Flash Encryption 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 回滚过程 can help to switch the application as
activeonly 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 防回滚 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 OTA Upgrades with 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 Flash Encryption feature described earlier.
Please refer to the NVS Encryption for detailed documentation on the working and instructions to enable this feature.
重要
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 ESP Local Control 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.
重要
We recommend periodically updating to the latest bugfix version of the ESP-IDF release to have all critical security fixes available.