alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'bugfix/host_security_workflow_docs_update_v5.2' into 'release/v5.2'

Browse Source 
fix(docs): correct the UART ROM DL mode disable section for ESP32 (v5.2)

See merge request espressif/esp-idf!29308
This commit is contained in:
Mahavir Jain 2024-03-06 19:53:43 +08:00
commit 64dcc3cee1
1 changed files with 101 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

197
docs/en/security/host-based-security-workflows.rst
View File

@ -56,7 +56,7 @@ When enabling the Flash Encryption and Secure Boot V2 externally we need to enab
The reason for this order is as follows: The reason for this order is as follows:
To enable the Secure Boot (SB) V2, it is necessary to keep the SB V2 key readable. To protect the key's readability, the write protection for RD_DIS (ESP_EFUSE_WR_DIS_RD_DIS) is applied. However, this action poses a challenge when attempting to enable Flash Encryption, as the Flash Encryption (FE) key needs to remain unreadable. This conflict arises because the RD_DIS is already write-protected, making it impossible to read protect the FE key. To enable the Secure Boot (SB) V2, it is necessary to keep the SB V2 key readable. To protect the key's readability, the write protection for ``RD_DIS`` (``ESP_EFUSE_WR_DIS_RD_DIS``) is applied. However, this action poses a challenge when attempting to enable Flash Encryption, as the Flash Encryption (FE) key needs to remain unreadable. This conflict arises because the ``RD_DIS`` is already write-protected, making it impossible to read protect the FE key.
.. _enable-flash-encryption-externally: .. _enable-flash-encryption-externally:
@ -198,7 +198,7 @@ In this case, all the eFuses related to flash encryption are written with help o
4. Burn the ``{IDF_TARGET_CRYPT_CNT}`` eFuse. 4. Burn the ``{IDF_TARGET_CRYPT_CNT}`` eFuse.
If you only want to enable flash encryption in **Development** mode and want to keep the ability to disable it in the future, Update the {IDF_TARGET_CRYPT_CNT} value in the below command from {IDF_TARGET_CRYPT_CNT_MAX_VAL} to 0x1. (not recommended for production) If you only want to enable flash encryption in **Development** mode and want to keep the ability to disable it in the future, Update the {IDF_TARGET_CRYPT_CNT} value in the below command from {IDF_TARGET_CRYPT_CNT_MAX_VAL} to 0x1 (not recommended for production).
.. code-block:: bash .. code-block:: bash
@ -270,13 +270,13 @@ In this case, all the eFuses related to flash encryption are written with help o
6. Burn flash encryption-related security eFuses as listed below: 6. Burn flash encryption-related security eFuses as listed below:
A) Burn security eFuses: A) Burn security eFuses:
.. important:: .. important::
For production use cases, it is highly recommended to burn all the eFuses listed below. For production use cases, it is highly recommended to burn all the eFuses listed below.
.. list:: .. list::
:esp32: - ``DISABLE_DL_ENCRYPT``: Disable the UART bootloader encryption access. :esp32: - ``DISABLE_DL_ENCRYPT``: Disable the UART bootloader encryption access.
:esp32: - ``DISABLE_DL_DECRYPT``: Disable the UART bootloader decryption access. :esp32: - ``DISABLE_DL_DECRYPT``: Disable the UART bootloader decryption access.
:esp32: - ``DISABLE_DL_CACHE``: Disable the UART bootloader flash cache access. :esp32: - ``DISABLE_DL_CACHE``: Disable the UART bootloader flash cache access.
@ -290,68 +290,72 @@ In this case, all the eFuses related to flash encryption are written with help o
:SOC_EFUSE_DIS_USB_JTAG: - ``DIS_USB_JTAG``: Disable USB switch to JTAG :SOC_EFUSE_DIS_USB_JTAG: - ``DIS_USB_JTAG``: Disable USB switch to JTAG
:SOC_EFUSE_DIS_PAD_JTAG: - ``DIS_PAD_JTAG``: Disable JTAG permanently :SOC_EFUSE_DIS_PAD_JTAG: - ``DIS_PAD_JTAG``: Disable JTAG permanently
:not esp32: - ``DIS_DOWNLOAD_MANUAL_ENCRYPT``: Disable UART bootloader encryption access :not esp32: - ``DIS_DOWNLOAD_MANUAL_ENCRYPT``: Disable UART bootloader encryption access
The respective eFuses can be burned by running: The respective eFuses can be burned by running:
.. code:: bash .. code:: bash
espefuse.py burn_efuse --port PORT EFUSE_NAME 0x1 espefuse.py burn_efuse --port PORT EFUSE_NAME 0x1
.. note:: .. 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.py` can be found `here <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`_.
B) Write protect security eFuses: B) Write protect security eFuses:
After burning the respective eFuses we need to write_protect the security configurations After burning the respective eFuses we need to write_protect the security configurations
.. only:: esp32 .. only:: esp32
.. code:: bash .. code:: bash
espefuse.py --port PORT write_protect_efuse MAC espefuse.py --port PORT write_protect_efuse MAC
.. note:: .. note::
The write disable bit for MAC also write disables DIS_CACHE which is required to prevent accidental burning of this bit. The write disable bit for MAC also write disables DIS_CACHE which is required to prevent accidental burning of this bit.
C) Disable UART ROM DL mode: C) Disable UART ROM DL mode:
.. only:: not esp32
.. code:: bash
espefuse.py --port PORT write_protect_efuse DIS_ICACHE
.. note::
The write protection of above eFuse also write protects multiple other eFuses, Please refer to the {IDF_TARGET_NAME} eFuse table for more details.
C) Enable Security Download mode:
.. warning:: .. warning::
Please burn the following bit at the very end. After this bit is burned, the espefuse tool can no longer be used to burn additional eFuses. Please burn the following bit at the very end. After this bit is burned, the espefuse tool can no longer be used to burn additional eFuses.
.. list:: .. list::
:esp32: - ``UART_DOWNLOAD_DIS`` : Disable the UART ROM Download mode. - ``UART_DOWNLOAD_DIS`` : Disable the UART ROM Download mode.
:not esp32: - ``ENABLE_SECURITY_DOWNLOAD``: Enable Secure ROM download mode
.. only:: esp32
The eFuse can be burned by running: The eFuse can be burned by running:
.. code:: bash .. code:: bash
espefuse.py --port PORT burn_efuse UART_DOWNLOAD_DIS espefuse.py --port PORT burn_efuse UART_DOWNLOAD_DIS
.. only:: not esp32
.. only:: not esp32
.. code:: bash
espefuse.py --port PORT write_protect_efuse DIS_ICACHE
.. note::
The write protection of above eFuse also write protects multiple other eFuses, Please refer to the {IDF_TARGET_NAME} eFuse table for more details.
C) Enable Security Download mode:
.. warning::
Please burn the following bit at the very end. After this bit is burned, the espefuse tool can no longer be used to burn additional eFuses.
.. list::
- ``ENABLE_SECURITY_DOWNLOAD``: Enable Secure ROM download mode
The eFuse can be burned by running: The eFuse can be burned by running:
.. code:: bash .. code:: bash
espefuse.py --port PORT burn_efuse ENABLE_SECURITY_DOWNLOAD espefuse.py --port PORT burn_efuse ENABLE_SECURITY_DOWNLOAD
.. important:: .. important::
@ -510,13 +514,13 @@ In this workflow, we shall use ``espsecure`` tool to generate signing keys and u
7. Burn relevant eFuses. 7. Burn relevant eFuses.
A) Burn security eFuses: A) Burn security eFuses:
.. important:: .. important::
For production use cases, it is highly recommended to burn all the eFuses listed below. For production use cases, it is highly recommended to burn all the eFuses listed below.
.. list:: .. list::
:esp32: - ``JTAG_DISABLE``: Disable the JTAG :esp32: - ``JTAG_DISABLE``: Disable the JTAG
:SOC_EFUSE_DIS_BOOT_REMAP: - ``DIS_BOOT_REMAP``: Disable capability to Remap ROM to RAM address space :SOC_EFUSE_DIS_BOOT_REMAP: - ``DIS_BOOT_REMAP``: Disable capability to Remap ROM to RAM address space
:SOC_EFUSE_HARD_DIS_JTAG: - ``HARD_DIS_JTAG``: Hard disable JTAG peripheral :SOC_EFUSE_HARD_DIS_JTAG: - ``HARD_DIS_JTAG``: Hard disable JTAG peripheral
@ -526,76 +530,79 @@ In this workflow, we shall use ``espsecure`` tool to generate signing keys and u
:SOC_EFUSE_DIS_USB_JTAG: - ``DIS_USB_JTAG``: Disable USB switch to JTAG :SOC_EFUSE_DIS_USB_JTAG: - ``DIS_USB_JTAG``: Disable USB switch to JTAG
:SOC_EFUSE_DIS_PAD_JTAG: - ``DIS_PAD_JTAG``: Disable JTAG permanently :SOC_EFUSE_DIS_PAD_JTAG: - ``DIS_PAD_JTAG``: Disable JTAG permanently
:SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS: - ``SECURE_BOOT_AGGRESSIVE_REVOKE``: Aggressive revocation of key digests, see :ref:`secure-boot-v2-aggressive-key-revocation` for more details. :SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS: - ``SECURE_BOOT_AGGRESSIVE_REVOKE``: Aggressive revocation of key digests, see :ref:`secure-boot-v2-aggressive-key-revocation` for more details.
The respective eFuses can be burned by running: The respective eFuses can be burned by running:
.. code:: bash .. code:: bash
espefuse.py burn_efuse --port PORT EFUSE_NAME 0x1 espefuse.py burn_efuse --port PORT EFUSE_NAME 0x1
.. note:: .. 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.py` can be found `here <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`_
B) Secure Boot V2-related eFuses: B) Secure Boot V2-related eFuses:
i) Disable the ability for read protection: i) Disable the ability for read protection:
The secure boot digest burned in the eFuse must be kept readable otherwise secure boot operation would result in a failure. To prevent the accidental enabling of read protection for this key block we need to burn the following eFuse: The secure boot digest burned in the eFuse must be kept readable otherwise secure boot operation would result in a failure. To prevent the accidental enabling of read protection for this key block we need to burn the following eFuse:
.. code:: bash .. code:: bash
espefuse.py -p $ESPPORT write_protect_efuse RD_DIS espefuse.py -p $ESPPORT write_protect_efuse RD_DIS
.. important:: .. important::
After this eFuse has been burned, read protection cannot be enabled for any key. E.g., if flash encryption which requires read protection for its key is not enabled at this point then it cannot be enabled afterwards. Please ensure that no eFuse keys are going to need read protection after this. After this eFuse has been burned, read protection cannot be enabled for any key. E.g., if flash encryption which requires read protection for its key is not enabled at this point then it cannot be enabled afterwards. Please ensure that no eFuse keys are going to need read protection after this.
.. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS .. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
ii) Revoke key digests: ii) Revoke key digests:
The unused digest slots need to be revoked when we are burning the secure boot key. The respective slots can be revoked by running The unused digest slots need to be revoked when we are burning the secure boot key. The respective slots can be revoked by running
.. code:: bash .. code:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse EFUSE_REVOKE_BIT espefuse.py --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. 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.
.. only:: esp32 .. only:: esp32
C) Disable UART ROM DL mode: C) Disable UART ROM DL mode:
.. only:: not esp32
C) Enable Security Download mode:
.. warning:: .. warning::
Please burn the following bit at the very end. After this bit is burned, the espefuse tool can no longer be used to burn additional eFuses. Please burn the following bit at the very end. After this bit is burned, the espefuse tool can no longer be used to burn additional eFuses.
.. list:: .. list::
:esp32: - ``UART_DOWNLOAD_DIS`` : Disable the UART ROM Download mode. - ``UART_DOWNLOAD_DIS`` : Disable the UART ROM Download mode.
:not esp32: - ``ENABLE_SECURITY_DOWNLOAD``: Enable Secure ROM download mode
.. only:: esp32
The eFuse can be burned by running: The eFuse can be burned by running:
.. code:: bash .. code:: bash
espefuse.py --port PORT burn_efuse UART_DOWNLOAD_DIS espefuse.py --port PORT burn_efuse UART_DOWNLOAD_DIS
.. only:: not esp32
.. only:: not esp32
The eFuse can be burned by running:
C) Enable Security Download mode:
.. code:: bash
.. warning::
Please burn the following bit at the very end. After this bit is burned, the espefuse tool can no longer be used to burn additional eFuses.
.. list::
- ``ENABLE_SECURITY_DOWNLOAD``: Enable Secure ROM download mode
The eFuse can be burned by running:
.. code:: bash
espefuse.py --port PORT burn_efuse ENABLE_SECURITY_DOWNLOAD espefuse.py --port PORT burn_efuse ENABLE_SECURITY_DOWNLOAD
Secure Boot V2 Guidelines Secure Boot V2 Guidelines
@ -606,5 +613,3 @@ Secure Boot V2 Guidelines
.. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS .. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
* It is recommended to use all the available digest slots to reduce dependency on a single private key. * It is recommended to use all the available digest slots to reduce dependency on a single private key.