JY Secure Boot Desgin

JY Secure Boot Desgin

Introduction

Purpose

Secure boot is one of the most important secure features for IoT/AIoT devices. It supplies the authenticity, integrity, and optional confidentiality of device images. With secure boot, devices can be controlled to run authorized images and execute specified functionalities.

Arm China secure boot solution leverages the lightweight cryptographic algorithms, compact data structures and simplified verified boot flow for resource-constrained IoT devices.

Key Features

JIAYU secure boot has the following features:

1. Configurable signing algorithms including RSA, ECDSA, SM2.

2. Configurable hash algorithms including SHA256, SHA512, SM3.

3. Configurable cipher algorithms including AES/SM4-ECB, AES/SM4-CBC, AES/SM4-CTR.

4. Multi-level boot chains.

5. Signing flow, which packs and signing the scattered images to all-in-one package.

6. Referenced universal bootloader (UBL).

7. Online and offline mode, which supports changing keys from production stage to developing stage.

Note:

1. The cipher algorithms are used in image encryption.

Overview

Two Stages

We define two stages of using JIAYU secure boot solution:

1. The developing stage. In this stage, customers are bringing up their chips or developing their device images, customers can use secure boot tool and secure boot core to customize their secure boot solution, such as selecting crypto algorithms, porting secure boot core.

2. The producing stage. In this stage, customers want to release their SDK or device images to others for making a real production. In this stage, customers can use secure boot online or offline mode to replace the signing key or image encryption keys for the real product, and also doesn’t touch the detailed implementation of secure boot solutions. Also, customers can use secure boot tool/secure boot core directly in this stage.

Secure boot tool and secure boot core

The secure boot tool and secure boot core are two basic components in JIAYU secure boot.

Secure boot tool is an executable tool, it runs on host side in offline mode, and SaaS side in online mode. The secure boot tool has the following functions:

1. Generating manifest file. Manifest is the metadata that describes the secure boot configurations. Details about manifest see section 5.3.

2. Generating secure boot public key hash.

3. Encrypting images.

4. Verifying or Examining manifest file.

Secure boot core runs on device, it verifies the manifest and images. There is hardware adaption layer (HAL) to port the secure boot core to different software environments, such as BootROM, bootloader.

Multi-level secure boot

Secure boot helper tool is used to pack all scattered images to one zipped package, and iteratively call secure boot tool to generate each level’s manifest. Besides, it also supports customer defined script to post process the zipped package, such as signing it.

Online and Offline mode

JIAYU secure boot supports both online mode and offline mode for generating signed package.

In online mode, all keys, including signing key and model key are deployed on secure boot SaaS, and no secret is leaked to developing environment or out of SaaS.

JIAYU secure boot online mode also supports generating manifests independently.

In offline mode, local secret keys are used, and no SaaS dependency is required.

UBL

JIAYU secure boot also includes one referenced universal bootloader (UBL), and from which customers can generate different images, such as BootROM, bootloader. The UBL is always using bare metal environment, no scheduler and interrupt handling is supported.

The UBL has the following features:

1. Support multi architectures:

   1. ARM32 bit (including ARMv7 and ARMv8 AARCH32)

   2. ARM64 bit (ARMv8 AARCH64)

   3. ARM-M (Cortex-M MCUs)

2. Platform portable.

3. Configurable. The UBL has about 20 configurations.

4. Secure boot core embedded.

5. Secure debug agent embedded.

6. Provisioning agent embedded.

7. Mbedtls embedded.

8. Low power supported.

9. Multi core (SMP) supported.

Note:

1. Architecture of ARM-M not test.

2. SMP and Low power not test.

Low Level Design

Secure boot architecture

JIAYU secure boot supplies a customized security solution for AIoT devices. The following two figures show the general architecture of JIAYU secure boot.

Secure boot host side architecture Note:

1. Secure boot online mode includes Signing SaaS and Secure Boot SaaS, and the signing tool and secure boot tool are integrated into the two SaaS.

2. In secure boot online mode, keys are indicated by key hints file.

3. In secure boot offline mode, keys are provided by key configuration file.

Secure boot device side architecture

On host side, the signing tool extract the input source package and re-signing with new keys to generate final signed package. This may happen on secure boot SaaS/signing SaaS or offline environment, and the associated solution is called online or offline secure boot.

The following describes the steps of host side operations:

1. Signing tool extracts the input source package, parses the multi-level secure boot configuration file and input key configuration file or key hints file, and generates several manifest/key descriptor files. Details about source package see section 4.8 signing tool.

2. The signing SaaS or offline signing tool replaces the new keys via key configuration file or key hints file. The keys include secure boot signing keys, model key (used by image encryption).

3. Signing tool calls the secure boot tool to generate manifests with boot chain sequence from bottom to top.

4. Signing tool also pack binaries and manifests to ZIP container as signed package.

On device side, secure boot core in different boot images verifies the next boot level’s images. There are HAL layer to port secure boot core to different images.

Besides, customers can also use secure boot tool and secure boot core all alone to port secure boot to their platform.

Secure boot usage

We suggest using secure boot in the following two stages:

Stage 1: The developing stage. This stage mostly happens in device developing or chip bring up. In this stage, developing engineers do the following steps to enabling JIAYU secure boot to their product:

1. Designing/Customizing their multi-level secure boot solution. For example, how many levels in their secure boot chain.

2. Porting secure boot core to their device images. This mainly includes HAL and OSAL.

3. Creating sample signing keys and model key to try the secure boot solution.

4. And finally, generating one signed package.

Also, this stage can use all features of secure boot.

Stage2: The production stage. This stage mostly happens in products production, or device manufacturers. This stage doesn’t care the detailed technology of secure boot or implementation of secure boot, but they should care about the keys used in secure boot. In this stage, we provide online/offline mode for customers to change the secure boot keys without touching secure boot configurations.

Developing Stage Flow

The flow in this stage are:

1. Designing the multi-level secure boot solution.

2. Initialize the secure boot configurations and developing sample keys.

