Purpose of the SSBL

The purpose of the SSBL is to allow the customer to do the following:

• Add external flash support so that update image blobs can be saved on the external flash or be executed on the external XIP flash. 

NOTE: This reference code implements support for ATXP032/128 on the Cygnus Board.

• Use specific image authentication or crypto algorithms using the SHA256-HMAC and AES128 default settings or use proprietary image formats.
• Implement proprietary security policies.
• Implement value-added features such as dual image with active/standby support, boot from RAM, or encrypted flash-resident images.

 

Location of the SSBL

The location of the SSBL example (apollo3_sec_bl) in the AmbiqSuite SDK is in the folder:

ambiqsuite\boards\apollo3p_evb\examples\apollo3_sec_bl.

 

Dependency of testing the stock SSBL

The SSBL needs third party security library (MBEDTLS) support, and runs on the Apollo3 Blue Plus EVB with the Cygnus daughter board for access to external flash devices.

 

Software structure of the SSBL

The structure of the SSBL software is as follows: 

 

├── apollo3_secbl.c                           // main entry function

├── apollo3_secbl.h                          // allow the customer to define the main boot entry address or define the new auth and crypt algorithms.
├── apollo3_secbl_flash.c                // internal flash interface definition and flash interface management functions
├── apollo3_secbl_flash.h               // define the flash interface data structure, macros definition of start address and size of internal flash
├── apollo3_secbl_image.c            // implement the image and boot validation functions
├── apollo3_secbl_image.h
├── apollo3_secbl_info0.c             // define all info0 access functions
├── apollo3_secbl_info0.h            // macros for info0 area access
├── apollo3_secbl_mpsi_flash.h   // macros definition for start address and size of specific external flash (‘atxp032/128 flash’ as example).
├── apollo3_secbl_mspi_flash.c    // implement the SSBL flash interface of ‘atxp032/128 flash’
├── apollo3_secbl_secure.c           // wrap functions to the SHA256-HMAC and AES128 of MBEDTLS
├── apollo3_secbl_secure.h          // some macros can be used to customize the auth and crypt algorithm
├── filelist.txt
└── mbedtls_config.h                   // MBEDTLS configs customized for the usage

 

How to add support for a new external flash

Use the  ‘.h | .c’ as template code which is designed for ATXP032/128 on the Cygnus Board.  Redefine the flash interface as below.

Note: The start address of an erase operation should be sector (block) aligned.  The start address of a write operation should be page aligned.

 

 

Add the external flash interface to the framework by calling ‘ssbl_flash_add’ function.

 

 

How to add support for a new authentication and crypto algorithm

Note: If adding new auth and crypto, please add the new auth and crypt algorithm support to the image blob generation scripts, too.

Assign a new number to the the macros of auth and cryto algorithms in the ‘.h’.

Note: The default auth - SHA256_HMAC is 1, and the default crypt - ASE128 is 1.

 

Redefine the ‘DIGEST_SIZE’, ‘CRYPT_SIZE’, ‘IV’ in the ‘h’

 

• Redefine the auth and crypt functions in the ‘c’.
  • ssbl_auth_start
  • ssbl_auth_update
  • ssbl_auth_finish
  • ssbl_verify_signature
  • ssbl_crypt_init
  • ssbl_crypt_decrypt
• Redefine the auth key and kek get functions in the ‘c’.
  
  • ssbl_info0_get_auth_key
  • ssbl_info0_get_kek

Note: The key length or location for the custom keys may be different and defined at different locations of INFO0 by the customer himself.

 

How to test the SSBL

Following are the test preconditions:

• The IAR compiler will be used for the test.
• The SBL is non-SKU. (In order to debug SSBL, we need to use non-SKU SBL to do the test.)
• Assume that the OTA application will save an image blob at the internal flash address ‘0x30000’.
• The image blob will be installed at the external flash address ‘0x0400 0000’.
• The SSBL will transfer to external flash image to execute.

To prepare the SSBL for non-SKU SBL, make sure the code start address is ‘0xC000’ by checking the ‘icf’ file.  Confirm that the boot image start address is ‘0x0400 0000’ by checking ‘.h’.

 

 

Build and flash the ‘apollo3_secbl.bin’ to the ‘0xC000’.

Prepare the ‘INFO0’ image blob by going to the ‘ambiqsuite\tools\apollo3_scripts’ to run these commands.

• Create the info0.bin by running the command ‘py --valid 1 info0 -k keys_info0.py --pl 0 --u0 0x1C200c0 --u1 0xFFFF3031 --u2 0x2 --u3 0x0 --u4 0x0 --u5 0x0 --main 0xC000 --gpio 0x2f --version 2 --wTO 5000 -s 1 --chipType apollo3p’
• Flash the ‘info.bin’ to the info0 area by running the command ‘JLink.exe -device AMA3B2KK-KBR -CommanderScript jlink-prog-info0.txt’.  The jlink-prog-info0.txt file is shown below and attached.

// connect to device
// NEED to specify -device AMA3B2KK-KBR (for Apollo3P) or -device AMA3B1KK-KBR/KCR 
// (for Apollo3) from command line
si SWD
speed 1000
r
sleep 10

//set C runtime environment
wreg MSP, 0x10000100

// erase info0
w4 0x10000000 0 // flash info instance
w4 0x10000004 0xd894e09e // info 0 key
w4 0x10000008 0xFFFFFFFF // clear return value
setPC 0x08000085 // call the ROM helper function flash_info_erase_from_sram
g
sleep 50
mem32 0x10000008 1 // dump return value for check

