espressif/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-04-27 19:13:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update nvs_flash docs for the HMAC-based NVS encr-keys protection scheme

Browse Source 
- Also updated the `nvs_partition_generator` and `mass_mfg` tools
  documentation
This commit is contained in:
Laukik Hase
2023-04-18 18:09:38 +05:30
parent 9ac87fcc8b
commit a06118012e
10 changed files with 506 additions and 275 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tools/mass_mfg/docs/README.rst
+103 -55
View File
@@ -11,14 +11,15 @@ This utility is designed to create instances of factory NVS partition images on
Please note that this utility only creates manufacturing binary images which then need to be flashed onto your devices using:
- `esptool.py`_
- `Flash Download tool <https://www.espressif.com/en/support/download/other-tools?keys=flash+download+tools>`_ (available on Windows only).Just download it, unzip, and follow the instructions inside the *doc* folder.
- `Flash Download tool <https://www.espressif.com/en/support/download/other-tools?keys=flash+download+tools>`_ (available on Windows only)
- Download and unzip it, and follow the instructions inside the *doc* folder.
- Direct flash programming using custom production tools.
Prerequisites
-------------
**This utility is dependent on esp-idf's NVS partition utility.**
**This utility is dependent on ESP-IDF's NVS Partition Generator Utility.**
* Operating System requirements:
- Linux / MacOS / Windows (standard distributions)
@@ -30,7 +31,7 @@ Prerequisites
Before using this utility, please make sure that:
- The path to Python is added to the PATH environment variable.
- You have installed the packages from `requirement.txt`, the file in the root of the esp-idf directory.
- You have installed the packages from `requirement.txt`, the file in the root of the ESP-IDF directory.
Workflow
@@ -66,7 +67,7 @@ The data in the configuration file has the following format (the `REPEAT` tag is
Each line should have three parameters: ``key,type,encoding``, separated by a comma.
If the ``REPEAT`` tag is present, the value corresponding to this key in the master value CSV file will be the same for all devices.
*Please refer to README of the NVS Partition Generator utility for detailed description of each parameter.*
*Please refer to README of the NVS Partition Generator Utility for detailed description of each parameter.*
Below is a sample example of such a configuration file::
@@ -134,31 +135,32 @@ Running the utility
**Optional Arguments**:
+-----+------------+----------------------------------------------------------------------+
| No. | Parameter | Description |
+=====+============+======================================================================+
| 1 | -h, --help | show this help message and exit |
+-----+------------+----------------------------------------------------------------------+
+-----+------------------------+----------------------------------------------------------------------+
| No. | Parameter | Description |
+=====+========================+======================================================================+
| 1 | ``-h`` / ``--help`` | Show the help message and exit |
+-----+------------------------+----------------------------------------------------------------------+
**Commands**:
Run mfg_gen.py {command} -h for additional help
+-----+--------------+--------------------------------------------------------------------+
| No. | Parameter | Description |
+=====+==============+====================================================================+
| 1 | generate | Generate NVS partition |
+-----+--------------+--------------------------------------------------------------------+
| 2 | generate-key | Generate keys for encryption |
+-----+--------------+--------------------------------------------------------------------+
+-----+------------------+--------------------------------------------------------------------+
| No. | Parameter | Description |
+=====+==================+====================================================================+
| 1 | ``generate`` | Generate NVS partition |
+-----+------------------+--------------------------------------------------------------------+
| 2 | ``generate-key`` | Generate keys for encryption |
+-----+------------------+--------------------------------------------------------------------+
**To generate factory images for each device (Default):**
**Usage**::
python mfg_gen.py generate [-h] [--fileid FILEID] [--version {1,2}] [--keygen]
[--keyfile KEYFILE] [--inputkey INPUTKEY]
[--outdir OUTDIR]
[--inputkey INPUTKEY] [--outdir OUTDIR]
[--key_protect_hmac] [--kp_hmac_keygen]
[--kp_hmac_keyfile KP_HMAC_KEYFILE] [--kp_hmac_inputkey KP_HMAC_INPUTKEY]
conf values prefix size
**Positional Arguments**:
@@ -166,38 +168,47 @@ Running the utility
+--------------+----------------------------------------------------------------------+
| Parameter | Description |
+==============+======================================================================+
| conf | Path to configuration csv file to parse |
| ``conf`` | Path to configuration csv file to parse |
+--------------+----------------------------------------------------------------------+
| values | Path to values csv file to parse |
| ``values`` | Path to values csv file to parse |
+--------------+----------------------------------------------------------------------+
| prefix | Unique name for each output filename prefix |
+-----+--------------+----------------------------------------------------------------+
| size | Size of NVS partition in bytes |
| | (must be multiple of 4096) |
| ``prefix`` | Unique name for each output filename prefix |
+--------------+----------------------------------------------------------------------+
| ``size`` | Size of NVS partition in bytes (must be multiple of 4096) |
+--------------+----------------------------------------------------------------------+
**Optional Arguments**:
+---------------------+--------------------------------------------------------------------+
| Parameter | Description |
+=====================+====================================================================+
| -h, --help | show this help message and exit |
+---------------------+--------------------------------------------------------------------+
| --fileid FILEID | Unique file identifier(any key in values file) |
| | for each filename suffix (Default: numeric value(1,2,3...) |
+---------------------+--------------------------------------------------------------------+
| --version {1,2} | Set multipage blob version. |
| | Version 1 - Multipage blob support disabled. |
| | Version 2 - Multipage blob support enabled. |
| | Default: Version 2 |
+---------------------+--------------------------------------------------------------------+
| --keygen | Generates key for encrypting NVS partition |
+---------------------+--------------------------------------------------------------------+
| --inputkey INPUTKEY | File having key for encrypting NVS partition |
+---------------------+--------------------------------------------------------------------+
| --outdir OUTDIR | Output directory to store files created |
| | (Default: current directory) |
+---------------------+--------------------------------------------------------------------+
+---------------------------------------------+-------------------------------------------------------------------------------+
| Parameter | Description |
+=============================================+===============================================================================+
| ``-h`` / ``--help`` | Show the help message and exit |
+---------------------------------------------+-------------------------------------------------------------------------------+
| ``--fileid FILEID`` | Unique file identifier (any key in values file) |
| | for each filename suffix (Default: numeric value(1,2,3...)) |
+---------------------------------------------+-------------------------------------------------------------------------------+
| ``--version {1,2}`` | Set multipage blob version. (Default: Version 2) |
| | |
| | Version 1 - Multipage blob support disabled. |
| | |
| | Version 2 - Multipage blob support enabled. |
+---------------------------------------------+-------------------------------------------------------------------------------+
| ``--keygen`` | Generates key for encrypting NVS partition |
+---------------------------------------------+-------------------------------------------------------------------------------+
| ``--inputkey INPUTKEY`` | File having key for encrypting NVS partition |
+---------------------------------------------+-------------------------------------------------------------------------------+
| ``--outdir OUTDIR`` | Output directory to store files created (Default: current directory) |
+---------------------------------------------+-------------------------------------------------------------------------------+
| ``--key_protect_hmac`` | If set, the NVS encryption key protection scheme based on HMAC |
| | peripheral is used; else the default scheme based on Flash Encryption |
| | is used |
+---------------------------------------------+-------------------------------------------------------------------------------+
| ``--kp_hmac_keygen`` | Generate the HMAC key for HMAC-based encryption scheme |
+---------------------------------------------+-------------------------------------------------------------------------------+
| ``--kp_hmac_keyfile KP_HMAC_KEYFILE`` | Path to output HMAC key file |
+---------------------------------------------+-------------------------------------------------------------------------------+
| ``--kp_hmac_inputkey KP_HMAC_INPUTKEY`` | File having the HMAC key for generating the NVS encryption keys |
+---------------------------------------------+-------------------------------------------------------------------------------+
You can run the utility to generate factory images for each device using the command below. A sample CSV file is provided with the utility::
@@ -213,7 +224,21 @@ You can run the utility to encrypt factory images for each device using the comm
python mfg_gen.py generate samples/sample_config.csv samples/sample_values_singlepage_blob.csv Sample 0x3000 --keygen
.. note:: Encryption key of the following format ``<outdir>/keys/keys-<prefix>-<fileid>.bin`` is created. This newly created file having encryption keys in ``keys/`` directory is compatible with NVS key-partition structure. Refer to :ref:`nvs_key_partition` for more details.
.. note:: Encryption key of the following format ``<outdir>/keys/keys-<prefix>-<fileid>.bin`` is created. This newly created file having encryption keys in ``keys/`` directory is compatible with NVS key-partition structure. Refer to :ref:`nvs_encr_key_partition` for more details.
- To generate an encrypted image using the HMAC-based scheme, the above command can be used alongwith some additional parameters.
- Encrypt by allowing the utility to generate encryption keys and the HMAC-key::
python mfg_gen.py generate samples/sample_config.csv samples/sample_values_singlepage_blob.csv Sample 0x3000 --keygen --key_protect_hmac --kp_hmac_keygen
.. note:: Encryption key of the format ``<outdir>/keys/keys-<timestamp>.bin`` and HMAC key of the format ``<outdir>/keys/hmac-keys-<timestamp>.bin`` are created.
- Encrypt by allowing the utility to generate encryption keys with user-provided HMAC-key::
python mfg_gen.py generate samples/sample_config.csv samples/sample_values_singlepage_blob.csv Sample 0x3000 --keygen --key_protect_hmac --kp_hmac_inputkey testdata/sample_hmac_key.bin
.. note:: You can provide the custom filename for the HMAC key as well as the encryption key as a parameter.
- Encrypt by providing the encryption keys as input binary file::
@@ -225,16 +250,25 @@ You can run the utility to encrypt factory images for each device using the comm
python mfg_gen.py generate-key [-h] [--keyfile KEYFILE] [--outdir OUTDIR]
**Optional Arguments**:
+--------------------+----------------------------------------------------------------------+
| Parameter | Description |
+====================+======================================================================+
| -h, --help | show this help message and exit |
+--------------------+----------------------------------------------------------------------+
| --keyfile KEYFILE | Path to output encryption keys file |
+--------------------+----------------------------------------------------------------------+
| --outdir OUTDIR | Output directory to store files created. |
| | (Default: current directory) |
+--------------------+----------------------------------------------------------------------+
+---------------------------------------------+-----------------------------------------------------------------------------------+
| Parameter | Description |
+=============================================+===================================================================================+
| ``-h`` / ``--help`` | Show the help message and exit |
+---------------------------------------------+-----------------------------------------------------------------------------------+
| ``--keyfile KEYFILE`` | Path to output encryption keys file |
+---------------------------------------------+-----------------------------------------------------------------------------------+
| ``--outdir OUTDIR`` | Output directory to store files created. (Default: current directory) |
+---------------------------------------------+-----------------------------------------------------------------------------------+
| ``--key_protect_hmac`` | If set, the NVS encryption key protection scheme based on HMAC |
| | peripheral is used; else the default scheme based on Flash Encryption |
| | is used |
+---------------------------------------------+-----------------------------------------------------------------------------------+
| ``--kp_hmac_keygen`` | Generate the HMAC key for HMAC-based encryption scheme |
+---------------------------------------------+-----------------------------------------------------------------------------------+
| ``--kp_hmac_keyfile KP_HMAC_KEYFILE`` | Path to output HMAC key file |
+---------------------------------------------+-----------------------------------------------------------------------------------+
| ``--kp_hmac_inputkey KP_HMAC_INPUTKEY`` | File having the HMAC key for generating the NVS encryption keys |
+---------------------------------------------+-----------------------------------------------------------------------------------+
You can run the utility to generate only encryption keys using the command below::
@@ -242,6 +276,20 @@ You can run the utility to generate only encryption keys using the command below
.. note:: Encryption key of the following format ``<outdir>/keys/keys-<timestamp>.bin`` is created. Timestamp format is: ``%m-%d_%H-%M``. To provide custom target filename use the --keyfile argument.
For generating encryption key for the HMAC-based scheme, the following commands can be used:
- Generate the HMAC key and the NVS encryption keys::
python mfg_gen.py generate-key --key_protect_hmac --kp_hmac_keygen
.. note:: Encryption key of the format ``<outdir>/keys/keys-<timestamp>.bin`` and HMAC key of the format ``<outdir>/keys/hmac-keys-<timestamp>.bin`` are created.
- Generate the NVS encryption keys, given the HMAC-key::
python mfg_gen.py generate-key --key_protect_hmac --kp_hmac_inputkey testdata/sample_hmac_key.bin
.. note:: You can provide the custom filename for the HMAC key as well as the encryption key as a parameter.
Generated encryption key binary file can further be used to encrypt factory images created on the per device basis.
The default numeric value: 1,2,3... of the ``fileid`` argument corresponds to each line bearing device instance values in the master value CSV file.