3. Generate manifests for each level of secure boot chain.

4. Create one multi-level secure boot configuration file from the secure boot configurations.

5. Generate one signed package.

The following figure is one example:

Production Stage Flow

1. Extract the source package.

2. Parses the multi-level secure boot configuration file and generate to several manifest/key descriptors.

3. Parses the key configuration or key hints file and initializes the new keys for secure boot.

4. With new keys, generate manifest binaries with secure boot tool or Multi-level secure boot tool.

5. Pack the manifest binaries, images and developing model key to one source package.

6. Sign the source package with signing tool.

The following figure is one example:

Secure boot tool

Secure boot tool is a host executable tool which supplies the following functions:

1. Generate manifest.

2. Verify manifest.

3. Generate public key hash.

Usage

The following is secure boot tool’s usage command:

secure_boot_tool [function] [options]

“function” specifies the secure boot tool’s function, can be one of:

Function Name	Description
GEN	Generate manifest, public key hash, and all secure boot covered images (including encrypted images).
TRUSTROOT	Generate the public key hash file from PEM format public key.
VERIFY	Verify manifest.

Each function requires different parameters. The following sections describe details about each function.

Besides, there are some common options:

Options Name	Description	Available Functions
-v	Enable verbose mode and output more logs. By default, the secure boot tool’s log level is INFO. If verbose mode is enabled, the log level is changed to DEBUG.	Available for all functions.
-V	Print the secure boot tool’s version and quit.	No function name is required.
-h	Print the secure boot tool’s usage and quit.	No function name is required.

GEN Function

This function is used to generate manifest file as well as the secure boot covered images. This requires two descriptor files to config the parameters:

1. Key descriptor. The key descriptor file contains secure key related configurations, such as the signing key, image encryption configurations.

2. Manifest descriptor. The manifest descriptor file contains image related configurations, such as image’s address, version.

The GEN function flows are:

1. Parse the descriptor files and check parameters.

2. For each input image file, calculate the hash value.

3. For each input image file, do image encryption if enabled.

4. Assemble to manifest file.

5. Sign the manifest file.

Parameters for GEN function are:

Parameter Name	Description	Constrains	Example
-keydesc	Specify the key descriptor file.	• The key descriptor file MUST be a JSON format file. • Details about key descriptor see section Key Descriptor.	./key_desc.json
-mnftdesc	Specify the manifest descriptor file.	• The manifest descriptor file MUST be a JSON format file. • Details about key descriptor see section Manifest Descriptor.	./mnft_desc.json
-pwd	The private key password file.	• Optional. • The password has no length constrain. • All characters in the password file should be printable (>= 0x21 && <= 0x7E)	./pwd.txt
-plugin	Customer implemented image encryption plugin library.	• Optional. • If supplied, will overwrite the default image encryption method. • Details see image encryption.	./libimg_enc.so
-out	Specify the output path.	• If output folder doesn’t exit, will create it.	./out

4.3.2.1 Key Descriptor

The following table describes the detailed format in key descriptor file:

Key Name	Value Type	Description	Constrains
security_config	JSON sub-item	Describes the basic secure configurations for secure boot.	• All sub-items in security config are mandatory.
manifest_signing_ key	String	Specify the asymmetric private key file of signing the manifest.	• The key file MUST be PEM format. • Only support: 1. RSA key with 2048/4096/8192 key size.
			2. EC key with NIST256/NIST521 curve type. 3. SM2 key.
manifest_signing_ algorithm	String	Specify the manifest signing algorithm.	• The signing algorithm MUST be aligned with the key type. • Only support: 1. RSASSA_PKCS_V15_SHA256 2. RSASSA_PKCS_V15_SHA512 3. RSASSA_PKCS_V21_SHA256 4. RSASSA_PKCS_V21_SHA512 5. ECDSA_SHA256 6. ECDSA_SHA512 7. SM2_DSA_SM3
public_key_hash_ algorithm	String	Specify the public key hash algorithm.	• The public key hash algorithm MUST be aligned with that in HAL implementation of secure boot core. • Only support: 1. SHA256 2. SHA512 3. SM3
image_hash_algori thm	String	Specify the image’s hash algorithm.	• Only support: 1. SHA256 2. SHA512 3. SM3
image_encryption _config	JSON sub-item	Describes the image encryption’s configurations.	• All sub-items in security config are optional. • If image encryption config is supplied, all sub-items within this configuration should be supplied.
encryption_algorit hm	String	Specify the image encryption algorithm.	Only support: 1. AES-ECB 2. AES-CBC 3. AES-CTR 4. SM4-ECB 5. SM4-CBC 6. SM4-CTR
model_key_file	String	Specify the model key file.	• The file contains raw binary data of model key. • The file size should be 16 Bytes, which is the model key size.
key_blob	String	User supplied data to scramble the image encryption key.	• Min 1 Byte. • Max 255 Bytes. • All characters in the keyblob should be printable (>= 0x21 && <= 0x7E)

4.3.2.2 Manifest Descriptor

The following table describes the detailed format in manifest descriptor file:

Key Name	Value Type	Description	Constrains
manifest_config	JSON sub-item	Describes the basic configurations for secure boot.	•	All sub-items in security config are mandatory.
format_version	Integer	The manifest format version.	•	Currently MUST be 2.
manifest_version	Integer	The manifest version.	•	The manifest version should >= that version read from HAL in secure boot core. For the first level of secure boot, the manifest version may be stored in OTP.
is_enable	Bool	Whether the manifest is used in developing mode, that is: all the verification is skipped.
images	Array	Describes the secure boot covered images.
extended_program	String	Specify the extended program binary file.	• • •	Optional, this item can be non-existent. The extended program size MUST be aligned with 4 Bytes. The max extended program size is 512 Bytes.

The following table describes one image format:

