docs/en/security: Add documentation for signed apps without hardware secure boot...

diff --git a/docs/en/api-reference/system/esp_https_ota.rst b/docs/en/api-reference/system/esp_https_ota.rst
index 762de6cf72d9b84674db8bbac65ae900727b34d7..72e3c3285f224350c37aa2b1bec4ddc0e4cc8d54 100644 (file)
--- a/docs/en/api-reference/system/esp_https_ota.rst
+++ b/docs/en/api-reference/system/esp_https_ota.rst
@@ -29,6 +29,11 @@ Application Example
             return ESP_OK;
         }
 
+Signature Verification
+----------------------
+
+For additional security, signature of OTA firmware images can be verified. For that, refer :ref:`secure-ota-updates`
+
 API Reference
 -------------
 

diff --git a/docs/en/api-reference/system/ota.rst b/docs/en/api-reference/system/ota.rst
index 82533547364201b99725100bb802e9911211ac02..db02807280547136f53e629bd275cab2881bac12 100644 (file)
--- a/docs/en/api-reference/system/ota.rst
+++ b/docs/en/api-reference/system/ota.rst
@@ -32,6 +32,13 @@ The OTA data partition is two flash sectors (0x2000 bytes) in size, to prevent p
 while it is being written. Sectors are independently erased and written with matching data, and if they disagree a
 counter field is used to determine which sector was written more recently.
 
+.. _secure-ota-updates:
+
+Secure OTA Updates Without Secure boot
+--------------------------------------
+
+The verification of signed OTA updates can be performed even without enabling hardware secure boot. For doing so, refer :ref:`signed-app-verify`
+
 See also
 --------
 

diff --git a/docs/en/security/secure-boot.rst b/docs/en/security/secure-boot.rst
index d03a614d53f9f607eb516df88d2ef1a1b8613fd4..713fbfe44e8e72b12dbcf591692bb0916118bdad 100644 (file)
--- a/docs/en/security/secure-boot.rst
+++ b/docs/en/security/secure-boot.rst
@@ -146,6 +146,8 @@ openssl ecparam -name prime256v1 -genkey -noout -out my_secure_boot_signing_key.
 
 Remember that the strength of the secure boot system depends on keeping the signing key private.
 
+.. _remote-sign-image:
+
 Remote Signing of Images
 ------------------------
 
@@ -253,10 +255,39 @@ Keyfile is the 32 byte raw secure boot key for the device. To flash this digest
 
   esptool.py write_flash 0x0 bootloader-digest.bin
 
-
 .. _secure-boot-and-flash-encr:
 
 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.
+
+.. _signed-app-verify:
+
+Signed App Verification Without Hardware Secure Boot
+----------------------------------------------------
+
+The integrity of apps can be checked even without enabling the hardware secure boot option. This option uses the same app signature scheme as hardware secure
+boot, but unlike hardware secure boot it does not prevent the bootloader from being physically updated. This means that the device can be secured
+against remote network access, but not physical access. Compared to using hardware Secure Boot this option is much simpler to implement. See :ref:`signed-app-verify-howto` for step by step instructions.
+
+An app can be verified on update and, optionally, be verified on boot.
+
+- Verification on update: When enabled, the signature is automatically checked whenever the esp_ota_ops.h APIs are used for OTA updates. If hardware secure boot is enabled, this option is always enabled and cannot be disabled. If hardware secure boot is not enabled, this option still adds significant security against network-based attackers by preventing spoofing of OTA updates.
+
+- Verification on boot: When enabled, the bootloader will be compiled with code to verify that an app is signed before booting it. If hardware secure boot is enabled, this option is always enabled and cannot be disabled. If hardware secure boot is not enabled, this option doesn't add significant security by itself so most users will want to leave it disabled.
+
+.. _signed-app-verify-howto:
+
+How To Enable Signed App Verification
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Run ``make menuconfig`` -> Security features -> Enable "Require signed app images"
+
+2. "Bootloader verifies app signatures" can be enabled, which verifies app on boot.
+
+3. By default, "Sign binaries during build" will be enabled on selecting "Require signed app images" option, which will sign binary files as a part of build process. The file named in "Secure boot private signing key" will be used to sign the image.
+
+4. If you disable "Sign binaries during build" option then you'll have to enter path of a public key file used to verify signed images in "Secure boot public signature verification key".
+   In this case, private signing key should be generated by following instructions in :ref:`secure-boot-generate-key`; public verification key and signed image should be generated by following instructions in :ref:`remote-sign-image`.
+