Merge branch 'docs/flash_enc_512bits' into 'master'

docs: update flash encryption docs with 512bit key related info

Closes IDF-3867

See merge request espressif/esp-idf!15318

Author: ESP-Marius

docs/en/security/flash-encryption.rst

@@ -283,71 +283,73 @@ To use a host generated key, take the following steps:
 
 2. Generate a random key by running:
 
-.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
+  .. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
 
-    If :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-256 (512-bit key) need to use the `XTS_AES_256_KEY_1` and `XTS_AES_256_KEY_2` purposes. The espsecure does not support 512-bit key, but it is possible to workaround:
+      If :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-128 (256-bit key):
 
-    .. code-block:: bash
+      .. code-block:: bash
 
-        espsecure.py generate_flash_encryption_key my_flash_encryption_key1.bin
+          espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
 
-        espsecure.py generate_flash_encryption_key my_flash_encryption_key2.bin
+      else if :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-256 (512-bit key):
 
-        # To use encrypt_flash_data with XTS_AES_256 requires combining the two binary files to one 64 byte file
-        cat my_flash_encryption_key1.bin my_flash_encryption_key2.bin > my_flash_encryption_key.bin
+      .. code-block:: bash
 
-    If :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-128 (256-bit key) need to use the `XTS_AES_128_KEY` purpose.
+          espsecure.py generate_flash_encryption_key --keylen 512 my_flash_encryption_key.bin
 
-    .. code-block:: bash
 
-        espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
+  .. only:: not SOC_FLASH_ENCRYPTION_XTS_AES_256
 
+      .. code-block:: bash
 
-.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES_256
+          espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
 
-    .. code-block:: bash
+3. **Before the first encrypted boot**, burn the key into your device's eFuse using the command below. This action can be done **only once**.
 
-        espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
+  .. only:: not SOC_FLASH_ENCRYPTION_XTS_AES
 
-3. **Before the first encrypted boot**, burn the key into your device's eFuse using the command below. This action can be done **only once**.
+    .. code-block:: bash
 
-.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES
+        espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin
 
-  .. code-block:: bash
+  .. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
+
+    .. code-block:: bash
 
-      espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin
+        espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin KEYPURPOSE
 
-.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
+    where ``BLOCK`` is a free keyblock between ``BLOCK_KEY0`` and ``BLOCK_KEY5``. And ``KEYPURPOSE`` is either ``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.
 
-  .. code-block:: bash
+    For AES-128 (256-bit key) - ``XTS_AES_128_KEY``:
 
-      espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin KEYPURPOSE
+    .. code-block:: bash
 
-  where ``BLOCK`` is a free keyblock between ``BLOCK_KEY0`` and ``BLOCK_KEY5``. And ``KEYPURPOSE`` is either ``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.
+        espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY
 
-  AES-128 (256-bit key) - ``XTS_AES_128_KEY``:
+    For AES-256 (512-bit key) - ``XTS_AES_256_KEY_1`` and ``XTS_AES_256_KEY_2``. ``espefuse.py`` 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.py`` will burn the first 256 bit of the key to the specified ``BLOCK`` and burn the corresponding block key purpose to ``XTS_AES_256_KEY_1``. The last 256 bit 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
+    .. code-block:: bash
 
-      espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY
+        espefuse.py  --port PORT  burn_key BLOCK my_flash_encryption_key.bin XTS_AES_256_KEY
 
-  AES-256 (512-bit key) - ``XTS_AES_256_KEY_1`` and ``XTS_AES_256_KEY_2``. It is not fully supported yet in espefuse.py and espsecure.py. Need to do the following steps:
+    If you wish to specify exactly which two blocks are used then it is possible to divide 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
+    .. code-block:: bash
 
-      espefuse.py  --port PORT  burn_key BLOCK   my_flash_encryption_key1.bin XTS_AES_256_KEY_1
+      split -b 32 my_flash_encryption_key.bin my_flash_encryption_key.bin.
+      espefuse.py  --port PORT  burn_key BLOCK my_flash_encryption_key.bin.aa XTS_AES_256_KEY_1
+      espefuse.py  --port PORT  burn_key BLOCK+1 my_flash_encryption_key.bin.ab XTS_AES_256_KEY_2
 
-      espefuse.py  --port PORT  burn_key BLOCK+1 my_flash_encryption_key2.bin XTS_AES_256_KEY_2
 
-.. only:: SOC_FLASH_ENCRYPTION_XTS_AES and not SOC_FLASH_ENCRYPTION_XTS_AES_256
+  .. only:: SOC_FLASH_ENCRYPTION_XTS_AES and not SOC_FLASH_ENCRYPTION_XTS_AES_256
 
-  .. code-block:: bash
+    .. code-block:: bash
 
-      espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY
+        espefuse.py --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``.
+    where ``BLOCK`` is a free keyblock between ``BLOCK_KEY0`` and ``BLOCK_KEY5``.
 
-If the key is not burned and the device is started after enabling flash encryption, the {IDF_TARGET_NAME} will generate a random key that software cannot access or modify.
+  If the key is not burned and the device is started after enabling flash encryption, the {IDF_TARGET_NAME} will generate a random key that software cannot access or modify.
 
 4. In :ref:`project-configuration-menu`, do the following:
 
@@ -875,12 +877,6 @@ Manually encrypting or decrypting files requires the flash encryption key to be
 
 The key file should be a single raw binary file (example: ``key.bin``).
 
-.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
-
-    .. note::
-
-       If using AES-XTS-256 then the key file is generated in two parts for programming via ``espefuse.py`` (``XTS_AES_256_KEY_1`` and ``XTS_AES_256_KEY_2``). ``espsecure.py`` currently only supports a single key file for encrypt/decrypt, so the individual files used for ``XTS_AES_256_KEY_1`` and ``XTS_AES_256_KEY_2`` should be manually concatenated to create a single file 64 bytes long.
-
 For example, these are the steps to encrypt the file ``build/my-app.bin`` to flash at offset 0x10000. Run espsecure.py as follows:
 
 .. only:: esp32
@@ -962,7 +958,7 @@ The following sections provide some reference information about the operation of
 
   Flash Encryption Algorithm
   ^^^^^^^^^^^^^^^^^^^^^^^^^^
-  
+
   - {IDF_TARGET_NAME} use the XTS-AES block cipher mode with 256 bit or 512 bit key size for flash encryption.
 
   - XTS-AES is a block cipher mode specifically designed for disc encryption and addresses the weaknesses other potential modes (e.g. AES-CTR) have for this use case. A detailed description of the XTS-AES algorithm can be found in `IEEE Std 1619-2007 <https://ieeexplore.ieee.org/document/4493450>`_.