Key Name	Value Type	Description	Constrains	Example
name	String	The image’s name identification.	• Max name string length is 7 (exclude the string ender ‘\0’). • Min name string length is 1. • The characters MUST be: [0-9], [a-z], [A-Z], _.	bl_31
encryption	Bool	Whether this image is encrypted.	• Optional. This item can be non-existent. If not exist, this image is unencrypted. • If enabled, the image encryption configuration in key descriptor MUST be exist. • If enabled, the image must NOT be XIP.	true
xip	Bool	Whether this image is XIP (eXecute In Place).	• Optional. This item can be non-exist. If not exist, this image is NOT XIP. • If enabled, the image must NOT be encrypted. • If enabled, the image must have static_address. That means, the image must NOT be embedded data. • If enabled, the image’s static_address MUST equal to the load_address.	false
flags	String	Customized Image Flags.	• Optional. If not exist, this images’ flags are read as 0 in secure boot core API. • MUST be hex string with “0x” prefix. • Can be converted to 32 bit hex value.	“0x12345678”
static_address	String	Specify the image’s static address. (LMA)	• Optional. This item can be non-existent. If not exist, this image is treading as an embedded data (typically the next level’s secure boot public key hash). • MUST be hex string with “0x” prefix. • Can be converted to 64 bit address.	“0x000000000000F000”
			The static address shouldn’t be overflowed with image size. That is: static_addr < static_addr + image_size.
			Customers should make sure each image’s [static_address, static_address + image_size/encrypted_image_size] are not overlapped. The encrypted_image_size is encrypted image size if image encryption is enabled.
load_address	String	Specify the image’s load address. (VMA)	Mandatory. One image must have load_address. MUST be hex string with “0x” prefix. Can be converted to 64 bit address. The load address shouldn’t be overflowed with image size. That is: load_addr < load_addr + image_size. Customers should make sure each image’s [load_address, load_address + image_size/encrypted_image_size] are not overlapped. The encrypted_image_size is encrypted image size if image encryption is enabled.	“0x000000000007F000”
entry_address	String	Specify the image’s entry address. (VMA)	Optional. This item can be non-existent. MUST be hex string with “0x” prefix. Can be converted to 64 bit address. The entry address should within: [load_addr, load_addr + img_size]	“0x000000000007F004”
file	String	Specify the image file.	The image file should be exist. If image’s static_address not exist (The image is embedded data), the image’s max size is 4096 Bytes.	“./tee.bin”

TRUSTROOT Function

This function is used to generate the public key hash file from PEM format public key or private key. The public key hash is the trust root of secure boot.

Parameters for TRUSTROOT function are:

Parameter Name	Description	Constrains	Example
-key	The input private or public key file.	• The key file MUST be PEM format. • Can be public key or private key. • Only support: 1. RSA key with 2048/4096/8192 key size. 2. EC key with NIST256/NIST521 curve type. 3. SM2 key.	rsa_2048_priv.pem
-scheme	Specify the public key hash algorithm.	• Available strings: 1. SHA256 2. SHA512 3. SM3	SHA256
-pwd	The private key password file.	• Optional, only necessary for private key that requires password.	./pwd.txt
		The password has no length constrain.
		The password has no length constrain.	The password has no length constrain.
-out	Specify the output folder to save public key hash file.	If output folder doesn’t exit, will create it.	./out

VERIFY Function

This function can be used to verify or check the manifest. If the public key hash file is supplied, it will also verify the public key in manifest.

Note: The VERIFY function doesn’t verify/check the images.

The verifying flow uses the following constant values:

1. Manifest version 0.

2. Lifecycle CM.

Parameters for VERIFY function are:

Parameter Name	Description	Constrains	Example
-mnft	The input manifest binary file.	• Must be exist.	manifest.bin
-hash	The input public key hash file.	• Optional. If not exist, the verification of public key in manifest is skipped. • The public key hash file can be generated by TRUSTROOT or GEN function.	pubkey_hash.bin

Return Code

Code	Description
0	Success
1	Bad parameter
2	Malloc memory failed
3	File operation failed
4	Verify manifest failed
100	Internal error

Secure boot core

Secure boot core is the main secure boot logic running on devices. It performs the following functions:

1. Verifying the asymmetric public key in the manifest. The trusted secure boot public key hash is read in HAL, customers can save the secure boot public key hash in trusted area, such as Fuse/OTP.

2. Verifying the manifest. The manifest is signed by the asymmetric private key. The signature and asymmetric public key are saved in the manifest.

3. Verifying and executing the extended program if any. The verification of the extended program is covered by the manifest, and the execution of extended program is also handled by HAL.

4. Decrypting the images if the image encryption is enabled.

5. Verifying the images. The digest of each image is saved in the manifest, and only the digest of image which matches the one in the manifest is a valid image.

The secure boot core should be a shared code which is portable to BootROM, Bootloader, and other software. To be portable, the secure boot core is designed to be:

1. HAL and OSAL dependent. Customers can implement the HAL and OSAL APIs to port secure boot core to their SW environment, besides, it doesn’t depend on any other libraries or functions.

2. Configurable. Secure boot core is configurable to support particular crypto algorithms, such as ECDSA only, so that memory footprint can be saved.

3. Debug enabled. There is both dynamic and static log level in OSAL LOG.

4. Image encryption method customized. Customers can overwrite the image encryption functions in secure boot core to use their image encryption method.

For the system safety, it is recommended that secure boot core be integrated into BootROM, as the first boot image solidified in read-only memory during the manufacturing stage. The following pictures describes the overall flows of secure boot core:

The following pictures describes details flows of secure boot core:

Flow #1: check secure boot enabled.

Flow #2: verify manifest header.

Flow #3: Verify manifest.

Flow #4: Verify images and update versions.

APIs

4.4.1.1 Types

The following describes the secure boot core APIs.

typedef void *secure_boot_ctx_t;

The secure boot context. It is used to store context data which is shared across multiple APIs.

typedef struct _secure_boot_image_info_t { char *name; uint64_t static_addr; void *loading_addr; void *entry_addr; size_t size; bool encryption; bool xip; uint32_t flags;

} secure_boot_image_info_t;

