kopia lustrzana https://github.com/espressif/esp-idf
[docs]: Clarified and improved Secure Boot docs
Jakob Hasse
rodzic
40cfc91aa2
commit
ea2e2b0d62
|
|
@ -5,40 +5,42 @@ Secure Boot V2
|
|||
|
||||
.. important::
|
||||
|
||||
The references in this document are related to Secure Boot V2, the preferred scheme from ESP32 ECO3 onwards, in ESP32-S2, and from ESP32-C3 ECO3 onwards.
|
||||
This document is about Secure Boot V2, supported on the following chips: ESP32 (ECO3 onwards), ESP32-S2, ESP32-S3 and ESP32-C3 (ECO3 onwards). Except for ESP32, it is the only supported Secure Boot scheme.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
Refer also to :doc:`Secure Boot <secure-boot-v1>` for ESP32.
|
||||
For ESP32 before ECO3, refer to :doc:`Secure Boot <secure-boot-v1>`. It is recommended that users use Secure Boot V2 if they have a chip version that supports it. Secure Boot V2 is safer and more flexible than Secure Boot V1.
|
||||
|
||||
Secure Boot V2 uses RSA based app and bootloader verification. This document can also be referred for signing apps with the RSA scheme without signing the bootloader.
|
||||
Secure Boot V2 uses RSA based app and bootloader verification. This document can also be used as a reference for signing apps using the RSA scheme without signing the bootloader.
|
||||
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
``Secure Boot V2`` and RSA scheme (``App Signing Scheme``) options are available for ESP32 from ECO3 onwards. To get these options visible in the menuconfig set :ref:`CONFIG_ESP32_REV_MIN` greater than or equal to `Rev 3`.
|
||||
``Secure Boot V2`` and RSA scheme (``App Signing Scheme``) options are available for ESP32 from ECO3 onwards. To use these options in menuconfig, set :ref:`CONFIG_ESP32_REV_MIN` greater than or equal to `Rev 3`.
|
||||
|
||||
.. only:: esp32c3
|
||||
|
||||
``Secure Boot V2`` is available for ESP32-C3 from ECO3 onwards. To get these options visible in the menuconfig set :ref:`CONFIG_ESP32C3_REV_MIN` greater than or equal to `Rev 3`.
|
||||
``Secure Boot V2`` is available for ESP32-C3 from ECO3 onwards. To use these options in menuconfig, set :ref:`CONFIG_ESP32C3_REV_MIN` greater than or equal to `Rev 3`.
|
||||
|
||||
Background
|
||||
----------
|
||||
|
||||
Secure Boot protects a device from running unsigned code (verification at time of load). A new RSA based secure boot
|
||||
verification scheme (Secure Boot V2) has been introduced for ESP32-S2, ESP32-S3, ESP32-C3 ECO3 onwards, and ESP32 ECO3 onwards.
|
||||
Secure Boot protects a device from running any unauthorized (i.e., unsigned) code by checking that each piece of software that is being booted is signed. On an {IDF_TARGET_NAME}, these pieces of software include the second stage bootloader and each application binary. Note that the first stage bootloader does not require signing as it is ROM code thus cannot be changed.
|
||||
|
||||
- The software bootloader’s RSA-PSS signature is verified by the Mask ROM and it is executed post successful verification.
|
||||
- The verified software bootloader verifies the RSA-PSS signature of the application image before it is executed.
|
||||
A new RSA based Secure Boot verification scheme (Secure Boot V2) has been introduced on the ESP32 (ECO3 onwards), ESP32-S2, ESP32-S3 and ESP32-C3 (ECO3 onwards).
|
||||
|
||||
The Secure Boot process on the {IDF_TARGET_NAME} involves the following steps:
|
||||
1. When the first stage bootloader loads the second stage bootloader, the second stage bootloader's RSA-PSS signature is verified. If the verification is successful, the second stage bootloader is executed.
|
||||
2. When the second stage bootloader loads a particular application image, the application's RSA-PSS signature is verified. If the verification is successful, the application image is executed.
|
||||
|
||||
Advantages
|
||||
----------
|
||||
|
||||
- The RSA public key is stored on the device. The corresponding RSA private key is kept secret on a server and is never accessed by the device.
|
||||
- The RSA public key is stored on the device. The corresponding RSA private key is kept at a secret place and is never accessed by the device.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
- Only one public key can be generated and stored in ESP32 ECO3 during manufacturing.
|
||||
- Only one public key can be generated and stored in the chip during manufacturing.
|
||||
|
||||
.. only:: esp32s2 or esp32c3 or esp32s3
|
||||
|
||||
|
|
@ -48,27 +50,45 @@ Advantages
|
|||
|
||||
- Conservatively - The old key is revoked after the bootloader and application have successfully migrated to a new key. Aggressively - The key is revoked as soon as verification with this key fails.
|
||||
|
||||
- Same image format & signature verification is applied for applications & software bootloader.
|
||||
- Same image format and signature verification method is applied for applications and software bootloader.
|
||||
|
||||
- No secrets are stored on the device. Therefore immune to passive side-channel attacks (timing or power analysis, etc.)
|
||||
- No secrets are stored on the device. Therefore, it is immune to passive side-channel attacks (timing or power analysis, etc.)
|
||||
|
||||
|
||||
Secure Boot V2 Process
|
||||
----------------------
|
||||
|
||||
This is an overview of the Secure Boot V2 Process, Step by step instructions are supplied under :ref:`secure-boot-v2-howto`.
|
||||
This is an overview of the Secure Boot V2 Process. Instructions how to enable Secure Boot are supplied in section :ref:`secure-boot-v2-howto`.
|
||||
|
||||
1. Secure Boot V2 verifies the signature blocks appended to the bootloader and application binaries. The signature block contains the image binary signed by a RSA-3072 private key and its corresponding public key. More details on the :ref:`signature-block-format`.
|
||||
Secure Boot V2 verifies the bootloader image and application binary images using a dedicated *signature block*. Each image has a separately generated signature block which is appended to the end of the image.
|
||||
|
||||
2. On startup, ROM code checks the Secure Boot V2 bit in eFuse.
|
||||
.. only:: esp32
|
||||
|
||||
3. If secure boot is enabled, ROM checks the SHA-256 of the public key in the signature block in the eFuse.
|
||||
Only one signature block can be appended to the bootloader or application image in ESP32 ECO3.
|
||||
|
||||
4. The ROM code validates the public key embedded in the software bootloader's signature block by matching the SHA-256 of its public key to the SHA-256 in eFuse as per the earlier step. Boot process will be aborted if a valid hash of the public key isn’t found in the eFuse.
|
||||
.. only:: esp32s2 or esp32c3 or esp32s3
|
||||
|
||||
5. The ROM code verifies the signature of the bootloader with the pre-validated public key with the RSA-PSS Scheme. In depth information on :ref:`verify_signature-block`.
|
||||
Up to 3 signature blocks can be appended to the bootloader or application image in {IDF_TARGET_NAME}.
|
||||
|
||||
6. Software bootloader, reads the app partition and performs similar verification on the application. The application is verified on every boot up and OTA update. If selected OTA app partition fails verification, bootloader will fall back and look for another correctly signed partition.
|
||||
Each signature block contains a signature of the preceding image as well as the corresponding RSA-3072 public key. For more details about the format, refer to :ref:`signature-block-format`. A digest of the RSA-3072 public key is stored in the eFuse.
|
||||
|
||||
The application image is not only verified on every boot but also on each over the air (OTA) update. If the currently selected OTA app image cannot be verified, the bootloader will fall back and look for another correctly signed application image.
|
||||
|
||||
The Secure Boot V2 process follows these steps:
|
||||
|
||||
1. On startup, the ROM code checks the Secure Boot V2 bit in the eFuse. If Secure Boot is disabled, a normal boot will be executed. If Secure Boot is enabled, the boot will proceed according to the following steps.
|
||||
|
||||
2. The ROM code verifies the bootloader's signature block (:ref:`verify_signature-block`). If this fails, the boot process will be aborted.
|
||||
|
||||
3. The ROM code verifies the bootloader image using the raw image data, its corresponding signature block(s), and the eFuse (:ref:`verify_image`). If this fails, the boot process will be aborted.
|
||||
|
||||
4. The ROM code executes the bootloader.
|
||||
|
||||
5. The bootloader verifies the application image's signature block (:ref:`verify_signature-block`). If this fails, the boot process will be aborted.
|
||||
|
||||
6. The bootloader verifies the application image using the raw image data, its corresponding signature blocks and the eFuse (:ref:`verify_image`). If this fails, the boot process will be aborted. If the verification fails but another application image is found, the bootloader will then try to verify that other image using steps 5 to 7. This repeats until a valid image is found or no other images are found.
|
||||
|
||||
7. The bootloader executes the verified application image.
|
||||
|
||||
.. _signature-block-format:
|
||||
|
||||
|
|
@ -77,29 +97,49 @@ Signature Block Format
|
|||
|
||||
The bootloader and application images are padded to the next 4096 byte boundary, thus the signature has a flash sector of its own. The signature is calculated over all bytes in the image including the padding bytes.
|
||||
|
||||
Each signature block contains the following:
|
||||
The content of each signature block is shown in the following table:
|
||||
|
||||
* **Offset 0 (1 byte):** Magic byte (0xe7)
|
||||
.. list-table:: Content of a Signature Block
|
||||
:widths: 10 10 40
|
||||
:header-rows: 1
|
||||
|
||||
* **Offset 1 (1 byte):** Version number byte (currently 0x02), 0x01 is for Secure Boot V1.
|
||||
* - **Offset**
|
||||
- **Size (bytes)**
|
||||
- **Description**
|
||||
* - 0
|
||||
- 1
|
||||
- Magic byte
|
||||
* - 1
|
||||
- 1
|
||||
- Version number byte (currently 0x02), 0x01 is for Secure Boot V1.
|
||||
* - 2
|
||||
- 2
|
||||
- Padding bytes, Reserved. Should be zero.
|
||||
* - 4
|
||||
- 32
|
||||
- SHA-256 hash of only the image content, not including the signature block.
|
||||
* - 36
|
||||
- 384
|
||||
- RSA Public Modulus used for signature verification. (value ‘n’ in RFC8017).
|
||||
* - 420
|
||||
- 4
|
||||
- RSA Public Exponent used for signature verification (value ‘e’ in RFC8017).
|
||||
* - 424
|
||||
- 384
|
||||
- Pre-calculated R, derived from ‘n’.
|
||||
* - 808
|
||||
- 4
|
||||
- Pre-calculated M’, derived from ‘n’
|
||||
* - 812
|
||||
- 384
|
||||
- RSA-PSS Signature result (section 8.1.1 of RFC8017) of image content, computed using following PSS parameters: SHA256 hash, MFG1 function, 0 length salt, default trailer field (0xBC).
|
||||
* - 1196
|
||||
- 4
|
||||
- CRC32 of the preceding 1095 bytes.
|
||||
* - 1200
|
||||
- 16
|
||||
- Zero padding to length 1216 bytes.
|
||||
|
||||
* **Offset 2 (2 bytes):** Padding bytes, Reserved. Should be zero.
|
||||
|
||||
* **Offset 4 (32 bytes):** SHA-256 hash of only the image content, not including the signature block.
|
||||
|
||||
* **Offset 36 (384 bytes):** RSA Public Modulus used for signature verification. (value ‘n’ in RFC8017).
|
||||
|
||||
* **Offset 420 (4 bytes):** RSA Public Exponent used for signature verification (value ‘e’ in RFC8017).
|
||||
|
||||
* **Offset 424 (384 bytes):** Precalculated R, derived from ‘n’.
|
||||
|
||||
* **Offset 808 (4 bytes):** Precalculated M’, derived from ‘n’
|
||||
|
||||
* **Offset 812 (384 bytes):** RSA-PSS Signature result (section 8.1.1 of RFC8017) of image content, computed using following PSS parameters: SHA256 hash, MFG1 function, 0 length salt, default trailer field (0xBC).
|
||||
|
||||
* **Offset 1196:** CRC32 of the preceding 1095 bytes.
|
||||
|
||||
* **Offset 1200 (16 bytes):** Zero padding to length 1216 bytes.
|
||||
|
||||
.. note::
|
||||
R and M' are used for hardware-assisted Montgomery Multiplication.
|
||||
|
|
@ -108,33 +148,23 @@ The remainder of the signature sector is erased flash (0xFF) which allows writin
|
|||
|
||||
.. _verify_signature-block:
|
||||
|
||||
Verifying the signature Block
|
||||
Verifying a Signature Block
|
||||
-----------------------------
|
||||
|
||||
A signature block is “valid” if the first byte is 0xe7 and a valid CRC32 is stored at offset 1196.
|
||||
A signature block is “valid” if the first byte is 0xe7 and a valid CRC32 is stored at offset 1196. Otherwise it's invalid.
|
||||
|
||||
.. only:: esp32
|
||||
.. _verify_image:
|
||||
|
||||
Only one signature block can be appended to the bootloader or application image in ESP32 ECO3.
|
||||
|
||||
.. only:: esp32s2 or esp32c3 or esp32s3
|
||||
|
||||
Upto 3 signature blocks can be appended to the bootloader or application image in {IDF_TARGET_NAME}.
|
||||
Verifying an Image
|
||||
-----------------------------
|
||||
|
||||
An image is “verified” if the public key stored in any signature block is valid for this device, and if the stored signature is valid for the image data read from flash.
|
||||
|
||||
1. The magic byte, signature block CRC is validated.
|
||||
1. Compare the SHA-256 hash digest of the public key embedded in the bootloader's signature block with the digest(s) saved in the eFuses. If public key's hash doesn't match any of the hashes from the eFuses, the verification fails.
|
||||
|
||||
2. Public key digests are generated per signature block and compared with the digests from eFuse. If none of the digests match, the verification process is aborted.
|
||||
2. Generate the application image digest and match it with the image digest in the signature block. If the digests don't match, the verification fails.
|
||||
|
||||
3. The application image digest is generated and matched with the image digest in the signature blocks. The verification process is aborted is the digests don't match.
|
||||
|
||||
4. The public key is used to verify the signature of the bootloader image, using RSA-PSS (section 8.1.2 of RFC8017) with the image digest calculated in step (3) for comparison.
|
||||
|
||||
- The application signing scheme is set to RSA for Secure Boot V2 and to ECDSA for Secure Boot V1.
|
||||
|
||||
.. important::
|
||||
It is recommended to use Secure Boot V2 on the chip versions supporting them.
|
||||
3. Use the public key to verify the signature of the bootloader image, using RSA-PSS (section 8.1.2 of RFC8017) with the image digest calculated in step (2) for comparison.
|
||||
|
||||
Bootloader Size
|
||||
---------------
|
||||
|
|
@ -150,17 +180,17 @@ eFuse usage
|
|||
|
||||
ESP32-ECO3:
|
||||
|
||||
- ABS_DONE_1 - Enables secure boot protection on boot.
|
||||
- ABS_DONE_1 - Enables Secure Boot protection on boot.
|
||||
|
||||
- BLK2 - Stores the SHA-256 digest of the public key. SHA-256 hash of public key modulus, exponent, precalculated R & M’ values (represented as 776 bytes – offsets 36 to 812 - as per the :ref:`signature-block-format`) is written to an eFuse key block. The write-protection bit must be set, but the read-protection bit must not.
|
||||
- BLK2 - Stores the SHA-256 digest of the public key. SHA-256 hash of public key modulus, exponent, pre-calculated R & M’ values (represented as 776 bytes – offsets 36 to 812 - as per the :ref:`signature-block-format`) is written to an eFuse key block. The write-protection bit must be set, but the read-protection bit must not.
|
||||
|
||||
.. only:: esp32s2 or esp32c3 or esp32s3
|
||||
|
||||
- SECURE_BOOT_EN - Enables secure boot protection on boot.
|
||||
- SECURE_BOOT_EN - Enables Secure Boot protection on boot.
|
||||
|
||||
- KEY_PURPOSE_X - Set the purpose of the key block on {IDF_TARGET_NAME} by programming SECURE_BOOT_DIGESTX (X = 0, 1, 2) into KEY_PURPOSE_X (X = 0, 1, 2, 3, 4, 5). Example: If KEY_PURPOSE_2 is set to SECURE_BOOT_DIGEST1, then BLOCK_KEY2 will have the Secure Boot V2 public key digest. The write-protection bit must be set (this field does not have a read-protection bit).
|
||||
|
||||
- BLOCK_KEYX - The block contains the data corresponding to its purpose programmed in KEY_PURPOSE_X. Stores the SHA-256 digest of the public key. SHA-256 hash of public key modulus, exponent, precalculated R & M’ values (represented as 776 bytes – offsets 36 to 812 - as per the :ref:`signature-block-format`) is written to an eFuse key block. The write-protection bit must be set, but the read-protection bit must not.
|
||||
- BLOCK_KEYX - The block contains the data corresponding to its purpose programmed in KEY_PURPOSE_X. Stores the SHA-256 digest of the public key. SHA-256 hash of public key modulus, exponent, pre-calculated R & M’ values (represented as 776 bytes – offsets 36 to 812 - as per the :ref:`signature-block-format`) is written to an eFuse key block. The write-protection bit must be set, but the read-protection bit must not.
|
||||
|
||||
- KEY_REVOKEX - The revocation bits corresponding to each of the 3 key block. Ex. Setting KEY_REVOKE2 revokes the key block whose key purpose is SECURE_BOOT_DIGEST2.
|
||||
|
||||
|
|
@ -168,7 +198,7 @@ eFuse usage
|
|||
|
||||
To ensure no trusted keys can be added later by an attacker, each unused key digest slot should be revoked (KEY_REVOKEX). It will be checked during app startup in :cpp:func:`esp_secure_boot_init_checks` and fixed unless :ref:`CONFIG_SECURE_BOOT_ALLOW_UNUSED_DIGEST_SLOTS` is enabled.
|
||||
|
||||
The key(s) must be readable in order to give software access to it. If the key(s) is read-protected then the software reads the key(s) as all zeros and the signature verification process occurs with error, bootloader and app can not be run.
|
||||
The key(s) must be readable in order to give software access to it. If the key(s) is read-protected then the software reads the key(s) as all zeros and the signature verification process will fail, and the boot process will be aborted.
|
||||
|
||||
.. _secure-boot-v2-howto:
|
||||
|
||||
|
|
@ -181,7 +211,7 @@ How To Enable Secure Boot V2
|
|||
|
||||
2. For ESP32, Secure Boot V2 is available only ESP32 ECO3 onwards. To view the "Secure Boot V2" option the chip revision should be changed to revision 3 (ESP32- ECO3). To change the chip revision, set "Minimum Supported ESP32 Revision" to Rev 3 in "Component Config" -> "ESP32- Specific".
|
||||
|
||||
3. Specify the path to secure boot signing key, relative to the project directory.
|
||||
3. Specify the path to Secure Boot signing key, relative to the project directory.
|
||||
|
||||
4. Select the desired UART ROM download mode in "UART ROM download mode". By default the UART ROM download mode has been kept enabled in order to prevent permanently disabling it in the development phase, this option is a potentially insecure option. It is recommended to disable the UART download mode for better security.
|
||||
|
||||
|
|
@ -189,7 +219,7 @@ How To Enable Secure Boot V2
|
|||
|
||||
2. The "Secure Boot V2" option will be selected and the "App Signing Scheme" would be set to RSA by default.
|
||||
|
||||
3. Specify the path to secure boot signing key, relative to the project directory.
|
||||
3. Specify the path to Secure Boot signing key, relative to the project directory.
|
||||
|
||||
4. Select the desired UART ROM download mode in "UART ROM download mode". By default, it is set to "Permanently switch to Secure mode" which is generally recommended. For production devices, the most secure option is to set it to "Permanently disabled".
|
||||
|
||||
|
|
@ -201,30 +231,30 @@ How To Enable Secure Boot V2
|
|||
A signing key generated this way will use the best random number source available to the OS and its Python installation (`/dev/urandom` on OSX/Linux and `CryptGenRandom()` on Windows). If this random number source is weak, then the private key will be weak.
|
||||
|
||||
.. important::
|
||||
For production environments, we recommend generating the keypair using openssl or another industry standard encryption program. See :ref:`secure-boot-v2-generate-key` for more details.
|
||||
For production environments, we recommend generating the key pair using openssl or another industry standard encryption program. See :ref:`secure-boot-v2-generate-key` for more details.
|
||||
|
||||
7. 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``.
|
||||
7. 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``.
|
||||
|
||||
8. When you're ready to flash the bootloader, run the specified command (you have to enter it yourself, this step is not performed by the build system) and then wait for flashing to complete.
|
||||
|
||||
9. 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:: ``idf.py 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.
|
||||
|
||||
10. Reset the {IDF_TARGET_NAME} 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 {IDF_TARGET_NAME} to verify that secure boot is enabled and no errors have occurred due to the build configuration.
|
||||
10. Reset the {IDF_TARGET_NAME} 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 {IDF_TARGET_NAME} to verify that Secure Boot is enabled and no errors have occurred due to the build configuration.
|
||||
|
||||
.. note:: Secure boot won't be enabled until after a valid partition table and app image have been flashed. This is to prevent accidents before the system is fully configured.
|
||||
|
||||
.. note:: If the {IDF_TARGET_NAME} is reset or powered down during the first boot, it will start the process again on the next boot.
|
||||
|
||||
11. On subsequent boots, the secure boot hardware will verify the software bootloader has not changed and the software bootloader will verify the signed app image (using the validated public key portion of its appended signature block).
|
||||
11. On subsequent boots, the Secure Boot hardware will verify the software bootloader has not changed and the software bootloader will verify the signed app image (using the validated public key portion of its appended signature block).
|
||||
|
||||
Restrictions after Secure Boot is enabled
|
||||
-----------------------------------------
|
||||
|
||||
- Any updated bootloader or app will need to be signed with a key matching the digest already stored in efuse.
|
||||
- Any updated bootloader or app will need to be signed with a key matching the digest already stored in eFuse.
|
||||
|
||||
- After Secure Boot is enabled, no further efuses can be read protected. (If :doc:`/security/flash-encryption` is enabled then the bootloader will ensure that any flash encryption key generated on first boot will already be read protected.) If :ref:`CONFIG_SECURE_BOOT_INSECURE` is enabled then this behaviour can be disabled, but this is not recommended.
|
||||
- After Secure Boot is enabled, no further eFuses can be read protected. (If :doc:`/security/flash-encryption` is enabled then the bootloader will ensure that any flash encryption key generated on first boot will already be read protected.) If :ref:`CONFIG_SECURE_BOOT_INSECURE` is enabled then this behavior can be disabled, but this is not recommended.
|
||||
|
||||
.. _secure-boot-v2-generate-key:
|
||||
|
||||
|
|
@ -241,14 +271,14 @@ For example, to generate a signing key using the openssl command line:
|
|||
openssl genrsa -out my_secure_boot_signing_key.pem 3072
|
||||
```
|
||||
|
||||
Remember that the strength of the secure boot system depends on keeping the signing key private.
|
||||
Remember that the strength of the Secure Boot system depends on keeping the signing key private.
|
||||
|
||||
.. _remote-sign-v2-image:
|
||||
|
||||
Remote Signing of Images
|
||||
------------------------
|
||||
|
||||
For production builds, it can be good practice to use a remote signing server rather than have the signing key on the build machine (which is the default esp-idf secure boot configuration). The espsecure.py command line program can be used to sign app images & partition table data for secure boot, on a remote system.
|
||||
For production builds, it can be good practice to use a remote signing server rather than have the signing key on the build machine (which is the default esp-idf Secure Boot configuration). The espsecure.py command line program can be used to sign app images & partition table data for Secure Boot, on a remote system.
|
||||
|
||||
To use remote signing, disable the option "Sign binaries during build". The private signing key does not need to be present on the build system.
|
||||
|
||||
|
|
@ -264,21 +294,21 @@ Secure Boot Best Practices
|
|||
--------------------------
|
||||
|
||||
* Generate the signing key on a system with a quality source of entropy.
|
||||
* Keep the signing key private at all times. A leak of this key will compromise the secure boot system.
|
||||
* Keep the signing key private at all times. A leak of this key will compromise the Secure Boot system.
|
||||
* Do not allow any third party to observe any aspects of the key generation or signing process using espsecure.py. Both processes are vulnerable to timing or other side-channel attacks.
|
||||
* Enable all secure boot options in the Secure Boot Configuration. These include flash encryption, disabling of JTAG, disabling BASIC ROM interpeter, and disabling the UART bootloader encrypted flash access.
|
||||
* Use secure boot in combination with :doc:`flash encryption<flash-encryption>` to prevent local readout of the flash contents.
|
||||
* Enable all Secure Boot options in the Secure Boot Configuration. These include flash encryption, disabling of JTAG, disabling BASIC ROM interpreter, and disabling the UART bootloader encrypted flash access.
|
||||
* Use Secure Boot in combination with :doc:`flash encryption<flash-encryption>` to prevent local readout of the flash contents.
|
||||
|
||||
.. only:: esp32s2 or esp32c3 or esp32s3
|
||||
|
||||
Key Management
|
||||
--------------
|
||||
|
||||
* Between 1 and 3 RSA-3072 public keypairs (Keys #0, #1, #2) should be computed independently and stored separately.
|
||||
* The KEY_DIGEST efuses should be write protected after being programmed.
|
||||
* The unused KEY_DIGEST slots must have their corresponding KEY_REVOKE efuse burned to permanently disable them. This must happen before the device leaves the factory.
|
||||
* Between 1 and 3 RSA-3072 public key pairs (Keys #0, #1, #2) should be computed independently and stored separately.
|
||||
* The KEY_DIGEST eFuses should be write protected after being programmed.
|
||||
* The unused KEY_DIGEST slots must have their corresponding KEY_REVOKE eFuse burned to permanently disable them. This must happen before the device leaves the factory.
|
||||
* The eFuses can either be written by the software bootloader during during first boot after enabling "Secure Boot V2" from menuconfig or can be done using `espefuse.py` which communicates with the serial bootloader program in ROM.
|
||||
* The KEY_DIGESTs should be numbered sequentially beginning at key digest #0. (ie if key digest #1 is used, key digest #0 should be used. If key digest #2 is used, key digest #0 & #1 must be used.)
|
||||
* The KEY_DIGESTs should be numbered sequentially beginning at key digest #0. (i.e., if key digest #1 is used, key digest #0 should be used. If key digest #2 is used, key digest #0 & #1 must be used.)
|
||||
* The software bootloader (non OTA upgradeable) is signed using at least one, possibly all three, private keys and flashed in the factory.
|
||||
* Apps should only be signed with a single private key (the others being stored securely elsewhere), however they may be signed with multiple private keys if some are being revoked (see Key Revocation, below).
|
||||
|
||||
|
|
@ -297,27 +327,27 @@ Secure Boot Best Practices
|
|||
--------------
|
||||
|
||||
* Keys are processed in a linear order. (key #0, key #1, key #2).
|
||||
* Applications should be signed with only one key at a time, to minimise the exposure of unused private keys.
|
||||
* Applications should be signed with only one key at a time, to minimize the exposure of unused private keys.
|
||||
* The bootloader can be signed with multiple keys from the factory.
|
||||
|
||||
Assuming a trusted private key (N-1) has been compromised, to update to new keypair (N).
|
||||
Assuming a trusted private key (N-1) has been compromised, to update to new key pair (N).
|
||||
|
||||
1. Server sends an OTA update with an application signed with the new private key (#N).
|
||||
2. The new OTA update is written to an unused OTA app partition.
|
||||
3. The new application's signature block is validated. The public keys are checked against the digests programmed in the eFuse & the application is verified using the verified public key.
|
||||
4. The active partition is set to the new OTA application's partition.
|
||||
5. Device resets, loads the bootloader (verified with key #N-1) which then boots new app (verified with key #N).
|
||||
6. The new app verifies bootloader with key #N (as a final check) and then runs code to revoke key #N-1 (sets KEY_REVOKE efuse bit).
|
||||
6. The new app verifies bootloader with key #N (as a final check) and then runs code to revoke key #N-1 (sets KEY_REVOKE eFuse bit).
|
||||
7. The API `esp_ota_revoke_secure_boot_public_key()` can be used to revoke the key #N-1.
|
||||
|
||||
* A similiar approach can also be used to physically reflash with a new key. For physical reflashing, the bootloader content can also be changed at the same time.
|
||||
* A similar approach can also be used to physically re-flash with a new key. For physical re-flashing, the bootloader content can also be changed at the same time.
|
||||
|
||||
.. _secure-boot-v2-technical-details:
|
||||
|
||||
Technical Details
|
||||
-----------------
|
||||
|
||||
The following sections contain low-level reference descriptions of various secure boot elements:
|
||||
The following sections contain low-level reference descriptions of various Secure Boot elements:
|
||||
|
||||
Manual Commands
|
||||
~~~~~~~~~~~~~~~
|
||||
|
|
@ -337,14 +367,14 @@ Keyfile is the PEM file containing an RSA-3072 private signing key.
|
|||
Secure Boot & Flash Encryption
|
||||
------------------------------
|
||||
|
||||
If secure boot is used without :doc:`Flash Encryption <flash-encryption>`, it is possible to launch "time-of-check to time-of-use" attack, where flash contents are swapped after the image is verified and running. Therefore, it is recommended to use both the features together.
|
||||
If Secure Boot is used without :doc:`Flash Encryption <flash-encryption>`, it is possible to launch "time-of-check to time-of-use" attack, where flash contents are swapped after the image is verified and running. Therefore, it is recommended to use both the features together.
|
||||
|
||||
.. _signed-app-verify-v2:
|
||||
|
||||
Signed App Verification Without Hardware Secure Boot
|
||||
----------------------------------------------------
|
||||
|
||||
The Secure Boot V2 signature of apps can be checked on OTA update, without enabling the hardware secure boot option. This option uses the same app signature scheme as Secure Boot V2, but unlike hardware secure boot it does not prevent an attacker who can write to flash from bypassing the signature protection.
|
||||
The Secure Boot V2 signature of apps can be checked on OTA update, without enabling the hardware Secure Boot option. This option uses the same app signature scheme as Secure Boot V2, but unlike hardware Secure Boot it does not prevent an attacker who can write to flash from bypassing the signature protection.
|
||||
|
||||
This may be desirable in cases where the delay of Secure Boot verification on startup is unacceptable, and/or where the threat model does not include physical access or attackers writing to bootloader or app partitions in flash.
|
||||
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue