espressif/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-04-27 19:13:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: Update esptool to v5

Browse Source
This commit is contained in:
Peter Dragun
2025-08-11 16:11:49 +02:00
parent 053fb47e78
commit e3198fff3c
129 changed files with 1237 additions and 1318 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/security/flash-encryption.rst
+13 -13
View File
@@ -13,7 +13,7 @@ This is a quick start guide to {IDF_TARGET_NAME}'s flash encryption feature. Usi
.. note::
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure.py <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure.py`` based counterparts.
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure`` based counterparts.
Introduction
------------
@@ -55,7 +55,7 @@ Other types of data can be encrypted conditionally:
Relevant eFuses
---------------
The flash encryption operation is controlled by various eFuses available on {IDF_TARGET_NAME}. The list of eFuses and their descriptions is given in the table below. The names in eFuse column are also used by ``espefuse.py`` tool and ``idf.py`` based eFuse commands. For usage in the eFuse API, modify the name by adding ``ESP_EFUSE_``, for example: esp_efuse_read_field_bit (ESP_EFUSE_DISABLE_DL_ENCRYPT).
The flash encryption operation is controlled by various eFuses available on {IDF_TARGET_NAME}. The list of eFuses and their descriptions is given in the table below. The names in eFuse column are also used by ``espefuse`` tool and ``idf.py`` based eFuse commands. For usage in the eFuse API, modify the name by adding ``ESP_EFUSE_``, for example: esp_efuse_read_field_bit (ESP_EFUSE_DISABLE_DL_ENCRYPT).
.. Comment: As text in cells of list-table header rows does not wrap, it is necessary to make 0 header rows and apply bold typeface to the first row. Otherwise, the table goes beyond the html page limits on the right.
@@ -164,7 +164,7 @@ The flash encryption operation is controlled by various eFuses available on {IDF
* R/W access control is available for all the eFuse bits listed in the table above.
* The default value of these bits is 0 after manufacturing.
Read and write access to eFuse bits is controlled by appropriate fields in the registers ``WR_DIS`` and ``RD_DIS``. For more information on {IDF_TARGET_NAME} eFuses, see :doc:`eFuse manager <../api-reference/system/efuse>`. To change protection bits of eFuse field using ``idf.py``, use these two commands: efuse-read-protect and efuse-write-protect (idf.py based aliases of espefuse.py commands write_protect_efuse and read_protect_efuse). Example ``idf.py efuse-write-protect DISABLE_DL_ENCRYPT``.
Read and write access to eFuse bits is controlled by appropriate fields in the registers ``WR_DIS`` and ``RD_DIS``. For more information on {IDF_TARGET_NAME} eFuses, see :doc:`eFuse manager <../api-reference/system/efuse>`. To change protection bits of eFuse field using ``idf.py``, use these two commands: efuse-read-protect and efuse-write-protect (idf.py based aliases of espefuse commands write-protect-efuse and read-protect-efuse). Example ``idf.py efuse-write-protect DISABLE_DL_ENCRYPT``.
.. only:: esp32c2
@@ -462,8 +462,8 @@ To use a host generated key, take the following steps:
.. code-block:: bash
espefuse.py --port PORT --chip esp32c2 burn_key_digest secure_boot_signing_key.pem \
burn_key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
espefuse --port PORT --chip esp32c2 burn-key-digest secure_boot_signing_key.pem \
burn-key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
If the key is not burned and the device is started after enabling flash encryption, the {IDF_TARGET_NAME} will generate a random key that software cannot access or modify.
@@ -571,7 +571,7 @@ When using Flash Encryption in production:
- Do not reuse the same flash encryption key between multiple devices. This means that an attacker who copies encrypted data from one device cannot transfer it to a second device.
:esp32: - When using ESP32 V3, if the UART ROM Download Mode is not needed for a production device then it should be disabled to provide an extra level of protection. Do this by calling :cpp:func:`esp_efuse_disable_rom_download_mode` during application startup. Alternatively, configure the project :ref:`CONFIG_ESP32_REV_MIN` level to 3 (targeting ESP32 V3 only) and select the :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` to "Permanently disable ROM Download Mode (recommended)". The ability to disable ROM Download Mode is not available on earlier ESP32 versions.
:not esp32: - The UART ROM Download Mode should be disabled entirely if it is not needed, or permanently set to "Secure Download Mode" otherwise. Secure Download Mode permanently limits the available commands to updating SPI config, changing baud rate, basic flash write, and returning a summary of the currently enabled security features with the `get_security_info` command. The default behaviour is to set Secure Download Mode on first boot in Release mode. To disable Download Mode entirely, select :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.
:not esp32: - The UART ROM Download Mode should be disabled entirely if it is not needed, or permanently set to "Secure Download Mode" otherwise. Secure Download Mode permanently limits the available commands to updating SPI config, changing baud rate, basic flash write, and returning a summary of the currently enabled security features with the `get-security-info` command. The default behaviour is to set Secure Download Mode on first boot in Release mode. To disable Download Mode entirely, select :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.
- Enable :doc:`Secure Boot <secure-boot-v2>` as an extra layer of protection, and to prevent an attacker from selectively corrupting any part of the flash before boot.
Enable Flash Encryption Externally
@@ -961,7 +961,7 @@ However, before the first boot you can choose to keep any of these features enab
Write protection of all the three eFuses is controlled by one bit. It means that write-protecting one eFuse bit will inevitably write-protect all unset eFuse bits.
Write protecting these eFuses to keep them unset is not currently very useful, as ``esptool.py`` does not support reading encrypted flash.
Write protecting these eFuses to keep them unset is not currently very useful, as ``esptool`` does not support reading encrypted flash.
.. only:: esp32
@@ -1018,7 +1018,7 @@ For example, these are the steps to encrypt the file ``my-app.bin`` to flash at
idf.py secure-encrypt-flash-data --aes-xts --keyfile /path/to/key.bin --address 0x10000 --output my-app-ciphertext.bin my-app.bin
The file ``my-app-ciphertext.bin`` can then be flashed to offset 0x10000 using ``esptool.py``. To see all of the command line options recommended for ``esptool.py``, see the output printed when ``idf.py build`` succeeds.
The file ``my-app-ciphertext.bin`` can then be flashed to offset 0x10000 using ``esptool``. To see all of the command line options recommended for ``esptool``, see the output printed when ``idf.py build`` succeeds.
.. note::
@@ -1075,9 +1075,9 @@ The following sections provide some reference information about the operation of
- The high 19 bits of the block offset (bit 5 to bit 23) are XORed with the main flash encryption key. This range is chosen for two reasons: the maximum flash size is 16MB (24 bits), and each block is 32 bytes so the least significant 5 bits are always zero.
- There is a particular mapping from each of the 19 block offset bits to the 256 bits of the flash encryption key to determine which bit is XORed with which. See the variable ``_FLASH_ENCRYPTION_TWEAK_PATTERN`` in the ``espsecure.py`` source code for complete mapping.
- There is a particular mapping from each of the 19 block offset bits to the 256 bits of the flash encryption key to determine which bit is XORed with which. See the variable ``_FLASH_ENCRYPTION_TWEAK_PATTERN`` in the ``espsecure`` source code for complete mapping.
- To see the full flash encryption algorithm implemented in Python, refer to the ``_flash_encryption_operation()`` function in the ``espsecure.py`` source code.
- To see the full flash encryption algorithm implemented in Python, refer to the ``_flash_encryption_operation()`` function in the ``espsecure`` source code.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
@@ -1092,7 +1092,7 @@ The following sections provide some reference information about the operation of
- The flash encryption key is stored in one or two ``BLOCK_KEYN`` eFuses and, by default, is protected from further writes or software readout.
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure.py`` source code.
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure`` source code.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
@@ -1108,7 +1108,7 @@ The following sections provide some reference information about the operation of
- The flash encryption key is stored in one ``BLOCK_KEYN`` eFuse and, by default, is protected from further writes or software readout.
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure.py`` source code.
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure`` source code.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
@@ -1123,7 +1123,7 @@ The following sections provide some reference information about the operation of
- The flash encryption key is stored in ``BLOCK_KEY0`` eFuse and, by default, is protected from further writes or software readout.
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure.py`` source code.
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure`` source code.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND
docs/en/security/secure-boot-v1.rst
+8 -8
View File
@@ -19,7 +19,7 @@ Secure boot is separate from the :doc:`flash-encryption` feature, and you can us
.. note::
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure.py <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure.py`` based counterparts.
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure`` based counterparts.
Background
----------
@@ -105,7 +105,7 @@ How to Enable Secure Boot
For production environments, we recommend generating the key pair using OpenSSL or another industry-standard encryption program. See :ref:`secure-boot-generate-key` for more details.
5. Run ``idf.py bootloader`` to build a secure boot-enabled bootloader. The build output will include a prompt for a flashing command, using ``esptool.py write_flash``.
5. Run ``idf.py bootloader`` to build a secure boot-enabled bootloader. The build output will include a prompt for a flashing command, using ``esptool write-flash``.
.. _secure-boot-resume-normal-flashing:
@@ -149,7 +149,7 @@ To enable a reflashable bootloader:
1. In the :ref:`project-configuration-menu`, select ``Bootloader Config`` > :ref:`CONFIG_SECURE_BOOT` > ``CONFIG_SECURE_BOOT_V1_ENABLED`` > :ref:`CONFIG_SECURE_BOOTLOADER_MODE` > ``Reflashable``.
2. If necessary, set the :ref:`CONFIG_SECURE_BOOTLOADER_KEY_ENCODING` based on the coding scheme used by the device. The coding scheme is shown in the ``Features`` line when ``esptool.py`` connects to the chip, or in the ``idf.py efuse-summary`` output.
2. If necessary, set the :ref:`CONFIG_SECURE_BOOTLOADER_KEY_ENCODING` based on the coding scheme used by the device. The coding scheme is shown in the ``Features`` line when ``esptool`` connects to the chip, or in the ``idf.py efuse-summary`` output.
3. Please follow the steps shown in :ref:`secure-boot-generate-key` to generate the signing key. The path of the generated key file must be specified in the ``Secure Boot Configuration`` menu.
@@ -181,7 +181,7 @@ Remember that the strength of the secure boot system depends on keeping the sign
Remote Signing of Images
------------------------
For production builds, it can be good practice to use a remote signing server rather than have the signing key on the build machine, which is the default ESP-IDF secure boot configuration. The ``espsecure.py`` command line program can be used to sign app images & partition table data for secure boot, on a remote system.
For production builds, it can be good practice to use a remote signing server rather than have the signing key on the build machine, which is the default ESP-IDF secure boot configuration. The ``espsecure`` command line program can be used to sign app images & partition table data for secure boot, on a remote system.
To use remote signing, disable the option ``Sign binaries during build``. The private signing key does not need to be present on the build system. However, the public signature verification key is required because it is compiled into the bootloader, and can be used to verify image signatures during OTA updates.
@@ -189,7 +189,7 @@ To extract the public key from the private key:
.. code-block::
espsecure.py extract_public_key --keyfile PRIVATE_SIGNING_KEY PUBLIC_VERIFICATION_KEY
espsecure extract-public-key --keyfile PRIVATE_SIGNING_KEY PUBLIC_VERIFICATION_KEY
The path to the public signature verification key needs to be specified in the menuconfig under ``Secure boot public signature verification key`` in order to build the secure bootloader.
@@ -211,7 +211,7 @@ Secure Boot Best Practices
* Generate the signing key on a system with a quality source of entropy.
* Keep the signing key private at all times. 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`` or ``idf.py secure-`` subcommands. Both processes are vulnerable to timing or other side-channel attacks.
* Do not allow any third party to observe any aspects of the key generation or signing process using ``espsecure`` or ``idf.py secure-`` subcommands. Both processes are vulnerable to timing or other side-channel attacks.
* Enable all secure boot options in Secure Boot Configuration. These include flash encryption, disabling of JTAG, disabling BASIC ROM interpreter, and disabling the UART bootloader encrypted flash access.
* Use secure boot in combination with :doc:`flash-encryption` to prevent local readout of the flash contents.
@@ -245,7 +245,7 @@ Secure Bootloader Digest Algorithm
Starting with an "image" of binary data as input, this algorithm generates a digest as output. The digest is sometimes referred to as an "abstract" in hardware documentation.
For a Python version of this algorithm, see the ``espsecure.py`` tool in the :component:`/esptool_py` directory. Specifically, the ``digest_secure_bootloader`` command.
For a Python version of this algorithm, see the ``espsecure`` tool in the :component:`/esptool_py` directory. Specifically, the ``digest-secure-bootloader`` command.
Items marked with (^) are to fulfill hardware restrictions, as opposed to cryptographic restrictions.
@@ -309,7 +309,7 @@ The output of the ``idf.py secure-digest-secure-bootloader`` command is a single
.. code-block::
esptool.py write_flash 0x0 bootloader-digest.bin
esptool write-flash 0x0 bootloader-digest.bin
.. _secure-boot-and-flash-encr:
docs/en/security/secure-boot-v2.rst
+8 -8
View File
@@ -50,7 +50,7 @@ Secure Boot v2
.. note::
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure.py <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure.py`` based counterparts.
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure`` based counterparts.
Background
----------
@@ -350,7 +350,7 @@ In the Secure Boot v2 scheme, the application image is padded to the flash MMU p
- Default flash MMU page size is 64 KB
:SOC_MMU_PAGE_SIZE_CONFIGURABLE: - {IDF_TARGET_NAME} supports configurable flash MMU page size, and ``CONFIG_MMU_PAGE_SIZE`` gets set based on the :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`
- Secure padding is applied through the option ``--secure-pad-v2`` in the ``elf2image`` conversion using ``esptool.py``
- Secure padding is applied through the option ``--secure-pad-v2`` in the ``elf2image`` conversion using ``esptool``
The following table explains the Secure Boot v2 signed image with secure padding and signature block appended:
@@ -487,7 +487,7 @@ How To Enable Secure Boot v2
For production environments, we recommend generating the key pair using OpenSSL or another industry-standard encryption program. See :ref:`secure-boot-v2-generate-key` for more details.
7. Run ``idf.py bootloader`` to build a Secure Boot-enabled bootloader. The build output will include a prompt for a flashing command, using ``esptool.py write_flash``.
7. Run ``idf.py bootloader`` to build a Secure Boot-enabled bootloader. The build output will include a prompt for a flashing command, using ``esptool write-flash``.
8. When you are ready to flash the bootloader, run the specified command and then wait for flashing to complete. You have to enter it yourself, this step is not performed by the build system.
@@ -621,7 +621,7 @@ Remote Signing of Images
Signing Using ``idf.py``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For production builds, it can be good practice to use a remote signing server rather than have the signing key on the build machine (which is the default ESP-IDF Secure Boot configuration). The ``espsecure.py`` command line program can be used to sign app images and partition table data for Secure Boot, on a remote system.
For production builds, it can be good practice to use a remote signing server rather than have the signing key on the build machine (which is the default ESP-IDF Secure Boot configuration). The ``espsecure`` command line program can be used to sign app images and partition table data for Secure Boot, on a remote system.
To use remote signing, disable the option :ref:`CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES` and build the firmware. The private signing key does not need to be present on the build system.
@@ -663,7 +663,7 @@ In such cases, disable the option :ref:`CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES
.. note::
For all the above three remote signing workflows, the signed binary is written to the filename provided to the ``--output`` argument, and the option ``--append_signatures`` allows us to append multiple signatures (up to 3) to the image.
For all the above three remote signing workflows, the signed binary is written to the filename provided to the ``--output`` argument, and the option ``--append-signatures`` allows us to append multiple signatures (up to 3) to the image.
.. only:: not SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
@@ -689,7 +689,7 @@ Secure Boot Best Practices
* Between 1 and 3 {IDF_TARGET_SBV2_KEY} public key pairs (Keys #0, #1, #2) should be computed independently and stored separately.
* The KEY_DIGEST eFuses should be write-protected after being programmed.
* The unused KEY_DIGEST slots must have their corresponding KEY_REVOKE eFuse burned to permanently disable them. This must happen before the device leaves the factory.
* The eFuses can either be written by the second stage bootloader during first boot after enabling ``Secure Boot v2`` from menuconfig or can be done using ``espefuse.py`` which communicates with the serial bootloader program in ROM.
* The eFuses can either be written by the second stage bootloader during first boot after enabling ``Secure Boot v2`` from menuconfig or can be done using ``espefuse`` which communicates with the serial bootloader program in ROM.
* The KEY_DIGESTs should be numbered sequentially beginning at key digest #0. If key digest #1 is used, key digest #0 should be used. If key digest #2 is used, key digest #0 & #1 must be used.
* The second stage bootloader is non-OTA upgradeable, and is signed using at least one, possibly all three, private keys and flashed in the factory.
* Apps should only be signed with a single private key, with the others being stored securely elsewhere. However, they may be signed with multiple private keys if some are being revoked, see :ref:`secure-boot-v2-key-revocation` below.
@@ -704,14 +704,14 @@ Secure Boot Best Practices
.. code-block::
idf.py secure-sign-data -k secure_boot_signing_key2.pem --append_signatures -o signed_bootloader.bin build/bootloader/bootloader.bin
idf.py secure-sign-data -k secure_boot_signing_key2.pem --append-signatures -o signed_bootloader.bin build/bootloader/bootloader.bin
* While signing with multiple private keys, it is recommended that the private keys be signed independently, if possible on different servers and stored separately.
* You can check the signatures attached to a binary using:
.. code-block::
espsecure.py signature_info_v2 datafile.bin
espsecure signature-info-v2 datafile.bin
.. only:: SOC_ECDSA_SUPPORT_CURVE_P384
docs/en/security/security-features-enablement-workflows.rst
+58 -58
View File
@@ -9,7 +9,7 @@ Security Features Enablement Workflows
{IDF_TARGET_CRYPT_CNT:default="SPI_BOOT_CRYPT_CNT",esp32="FLASH_CRYPT_CNT"}
{IDF_TARGET_CRYPT_CNT_MAX_VAL:default="7",esp32="127"}
{IDF_TARGET_SBV2_DEFAULT_SCHEME:default="RSA", esp32c2="ECDSA (V2)"}
{IDF_TARGET_FLASH_ENC_ARGS:default="--aes_xts", esp32=""}
{IDF_TARGET_FLASH_ENC_ARGS:default="--aes-xts", esp32=""}
Introduction
------------
@@ -83,7 +83,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code:: bash
esptool.py --port PORT erase_flash
esptool --port PORT erase-flash
2. Generate a Flash Encryption key
@@ -93,7 +93,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
espsecure generate-flash-encryption-key my_flash_encryption_key.bin
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
@@ -101,20 +101,20 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
espsecure generate-flash-encryption-key my_flash_encryption_key.bin
else if :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-256 (512-bit key):
.. code-block:: bash
espsecure.py generate_flash_encryption_key --keylen 512 my_flash_encryption_key.bin
espsecure generate-flash-encryption-key --keylen 512 my_flash_encryption_key.bin
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
espsecure generate-flash-encryption-key my_flash_encryption_key.bin
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
@@ -122,13 +122,13 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
espsecure generate-flash-encryption-key my_flash_encryption_key.bin
else if :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-128 key derived from 128 bits (SHA256(128 bits)):
.. code-block:: bash
espsecure.py generate_flash_encryption_key --keylen 128 my_flash_encryption_key.bin
espsecure generate-flash-encryption-key --keylen 128 my_flash_encryption_key.bin
3. Burn the Flash Encryption key into eFuse
@@ -142,13 +142,13 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin
espefuse --port PORT burn-key flash_encryption my_flash_encryption_key.bin
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin KEYPURPOSE
espefuse --port PORT burn-key BLOCK my_flash_encryption_key.bin KEYPURPOSE
where ``BLOCK`` is a free keyblock between ``BLOCK_KEY0`` and ``BLOCK_KEY5``. And ``KEYPURPOSE`` is either ``XTS_AES_256_KEY_1``, ``XTS_AES_256_KEY_2``, ``XTS_AES_128_KEY``. See `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ for a description of the key purposes.
@@ -156,28 +156,28 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY
espefuse --port PORT burn-key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY
For AES-256 (512-bit key) - ``XTS_AES_256_KEY_1`` and ``XTS_AES_256_KEY_2``. ``espefuse.py`` supports burning both these two key purposes together with a 512-bit key to two separate key blocks via the virtual key purpose ``XTS_AES_256_KEY``. When this is used ``espefuse.py`` will burn the first 256 bits of the key to the specified ``BLOCK`` and burn the corresponding block key purpose to ``XTS_AES_256_KEY_1``. The last 256 bits of the key will be burned to the first free key block after ``BLOCK`` and the corresponding block key purpose to ``XTS_AES_256_KEY_2``
For AES-256 (512-bit key) - ``XTS_AES_256_KEY_1`` and ``XTS_AES_256_KEY_2``. ``espefuse`` supports burning both these two key purposes together with a 512-bit key to two separate key blocks via the virtual key purpose ``XTS_AES_256_KEY``. When this is used ``espefuse`` will burn the first 256 bits of the key to the specified ``BLOCK`` and burn the corresponding block key purpose to ``XTS_AES_256_KEY_1``. The last 256 bits of the key will be burned to the first free key block after ``BLOCK`` and the corresponding block key purpose to ``XTS_AES_256_KEY_2``
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin XTS_AES_256_KEY
espefuse --port PORT burn-key BLOCK my_flash_encryption_key.bin XTS_AES_256_KEY
If you wish to specify exactly which two blocks are used then it is possible to divide the key into two 256-bit keys, and manually burn each half with ``XTS_AES_256_KEY_1`` and ``XTS_AES_256_KEY_2`` as key purposes:
.. code-block:: bash
split -b 32 my_flash_encryption_key.bin my_flash_encryption_key.bin
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin.aa XTS_AES_256_KEY_1
espefuse.py --port PORT burn_key BLOCK+1 my_flash_encryption_key.bin.ab XTS_AES_256_KEY_2
espefuse --port PORT burn-key BLOCK my_flash_encryption_key.bin.aa XTS_AES_256_KEY_1
espefuse --port PORT burn-key BLOCK+1 my_flash_encryption_key.bin.ab XTS_AES_256_KEY_2
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY
espefuse --port PORT burn-key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY
where ``BLOCK`` is a free keyblock between ``BLOCK_KEY0`` and ``BLOCK_KEY5``.
@@ -187,20 +187,20 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK_KEY0 flash_encryption_key256.bin XTS_AES_128_KEY
espefuse --port PORT burn-key BLOCK_KEY0 flash_encryption_key256.bin XTS_AES_128_KEY
For AES-128 key derived from SHA256(128 eFuse bits) - ``XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS``. The FE key will be written in the lower part of eFuse BLOCK_KEY0. The upper 128 bits are not used and will remain available for reading by software. Using the special mode of the espefuse tool, shown in the ``For burning both keys together`` section below, the user can write their data to it using any espefuse commands.
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
espefuse --port PORT burn-key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
For burning both keys together (Secure Boot and Flash Encryption):
.. code-block:: bash
espefuse.py --port PORT --chip esp32c2 burn_key_digest secure_boot_signing_key.pem \
burn_key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
espefuse --port PORT --chip esp32c2 burn-key-digest secure_boot_signing_key.pem \
burn-key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
.. only:: SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK
@@ -216,7 +216,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse {IDF_TARGET_CRYPT_CNT} {IDF_TARGET_CRYPT_CNT_MAX_VAL}
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse {IDF_TARGET_CRYPT_CNT} {IDF_TARGET_CRYPT_CNT_MAX_VAL}
.. only:: esp32
@@ -224,7 +224,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse FLASH_CRYPT_CONFIG 0xF
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse FLASH_CRYPT_CONFIG 0xF
5. Burn Flash Encryption-related security eFuses as listed below
@@ -256,11 +256,11 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code:: bash
espefuse.py burn_efuse --port PORT EFUSE_NAME 0x1
espefuse burn-efuse --port PORT EFUSE_NAME 0x1
.. note::
Please update the ``EFUSE_NAME`` with the eFuse that you need to burn. Multiple eFuses can be burned at the same time by appending them to the above command (e.g., ``EFUSE_NAME VAL EFUSE_NAME2 VAL2``). More documentation about `espefuse.py` can be found `here <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`_.
Please update the ``EFUSE_NAME`` with the eFuse that you need to burn. Multiple eFuses can be burned at the same time by appending them to the above command (e.g., ``EFUSE_NAME VAL EFUSE_NAME2 VAL2``). More documentation about `espefuse` can be found `here <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`_.
.. only:: esp32
@@ -270,7 +270,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code:: bash
espefuse.py --port PORT write_protect_efuse DIS_CACHE
espefuse --port PORT write-protect-efuse DIS_CACHE
.. note::
@@ -284,7 +284,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code:: bash
espefuse.py --port PORT write_protect_efuse DIS_ICACHE
espefuse --port PORT write-protect-efuse DIS_ICACHE
.. note::
@@ -312,15 +312,15 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espsecure.py encrypt_flash_data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} --output bootloader-enc.bin build/bootloader/bootloader.bin
espsecure encrypt-flash-data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} --output bootloader-enc.bin build/bootloader/bootloader.bin
espsecure.py encrypt_flash_data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address 0x8000 --output partition-table-enc.bin build/partition_table/partition-table.bin
espsecure encrypt-flash-data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address 0x8000 --output partition-table-enc.bin build/partition_table/partition-table.bin
espsecure.py encrypt_flash_data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address 0x10000 --output my-app-enc.bin build/my-app.bin
espsecure encrypt-flash-data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address 0x10000 --output my-app-enc.bin build/my-app.bin
In the above command, the offsets are used for a sample firmware, and the actual offset for your firmware can be obtained by checking the partition table entry or by running `idf.py partition-table`. Please note that not all the binaries need to be encrypted, the encryption applies only to those generated from the partitions which are marked as ``encrypted`` in the partition table definition file. Other binaries are flashed unencrypted, i.e., as a plain output of the build process.
The above files can then be flashed to their respective offset using ``esptool.py``. To see all of the command line options recommended for ``esptool.py``, see the output printed when ``idf.py build`` succeeds.
The above files can then be flashed to their respective offset using ``esptool``. To see all of the command line options recommended for ``esptool``, see the output printed when ``idf.py build`` succeeds.
When the application contains the following partition: ``otadata`` and ``nvs_encryption_keys``, they need to be encrypted as well. Please refer to :ref:`encrypted-partitions` for more details about encrypted partitions.
@@ -330,9 +330,9 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. only:: esp32
If your ESP32 uses non-default :ref:`FLASH_CRYPT_CONFIG value in eFuse <setting-flash-crypt-config>` then you will need to pass the ``--flash_crypt_conf`` argument to ``espsecure.py`` to set the matching value. This will not happen when the Flash Encryption is enabled by the second stage bootloader but may happen when burning eFuses manually to enable Flash Encryption.
If your ESP32 uses non-default :ref:`FLASH_CRYPT_CONFIG value in eFuse <setting-flash-crypt-config>` then you will need to pass the ``--flash-crypt-conf`` argument to ``espsecure`` to set the matching value. This will not happen when the Flash Encryption is enabled by the second stage bootloader but may happen when burning eFuses manually to enable Flash Encryption.
The command ``espsecure.py decrypt_flash_data`` can be used with the same options (and different input or output files), to decrypt ciphertext flash contents or a previously encrypted file.
The command ``espsecure decrypt-flash-data`` can be used with the same options (and different input or output files), to decrypt ciphertext flash contents or a previously encrypted file.
8. Secure the ROM download mode
@@ -352,7 +352,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code:: bash
espefuse.py --port PORT burn_efuse UART_DOWNLOAD_DIS
espefuse --port PORT burn-efuse UART_DOWNLOAD_DIS
.. only:: not esp32
@@ -366,7 +366,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code:: bash
espefuse.py --port PORT burn_efuse ENABLE_SECURITY_DOWNLOAD
espefuse --port PORT burn-efuse ENABLE_SECURITY_DOWNLOAD
.. important::
@@ -396,7 +396,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espsecure.py generate_signing_key --version 2 --scheme rsa3072 secure_boot_signing_key.pem
espsecure generate-signing-key --version 2 --scheme rsa3072 secure_boot_signing_key.pem
.. only:: SOC_SECURE_BOOT_V2_ECC
@@ -404,7 +404,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espsecure.py generate_signing_key --version 2 --scheme ecdsa256 secure_boot_signing_key.pem
espsecure generate-signing-key --version 2 --scheme ecdsa256 secure_boot_signing_key.pem
.. only:: not SOC_ECDSA_SUPPORT_CURVE_P384
@@ -424,7 +424,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espsecure.py digest_sbv2_public_key --keyfile secure_boot_signing_key.pem --output digest.bin
espsecure digest-sbv2-public-key --keyfile secure_boot_signing_key.pem --output digest.bin
.. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
@@ -438,19 +438,19 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espefuse.py --port PORT --chip esp32 burn_key secure_boot_v2 digest.bin
espefuse --port PORT --chip esp32 burn-key secure_boot_v2 digest.bin
.. only:: esp32c2
.. code:: bash
espefuse.py --port PORT --chip esp32c2 burn_key KEY_BLOCK0 digest.bin SECURE_BOOT_DIGEST
espefuse --port PORT --chip esp32c2 burn-key KEY_BLOCK0 digest.bin SECURE_BOOT_DIGEST
.. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
.. code:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_key BLOCK digest.bin SECURE_BOOT_DIGEST0
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-key BLOCK digest.bin SECURE_BOOT_DIGEST0
where ``BLOCK`` is a free keyblock between ``BLOCK_KEY0`` and ``BLOCK_KEY5``.
@@ -464,13 +464,13 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espefuse.py --port PORT --chip esp32 burn_efuse ABS_DONE_1
espefuse --port PORT --chip esp32 burn-efuse ABS_DONE_1
.. only:: not esp32
.. code:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse SECURE_BOOT_EN
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse SECURE_BOOT_EN
.. only:: SOC_ECDSA_SUPPORT_CURVE_P384
@@ -478,7 +478,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse SECURE_BOOT_SHA384_EN
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse SECURE_BOOT_SHA384_EN
5. Burn relevant eFuses
@@ -507,11 +507,11 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espefuse.py burn_efuse --port PORT EFUSE_NAME 0x1
espefuse burn-efuse --port PORT EFUSE_NAME 0x1
.. note::
Please update the EFUSE_NAME with the eFuse that you need to burn. Multiple eFuses can be burned at the same time by appending them to the above command (e.g., EFUSE_NAME VAL EFUSE_NAME2 VAL2). More documentation about `espefuse.py` can be found `here <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`_
Please update the EFUSE_NAME with the eFuse that you need to burn. Multiple eFuses can be burned at the same time by appending them to the above command (e.g., EFUSE_NAME VAL EFUSE_NAME2 VAL2). More documentation about `espefuse` can be found `here <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`_
B) Secure Boot v2-related eFuses
@@ -521,7 +521,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espefuse.py -p $ESPPORT write_protect_efuse RD_DIS
espefuse -p $ESPPORT write-protect-efuse RD_DIS
.. important::
@@ -535,7 +535,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse EFUSE_REVOKE_BIT
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse EFUSE_REVOKE_BIT
The ``EFUSE_REVOKE_BIT`` in the above command can be ``SECURE_BOOT_KEY_REVOKE0`` or ``SECURE_BOOT_KEY_REVOKE1`` or ``SECURE_BOOT_KEY_REVOKE2``. Please note that only the unused key digests must be revoked. Once revoked, the respective digest cannot be used again.
@@ -565,9 +565,9 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espsecure.py sign_data --version 2 --keyfile secure_boot_signing_key.pem --output bootloader-signed.bin build/bootloader/bootloader.bin
espsecure sign-data --version 2 --keyfile secure_boot_signing_key.pem --output bootloader-signed.bin build/bootloader/bootloader.bin
espsecure.py sign_data --version 2 --keyfile secure_boot_signing_key.pem --output my-app-signed.bin build/my-app.bin
espsecure sign-data --version 2 --keyfile secure_boot_signing_key.pem --output my-app-signed.bin build/my-app.bin
.. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
@@ -575,9 +575,9 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espsecure.py sign_data --keyfile secure_boot_signing_key2.pem --version 2 --append_signatures -o bootloader-signed2.bin bootloader-signed.bin
espsecure sign-data --keyfile secure_boot_signing_key2.pem --version 2 --append-signatures -o bootloader-signed2.bin bootloader-signed.bin
espsecure.py sign_data --keyfile secure_boot_signing_key2.pem --version 2 --append_signatures -o my-app-signed2.bin my-app-signed.bin
espsecure sign-data --keyfile secure_boot_signing_key2.pem --version 2 --append-signatures -o my-app-signed2.bin my-app-signed.bin
The same process can be repeated for the third key. Note that the names of the input and output files must not be the same.
@@ -585,9 +585,9 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espsecure.py signature_info_v2 bootloader-signed.bin
espsecure signature-info-v2 bootloader-signed.bin
The above files along with other binaries (e.g., partition table) can then be flashed to their respective offset using ``esptool.py``. To see all of the command line options recommended for ``esptool.py``, see the output printed when ``idf.py build`` succeeds. The flash offset for your firmware can be obtained by checking the partition table entry or by running ``idf.py partition-table``.
The above files along with other binaries (e.g., partition table) can then be flashed to their respective offset using ``esptool``. To see all of the command line options recommended for ``esptool``, see the output printed when ``idf.py build`` succeeds. The flash offset for your firmware can be obtained by checking the partition table entry or by running ``idf.py partition-table``.
8. Secure the ROM download mode
@@ -607,7 +607,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espefuse.py --port PORT burn_efuse UART_DOWNLOAD_DIS
espefuse --port PORT burn-efuse UART_DOWNLOAD_DIS
.. only:: not esp32
@@ -621,7 +621,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espefuse.py --port PORT burn_efuse ENABLE_SECURITY_DOWNLOAD
espefuse --port PORT burn-efuse ENABLE_SECURITY_DOWNLOAD
Secure Boot v2 Guidelines
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -667,7 +667,7 @@ The details about NVS encryption and related schemes can be found at :doc:`NVS E
.. code:: bash
espefuse.py --port PORT burn_key BLOCK hmac_key.bin HMAC_UP
espefuse --port PORT burn-key BLOCK hmac_key.bin HMAC_UP
Here, ``BLOCK`` is a free keyblock between ``BLOCK_KEY0`` and ``BLOCK_KEY5``.
@@ -697,7 +697,7 @@ The details about NVS encryption and related schemes can be found at :doc:`NVS E
5. Flash NVS partition
The NVS partition (``nvs_encr_partition.bin``) generated in Step 3 can then be flashed to its respective offset using ``esptool.py``. To see all of the command line options recommended for ``esptool.py``, check the output printed when ``idf.py build`` succeeds.
The NVS partition (``nvs_encr_partition.bin``) generated in Step 3 can then be flashed to its respective offset using ``esptool``. To see all of the command line options recommended for ``esptool``, check the output printed when ``idf.py build`` succeeds.
If Flash Encryption is enabled for the chip, please encrypt the partition first before flashing. More details please refer to the flashing related steps of `Flash Encryption workflow <enable-flash-encryption-externally_>`_.
@@ -743,6 +743,6 @@ In this case we generate NVS Encryption keys on a host. This key is then flashed
4. Flash NVS partition and NVS encryption keys
The NVS partition (``nvs_encr_partition.bin``) and NVS encryption key (``nvs_encr_key.bin``) can then be flashed to their respective offset using ``esptool.py``. To see all of the command line options recommended for ``esptool.py``, check the output print when ``idf.py build`` succeeds.
The NVS partition (``nvs_encr_partition.bin``) and NVS encryption key (``nvs_encr_key.bin``) can then be flashed to their respective offset using ``esptool``. To see all of the command line options recommended for ``esptool``, check the output print when ``idf.py build`` succeeds.
If Flash Encryption is enabled for the chip, then please encrypt the partition first before flashing. You may refer the flashing related steps of `Flash Encryption workflow <enable-flash-encryption-externally_>`_.
docs/en/security/security.rst
+5 -5
View File
@@ -11,7 +11,7 @@ This guide provides an overview of the overall security features available in va
.. note::
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure.py <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure.py`` based counterparts.
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure`` based counterparts.
.. only:: TARGET_SUPPORT_QEMU
@@ -55,7 +55,7 @@ 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 ``idf.py secure-`` or ``espsecure.py`` commands. Both processes are vulnerable to timing or other side-channel attacks.
* Do not allow any third party to observe any aspects of the key generation or signing process using ``idf.py secure-`` or ``espsecure`` commands. 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.
@@ -183,7 +183,7 @@ UART Download Mode
.. important::
If UART Download mode is disabled then ``esptool.py`` can not work on the device.
If UART Download mode is disabled then ``esptool`` can not work on the device.
.. only:: SOC_SUPPORTS_SECURE_DL_MODE
@@ -191,12 +191,12 @@ UART Download 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, e.g., changing baud rate, basic flash write, and the command to return a summary of currently enabled security features (``get_security_info``).
* 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.py`` can only work with the argument ``--no-stub``.
In Secure UART Download mode, ``esptool`` can only work with the argument ``--no-stub``.
.. only:: SOC_WIFI_SUPPORTED