PSoC64 Secure Boot Utilities Middleware Library

Overview

The Secure Boot Utilities Middleware Library is a set of utility code for the PSoC64 device to perform some operations, for example, providing an interface to Secure FlashBoot SysCalls including the PSA cryptographic functions, generic syscall functions, base64 decode provisioning JWT packet, parsing JSON data, policy parsing helpers, dynamic memory manager.

Features

PSA Cryptographic library

Wrapper functions to call PSA Crypto API v1.0 are implemented in Secure FlashBoot. All cryptographic functions are implemented according to the Mbed Crypto library version 2.24 interface. This version corresponds to the version which used in Secure FlashBoot. Refer to the PSA Crypto API Reference Guide for the specific PSA Crypto functions:

• https://armmbed.github.io/mbed-crypto/html/index.html
• https://github.com/ARMmbed/mbedtls/tree/v2.24.0#psa-cryptography-api

Generic Syscall functions

Wrapper functions to call several syscalls which are implemented in Secure FlashBoot:

• Get Provision details
• DAP control
• Rollback counter manipulation
• Acquire response
• Attestation

base64 library

The base64 library implements the base64 encoding and decoding functions. The base64 decoding function is used to decode a provisioned JWT packet that contains the policy. base64 is a third-party library.

cJSON library

cJSON is a lightweight JSON parser. Optimized version 1.3.2 is released in this library. Version 1.3.2 is used because of the smallest flash memory consumption. The 'valueint' type in the cJSON structure is changed from double to uint32_t to reduce the flash memory usage and time consumption. PSoC64 uses only 32-bit unsigned integers in the provisioning policy. cJSON is a third party library and it is distributed under the MIT license.

JWT/JSON Policy parsing helper functions.

Includes functions for: - Decode and parse the JWT packet - Find items in the JSON object - Find the boot and upgrade the image address in the provisioning policy

Swap upgrade utility functions

This interface allows writing "Image OK" flag to the slot trailer, so CypressBootloader cannot revert the new image.

High-level interface for interacting with the Watchdog Timer.

This interface allows start/stop WDT and set new timeout value. This interface abstracts out the chip specific details. If any chip specific functionality is necessary, or performance is critical, the low-level functions can be used directly.

Dynamic memory allocation functions.

The static buffer is allocated, it is used dynamically for the memory allocation functions. CY_P64_HEAP_DATA_SIZE defines the size for a local buffer and can be re-defined by the user based on the maximum memory size requirements.

Supported Kits (make variable 'TARGET')

• PSoC 64 Secure Boot Wi-Fi BT Pioneer Kit (CY8CKIT-064B0S2-4343W)
• PSoC 64 Standard Secure - AWS Wi-Fi BT Pioneer Kit (CY8CKIT-064S0S2-4343W)
• PSoC 64 Secure Boot BLE Prototyping Kit (CY8CPROTO-064B0S1-BLE)
• PSoC 64 Secure Boot Prototyping Kit (CY8CPROTO-064B0S3)
• PSoC 64 Secure Boot Prototyping Kit (CY8CPROTO-064S1-SB)

Quick Start Guide

This quick start guide assumes that the environment is configured to use the PSoC 6 Peripheral Driver Library(psoc6pdl) for development and the PSoC 6 Peripheral Driver Library(psoc6pdl) is included into the project.

It also assumes the PSoC64 device is provisioned as documented in PSoC 64 Secure MCU Secure Boot SDK User Guide

Adding the library

There are two ways to add library to our project:

• add a dependency file (MTB format) into the 'deps' folder;
• use the Library Manager. It is available under Libraries Tab > PSoC 6 Middleware > p64-utils.

Using the library

The library automatically allocates the buffer that is enough for default policy parsing. If the project needs additional memory, change the default buffer size in makefile by defining 'CY_P64_HEAP_DATA_SIZE=XXXX' with the required value.

Code snippet: Get Provisioning policy and parse it to the JSON object

#include "cy_p64_syscalls.h"
#include "cy_p64_jwt_policy.h"

int main(void)
{
    __enable_irq();
    {
        cy_p64_error_codes_t status;
        char *jwt_packet;
        cy_p64_cJSON *json_packet;

        /* Get the provisioned JWT policy */
        status = cy_p64_get_provisioning_details(CY_P64_POLICY_JWT, &jwt_packet, NULL);
        if(status == CY_P64_SUCCESS)
        {
            /* Decode the JWT policy and parse it to the JSON object */
            status = cy_p64_decode_payload_data(jwt_packet, &json_packet);
            if(status == CY_P64_SUCCESS)
            {
                /* json_packet contains the parsed policy, which may be used by the following examples */
				
                /* Delete the JSON object after usage and free memory */
                cy_p64_cJSON_Delete(json_packet);
            }
        }
    }
    for (;;)
    {
    }
}

Code snippet: Find the upgrade image address and size in the policy

	{
		uint32_t upgrade_address;
		uint32_t upgrade_size;
		status = cy_p64_policy_get_image_address_and_size(json_packet, 1, "UPGRADE", &upgrade_address, &upgrade_size);
		if(status == CY_P64_SUCCESS)
		{
			/* Use upgrade_address and upgrade_size for DFU to program upgrade image */
		}
	}

Code snippet: Confirm that the image is ok

	#include "cy_p64_image.h"
	
	/* Find the boot image address and size in the policy */
	{
		uint32_t boot_address;
		uint32_t boot_size;
		uint32_t image_id = 1;
		status = cy_p64_policy_get_image_address_and_size(json_packet, image_id, "BOOT", &boot_address, &boot_size);
		if(status == CY_P64_SUCCESS)
		{
			/* Confirm that booted image is Ok, so MCU Boot will not swap it */
			status = cy_p64_confirm_image(boot_address, boot_size);
		}
	}

Note: To confirm the CM4 boot image when device is provisioned with policy_multi_CM0_CM4.json policy, set image_id = 16.

Performance

PSA Crypto API benchmark for the PSoC64 2M device with the CM0p core frequency set to 50 Mhz:

Algorithm	Execution time
SHA-256	2 ms/10kB payload
SHA-256	4 ms/100kB payload
AES-CBC-128	18 ms/10kB payload
AES-CBC-256	19 ms/10kB payload
AES-CTR-128	13 ms/10kB payload
AES-CTR-256	14 ms/10kB payload
HMAC-SHA256	2 ms/10kB payload
ECDSA-secp256r1	110 ms/sign
ECDSA-secp256r1	224 ms/verify
ECDSA-secp256r1	363 ms/verify (including public key calculation)
ECDH-secp256r1	137 ms/generate key pair
ECDH-secp256r1	141 ms/handshake

More information

The following resources contain more information:

• PSoC64 Secure Boot Utilities RELEASE.md
• PSoC64 Secure Boot Utilities API Reference Guide
• PSoC 64 Secure MCU Secure Boot SDK User Guide
• PSoC 64 Microcontrollers
• ModusToolbox Software Environment, Quick Start Guide, Documentation, and Videos
• Cypress Semiconductor

---

© Cypress Semiconductor Corporation (an Infineon company), 2019-2022.