vhdirk · Oct 30, 2026 · dgarske · Nov 3, 2026
diff --git a/arch.mk b/arch.mk
@@ -483,6 +483,7 @@ ifeq ($(ARCH),ARM)
   ifeq ($(TARGET),stm32l0)
     CORTEX_M0=1
     SPI_TARGET=stm32
+    FLASH_ERASE_UNIT?=128
   endif
 
   ifeq ($(TARGET),stm32c0)

diff --git a/docs/HAL.md b/docs/HAL.md
@@ -62,9 +62,11 @@ by the bootloader at the end of every write and erase operations.
 Called by the bootloader to erase part of the flash memory to allow subsequent boots.
 Erase operations must be performed via the specific IAP interface of the target microcontroller.
 `address` marks the start of the area that the bootloader wants to erase, and `len` specifies
-the size of the area to be erased. `address` is guaranteed to be aligned to `WOLFBOOT_SECTOR_SIZE`,
-and `len` is guaranteed to be a multiple of `WOLFBOOT_SECTOR_SIZE`. This function must take into account
-the geometry of the flash sectors, and erase all the sectors in between.
+the size of the area to be erased. Most requests are aligned to `WOLFBOOT_SECTOR_SIZE` and have
+a length that is a multiple of it. Encrypted-key maintenance may issue smaller requests aligned
+to `WOLFBOOT_FLASH_ERASE_UNIT`, configured with `FLASH_ERASE_UNIT` (which defaults to
+`WOLFBOOT_SECTOR_SIZE`). The HAL must support both request sizes and take the flash geometry into
+account when erasing.
 
 `void hal_prepare_boot(void)`
 

