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

Merge branch 'feature/doc_for_parttool' into 'master'

Browse Source 
feat(doc): Adds note for parttool that if SB or FE are on

See merge request espressif/esp-idf!31318
This commit is contained in:
Konstantin Kondrashov 2024-06-24 16:28:24 +08:00
commit a648a95660
2 changed files with 30 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
docs/en/api-guides/partition-tables.rst
View File

@ -328,6 +328,24 @@ The command-line interface of `parttool.py` has the following structure:
# Print the size of default boot partition
parttool.py --port "/dev/ttyUSB1" get_partition_info --partition-boot-default --info size
.. note::
If the device has already enabled ``Flash Encryption`` or ``Secure Boot``, attempting to use commands that modify the flash content, such as ``erase_partition`` or ``write_partition``, will result in an error. This error is generated by the erase command of ``esptool.py``, which is called first before writing. This error is done as a safety measure to prevent bricking your device.
::
A fatal error occurred: Active security features detected, erasing flash is disabled as a safety measure. Use --force to override, please use with caution, otherwise it may brick your device!
To work around this, you need use the ``--force`` flag with ``esptool.py``. Specifically, the ``parttool.py`` provides the ``--esptool-erase-args`` argument that help to pass this flag to ``esptool.py``.
.. code-block:: bash
# Erase partition with name 'storage'
# If Flash Encryption or Secure Boot are enabled then add "--esptool-erase-args=force"
parttool.py --port "/dev/ttyUSB1" --esptool-erase-args=force erase_partition --partition-name=storage
# Write to partition 'factory' the contents of a file named 'factory.bin'
# If Flash Encryption or Secure Boot are enabled then add "--esptool-erase-args=force"
parttool.py --port "/dev/ttyUSB1" --esptool-erase-args=force write_partition --partition-name=factory --input "factory.bin"
More information can be obtained by specifying `--help` as argument:
.. code-block:: bash

12
docs/en/api-reference/storage/nvs_encryption.rst
View File

@ -66,6 +66,10 @@ The XTS encryption keys in the :ref:`nvs_encr_key_partition` can be generated in
parttool.py --port PORT --partition-table-file=PARTITION_TABLE_FILE --partition-table-offset PARTITION_TABLE_OFFSET erase_partition --partition-type=data --partition-subtype=nvs_keys
# If Flash Encryption or Secure Boot are enabled then add "--esptool-erase-args=force" to suppress the error:
# "Active security features detected, erasing flash is disabled as a safety measure. Use --force to override ..."
parttool.py --port PORT --esptool-erase-args=force --partition-table-file=PARTITION_TABLE_FILE --partition-table-offset PARTITION_TABLE_OFFSET erase_partition --partition-type=data --partition-subtype=nvs_keys
**Use a pre-generated NVS key partition**
This option will be required by the user when keys in the :ref:`nvs_encr_key_partition` are not generated by the application. The :ref:`nvs_encr_key_partition` containing the XTS encryption keys can be generated with the help of :doc:`NVS Partition Generator Utility </api-reference/storage/nvs_partition_gen>`. Then the user can store the pre-generated key partition on the flash with help of the following two commands:
@ -80,12 +84,20 @@ The XTS encryption keys in the :ref:`nvs_encr_key_partition` can be generated in
parttool.py --port PORT --partition-table-offset PARTITION_TABLE_OFFSET write_partition --partition-name="name of nvs_key partition" --input NVS_KEY_PARTITION_FILE
# If Flash Encryption or Secure Boot are enabled then add "--esptool-erase-args=force" to suppress the error:
# "Active security features detected, erasing flash is disabled as a safety measure. Use --force to override ..."
parttool.py --port PORT --esptool-erase-args=force --partition-table-offset PARTITION_TABLE_OFFSET write_partition --partition-name="name of nvs_key partition" --input NVS_KEY_PARTITION_FILE
.. note::
If the device is encrypted in flash encryption development mode and you want to renew the NVS key partition, you need to tell :component_file:`parttool.py<partition_table/parttool.py>` to encrypt the NVS key partition and you also need to give it a pointer to the unencrypted partition table in your build directory (build/partition_table) since the partition table on the device is encrypted, too. You can use the following command:
::
parttool.py --esptool-write-args encrypt --port PORT --partition-table-file=PARTITION_TABLE_FILE --partition-table-offset PARTITION_TABLE_OFFSET write_partition --partition-name="name of nvs_key partition" --input NVS_KEY_PARTITION_FILE
# If Flash Encryption or Secure Boot are enabled then add "--esptool-erase-args=force" to suppress the error:
# "Active security features detected, erasing flash is disabled as a safety measure. Use --force to override ..."
parttool.py --esptool-erase-args=force --esptool-write-args encrypt --port PORT --partition-table-file=PARTITION_TABLE_FILE --partition-table-offset PARTITION_TABLE_OFFSET write_partition --partition-name="name of nvs_key partition" --input NVS_KEY_PARTITION_FILE
Since the key partition is marked as ``encrypted`` and :doc:`Flash Encryption <../../security/flash-encryption>` is enabled, the bootloader will encrypt this partition using flash encryption key on the first boot.
It is possible for an application to use different keys for different NVS partitions and thereby have multiple key-partitions. However, it is a responsibility of the application to provide the correct key-partition and keys for encryption or decryption.