// program info0
w4 0x10000000 0 // flash info instance
w4 0x10000004 0 // offset
w4 0x10000008 0x800 // length in words
w4 0x1000000C 0xd894e09e // info 0 key
w4 0x10000010 0xFFFFFFFF // clear return value
loadbin info0.bin 0x10001000 //load the info0 binary into sram
setPC 0x08000061 // call the ROM helper function flash_program_info_area_from_sram
g
sleep 50
mem32 0x10000010 1 // dump return value for check

// perform software POI
w4 0x40000004 0x1B

// quit
qc

 

Prepare the test application binary using the following steps.

Note: replace the hardcode directory with yours.

• Use the ‘hello_world’ as the test example.
• Change the icf to redefine the code start address as‘0x0400 0100’ and build the test application.
• Run the command “py --bin C:\code\ambiq\ambiqsuite\boards\common3\examples\hello_world\iar\bin\hello_world.bin -k keys_info0.py --load-address 0x04000000 --magic-num 0xC0 -o hello_world_secure_0x04000000 --version 0x3 --kek 8 --authkey 10 --encalgo 1 --authalgo 1 --authB 1 --crcB 1 --authI 1 --loglevel 5” to add auth and crypt information header to the binary.

 

Use the jlink script ‘jlink-prog-ota-img.txt’ to load the binary to the ‘0x30000’ and create a customized OTA descriptors list at internal flash address ‘0xFA100’ (customer can choose any valid flash address without conflicting with SSBL). run the command ‘exe -device AMA3B2KK-KBR -CommanderScript jlink-prog-ota-img.txt’.  The jlink-prog-ota-img.txt file is shown below and attached.

//connect to device
device AMA3B2KK-KBR
si SWD
speed 1000
r
sleep 10

// Load hello world secure image
// loadbin hello_world_secure_80000.bin 0x30000

loadbin hello_world_secure_0x04000000.bin 0x30000

// Set up Customer Specific Secondary OTA Descriptor image blob at 0xFA100 (just an example)
w4 0xFA100 0xC100000C // Magic 0xC1, length 12 Bytes
w4 0xFA104 0x30003 // OTA image pointer ¨C last 2 bits 1
w4 0xFA108 0xFFFFFFFF // end of list

w4 0xFA000 0xFA103 // address of 0xC1 image ¨C last 2 bits 1
w4 0xFA004 0xFFFFFFFF // end of list

// Set up OTA Descriptor at 0xFA000
// w4 0xFA000 0x30003
// w4 0xFA004 0xFFFFFFFF

// Set up OTAPointer
w4 0x40020264 0xFA001

// Reset POI
w4 0x40000004 0x1B

// quit
qc

 

If every step is correct, you will see the below output information:

 

How to prepare the secondary customized OTA descriptors

The SBL and SSBL need OTA descriptors to know the location of the image blobs.  During the test, a jlink script is used to create a OTA descriptors.  For production, OTA application should prepare these OTA descriptors.  All OTA descriptors should be kept in the internal flash (so SBL can access).

The OTA descriptor which points to image blobs locating in the internal flash and uses default auth and crypt should be kept in the first level OTA descriptor list.  These descriptors will be handled by SBL.  The OTA descriptor which points to the image blobs located in the external flash and uses non-default auth and crypt should be kept in the second level OTA descriptor list file (image type is “0xC1”). 

One item in the first level descriptor points to the second level OTA descriptor list file.  The SSBL will handle the OTA descriptor list in the second level OTA descriptor list file.

 

Use the test jlink script as example.  At the internal flash address 0xFA000, the first item points to the customer-specific OTA descriptor list file image blob at internal flash address 0xFA100.  SSBL can get the real OTA descriptor ‘0x30000’ after the customer-specific image header.  Even though this image blob is located in internal flash, its installation address is located in external flash (MSPI1 as an example) “0x04000000”, so it should be put in the second level OTA descriptor list file.

This customer-specific OTA descriptor file definition can be found in ‘apollo3_secbl.h’.

 

The install image blob can be put in the external flash by the OTA application, which could be normal use case.  For this use case we can define the OTA descriptor like below to be saved at the external MSPI flash address “0x0400 0000”).

 

 

How to handle the address of IOM external flash

For MSPI flash, we can use the below address mapping to identify the flash interface.  

 

Since flash erase, write and read use the offset address, the flash interface driver can get the offset by subtracting this start address in the following code.

 

 

The IOM external flash address can’t be mapped into the MCU bus address like MSPI.  We still need to assign a “virtual address” to point SSBL to the external flash in this case.  In other words, we can simply fix the two most significant bits in the 32-bit OTA address.  A descriptor like “0b10” can be defined to identify an external IOM flash.  Address ”0x8000 0000“ will be the start address of this external flash.  Every place which needs this information to identify a specific offset within the IOM external flash (i.e. the OTA image pointers) should add “0x8000 0000” to the offset.

IOM flash driver code should like below:

 

The OTA descriptor should look like below:

 

Finally, the load address in the image header should look like below:

create_cust_image_blob.py --bin 
C:\code\ambiq\ambiqsuite\boards\common3\examples\hello_world\iar\bin\hello_world.bin -k 
keys_info0.py --load-address 0x80000000 --magic-num 0xC0 -o hello_world_secure_0x04000000 
--version 0x3 --kek 8 --authkey 10 --encalgo 1 --authalgo 1 --authB 1 --crcB 1 --authI 1 
--loglevel 5