diff --git a/docs/compile.md b/docs/compile.md
@@ -320,6 +320,18 @@ and a journal record is 16 bytes, or one write unit if larger.
 | [Journal](#trailer-storage-option-nvm_flash_journal-and-nvm_flash_journal_dual) | `NVM_FLASH_JOURNAL=1` | sector size / record size >= 3N + 4, slow erases | 1 record program | 1 | yes |
 | [Journal in two sectors](#redundant-sector-journaling-nvm_flash_journal_dual) | `NVM_FLASH_JOURNAL=1` and `NVM_FLASH_JOURNAL_DUAL=1` | slow erases, and a reset must never damage the log | 1 record program | 2 | yes |
 
+### Flash erase unit
+
+`FLASH_ERASE_UNIT=<bytes>` sets the smallest aligned erase range wolfBoot may request
+from `hal_flash_erase()` while updating the encrypted key and trailer. It must be a
+power of two that divides `WOLFBOOT_SECTOR_SIZE`. If omitted, it defaults to
+`WOLFBOOT_SECTOR_SIZE`; the STM32L0 target defaults to 128 bytes.
+
+The HAL must support erasing ranges aligned to this unit. Most other erase requests
+remain sector-sized. In non-write-once builds, `NVM_CACHE_SIZE` defaults to this
+erase unit and must be at least that large. In `NVM_FLASH_WRITEONCE` builds, the
+cache remains sector-sized because the two trailer copies must stay sector-aligned.
+
 For a specific platform example, the AURIX TC3xx platform has these flash constraints:
 
 - The smallest unit it can program is a 32-byte page, and a page can be programmed only once per erase.

diff --git a/docs/encrypted_partitions.md b/docs/encrypted_partitions.md
@@ -262,8 +262,10 @@ all the needed symbols in RAM.
 
 ### Using a custom buffer as encrypt/decrypt cache
 
-By default, encryption support requires a buffer of the same size as the external flash page size to be allocated in RAM.
-You can provide a custom pre-allocated buffer by passing its address via the option `ENCRYPT_CACHE`, e.g.:
+By default, encryption support uses a buffer sized by `NVM_CACHE_SIZE`. In non-write-once
+builds, this defaults to `WOLFBOOT_FLASH_ERASE_UNIT`; in write-once builds it remains
+`WOLFBOOT_SECTOR_SIZE`. A custom pre-allocated buffer must be at least `NVM_CACHE_SIZE`
+bytes and can be provided by passing its address via `ENCRYPT_CACHE`, e.g.:
 
 `ENCRYPT_CACHE=0x20010000`
 
@@ -278,4 +280,3 @@ An example of encrypted update trigger can be found in the [stm32wb test applica
 
 
 
-
diff --git a/options.mk b/options.mk
@@ -1289,6 +1289,10 @@ ifneq ($(FLASH_WRITE_UNIT),)
   CFLAGS+= -D"WOLFBOOT_FLASH_WRITE_UNIT=$(FLASH_WRITE_UNIT)"
 endif
 
+ifneq ($(FLASH_ERASE_UNIT),)
+  CFLAGS+= -D"WOLFBOOT_FLASH_ERASE_UNIT=$(FLASH_ERASE_UNIT)"
+endif
+
 ifeq ($(CUSTOM_PARTITION_TRAILER),1)
   CFLAGS+= -D"CUSTOM_PARTITION_TRAILER"
 endif

diff --git a/src/libwolfboot.c b/src/libwolfboot.c
@@ -161,8 +161,29 @@ int wolfBoot_initialize_encryption(void)
 #   define NULL (void *)0
 #endif
 
+#ifndef WOLFBOOT_FLASH_ERASE_UNIT
+#define WOLFBOOT_FLASH_ERASE_UNIT WOLFBOOT_SECTOR_SIZE
+#endif
+
+#if WOLFBOOT_FLASH_ERASE_UNIT <= 0
+    #error WOLFBOOT_FLASH_ERASE_UNIT must be positive
+#elif (WOLFBOOT_FLASH_ERASE_UNIT & (WOLFBOOT_FLASH_ERASE_UNIT - 1)) != 0
+    #error WOLFBOOT_FLASH_ERASE_UNIT must be a power of two
+#elif (WOLFBOOT_SECTOR_SIZE % WOLFBOOT_FLASH_ERASE_UNIT) != 0
+    #error WOLFBOOT_FLASH_ERASE_UNIT must divide WOLFBOOT_SECTOR_SIZE
+#endif
+
 #ifndef NVM_CACHE_SIZE
-#define NVM_CACHE_SIZE WOLFBOOT_SECTOR_SIZE
+    #ifdef NVM_FLASH_WRITEONCE
+        #define NVM_CACHE_SIZE WOLFBOOT_SECTOR_SIZE
+    #else
+        #define NVM_CACHE_SIZE WOLFBOOT_FLASH_ERASE_UNIT
+    #endif
+#endif
+
+#ifndef NVM_FLASH_WRITEONCE
+typedef char wolfBoot_encrypt_cache_size_check[
+    (NVM_CACHE_SIZE >= WOLFBOOT_FLASH_ERASE_UNIT) ? 1 : -1];
 #endif
 
 #ifdef BUILD_TOOL
@@ -2720,6 +2741,24 @@ void RAMFUNCTION wolfBoot_crypto_set_iv(const uint8_t *nonce, uint32_t iv_counte
 #ifndef CUSTOM_ENCRYPT_KEY
 /* Under CUSTOM_ENCRYPT_KEY the platform supplies the key, so the
  * partition-resident storage below (needs WOLFBOOT_PARTITION_*) is dropped. */
+#if !defined(NVM_FLASH_WRITEONCE) && !defined(MMU) && \
+    !defined(WOLFBOOT_RENESAS_TSIP)
+static void RAMFUNCTION hal_set_key_cache_copy(uint8_t *cache,
+        uintptr_t page_addr, uintptr_t field_addr, const uint8_t *data,
+        size_t length)
+{
+    uintptr_t page_end = page_addr + WOLFBOOT_FLASH_ERASE_UNIT;
+    uintptr_t field_end = field_addr + length;
+    uintptr_t copy_start = field_addr > page_addr ? field_addr : page_addr;
+    uintptr_t copy_end = field_end < page_end ? field_end : page_end;
+
+    if (copy_start < copy_end) {
+        XMEMCPY(cache + (copy_start - page_addr),
+            data + (copy_start - field_addr), copy_end - copy_start);
+    }
+}
+#endif
+
 static int RAMFUNCTION hal_set_key(const uint8_t *k, const uint8_t *nonce)
 {
 #ifdef WOLFBOOT_RENESAS_TSIP
@@ -2732,41 +2771,33 @@ static int RAMFUNCTION hal_set_key(const uint8_t *k, const uint8_t *nonce)
     XMEMCPY(ENCRYPT_KEY + ENCRYPT_KEY_SIZE, nonce, ENCRYPT_NONCE_SIZE);
     return 0;
 #else
-    uintptr_t addr, addr_align, addr_off;
+    uintptr_t addr, addr_align;
     int ret = 0;
-    uint32_t trailer_relative_off = 4;
 #ifdef NVM_FLASH_WRITEONCE
+    uintptr_t addr_off;
+    uint32_t trailer_relative_off = 4;
     int sel_sec = 0;
 #endif
 #if !defined(WOLFBOOT_SMALL_STACK) && !defined(NVM_FLASH_WRITEONCE) && \
     !defined(WOLFBOOT_ENCRYPT_CACHE)
     uint8_t ENCRYPT_CACHE[NVM_CACHE_SIZE] XALIGNED_STACK(32);
 #endif
 
+#ifdef NVM_FLASH_WRITEONCE
     addr = ENCRYPT_TMP_SECRET_OFFSET + WOLFBOOT_PARTITION_BOOT_ADDRESS;
     addr_align = addr & (~(WOLFBOOT_SECTOR_SIZE - 1));
     addr_off = addr & (WOLFBOOT_SECTOR_SIZE - 1);
-#ifdef NVM_FLASH_WRITEONCE
     /* we read from the populated sector, now write to the erased sector */
     sel_sec = nvm_select_fresh_sector(PART_BOOT);
     addr_align -= (sel_sec * WOLFBOOT_SECTOR_SIZE);
-#endif
     hal_flash_unlock();
     /* casting to unsigned long to abide compilers on 64bit architectures */
     XMEMCPY(ENCRYPT_CACHE,
             (void*)(unsigned long)(addr_align),
                 WOLFBOOT_SECTOR_SIZE);
-#ifdef NVM_FLASH_WRITEONCE
     /* we read from the populated sector, now write to the erased sector */
     addr_align = addr & (~(WOLFBOOT_SECTOR_SIZE - 1));
     addr_align -= (!sel_sec * WOLFBOOT_SECTOR_SIZE);
-#else
-    /* erase the old key */
-    ret = hal_flash_erase(addr_align, WOLFBOOT_SECTOR_SIZE);
-    if (ret != 0)
-        goto exit_lock;
-#endif
-
     /* Populate key + nonce in the cache */
     XMEMCPY(ENCRYPT_CACHE + addr_off, k, ENCRYPT_KEY_SIZE);
     XMEMCPY(ENCRYPT_CACHE + addr_off + ENCRYPT_KEY_SIZE, nonce,
@@ -2776,18 +2807,13 @@ static int RAMFUNCTION hal_set_key(const uint8_t *k, const uint8_t *nonce)
     XMEMCPY(ENCRYPT_CACHE + addr_off - trailer_relative_off,
             &wolfboot_magic_trail, 4);
 #ifdef FLAGS_HOME
-    /* If flags are stored in BOOT partition, take into account the offset
-     * of the flags used for the update partition too, to avoid erasing the
-     * sector.
-     */
     trailer_relative_off += (PART_BOOT_ENDFLAGS - PART_UPDATE_ENDFLAGS);
     XMEMCPY(ENCRYPT_CACHE + addr_off - trailer_relative_off,
             &wolfboot_magic_trail, 4);
 #endif
 
     /* Writing cache back to sector "!sel_sec" */
     ret = hal_flash_write(addr_align, ENCRYPT_CACHE, WOLFBOOT_SECTOR_SIZE);
-#ifdef NVM_FLASH_WRITEONCE
     if (ret != 0)
         goto exit_lock;
     /* Erasing original sector "sel_sec",
@@ -2796,6 +2822,75 @@ static int RAMFUNCTION hal_set_key(const uint8_t *k, const uint8_t *nonce)
     addr_align = addr & (~(WOLFBOOT_SECTOR_SIZE - 1));
     addr_align -= (sel_sec * WOLFBOOT_SECTOR_SIZE);
     ret = hal_flash_erase(addr_align, WOLFBOOT_SECTOR_SIZE);
+#else
+    uintptr_t boot_base = WOLFBOOT_PARTITION_BOOT_ADDRESS;
+    uintptr_t boot_end, unit, first_addr, end_addr, first_unit, last_unit;
+#ifdef FLAGS_HOME
+    uintptr_t flag_magic_off, flag_magic_addr;
+#endif
+
+    if (boot_base > UINTPTR_MAX - WOLFBOOT_PARTITION_SIZE)
+        return -1;
+    boot_end = boot_base + WOLFBOOT_PARTITION_SIZE;
+    unit = WOLFBOOT_FLASH_ERASE_UNIT;
+    if ((boot_base % unit) != 0 ||
+            (WOLFBOOT_PARTITION_SIZE % unit) != 0 ||
+            (uintptr_t)ENCRYPT_TMP_SECRET_OFFSET > boot_end - boot_base)
+        return -1;
+    addr = boot_base + ENCRYPT_TMP_SECRET_OFFSET;
+    if (addr < boot_base + sizeof(uint32_t) ||
+            (size_t)ENCRYPT_KEY_SIZE + ENCRYPT_NONCE_SIZE > boot_end - addr)
+        return -1;
+    first_addr = addr - sizeof(uint32_t);
+    end_addr = addr + ENCRYPT_KEY_SIZE + ENCRYPT_NONCE_SIZE;
+
+#ifdef FLAGS_HOME
+    if ((uintptr_t)PART_BOOT_ENDFLAGS < (uintptr_t)PART_UPDATE_ENDFLAGS)
+        return -1;
+    flag_magic_off = (uintptr_t)PART_BOOT_ENDFLAGS -
+        (uintptr_t)PART_UPDATE_ENDFLAGS;
+    if (flag_magic_off > addr - boot_base - sizeof(uint32_t))
+        return -1;
+    flag_magic_addr = addr - sizeof(uint32_t) - flag_magic_off;
+    first_addr = flag_magic_addr;
+#endif
+    first_unit = first_addr & ~(unit - 1);
+    last_unit = (end_addr - 1) & ~(unit - 1);
+
+    hal_flash_unlock();
+    for (addr_align = first_unit; addr_align <= last_unit;
+            addr_align += unit) {
+        if (addr_align < boot_base || addr_align >= boot_end ||
+                unit > boot_end - addr_align) {
+            ret = -1;
+            goto exit_lock;
+        }
+        XMEMCPY(ENCRYPT_CACHE,
+            (void *)(unsigned long)addr_align, unit);
+        ret = hal_flash_erase(addr_align, unit);
+        if (ret != 0)
+            goto exit_lock;
+
+#ifdef FLAGS_HOME
+        hal_set_key_cache_copy((uint8_t *)(uintptr_t)ENCRYPT_CACHE,
+            addr_align, flag_magic_addr,
+            (const uint8_t *)&wolfboot_magic_trail,
+            sizeof(wolfboot_magic_trail));
+#endif
+        hal_set_key_cache_copy((uint8_t *)(uintptr_t)ENCRYPT_CACHE,
+            addr_align, addr - sizeof(uint32_t),
+            (const uint8_t *)&wolfboot_magic_trail,
+            sizeof(wolfboot_magic_trail));
+        hal_set_key_cache_copy((uint8_t *)(uintptr_t)ENCRYPT_CACHE,
+            addr_align, addr, k, ENCRYPT_KEY_SIZE);
+        hal_set_key_cache_copy((uint8_t *)(uintptr_t)ENCRYPT_CACHE,
+            addr_align, addr + ENCRYPT_KEY_SIZE, nonce,
+            ENCRYPT_NONCE_SIZE);
+
+        ret = hal_flash_write(addr_align, ENCRYPT_CACHE, unit);
+        if (ret != 0)
+            goto exit_lock;
+    }
 #endif
 exit_lock:
     /* Scrub the staged key/nonce on every build where wolfBoot owns the
@@ -3402,8 +3497,8 @@ static uint8_t RAMFUNCTION part_address(uintptr_t a)
  * written per pass must be a block multiple: a partial block at the end of a
  * pass would be written as stale cache content and would leave the address
  * unaligned, desynchronising the keystream from ext_flash_decrypt_read().
- * NVM_CACHE_SIZE defaults to WOLFBOOT_SECTOR_SIZE, which is always a multiple,
- * but it can be overridden. */
+ * NVM_CACHE_SIZE defaults to the erase unit in non-write-once builds and to
+ * WOLFBOOT_SECTOR_SIZE in write-once builds. */
 #define ENCRYPT_STAGE_SIZE \
     ((NVM_CACHE_SIZE) - ((NVM_CACHE_SIZE) % ENCRYPT_BLOCK_SIZE))
 typedef char wolfBoot_encrypt_stage_size_check[

diff --git a/tools/config.mk b/tools/config.mk
@@ -121,7 +121,8 @@ WATCHDOG_HANDOFF?=0
 CONFIG_VARS:= ARCH TARGET SIGN HASH MCUXSDK MCUXPRESSO MCUXPRESSO_CPU MCUXPRESSO_DRIVERS \
 	MCUXPRESSO_CMSIS FREEDOM_E_SDK STM32CUBE CYPRESS_PDL CYPRESS_CORE_LIB CYPRESS_TARGET_LIB DEBUG VTOR \
 	CORTEX_M0 CORTEX_M7 CORTEX_M23 CORTEX_M33 CORTEX_M55 NO_ASM EXT_FLASH SPI_FLASH NO_XIP UART_FLASH ALLOW_DOWNGRADE NVM_FLASH_WRITEONCE CUSTOM_PARTITION_TRAILER \
-	NVM_FLASH_JOURNAL NVM_FLASH_JOURNAL_DUAL NVM_FLASH_ECC FLASH_WRITE_UNIT \
+	NVM_FLASH_JOURNAL NVM_FLASH_JOURNAL_DUAL NVM_FLASH_ECC \
+	FLASH_WRITE_UNIT FLASH_ERASE_UNIT \
 	DISABLE_BACKUP WOLFBOOT_VERSION V NO_MPU ENCRYPT FLAGS_HOME FLAGS_INVERT \
 	SPMATH SPMATHALL RAM_CODE DUALBANK_SWAP IMAGE_HEADER_SIZE PKA TZEN PSOC6_CRYPTO \
 	WOLFTPM WOLFBOOT_TPM_VERIFY MEASURED_BOOT WOLFBOOT_TPM_SEAL WOLFBOOT_TPM_KEYSTORE WOLFBOOT_SECURE_APP WOLFBOOT_SECURE_HANDOFF_ADDRESS \

diff --git a/tools/unit-tests/Makefile b/tools/unit-tests/Makefile
@@ -62,6 +62,8 @@ TESTS:=unit-parser unit-parser-large-header unit-fdt unit-extflash unit-string \
        unit-aes256 unit-chacha20 unit-pci unit-pci-4gib unit-mock-state \
        unit-sectorflags unit-max-space \
        unit-image unit-image-hybrid unit-image-rsa unit-nvm unit-nvm-flagshome unit-enc-nvm \
+       unit-enc-key unit-enc-key-aes256 unit-enc-key-straddle \
+       unit-enc-key-sector unit-enc-key-flagshome \
        unit-enc-nvm-flagshome unit-delta unit-gzip unit-update-flash unit-update-flash-delta \
        unit-update-flash-db \
        unit-update-flash-hook \
@@ -369,6 +371,36 @@ unit-enc-nvm:WOLFCRYPT_SRC+=$(WOLFBOOT_LIB_WOLFSSL)/wolfcrypt/src/chacha.c
 unit-enc-nvm-flagshome:CFLAGS+=-DNVM_FLASH_WRITEONCE -DMOCK_PARTITIONS \
 	-DEXT_ENCRYPTED -DENCRYPT_WITH_CHACHA -DEXT_FLASH -DHAVE_CHACHA -DFLAGS_HOME
 unit-enc-nvm-flagshome:WOLFCRYPT_SRC+=$(WOLFBOOT_LIB_WOLFSSL)/wolfcrypt/src/chacha.c
+unit-enc-key:CFLAGS+=-DMOCK_PARTITIONS -DEXT_FLASH -DEXT_ENCRYPTED \
+	-DENCRYPT_WITH_CHACHA -DHAVE_CHACHA -DWOLFBOOT_SMALL_STACK \
+	-DWOLFBOOT_SECTOR_SIZE=0x1000 -DWOLFBOOT_FLASH_ERASE_UNIT=128 \
+	-DMOCK_FLASH_ERASE_UNIT=128
+unit-enc-key:WOLFCRYPT_SRC+= \
+	$(WOLFBOOT_LIB_WOLFSSL)/wolfcrypt/src/chacha.c
+unit-enc-key-aes256:CFLAGS+=-DMOCK_PARTITIONS -DEXT_FLASH -DEXT_ENCRYPTED \
+	-DENCRYPT_WITH_AES256 -DWOLFSSL_AES_DIRECT -DWOLFSSL_AES_256 \
+	-DWOLFSSL_AES_COUNTER -DWOLFBOOT_SMALL_STACK \
+	-DWOLFBOOT_SECTOR_SIZE=0x1000 -DWOLFBOOT_FLASH_ERASE_UNIT=128 \
+	-DMOCK_FLASH_ERASE_UNIT=128
+unit-enc-key-aes256:WOLFCRYPT_SRC+= \
+	$(WOLFBOOT_LIB_WOLFSSL)/wolfcrypt/src/aes.c
+unit-enc-key-straddle:CFLAGS+=-DMOCK_PARTITIONS -DEXT_FLASH -DEXT_ENCRYPTED \
+	-DENCRYPT_WITH_CHACHA -DHAVE_CHACHA -DWOLFBOOT_SMALL_STACK \
+	-DWOLFBOOT_SECTOR_SIZE=0x1000 -DWOLFBOOT_FLASH_ERASE_UNIT=64 \
+	-DMOCK_FLASH_ERASE_UNIT=64 -DTRAILER_SKIP=24
+unit-enc-key-straddle:WOLFCRYPT_SRC+= \
+	$(WOLFBOOT_LIB_WOLFSSL)/wolfcrypt/src/chacha.c
+unit-enc-key-sector:CFLAGS+=-DMOCK_PARTITIONS -DEXT_FLASH -DEXT_ENCRYPTED \
+	-DENCRYPT_WITH_CHACHA -DHAVE_CHACHA -DWOLFBOOT_SMALL_STACK \
+	-DWOLFBOOT_SECTOR_SIZE=0x1000 -DMOCK_FLASH_ERASE_UNIT=0x1000
+unit-enc-key-sector:WOLFCRYPT_SRC+= \
+	$(WOLFBOOT_LIB_WOLFSSL)/wolfcrypt/src/chacha.c
+unit-enc-key-flagshome:CFLAGS+=-DMOCK_PARTITIONS -DEXT_FLASH -DEXT_ENCRYPTED \
+	-DENCRYPT_WITH_CHACHA -DHAVE_CHACHA -DWOLFBOOT_SMALL_STACK \
+	-DWOLFBOOT_SECTOR_SIZE=0x1000 -DWOLFBOOT_FLASH_ERASE_UNIT=128 \
+	-DMOCK_FLASH_ERASE_UNIT=128 -DFLAGS_HOME
+unit-enc-key-flagshome:WOLFCRYPT_SRC+= \
+	$(WOLFBOOT_LIB_WOLFSSL)/wolfcrypt/src/chacha.c
 unit-delta:CFLAGS+=-DNVM_FLASH_WRITEONCE -DMOCK_PARTITIONS -DDELTA_UPDATES -DDELTA_BLOCK_SIZE=512
 unit-pkcs11_store:CFLAGS+=-I$(WOLFBOOT_LIB_WOLFPKCS11) -DMOCK_PARTITIONS -DMOCK_KEYVAULT -DSECURE_PKCS11 -DWOLFPKCS11_USER_SETTINGS
 # Same suite against a flash-read cache that only refreshes on
@@ -1140,6 +1172,12 @@ unit-enc-nvm: ../../include/target.h unit-enc-nvm.c
 unit-enc-nvm-flagshome: ../../include/target.h unit-enc-nvm.c
 	gcc -o $@ $(WOLFCRYPT_SRC) unit-enc-nvm.c $(CFLAGS) $(WOLFCRYPT_CFLAGS) $(LDFLAGS)
 
+unit-enc-key unit-enc-key-aes256 unit-enc-key-straddle \
+unit-enc-key-sector unit-enc-key-flagshome: \
+	../../include/target.h unit-enc-key.c
+	gcc -o $@ $(WOLFCRYPT_SRC) unit-enc-key.c $(CFLAGS) \
+		$(WOLFCRYPT_CFLAGS) $(LDFLAGS)
+
 unit-delta: ../../include/target.h unit-delta.c
 	gcc -o $@ unit-delta.c $(CFLAGS) $(LDFLAGS)