blackbeard420/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf synced 2025-03-10 01:29:21 -04:00
Code Issues Projects Releases Wiki Activity

Merge branch 'fix/nvs_part_gen_docs' into 'master'

Browse Source 
fix(docs/nvs_part_gen): Show the NVS HMAC encryption scheme-specific commands only for supported SOCs

See merge request espressif/esp-idf!26332
This commit is contained in:
Laukik Hase 2023-10-11 20:56:54 +08:00
commit 239bc3b96f
1 changed files with 75 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
components/nvs_flash/nvs_partition_generator/README.rst
View File

@ -158,12 +158,19 @@ You can run the utility to generate NVS partition using the command below. A sam
Generate Encryption Keys Partition Generate Encryption Keys Partition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Usage**:: .. only:: SOC_HMAC_SUPPORTED
python nvs_partition_gen.py generate-key [-h] [--key_protect_hmac] [--kp_hmac_keygen] **Usage**::
[--kp_hmac_keyfile KP_HMAC_KEYFILE] [--kp_hmac_inputkey KP_HMAC_INPUTKEY]
[--keyfile KEYFILE] [--outdir OUTDIR]
python nvs_partition_gen.py generate-key [-h] [--key_protect_hmac] [--kp_hmac_keygen]
[--kp_hmac_keyfile KP_HMAC_KEYFILE] [--kp_hmac_inputkey KP_HMAC_INPUTKEY]
[--keyfile KEYFILE] [--outdir OUTDIR]
.. only:: not SOC_HMAC_SUPPORTED
**Usage**::
python nvs_partition_gen.py generate-key [-h] [--keyfile KEYFILE] [--outdir OUTDIR]
**Optional Arguments**: **Optional Arguments**:
@ -172,49 +179,69 @@ Generate Encryption Keys Partition
+=============================================+===================================================================================+ +=============================================+===================================================================================+
| ``-h`` \ ``--help`` | Show the help message and exit | | ``-h`` \ ``--help`` | Show the help message and exit |
+---------------------------------------------+-----------------------------------------------------------------------------------+ +---------------------------------------------+-----------------------------------------------------------------------------------+
| ``--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 |
+---------------------------------------------+-----------------------------------------------------------------------------------+
| ``--keyfile KEYFILE`` | Path to output encryption keys file | | ``--keyfile KEYFILE`` | Path to output encryption keys file |
+---------------------------------------------+-----------------------------------------------------------------------------------+ +---------------------------------------------+-----------------------------------------------------------------------------------+
| ``--outdir OUTDIR`` | Output directory to store files created. (Default: current directory) | | ``--outdir OUTDIR`` | Output directory to store files created. (Default: current directory) |
+---------------------------------------------+-----------------------------------------------------------------------------------+ +---------------------------------------------+-----------------------------------------------------------------------------------+
.. only:: SOC_HMAC_SUPPORTED
**Optional Arguments (HMAC scheme-specific)**:
+---------------------------------------------+-----------------------------------------------------------------------------------+
| Parameter | Description |
+=============================================+===================================================================================+
| ``--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 the encryption key partition using the command below:: You can run the utility to generate only the encryption key partition using the command below::
python nvs_partition_gen.py generate-key python nvs_partition_gen.py generate-key
For generating encryption key for the HMAC-based scheme, the following commands can be used: .. only:: SOC_HMAC_SUPPORTED
- Generate the HMAC key and the NVS encryption keys:: For generating encryption key for the HMAC-based scheme, the following commands can be used:
python nvs_partition_gen.py generate-key --key_protect_hmac --kp_hmac_keygen - Generate the HMAC key and the NVS encryption keys::
.. 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. python nvs_partition_gen.py generate-key --key_protect_hmac --kp_hmac_keygen
- Generate the NVS encryption keys, given the HMAC-key:: .. 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.
python nvs_partition_gen.py generate-key --key_protect_hmac --kp_hmac_inputkey testdata/sample_hmac_key.bin - Generate the NVS encryption keys, given the HMAC-key::
.. note:: You can provide the custom filename for the HMAC key as well as the encryption key as a parameter. python nvs_partition_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.
Generate Encrypted NVS Partition Generate Encrypted NVS Partition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Usage**:: .. only:: SOC_HMAC_SUPPORTED
python nvs_partition_gen.py encrypt [-h] [--version {1,2}] [--keygen] **Usage**::
[--keyfile KEYFILE] [--inputkey INPUTKEY] [--outdir OUTDIR]
[--key_protect_hmac] [--kp_hmac_keygen] python nvs_partition_gen.py encrypt [-h] [--version {1,2}] [--keygen]
[--kp_hmac_keyfile KP_HMAC_KEYFILE] [--kp_hmac_inputkey KP_HMAC_INPUTKEY] [--keyfile KEYFILE] [--inputkey INPUTKEY] [--outdir OUTDIR]
input output size [--key_protect_hmac] [--kp_hmac_keygen]
[--kp_hmac_keyfile KP_HMAC_KEYFILE] [--kp_hmac_inputkey KP_HMAC_INPUTKEY]
input output size
.. only:: not SOC_HMAC_SUPPORTED
**Usage**::
python nvs_partition_gen.py encrypt [-h] [--version {1,2}] [--keygen]
[--keyfile KEYFILE] [--inputkey INPUTKEY] [--outdir OUTDIR]
input output size
**Positional Arguments**: **Positional Arguments**:
@ -250,16 +277,24 @@ Generate Encrypted NVS Partition
+---------------------------------------------+-------------------------------------------------------------------------------+ +---------------------------------------------+-------------------------------------------------------------------------------+
| ``--outdir OUTDIR`` | Output directory to store file created (Default: current directory) | | ``--outdir OUTDIR`` | Output directory to store file 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 | .. only:: SOC_HMAC_SUPPORTED
| | is used |
+---------------------------------------------+-------------------------------------------------------------------------------+ **Optional Arguments (HMAC scheme-specific)**:
| ``--kp_hmac_keygen`` | Generate the HMAC key for HMAC-based encryption scheme |
+---------------------------------------------+-------------------------------------------------------------------------------+ +---------------------------------------------+-------------------------------------------------------------------------------+
| ``--kp_hmac_keyfile KP_HMAC_KEYFILE`` | Path to output HMAC key file | | Parameter | Description |
+---------------------------------------------+-------------------------------------------------------------------------------+ +=============================================+===============================================================================+
| ``--kp_hmac_inputkey KP_HMAC_INPUTKEY`` | File having the HMAC key for generating the NVS encryption keys | | ``--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 encrypt NVS partition using the command below. A sample CSV file is provided with the utility: You can run the utility to encrypt NVS partition using the command below. A sample CSV file is provided with the utility:
@ -269,6 +304,8 @@ You can run the utility to encrypt NVS partition using the command below. A samp
.. note:: Encryption key of the format ``<outdir>/keys/keys-<timestamp>.bin`` is created. .. note:: Encryption key of the format ``<outdir>/keys/keys-<timestamp>.bin`` is created.
.. only:: SOC_HMAC_SUPPORTED
- To generate an encrypted partition using the HMAC-based scheme, the above command can be used alongwith some additional parameters. - To generate an encrypted partition 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:: - Encrypt by allowing the utility to generate encryption keys and the HMAC-key::