The image information structure. The caller can get each image’s information with secure_boot_core_get_image_info_by_idx or secure_boot_core_get_image_info_by_name API. The image info is only valid within a valid secure boot context.

name: Image’s name, which matches that in manifest descriptor. static_addr: Image’s static address. 0xFFFFFFFF or 0xFFFFFFFFFFFFFFFF if the image is embedded. loading_addr: Image’s loading address.. entry_addr: Image’s entry address. 0xFFFFFFFF or 0xFFFFFFFFFFFFFFFF if doesn’t have. size: Image’ size. It is decrypted data size if this image is encrypted. encryption: Identifies whether the image is encrypted. xip: Identifies whether the image is XIP. flags: Customer defined 32bit flags in manifest descriptor file.

4.4.1.2 Functions

osal_err_t secure_boot_core_init(secure_boot_ctx_t *context);

This is the secure boot core’s initialization function. This is the first function to be called in secure boot core. it initializes the resources for the secure boot core and allocates one context for latter APIs’ usage.

void secure_boot_core_cleanup(secure_boot_ctx_t context);

This is the secure boot core’s cleanup function. This is the last function to be called in secure boot core. It destroys and frees all the resources and the context used by the secure boot core.

osal_err_t secure_boot_core_verify(secure_boot_ctx_t context);

This is the secure boot core’s main process function. It is called after the secure_boot_core_init function and before secure_boot_core_cleanup. This function performs all the secure boot authentications, including verifying public key hash, verifying the manifest and verifying images.

osal_err_t secure_boot_core_get_image_number(secure_boot_ctx_t context, uint32_t *img_num);

The function must be called after secure_boot_core_verify returns OSAL_SUCCESS. It returns the number of the images which pass the verification.

osal_err_t secure_boot_core_get_image_info_by_idx(

secure_boot_ctx_t context, uint32_t img_id, secure_boot_image_info_t *info);

The function must be called after secure_boot_core_verify returns OSAL_SUCCESS. It returns the information about the image which has index of img_id. The image index is the array index in the manifest descriptor when generating manifest.

Note: the pointers in the image info are only valid when the secure boot context is valid, that is, using image info with cleanuped secure boot context is illegal.

osal_err_t

secure_boot_core_get_image_info_by_name(secure_boot_ctx_t context, const char *name,

secure_boot_image_info_t *info);

The function must be called after secure_boot_core_verify returns OSAL_SUCCESS. It returns the information about the image which has the name in parameter. The image name matches that in the manifest descriptor when generating manifest.

HAL Dependency

The secure boot core depends on the following HAL APIs:

HAL_API bool hal_secure_boot_is_enabled(void);

HAL_API osal_err_t hal_secure_boot_read_manifest(uint8_t *buf, size_t size); HAL_API osal_err_t hal_secure_boot_read_trust_pubkey_hash(uint8_t *data,

size_t *size);

HAL_API osal_err_t hal_secure_boot_read_lcs(uint32_t *lcs);

HAL_API osal_err_t hal_secure_boot_write_manifest_version(uint32_t version);

HAL_API osal_err_t hal_secure_boot_read_manifest_version(uint32_t *version);

HAL_API osal_err_t hal_secure_boot_run_extended_program(uint8_t *ext_prog,

size_t ext_prog_size);

Details about HAL API see HAL document.

Mbedtls Dependency

The secure boot core depends on the following Mbedtls APIs:

Rsa/ecdsa/sm2dsa.h

Crypto Configurations

Each crypto algorithm can be enabled via configurations:

Name	Description
CAL_ENABLE_SHA1	Enable SHA1
CAL_ENABLE_SHA256	Enable SHA256
CAL_ENABLE_SHA512	Enable SHA512
CAL_ENABLE_SM3	Enable SM3
CAL_ENABLE_AES	Enable AES
CAL_ENABLE_SM4	Enable SM4
CAL_ENABLE_RSA	Enable RSA
CAL_ENABLE_ECDSA	Enable ECDSA
CAL_ENABLE_SM2	Enable SM2

Image Decryption Function

The image decryption method is supplied by function:

osal_err_t secure_boot_decrypt_image(cipher_sch_t sch,

cipher_key_factors_t *key_factors, const uint8_t *iv,

size_t iv_size, const uint8_t *src, size_t src_size, uint8_t *dst, size_t *dst_size)

And there is default image decryption implementation in file img_dec_sec.c. Customers can overwrite this implementation if using image encryption plug-in file when generating manifest file.

Manifest

The manifest is the metadata that describes the secure boot configurations. It contains the following parts for the secure boot core usage:

1. The manifest’s flags, such as manifest version, developing mode.

2. The manifest’s signature and signature type.

3. The asymmetric public key which is to verify the manifest signature.

4. The device images’ information, such as the image’ version, loading address, static address, and image encryption flag.

5. The key blob if the image encryption is enabled. Key blob is the identifier of the symmetric cipher key for decrypting the device’s images.

6. The extended program if any.

The manifest file contains all the information needed by the secure boot core. You need to treat the manifest file as a normal device image and burn it to the device’s Non-volatile storage (for example, flash) in the manufacturing stage.

The following is the detailed manifest format:

Note:

1. The extended program is optional. It exists when the manifest descriptor contains extended program.

2. The key blob and IV is optional, only exist when image encryption enabled. IV always exists if image encryption is enabled, even using non-IV encryption algorithm (such as AES-ECB).

Manifest Flags

The following figure describes detailed layout of manifest header.

Note:

1. Magic value is: 0x4D6E4674.

2. Currently the manifest format version is always 2.

3. The public key size in manifest is one array which contains 2 integers. For RSA, they are N and E data size. For ECDSA/SM2, they are Q.X and Q.Y data size.

The following table describes the hash scheme enumerations:

Name	Value	Hex Value
SHA256	2	0x02
SHA512	3	0x03
SM3	4	0x04

The following table describes the signing scheme enumerations:

