Merge branch 'feature/secure_boot_esp32s2_v4.2' into 'release/v4.2'

Feature/secure boot esp32s2 v4.2

See merge request espressif/esp-idf!9958

components/app_update/esp_ota_ops.c

@@ -41,6 +41,12 @@
 #include "esp_system.h"
 #include "esp_efuse.h"
 
+#ifdef CONFIG_IDF_TARGET_ESP32
+#include "esp32/rom/crc.h"
+#elif CONFIG_IDF_TARGET_ESP32S2
+#include "esp32s2/rom/crc.h"
+#include "esp32s2/rom/secure_boot.h"
+#endif
 
 #define SUB_TYPE_ID(i) (i & 0x0F)
 
@@ -858,3 +864,24 @@ esp_err_t esp_ota_erase_last_boot_app_partition(void)
 
     return ESP_OK;
 }
+
+#if CONFIG_IDF_TARGET_ESP32S2 && CONFIG_SECURE_BOOT_V2_ENABLED
+esp_err_t esp_ota_revoke_secure_boot_public_key(esp_ota_secure_boot_public_key_index_t index) {
+
+    if (!esp_secure_boot_enabled()) {
+        ESP_LOGE(TAG, "Secure boot v2 has not been enabled.");
+        return ESP_FAIL;
+    }
+
+    if (index != SECURE_BOOT_PUBLIC_KEY_INDEX_0 &&
+         index != SECURE_BOOT_PUBLIC_KEY_INDEX_1 &&
+         index != SECURE_BOOT_PUBLIC_KEY_INDEX_2) {
+        ESP_LOGE(TAG, "Invalid Index found for public key revocation %d.", index);
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    ets_secure_boot_revoke_public_key_digest(index);
+    ESP_LOGI(TAG, "Revoked signature block %d.", index);
+    return ESP_OK;
+}
+#endif

components/app_update/include/esp_ota_ops.h

@@ -299,6 +299,34 @@ esp_err_t esp_ota_erase_last_boot_app_partition(void);
  */
 bool esp_ota_check_rollback_is_possible(void);
 
+#if CONFIG_IDF_TARGET_ESP32S2 && (CONFIG_SECURE_BOOT_V2_ENABLED || __DOXYGEN__)
+
+/**
+ * Secure Boot V2 public key indexes.
+ */
+typedef enum {
+    SECURE_BOOT_PUBLIC_KEY_INDEX_0,     /*!< Points to the 0th index of the Secure Boot v2 public key */
+    SECURE_BOOT_PUBLIC_KEY_INDEX_1,     /*!< Points to the 1st index of the Secure Boot v2 public key */
+    SECURE_BOOT_PUBLIC_KEY_INDEX_2      /*!< Points to the 2nd index of the Secure Boot v2 public key */
+} esp_ota_secure_boot_public_key_index_t;
+
+/**
+ * @brief Revokes the old signature digest. To be called in the application after the rollback logic.
+ *
+ * Relevant for Secure boot v2 on ESP32-S2 where upto 3 key digests can be stored (Key #N-1, Key #N, Key #N+1).
+ * When key #N-1 used to sign an app is invalidated, an OTA update is to be sent with an app signed with key #N-1 & Key #N.
+ * After successfully booting the OTA app should call this function to revoke Key #N-1.
+ *
+ * @param index - The index of the signature block to be revoked
+ *
+ * @return
+ *        - ESP_OK: If revocation is successful.
+ *        - ESP_ERR_INVALID_ARG: If the index of the public key to be revoked is incorrect.
+ *        - ESP_FAIL: If secure boot v2 has not been enabled.
+ */
+esp_err_t esp_ota_revoke_secure_boot_public_key(esp_ota_secure_boot_public_key_index_t index);
+#endif /* CONFIG_IDF_TARGET_ESP32S2 */
+
 #ifdef __cplusplus
 }
 #endif

components/bootloader/Kconfig.projbuild

@@ -369,7 +369,7 @@ menu "Security features"
 
         config SECURE_SIGNED_APPS_RSA_SCHEME
             bool "RSA"
-            depends on ESP32_REV_MIN_3 && SECURE_BOOT_V2_ENABLED
+            depends on (ESP32_REV_MIN_3 || IDF_TARGET_ESP32S2) && SECURE_BOOT_V2_ENABLED
             help
                 Appends the RSA-3072 based Signature block to the application.
                 Refer to <Secure Boot Version 2 documentation link> before enabling.
@@ -433,7 +433,9 @@ menu "Security features"
 
         config SECURE_BOOT_V2_ENABLED
             bool "Enable Secure Boot version 2"
-            depends on ESP32_REV_MIN_3
+            depends on ESP32_REV_MIN_3 || IDF_TARGET_ESP32S2
+            select SECURE_ENABLE_SECURE_ROM_DL_MODE if IDF_TARGET_ESP32S2 && !SECURE_INSECURE_ALLOW_DL_MODE
+            select SECURE_DISABLE_ROM_DL_MODE if ESP32_REV_MIN_3 && !SECURE_INSECURE_ALLOW_DL_MODE
             help
                 Build a bootloader which enables Secure Boot version 2 on first boot.
                 Refer to Secure Boot V2 section of the ESP-IDF Programmer's Guide for this version before enabling.
@@ -667,6 +669,19 @@ menu "Security features"
                 key digest, causing an immediate denial of service and possibly allowing an additional fault
                 injection attack to bypass the signature protection.
 
+        config SECURE_INSECURE_ALLOW_DL_MODE
+            bool "Don't automatically restrict UART download mode"
+            depends on SECURE_BOOT_INSECURE && SECURE_BOOT_V2_ENABLED
+            default N
+            help
+                By default, enabling either flash encryption in release mode or secure boot will automatically
+                disable UART download mode on ESP32 ECO3, or enable secure download mode on newer chips.
+                This is recommended to reduce the attack surface of the chip.
+
+                To allow the full UART download mode to stay enabled, enable this option and ensure
+                the options SECURE_DISABLE_ROM_DL_MODE and SECURE_ENABLE_SECURE_ROM_DL_MODE are disabled as applicable.
+                This is not recommended.
+
         config SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC
             bool "Leave UART bootloader encryption enabled"
             depends on SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT

components/bootloader/subproject/CMakeLists.txt

@@ -92,15 +92,15 @@ endif()
 
 if(CONFIG_SECURE_BOOT_V2_ENABLED)
     if(CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES)
-        get_filename_component(secure_boot_signing_key 
+        get_filename_component(secure_boot_signing_key
             "${SECURE_BOOT_SIGNING_KEY}" ABSOLUTE BASE_DIR "${project_dir}")
 
         if(NOT EXISTS "${secure_boot_signing_key}")
-            message(FATAL_ERROR
-                "Secure Boot Signing Key Not found."
-                "\nGenerate the Secure Boot V2 RSA-PSS 3072 Key."
-                "\nTo generate one, you can use this command:"
-                "\n\t${espsecurepy} generate_signing_key --version 2 ${SECURE_BOOT_SIGNING_KEY}")
+        message(FATAL_ERROR
+            "Secure Boot Signing Key Not found."
+            "\nGenerate the Secure Boot V2 RSA-PSS 3072 Key."
+            "\nTo generate one, you can use this command:"
+            "\n\t${espsecurepy} generate_signing_key --version 2 ${SECURE_BOOT_SIGNING_KEY}")
         endif()
 
         set(bootloader_unsigned_bin "bootloader-unsigned.bin")
@@ -117,7 +117,7 @@ if(CONFIG_SECURE_BOOT_V2_ENABLED)
     else()
         add_custom_command(OUTPUT ".signed_bin_timestamp"
         VERBATIM
-        COMMENT "Bootloader generated but not signed")    
+        COMMENT "Bootloader generated but not signed")
     endif()
 
     add_custom_target (gen_signed_bootloader ALL DEPENDS "${build_dir}/.signed_bin_timestamp")
