..
  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.

Security Features Enablement Workflows
======================================

:link_to_translation:`zh_CN:[中文]`

{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=""}

Introduction
------------

When enabling security features on ESP32 SoCs, it is recommended that power supply be uninterrupted. Power failures during this process could cause issues that are hard to debug and, in some cases, may cause permanent boot-up failures.

This guide describes a set of workflows to enable security features on the device with the assistance of an external host machine. These workflows are broken down into various stages, with each stage generating signing/encryption keys on the host machine. This allows for greater chances of recovery in case of power or other failures. Furthermore, these workflows expedites the overall provisioning process via the use of the host machine (e.g., encrypting firmware on the host is quicker than on the device).

.. only:: TARGET_SUPPORT_QEMU

   .. important::

      It is possible to try out the security features for {IDF_TARGET_NAME} target SoC under :doc:`../api-guides/tools/qemu` virtually. Once the security workflow is established, you can then proceed to the real hardware.

Goals
-----

#. Simplify the traditional workflow for enabling security features with stepwise instructions.
#. Design a more flexible workflow when compared to the traditional firmware-based workflow.
#. Improve reliability by dividing the workflow into small operations.
#. Eliminate dependency on :ref:`second-stage-bootloader`.

Prerequisites
-------------

* ``esptool``: Please make sure the ``esptool`` has been installed. It can be installed by running:

.. code:: bash

    pip install esptool

Scope
-----

* :ref:`enable-flash-encryption-and-secure-boot-v2-externally`
* :ref:`enable-flash-encryption-externally`
* :ref:`enable-secure-boot-v2-externally`
* :ref:`enable-nvs-encryption-externally`

Security Features Enablement
----------------------------

.. _enable-flash-encryption-and-secure-boot-v2-externally:

Enable Flash Encryption and Secure Boot v2 Externally
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. important::

    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 together, they must be enabled in the following order:

#. 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`.

The reason for this particular ordering is that when enabling 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In this case, all the eFuses related to Flash Encryption are written with help of the espefuse tool. More details about Flash Encryption process can be found in :doc:`/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`

    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

        esptool --port PORT erase-flash

2. Generate a Flash Encryption key

    A random Flash Encryption key can be generated by running:

    .. only:: not SOC_FLASH_ENCRYPTION_XTS_AES

        .. code-block:: bash

            espsecure generate-flash-encryption-key my_flash_encryption_key.bin

    .. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256

        If :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-128 (256-bit key):

        .. code-block:: bash

            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 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 generate-flash-encryption-key my_flash_encryption_key.bin

    .. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK

        If :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-128 (256-bit key):

        .. code-block:: bash

            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 generate-flash-encryption-key --keylen 128 my_flash_encryption_key.bin

3. Program the generated Flash Encryption key into the device

    .. only:: SOC_KEY_MANAGER_SUPPORTED

        a. If you intend to use the Key Manager to store the Flash Encryption key, generate the Key Recovery Information for the Flash Encryption key and store it in the flash memory at the address 0x0 using the command:

        .. code-block:: bash

            esptool --port PORT write-flash 0x0 key_recovery_info.bin

        After storing the Key Recovery Information in flash memory, you also need to program the ``KM_XTS_KEY_LENGTH_256`` and the ``FORCE_USE_KEY_MANAGER_KEY`` eFuses.

        .. warning::

            This action **cannot be reverted**.

        Bit 1 of the ``FORCE_USE_KEY_MANAGER_KEY`` eFuse is used to force using a Key Manager-based XTS-AES key. Once this eFuse is burned, eFuse-based Flash Encryption keys can no longer be used; the device will exclusively use the Key Manager for Flash Encryption key management.

        .. code-block:: bash

            espefuse --port PORT burn-efuse FORCE_USE_KEY_MANAGER_KEY 2

        The ``KM_XTS_KEY_LENGTH_256`` eFuse controls the length of the Key-Manager based XTS-AES key. Set this eFuse to 1 to use a 128-bit key, and to 0 to use a 256-bit key.

        To use a 128-bit key, set the ``KM_XTS_KEY_LENGTH_256`` eFuse to 1.

        .. code-block:: bash

            espefuse --port PORT burn-efuse KM_XTS_KEY_LENGTH_256 1

        Otherwise, to use a 256-bit key, set the ``KM_XTS_KEY_LENGTH_256`` eFuse to 0.

        .. code-block:: bash

            espefuse --port PORT burn-efuse KM_XTS_KEY_LENGTH_256 0

        b. To store the Flash Encryption key in the eFuses, run the following commands:

    .. only:: not SOC_KEY_MANAGER_SUPPORTED

        To store the Flash Encryption key in the eFuses, run the following commands:

    .. warning::

        This action **cannot be reverted**.

    .. only:: not SOC_FLASH_ENCRYPTION_XTS_AES

        .. code-block:: bash

            espefuse --port PORT burn-key flash_encryption my_flash_encryption_key.bin

    .. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256

        .. code-block:: bash

            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.

        For AES-128 (256-bit key) - ``XTS_AES_128_KEY``:

        .. code-block:: bash

            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`` 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 --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 --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 --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``.

    .. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK

        For AES-128 (256-bit key) - ``XTS_AES_128_KEY`` (the ``XTS_KEY_LENGTH_256`` eFuse will be burned to 1):

        .. code-block:: bash

            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 --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 --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

        .. warning::

            For the {IDF_TARGET_NAME} BLOCK9 (BLOCK_KEY5) can not be used by XTS_AES keys.


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).

    .. code-block:: bash

        espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse {IDF_TARGET_CRYPT_CNT} {IDF_TARGET_CRYPT_CNT_MAX_VAL}

    .. only:: esp32

        In the case of {IDF_TARGET_NAME}, you also need to burn the ``FLASH_CRYPT_CONFIG``. It can be done by running:

        .. code-block:: bash

            espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse FLASH_CRYPT_CONFIG 0xF

