forked from espressif/esp-idf
build system: Use CMake-based build system as default when describing commands
This commit is contained in:
Angus Gratton
committed by
Angus Gratton
Angus Gratton
parent
f6ad7f564d
commit
47bbb107a8
@@ -72,7 +72,7 @@ The flash encryption operation is controlled by various eFuses available on ESP3
|
||||
encrypt flash at boot time
|
||||
Odd number of bits set (1, 3, 5, 7): do
|
||||
not encrypt flash at boot time
|
||||
|
||||
|
||||
|
||||
Read and write access to above bits is controlled by appropriate bits in ``efuse_wr_disable`` and ``efuse_rd_disable`` registers. More information about ESP32 eFuse can be found at :doc:`eFuse manager <../api-reference/system/efuse>`.
|
||||
|
||||
@@ -116,9 +116,9 @@ As mentioned above :ref:`flash_enc_development_mode` allows user to download as
|
||||
|
||||
- Navigate to flash encryption sample application in ``$IDF_PATH/examples/security/flash_encryption`` folder. This sample application will print the status of flash encryption: enabled or disabled. It will print the ``FLASH_CRYPT_CNT`` eFuse value.
|
||||
|
||||
- Enable flash encryption support in second stage bootloader. In make menuconfig, navigate to “Security Features”.
|
||||
- Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features".
|
||||
|
||||
- Select “Enable flash encryption on boot”.
|
||||
- Select :ref:`Enable flash encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`.
|
||||
|
||||
- By default the mode is set for **Development**.
|
||||
|
||||
@@ -132,7 +132,7 @@ Build and flash the complete image including: bootloader, partition table and ap
|
||||
|
||||
::
|
||||
|
||||
make -j4 flash monitor
|
||||
idf.py flash monitor
|
||||
|
||||
Once the flashing is complete device will reset and on next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application would get decrypted at runtime and executed. Below is a sample output when ESP32 boots after flash encryption is enabled for the first time.
|
||||
|
||||
@@ -281,7 +281,7 @@ At this stage if user wants to update modified plaintext application image to fl
|
||||
|
||||
::
|
||||
|
||||
make -j4 encrypted-app-flash monitor
|
||||
idf.py encrypted-app-flash monitor
|
||||
|
||||
.. _encrypt_partitions:
|
||||
|
||||
@@ -292,7 +292,7 @@ If all partitions needs to be updated in encrypted format, it can be done as
|
||||
|
||||
::
|
||||
|
||||
make -j4 encrypted-flash monitor
|
||||
idf.py encrypted-flash monitor
|
||||
|
||||
.. _pregenerated-flash-encryption-key:
|
||||
|
||||
@@ -310,9 +310,9 @@ It is possible to pregenerate the flash encryption key on the host computer and
|
||||
|
||||
espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin
|
||||
|
||||
- Enable flash encryption support in second stage bootloader. In make menuconfig, navigate to “Security Features”.
|
||||
- Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features".
|
||||
|
||||
- Select “Enable flash encryption on boot”.
|
||||
- Select :ref:`Enable flash encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`.
|
||||
|
||||
- By default the mode is set for **Development**.
|
||||
|
||||
@@ -327,7 +327,7 @@ Build and flash the complete image including: bootloader, partition table and ap
|
||||
|
||||
::
|
||||
|
||||
make -j4 flash monitor
|
||||
idf.py flash monitor
|
||||
|
||||
On next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application would get decrypted at runtime and executed.
|
||||
|
||||
@@ -335,7 +335,7 @@ At this stage if user wants to update new plaintext application image to flash t
|
||||
|
||||
::
|
||||
|
||||
make -j4 encrypted-app-flash monitor
|
||||
idf.py encrypted-app-flash monitor
|
||||
|
||||
For reprogramming all partitions in encrypted format follow :ref:`encrypt_partitions`.
|
||||
|
||||
@@ -348,10 +348,10 @@ Release Mode
|
||||
In Release mode UART bootloader can not perform flash encryption operations and new plaintext images can be downloaded ONLY using OTA scheme which will encrypt the plaintext image before writing to flash.
|
||||
|
||||
- Ensure you have a ESP32 device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`.
|
||||
|
||||
- Enable flash encryption support in second stage bootloader. In make menuconfig, navigate to “Security Features”.
|
||||
|
||||
- Select “Enable flash encryption on boot”.
|
||||
- Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features".
|
||||
|
||||
- Select :ref:`Enable flash encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`.
|
||||
|
||||
- Select **Release Mode**, by default the mode is set for **Development**. Please note **once the Release mode is selected the ``download_dis_encrypt`` and ``download_dis_decrypt`` eFuse bits will be programmed to disable UART bootloader access to flash contents**.
|
||||
|
||||
@@ -365,7 +365,7 @@ Build and flash the complete image including: bootloader, partition table and ap
|
||||
|
||||
::
|
||||
|
||||
make -j4 flash monitor
|
||||
idf.py flash monitor
|
||||
|
||||
On next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application should execute correctly.
|
||||
|
||||
@@ -549,12 +549,11 @@ If you've accidentally enabled flash encryption for some reason, the next flash
|
||||
|
||||
You can disable flash encryption again by writing ``FLASH_CRYPT_CNT`` eFuse (only in Development mode):
|
||||
|
||||
- First, run ``make menuconfig`` and uncheck "Enable flash encryption boot" under "Security Features".
|
||||
- First, open :ref:`project-configuration-menu` and disable :ref:`Enable flash encryption boot <CONFIG_SECURE_FLASH_ENC_ENABLED>` under "Security Features".
|
||||
- Exit menuconfig and save the new configuration.
|
||||
- Run ``make menuconfig`` again and double-check you really disabled this option! *If this option is left enabled, the bootloader will immediately re-enable encryption when it boots*.
|
||||
- Run ``make flash`` to build and flash a new bootloader and app, without flash encryption enabled.
|
||||
- Run ``idf.py menuconfig`` again and double-check you really disabled this option! *If this option is left enabled, the bootloader will immediately re-enable encryption when it boots*.
|
||||
- Run ``idf.py flash`` to build and flash a new bootloader and app, without flash encryption enabled.
|
||||
- Run ``espefuse.py`` (in ``components/esptool_py/esptool``) to disable the FLASH_CRYPT_CNT::
|
||||
|
||||
espefuse.py burn_efuse FLASH_CRYPT_CNT
|
||||
|
||||
Reset the ESP32 and flash encryption should be disabled, the bootloader will boot as normal.
|
||||
@@ -584,7 +583,7 @@ Flash Encryption and Secure Boot
|
||||
It is recommended to use flash encryption and secure boot together. However, if Secure Boot is enabled then additional restrictions apply to reflashing the device:
|
||||
|
||||
- :ref:`updating-encrypted-flash-ota` are not restricted (provided the new app is signed correctly with the Secure Boot signing key).
|
||||
- :ref:`Plaintext serial flash updates <updating-encrypted-flash-serial>` are only possible if the :ref:`Reflashable <CONFIG_SECURE_BOOTLOADER_MODE>` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the ESP32 (refer to :ref:`Secure Boot <secure-boot-reflashable>` docs.). In this configuration, ``make bootloader`` will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0. When following the plaintext serial reflashing steps it is necessary to re-flash this file before flashing other plaintext data.
|
||||
- :ref:`Plaintext serial flash updates <updating-encrypted-flash-serial>` are only possible if the :ref:`Reflashable <CONFIG_SECURE_BOOTLOADER_MODE>` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the ESP32 (refer to :ref:`Secure Boot <secure-boot-reflashable>` docs.). In this configuration, ``idf.py bootloader`` will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0. When following the plaintext serial reflashing steps it is necessary to re-flash this file before flashing other plaintext data.
|
||||
- :ref:`Reflashing via Pregenerated Flash Encryption Key <pregenerated-flash-encryption-key>` is still possible, provided the bootloader is not reflashed. Reflashing the bootloader requires the same :ref:`Reflashable <CONFIG_SECURE_BOOTLOADER_MODE>` option to be enabled in the Secure Boot config.
|
||||
|
||||
.. _flash-encryption-without-secure-boot:
|
||||
|
||||
@@ -25,7 +25,7 @@ Secure Boot Process Overview
|
||||
|
||||
This is a high level overview of the secure boot process. Step by step instructions are supplied under :ref:`secure-boot-howto`. Further in-depth details are supplied under :ref:`secure-boot-technical-details`:
|
||||
|
||||
1. The options to enable secure boot are provided in the ``make menuconfig`` hierarchy, under "Secure Boot Configuration".
|
||||
1. The options to enable secure boot are provided in the :ref:`project-configuration-menu`, under "Secure Boot Configuration".
|
||||
|
||||
2. Secure Boot defaults to signing images and partition table data during the build process. The "Secure boot private signing key" config item is a file path to a ECDSA public/private key pair in a PEM format file.
|
||||
|
||||
@@ -76,7 +76,7 @@ Options to work around this are:
|
||||
How To Enable Secure Boot
|
||||
-------------------------
|
||||
|
||||
1. Run ``make menuconfig``, navigate to "Secure Boot Configuration" and select the option "One-time Flash". (To understand the alternative "Reflashable" choice, see :ref:`secure-boot-reflashable`.)
|
||||
1. Open the :ref:`project-configuration-menu`, navigate to "Secure Boot Configuration" and select the option "One-time Flash". (To understand the alternative "Reflashable" choice, see :ref:`secure-boot-reflashable`.)
|
||||
|
||||
2. Select a name for the secure boot signing key. This option will appear after secure boot is enabled. The file can be anywhere on your system. A relative path will be evaluated from the project directory. The file does not need to exist yet.
|
||||
|
||||
@@ -90,15 +90,15 @@ How To Enable Secure Boot
|
||||
.. important::
|
||||
For production environments, we recommend generating the keypair using openssl or another industry standard encryption program. See :ref:`secure-boot-generate-key` for more details.
|
||||
|
||||
5. Run ``make bootloader`` to build a secure boot enabled bootloader. The output of ``make`` will include a prompt for a flashing command, using ``esptool.py write_flash``.
|
||||
5. Run ``idf.py bootloader`` to build a secure boot enabled bootloader. The build output will include a prompt for a flashing command, using ``esptool.py write_flash``.
|
||||
|
||||
.. _secure-boot-resume-normal-flashing:
|
||||
|
||||
6. When you're ready to flash the bootloader, run the specified command (you have to enter it yourself, this step is not performed by make) and then wait for flashing to complete. **Remember this is a one time flash, you can't change the bootloader after this!**.
|
||||
|
||||
7. Run ``make flash`` to build and flash the partition table and the just-built app image. The app image will be signed using the signing key you generated in step 4.
|
||||
7. Run ``idf.py flash`` to build and flash the partition table and the just-built app image. The app image will be signed using the signing key you generated in step 4.
|
||||
|
||||
.. note:: ``make flash`` doesn't flash the bootloader if secure boot is enabled.
|
||||
.. note:: ``idf.py flash`` doesn't flash the bootloader if secure boot is enabled.
|
||||
|
||||
8. Reset the ESP32 and it will boot the software bootloader you flashed. The software bootloader will enable secure boot on the chip, and then it verifies the app image signature and boots the app. You should watch the serial console output from the ESP32 to verify that secure boot is enabled and no errors have occurred due to the build configuration.
|
||||
|
||||
@@ -123,13 +123,13 @@ In the esp-idf build process, this 256-bit key file is derived from the app sign
|
||||
|
||||
To enable a reflashable bootloader:
|
||||
|
||||
1. In the ``make menuconfig`` step, select "Bootloader Config" -> :ref:`CONFIG_SECURE_BOOT_ENABLED` -> :ref:`CONFIG_SECURE_BOOTLOADER_MODE` -> Reflashable.
|
||||
1. In the :ref:`project-configuration-menu`, select "Bootloader Config" -> :ref:`CONFIG_SECURE_BOOT_ENABLED` -> :ref:`CONFIG_SECURE_BOOTLOADER_MODE` -> Reflashable.
|
||||
|
||||
2. If necessary, set the :ref:`CONFIG_SECURE_BOOTLOADER_KEY_ENCODING` based on the coding scheme used by the device. The coding scheme is shown in the ``Features`` line when ``esptool.py`` connects to the chip, or in the ``espefuse.py summary`` output.
|
||||
|
||||
2. Follow the steps shown above to choose a signing key file, and generate the key file.
|
||||
|
||||
3. Run ``make bootloader``. A binary key file will be created, derived from the private key that is used for signing. Two sets of flashing steps will be printed - the first set of steps includes an ``espefuse.py burn_key`` command which is used to write the bootloader key to efuse. (Flashing this key is a one-time-only process.) The second set of steps can be used to reflash the bootloader with a pre-calculated digest (generated during the build process).
|
||||
3. Run ``idf.py bootloader``. A binary key file will be created, derived from the private key that is used for signing. Two sets of flashing steps will be printed - the first set of steps includes an ``espefuse.py burn_key`` command which is used to write the bootloader key to efuse. (Flashing this key is a one-time-only process.) The second set of steps can be used to reflash the bootloader with a pre-calculated digest (generated during the build process).
|
||||
|
||||
4. Resume from :ref:`Step 6 of the one-time flashing process <secure-boot-resume-normal-flashing>`, to flash the bootloader and enable secure boot. Watch the console log output closely to ensure there were no errors in the secure boot configuration.
|
||||
|
||||
@@ -244,7 +244,7 @@ Deterministic ECDSA as specified by `RFC 6979 <https://tools.ietf.org/html/rfc69
|
||||
Manual Commands
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Secure boot is integrated into the esp-idf build system, so ``make`` will automatically sign an app image if secure boot is enabled. ``make bootloader`` will produce a bootloader digest if menuconfig is configured for it.
|
||||
Secure boot is integrated into the esp-idf build system, so ``make`` will automatically sign an app image if secure boot is enabled. ``idf.py bootloader`` will produce a bootloader digest if menuconfig is configured for it.
|
||||
|
||||
However, it is possible to use the ``espsecure.py`` tool to make standalone signatures and digests.
|
||||
|
||||
@@ -291,7 +291,7 @@ An app can be verified on update and, optionally, be verified on boot.
|
||||
How To Enable Signed App Verification
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. Run ``make menuconfig`` -> Security features -> Enable "Require signed app images"
|
||||
1. Open :ref:`project-configuration-menu` -> Security features -> Enable :ref:`CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT`
|
||||
|
||||
2. "Bootloader verifies app signatures" can be enabled, which verifies app on boot.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user