@@ -166,6 +166,24 @@ elseif(CONFIG_SECURE_BOOTLOADER_REFLASHABLE)
             "* Not recommended to re-use the same secure boot keyfile on multiple production devices."
         DEPENDS gen_secure_bootloader_key gen_bootloader_digest_bin
         VERBATIM)
+elseif(CONFIG_SECURE_BOOT_V2_ENABLED AND CONFIG_IDF_TARGET_ESP32S2)
+    add_custom_command(TARGET bootloader.elf POST_BUILD
+    COMMAND ${CMAKE_COMMAND} -E echo
+        "=============================================================================="
+    COMMAND ${CMAKE_COMMAND} -E echo
+        "Bootloader built. Secure boot enabled, so bootloader not flashed automatically."
+    COMMAND ${CMAKE_COMMAND} -E echo
+        "To sign the bootloader with additional private keys."
+    COMMAND ${CMAKE_COMMAND} -E echo
+        "\t${espsecurepy} sign_data -k secure_boot_signing_key2.pem -v 2 --append_signatures -o signed_bootloader.bin build/bootloader/bootloader.bin"
+    COMMAND ${CMAKE_COMMAND} -E echo
+        "Secure boot enabled, so bootloader not flashed automatically."
+    COMMAND ${CMAKE_COMMAND} -E echo
+        "\t${esptoolpy_write_flash} ${BOOTLOADER_OFFSET} ${CMAKE_BINARY_DIR}/bootloader.bin"
+    COMMAND ${CMAKE_COMMAND} -E echo
+        "=============================================================================="
+    DEPENDS gen_signed_bootloader
+    VERBATIM)
 elseif(CONFIG_SECURE_BOOT_V2_ENABLED)
     add_custom_command(TARGET bootloader.elf POST_BUILD
     COMMAND ${CMAKE_COMMAND} -E echo

components/bootloader/subproject/main/ld/esp32s2/bootloader.ld

@@ -5,9 +5,9 @@
 
 MEMORY
 {
-  iram_seg (RWX) :                  org = 0x40050000, len = 0x4000  /* 16KB, SRAM Block_14 */
-  iram_loader_seg (RWX) :           org = 0x40054000, len = 0x4000  /* 16KB, SRAM Block_15 */
-  dram_seg (RW) :                   org = 0x3FFE8000, len = 0x2800  /* 10KB, Top of SRAM Block_16, and before ROM data and stack */
+  iram_seg (RWX) :                  org = 0x4004c000, len = 0x4000  /* SRAM Block 13 */
+  iram_loader_seg (RWX) :           org = 0x40050000, len = 0x6000  /* SRAM Block 14 & part of 15 */
+  dram_seg (RW) :                   org = 0x3FFE6000, len = 0x4B00  /* Part SRAM Blocks 15 & 16, ROM static buffer starts at end of this region (reclaimed after app runs) */
 }
 
 /*  Default entry point:  */

components/bootloader_support/src/bootloader_utility.c

@@ -821,6 +821,7 @@ void bootloader_debug_buffer(const void *buffer, size_t length, const char *labe
 
 esp_err_t bootloader_sha256_flash_contents(uint32_t flash_offset, uint32_t len, uint8_t *digest)
 {
+
     if (digest == NULL) {
         return ESP_ERR_INVALID_ARG;
     }
@@ -837,7 +838,7 @@ esp_err_t bootloader_sha256_flash_contents(uint32_t flash_offset, uint32_t len,
     while (len > 0) {
         uint32_t mmu_page_offset = ((flash_offset & MMAP_ALIGNED_MASK) != 0) ? 1 : 0; /* Skip 1st MMU Page if it is already populated */
         uint32_t partial_image_len = MIN(len, ((mmu_free_pages_count - mmu_page_offset) * SPI_FLASH_MMU_PAGE_SIZE)); /* Read the image that fits in the free MMU pages */
-        
+
         const void * image = bootloader_mmap(flash_offset, partial_image_len);
         if (image == NULL) {
             bootloader_sha256_finish(sha_handle, NULL);

components/bootloader_support/src/esp32/secure_boot.c

@@ -319,7 +319,7 @@ esp_err_t esp_secure_boot_v2_permanently_enable(const esp_image_metadata_t *imag
     uint32_t dis_reg = REG_READ(EFUSE_BLK0_RDATA0_REG);
     bool efuse_key_read_protected = dis_reg & EFUSE_RD_DIS_BLK2;
     bool efuse_key_write_protected = dis_reg & EFUSE_WR_DIS_BLK2;
-    if (efuse_key_write_protected == false 
+    if (efuse_key_write_protected == false
         && efuse_key_read_protected == false
         && REG_READ(EFUSE_BLK2_RDATA0_REG) == 0
         && REG_READ(EFUSE_BLK2_RDATA1_REG) == 0

components/bootloader_support/src/esp32s2/secure_boot.c

@@ -11,43 +11,315 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-#include "esp_secure_boot.h"
+#include <string.h>
+
 #include "esp_log.h"
+#include "esp_secure_boot.h"
+#include "soc/efuse_reg.h"
+
+#include "bootloader_flash.h"
+#include "bootloader_sha.h"
+#include "bootloader_utility.h"
+
+#include "esp32s2/rom/crc.h"
+#include "esp_efuse.h"
+#include "esp_efuse_table.h"
+
+#include "esp32s2/rom/efuse.h"
 #include "esp32s2/rom/secure_boot.h"
 
-static const char *TAG = "secure_boot";
+static const char *TAG = "secure_boot_v2";
+#define ALIGN_UP(num, align) (((num) + ((align) - 1)) & ~((align) - 1))
 
-esp_err_t esp_secure_boot_permanently_enable(void)
+#define SIG_BLOCK_MAGIC_BYTE 0xe7
+#define CRC_SIGN_BLOCK_LEN 1196
+#define SIG_BLOCK_PADDING 4096
+
+#define DIGEST_LEN 32
+
+/* A signature block is valid when it has correct magic byte, crc and image digest. */
+static esp_err_t validate_signature_block(const ets_secure_boot_sig_block_t *block, int block_num, const uint8_t *image_digest)
 {
-    uint8_t hash[32];
-
-    if (ets_efuse_secure_boot_enabled())
-    {
-        ESP_LOGI(TAG, "secure boot is already enabled, continuing..");
+    uint32_t crc = crc32_le(0, (uint8_t *)block, CRC_SIGN_BLOCK_LEN);
+    if (block->magic_byte != SIG_BLOCK_MAGIC_BYTE) {
+        // All signature blocks have been parsed, no new signature block present.
+        ESP_LOGD(TAG, "Signature block(%d) invalid/absent.", block_num);
+        return ESP_FAIL;
+    }
+    if (block->block_crc != crc) {
+        ESP_LOGE(TAG, "Magic byte correct but incorrect crc.");
+        return ESP_FAIL;
+    }
+    if (memcmp(image_digest, block->image_digest, DIGEST_LEN)) {
+        ESP_LOGE(TAG, "Magic byte & CRC correct but incorrect image digest.");
+        return ESP_FAIL;
+    } else {
+        ESP_LOGD(TAG, "valid signature block(%d) found", block_num);
         return ESP_OK;
     }
 
-    ESP_LOGI(TAG, "Verifying bootloader signature...\n");
-    int r = ets_secure_boot_verify_bootloader(hash, false);
-    if (r != ESP_OK) {
-        ESP_LOGE(TAG, "Failed to verify bootloader signature");
-        return r;
+    return ESP_FAIL;
+}
+
+/* Structure to hold public key digests calculated from the signature blocks of a single image.
+
+   Each image can have one or more signature blocks (up to SECURE_BOOT_NUM_BLOCKS). Each signature block
+   includes a public key.
+
+   Different to the ROM ets_secure_boot_key_digests_t structure which holds pointers to eFuse data with digests,
+   in this data structure the digest data is included.
+*/
+typedef struct {
+    uint8_t key_digests[SECURE_BOOT_NUM_BLOCKS][DIGEST_LEN];
+    unsigned num_digests; /* Number of valid digests, starting at index 0 */
+} image_sig_public_key_digests_t;
+
+/* Generates the public key digests of the valid public keys in an image's
+   signature block, verifies each signature, and stores the key digests in the
+   public_key_digests structure.
+
+   @param flash_offset Image offset in flash
+   @param flash_size Image size in flash (not including signature block)
+   @param[out] public_key_digests Pointer to structure to hold the key digests for valid sig blocks
+
+
+   Note that this function doesn't read any eFuses, so it doesn't know if the
+   keys are ultimately trusted by the hardware or not
+
+   @return - ESP_OK if no signatures failed to verify, or if no valid signature blocks are found at all.
+           - ESP_FAIL if there's a valid signature block that doesn't verify using the included public key (unexpected!)
+*/
+static esp_err_t s_calculate_image_public_key_digests(uint32_t flash_offset, uint32_t flash_size, image_sig_public_key_digests_t *public_key_digests)
+{
+    esp_err_t ret;
+    uint8_t image_digest[DIGEST_LEN] = {0};
+    uint8_t __attribute__((aligned(4))) key_digest[DIGEST_LEN] = {0};
+    size_t sig_block_addr = flash_offset + ALIGN_UP(flash_size, FLASH_SECTOR_SIZE);
+
+    ESP_LOGD(TAG, "calculating public key digests for sig blocks of image offset 0x%x (sig block offset 0x%x)", flash_offset, sig_block_addr);
+
+    bzero(public_key_digests, sizeof(image_sig_public_key_digests_t));
+
+    ret = bootloader_sha256_flash_contents(flash_offset, sig_block_addr - flash_offset, image_digest);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "error generating image digest, %d", ret);
+        return ret;
     }
 
-    esp_efuse_batch_write_begin(); /* Batch all efuse writes at the end of this function */
+    ESP_LOGD(TAG, "reading signatures");
+    const ets_secure_boot_signature_t *signatures = bootloader_mmap(sig_block_addr, sizeof(ets_secure_boot_signature_t));
+    if (signatures == NULL) {
+        ESP_LOGE(TAG, "bootloader_mmap(0x%x, 0x%x) failed", sig_block_addr, sizeof(ets_secure_boot_signature_t));
+        return ESP_FAIL;
+    }
+
+    for (int i = 0; i < SECURE_BOOT_NUM_BLOCKS; i++) {
+        const ets_secure_boot_sig_block_t *block = &signatures->block[i];
+
+        ret = validate_signature_block(block, i, image_digest);
+        if (ret != ESP_OK) {
+            ret = ESP_OK;  // past the last valid signature block
+            break;
+        }
+
+        /* Generating the SHA of the public key components in the signature block */
+        bootloader_sha256_handle_t sig_block_sha;
+        sig_block_sha = bootloader_sha256_start();
+        bootloader_sha256_data(sig_block_sha, &block->key, sizeof(block->key));
+        bootloader_sha256_finish(sig_block_sha, key_digest);
+
+        // Check we can verify the image using this signature and this key
+        uint8_t temp_verified_digest[DIGEST_LEN];
+        bool verified = ets_rsa_pss_verify(&block->key, block->signature, image_digest, temp_verified_digest);
+
+        if (!verified) {
+            /* We don't expect this: the signature blocks before we enable secure boot should all be verifiable or invalid,
+               so this is a fatal error
+            */
+            ret = ESP_FAIL;
+            ESP_LOGE(TAG, "Secure boot key (%d) verification failed.", i);
+            break;
+        }
+        ESP_LOGD(TAG, "Signature block (%d) is verified", i);
+        /* Copy the key digest to the buffer provided by the caller */
+        memcpy((void *)public_key_digests->key_digests[i], key_digest, DIGEST_LEN);
+        public_key_digests->num_digests++;
+    }
+
+    if (ret == ESP_OK && public_key_digests->num_digests > 0) {
+        ESP_LOGI(TAG, "Digests successfully calculated, %d valid signatures (image offset 0x%x)",
+                 public_key_digests->num_digests, flash_offset);
+    }
+
+    bootloader_munmap(signatures);
+    return ret;
+}
+
+esp_err_t esp_secure_boot_v2_permanently_enable(const esp_image_metadata_t *image_data)
+{
+    ESP_LOGI(TAG, "enabling secure boot v2 - ESP32-S2...");
+
+    if (esp_secure_boot_enabled()) {
+        ESP_LOGI(TAG, "secure boot v2 is already enabled, continuing..");
+        return ESP_OK;
+    }
+
+    esp_err_t ret;
+    /* Verify the bootloader */
+    esp_image_metadata_t bootloader_data = { 0 };
+    ret = esp_image_verify_bootloader_data(&bootloader_data);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "bootloader image appears invalid! error %d", ret);
+        return ret;
+    }
+
+    /* Check if secure boot digests are present */
+    bool has_secure_boot_digest = ets_efuse_find_purpose(ETS_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST0, NULL);
+    has_secure_boot_digest |= ets_efuse_find_purpose(ETS_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST1, NULL);
+    has_secure_boot_digest |= ets_efuse_find_purpose(ETS_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST2, NULL);
+    ESP_LOGI(TAG, "Secure boot digests %s", has_secure_boot_digest ? "already present":"absent, generating..");
+
+    ets_efuse_clear_program_registers();
+    if (!has_secure_boot_digest) {
+        image_sig_public_key_digests_t boot_key_digests = {0};
+        image_sig_public_key_digests_t app_key_digests = {0};
+
+        /* Generate the bootloader public key digests */
+        ret = s_calculate_image_public_key_digests(bootloader_data.start_addr, bootloader_data.image_len - SIG_BLOCK_PADDING, &boot_key_digests);
+        if (ret != ESP_OK) {
+            ESP_LOGE(TAG, "Bootloader signature block is invalid");
+            return ret;
+        }
+
+        if (boot_key_digests.num_digests == 0) {
+            ESP_LOGE(TAG, "No valid bootloader signature blocks found.");
+            return ESP_FAIL;
+        }
+        ESP_LOGI(TAG, "%d signature block(s) found appended to the bootloader.", boot_key_digests.num_digests);
+
+        int unused_key_slots = ets_efuse_count_unused_key_blocks();
+        if (boot_key_digests.num_digests > unused_key_slots) {
+            ESP_LOGE(TAG, "Bootloader signatures(%d) more than available key slots(%d).", boot_key_digests.num_digests, unused_key_slots);
+            return ESP_FAIL;
+        }
+
+        for (int i = 0; i < boot_key_digests.num_digests; i++) {
+            ets_efuse_block_t block;
+            const uint32_t secure_boot_key_purpose[SECURE_BOOT_NUM_BLOCKS] = { ETS_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST0,
+                                ETS_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST1, ETS_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST2 };
+
+            block = ets_efuse_find_unused_key_block();
+            if (block == ETS_EFUSE_BLOCK_MAX) {
+                ESP_LOGE(TAG, "No more unused key blocks available.");
+                return ESP_FAIL;
+            }
+
+            int r = ets_efuse_write_key(block, secure_boot_key_purpose[i], boot_key_digests.key_digests[i], DIGEST_LEN);
+            if (r != 0) {
+                ESP_LOGE(TAG, "Failed to write efuse block %d with purpose %d. Can't continue.", block, secure_boot_key_purpose[i]);
+                return ESP_FAIL;
+            }
+
+            // Note: write key will write protect both the block and the purpose eFuse, always
+        }
+
+        /* Generate the application public key digests */
+        ret = s_calculate_image_public_key_digests(image_data->start_addr, image_data->image_len - SIG_BLOCK_PADDING, &app_key_digests);
+        if (ret != ESP_OK) {
+            ESP_LOGE(TAG, "App signature block is invalid.");
+            return ret;
+        }
+
+        if (app_key_digests.num_digests == 0) {
+            ESP_LOGE(TAG, "No valid applications signature blocks found.");
+            return ESP_FAIL;
+        }
+
+        ESP_LOGI(TAG, "%d signature block(s) found appended to the app.", app_key_digests.num_digests);
+        if (app_key_digests.num_digests > boot_key_digests.num_digests) {
+            ESP_LOGW(TAG, "App has %d signature blocks but bootloader only has %d. Some keys missing from bootloader?");
+        }
+
+        /* Confirm if at least one public key from the application matches a public key in the bootloader
+           (Also, ensure if that public revoke bit is not set for the matched key) */
+        bool match = false;
+        const uint32_t revoke_bits[SECURE_BOOT_NUM_BLOCKS] = { EFUSE_SECURE_BOOT_KEY_REVOKE0,
+                                EFUSE_SECURE_BOOT_KEY_REVOKE1, EFUSE_SECURE_BOOT_KEY_REVOKE2 };
+
+        for (int i = 0; i < boot_key_digests.num_digests; i++) {
+
+            if (REG_GET_BIT(EFUSE_RD_REPEAT_DATA1_REG, revoke_bits[i])) {
+                ESP_LOGI(TAG, "Key block(%d) has been revoked.", i);
+                continue; // skip if the key block is revoked
+            }
+
+            for (int j = 0; j < app_key_digests.num_digests; j++) {
+                if (!memcmp(boot_key_digests.key_digests[i], app_key_digests.key_digests[j], DIGEST_LEN)) {
+                    ESP_LOGI(TAG, "Application key(%d) matches with bootloader key(%d).", j, i);
+                    match = true;
+                }
+            }
+        }
+
+        if (match == false) {
+            ESP_LOGE(TAG, "No application key digest matches the bootloader key digest.");
+            return ESP_FAIL;
+        }
+
+        /* Revoke the empty signature blocks */
+        if (boot_key_digests.num_digests < SECURE_BOOT_NUM_BLOCKS) {
+            /* The revocation index can be 0, 1, 2. Bootloader count can be 1,2,3. */
+            for (uint8_t i = boot_key_digests.num_digests; i < SECURE_BOOT_NUM_BLOCKS; i++) {
+                ESP_LOGI(TAG, "Revoking empty key digest slot (%d)...", i);
+                ets_secure_boot_revoke_public_key_digest(i);
+            }
+        }
+    }
+
+    esp_err_t err = esp_efuse_batch_write_begin();
+    if (err != ESP_OK) {
+        ESP_LOGI(TAG, "Error batch programming security eFuses.");
+        return err;
+    }
+
+    __attribute__((unused)) static const uint8_t enable = 1;
 
-    esp_efuse_write_field_bit(ESP_EFUSE_SECURE_BOOT_EN);
     esp_efuse_write_field_bit(ESP_EFUSE_DIS_BOOT_REMAP);
     esp_efuse_write_field_bit(ESP_EFUSE_DIS_LEGACY_SPI_BOOT);
 
-    // TODO: also disable JTAG here, etc
+#ifdef CONFIG_SECURE_ENABLE_SECURE_ROM_DL_MODE
+    ESP_LOGI(TAG, "Enabling Security download mode...");
+    esp_efuse_write_field_bit(ESP_EFUSE_ENABLE_SECURITY_DOWNLOAD);
+#else
+    ESP_LOGW(TAG, "Not enabling Security download mode - SECURITY COMPROMISED");
+#endif
 
-    esp_err_t err = esp_efuse_batch_write_commit();
+#ifndef CONFIG_SECURE_BOOT_ALLOW_JTAG
+    ESP_LOGI(TAG, "Disable hardware & software JTAG...");
+    esp_efuse_write_field_bit(ESP_EFUSE_HARD_DIS_JTAG);
+    esp_efuse_write_field_bit(ESP_EFUSE_SOFT_DIS_JTAG);
+#else
+    ESP_LOGW(TAG, "Not disabling JTAG - SECURITY COMPROMISED");
+#endif
 
-    if (err == ESP_OK) {
-        assert(ets_efuse_secure_boot_enabled());
-        ESP_LOGI(TAG, "Secure boot permanently enabled");
+#ifdef CONFIG_SECURE_BOOT_ENABLE_AGGRESSIVE_KEY_REVOKE
+    esp_efuse_write_field_bit(ESP_EFUSE_SECURE_BOOT_AGGRESSIVE_REVOKE);
+#endif
+
+    esp_efuse_write_field_bit(ESP_EFUSE_SECURE_BOOT_EN);
+
+    err = esp_efuse_batch_write_commit();
+    if (err != ESP_OK) {
+        ESP_LOGI(TAG, "Error programming security eFuses.");
+        return err;
     }
 
+#ifdef CONFIG_SECURE_BOOT_ENABLE_AGGRESSIVE_KEY_REVOKE
+    assert(ets_efuse_secure_boot_aggressive_revoke_enabled());
+#endif
+
+    assert(ets_efuse_secure_boot_enabled());
+    ESP_LOGI(TAG, "Secure boot permanently enabled");
+
     return ESP_OK;
 }

components/bootloader_support/src/esp32s2/secure_boot_signatures.c

@@ -13,29 +13,32 @@
 // limitations under the License.
 #include "sdkconfig.h"
 
+#include <string.h>
+#include "esp_fault.h"
 #include "bootloader_flash.h"
 #include "bootloader_sha.h"
+#include "bootloader_utility.h"
 #include "esp_log.h"
 #include "esp_image_format.h"
+#include "esp_secure_boot.h"
 #include "esp32s2/rom/secure_boot.h"
 
 static const char* TAG = "secure_boot";
 
 #define DIGEST_LEN 32
+#define ALIGN_UP(num, align) (((num) + ((align) - 1)) & ~((align) - 1))
 
 esp_err_t esp_secure_boot_verify_signature(uint32_t src_addr, uint32_t length)
 {
-    ets_secure_boot_key_digests_t trusted_keys = { 0 };
     uint8_t digest[DIGEST_LEN];
     uint8_t verified_digest[DIGEST_LEN] = { 0 }; /* Note: this function doesn't do any anti-FI checks on this buffer */
     const uint8_t *data;
 
     ESP_LOGD(TAG, "verifying signature src_addr 0x%x length 0x%x", src_addr, length);
 
-    if ((src_addr + length) % 4096 != 0) {
-        ESP_LOGE(TAG, "addr 0x%x length 0x%x doesn't end on a sector boundary", src_addr, length);
-        return ESP_ERR_INVALID_ARG;
-    }
+    /* Padding to round off the input to the nearest 4k boundary */
+    int padded_length = ALIGN_UP(length, FLASH_SECTOR_SIZE);
+    ESP_LOGD(TAG, "verifying src_addr 0x%x length", src_addr, padded_length);
 
     data = bootloader_mmap(src_addr, length + sizeof(struct ets_secure_boot_sig_block));
     if (data == NULL) {
@@ -43,23 +46,16 @@ esp_err_t esp_secure_boot_verify_signature(uint32_t src_addr, uint32_t length)
         return ESP_FAIL;
     }
 
-    // Calculate digest of main image
-#ifdef BOOTLOADER_BUILD
-    bootloader_sha256_handle_t handle = bootloader_sha256_start();
-    bootloader_sha256_data(handle, data, length);
-    bootloader_sha256_finish(handle, digest);
-#else
-    /* Use thread-safe esp-idf SHA function */
-    esp_sha(SHA2_256, data, length, digest);
-#endif
-
-    int r = ets_secure_boot_read_key_digests(&trusted_keys);
-
-    if (r == ETS_OK) {
-        const ets_secure_boot_signature_t *sig = (const ets_secure_boot_signature_t *)(data + length);
-        // TODO: calling this function in IDF app context is unsafe
-        r = ets_secure_boot_verify_signature(sig, digest, &trusted_keys, verified_digest);
+    /* Calculate digest of main image */
+    esp_err_t err = bootloader_sha256_flash_contents(src_addr, padded_length, digest);
+    if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Digest calculation failed 0x%x, 0x%x", src_addr, padded_length);
+        bootloader_munmap(data);
+        return err;
     }
+
+    const ets_secure_boot_signature_t *sig = (const ets_secure_boot_signature_t *)(data + length);
+    int r = esp_secure_boot_verify_rsa_signature_block(sig, digest, verified_digest);
     bootloader_munmap(data);
 
     return (r == ETS_OK) ? ESP_OK : ESP_FAIL;
@@ -68,15 +64,30 @@ esp_err_t esp_secure_boot_verify_signature(uint32_t src_addr, uint32_t length)
 esp_err_t esp_secure_boot_verify_rsa_signature_block(const ets_secure_boot_signature_t *sig_block, const uint8_t *image_digest, uint8_t *verified_digest)
 {
     ets_secure_boot_key_digests_t trusted_keys;
+    ets_secure_boot_key_digests_t trusted_key_copies[2];
+    ETS_STATUS r;
+    ets_secure_boot_status_t sb_result;
 
-    int r = ets_secure_boot_read_key_digests(&trusted_keys);
-    if (r != 0) {
-        ESP_LOGE(TAG, "No trusted key digests were found in efuse!");
-    } else {
-        ESP_LOGD(TAG, "Verifying with RSA-PSS...");
-        // TODO: calling this function in IDF app context is unsafe
-        r = ets_secure_boot_verify_signature(sig_block, image_digest, &trusted_keys, verified_digest);
+    memset(&trusted_keys, 0, sizeof(ets_secure_boot_key_digests_t));
+    memset(trusted_key_copies, 0, 2 * sizeof(ets_secure_boot_key_digests_t));
+
+    if (!esp_secure_boot_enabled()) {
+        return ESP_OK;
     }
 
-    return (r == 0) ? ESP_OK : ESP_ERR_IMAGE_INVALID;
+    r = ets_secure_boot_read_key_digests(&trusted_keys);
+    if (r != ETS_OK) {
+        ESP_LOGI(TAG, "Could not read secure boot digests!");
+        return ESP_FAIL;
+    }
+
+    // Create the copies for FI checks (assuming result is ETS_OK, if it's not then it'll fail the fault check anyhow)
+    ets_secure_boot_read_key_digests(&trusted_key_copies[0]);
+    ets_secure_boot_read_key_digests(&trusted_key_copies[1]);
+    ESP_FAULT_ASSERT(memcmp(&trusted_keys, &trusted_key_copies[0], sizeof(ets_secure_boot_key_digests_t)) == 0);
+    ESP_FAULT_ASSERT(memcmp(&trusted_keys, &trusted_key_copies[1], sizeof(ets_secure_boot_key_digests_t)) == 0);
+
+    ESP_LOGI(TAG, "Verifying with RSA-PSS boot...");
+    sb_result = ets_secure_boot_verify_signature(sig_block, image_digest, &trusted_keys, verified_digest);
+    return (sb_result == SB_SUCCESS) ? ESP_OK : ESP_FAIL;
 }

components/bootloader_support/src/esp_image_format.c

@@ -275,7 +275,7 @@ static esp_err_t image_load(esp_image_load_mode_t mode, const esp_partition_pos_
        "only verify signature in bootloader" into the macro so it's tested multiple times.
      */
 #if CONFIG_SECURE_BOOT_V2_ENABLED
-    ESP_FAULT_ASSERT(memcmp(image_digest, verified_digest, HASH_LEN) == 0);
+    ESP_FAULT_ASSERT(!esp_secure_boot_enabled() || memcmp(image_digest, verified_digest, HASH_LEN) == 0);
 #else // Secure Boot V1 on ESP32, only verify signatures for apps not bootloaders
     ESP_FAULT_ASSERT(data->start_addr == ESP_BOOTLOADER_OFFSET || memcmp(image_digest, verified_digest, HASH_LEN) == 0);
 #endif
@@ -310,7 +310,7 @@ err:
     // Prevent invalid/incomplete data leaking out
     bzero(data, sizeof(esp_image_metadata_t));
     return err;
-    }
+}
 
 esp_err_t bootloader_load_image(const esp_partition_pos_t *part, esp_image_metadata_t *data)
 {

components/bootloader_support/src/idf/bootloader_sha.c

@@ -51,4 +51,5 @@ void bootloader_sha256_finish(bootloader_sha256_handle_t handle, uint8_t *digest
     }
     mbedtls_sha256_free(ctx);
     free(handle);
+    handle = NULL;
 }

components/bootloader_support/src/idf/secure_boot_signatures.c

@@ -27,6 +27,11 @@
 #include "mbedtls/ctr_drbg.h"
 #include <string.h>
 #include <sys/param.h>
+#include "esp_secure_boot.h"
+
+#ifdef CONFIG_IDF_TARGET_ESP32S2
+#include <esp32s2/rom/secure_boot.h>
+#endif
 
 #define DIGEST_LEN 32
 
@@ -142,6 +147,26 @@ static const char *TAG = "secure_boot_v2";
 #define ALIGN_UP(num, align) (((num) + ((align) - 1)) & ~((align) - 1))
 #define RSA_KEY_SIZE 384 /* RSA 3072 Bits */
 
+#if CONFIG_IDF_TARGET_ESP32S2
+inline static bool digest_matches(const void *trusted, const void *computed)
+{
+    if (trusted == NULL) {
+        return false;
+    }
+
+    // 'trusted' is probably a pointer to read-only efuse registers,
+    // which only support word reads. memcmp() cannot be guaranteed
+    // to do word reads, so we make a local copy here (we know that
+    // memcpy() will do word operations if it can).
+    uint8_t __attribute__((aligned(4))) trusted_local[ETS_DIGEST_LEN];
+    uint8_t __attribute__((aligned(4))) computed_local[ETS_DIGEST_LEN];
+
+    memcpy(trusted_local, trusted, ETS_DIGEST_LEN);
+    memcpy(computed_local, computed, ETS_DIGEST_LEN);
+    return memcmp(trusted_local, computed_local, ETS_DIGEST_LEN) == 0;
+}
+#endif /* CONFIG_IDF_TARGET_ESP32S2 */
+
 esp_err_t esp_secure_boot_verify_signature(uint32_t src_addr, uint32_t length)
 {
     uint8_t digest[DIGEST_LEN] = {0};
@@ -173,23 +198,19 @@ esp_err_t esp_secure_boot_verify_signature(uint32_t src_addr, uint32_t length)
 
 esp_err_t esp_secure_boot_verify_rsa_signature_block(const ets_secure_boot_signature_t *sig_block, const uint8_t *image_digest, uint8_t *verified_digest)
 {
-    int i = 0;
-
+    uint8_t i = 0;
 #if CONFIG_SECURE_BOOT_V2_ENABLED /* Verify key against efuse block */
-    uint8_t efuse_trusted_digest[DIGEST_LEN] = {0}, sig_block_trusted_digest[DIGEST_LEN] = {0};
-    memcpy(efuse_trusted_digest, (uint8_t *) EFUSE_BLK2_RDATA0_REG, sizeof(efuse_trusted_digest));
+    uint8_t sig_block_key_digest[SECURE_BOOT_NUM_BLOCKS][DIGEST_LEN] = {0};
 
     /* Note: in IDF verification we don't add any fault injection resistance, as we don't expect this to be called
        during boot-time verification. */
     memset(verified_digest, 0, DIGEST_LEN);
 
-    /* Generating the SHA of the public key components in the signature block */
-    bootloader_sha256_handle_t sig_block_sha;
-    sig_block_sha = bootloader_sha256_start();
-    bootloader_sha256_data(sig_block_sha, &sig_block->block[0].key, sizeof(sig_block->block[0].key));
-    bootloader_sha256_finish(sig_block_sha, (unsigned char *)sig_block_trusted_digest);
+#if CONFIG_IDF_TARGET_ESP32
+    uint8_t efuse_trusted_digest[DIGEST_LEN] = {0};
+    memcpy(efuse_trusted_digest, (uint8_t *) EFUSE_BLK2_RDATA0_REG, sizeof(efuse_trusted_digest));
 
-    if (memcmp(efuse_trusted_digest, sig_block_trusted_digest, DIGEST_LEN) != 0) {
+    if (memcmp(efuse_trusted_digest, sig_block_key_digest, DIGEST_LEN) != 0) {
         const uint8_t zeroes[DIGEST_LEN] = {0};
         /* Can't continue if secure boot is enabled, OR if a different digest is already written in efuse BLK2
 
@@ -200,7 +221,25 @@ esp_err_t esp_secure_boot_verify_rsa_signature_block(const ets_secure_boot_signa
             return ESP_FAIL;
         }
     }
-#endif
+#elif CONFIG_IDF_TARGET_ESP32S2
+    bool match = false;
+    ets_secure_boot_key_digests_t efuse_trusted_digest;
+    ETS_STATUS r;
+    r = ets_secure_boot_read_key_digests(&efuse_trusted_digest);
+    if (r != 0) {
+        ESP_LOGI(TAG, "Could not read secure boot digests!");
+        return ESP_FAIL;
+    }
+#endif /* CONFIG_IDF_TARGET_ESP32 */
+
+    /* Generating the SHA of the public key components in the signature block */
+    for (i = 0; i < SECURE_BOOT_NUM_BLOCKS; i++) {
+        bootloader_sha256_handle_t sig_block_sha;
+        sig_block_sha = bootloader_sha256_start();
+        bootloader_sha256_data(sig_block_sha, &sig_block->block[i].key, sizeof(sig_block->block[i].key));
+        bootloader_sha256_finish(sig_block_sha, (unsigned char *)sig_block_key_digest[i]);
+    }
+#endif /* CONFIG_SECURE_BOOT_V2_ENABLED */
 
     ESP_LOGI(TAG, "Verifying with RSA-PSS...");
     int ret = 0;
@@ -222,6 +261,19 @@ esp_err_t esp_secure_boot_verify_rsa_signature_block(const ets_secure_boot_signa
     }
 
     for (i = 0; i < SECURE_BOOT_NUM_BLOCKS; i++) {
+#if CONFIG_IDF_TARGET_ESP32S2
+        for (uint8_t j = 0; j < SECURE_BOOT_NUM_BLOCKS; j++) {
+            if (digest_matches(efuse_trusted_digest.key_digests[j], sig_block_key_digest[i])) {
+                ESP_LOGI(TAG, "eFuse key matches(%d) matches the application key(%d).", j, i);
+                match = true;
+                break;
+            }
+        }
+        if (match == false) {
+            continue; // Skip the public keys whose digests don't match.
+        }
+# endif
+
         const mbedtls_mpi N = { .s = 1,
                                 .n = sizeof(sig_block->block[i].key.n)/sizeof(mbedtls_mpi_uint),
                                 .p = (void *)sig_block->block[i].key.n,
@@ -260,7 +312,7 @@ esp_err_t esp_secure_boot_verify_rsa_signature_block(const ets_secure_boot_signa
             goto exit;
         }
 
-        ret = mbedtls_rsa_rsassa_pss_verify( &pk, mbedtls_ctr_drbg_random, &ctr_drbg, MBEDTLS_RSA_PUBLIC, MBEDTLS_MD_SHA256, 32, 
+        ret = mbedtls_rsa_rsassa_pss_verify( &pk, mbedtls_ctr_drbg_random, &ctr_drbg, MBEDTLS_RSA_PUBLIC, MBEDTLS_MD_SHA256, DIGEST_LEN, 
                                             sig_block->block[i].image_digest, sig_be);
         if (ret != 0) {
             ESP_LOGE(TAG, "Failed mbedtls_rsa_rsassa_pss_verify, err: %d", ret);
@@ -276,6 +328,10 @@ esp_err_t esp_secure_boot_verify_rsa_signature_block(const ets_secure_boot_signa
     
     free(sig_be);
     free(buf);
-    return (!ret) ? ESP_OK : ESP_ERR_IMAGE_INVALID;
+#if CONFIG_IDF_TARGET_ESP32
+    return (ret != 0) ? ESP_ERR_IMAGE_INVALID: ESP_OK;
+#elif CONFIG_IDF_TARGET_ESP32S2
+    return (ret != 0 || match == false) ? ESP_ERR_IMAGE_INVALID: ESP_OK;
+#endif /* CONFIG_IDF_TARGET_ESP32 */
 }
 #endif

components/esp32s2/ld/esp32s2.ld

@@ -27,7 +27,7 @@
 #define RAM_IRAM_START    0x40020000
 #define RAM_DRAM_START    0x3FFB0000
 
-#define DATA_RAM_END      0x3FFE4000  /* 2nd stage bootloader iram_loader_seg starts at block 15 */
+#define DATA_RAM_END      0x3FFE0000  /* 2nd stage bootloader iram_loader_seg starts at SRAM block 14 (reclaimed after app boots) */
 
 #define IRAM_ORG    (RAM_IRAM_START + CONFIG_ESP32S2_INSTRUCTION_CACHE_SIZE \
                                     + CONFIG_ESP32S2_DATA_CACHE_SIZE)

components/esp_rom/include/esp32/rom/secure_boot.h

@@ -81,11 +81,11 @@ typedef struct ets_secure_boot_signature ets_secure_boot_signature_t;
  *
  * This function is used to verify the bootloader before burning its public key hash into Efuse.
  * Also, it is used to verify the app on loading the image on boot and on OTA.
- * 
+ *
  * @param sig The signature block flashed aligned 4096 bytes from the firmware.
  * @param image_digest The SHA-256 Digest of the firmware to be verified
  * @param trusted_key_digest The SHA-256 Digest of the public key (ets_rsa_pubkey_t) of a single signature block.
- * @param verified_digest RSA-PSS signature of image_digest. Pass an uninitialised array. 
+ * @param verified_digest RSA-PSS signature of image_digest. Pass an uninitialised array.
  *
  * @return SBV2_SUCCESS if signature is valid
  * SBV2_FAILED for failures.
@@ -94,16 +94,16 @@ secure_boot_v2_status_t ets_secure_boot_verify_signature(const ets_secure_boot_s
 
 /** @brief This function verifies the 1st stage bootloader. Implemented in the ROM.
  *  Reboots post verification. It reads the Efuse key for verification of the public key.
- * 
+ *
  * This function is not used in the current workflow.
- * 
+ *
  */
 void ets_secure_boot_verify_boot_bootloader(void);
 
 /** @brief Confirms if the secure boot V2 has been enabled. Implemented in the ROM.
- * 
+ *
  * In ESP32-ECO3 - It checks the value of ABS_DONE_1 in EFuse.
- * 
+ *
  * @return true if is Secure boot v2 has been enabled
  * False if Secure boot v2 has not been enabled.
  */
@@ -111,4 +111,8 @@ bool ets_use_secure_boot_v2();
 
 #endif /* CONFIG_ESP32_REV_MIN_3 */
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif /* _ROM_SECURE_BOOT_H_ */

components/esp_rom/include/esp32s2/rom/rsa_pss.h

@@ -28,7 +28,7 @@ typedef struct {
     uint32_t mdash;
 } ets_rsa_pubkey_t;
 
-bool ets_rsa_pss_verify(const ets_rsa_pubkey_t *key, const uint8_t *sig, const uint8_t *digest);
+bool ets_rsa_pss_verify(const ets_rsa_pubkey_t *key, const uint8_t *sig, const uint8_t *digest, uint8_t *verified_digest);
 
 void ets_mgf1_sha256(const uint8_t *mgfSeed, size_t seedLen, size_t maskLen, uint8_t *mask);
 

docs/conf_common.py

@@ -157,7 +157,6 @@ ESP32_DOCS = ['api-guides/ulp_instruction_set.rst',
               'api-guides/RF_calibration.rst',
               'api-reference/system/ipc.rst',
               'security/secure-boot-v1.rst',
-              'security/secure-boot-v2.rst',
               'api-reference/peripherals/secure_element.rst',
               'hw-reference/esp32/**'] + LEGACY_DOCS
 

docs/en/api-guides/index.rst

@@ -30,7 +30,7 @@ API Guides
     :esp32: RF Calibration <RF_calibration>
     ROM debug console <romconsole>
     :esp32: Secure Boot <../security/secure-boot-v1>
-    :esp32: Secure Boot V2 <../security/secure-boot-v2>
+    Secure Boot V2 <../security/secure-boot-v2>
     Thread Local Storage <thread-local-storage>
     Tools <tools/index>
     ULP Coprocessor <ulp>

docs/en/api-guides/unit-tests.rst

@@ -170,8 +170,8 @@ Some old ways of disabling unit tests for targets, that have obvious disadvantag
   - Test item: some items that will be performed on some targets, but skipped on other
     targets. E.g.
 
-    There are three test items SD 1-bit, SD 4-bit and SDSPI. For ESP32S2, which doesn't have
-    SD host, among the tests only SDSPI is enabled on ESP32S2.
+    There are three test items SD 1-bit, SD 4-bit and SDSPI. For ESP32-S2, which doesn't have
+    SD host, among the tests only SDSPI is enabled on ESP32-S2.
 
   - Test implementation: some code will always happen, but in different ways. E.g.
 

docs/en/security/secure-boot-v1.rst

@@ -4,7 +4,7 @@ Secure Boot
 .. important::
 
     All references in this document are related to Secure Boot V1 (The AES based Secure Boot Scheme). ESP32 Revision 3 onwards, the preferred secure boot scheme is :doc:`Secure Boot V2 <secure-boot-v2>`.  
-    Please refer to Secure Boot V2 document for ESP32 Revision 3 or ESP32S2.
+    Please refer to Secure Boot V2 document for ESP32 Revision 3 or ESP32-S2.
 
 Secure Boot is a feature for ensuring only your code can run on the chip. Data loaded from flash is verified on each reset.
 

docs/en/security/secure-boot-v2.rst

@@ -3,15 +3,19 @@ Secure Boot V2
 
 .. important::
 
-    The references in this document are related to Secure Boot v2, the preferred scheme from ESP32-ECO3 onwards and in ESP32S2. (Refer to :doc:`Secure Boot <secure-boot-v1>` for ESP32)
-    
+    The references in this document are related to Secure Boot V2, the preferred scheme from ESP32-ECO3 onwards and in ESP32-S2.
+
+    .. only:: esp32
+
+        Refer also to :doc:`Secure Boot <secure-boot-v1>` for ESP32.
+
     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.
 
 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 ESP32S2 and ESP32 ECO3 onwards. 
+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 and ESP32 ECO3 onwards.
 
 - 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.
@@ -21,9 +25,13 @@ 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.
 
-- Upto three public keys can store can be generated and stored in ESP32S2 during manufacturing. (ESP32 ECO3: only one key)
+- Up to three public keys can be generated and stored in ESP32-S2 during manufacturing. (ESP32 ECO3: only one key)
 
-- ESP32S2 also provides the facility to revoke individual public keys.  
+  .. only:: esp32
+
+    - ESP32-S2 provides the facility to permanently revoke individual public keys. This can be configured conservatively or aggressively.
+
+    - 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.
 
@@ -37,7 +45,7 @@ This is an overview of the Secure Boot V2 Process, Step by step instructions are
 
 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`.
 
-2. On startup, ROM code checks the secure boot v2  bit in eFuse.
+2. On startup, ROM code checks the Secure Boot V2  bit in eFuse.
 
 3. If secure boot is enabled, ROM checks the SHA-256 of the public key in the signature block in the eFuse.
 
@@ -88,9 +96,9 @@ The remainder of the signature sector is erased flash (0xFF) which allows writin
 Verifying the signature Block
 -----------------------------
 
-A signature block is “valid” if the first byte is 0xe7 and a valid CRC32 is stored at offset 1196. Upto 3 signature blocks can be appended to the bootloader or application image in ESP32S2. (ESP32 ECO3: only one key)
+A signature block is “valid” if the first byte is 0xe7 and a valid CRC32 is stored at offset 1196. Upto 3 signature blocks can be appended to the bootloader or application image in ESP32-S2. (ESP32 ECO3: only one key)
 
-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. 
+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.
 
@@ -100,10 +108,10 @@ An image is “verified” if the public key stored in any signature block is va
 
 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.
+- 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.
+  It is recommended to use Secure Boot V2 on the chip versions supporting them.
 
 .. _secure-boot-v2-bootloader-size:
 
@@ -133,25 +141,46 @@ Options to work around this are:
 eFuse usage
 -----------
 
-ESP32-ECO3:
+.. only:: esp32
 
-- ABS_DONE_1 - Enables secure boot protection on boot.
+    ESP32-ECO3:
 
-- 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.
+    - 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.
+
+.. only:: esp32s2
+
+    - SECURE_BOOT_EN - Enables secure boot protection on boot.
+
+    - KEY_PURPOSE_X - Set the purpose of the key block on ESP32-S2 by programming SECURE_BOOT_DIGESTX (X = 0, 1, 2) into KEY_PURPOSE_X (X = 0, 1, 2, 3, 4). Example: If KEY_PURPOSE_2 is set to SECURE_BOOT_DIGEST1, then BLOCK_KEY2 will have the Secure Boot V2 public key digest.
+
+    - 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.
+
+    - 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.
+
+    - SECURE_BOOT_AGGRESSIVE_REVOKE - Enables aggressive revocation of keys. The key is revoked as soon as verification with this key fails.
 
 .. _secure-boot-v2-howto:
 
 How To Enable Secure Boot V2
 ----------------------------
 
-1. Open the :ref:`project-configuration-menu`, in "Security Features" set "Enable hardware Secure Boot in bootloader" to enable Secure Boot. The chip revision should be changed to revision 3(ESP32- ECO3) to view the Secure Boot V2 option.
+1. Open the :ref:`project-configuration-menu`, in "Security Features" set "Enable hardware Secure Boot in bootloader" to enable Secure Boot.
 
-2. To change the chip revision, set "Minimum Supported ESP32 Revision" to Rev 3 in "Component Config" -> "ESP32- Specific", the Secure Boot V2 option can be enabled under "Enable hardware Secure Boot in bootloader" -> "Secure Boot Version". Secure Boot V2 is available for ESP32 ECO3 onwards and in ESP32S2.
+.. only:: esp32
 
-3. Specify the secure boot signing key path. The file can be anywhere on your system. A relative path will be evaluated from the project directory. The file does not need to exist yet.
+    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".
 
-4. Set other menuconfig options (as desired). Pay particular attention to the "Bootloader Config" options, as you can only flash the bootloader once. Then exit menuconfig and save your configuration
+    3. Specify the secure boot signing key path. The file can be anywhere on your system. A relative path will be evaluated from the project directory. The file does not need to exist yet.
+
+.. only:: esp32s2
+
+    2. The "Secure Boot V2" option will be selected and the "App Signing Scheme" would be set to RSA by default.
+
+    3. Select the number of keys to be used to sign the bootloader binary and chose one of them to sign the application. Specify the secure boot signing key paths for each one of these. The file can be anywhere on your system. A relative path will be evaluated from the project directory. The file does not need to exist yet.
+
+4. Set other menuconfig options (as desired). Pay particular attention to the "Bootloader Config" options, as you can only flash the bootloader once. Then exit menuconfig and save your configuration.
 
 5. The first time you run ``make`` or ``idf.py build``, if the signing key is not found then an error message will be printed with a command to generate a signing key via ``espsecure.py generate_signing_key``.
 
@@ -169,11 +198,11 @@ How To Enable Secure Boot V2
 
 .. note:: ``idf.py flash`` doesn't flash the bootloader if secure boot is enabled.
 
-9. Reset the ESP32 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 ESP32 to verify that secure boot is enabled and no errors have occurred due to the build configuration.
+9. 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 ESP32 is reset or powered down during the first boot, it will start the process again on the next boot.
+.. 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.
 
 10. 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).
 
@@ -227,6 +256,48 @@ Secure Boot Best Practices
 * 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.
 
+.. only:: esp32s2
+
+    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.
+    * 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 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).
+
+    Multiple Keys
+    -------------
+
+    * The bootloader should be signed with all the private key(s) that are needed for the life of the device, before it is flashed.
+    * The build system can sign with at most one private key, user has to run manual commands to append more signatures if necessary.
+    * You can use the append functionality of ``espsecure.py``, this command would also printed at the end of the Secure Boot V2 enabled bootloader compilation.
+        espsecure.py sign_data -k secure_boot_signing_key2.pem -v 2 --append_signatures -o signed_bootloader.bin build/bootloader/bootloader.bin
+    * While signing with multiple private keys, it is recommended that the private keys be signed independently, if possible on different servers and stored separately.
+    * You can check the signatures attached to a binary using -
+        espsecure.py signature_info_v2 datafile.bin
+
+    Key Revocation
+    --------------
+
+    * 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.
+    * 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).
+    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).
+    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.
+
 .. _secure-boot-v2-technical-details:
 
 Technical Details

docs/zh_CN/api-guides/index.rst

@@ -22,7 +22,7 @@ API 指南
    引导加载程序 <bootloader>
    分区表 <partition-tables>
    :esp32: Secure Boot <../security/secure-boot-v1>
-   :esp32:  Secure Boot V2 <../security/secure-boot-v2>
+   Secure Boot V2 <../security/secure-boot-v2>
    ULP 协处理器 <ulp>
    :esp32: ULP (传统 GNU Make) <ulp-legacy>
    单元测试 <unit-tests>

tools/idf.py

@@ -462,8 +462,6 @@ def init_cli(verbose_output=None):
             # Otherwise, if we built any binaries print a message about
             # how to flash them
             def print_flashing_message(title, key):
-                print("\n%s build complete. To flash, run this command:" % title)
-
                 with open(os.path.join(args.build_dir, "flasher_args.json")) as f:
                     flasher_args = json.load(f)
 
@@ -471,6 +469,10 @@ def init_cli(verbose_output=None):
                     return _safe_relpath(os.path.join(args.build_dir, f))
 
                 if key != "project":  # flashing a single item
+                    if key not in flasher_args:
+                        # This is the case for 'idf.py bootloader' if Secure Boot is on, need to follow manual flashing steps
+                        print("\n%s build complete." % title)
+                        return
                     cmd = ""
                     if (key == "bootloader"):  # bootloader needs --flash-mode, etc to be passed in
                         cmd = " ".join(flasher_args["write_flash_args"]) + " "
@@ -486,6 +488,8 @@ def init_cli(verbose_output=None):
                     for o, f in flash_items:
                         cmd += o + " " + flasher_path(f) + " "
 
+                print("\n%s build complete. To flash, run this command:" % title)
+
                 print(
                     "%s %s -p %s -b %s --before %s --after %s --chip %s %s write_flash %s" % (
                         PYTHON,

tools/test_apps/security/secure_boot/sdkconfig.ci.00

@@ -1,4 +1,5 @@
 # Secure Boot V2 - ESP-ECO3+
+CONFIG_IDF_TARGET="esp32"
 CONFIG_SECURE_BOOT=y
 CONFIG_ESP32_REV_MIN_3=y
 CONFIG_SECURE_BOOT_V2_ENABLED=y

tools/test_apps/security/secure_boot/sdkconfig.ci.01

@@ -1,4 +1,5 @@
 # Secure Boot V1
+CONFIG_IDF_TARGET="esp32"
 CONFIG_SECURE_BOOT=y
 CONFIG_SECURE_BOOT_V1_ENABLED=y
 CONFIG_SECURE_BOOT_SIGNING_KEY="test_ecdsa_key.pem"

tools/test_apps/security/secure_boot/sdkconfig.ci.02

@@ -1,4 +1,5 @@
 # ECDSA App signing without secure boot
+CONFIG_IDF_TARGET="esp32"
 CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT=y
 CONFIG_SECURE_SIGNED_ON_BOOT_NO_SECURE_BOOT=y
 CONFIG_SECURE_BOOT_SIGNING_KEY="test_ecdsa_key.pem"

tools/test_apps/security/secure_boot/sdkconfig.ci.03

@@ -0,0 +1,5 @@
+# ESP32-S2 Secure Boot
+CONFIG_IDF_TARGET="esp32s2"
+CONFIG_SECURE_BOOT=y
+CONFIG_SECURE_BOOT_SIGNING_KEY="test_rsa_3072_key.pem"
+

tools/test_apps/security/secure_boot/sdkconfig.ci.04

@@ -0,0 +1,6 @@
+# ESP32-S2 Secure Boot & Flash Encryption (Release mode)
+CONFIG_IDF_TARGET="esp32s2"
+CONFIG_SECURE_BOOT=y
+CONFIG_SECURE_BOOT_SIGNING_KEY="test_rsa_3072_key.pem"
+CONFIG_SECURE_FLASH_ENC_ENABLED=y
+SECURE_FLASH_ENCRYPTION_MODE_RELEASE=y

tools/unit-test-app/configs/default_s2_1

@@ -1,3 +1,3 @@
 # This config is split between targets since different component needs to be included (esp32, esp32s2)
 CONFIG_IDF_TARGET="esp32s2"
-TEST_COMPONENTS=freertos esp32s2 esp_timer driver heap pthread soc spi_flash vfs
+TEST_COMPONENTS=freertos esp32s2 esp_timer driver heap

tools/unit-test-app/configs/default_s2_2

@@ -0,0 +1,3 @@
+# This config is split between targets since different component needs to be included (esp32, esp32s2)
+CONFIG_IDF_TARGET="esp32s2"
+TEST_COMPONENTS=pthread soc spi_flash vfs

tools/unit-test-app/configs/single_core_s2

@@ -1,6 +1,4 @@
 # This config is split between targets since different component needs to be included (esp32, esp32s2)
 CONFIG_IDF_TARGET="esp32s2"
-TEST_COMPONENTS=freertos esp32s2 esp_timer driver heap pthread soc spi_flash vfs test_utils
-CONFIG_MEMMAP_SMP=n
-CONFIG_FREERTOS_UNICORE=y
+TEST_COMPONENTS=esp32s2 esp_timer driver heap soc spi_flash test_utils
 CONFIG_ESP32S2_RTCDATA_IN_FAST_MEM=y