Name	Value	Hex Value
RSASSA_PKCS_V1.5_SHA256	66	0x42
RSASSA_PKCS_V1.5_SHA512	67	0x43
RSASSA_PKCS_V2.1_SHA256	71	0x47
RSASSA_PKCS_V2.1_SHA512	72	0x48
ECDSA_SHA256	98	0x62
ECDSA_SHA512	99	0x63
SM2_DSA_SM3	113	0x71

The following table describes the image encryption cipher scheme enumerations:

Name	Value	Hex Value
AES_ECB	161	0xA1
AES_CBC	162	0xA2
AES_CTR	163	0xA3
SM4_ECB	209	0xD1
SM4_CBC	210	0xD2
SM4_CTR	211	0xD3

The following table describes the public key type enumerations:

Name	Value	Hex Value
RSA 2048	1	0x01
RSA 4096	2	0x02
RSA 8192	3	0x03
ECP NIST 256	17	0x11
ECP NIST 521	18	0x12
SM2	48	0x30

Image Flags

The following figure describes detailed layout of image flags.

Note:

1. Image name is stored in 8 Bytes array.

2. If the image is embedded, the static address is set to the offset of image within manifest.

3. If the image doesn’t have entry address, it is set to 0xFFFFFFFFFFFFFFFF.

The image flag is one bit-mapped data with the following descriptions:

Name	Description	Value
IS_ENCRYPT	Indicate whether the image is encrypted.	1
IS_EMBEDDED	Indicate whether the image is embedded in manifest. The embedded data is packed in manifest, and has no static address.	2
IS_XIP	Indicate whether the image is XIP.	8
HAS_ENTRYADDR	Indicate whether the image has entry address.	4

Public Key Format

The RSA public key format is:

The EC and SM2 public key format is:

Image encryption

Image encryption is an enhancement of secure boot. With image encryption, encrypted images are stored in the non-volatile storage of the device. The secure boot core decrypts and verifies the images in boot stage. Image encryption improves the security level, prevents the device’s images from being plagiarized, and increases the device firmware’s confidentiality.

In secure boot tool and secure boot core, there is default image encryption method. Besides, customers can overwrite the default image encryption method by:

1. In secure boot tool, supply an image encryption plug-in file by -plugin argument.

2. In secure boot core, overwrite the implementation of function: secure_boot_decrypt_image.

The following describes the default image encryption method:

The secure boot tool encrypts the original images which are described by the manifest descriptor file. The encryption key is derived from model key, key blob and image name. The following figure shows the image encryption key derivation algorithm:

The HASH algorithm is SHA256.

For the final level image encryption key size:

• AES-ECB/CBC/CTR: always use 256 bits.

• SM4: always use 128 bits.

The Keyladder algorithm leverages Merak crypto engine on device if have.

The IV (used for CBC/CTR scheme) are random generated data, so for image encryption scheme which requires IV (AES-CBC/CTR, SM4-CBC/CTR), the encrypted images are different for each time generating manifest.

For block sized crypto scheme (ECB, CBC), the encrypted images are always block size aligned. Secure boot tool will generate PKCS#1 padding for input images.

In the secure boot core, encrypted images are read from their static address, decrypted and copied to their load address. It is required that the encrypted images are not XIP. The decryption key is also derived via the same algorithm as encryption key.

Extended program

The extended program is another enhancement of secure boot. The extended program makes it possible to securely execute some user codes in the secure boot core and makes it flexible for some hotfixes of inalterable code, such as BootROM. The extended program is verified along with the manifest and runs after device images’ verification.

It is recommended that you implement very simple logic in the extended program, such as configuring registers, because complicated software stack makes the extended program complex and out of control.

The execution environment of extended program is in the secure boot core. Secure boot core calls the following HAL API to execute the extended program:

HAL_API osal_err_t hal_secure_boot_run_extended_program(uint8_t *ext_prog, size_t ext_prog_size);

When implementing the extended program, be careful to avoid any conflict, such as stack overflow.

Signing tool

Introduction

Signing tool is the tool aims to deal with a bunch of binaries which need to be covered by Secure boot and followed by a specified secure boot verification chain. It takes several inputs, they are:

o Source package o Secure boot configuration o Key config o Secure boot wrapper o Post process o Post process arguments

Overview

4.8.2.1 Offline mode

4.8.2.2 Online mode

The above block diagram introduces offline and online scenario. Most of the flows of signing tool between offline and online are identical, the major difference is the manner of calling to secure boot tool, offline case by call secure boot tool directly but online mode call to secure boot wrapper, secure boot wrapper works as a proxy to call to secure boot tool.

On the left side. key conf describes key entries and with a reference of corresponding key files. Source package contains binaries from BIN0 ~ BINn. Secure boot configuration contains each secure boot level entry which be used to generate manifest descriptor by signing tool.

In the middle. Signing tool parse secure boot configuration, unpack corresponding binary according to the description of secure boot configuration and generate key descriptor and manifest descriptor according to secure boot configuration. Key descriptor, manifest descriptor and binaries formed as secure boot material which is the secure boot tool input. Signing tool submit these data to secure boot tool and secure boot tool feedback by its outputs. Signing tool packs those outputs of secure boot as signed package.

On the right side. Signed package was generated by signing tool and signing tool will call VENDOR DEFINED post process if user specified post process tool. Post process implementation requires must at least have one input that is the signed package.

Source package

Source package is a ZIP package which follows ZIP32 standard. It consists of a bunch of binaries need to be signed by Signing tool which will call into Secure boot tool to generate manifest to cover these binaries by secure boot verification chain.

Secure boot configuration

Secure boot configuration is JSON formatted file, which describes these binaries location in Source package and these binaries belong to which level of secure boot chain and which manifest binary will be generated.

Key config

Key config describes key files location (Offline mode) or key index in SaaS (Online mode) of each secure boot level which be described by Secure boot configuration.

Secure boot wrapper

Secure boot wrapper input only valid when signing tool working in Online mode which means signing tool be deployed into SaaS environment. Secure boot wrapper helps to establish communication between signing tool and secure boot SaaS.

