mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
feat(docs): Add workflow for externally enabling NVS Encryption
Fix documentation for host based workflows for flash encryption and
secure boot v2
This commit is contained in:
Aditya Patwardhan
parent
617130a485
commit
1366949c8a
@ -18,6 +18,8 @@ To use this utility in encryption mode, install the following packages:
|
|||||||
|
|
||||||
All the required packages are included in `requirements.txt` in the root of the ESP-IDF directory.
|
All the required packages are included in `requirements.txt` in the root of the ESP-IDF directory.
|
||||||
|
|
||||||
|
.. _nvs-csv-file-format:
|
||||||
|
|
||||||
CSV File Format
|
CSV File Format
|
||||||
~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
@ -242,6 +244,8 @@ You can run the utility to generate only the encryption key partition using the
|
|||||||
|
|
||||||
.. note:: You can provide the custom filename for the HMAC key as well as the encryption key as a parameter.
|
.. note:: You can provide the custom filename for the HMAC key as well as the encryption key as a parameter.
|
||||||
|
|
||||||
|
.. _generate-encrypted-nvs-partition:
|
||||||
|
|
||||||
Generate Encrypted NVS Partition
|
Generate Encrypted NVS Partition
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
|||||||
@ -18,6 +18,8 @@ NVS 分区生成程序适合用于生成二进制数据 (blob)，其中包括设
|
|||||||
|
|
||||||
根目录下的 `requirements.txt` 包含必需 python 包，请预先安装。
|
根目录下的 `requirements.txt` 包含必需 python 包，请预先安装。
|
||||||
|
|
||||||
|
.. _nvs-csv-file-format:
|
||||||
|
|
||||||
CSV 文件格式
|
CSV 文件格式
|
||||||
~~~~~~~~~~~~
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
@ -242,6 +244,8 @@ NVS 分区生成程序还可使用 XTS-AES 加密生成二进制加密文件或
|
|||||||
|
|
||||||
.. note:: 可将自定义文件名作为参数提供给 HMAC 密钥和加密密钥。
|
.. note:: 可将自定义文件名作为参数提供给 HMAC 密钥和加密密钥。
|
||||||
|
|
||||||
|
.. _generate-encrypted-nvs-partition:
|
||||||
|
|
||||||
生成 NVS 加密分区
|
生成 NVS 加密分区
|
||||||
~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
|||||||
@ -1,3 +1,6 @@
|
|||||||
|
..
|
||||||
|
WARNING: The steps of each section in the document are referenced at multiple places. If you are changing the step number by adding/deleting a step then make sure to update the references respectively.
|
||||||
|
|
||||||
Host-Based Security Workflows
|
Host-Based Security Workflows
|
||||||
=============================
|
=============================
|
||||||
|
|
||||||
@ -36,6 +39,7 @@ Scope
|
|||||||
* :ref:`enable-flash-encryption-and-secure-boot-v2-externally`
|
* :ref:`enable-flash-encryption-and-secure-boot-v2-externally`
|
||||||
* :ref:`enable-flash-encryption-externally`
|
* :ref:`enable-flash-encryption-externally`
|
||||||
* :ref:`enable-secure-boot-v2-externally`
|
* :ref:`enable-secure-boot-v2-externally`
|
||||||
|
* :ref:`enable-nvs-encryption-externally`
|
||||||
|
|
||||||
Security Workflows
|
Security Workflows
|
||||||
------------------
|
------------------
|
||||||
@ -49,35 +53,39 @@ Enable Flash Encryption and Secure Boot V2 Externally
|
|||||||
|
|
||||||
It is recommended to enable both Flash Encryption and Secure Boot V2 for a production use case.
|
It is recommended to enable both Flash Encryption and Secure Boot V2 for a production use case.
|
||||||
|
|
||||||
When enabling the Flash Encryption and Secure Boot V2 externally we need to enable them in the following order:
|
When enabling the Flash Encryption and Secure Boot V2 together we need to enable them in the following order:
|
||||||
|
|
||||||
#. Enable the Flash Encryption feature by following the steps listed in :ref:`enable-flash-encryption-externally`.
|
#. Enable the Flash Encryption feature by following the steps listed in :ref:`enable-flash-encryption-externally`.
|
||||||
#. Enable the Secure Boot V2 feature by following the steps listed in :ref:`enable-secure-boot-v2-externally`.
|
#. Enable the Secure Boot V2 feature by following the steps listed in :ref:`enable-secure-boot-v2-externally`.
|
||||||
|
|
||||||
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.
|
.. note::
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
Enable Flash Encryption Externally
|
Enable Flash Encryption Externally
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
In this case, all the eFuses related to flash encryption are written with help of the espefuse tool. More details about flash encryption can be found in the :doc:`Flash Encryption Guide </security/flash-encryption>`
|
In this case, all the eFuses related to Flash Encryption are written with help of the espefuse tool. More details about flash encryption can be found in the :doc:`Flash Encryption Guide </security/flash-encryption>`
|
||||||
|
|
||||||
1. Ensure that you have an {IDF_TARGET_NAME} device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`.
|
1. Check device status
|
||||||
|
|
||||||
See how to check :ref:`flash-encryption-status`.
|
Ensure that you have an {IDF_TARGET_NAME} device with default Flash Encryption eFuse settings as shown in :ref:`flash-encryption-efuse`.
|
||||||
|
|
||||||
In this case, the flash on the chip must be erased and flash encryption must not be enabled. The chip can be erased by running:
|
See how to check :ref:`flash-encryption-status`.
|
||||||
|
|
||||||
|
At this point, the Flash Encryption must not be already enabled on the chip. Additionally, the flash on the chip needs to be erased, which can be done by running:
|
||||||
|
|
||||||
.. code:: bash
|
.. code:: bash
|
||||||
|
|
||||||
esptool.py --port PORT erase_flash
|
esptool.py --port PORT erase_flash
|
||||||
|
|
||||||
2. Generate a flash encryption key.
|
2. Generate a Flash Encryption key
|
||||||
|
|
||||||
A random flash encryption key can be generated by running:
|
A random Flash Encryption key can be generated by running:
|
||||||
|
|
||||||
.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES
|
.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES
|
||||||
|
|
||||||
@ -120,7 +128,7 @@ In this case, all the eFuses related to flash encryption are written with help o
|
|||||||
|
|
||||||
espsecure.py generate_flash_encryption_key --keylen 128 my_flash_encryption_key.bin
|
espsecure.py generate_flash_encryption_key --keylen 128 my_flash_encryption_key.bin
|
||||||
|
|
||||||
3. Burn the flash encryption key into eFuse.
|
3. Burn the Flash Encryption key into eFuse
|
||||||
|
|
||||||
This action **cannot be reverted**. It can be done by running:
|
This action **cannot be reverted**. It can be done by running:
|
||||||
|
|
||||||
@ -196,9 +204,9 @@ In this case, all the eFuses related to flash encryption are written with help o
|
|||||||
For the {IDF_TARGET_NAME} BLOCK9 (BLOCK_KEY5) can not be used by XTS_AES keys.
|
For the {IDF_TARGET_NAME} BLOCK9 (BLOCK_KEY5) can not be used by XTS_AES keys.
|
||||||
|
|
||||||
|
|
||||||
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
|
||||||
|
|
||||||
@ -212,74 +220,9 @@ In this case, all the eFuses related to flash encryption are written with help o
|
|||||||
|
|
||||||
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse FLASH_CRYPT_CONFIG 0xF
|
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse FLASH_CRYPT_CONFIG 0xF
|
||||||
|
|
||||||
.. note::
|
5. Burn Flash Encryption-related security eFuses as listed below
|
||||||
|
|
||||||
At this point, the flash encryption on the device has been enabled. You may test the flash encryption process as given in step 5. Please note that the security-related eFuses have not been burned at this point. It is recommended that they should be burned in production use cases as explained in step 6.
|
A) Burn security eFuses
|
||||||
|
|
||||||
5. Encrypt and flash the binaries.
|
|
||||||
|
|
||||||
The bootloader and the application binaries for the project must be built with Flash Encryption Release mode with default configurations.
|
|
||||||
|
|
||||||
Flash encryption Release mode can be set in the menuconfig as follows:
|
|
||||||
|
|
||||||
.. list::
|
|
||||||
|
|
||||||
- :ref:`Enable flash encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`
|
|
||||||
:esp32: - :ref:`Select Release mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (Note that once Release mode is selected, the ``DISABLE_DL_ENCRYPT`` and ``DISABLE_DL_DECRYPT`` eFuse bits will be burned to disable flash encryption hardware in ROM Download Mode.)
|
|
||||||
:esp32: - :ref:`Select UART ROM download mode (Permanently disabled (recommended)) <CONFIG_SECURE_UART_ROM_DL_MODE>` (Note that this option is only available when :ref:`CONFIG_ESP32_REV_MIN` is set to 3 (ESP32 V3).) The default choice is to keep UART ROM download mode enabled, however it is recommended to permanently disable this mode to reduce the options available to an attacker.
|
|
||||||
:not esp32: - :ref:`Select Release mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (Note that once Release mode is selected, the ``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` eFuse bit will be burned to disable flash encryption hardware in ROM Download Mode.)
|
|
||||||
:not esp32: - :ref:`Select UART ROM download mode (Permanently switch to Secure mode (recommended)) <CONFIG_SECURE_UART_ROM_DL_MODE>`. This is the default option and is recommended. It is also possible to change this configuration setting to permanently disable UART ROM download mode, if this mode is not needed.
|
|
||||||
- :ref:`Select the appropriate bootloader log verbosity <CONFIG_BOOTLOADER_LOG_LEVEL>`
|
|
||||||
- Save the configuration and exit.
|
|
||||||
|
|
||||||
|
|
||||||
The binaries can be encrypted on the host machine by running:
|
|
||||||
|
|
||||||
.. only:: esp32
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
espsecure.py encrypt_flash_data --keyfile my_flash_encryption_key.bin --address 0x1000 --output bootloader-enc.bin build/bootloader/bootloader.bin
|
|
||||||
|
|
||||||
espsecure.py encrypt_flash_data --keyfile my_flash_encryption_key.bin --address 0x8000 --output partition-table-enc.bin build/partition_table/partition-table.bin
|
|
||||||
|
|
||||||
espsecure.py encrypt_flash_data --keyfile my_flash_encryption_key.bin --address 0x10000 --output my-app-enc.bin build/my-app.bin
|
|
||||||
|
|
||||||
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
espsecure.py encrypt_flash_data --keyfile my_flash_encryption_key.bin --address 0x2000 --output bootloader-enc.bin build/bootloader/bootloader.bin
|
|
||||||
|
|
||||||
espsecure.py encrypt_flash_data --keyfile my_flash_encryption_key.bin --address 0x8000 --output partition-table-enc.bin build/partition_table/partition-table.bin
|
|
||||||
|
|
||||||
espsecure.py encrypt_flash_data --keyfile my_flash_encryption_key.bin --address 0x10000 --output my-app-enc.bin build/my-app.bin
|
|
||||||
|
|
||||||
.. only:: not esp32
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
espsecure.py encrypt_flash_data --aes_xts --keyfile my_flash_encryption_key.bin --address 0x0 --output bootloader-enc.bin build/my-app.bin
|
|
||||||
|
|
||||||
espsecure.py encrypt_flash_data --aes_xts --keyfile my_flash_encryption_key.bin --address 0x8000 --output partition-table-enc.bin build/partition_table/partition-table.bin
|
|
||||||
|
|
||||||
espsecure.py encrypt_flash_data --aes_xts --keyfile my_flash_encryption_key.bin --address 0x10000 --output my-app-enc.bin build/my-app.bin
|
|
||||||
|
|
||||||
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. In the above command the offsets are used for a sample firmware, the actual offset for your firmware can be obtained by checking the partition table entry or by running `idf.py partition-table`. When the application contains the following partition: ``otadata``, ``nvs_encryption_keys`` they need to be encrypted as well. Please refer to :ref:`encrypted-partitions` for more details about encrypted partitions.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
If the flashed ciphertext file is not recognized by the {IDF_TARGET_NAME} when it boots, check that the keys match and that the command line arguments match exactly, including the correct offset. It is important to provide the correct offset as the ciphertext changes when the offset changes.
|
|
||||||
|
|
||||||
.. 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 if the device configured flash encryption by itself 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/output files), to decrypt ciphertext flash contents or a previously encrypted file.
|
|
||||||
|
|
||||||
6. Burn flash encryption-related security eFuses as listed below:
|
|
||||||
|
|
||||||
A) Burn security eFuses:
|
|
||||||
|
|
||||||
.. important::
|
.. important::
|
||||||
|
|
||||||
@ -287,13 +230,13 @@ In this case, all the eFuses related to flash encryption are written with help o
|
|||||||
|
|
||||||
.. 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
|
||||||
: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_DIS_DOWNLOAD_ICACHE: - ``DIS_DOWNLOAD_ICACHE``: Disable UART cache
|
:SOC_EFUSE_DIS_DOWNLOAD_ICACHE: - ``DIS_DOWNLOAD_ICACHE``: Disable UART cache
|
||||||
:SOC_EFUSE_DIS_DOWNLOAD_DCACHE: - ``DIS_DOWNLOAD_DCACHE``: Disable UART cache.
|
:SOC_EFUSE_DIS_DOWNLOAD_DCACHE: - ``DIS_DOWNLOAD_DCACHE``: Disable UART cache
|
||||||
:SOC_EFUSE_HARD_DIS_JTAG: - ``HARD_DIS_JTAG``: Hard disable JTAG peripheral
|
:SOC_EFUSE_HARD_DIS_JTAG: - ``HARD_DIS_JTAG``: Hard disable JTAG peripheral
|
||||||
:SOC_EFUSE_DIS_DIRECT_BOOT:- ``DIS_DIRECT_BOOT``: Disable direct boot (legacy SPI boot mode)
|
:SOC_EFUSE_DIS_DIRECT_BOOT:- ``DIS_DIRECT_BOOT``: Disable direct boot (legacy SPI boot mode)
|
||||||
:SOC_EFUSE_DIS_LEGACY_SPI_BOOT: - ``DIS_LEGACY_SPI_BOOT``: Disable legacy SPI boot mode
|
:SOC_EFUSE_DIS_LEGACY_SPI_BOOT: - ``DIS_LEGACY_SPI_BOOT``: Disable legacy SPI boot mode
|
||||||
@ -312,74 +255,142 @@ In this case, all the eFuses related to flash encryption are written with help o
|
|||||||
|
|
||||||
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
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
espefuse.py --port PORT write_protect_efuse MAC
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
The write disable bit for MAC also write disables DIS_CACHE which is required to prevent accidental burning of this bit.
|
||||||
|
|
||||||
|
.. 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.
|
||||||
|
|
||||||
|
6. Configure the project
|
||||||
|
|
||||||
|
The bootloader and the application binaries for the project must be built with Flash Encryption Release mode with default configurations.
|
||||||
|
|
||||||
|
Flash encryption Release mode can be set in the menuconfig as follows:
|
||||||
|
|
||||||
|
.. list::
|
||||||
|
|
||||||
|
- :ref:`Enable Flash Encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`
|
||||||
|
:esp32: - :ref:`Select Release mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (Note that once Release mode is selected, the ``DISABLE_DL_ENCRYPT`` and ``DISABLE_DL_DECRYPT`` eFuse bits will be burned to disable Flash Encryption hardware in ROM Download Mode)
|
||||||
|
:esp32: - :ref:`Select UART ROM download mode (Permanently disabled (recommended)) <CONFIG_SECURE_UART_ROM_DL_MODE>` (Note that this option is only available when :ref:`CONFIG_ESP32_REV_MIN` is set to 3 (ESP32 V3).) The default choice is to keep UART ROM download mode enabled, however it is recommended to permanently disable this mode to reduce the options available to an attacker
|
||||||
|
:not esp32: - :ref:`Select Release mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (Note that once Release mode is selected, the ``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` eFuse bit will be burned to disable Flash Encryption hardware in ROM Download Mode)
|
||||||
|
:not esp32: - :ref:`Select UART ROM download mode (Permanently switch to Secure mode (recommended)) <CONFIG_SECURE_UART_ROM_DL_MODE>`. This is the default option and is recommended. It is also possible to change this configuration setting to permanently disable UART ROM download mode, if this mode is not needed
|
||||||
|
- :ref:`Select the appropriate bootloader log verbosity <CONFIG_BOOTLOADER_LOG_LEVEL>`
|
||||||
|
- Save the configuration and exit
|
||||||
|
|
||||||
|
7. Build, Encrypt and Flash the binaries
|
||||||
|
|
||||||
|
The binaries can be encrypted on the host machine by running:
|
||||||
|
|
||||||
.. only:: esp32
|
.. only:: esp32
|
||||||
|
|
||||||
.. code:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
espefuse.py --port PORT write_protect_efuse MAC
|
espsecure.py encrypt_flash_data --keyfile my_flash_encryption_key.bin --address 0x1000 --output bootloader-enc.bin build/bootloader/bootloader.bin
|
||||||
|
|
||||||
.. note::
|
espsecure.py encrypt_flash_data --keyfile my_flash_encryption_key.bin --address 0x8000 --output partition-table-enc.bin build/partition_table/partition-table.bin
|
||||||
|
|
||||||
The write disable bit for MAC also write disables DIS_CACHE which is required to prevent accidental burning of this bit.
|
espsecure.py encrypt_flash_data --keyfile my_flash_encryption_key.bin --address 0x10000 --output my-app-enc.bin build/my-app.bin
|
||||||
|
|
||||||
C) Disable UART ROM DL mode:
|
.. only:: not esp32 and not SOC_KEY_MANAGER_SUPPORTED
|
||||||
|
|
||||||
.. warning::
|
.. code-block:: bash
|
||||||
|
|
||||||
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.
|
espsecure.py encrypt_flash_data --aes_xts --keyfile my_flash_encryption_key.bin --address 0x1000 --output bootloader-enc.bin build/bootloader/bootloader.bin
|
||||||
|
|
||||||
.. list::
|
espsecure.py encrypt_flash_data --aes_xts --keyfile my_flash_encryption_key.bin --address 0x8000 --output partition-table-enc.bin build/partition_table/partition-table.bin
|
||||||
|
|
||||||
- ``UART_DOWNLOAD_DIS`` : Disable the UART ROM Download mode.
|
espsecure.py encrypt_flash_data --aes_xts --keyfile my_flash_encryption_key.bin --address 0x10000 --output my-app-enc.bin build/my-app.bin
|
||||||
|
|
||||||
The eFuse can be burned by running:
|
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
||||||
|
|
||||||
.. code:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
espefuse.py --port PORT burn_efuse UART_DOWNLOAD_DIS
|
espsecure.py encrypt_flash_data --keyfile my_flash_encryption_key.bin --address 0x2000 --output bootloader-enc.bin build/bootloader/bootloader.bin
|
||||||
|
|
||||||
|
espsecure.py encrypt_flash_data --keyfile my_flash_encryption_key.bin --address 0x8000 --output partition-table-enc.bin build/partition_table/partition-table.bin
|
||||||
|
|
||||||
|
espsecure.py encrypt_flash_data --keyfile my_flash_encryption_key.bin --address 0x10000 --output my-app-enc.bin build/my-app.bin
|
||||||
|
|
||||||
|
|
||||||
.. only:: not esp32
|
In the above command the offsets are used for a sample firmware, 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.
|
||||||
|
|
||||||
.. code:: bash
|
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.
|
||||||
|
|
||||||
espefuse.py --port PORT write_protect_efuse DIS_ICACHE
|
When the application contains the following partition: ``otadata``, ``nvs_encryption_keys`` they need to be encrypted as well. Please refer to :ref:`encrypted-partitions` for more details about encrypted partitions.
|
||||||
|
|
||||||
.. note::
|
.. 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.
|
If the flashed ciphertext file is not recognized by the {IDF_TARGET_NAME} when it boots, check that the keys match and that the command line arguments match exactly, including the correct offset. It is important to provide the correct offset as the ciphertext changes when the offset changes.
|
||||||
|
|
||||||
C) Enable Security Download mode:
|
.. only:: esp32
|
||||||
|
|
||||||
.. warning::
|
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 firmware bootloader but may happen when burning eFuses manually to enable flash encryption.
|
||||||
|
|
||||||
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.
|
The command ``espsecure.py decrypt_flash_data`` can be used with the same options (and different input/output files), to decrypt ciphertext flash contents or a previously encrypted file.
|
||||||
|
|
||||||
.. list::
|
8. Secure the ROM Download mode
|
||||||
|
|
||||||
- ``ENABLE_SECURITY_DOWNLOAD``: Enable Secure ROM download mode
|
.. warning::
|
||||||
|
|
||||||
The eFuse can be burned by running:
|
Please perform the following step at the very end. After this eFuse is burned, the espefuse tool can no longer be used to burn additional eFuses.
|
||||||
|
|
||||||
.. code:: bash
|
.. only: esp32
|
||||||
|
|
||||||
espefuse.py --port PORT burn_efuse ENABLE_SECURITY_DOWNLOAD
|
Disable UART ROM DL mode:
|
||||||
|
|
||||||
|
.. list::
|
||||||
|
|
||||||
|
- ``UART_DOWNLOAD_DIS`` : Disable the UART ROM Download mode
|
||||||
|
|
||||||
|
The eFuse can be burned by running:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
espefuse.py --port PORT burn_efuse UART_DOWNLOAD_DIS
|
||||||
|
|
||||||
|
.. only:: not esp32
|
||||||
|
|
||||||
|
Enable Security Download mode:
|
||||||
|
|
||||||
|
.. 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
|
||||||
|
|
||||||
.. important::
|
.. important::
|
||||||
|
|
||||||
7. Delete flash encryption key on host:
|
9. Delete Flash Encryption key on host
|
||||||
|
|
||||||
Once the flash encryption has been enabled for the device, the key **must be deleted immediately**. This ensures that the host cannot produce encrypted binaries for the same device going forward. This step is important to reduce the vulnerability of the flash encryption key.
|
Once the Flash Encryption has been enabled for the device, the key **must be deleted immediately**. This ensures that the host cannot produce encrypted binaries for the same device going forward. This step is important to reduce the vulnerability of the flash encryption key.
|
||||||
|
|
||||||
Flash Encryption Guidelines
|
Flash Encryption Guidelines
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
* It is recommended to generate a unique flash encryption key for each device for production use-cases.
|
* It is recommended to generate a unique Flash Encryption key for each device for production use-cases.
|
||||||
* It is recommended to ensure that the RNG used by host machine to generate the flash encryption key has good entropy.
|
* It is recommended to ensure that the RNG used by host machine to generate the Flash Encryption key has good entropy.
|
||||||
* See :ref:`flash-encryption-limitations` for more details.
|
* See :ref:`flash-encryption-limitations` for more details.
|
||||||
|
|
||||||
.. _enable-secure-boot-v2-externally:
|
.. _enable-secure-boot-v2-externally:
|
||||||
@ -389,7 +400,7 @@ Enable Secure Boot V2 Externally
|
|||||||
|
|
||||||
In this workflow, we shall use ``espsecure`` tool to generate signing keys and use the ``espefuse`` tool to burn the relevant eFuses. The details about the Secure Boot V2 process can be found at :doc:`Secure Boot V2 Guide </security/secure-boot-v2>`
|
In this workflow, we shall use ``espsecure`` tool to generate signing keys and use the ``espefuse`` tool to burn the relevant eFuses. The details about the Secure Boot V2 process can be found at :doc:`Secure Boot V2 Guide </security/secure-boot-v2>`
|
||||||
|
|
||||||
1. Generate Secure Boot V2 Signing Private Key.
|
1. Generate Secure Boot V2 Signing Private Key
|
||||||
|
|
||||||
.. only:: esp32 or SOC_SECURE_BOOT_V2_RSA
|
.. only:: esp32 or SOC_SECURE_BOOT_V2_RSA
|
||||||
|
|
||||||
@ -403,9 +414,9 @@ In this workflow, we shall use ``espsecure`` tool to generate signing keys and u
|
|||||||
|
|
||||||
The Secure Boot V2 signing key for ECDSA scheme can be generated by running:
|
The Secure Boot V2 signing key for ECDSA scheme can be generated by running:
|
||||||
|
|
||||||
.. code:: bash
|
.. code:: bash
|
||||||
|
|
||||||
espsecure.py generate_signing_key --version 2 --scheme ecdsa256 secure_boot_signing_key.pem
|
espsecure.py generate_signing_key --version 2 --scheme ecdsa256 secure_boot_signing_key.pem
|
||||||
|
|
||||||
The scheme in the above command can be changed to ``ecdsa192`` to generate ecdsa192 private key.
|
The scheme in the above command can be changed to ``ecdsa192`` to generate ecdsa192 private key.
|
||||||
|
|
||||||
@ -413,7 +424,7 @@ In this workflow, we shall use ``espsecure`` tool to generate signing keys and u
|
|||||||
|
|
||||||
A total of 3 keys can be used for Secure Boot V2 at once. These should be computed independently and stored separately. The same command with different key file names can be used to generate multiple Secure Boot V2 signing keys. It is recommended to use multiple keys in order to reduce dependency on a single key.
|
A total of 3 keys can be used for Secure Boot V2 at once. These should be computed independently and stored separately. The same command with different key file names can be used to generate multiple Secure Boot V2 signing keys. It is recommended to use multiple keys in order to reduce dependency on a single key.
|
||||||
|
|
||||||
2. Generate Public Key Digest.
|
2. Generate Public Key Digest
|
||||||
|
|
||||||
The public key digest for the private key generated in the previous step can be generated by running:
|
The public key digest for the private key generated in the previous step can be generated by running:
|
||||||
|
|
||||||
@ -425,7 +436,7 @@ In this workflow, we shall use ``espsecure`` tool to generate signing keys and u
|
|||||||
|
|
||||||
In case of multiple digests, each digest should be kept in a separate file.
|
In case of multiple digests, each digest should be kept in a separate file.
|
||||||
|
|
||||||
3. Burn the key digest in eFuse.
|
3. Burn the key digest in eFuse
|
||||||
|
|
||||||
The public key digest can be burned in the eFuse by running:
|
The public key digest can be burned in the eFuse by running:
|
||||||
|
|
||||||
@ -439,19 +450,19 @@ In this workflow, we shall use ``espsecure`` tool to generate signing keys and u
|
|||||||
|
|
||||||
.. code:: bash
|
.. code:: bash
|
||||||
|
|
||||||
espefuse.py --port PORT --chip esp32c2 burn_key KEY_BLOCK0 SECURE_BOOT_DIGEST digest.bin
|
espefuse.py --port PORT --chip esp32c2 burn_key KEY_BLOCK0 digest.bin SECURE_BOOT_DIGEST
|
||||||
|
|
||||||
.. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
|
.. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
|
||||||
|
|
||||||
.. code:: bash
|
.. code:: bash
|
||||||
|
|
||||||
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_key BLOCK SECURE_BOOT_DIGEST0 digest.bin
|
espefuse.py --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``.
|
where ``BLOCK`` is a free keyblock between ``BLOCK_KEY0`` and ``BLOCK_KEY5``.
|
||||||
|
|
||||||
In case of multiple digests, the other digests can be burned sequentially by changing the key purpose to ``SECURE_BOOT_DIGEST1`` and ``SECURE_BOOT_DIGEST2`` respectively.
|
In case of multiple digests, the other digests can be burned sequentially by changing the key purpose to ``SECURE_BOOT_DIGEST1`` and ``SECURE_BOOT_DIGEST2`` respectively.
|
||||||
|
|
||||||
4. Enable Secure Boot V2.
|
4. Enable Secure Boot V2
|
||||||
|
|
||||||
Secure Boot V2 eFuse can be enabled by running:
|
Secure Boot V2 eFuse can be enabled by running:
|
||||||
|
|
||||||
@ -467,64 +478,9 @@ In this workflow, we shall use ``espsecure`` tool to generate signing keys and u
|
|||||||
|
|
||||||
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse SECURE_BOOT_EN
|
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse SECURE_BOOT_EN
|
||||||
|
|
||||||
|
5. Burn relevant eFuses
|
||||||
|
|
||||||
.. note::
|
A) Burn security eFuses
|
||||||
|
|
||||||
At this stage the secure boot V2 has been enabled for the {IDF_TARGET_NAME}. The ROM bootloader shall now verify the authenticity of the :ref:`second-stage-bootloader` on every bootup. You may test the secure boot process by executing Steps 5 & 6. Please note that security-related eFuses have not been burned at this point. For production use cases, all security-related eFuses must be burned as given in step 7.
|
|
||||||
|
|
||||||
5. Build the binaries.
|
|
||||||
|
|
||||||
By default, the ROM bootloader would only verify the :ref:`second-stage-bootloader` (firmware bootloader). The firmware bootloader would verify the app partition only when the :ref:`CONFIG_SECURE_BOOT` option is enabled (and :ref:`CONFIG_SECURE_BOOT_VERSION` is set to ``SECURE_BOOT_V2_ENABLED``) while building the bootloader.
|
|
||||||
|
|
||||||
a) Open the :ref:`project-configuration-menu`, in "Security features" set "Enable hardware Secure Boot in bootloader" to enable Secure Boot.
|
|
||||||
|
|
||||||
.. only:: esp32
|
|
||||||
|
|
||||||
For ESP32, Secure Boot V2 is available only for ESP32 ECO3 onwards. To view the "Secure Boot V2" option the chip revision should be changed to revision v3.0 (ECO3). To change the chip revision, set "Minimum Supported ESP32 Revision" to "Rev 3.0 (ECO3)" in "Component Config" -> "Hardware Settings" -> "Chip Revision".
|
|
||||||
|
|
||||||
.. only:: SOC_SECURE_BOOT_V2_RSA or SOC_SECURE_BOOT_V2_ECC
|
|
||||||
|
|
||||||
The "Secure Boot V2" option will be selected and the "App Signing Scheme" will be set to {IDF_TARGET_SBV2_DEFAULT_SCHEME} by default.
|
|
||||||
|
|
||||||
b) Disable the option :ref:`CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES` for the project in the :ref:`project-configuration-menu`. This shall make sure that all the generated binaries are secure padded and unsigned. This step is done to avoid generating signed binaries as we are going to manually sign the binaries using ``espsecure`` tool.
|
|
||||||
|
|
||||||
After the above configurations, the bootloader and application binaries can be built with ``idf.py build`` command.
|
|
||||||
|
|
||||||
6. Sign and Flash the binaries.
|
|
||||||
|
|
||||||
The Secure Boot V2 workflow only verifies the ``bootloader`` and ``application`` binaries, hence only those binaries need to be signed. The other binaries (e.g., ``partition-table.bin``) can be flashed as they are generated in the build stage.
|
|
||||||
|
|
||||||
The ``bootloader.bin`` and ``app.bin`` binaries can be signed by running:
|
|
||||||
|
|
||||||
.. code:: bash
|
|
||||||
|
|
||||||
espsecure.py 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
|
|
||||||
|
|
||||||
.. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
|
|
||||||
|
|
||||||
If multiple keys secure boot keys are to be used then the same signed binary can be appended with a signature block signed with the new key as follows:
|
|
||||||
|
|
||||||
.. code:: bash
|
|
||||||
|
|
||||||
espsecure.py 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
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
The signatures attached to a binary can be checked by running:
|
|
||||||
|
|
||||||
.. code:: bash
|
|
||||||
|
|
||||||
espsecure.py 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``.
|
|
||||||
|
|
||||||
7. Burn relevant eFuses.
|
|
||||||
|
|
||||||
A) Burn security eFuses:
|
|
||||||
|
|
||||||
.. important::
|
.. important::
|
||||||
|
|
||||||
@ -552,26 +508,25 @@ In this workflow, we shall use ``espsecure`` tool to generate signing keys and u
|
|||||||
|
|
||||||
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 read-protection option:
|
||||||
|
|
||||||
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 the Secure Boot operation would result in a failure. To prevent the accidental enabling of read protection for this key block, the following eFuse needs to be burned:
|
||||||
|
|
||||||
|
.. important::
|
||||||
|
|
||||||
|
After burning above-mentioned eFuse, the 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 completing this step.
|
||||||
|
|
||||||
.. code:: bash
|
.. code:: bash
|
||||||
|
|
||||||
espefuse.py -p $ESPPORT write_protect_efuse RD_DIS
|
espefuse.py -p $ESPPORT write_protect_efuse RD_DIS
|
||||||
|
|
||||||
.. 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.
|
|
||||||
|
|
||||||
|
|
||||||
.. 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
|
||||||
|
|
||||||
@ -579,48 +534,212 @@ In this workflow, we shall use ``espsecure`` tool to generate signing keys and u
|
|||||||
|
|
||||||
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.
|
||||||
|
|
||||||
|
6. Configure the project
|
||||||
|
|
||||||
|
By default, the ROM bootloader would only verify the :ref:`second-stage-bootloader` (firmware bootloader). The firmware bootloader would verify the app partition only when the :ref:`CONFIG_SECURE_BOOT` option is enabled (and :ref:`CONFIG_SECURE_BOOT_VERSION` is set to ``SECURE_BOOT_V2_ENABLED``) while building the bootloader.
|
||||||
|
|
||||||
|
a) Open the :ref:`project-configuration-menu`, in "Security features" set "Enable hardware Secure Boot in bootloader" to enable Secure Boot.
|
||||||
|
|
||||||
.. only:: esp32
|
.. only:: esp32
|
||||||
|
|
||||||
C) Disable UART ROM DL mode:
|
For ESP32, Secure Boot V2 is available only for ESP32 ECO3 onwards. To view the "Secure Boot V2" option the chip revision should be changed to revision v3.0 (ECO3). To change the chip revision, set "Minimum Supported ESP32 Revision" to "Rev 3.0 (ECO3)" in "Component Config" -> "Hardware Settings" -> "Chip Revision".
|
||||||
|
|
||||||
.. warning::
|
.. only:: SOC_SECURE_BOOT_V2_RSA or SOC_SECURE_BOOT_V2_ECC
|
||||||
|
|
||||||
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.
|
The "Secure Boot V2" option will be selected and the "App Signing Scheme" will be set to {IDF_TARGET_SBV2_DEFAULT_SCHEME} by default.
|
||||||
|
|
||||||
.. list::
|
b) Disable the option :ref:`CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES` for the project in the :ref:`project-configuration-menu`. This shall make sure that all the generated binaries are secure padded and unsigned. This step is done to avoid generating signed binaries as we are going to manually sign the binaries using ``espsecure`` tool.
|
||||||
|
|
||||||
- ``UART_DOWNLOAD_DIS`` : Disable the UART ROM Download mode.
|
7. Build, Sign and Flash the binaries
|
||||||
|
|
||||||
The eFuse can be burned by running:
|
After the above configurations, the bootloader and application binaries can be built with ``idf.py build`` command.
|
||||||
|
|
||||||
.. code:: bash
|
The Secure Boot V2 workflow only verifies the ``bootloader`` and ``application`` binaries, hence only those binaries need to be signed. The other binaries (e.g., ``partition-table.bin``) can be flashed as they are generated in the build stage.
|
||||||
|
|
||||||
|
The ``bootloader.bin`` and ``app.bin`` binaries can be signed by running:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
espsecure.py 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
|
||||||
|
|
||||||
|
.. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
|
||||||
|
|
||||||
|
If multiple keys Secure Boot keys are to be used then the same signed binary can be appended with a signature block signed with the new key as follows:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
espsecure.py 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
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
The signatures attached to a binary can be checked by running:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
espsecure.py 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``.
|
||||||
|
|
||||||
|
8. Secure the ROM Download mode:
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
Please perform the following step at the very end. After this eFuse is burned, the espefuse tool can no longer be used to burn additional eFuses.
|
||||||
|
|
||||||
|
.. only: esp32
|
||||||
|
|
||||||
|
Disable UART ROM DL mode:
|
||||||
|
|
||||||
|
.. list::
|
||||||
|
|
||||||
|
- ``UART_DOWNLOAD_DIS`` : Disable the UART ROM Download mode
|
||||||
|
|
||||||
|
The eFuse can be burned by running:
|
||||||
|
|
||||||
|
.. 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
|
Enable Security Download mode:
|
||||||
|
|
||||||
C) Enable Security Download mode:
|
.. list::
|
||||||
|
|
||||||
.. warning::
|
- ``ENABLE_SECURITY_DOWNLOAD``: Enable Secure ROM download mode
|
||||||
|
|
||||||
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.
|
The eFuse can be burned by running:
|
||||||
|
|
||||||
.. list::
|
.. code:: bash
|
||||||
|
|
||||||
- ``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
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
* It is recommended to store the secure boot key in a highly secure place. A physical or a cloud HSM may be used for secure storage of the secure boot private key. Please take a look at :ref:`remote-sign-v2-image` for more details.
|
* It is recommended to store the Secure Boot key in a highly secure place. A physical or a cloud HSM may be used for secure storage of the Secure Boot private key. Please take a look at :ref:`remote-sign-v2-image` for more details.
|
||||||
|
|
||||||
.. 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.
|
||||||
|
|
||||||
|
.. _enable-nvs-encryption-externally:
|
||||||
|
|
||||||
|
Enable NVS Encryption Externally
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The details about NVS Encryption and related schemes can be found at :doc:`NVS Encryption </api-reference/storage/nvs_encryption>`.
|
||||||
|
|
||||||
|
.. only:: SOC_HMAC_SUPPORTED
|
||||||
|
|
||||||
|
.. _enable-nvs-encryption-based-on-hmac:
|
||||||
|
|
||||||
|
Enable NVS Encryption based on HMAC
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
1. Generate the HMAC key and NVS Encryption key
|
||||||
|
|
||||||
|
In the HMAC based NVS scheme, there are two keys:
|
||||||
|
|
||||||
|
* HMAC key - this is a 256 bit HMAC key that shall be stored in the eFuse
|
||||||
|
* NVS Encryption key - This is the NVS Encryption key that is used to encrypt the NVS partition. This key is derived at run-time using the HMAC key.
|
||||||
|
|
||||||
|
The above keys can be generated with the :component_file:`nvs_flash/nvs_partition_generator/nvs_partition_gen.py` script with help of the following command:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
python3 nvs_partition_gen.py generate-key --key_protect_hmac --kp_hmac_keygen --kp_hmac_keyfile hmac_key.bin --keyfile nvs_encr_key.bin
|
||||||
|
|
||||||
|
This shall generate the respective keys in the ``keys`` folder.
|
||||||
|
|
||||||
|
2. Burn the HMAC key in the eFuse
|
||||||
|
|
||||||
|
The NVS key can be burned in the eFuse of {IDF_TARGET_NAME} with help of following command:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
espefuse.py --port PORT burn_key BLOCK hmac_key.bin HMAC_UP
|
||||||
|
|
||||||
|
where ``BLOCK`` is a free keyblock between ``BLOCK_KEY0`` and ``BLOCK_KEY5``.
|
||||||
|
|
||||||
|
3. Generate the encrypted NVS partition
|
||||||
|
|
||||||
|
We shall generate the actual encrypted NVS partition on host. More details about generating the encryption NVS partition can be found at :ref:`generate-encrypted-nvs-partition`.
|
||||||
|
For this purpose, the contents of the NVS file shall be available in a CSV file. Please check out :ref:`nvs-csv-file-format` for more details.
|
||||||
|
|
||||||
|
The encrypted NVS partition can be generated with following command:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
python3 nvs_partition_gen.py encrypt sample_singlepage_blob.csv nvs_encr_partition.bin 0x3000 --inputkey keys/nvs_encr_key.bin
|
||||||
|
|
||||||
|
Some command arguments are explained below:
|
||||||
|
|
||||||
|
* CSV file name - In this case `sample_singlepage_blob.csv` is the CSV file which contains the NVS data, Replace this with the file you wish to choose.
|
||||||
|
|
||||||
|
* NVS partition offset - This is the offset at which that NVS partition shall be stored in the flash of {IDF_TARGET_NAME}. The offset of your nvs-partition can be found be executing `idf.py partition-table` in the projtect directory. Please update the sample value of `0x3000` in the above-provided command to the correct offset.
|
||||||
|
|
||||||
|
4. Configure the project
|
||||||
|
|
||||||
|
* Enable `NVS Encryption` by enabling :ref:`CONFIG_NVS_ENCRYPTION`.
|
||||||
|
|
||||||
|
* Enable the HMAC based NVS Encryption by setting :ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` to ``CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC``
|
||||||
|
|
||||||
|
* Set the HMAC efuse key id at :ref:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID` to the one in which the eFuse key was burned in Step 2.
|
||||||
|
|
||||||
|
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.
|
||||||
|
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_>`_.
|
||||||
|
|
||||||
|
.. _enable-flash-enc-based-nvs-encryption:
|
||||||
|
|
||||||
|
Enable NVS Encryption based on Flash Encryption
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
In this case we generate NVS Encryption keys on a host. This key is then flashed on the chip and protected with help of the :doc:`Flash Encryption </security/flash-encryption>` feature.
|
||||||
|
|
||||||
|
1. Generate the NVS Encryption key
|
||||||
|
|
||||||
|
For generation of respective keys, we shall use :doc:`NVS partition generator utility </api-reference/storage/nvs_partition_gen>`. We shall generate the encryption key on host and this key key shall be stored on the flash of {IDF_TARGET_NAME} in encrypted state.
|
||||||
|
|
||||||
|
The key can be generated with the :component_file:`nvs_flash/nvs_partition_generator/nvs_partition_gen.py` script with help of the following command:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
python3 nvs_partition_gen.py generate-key --keyfile nvs_encr_key.bin
|
||||||
|
|
||||||
|
This shall generate the respective key in the ``keys`` folder.
|
||||||
|
|
||||||
|
2. Generate the encrypted NVS partition
|
||||||
|
|
||||||
|
We shall generate the actual encrypted NVS partition on host. More details about generating the encryption NVS partition can be found at :ref:`generate-encrypted-nvs-partition`.
|
||||||
|
For this, the contents of the NVS file shall be available in a CSV file. Please refer :ref:`nvs-csv-file-format` for more details.
|
||||||
|
|
||||||
|
The encrypted NVS partition can be generated with following command:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
python3 nvs_partition_gen.py encrypt sample_singlepage_blob.csv nvs_encr_partition.bin 0x3000 --inputkey keys/nvs_encr_key.bin
|
||||||
|
|
||||||
|
Some command arguments are explained below:
|
||||||
|
|
||||||
|
* CSV file name - In this case `sample_singlepage_blob.csv` is the CSV file which contains the NVS data, Replace this with the file you wish to choose.
|
||||||
|
|
||||||
|
* NVS partition offset - This is the offset at which that NVS partition shall be stored in the flash of {IDF_TARGET_NAME}. The offset of your nvs-partition can be found be executing `idf.py partition-table` in the projtect directory. Please update the sample value of `0x3000` in the above-provided command to the correct offset.
|
||||||
|
|
||||||
|
3. Configure the project
|
||||||
|
|
||||||
|
* Enable `NVS Encryption` by enabling :ref:`CONFIG_NVS_ENCRYPTION`.
|
||||||
|
* Set NVS to use Flash Encryption based scheme by setting :ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` to ``CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC``.
|
||||||
|
|
||||||
|
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 printed 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_>`_.
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user