MPLAB® Harmony v3 is now configurable through MPLAB Code Configurator (MCC). Refer to the following links for specific instructions to use MPLAB Harmony v3 with MCC.
Objective
This tutorial shows how to use the Secure Boot feature on the PIC32CM LS60 microcontroller (MCU) using ATECC608B to create a Secure Bootloader and an application that is loaded using the Secure Bootloader. This tutorial helps you get started in developing secure applications on PIC32CM LS60 MCUs using Microchip's Trust Platform Design Suite (TPDS) and MPLAB Harmony v3 software framework. The project you create will run on the PIC32CM LS60 Curiosity Pro Evaluation Kit (EV76R77A).
The application is developed on the MPLAB Harmony v3 software framework. MPLAB Harmony v3 is a modular framework that provides interoperable firmware libraries for application development on 32-bit MCUs and MPUs. It includes an easy-to-use Graphical User Interface (GUI) (MPLAB Code Configurator (MCC)) for selecting, configuring, and generating starter codes, peripheral libraries, and middleware (USB, TCP/IP, Graphics, and so on).
The application demonstrates the development of two projects.
- A Secure Bootloader
- A Test Application
Secure Bootloader:
The Secure Bootloader on PIC32CM LS60 provides a layer of security to the boot process by checking the integrity of the Bootloader before moving to program a firmware image into the device's Flash memory. This helps prevent unauthorized access and malicious code from being loaded onto the device.
The Secure Bootloader implements a security layer through the Secure Boot feature on PIC32CM LS60 devices. The process typically involves:
- Storing cryptographic keys: Public and private key pairs are generated, with the private key securely stored in the secure element and the public key programmed into the MCU.
- Signing: The bootloader code is signed using the private key, creating a digital signature that is appended to the bootloader code image.
- Verification: When the MCU boots, the Bootloader's digital signature is checked using the public key stored in the device. If the signature is valid, it confirms the Bootloader's integrity and authenticity, allowing it to execute and load the application firmware (if needed).
Test Application:
The test application firmware is sent by a host PC (running a script) interfaced to the PIC32CM LS60 MCU through UART. The test application image is received and loaded by the Secure Bootloader.
The test application you create will utilize the following peripherals:
- SERCOM2 (as Universal Synchronous Asynchronous Receiver Transmitter (USART)) peripheral library to communicate with the PC utility for receiving the test application image using the Bootloader library.
- NVMCTRL peripheral library to read or write the firmware image from the Flash memory.
There are two approaches for this tutorial:
- Create the project from scratch:
- Use the provided source files and follow the step-by-step instructions below.
- Use the solution project as an example:
- Build the solution project and download it to the PIC32CM LS60 Curiosity Evaluation Kit to observe the expected behavior.
Lab Objectives
- Create MPLAB X IDE Harmony v3 projects for a PIC32CM LS60 MCU from scratch.
- Use MCC to configure and generate Harmony v3 Peripheral Library code for USART, NVM, PM, and PORT peripherals.
- Use MCC to configure and generate the Bootloader library for UART.
- Use the Harmony v3 Peripheral Library Application Programming Interfaces (APIs) to implement and demonstrate the Secure Bootloader application.
Materials
Hardware Tools
Tool | About | Purchase |
---|---|---|
PIC32CM LS60 Curiosity Pro
Evaluation Kit |
| |
MikroElektronika USB UART Click
Extension Kit |
| |
The Curiosity Pro series evaluation kits include an onboard Embedded Debugger (EDBG). No external tools are necessary to program or debug the PIC32CM LS60. For programming or debugging, the EDBG connects to the host PC through the USB micro-B connector on the PIC32CM LS60 Curiosity Pro Evaluation Kit.
Software Tools
This project has been verified to work with the following versions of software tools:
- MPLAB X IDE v6.05
- MPLAB XC32 Compiler v4.21
- MPLAB Harmony BSP v3.15.0
- MPLAB Harmony CSP v3.16.0
- DEV_PACKS v3.16.0
- bootloader v3.6.0
- MCC Plugin Version v5.3.0
- MCC Core Version v5.5.0
- MCC Harmony Core Version v1.3.1
- Trust Platform Design Suite V2
- Any Serial Terminal application like Tera Term terminal application.
- Python - v3 and above
Because we regularly update our tools, occasionally you may discover an issue while using the newer versions. If you suspect that to be the case, we recommend that you double-check and use the same versions that the project was tested with.
Note: To get the details of the tools used, refer to the project manifest file (harmony-manifest-success.yml) in the provided solution.
Secure Bootloader: - Available under the project folder:
firmware/secure_bootloader/Secure/firmware/src/config/pic32cm_ls60_cpro
firmware/secure_bootloader/Non-Secure/firmware/src/config/pic32cm_ls60_cpro
Application: - Available under the Secure and Non-Secure parts of the project present in the folder:
firmware/test_app/Secure/firmware/src/config/pic32cm_ls60_cpro
firmware/test_app/NonSecure/firmware/src/config/pic32cm_ls60_cpro
Tool | About | Installers |
Installation
Instructions |
||
---|---|---|---|---|---|
Windows | Linux | Mac OSX | |||
MPLAB® X
Integrated Development Environment |
| | | | |
MPLAB® XC32
C/C++ Compiler |
| | | | |
For this lab, download the following repositories from GitHub:
- BSP: The following table shows the summary of contents.
Folder | Description |
---|---|
boards | Board Support Package code for Microchip 32-bit SAM and PIC® microcontroller and microprocessor devices |
- CSP: The following table shows the summary of contents.
Folder | Description |
---|---|
apps | Example applications for CSP library components |
arch | Initialization and starter code templates and data |
docs | CSP library help documentation |
peripheral | Peripheral library templates and configuration data |
- DEV_PACKS: The following table shows the summary of the contents.
Folder | Description |
---|---|
Microchip | Peripheral register specific definitions |
arm | Core Specific Register Definitions (CMSIS) |
- Bootloader: The following table shows the summary of the contents.
File/Folder | Description |
---|---|
apps | Example applications for Bootloader |
config | Bootloader library Python files |
docs | Bootloader libraries help with documentation |
templates | Bootloader library templates and configuration data |
tools | Bootloader library Python script files |
- quick_docs: The following table shows the summary of the contents.
File/Folder | Description |
---|---|
docs | quick_docs documentation |
source | quick_docs readme markdown files |
- Use the MPLAB® Code Configurator (MCC) to download the repositories.
Overview:
PIC32CM LS60 Memories Security Attribution:
The Flash memory on PIC32CM LS60 can be divided into up to five regions, two of which are dedicated to the bootloader while the remaining regions are dedicated to the application.
The BOOT region, which contains the bootloader, can be further divided into two sub-regions:
- Secure sub-region (S)
- Non-Secure Callable sub-region (NSC)
The APPLICATION region can be divided into three sub-regions:
- Secure sub-region (S)
- Non-Secure Callable sub-region (NSC)
- Non-Secure sub-region (NS)
These sub-regions have different access permissions and security attributes to help protect the device against unauthorized access and tampering.
The PIC32CM LS60 MCU features the TrustZone technology, which provides hardware-enforced isolation between Secure and Non-Secure memory regions.
- Secure memory region: This region is accessible only when the processor is operating in a secure state. It can be used to store sensitive data, execute secure code, and manage critical system resources. The secure memory region helps protect against unauthorized access, tampering, or reverse engineering.
- Non-Secure memory region: This region is accessible from both Secure and Non-Secure states. It is used for storing general-purpose data and executing non-critical code. Non-Secure memory regions can be accessed by potentially untrusted applications, but they cannot access secure memory regions.
The Non-Secure callable regions have functions that allow code running in the Non-Secure region to invoke functions located in the secure region. The NSC functions provide a mechanism for controlled and secure communication between the Secure and Non-Secure regions.
Secure Boot on PIC32CM LS60:
The Boot ROM in the PIC32CM LS60 supports Secure Boot through SHA-256, HMAC, and ATECC608B. Secure Boot can be enabled to authenticate the bootloader image in a configurable portion of the Flash, known as the Boot region. If the authentication process fails, the device can be reset, and the authentication process restarted.
This tutorial showcases the implementation of the Secure Boot using ATECC608B and SHA-256 hash function with boot key. In this process, the Boot ROM will leverage ATECC608B to authenticate and verify the integrity of the bootloader.
The following steps are performed using the TPDS.
Step 1: Provisioning Keys
- Generate and store private/public keys and IOPROT keys in the ATECC608B slots shown below
Step 2: Signing and Programming
- Based on the bootloader image Secure Boot fuse configurations, Use the SHA-256 hash function with 32 bytes BOOTKEY to generate the digest for the bootloader image. Encrypt digest using the ATECC608B primary private key and generate a signature.
- Append the signature to the bootloader image.
- Program the bootloader image with signature into the Secure Flash boot region.
- The BOOTKEY, IOPROTKEY, and BOOTOPT along with other Boot configurations are programmed in the NVM Boot Configuration row (BOCOR) in the BOOT ROM.
- BOOTKEY: A 32-byte key defined by the bootloader. BOOTKEY helps prevent any unauthorized alteration of the bootloader code. With the help of the boot key, a slight modification is made in the digest computation process to ensure that a valid digest is produced only with the use of a key.
- IOPROTKEY: A key to encrypt the communication between the PIC32CM LS60 microcontroller and the ATECC608B.
- BOOTOPT: The fuse configuration value representing the Secure Boot mode selected; ATECC608B-based Secure Boot and SHA with BOOTKEY combination
The following steps are performed at runtime.
Step 3: Verification:
The bootloader is authenticated and its integrity is verified by the Boot ROM using the assistance of the ATECC608B. During the power-on reset, the Boot ROM checks the BOOTOPT configuration value. If the value is 5, it performs the ATECC608B-based Secure Boot authentication.
During the first authentication process, the Boot ROM checks the integrity of the bootloader by sending both the digest and signature to the ATECC608B for verification. If the verification is successful, the Boot ROM stores the computed digest in the ATECC608B and executes the bootloader from the BOOT Region. If the verification fails, the device enters interactive debug mode and stops functioning.
During subsequent authentication requests, the Boot ROM provides only the digest to the ATECC608B. The ATECC608B then compares this digest with the digest that was stored during the initial authentication process. If the digests match, the Boot ROM proceeds to execute the bootloader from the BOOT Region. However, if they don't match, the device enters interactive debug mode and stops functioning.
MPLAB Code Configurator version 5.3.0 with Harmony v3 will be used to configure the PIC32CM LS60, the UART Bootloader, and the peripheral libraries.
MPLAB X IDE v6.05 and MPLAB XC32 compiler v4.21 have been used to build the application.
Two Ways to Use This Tutorial:
1. Creating the project from scratch. Use the provided source files and follow the step-by-step instructions mentioned below.
2. Using the solution project as an example. Just build the solution project and download it to the PIC32CM LS60 Curiosity Pro Evaluation Kit (EV76R77A) board, go through the readme.md inside the project folder and observe the expected behavior.
Application Description
The following are the steps to demonstrate the Secure Boot feature on PIC32CM LS60 MCU.
Step 1: Secure Boot Configuration | Provisioning | Secure Booting
- The PIC32CM LS60 MCU is configured to run in Secure Boot mode with the ATECC608B-based boot protection verification method and SHA-based NVM boot configuration (BOOTOPT=5).
- Program the Secure Bootloader code using Microchip's Trust Platform Design Suite (TPDS).
- The successful running of the Secure Bootloader is indicated by turning the green LED0 ON.
- Receive the test application image over UART from a PC by running a Python script. The successful receiving of the application is indicated by toggling the red LED.
- Red LED1 starts toggling, indicating secure and successful application booting.
Step 2: Impersonating Bootloader
- Generate a .hex file (say an impersonating bootloader) in MPLAB X IDE.
- Program the hex file using MPLAB X IDE (Ensure the Bootloader is programmed at 0x00)
- Since the bootloader image in NVM is an impersonated one, it doesn't have the digest matching the ATECC608B-based authentication and integrity checks. The application fails to Boot. Both LED's are OFF state.
Step 3: Restoring the Secure Bootloader and Validation
- Generate the Secure bootloader hex file in MPLAB X IDE.
- Use the Private/Public key used in Step 1 in TPDS and create the signed .hex file.
- Program the signed.hex file using the TPDS. The successful running of the Secure Bootloader is indicated by turning the green LED0 ON.
- Receive the test application image over UART from a PC by running a Python script. The successful receiving of the application is indicated by toggling the red LED.
- Since the Secure Bootloader is restored, the Secure bootloader and application work as expected. Red LED1 starts toggling, indicating secure and successful application booting.
Lab Source Files and Solutions
This ZIP file contains the completed solution project for this lab. It also contains the source files needed to perform the lab by following the step-by-step instructions (see the "Procedure" section on this page).
The contents of this ZIP file need to be placed in a folder of your choice.
Note:
- The project location of a Harmony v3 project is independent of the location of the Harmony Framework path (i.e., you need not create or place a Harmony v3 project in a relative path under the Harmony v3 framework folder). The project can be created or placed in any directory of your choice. This is true because when created, a Harmony v3 project generates all the referred source and header files and libraries (if any) under the project folder.
- The point above contrasts with the Harmony v2 project location. In Harmony v2, the project was supposed to be created in a location under the Harmony framework.
Extracting the ZIP file creates the following folders:
- pic32cm_ls60_cpro_secure_boot contains the lab solution (in the firmware folder) and source files (in the dev_files folder).
- dev_files contains subfolder pic32cm_ls60_cpro which contains application source files for Secure Bootloader, Test Application, and other support files (if any) required to perform the lab (see "Procedure" section below).
- firmware/secure_bootloader contains the completed lab solution project for Secure Bootloader.
- firmware/test_app contains the completed lab solution project for Test Application.
- hex/secure_bootloader contains the hex file for the Secure Bootloader.
- hex/test_app contains the hex and unified binary file for the Test Application.
- readme.md contains detailed steps to run the application.
Procedure
All steps must be completed before you are ready to build, download, and run the application.
Lab Index
Step 1: Create the Secure Bootloader Project from Scratch
- Step 1.1 - Setup MPLAB X MCC Plugin
- Step 1.2 - Create a Secure Bootloader Project
- Step 1.3 - MCC Content Manager Wizard
- Step 1.4 - Configure the Secure Bootloader project using MCC
Step 2: Create a Test Application Project from Scratch
- Step 2.1 - Create a Test Application Project
- Step 2.2 - MCC Content Manager Wizard
- Step 2.3 - Configure the Test Application project using MCC
Step 3: Running the Application
- Step 3.1 - Generate the PIC32CM LS60 User Row Configurations for the Test Application project
- Step 3.2 - Secure Boot Configuration | Provisioning | Secure Booting
- Step 3.3 - Impersonating Bootloader
- Step 3.4 - Restoring the Secure Bootloader and Validation