Secure boot wrapper defined as:

• Establish the communication between sign tool and secure boot SaaS.

• Inputs comply with secure boot tool requirements.

• Outputs are the secure boot tool outputs.

Post process & Post process arguments

Post process is VENDOR DEFINED, it used to process the signed package and outputs vendor defined formats of binaries or package (e.g. concatenate all binaries as flash image).

Constrains of implementation：

• Must have one input parameter is the signed package.

• Has optional VENDOR DEFINED inputs, denote as VI.

• Has optional VENDOR DEFINED outputs, denote as VO.

Usage

sign_tool [options]

Parameters

Parameter Name	Description	Constrains	Example
-p, --package	Specify the source package location	The package is zip package	./source.zip
-b, -- secure-bootconfiguration	Specify the secure boot configuration	The secure boot configuration MUST be a JSON format file.	./secure_boot_conf.json
-s, --secure-bootwrapper	Specify secure boot wrapper tool location	A wrapper to call into Secure boot SaaS	./secure_boot_wrapper
--key-hints	Specify key hints file	The key hints MUST be a JSON format	./keyhints.json
--offline	Denote the signing tool work in offline mode.
--post-process	Specified VENDOR DEFINED post process entry.	• Optional • The post process entry must be an executable file. • The post process must implement ‘--post-input’ parameter used to specify signed package which is the output of signing tool.	./xxx_vendor_postprocess
--post-process-args	Specified the arguments of VENDOR DEFINED post process.	• Optional, only valid when ‘--post-process’ specified. • Must enclose by quotation marks. • Content must meet post process entry requirement.	“ -arg1 arg1 -arg2 arg2”

4.8.7.1 Secure boot configuration

The following table describes the detailed format in secure boot configuration file:

Key Name	Value Type	Description	Constrains	Example
format_version	Integer	Refer to 4.3.2.2	• Refer to 4.3.2.2	2
configs	Array	Contains a set of secure boot level entries.	• At least have one secure boot level entry.

The following table describes one secure boot level entry:

Key Name	Value Type	Description	Constrains	Example
level_name	String	The name of secure boot level	• Mandatory. This item must exist. • The characters MUST be: [0-9], [a-z], [A-Z], _.	Prim_bl2
			• Length maximum to 128.
manifest_version	Integer	Refer to 4.3.2.2	• Refer to 4.3.2.2
is_enable	Bool		• Mandatory.s
generated_manifest_file	String	The file name included relative path in the source package of the manifest binary output.	• Must be reasonable relative path in the source package	bins/prim_manifest.bin
images	Array	Aligned with ‘images’ in 4.3.2.2. Key ‘file’ indicate the relative path of the source package. Key ‘file_indicate’ denotes the next secure boot level name with ‘Level_’ as prefix and ‘_PubkeyHash’ as suffix.	Refer to 4.3.2.2
extended_program	String	Refer to 4.3.2.2	• Refer to 4.3.2.2 • Specified file must exist in source package.	Refer to 4.3.2.2
security_config	JSON sub-item	Describes the basic secure configurations for secure boot.	• All sub-items in security config are mandatory.	-
manifest_signing_key_type	String	Specify the asymmetric private key type of signing the manifest.	• Only support o ECP_NIST_256 o ECP_NIST_521 o RSA_2048 o RSA_4096 o RSA_8192 o SM2	RSA_4096
manifest_signing_algorithm	String	Refer to 4.3.2.1	• The signing algorithm MUST be aligned with the key type. • Only support: 1. RSASSA_PKCS_V15_SHA1 2. RSASSA_PKCS_V15_SHA256 3. RSASSA_PKCS_V15_SHA512 4. RSASSA_PKCS_V21_SHA1 5. RSASSA_PKCS_V21_SHA256 6. RSASSA_PKCS_V21_SHA512 7. ECDSA_SHA1	RSASSA_PKCS_V15_SHA256
				8. ECDSA_SHA256 9. ECDSA_SHA512 10. SM2_DSA_SM3
			•	Refer to 4.3.2.1
public_key_hash_algorithm	String	Refer to 4.3.2.1	• • •	The public key hash algorithm MUST be aligned with that in HAL implementation of secure boot core. Only support: 1. SHA1 2. SHA256 3. SHA512 4. SM3 Refer to 4.3.2.1	SHA256
image_hash_algorithm	String	Refer to 4.3.2.1	• •	Only support: 1. SHA1 2. SHA256 3. SHA512 4. SM3 Refer to 4.3.2.1	SHA256
image_encryption_config	JSON sub-item	Describes the image encryption’s configurations.	• •	All sub-items in security config are optional. If image encryption config is supplied, all subitems within this configuration should be supplied.
encryption_algorithm	String	Refer to 4.3.2.1.	• •	Only support: 1. AES-ECB 2. AES-CBC 3. AES-CTR 4. SM4-ECB 5. SM4-CBC 6. SM4-CTR Refer to 4.3.2.1	AES-ECB
encryption_plugin	String	Specify user defined plugin file name of image encryption	• • •	Optional Offline mode: The plugin library path, a relative path from sign tool. Online mode: The plugin name, defined by signing SaaS.	libimg_enc_plugin.so

The following table describes one image format:

Key Name	Value Type	Description	Constrains	Example
name	String	Refer to 4.3.2.2	• Refer to 4.3.2.2	bl_31
encryption	Bool	Refer to 4.3.2.2	• Refer to 4.3.2.2	true
static_address	String	Refer to 4.3.2.2	• Refer to 4.3.2.2	“0x000000000000F000”
load_address	String	Refer to 4.3.2.2	•	Refer to 4.3.2.2	“0x000000000007F000”
entry_address	String	Refer to 4.3.2.2	•	Refer to 4.3.2.2	“0x000000000007F004”
xip	Bool	Whether this image is XIP (eXecute In Place).	• • • •	Optional. This item can be non-exist. If not exist, this image is NOT XIP. If enabled, the image must NOT be encrypted. If enabled, the image must have static_address. That means, the image must NOT be embedded data. If enabled, the image’s static_address MUST equal to the load_address.	false
file	String	Specify the image file. Exclusive with file_indicate (see below)	• • •	Mandatory, if this is a normal image entry. The image file must exist in source package. If image’s static_address not exist (The image is embedded data), the image’s max size is 4096 Bytes.	“./tee.bin”
file_indicate	String	Special entry to describe next secure boot level name. When this field exist, which indicate this image entry is a public hash entry for next boot level. Exclusive with file (see above)	• • • • •	Mandatory. If this entry is a public hash entry. Must be with ‘Level_’ as prefix. Must be with ‘_PubkeyHash’ as suffix. The characters MUST be: [0-9], [a-z], [A-Z], _. The length must be aligned with the length of level_name.	Level_prim_bl3x_PubkeyHash

4.8.7.2 Key config

The key config is the signing tool input when it works in offline mode, which be used to specify each secure boot level singing key.

The following table describes the detailed format in manifest descriptor file:

[TABLE]

4.8.7.3 Key Hints

The Key Hints is the signing tool input when it works in online mode, which be used to specify each secure boot level singing key.

The following table describes the detailed format in manifest descriptor file:

Key Name	Value Type	Description	Constrains	Example
model_key_file	String	Describes the model key file location.	• Optional. But must exist when image encryption enabled. • File must exist and have correct access rights.	./xxx_model.key
Key name is equal to level name in secure boot configuration, refer to 4.8.7.1	JSON sub-item	Describe the manifest signing key and key blob of corresponding secure boot level.	• The object name must equal to level_name defined in secure boot configuration.
signing_key	String	The signing key file or Random	• Mandatory. • Only support: o Key file o Random	./key.pem
			•	If key file, must exist and key type must match with secure boot configuration.
			•	If “Random”, signing tool will generate random key.
signing_key_pwd	String	Key file password	•	Optional, if key has password, this field to specify the password.	“xxxx_pwd”
key_blob	String	User supplied data to scramble the image encryption key.	• •	Refer to 4.3.2.1 If this secure boot level enable image encryption, key_blob is mandatory.	“example_keyblob”

Key Name	Value Type	Description	Constrains	Example
Key name is equal to level name in secure boot configuration, refer to 4.8.7.1	JSON sub-item	Describe the manifest signing key and key blob of corresponding secure boot level.	• The object name must equal to level_name defined in secure boot configuration.
signing_key	String	Sign key ID in Secure boot SaaS	• Only support: o SecureBootRootKey o Fixed_ID_N o Random • First secure boot level signing key must equal to “SecureBootRootKey”. • The ‘N’ in “Fixed_ID_N” must be a decimal number. • Random indicate signing key is generated by Secure boot SaaS.	Fixed_ID_2
key_blob	String	Specify key blob to scramble the image encryption key.	• Only support: o Fixed_ID_N • The ‘N’ in “Fixed_ID_N” must be a decimal number.	Fixed_ID_6

Return code

Code	Description
0	Success
21	Bad parameter
22	ZIP package unpack error
23	ZIP package pack error
24	Sign package error
25	Secure boot configuration error
26	Key hints error
27	Internal error

Online and Offline Secure Boot

Online Secure Boot

The following picture is online secure boot architecture:

Detailed about signing SaaS and Secure Boot SaaS please see secure boot SaaS UDS.

The following picture describes the secure boot online mode inputs and outputs:

Offline Secure Boot

The following picture is offline secure boot architecture:

The differences of offline VS online:

• Input key config with local key files rather than key hints.

• Directly call secure boot tool rather than call into Secure Boot SaaS.

UBL

JIAYU secure boot includes on referenced bootloader: Universal BootLoader (UBL). The UBL supplies a bare metal execution environment, customers can build UBL to BootROM, BootLoader.

Supported architecture

UBL supports the following architectures:

Architecture	Description
ARM-A 64bit	The ARM-A 64bit is for ARMv8-A AARCH64.
ARM-A 32bit	ARM-A 32bit includes: 1. ARMv8-A AARCH32 2. Cortex A7 3. Cortex A8 4. Cortex A9 5. Cortex A15 6. Cortex A7 7. ARM11
ARM-M	ARM-M includes: 1. Cortex M0 2. Cortex M0+ 3. Cortex M3 4. Cortex M4 5. Cortex M7 6. Cortex M33

Details about supported architectures see arch folder in UBL.

Platform porting

Porting a new platform in UBL is tedious work. Currently UBL has supported the following platforms:

Platform Name	Description
An505	An505 is supported only in qemu with the following command: qemu-system-arm -machine mps2-an505 -cpu cortex-m33
Chariot	Armchina Chariot board.
Qemu Virtual ARMA53	Qemu command: qemu-system-aarch64 -machine virt, secure=on -cpu cortex-a53
Qemu Virtual ARMA15	Qemu command: qemu-system-aarch64 -machine virt, secure=on -cpu cortex-a15

Customers can porting a new platform reference to the upper one. Also, you can port a new platform following these steps:

1. Create a new folder in platform of ubl. The folder name is your platform name, such as test_platform.

2. Create a config file in your platform folder. The config file MUST includes:

   1. The arch config: CFG_ARCH.

   2. The platform config: CFG_PLATFORM.

   3. Other mandatory configs.

3. Create a hal_platform.h file in your platform folder, in which MUST contains:

   1. The main stack size: CFG_MAIN_STACK_SIZE

   2. The system heap size: CFG_SYSTEM_HEAP_SIZE

   3. The linker configurations: CFG_LINKER_FORMAT and CFG_LINKER_ARCH

   4. The binary RO region: CFG_RO_BASE and CFG_RO_LIMIT

   5. The memory RW region: CFG_RW_BASE and CFG_RW_LIMIT

