Permalink
Cannot retrieve contributors at this time
Name already in use
A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
p64_utils/README.md
Go to fileThis commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
173 lines (144 sloc)
7.63 KB
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
# 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)](http://www.cypress.com/CY8CKIT-064B0S2-4343W) | |
* [PSoC 64 Standard Secure - AWS Wi-Fi BT Pioneer Kit (CY8CKIT-064S0S2-4343W) ](http://www.cypress.com/CY8CKIT-064S0S2-4343W) | |
* [PSoC 64 Secure Boot BLE Prototyping Kit (CY8CPROTO-064B0S1-BLE) ](http://www.cypress.com/CY8CPROTO-064B0S1-BLE) | |
* [PSoC 64 Secure Boot Prototyping Kit (CY8CPROTO-064B0S3) ](http://www.cypress.com/CY8CPROTO-064B0S3) | |
* [PSoC 64 Secure Boot Prototyping Kit (CY8CPROTO-064S1-SB) ](http://www.cypress.com/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](www.cypress.com/documentation/software-and-drivers/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 | |
```c | |
#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 | |
```c | |
{ | |
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 | |
```c | |
#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](./RELEASE.md) | |
* [PSoC64 Secure Boot Utilities API Reference Guide](https://cypresssemiconductorco.github.io/p64_utils/p64_utils_api_reference_manual/html/index.html) | |
* [PSoC 64 Secure MCU Secure Boot SDK User Guide](https://www.cypress.com/documentation/software-and-drivers/psoc-64-secure-mcu-secure-boot-sdk-user-guide) | |
* [PSoC 64 Microcontrollers](https://www.cypress.com/products/psoc-64-microcontrollers-arm-cortex-m4m0) | |
* [ModusToolbox Software Environment, Quick Start Guide, Documentation, and Videos](https://www.cypress.com/products/modustoolbox-software-environment) | |
* [Cypress Semiconductor](http://www.cypress.com) | |
--- | |
© Cypress Semiconductor Corporation (an Infineon company), 2019-2022. |