5. Burn Flash Encryption-related security eFuses as listed below

    A) Burn security eFuses

    .. important::

        For production use cases, it is highly recommended to burn all the eFuses listed below.

    .. list::

        :esp32: - ``DISABLE_DL_ENCRYPT``: Disable the UART bootloader encryption access
        :esp32: - ``DISABLE_DL_DECRYPT``: Disable the UART bootloader decryption access
        :esp32: - ``DISABLE_DL_CACHE``: Disable the UART bootloader flash cache access
        :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_DOWNLOAD_ICACHE: - ``DIS_DOWNLOAD_ICACHE``: 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_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_USB_JTAG: - ``DIS_USB_JTAG``: Disable USB switch to JTAG
        :SOC_EFUSE_DIS_PAD_JTAG: - ``DIS_PAD_JTAG``: Disable JTAG permanently
        :not esp32: - ``DIS_DOWNLOAD_MANUAL_ENCRYPT``: Disable UART bootloader encryption access
        :SOC_EFUSE_DIS_DOWNLOAD_MSPI: - ``DIS_DOWNLOAD_MSPI``: Disable the MSPI access in download mode
        :SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND: - ``XTS_DPA_PSEUDO_LEVEL``: Enable the pseudo rounds function of the XTS-AES peripheral. The value to be burned in the eFuse can be 1, 2 or 3, denoting the security level. By default ESP-IDF's bootloader configures the value of this eFuse to 1 while enabling flash encryption release mode during boot-up.

    The respective eFuses can be burned by running:

    .. code:: bash

        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` can be found `here <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`_.

    .. only:: esp32

        B) Write protect security eFuses

        After burning the respective eFuses we need to write-protect the security configurations. It can be done by burning following eFuse:

        .. code:: bash

            espefuse --port PORT write-protect-efuse DIS_CACHE

        .. 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.

    .. only:: SOC_EFUSE_DIS_ICACHE

        B) Write protect security eFuses

        After burning the respective eFuses we need to write_protect the security configurations. It can be done by burning following eFuse

        .. code:: bash

            espefuse --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:

    .. code-block:: bash

        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 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 0x10000 --output my-app-enc.bin build/my-app.bin

    .. note::

        If secure boot is enabled, perform secure boot signing of the firmware before carrying out the above encryption operation.

    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``. 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.

    .. 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`` 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 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

    .. 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 --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 --port PORT burn-efuse ENABLE_SECURITY_DOWNLOAD

.. important::

    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 can't 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~

* 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.
* See :ref:`flash-encryption-limitations` for more details.

.. _enable-secure-boot-v2-externally:

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:`/security/secure-boot-v2`.

1. Generate Secure Boot v2 Signing Private Key

    .. only:: esp32 or SOC_SECURE_BOOT_V2_RSA

        The Secure Boot v2 signing key for the RSA3072 scheme can be generated by running:

        .. code:: bash

            espsecure generate-signing-key --version 2 --scheme rsa3072 secure_boot_signing_key.pem

    .. only:: SOC_SECURE_BOOT_V2_ECC

        The Secure Boot v2 signing key for ECDSA scheme can be generated by running:

        .. code:: bash

            espsecure generate-signing-key --version 2 --scheme ecdsa256 secure_boot_signing_key.pem

        .. only:: not SOC_ECDSA_SUPPORT_CURVE_P384

           The scheme in the above command can be changed to ``ecdsa192`` to generate ecdsa192 private key.

        .. only:: SOC_ECDSA_SUPPORT_CURVE_P384

           The scheme in the above command can be changed to ``ecdsa384`` or ``ecdsa192`` to generate ecdsa384 or ecdsa192 private key.

    .. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS

        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

    The public key digest for the private key generated in the previous step can be generated by running:

    .. code:: bash

        espsecure digest-sbv2-public-key --keyfile secure_boot_signing_key.pem --output digest.bin

    .. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS

        In case of multiple digests, each digest should be kept in a separate file.

3. Burn the key digest in eFuse

    The public key digest can be burned in the eFuse by running:

    .. only:: esp32

        .. code:: bash

            espefuse --port PORT --chip esp32 burn-key secure_boot_v2 digest.bin

    .. only:: esp32c2

        .. code:: bash

            espefuse --port PORT --chip esp32c2 burn-key KEY_BLOCK0 digest.bin SECURE_BOOT_DIGEST

    .. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS

        .. code:: bash

            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``.

        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

    Secure Boot v2 eFuse can be enabled by running:

    .. only:: esp32

        .. code:: bash

            espefuse --port PORT --chip esp32 burn-efuse ABS_DONE_1

  .. only:: not esp32

       .. code:: bash

            espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse SECURE_BOOT_EN

    .. only:: SOC_ECDSA_SUPPORT_CURVE_P384

        In case Secure Boot v2 is enabled with the ECDSA-P384 signature scheme, SHA-384 must be used to calculate the digest of the image. Thus, the following eFuse needs to be burned:

        .. code:: bash

            espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse SECURE_BOOT_SHA384_EN


5. Burn relevant eFuses

    A) Burn security eFuses

    .. important::

        For production use cases, it is highly recommended to burn all the eFuses listed below.

    .. list::

        :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_HARD_DIS_JTAG: - ``HARD_DIS_JTAG``: Hard disable JTAG peripheral.
        :SOC_EFUSE_SOFT_DIS_JTAG: - ``SOFT_DIS_JTAG``: Disable software access to JTAG peripheral.
        :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_USB_JTAG: - ``DIS_USB_JTAG``: Disable USB switch to JTAG.
        :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_ECDSA_P192_CURVE_DEFAULT_DISABLED: - ``WR_DIS_ECDSA_CURVE_MODE``: Disable writing to the ECDSA curve mode eFuse bit. As this write protection bit is shared with ``ECC_FORCE_CONST_TIME``, it is recommended to write-protect this bit only after configuring the ``ECC_FORCE_CONST_TIME`` eFuse.
        :SOC_ECDSA_SUPPORT_CURVE_P384: - ``WR_DIS_SECURE_BOOT_SHA384_EN``: Disable writing to the SHA-384 Secure Boot eFuse bit. As this write protection bit is shared with ``XTS_DPA_PSEUDO_LEVEL`` and ``ECC_FORCE_CONST_TIME``, it is recommended to write protect this bit only after configuring all the other shared eFuses.

    The respective eFuses can be burned by running:

    .. code:: bash

        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` can be found `here <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`_

    B) Secure Boot v2-related eFuses

    i) Disable the read-protection option:

    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:

    .. code:: bash

        espefuse -p $ESPPORT write-protect-efuse RD_DIS

    .. important::

        After burning above-mentioned eFuse, the read protection can't be enabled for any key. For example, if Flash Encryption which requires read protection for its key is not enabled at this point, then it can't be enabled afterwards. Please ensure that no eFuse keys are going to need read protection after completing this step.

    .. only:: SOC_EFUSE_REVOKE_BOOT_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

        .. code:: bash

            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.

6. Configure the project

    By default, the first stage (ROM) bootloader would only verify the :ref:`second-stage-bootloader`. The second stage 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.

7. Build, Sign and Flash the binaries

    After the above configurations, the bootloader and application binaries can be built with ``idf.py build`` command.

    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 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 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 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 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 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``. 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

    .. 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 --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 --port PORT burn-efuse ENABLE_SECURITY_DOWNLOAD

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.

.. 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.

.. _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 --port PORT burn-key BLOCK hmac_key.bin HMAC_UP

        Here, ``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 the 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. Please replace this with the file you wish to choose.

        * NVS partition size - This is the size of the NVS partition in bytes. Please update the sample value of ``0x3000`` in the above-provided command to the correct size of your NVS partition.

    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``. 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_>`_.

.. _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 the help of :doc:`Flash Encryption </security/flash-encryption>` features.

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 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 the 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 encrypted 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 to :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. Please replace it with the file you wish to choose.

    * NVS partition size - This is the size of the NVS partition in bytes. Please update the sample value of ``0x3000`` in the above-provided command to the correct size of your NVS partition.

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``. 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 NVS key partition first before flashing. You may refer the flashing related steps of `Flash Encryption workflow <enable-flash-encryption-externally_>`_.
