espressif: add downgrade prevention feature

Signed-off-by: Almir Okato <almir.okato@espressif.com>

Author: almir-okato

boot/espressif/hal/include/mcuboot_config/mcuboot_config.h

@@ -84,6 +84,18 @@
  */
 #define MCUBOOT_VALIDATE_PRIMARY_SLOT
 
+#ifdef CONFIG_ESP_DOWNGRADE_PREVENTION
+#define MCUBOOT_DOWNGRADE_PREVENTION 1
+/* MCUBOOT_DOWNGRADE_PREVENTION_SECURITY_COUNTER is used later as bool value so it is
+ * always defined, (unlike MCUBOOT_DOWNGRADE_PREVENTION which is only used in
+ * preprocessor condition and my be not defined) */
+#  ifdef CONFIG_ESP_DOWNGRADE_PREVENTION_SECURITY_COUNTER
+#    define MCUBOOT_DOWNGRADE_PREVENTION_SECURITY_COUNTER 1
+#  else
+#    define MCUBOOT_DOWNGRADE_PREVENTION_SECURITY_COUNTER 0
+#  endif
+#endif
+
 /*
  * Flash abstraction
  */

boot/espressif/port/esp32/bootloader.conf

@@ -12,6 +12,12 @@ CONFIG_ESP_MCUBOOT_WDT_ENABLE=y
 CONFIG_ESP_SCRATCH_OFFSET=0x210000
 CONFIG_ESP_SCRATCH_SIZE=0x40000
 
+# When enabled, prevents updating image to an older version
+# CONFIG_ESP_DOWNGRADE_PREVENTION=y
+# This option makes downgrade prevention rely also on security
+# counter (defined using imgtool) instead of only image version
+# CONFIG_ESP_DOWNGRADE_PREVENTION_SECURITY_COUNTER=y
+
 # Enables the MCUboot Serial Recovery, that allows the use of
 # MCUMGR to upload a firmware through the serial port
 # CONFIG_ESP_MCUBOOT_SERIAL=y

boot/espressif/port/esp32c3/bootloader.conf

@@ -12,6 +12,12 @@ CONFIG_ESP_MCUBOOT_WDT_ENABLE=y
 CONFIG_ESP_SCRATCH_OFFSET=0x210000
 CONFIG_ESP_SCRATCH_SIZE=0x40000
 
+# When enabled, prevents updating image to an older version
+# CONFIG_ESP_DOWNGRADE_PREVENTION=y
+# This option makes downgrade prevention rely also on security
+# counter (defined using imgtool) instead of only image version
+# CONFIG_ESP_DOWNGRADE_PREVENTION_SECURITY_COUNTER=y
+
 # Enables the MCUboot Serial Recovery, that allows the use of
 # MCUMGR to upload a firmware through the serial port
 # CONFIG_ESP_MCUBOOT_SERIAL=y

boot/espressif/port/esp32s2/bootloader.conf

@@ -12,6 +12,12 @@ CONFIG_ESP_MCUBOOT_WDT_ENABLE=y
 CONFIG_ESP_SCRATCH_OFFSET=0x210000
 CONFIG_ESP_SCRATCH_SIZE=0x40000
 
+# When enabled, prevents updating image to an older version
+# CONFIG_ESP_DOWNGRADE_PREVENTION=y
+# This option makes downgrade prevention rely also on security
+# counter (defined using imgtool) instead of only image version
+# CONFIG_ESP_DOWNGRADE_PREVENTION_SECURITY_COUNTER=y
+
 # Enables the MCUboot Serial Recovery, that allows the use of
 # MCUMGR to upload a firmware through the serial port
 # CONFIG_ESP_MCUBOOT_SERIAL=y

boot/espressif/port/esp32s3/bootloader.conf

@@ -12,6 +12,12 @@ CONFIG_ESP_MCUBOOT_WDT_ENABLE=y
 CONFIG_ESP_SCRATCH_OFFSET=0x210000
 CONFIG_ESP_SCRATCH_SIZE=0x40000
 
+# When enabled, prevents updating image to an older version
+# CONFIG_ESP_DOWNGRADE_PREVENTION=y
+# This option makes downgrade prevention rely also on security
+# counter (defined using imgtool) instead of only image version
+# CONFIG_ESP_DOWNGRADE_PREVENTION_SECURITY_COUNTER=y
+
 # Enables multi image, if it is not defined, it is assumed
 # only one updatable image
 # CONFIG_ESP_IMAGE_NUMBER=2

docs/readme-espressif.md

@@ -130,6 +130,28 @@ For signing with a crypto key and guarantee the authenticity of the image being
 esptool.py -p <PORT> -b <BAUD> --before default_reset --after hard_reset --chip <TARGET>  write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <SLOT_OFFSET> <SIGNED_BIN>
 ```
 
+# [Downgrade prevention](#downgrade-prevention)
+
+Downgrade prevention (avoid updating of images to an older version) can be enabled using the following configuration:
+
+```
+CONFIG_ESP_DOWNGRADE_PREVENTION=y
+```
+
+MCUboot will then verify and compare the new image version number with the current one before perform an update swap.
+
+Version number is added to the image when signing it with `imgtool` (`-v` parameter, e.g. `-v 1.0.0`).
+
+### [Downgrade prevention with security counter](#downgrade-prevention-with-security-counter)
+
+It is also possible to rely on a security counter, also added to the image when signing with `imgtool` (`-s` parameter), apart from version number. This allows image downgrade at some extent, since any update must have greater or equal security counter value. Enable using the following configuration:
+
+```
+CONFIG_ESP_DOWNGRADE_PREVENTION_SECURITY_COUNTER=y
+```
+
+E.g.: if the current image was signed using `-s 1` parameter, an eventual update image must have been signed using security counter `-s 1` or greater.
+
 # [Security Chain on Espressif port](#security-chain-on-espressif-port)
 
 [MCUboot encrypted images](encrypted_images.md) do not provide full code confidentiality when only external storage is available (see [Threat model](encrypted_images.md#threat-model)) since by MCUboot design the image in Primary Slot, from where the image is executed, is stored plaintext.