Skip to content

L. wolfCrypt in TrustZone-M secure domain

wolfCrypt in TrustZone-M secure domain

ARMv8-M microcontrollers support hardware-assisted domain separation for running software. This TEE mechanism provides two separate domains (secure & non-secure), and an additional zone that can be used as interface to call into secure functions from the non-secure domain (non-secure callable).

wolfBoot may optionally export the crypto functions as a non-callable APIs that are accessible from any software staged in non-secure domain.

Compiling wolfBoot with wolfCrypt in TrustZone-M secure domain

When wolfBoot is compiled with the options TZEN=1 and WOLFCRYPT_TZ=1, a more complete set of components of the wolfCrypt crypto library are built-in the bootloader, and they can be accessed by applications or OSs running in non-secure domain through non-secure callable APIs.

This feature is used to isolate the core crypto operations from the applications.

PKCS11 API in non-secure world

The WOLFCRYPT_TZ_PKCS11 option provides a standard PKCS11 interface, including a storage for PKCS11 objects in a dedicated flash area in secure mode.

This means that applications, TLS libraries and operating systems running in non-secure domain can access wolfCrypt through a standard PKCS11 interface and use the crypto library with pre-provisioned keys that are never exposed to the non-secure domain.

Example using STM32L552

  • Copy the example configuration for STM32-L5 with support for wolfCrypt in TrustZone-M and PKCS11 interface: cp config/examples/stm32l5-wolfcrypt-tz.config .config

  • Run make. wolfboot.elf and the test applications are built as separate objects. The application is signed and stored as test-app/image_v1_signed.bin.

  • Ensure that the option bytes on your target device are set as follows:

OPTION BYTES BANK: 0

   Read Out Protection:

     RDP          : 0xAA (Level 0, no protection)

   BOR Level:

     BOR_LEV      : 0x0 (BOR Level 0, reset level threshold is around 1.7 V)

   User Configuration:

     nRST_STOP    : 0x1 (No reset generated when entering Stop mode)
     nRST_STDBY   : 0x1 (No reset generated when entering Standby mode)
     nRST_SHDW    : 0x1 (No reset generated when entering the Shutdown mode)
     IWDG_SW      : 0x1 (Software independant watchdog)
     IWDG_STOP    : 0x1 (IWDG counter active in stop mode)
     IWDG_STDBY   : 0x1 (IWDG counter active in standby mode)
     WWDG_SW      : 0x1 (Software window watchdog)
     SWAP_BANK    : 0x0 (Bank 1 and bank 2 address are not swapped)
     DB256        : 0x1 (256Kb dual-bank Flash with contiguous addresses)
     DBANK        : 0x0 (Single bank mode with 128 bits data read width)
     SRAM2_PE     : 0x1 (SRAM2 parity check disable)
     SRAM2_RST    : 0x1 (SRAM2 is not erased when a system reset occurs)
     nSWBOOT0     : 0x1 (BOOT0 taken from PH3/BOOT0 pin)
     nBOOT0       : 0x1 (nBOOT0 = 1)
     PA15_PUPEN   : 0x1 (USB power delivery dead-battery disabled/ TDI pull-up activated)
     TZEN         : 0x1 (Global TrustZone security enabled)
     HDP1EN       : 0x0 (No HDP area 1)
     HDP1_PEND    : 0x0  (0x8000000)
     HDP2EN       : 0x0 (No HDP area 2)
     HDP2_PEND    : 0x0  (0x8000000)
     NSBOOTADD0   : 0x100000  (0x8000000)
     NSBOOTADD1   : 0x17F200  (0xBF90000)
     SECBOOTADD0  : 0x180000  (0xC000000)
     BOOT_LOCK    : 0x0 (Boot based on the pad/option bit configuration)

   Secure Area 1:

     SECWM1_PSTRT : 0x0  (0x8000000)
     SECWM1_PEND  : 0x39  (0x8039000)

   Write Protection 1:

     WRP1A_PSTRT  : 0x7F  (0x807F000)
     WRP1A_PEND   : 0x0  (0x8000000)
     WRP1B_PSTRT  : 0x7F  (0x807F000)
     WRP1B_PEND   : 0x0  (0x8000000)
OPTION BYTES BANK: 1

   Secure Area 2:

     SECWM2_PSTRT : 0x7F  (0x807F000)
     SECWM2_PEND  : 0x0  (0x8000000)

   Write Protection 2:

     WRP2A_PSTRT  : 0x7F  (0x80BF000)
     WRP2A_PEND   : 0x0  (0x8040000)
     WRP2B_PSTRT  : 0x7F  (0x80BF000)
     WRP2B_PEND   : 0x0  (0x8040000)
  • Upload wolfboot.bin and the test application to the two different domains in flash:
STM32_Programmer_CLI -c port=swd -d wolfboot.bin 0x0C000000
STM32_Programmer_CLI -c port=swd -d test-app/image_v1_signed.bin 0x08040000
  • After rebooting, the LED on the board should turn on sequentially:
    • Red LED: Secure boot was successful. Application has started.
    • Blue LED: PKCS11 Token has been initialized and stored
    • Green LED: ECDSA Sign/Verify test successful

Example using STM32H563

  • Copy one of the example configurations for STM32H5 with support for TrustZone and PKCS11 to .config: cp config/examples/stm32h5-tz.config .config cp config/examples/stm32h5-tz-dualbank-otp.config .config (with Dual Bank) cp config/examples/stm32h5-tz-dualbank-otp-lms.config .config (with Dual Bank and PQ LMS)

  • Run make. wolfboot.elf and the test applications are built as separate objects. The application is signed and stored as test-app/image_v1_signed.bin.

  • Ensure that the option bytes on your target device are set as follows:

OPTION BYTES BANK: 0

   Product state:

     PRODUCT_STATE: 0xED (Open)

   BOR Level:

     BOR_LEV      : 0x0 (BOR Level 1, the threshold level is low (around 2.1 V))
     BORH_EN      : 0x0  (0x0)

   User Configuration:

     IO_VDD_HSLV  : 0x0  (0x0)
     IO_VDDIO2_HSLV: 0x0  (0x0)
     IWDG_STOP    : 0x1  (0x1)
     IWDG_STDBY   : 0x1  (0x1)
     BOOT_UBE     : 0xB4 (OEM-iRoT (user flash) selected)
     SWAP_BANK    : 0x0  (0x0)
     IWDG_SW      : 0x1  (0x1)
     NRST_STOP    : 0x1  (0x1)
     NRST_STDBY   : 0x1  (0x1)
OPTION BYTES BANK: 1

   User Configuration 2:

     TZEN         : 0xB4 (Trust zone enabled)
     SRAM2_ECC    : 0x1 (SRAM2 ECC check disabled)
     SRAM3_ECC    : 0x1 (SRAM3 ECC check disabled)
     BKPRAM_ECC   : 0x1 (BKPRAM ECC check disabled)
     SRAM2_RST    : 0x1 (SRAM2 not erased when a system reset occurs)
     SRAM1_3_RST  : 0x1 (SRAM1 and SRAM3 not erased when a system reset occurs)
OPTION BYTES BANK: 2

   Boot Configuration:

     NSBOOTADD    : 0x80400  (0x8040000)
     NSBOOT_LOCK  : 0xC3 (The SWAP_BANK and NSBOOTADD can still be modified following their individual rules.)
     SECBOOT_LOCK : 0xC3 (The BOOT_UBE, SWAP_BANK and SECBOOTADD can still be modified following their individual rules.)
     SECBOOTADD   : 0xC0000  (0xC000000)
OPTION BYTES BANK: 3

   Bank1 - Flash watermark area definition:

     SECWM1_STRT  : 0x0  (0x8000000)
     SECWM1_END   : 0x1F  (0x803E000)

   Write sector group protection 1:

     WRPSGn1      : 0xFFFFFFFF  (0x0)
OPTION BYTES BANK: 4

   Bank2 - Flash watermark area definition:

     SECWM2_STRT  : 0x7F  (0x81FE000)
     SECWM2_END   : 0x0  (0x8100000)

   Write sector group protection 2:

     WRPSGn2      : 0xFFFFFFFF  (0x8000000)
OPTION BYTES BANK: 5

   OTP write protection:

     LOCKBL       : 0x0  (0x0)
OPTION BYTES BANK: 6

   Flash data bank 1 sectors:

     EDATA1_EN    : 0x0 (No Flash high-cycle data area)
     EDATA1_STRT  : 0x0  (0x0)
OPTION BYTES BANK: 7

   Flash data bank 2 sectors :

     EDATA2_EN    : 0x0 (No Flash high-cycle data area)
     EDATA2_STRT  : 0x0  (0x0)
OPTION BYTES BANK: 8

   Flash HDP bank 1:

     HDP1_STRT    : 0x1  (0x2000)
     HDP1_END     : 0x0  (0x0)
OPTION BYTES BANK: 9

   Flash HDP bank 2:

     HDP2_STRT    : 0x1  (0x2000)
     HDP2_END     : 0x0  (0x0)
  • Upload wolfboot.bin and the test application to the two different domains in flash:
STM32_Programmer_CLI -c port=swd -d wolfboot.bin 0x0C000000
STM32_Programmer_CLI -c port=swd -d test-app/image_v1_signed.bin 0x08040000
  • After rebooting, the LED on the board should turn on sequentially:
    • Red LED: Secure boot was successful. Application has started.
    • Blue LED: PKCS11 Token has been initialized and stored
    • Green LED: ECDSA Sign/Verify test successful