Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .github/workflows/test-configs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -1667,6 +1667,21 @@ jobs:
arch: aarch64
config-file: ./config/examples/versal_vmk180_sdcard.config

# ML-DSA-87 signed, AES-256 encrypted images in two fixed QSPI slots.
versal_vmk180_pq_enc_test:
uses: ./.github/workflows/test-build-aarch64.yml
with:
arch: aarch64
config-file: ./config/examples/versal_vmk180.config
make-args: SIGN=ML_DSA ML_DSA_LEVEL=5 IMAGE_SIGNATURE_SIZE=4627 IMAGE_HEADER_SIZE=12288 ENCRYPT=1 ENCRYPT_WITH_AES256=1 CUSTOM_ENCRYPT_KEY=1 ENCRYPT_CACHE=0x08200000 DUALBOOT_ROLLBACK_UNCONFIRMED=1 WOLFBOOT_PARTITION_SIZE=0x400000 WOLFBOOT_PARTITION_UPDATE_ADDRESS=0xC00000 WOLFBOOT_PARTITION_SWAP_ADDRESS=0x1000000

versal_vmk180_sdcard_pq_enc_test:
uses: ./.github/workflows/test-build-aarch64.yml
with:
arch: aarch64
config-file: ./config/examples/versal_vmk180_sdcard.config
make-args: SIGN=ML_DSA ML_DSA_LEVEL=5 IMAGE_SIGNATURE_SIZE=4627 IMAGE_HEADER_SIZE=12288 ENCRYPT=1 ENCRYPT_WITH_AES256=1 CUSTOM_ENCRYPT_KEY=1 DISK_BOOT_CONFIRM=1 WOLFBOOT_SECTOR_SIZE=0x4000

# FIT read from a filesystem with no kernel load/entry and no fdt
# sub-image, so the staging addresses come from the build.
versal_vmk180_sdcard_fit_file_test:
Expand Down
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,7 @@ tools/unit-tests/unit-spi-flash
tools/unit-tests/unit-string
tools/unit-tests/unit-update-flash
tools/unit-tests/unit-update-flash-enc
tools/unit-tests/unit-update-flash-enc-cache
tools/unit-tests/unit-update-flash-db
tools/unit-tests/unit-update-flash-flagshome
tools/unit-tests/unit-update-flash-invert
Expand Down Expand Up @@ -682,6 +683,7 @@ tools/unit-tests/unit-t10xx-flash-status
tools/unit-tests/unit-ti-hercules-erase
tools/unit-tests/unit-update-disk-fsp
tools/unit-tests/unit-update-ram-custom-trailer
tools/unit-tests/unit-update-ram-rollback-unconfirmed
tools/unit-tests/unit-update-ram-nofixed-noramboot
tools/unit-tests/unit-update-trigger-scrub
tools/unit-tests/unit-x86-uart
Expand Down
6 changes: 6 additions & 0 deletions docs/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,12 +27,16 @@ Basic interaction from the application is provided via the following high-level

`void wolfBoot_success(void)`

`void wolfBoot_success_part(uint8_t part)`

### Firmware version

Current (boot) firmware and update firmware versions can be retrieved from the application using:

`uint32_t wolfBoot_get_image_version(uint8_t part)`

On an MMU target that keeps its images encrypted in flash (`EXT_ENCRYPTED` with `MMU`), only the bootloader holds the key, so this call returns 0 from the application for an encrypted partition.

Or via the shortcut macros:

`wolfBoot_current_firmware_version()`
Expand All @@ -53,6 +57,8 @@ single-block SWAP space.

### Confirm current image

- `wolfBoot_success_part(part)` marks `PART_BOOT` or `PART_UPDATE` as successful and ignores any other value. A fixed-slot dual-boot application that may run from either partition passes the one it was booted from, which the bootloader reports to it (on Versal, the `/chosen/wolfboot,boot-part` device tree property). `wolfBoot_success()` is the same call for `PART_BOOT`.

- `wolfBoot_success()` indicates a successful boot of a new firmware. This can be called by the application
at any time, but it will only be effective to mark the current firmware (in the BOOT partition) with the state
`STATE_SUCCESS`, indicating that no roll-back is required. An application should typically call `wolfBoot_success()`
Expand Down
25 changes: 25 additions & 0 deletions docs/Targets.md
Original file line number Diff line number Diff line change
Expand Up @@ -4949,6 +4949,31 @@ Typical boot timing with ECC384/SHA384 signing:

---

### Post-quantum signed and encrypted images

The Versal configurations also build with ML-DSA-87 signatures and AES-256 encrypted images by adding make arguments:

```sh
# QSPI, two fixed slots at 0x800000 and 0xC00000
cp config/examples/versal_vmk180.config .config
make SIGN=ML_DSA ML_DSA_LEVEL=5 IMAGE_SIGNATURE_SIZE=4627 IMAGE_HEADER_SIZE=12288 \
ENCRYPT=1 ENCRYPT_WITH_AES256=1 CUSTOM_ENCRYPT_KEY=1 ENCRYPT_CACHE=0x08200000 \
DUALBOOT_ROLLBACK_UNCONFIRMED=1 WOLFBOOT_PARTITION_SIZE=0x400000 \
WOLFBOOT_PARTITION_UPDATE_ADDRESS=0xC00000 WOLFBOOT_PARTITION_SWAP_ADDRESS=0x1000000

# SD card A/B slots
cp config/examples/versal_vmk180_sdcard.config .config
make SIGN=ML_DSA ML_DSA_LEVEL=5 IMAGE_SIGNATURE_SIZE=4627 IMAGE_HEADER_SIZE=12288 \
ENCRYPT=1 ENCRYPT_WITH_AES256=1 CUSTOM_ENCRYPT_KEY=1 DISK_BOOT_CONFIRM=1 \
WOLFBOOT_SECTOR_SIZE=0x4000
```

The QSPI flash is not memory mapped, so wolfBoot reads the ciphertext of the selected slot into DDR at `WOLFBOOT_LOAD_ADDRESS`, decrypts it in place and verifies it there.

The platform supplies the image key through the `CUSTOM_ENCRYPT_KEY` hooks. `hal/versal.c` has weak defaults that fail, so an encrypted image does not boot until `wolfBoot_get_encrypt_key()` is provided, for example from eFuse, BBRAM or a PUF-wrapped store; link it with `OBJS_EXTRA=<file>.o`.

With `DUALBOOT_ROLLBACK_UNCONFIRMED=1` (see [compile.md](compile.md#roll-back-an-unconfirmed-image-in-dual-boot-mode)) wolfBoot reports the slot it booted to the application in the device tree as `/chosen/wolfboot,boot-part` (0 = boot slot, 1 = update slot), so a bare-metal application can confirm its own slot with `wolfBoot_success_part()` and write an update to the other one. ML-DSA-87 verification needs a deep stack; the EL2 stack in `hal/versal.ld` is sized for it.

### SD Card Boot (MBR + A/B)

Use `config/examples/versal_vmk180_sdcard.config`. This uses the Arasan SDHCI controller and an **MBR** partitioned SD card.
Expand Down
6 changes: 6 additions & 0 deletions docs/compile.md
Original file line number Diff line number Diff line change
Expand Up @@ -506,6 +506,12 @@ downgrades, compile with `ALLOW_DOWNGRADE=1`.
Warning: this option will disable version checking before the updates, thus exposing the system to potential
forced downgrade attacks.

### Roll back an unconfirmed image in dual-boot mode

A dual-boot target that loads the image to RAM (two fixed slots, no swap, `src/update_ram.c`) boots the slot with the higher version and marks it `TESTING` until the application confirms it with `wolfBoot_success_part()`. If the board resets while the slot is still `TESTING`, wolfBoot falls back to the other slot only when that does not lower the version, so an update that boots but never confirms keeps being retried.

`DUALBOOT_ROLLBACK_UNCONFIRMED=1` lets that fallback go to a lower version: the other slot boots, and the unconfirmed slot is erased once that image has passed verification. If the other slot fails verification, the unconfirmed image is kept and booted again. The version check for confirmed images is unchanged. The option is not available with the hardware-assisted swap loader. The trade-off is that someone able to reset the board during the probation window can keep it on the older image, which `ALLOW_DOWNGRADE=0` otherwise prevents once the newer one has been written.

### Linux kernel command line (bootargs)

On the FIT Linux-boot targets whose DTB comes from the signed FIT (Versal, ZynqMP, PolarFire SoC), a DTB that already carries a non-empty `/chosen/bootargs` keeps it by default - the image boots with the arguments its kernel was validated with, and wolfBoot logs `FDT: using DTB bootargs: ...`. Three macros control this:
Expand Down
40 changes: 39 additions & 1 deletion hal/versal.c
Original file line number Diff line number Diff line change
Expand Up @@ -821,7 +821,10 @@ static int qspi_transfer(QspiDev_t *dev, const uint8_t *txData, uint32_t txLen,
chunkLen = writeLen;

while (chunkLen > 0 && ret == 0) {
uint32_t chunk = (chunkLen > 255) ? 255 : chunkLen;
/* Dual parallel stripes bytes across the two devices, so a chunk
* boundary must fall on an even byte count. */
uint32_t chunkMax = dev->stripe ? 254 : 255;
uint32_t chunk = (chunkLen > chunkMax) ? chunkMax : chunkLen;
chunkEntry = txEntry | GQSPI_GEN_FIFO_IMM(chunk);

ret = qspi_gen_fifo_push(chunkEntry);
Expand Down Expand Up @@ -1457,6 +1460,31 @@ void* hal_get_dts_update_address(void)
#endif
}

#if defined(EXT_ENCRYPTED) && defined(CUSTOM_ENCRYPT_KEY)
/* No key store is implemented for this target: these defaults fail, so an
* encrypted image does not boot until the platform supplies the key (eFuse,
* BBRAM or a PUF-wrapped store) by overriding wolfBoot_get_encrypt_key(). */
int WEAKFUNCTION wolfBoot_get_encrypt_key(uint8_t *key, uint8_t *nonce)
{
(void)key;
(void)nonce;
return -1;
}

int WEAKFUNCTION wolfBoot_set_encrypt_key(const uint8_t *key,
const uint8_t *nonce)
{
(void)key;
(void)nonce;
return -1;
}

int WEAKFUNCTION wolfBoot_erase_encrypt_key(void)
{
return -1;
}
#endif

#ifdef __WOLFBOOT
/**
* Fixup Device Tree before booting Linux
Expand Down Expand Up @@ -1499,6 +1527,16 @@ int hal_dts_fixup(void* dts_addr, uint32_t capacity)
}
#ifdef WOLFBOOT_UPDATE_DISK
(void)wolfBoot_disk_dts_fixup(&ctx);
#elif defined(WOLFBOOT_DUALBOOT) && defined(WOLFBOOT_FIXED_PARTITIONS)
if (wolfBoot_ramboot_part() >= 0) {
ret = fdt_fixup_chosen_val(&ctx, "wolfboot,boot-part",
(uint32_t)wolfBoot_ramboot_part());
if (ret != 0) {
wolfBoot_printf("FDT: Failed to set wolfboot,boot-part (%d)\n",
ret);
return ret;
}
}
#endif

return 0;
Expand Down
2 changes: 1 addition & 1 deletion hal/versal.ld
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ _HEAP_SIZE = DEFINED(_HEAP_SIZE) ? _HEAP_SIZE : 0x20000; /* 128KB heap */

_EL0_STACK_SIZE = DEFINED(_EL0_STACK_SIZE) ? _EL0_STACK_SIZE : 0x1000;
_EL1_STACK_SIZE = DEFINED(_EL1_STACK_SIZE) ? _EL1_STACK_SIZE : 0x2000;
_EL2_STACK_SIZE = DEFINED(_EL2_STACK_SIZE) ? _EL2_STACK_SIZE : 0x8000; /* Primary stack at EL2 */
_EL2_STACK_SIZE = DEFINED(_EL2_STACK_SIZE) ? _EL2_STACK_SIZE : 0x40000; /* Primary stack at EL2, sized for ML-DSA-87 verify */

/* Memory regions
* wolfBoot at 0x8000000 with 2MB allocated
Expand Down
3 changes: 3 additions & 0 deletions include/fdt.h
Original file line number Diff line number Diff line change
Expand Up @@ -375,6 +375,9 @@ int fdt_fixup_chosen_val(fdt_ctx* ctx, const char* name, uint32_t val);
int wolfBoot_disk_dts_fixup(fdt_ctx* ctx);
#endif

/* Slot (PART_BOOT / PART_UPDATE) the RAM-boot loader verified, or -1. */
int wolfBoot_ramboot_part(void);

/* Write /chosen/linux,initrd-{start,end} as 64-bit big-endian values,
* creating /chosen if needed. Returns 0 or a negative FDT_ERR_*. */
int fdt_fixup_initrd(fdt_ctx* ctx, uint64_t start, uint64_t size);
Expand Down
11 changes: 10 additions & 1 deletion include/image.h
Original file line number Diff line number Diff line change
Expand Up @@ -1797,7 +1797,16 @@ int keyslot_id_by_sha(const uint8_t *hint);
# define PART_IS_EXT(x) (!(x)->not_ext) && PARTN_IS_EXT(((x)->part))


#if defined(EXT_ENCRYPTED) && (defined(__WOLFBOOT) || defined(UNIT_TEST))
/* An MMU target that loads the image from external flash to RAM keeps the
* ciphertext in flash as written and decrypts it in RAM
* (wolfBoot_ram_decrypt), so flash access for headers and trailers is raw. */
#if defined(EXT_ENCRYPTED) && defined(MMU) && defined(EXT_FLASH) && \
defined(NO_XIP)
#define WOLFBOOT_RAM_DECRYPT_EXT
#endif

#if defined(EXT_ENCRYPTED) && !defined(WOLFBOOT_RAM_DECRYPT_EXT) && \
(defined(__WOLFBOOT) || defined(UNIT_TEST))
#define ext_flash_check_write ext_flash_encrypt_write
#define ext_flash_check_read ext_flash_decrypt_read
#else
Expand Down
7 changes: 6 additions & 1 deletion include/wolfboot/wolfboot.h
Original file line number Diff line number Diff line change
Expand Up @@ -790,6 +790,7 @@ extern "C" {

void wolfBoot_update_trigger(void);
void wolfBoot_success(void);
void wolfBoot_success_part(uint8_t part);
uint32_t wolfBoot_image_size(uint8_t *image);
uint32_t wolfBoot_get_blob_version(uint8_t *blob);
uint16_t wolfBoot_get_blob_type(uint8_t *blob);
Expand Down Expand Up @@ -822,6 +823,9 @@ int wolfBoot_clear_trailer(uint8_t part);

int wolfBoot_fallback_is_possible(void);
int wolfBoot_dualboot_candidate(void);
#ifdef WOLFBOOT_DUALBOOT_ROLLBACK_UNCONFIRMED
void wolfBoot_dualboot_erase_rejected(int active);
#endif

int wolfBoot_dualboot_candidate_addr(void**);
int wolfBoot_get_partition_state(uint8_t part, uint8_t *st);
Expand Down Expand Up @@ -905,7 +909,8 @@ int wolfBoot_record_failure(uint8_t phase, uint8_t cause, uint8_t partition,

#endif /* EXT_ENCRYPTED */

#if defined(EXT_ENCRYPTED) && defined(MMU)
#if defined(EXT_ENCRYPTED) && defined(MMU) && \
(defined(__WOLFBOOT) || defined(UNIT_TEST))
int wolfBoot_ram_decrypt(uint8_t *src, uint8_t *dst);
#endif

Expand Down
9 changes: 8 additions & 1 deletion options.mk
Original file line number Diff line number Diff line change
Expand Up @@ -1126,6 +1126,13 @@ ifneq ($(filter 1,$(DISK_SDCARD) $(DISK_EMMC)),)
endif
endif

# Dual-boot (two fixed slots, no swap): an image that was booted on probation
# and never confirmed is dropped in favour of the other slot even when that
# slot holds a lower version. Anti-rollback still applies to confirmed images.
ifeq ($(DUALBOOT_ROLLBACK_UNCONFIRMED),1)
CFLAGS+=-D"WOLFBOOT_DUALBOOT_ROLLBACK_UNCONFIRMED"
Comment on lines +1132 to +1133
endif

# Optional boot confirmation and rollback for disk boot (src/update_disk.c).
# wolfBoot marks the slot it boots as TESTING in the last sector of that raw
# partition; the OS clears it to SUCCESS once it is up. A slot still marked
Expand Down Expand Up @@ -2027,7 +2034,7 @@ endif
# Support external encryption cache
#
ifeq ($(ENCRYPT),1)
ifeq ($(ENCRYPT_CACHE),1)
ifneq ($(ENCRYPT_CACHE),)
CFLAGS+=-D"WOLFBOOT_ENCRYPT_CACHE=$(ENCRYPT_CACHE)"
endif
endif
Expand Down
Loading
Loading