4. Besides, you MUST also implement several platform porting APIs:

   1. plaform_asm_early_init

   2. platform_asm_get_my_entrypoint

   3. platform_init

   4. platform_panic

   5. platform_putc

   6. platform_init_entry_point_info

   7. platform_prepare_exit

   8. platform_main_stack

Configurations

There are some configurations in UBL:

Configuration Name	Description
CFG_ENABLE_SMP	Enabling SMP (multi-cores).
CFG_ARCH	Configuring the architecture. Can be one of: • arm • arm64 • arm-m
CFG_ARM_CPU	Configuring the CPU. For ARCH = arm, can be: • cortex-a7 • cortex-a8 • cortex-a9 • cortex-a9-neon • arm1136j-s • arm1176jzf-s • cortex-r4f • armemu For ARCH=arm-m, can be: • cortex-m0

Configuration Name	Description
CFG_ENABLE_SMP	Enabling SMP (multi-cores).
CFG_ARCH	Configuring the architecture. Can be one of: • arm • arm64 • arm-m
CFG_ARM_CPU	Configuring the CPU. For ARCH = arm, can be: • cortex-a7 • cortex-a8 • cortex-a9 • cortex-a9-neon • arm1136j-s • arm1176jzf-s • cortex-r4f • armemu For ARCH=arm-m, can be: • cortex-m0
	• cortex-m0pl • cortex-m3 • cortex-m4 • cortex-m4f • cortex-m7 • cortex-m7-f • cortex-m33
CFG_PLATFORM	Configuring the platform, must be the platform folder name.
CFG_ENABLE_MMU	Enabling MMU. Only valid for ARCH=arm/arm64.
CFG_LINKER_FORMAT	The linker format. One of: • elf64-littleaarhc64 • elf32-littlearm
CFG_LINKER_ARCH	The linker arch. One of: • aarch64 • arm
CFG_MAX_MMAP_REGIONS	The max memory map regions. Only available when MMU is enabled.
CFG_MAX_XLAT_TABLES	The max xlat tables. Only available when MMU is enabled.
CFG_VIRT_ADDR_SPACE_SIZE	The virtual address space size. Only available when MMU is enabled.
CFG_PHY_ADDR_SPACE_SIZE	The physical address space size. Only available when MMU is enabled.
CFG_MAIN_STACK_SIZE	The main stack size in byte.
CFG_RO_BASE	The binary RO base address. Currently ubl links all .text .ro .data sections in RO area. The static address of this binary is RO_BASE.
CFG_RO_LIMIT	The binary RO limit address.
CFG_RW_BASE	The run-time RW base. Currently ubl copies .data section and link .bss section in RW area.
CFG_RW_LIMIT	The run-time RW limit address.
CFG_ENABLE_SHELL	Whether to enable shell.
CFG_SECURE_BOOT	Whether to enable secure boot.
CFG_PROVISIONING	Whether to enable provisioning agent.
CFG_MBEDTLS	Whether to enable mbedtls.
CFG_ENABLE_DEBUG	Whether to enable debug.
CFG_DRIVER_EMMC	Whether to enable EMMC driver.
CFG_DRIVER_EMMC_RPMB	Whether to enable RPMB driver in EMMC.

JIAYU Secure Boot Demonstration

There is one secure boot implementation on JIAYU demonstration board: Chariot developing board.

The following picture describes the multi-level secure boot configurations for JIAYU demonstration.

Appendix

Public key certificate

Certificate can be a self-signed certificate, but in most common way is issued by CA. In section 4.8, singing tool IMPLEMENT DEFINED post process of sign tool need user input private key and its public key certificate to sign the chariot OTA package.

So, this section tries to introduce how to setup a CA and use it to sign a certificate sign request under linux environment and based on openssl tool.

Setup CA

5.1.1.1 Create work directory

The following commands help to create CA work directory:

$ mkdir -p CA/workdir/certs

$ pushd CA/workdir

$ touch database.txt

$ cat << EOF > serial

01

EOF

$ popd

5.1.1.2 CA configuration

The following command help to create CA configuration file:

$ pushd CA

$ cat << EOF > ca.cnf

[ca]

default_ca = OTACA

[OTACA]

certificate = ./workdir/cacert.pem database = ./workdir/database.txt private_key = ./workdir/cakey.pem new_certs_dir = ./workdir/certs default_md = sha256 policy = policy_ota serial = ./workdir/serial default_days = 365

[policy_ota] commonName = supplied

EOF

$ popd

5.1.1.3 CA root certificate

The following commands help to create root certificate of CA:

$ pushd CA/workdir

# Gen CA root key

$ openssl genrsa -out cakey.pem 4096

$popd

$pushd CA

# Gen CA CSR

$ openssl req -new -key workdir/cakey.pem -out ca.csr -subj '/C=CN/ST=SHA/L=SHA/O=ARM\ CHINA/OU=SISE\ OTA\ CA/CN=otaca'

# Self sign CSR.

$ openssl ca -config ca.cnf -selfsign -keyfile workdir/cakey.pem -in ca.csr -out workdir/cacert.pem startdate 19700101000000Z -enddate 21201231235959Z

$ popd

Sign request

5.1.2.1 Gen private key

The following commands generate an RSA 2048bits private key:

$ mkdir -p request

$ pushd request

$ openssl genrsa -out package.key 2048

$ popd

5.1.2.2 Gen CSR

The following commands use RSA 2048bits private key generate a CSR (certificate sign request):

$ pushd request

$ openssl req -new -out package.csr -key package.key -subj '/C=CN/ST=SHA/L=SHA/O=ARM\

CHINA/OU=OTA\ PACKAGE \SIGN/CN=otapkg_release01' $ popd

5.1.2.3 Sign CSR

The following commands sign the CSR and output the corresponding certificate of private key:

$ pushd CA

$ openssl ca -config ca.cnf -in ../request/package.csr -out ../request/package.cert -batch $ popd

5.1.2.4 Verify certificate

The following commands verify the certificate by CA:

$ pushd CA

$ openssl verify -CAfile ./workdir/cacert.pem -no-CApath ../request/package.cert $ popd