ModusToolbox™ Secure Policy Configurator user guide¶
ModusToolbox™ tools package version 3.0.0
Secure Policy Configurator version1.30
About this document
Scope and purpose
The Secure Policy Configurator is used to open, create or change policy configuration files for the PSoC™ 64
“Secure Boot” MCU devices, also modify policy tools and provision devices.
This document helps application developers understand how to use the Secure Policy Configurator as part of creating a ModusToolbox™ application.
Emphasizes heading levels, column headings, menus and sub-menus
Denotes file names and paths.
Denotes APIs, functions, interrupt handlers, events, data types, error handlers, file/folder names, directories, command line inputs, code snippets
File > New
Indicates that a cascading sub-menu opens when you select a menu item
Abbreviations and definitions
The following define the abbreviations and terms used in this document:
Application – One or more projects related to each other.
Configurator – A GUI-based tool used to configure a resource.
cysecuretools – A set of Python scripts and policy templates to perform provisioning for the PSoC™ 64 devices.
DAPLink – Arm Mbed DAPLink is an open-source software project that enables programming and debugging application software running on Arm Cortex CPUs.
Image, Single/Multi – Single-image and Multi-image types can be created to define how the CM0+ “secure” co-processor and CM4 binaries are generated.
Single-image mode – The default mode, in which the CM0+ “secure” co-processor code binary is attached to the beginning of the CM4 binary to form a single binary. Therefore, the CM0+ “secure” co- processor and CM4 must be updated at the same time, as they require a single update binary.
Multi-image mode – The CM0+ “secure” co-processor and CM4 binaries are updated individually with two different update binaries.
JWT – JSON Web Token is an open, industry standard RFC 7519 method to securely represent claims between two parties.
Monotonic counter ID – The counter to prevent a rollback during the upgrade process. Indicates the monotonic counter value associated with the image, which is booted. During a “secure” boot, this counter value is compared to this image version code. During the upgrade process, this counter is incremented to the value from the image header of the upgrade image.
Policies – A collection of pre-defined (name, value) pairs that describe what is allowed and not allowed on the device.
Provisioning – The act of configuring a device with an authorized set of keys, certificates, credentials, and firmware images. Once provisioned, the device can be accessed or modified only with the keys injected adhering to the relevant policies. The act is executed in two steps:
Provisioning identity; the unique device secret (UDS) and the device public/private key pair.
This occurs only once in a secure manufacturing environment.
Provisioning keys and policies.
Reprovisioning – The act of reconfiguring a device with a new certificate.
Public key certificate – The X.509 type certificate is a standard public key certificate used in many Internet protocols, including TLS/SSL.
Certificate – A message, digitally signed by a “Certificate Authority (CA)”, linking a public key to the identity of the certificate holder (can be a URL, name/address, ID/serial number).
RMA (Return Merchandise Authorization) mode – The device transitions to this mode when the user wants Cypress to perform failure analysis on the device, which means that any areas of the user’s flash that may contain proprietary code or sensitive data will be erased automatically.
Rollback Counter – A special counter accessed by “Secure Boot” code. This counter prevents downgrading the device to an older version of its software that has been deprecated due to security.
“Secure Boot” – A bootup process where the firmware being run by the chip is trusted by using strong cryptographic schemes and an immutable RoT.
SMIF – Serial Memory interface, hereinafter refers to the highspeed Quad-SPI interface on PSoC™ 6.
SWD – Single Wire Debug, a two-wire debug port defined for Arm Cortex CPU’s.
Refer to the following documents for more information as needed:
API reference guides
Device technical reference manuals
The Secure Policy Configurator is part of a collection of tools included with the ModusToolbox™ software. You can use the Secure Policy Configurator to open, create or change policy configuration files for the PSoC™ 64 “Secure Boot” MCU devices, also modify policy tools and provision devices. For details, refer to the “Secure Boot” SDK user guide. The Secure Policy Configurator provides easy execution of configuration without using the command line and editing a policy file without editing the XML policy file.
The Secure Policy Configurator requires the cysecuretools program, which is installed on Windows systems as a part of Python bundled with ModusToolbox™ 2.2 and later. For other operating systems, you can download it from PyPI or here:
2.1 Configuring cysecuretools location¶
For Windows, cysecuretools is installed in the appropriate ModusToolbox™ tools_<version> directory as a part of Python bundled with the software. The Secure Policy Configurator uses that installation by default.
For macOS and Linux, use one of the following ways:
Add the cysecuretools installation directory to the PATH environment variable.
Select File > Settings and configure a custom path directory to the cysecuretools location.
For detailed cysecuretools installation instructions, refer to the “Secure Boot” SDK user guide.
3 Quick start¶
The Quick Start section provides a simple workflow for how to use the Secure Policy Configurator.
3.1 Create an application¶
Follow instructions in the ModusToolbox™ user guide “Getting Started” chapter to create a new application for the PSoC™ 64 “Secure Boot” kit.
3.3 Create a policy file¶
To create a new policy file:
Select File > New to open the New Configuration dialog.
Using the New command creates multiple policy files (single-image, multi-image, swap), any of which can be selected for use with the project.
Next to the Project directory, click the Browse [ … ] button and navigate to and select the application directory, which contains the following by default:
/path/keys – Keys used for code signing and provisioning.
/path/packets – Provisioning packets.
/path/policy – Copied project policy options
/path/prebuilt – A stored prebuilt bootloader.
In the Target pull-down menu, select the appropriate device family or kit, and click OK.
Select File > Save in the main GUI to generate the user keys.
3.4 Provision a device¶
These are the minimum steps if you want to use the default policy settings:
Create or open an existing policy file.
Plug in the kit using the kit’s USB cable and connect the host computer to the kit. KitProg3 is powered via the USB cable.
The kit must be in DAPLink mode. Press the Mode button on the kit until the Status LED blinks fast. For details, refer to the KitProg3 User Guide.
Click Refresh Probe List on the toolbar.
Select the device from the Probe list in the toolbar.
Select Execute > Run Entrance Exam.
Select Execute > Provision Device.
If the device is already provisioned, select Execute > Reprovision Device instead.
The device must be initially configured to be reprovisioned (check the Reprovisioning Options in the Advanced tab) in order to be reprovisioned later.
4 Launch the Secure Policy Configurator¶
The best way to launch the Secure Policy Configurator is within the context of an application using either the make command or the Eclipse IDE. You can also open the configurator as a stand-alone tool. If you launch the configurator as part of an application, it defaults to the application directory. If you launch the configurator as a stand-alone tool, it defaults to the installation directory.
When launched, the Secure Policy Configurator attempts to open the default policy file from the /<path>/policy subdirectory. If the policy subdirectory and/or policy files do not exist, the configurator opens an empty window with a message to create a new or open an existing configuration (policy) file.
Create a new policy file as described under Create a policy file.
Use the File > Open menu to locate and open an existing policy file.
4.1 make command¶
As described in the ModusToolbox™ user guide “Build System” chapter, you can run numerous make commands in the application directory, such as launching the Secure Policy Configurator. After you have created a ModusToolbox™ application, navigate to the application directory and type the following command in the appropriate bash terminal window:
This command opens the Secure Policy Configurator GUI for the specific application in which you are working.
4.2 Eclipse IDE¶
To launch the Secure Policy Configurator from the Eclipse IDE, right-click on the project and select ModusToolbox™ > Secure Policy Configurator. You can also open the Secure Policy Configurator by clicking the link in the Eclipse IDE for ModusToolbox™ Quick Panel.
4.3 Executable (GUI)¶
You can launch the Secure Policy Configurator as a stand-alone tool by running its executable as appropriate for your operating system (for example, double-click it or select it using the Windows Start menu). By default, it is installed here:
When launched this way, the Secure Policy Configurator opens without a policy configuration file, and the default directory is where the configurator is installed. You can create a policy configuration file and save it in the application directory in a subdirectory named “secure”.
5 GUI description¶
The Secure Policy Configurator GUI contains menus, tabs, and dialogs to configure “secure policy” configuration files.
The toolbar contains several commands also available from the menus.
New – Creates a new “secure policy” directory.
Open – Opens an existing policy file (.json).
Save – Saves changes to the policy file. Generates a user key if it does not exist already.
Undo – Undoes the previous change.
Redo – Redoes the last undone change.
Execute – Equivalent to the Execute menu.
Probe – This is a drop-down menu of all the available probes currently connected to the PC. The user may select any of the listed probes for the actions in the Execute menu. A note displays to remind the user to switch the kit or programmer to DAPLink mode.
Refresh Probe List – Searches for a kit or programmer currently attached to the PC and repopulates the Probe list.
The Secure Policy Configurator contains several tabs in which to update various settings.
5.4 Notice List¶
The Notice List combines notices (errors, warnings, tasks, and any other information) from many places in your design into a centralized list. If a notice shows a location, you can double-click the entry to navigate to the error or warning. For details, refer to the description in the Device Configurator guide.
The log pane shows any errors or status. A log file collects the output of any executed script to the log pane. The placement of this log file is consistent with other tools in the build system.
5.6 Keys tab¶
The Key tab provides a method to associate a Key ID with the appropriate key file.
1, 2, 3, 11 – These keys cannot be modified by the configurator. They are reserved for other purposes.
4, 5, 6, 7, 8, 9, 10, 12 – The user keys whose entries can be modified. These keys can be loaded with keys provided by the OEM. Key ID 8 is the default user application key.
This field provides the Keys’ assignments.
The Browse [ … ] button on the right – to select which key is associated with the Key ID and configure the path to each key file.
5.7 Configuration tabs¶
Depending on the selected device and policy file, you will see varying tabs for configuration.
If you open or create a single-image policy file, the Configuration tab displays as follows:
5.7.2 Single-Image Swap mode¶
5.7.3 Multi-Image CM4 Configuration¶
For a multi-image policy file, there are two tabs: CM4 Configuration and CM0+ Configuration. The following shows the CM4 Configuration tab settings:
5.7.4 Multi-Image CM0+ Configuration¶
For a multi-image policy file, there are two tabs: CM4 Configuration and CM0+ Configuration The following shows the CM0+ Configuration tab settings:
5.8 Configuration parameters¶
The following describe the configuration parameters available in the Configuration tabs.
Some of the parameters display only in the specified tab.
5.8.1 Boot image (Primary Slot)¶
The memory location to execute code.
126.96.36.199 Start address¶
The location of the boot image.
188.8.131.52 Slot size (bytes)¶
The size of the boot image.
184.108.40.206 CM4 start address (Configuration tab)¶
This is the location in which the CM4 portion of the image starts. In Single-image mode, the CM0+ binary is combined with the user’s CM4 code binary.
220.127.116.11 Key signing ID¶
The key ID to check the boot image signature. The user must select one of the Custom keys (6-10) in the Keys
tab prior to provisioning.
18.104.22.168 CM4 debug option (Configuration and CM4 tabs)¶
CM0+ debug option (CM0+ Configuration tab)
Determine how to debug the CM4/CM0. The options:
Enable – Always enabled.
Disable – Always disabled.
Allow by Firmware – The debug access port may be enabled by the firmware.
Allow by Certificate – The debug access port may be enabled by the certificate.
22.214.171.124 CM4 debug token key ID (Configuration and CM4 Configuration tabs)¶
CM0+ debug token key ID (CM0+ Configuration tab)
The ID to the key to authenticate the debugger.
5.8.2 Version control¶
This box includes three options for firmware upgrade version control and rollback.
126.96.36.199 Monotonic counter ID¶
Prevents a rollback during the upgrade process
188.8.131.52 Rollback counter value¶
The initial counter value.
184.108.40.206 Image version¶
The version of the image for the MCU Boot header.
5.8.3 Start WDT¶
This check box is available on the Single-image Configuration tab or the Multi-image CM0+ Configuration tab. The watchdog timer is used to protect the device from freezing after updating with an incorrect CM4 or CM0+ image. If this check box is enabled, the timer is used to reset the device and revert to the previous image. This setting applies to the entire application, and it is separate from the Start WDT setting on the Advanced dialog.
This occurs only if Swap mode is enabled on a CYxx64xA device.
220.127.116.11 WDT timeout (ms)¶
The parameter to set the time (in milliseconds) after which the device resets automatically (if the watchdog timer has not been reset previously by the firmware).
18.104.22.168 Set image OK (Swap mode only)¶
After a swap upgrade is completed, the new image updates the flash contents to mark itself “OK”, so the bootloader can choose to run it during the next boot. On a startup, the bootloader inspects the flash contents to decide if swapping of the application images was completed.
Depending on the use case, the swap can also be made permanent directly (by setting the “image OK” flag during the image signing). In this case, the bootloader will never attempt to revert the images on the next reset.
In a multi-image case, the bootloader considers “image OK” flags of each image separately, so both user applications must set the “image ok” flag in their own areas because they consider the “image OK” flags of images separately.
5.8.4 Upgrade image (Secondary Slot)¶
The memory location to stage code for the CM0+ upgrade.
5.8.5 Upgrade enabled¶
If checked, firmware upgrades are allowed.
22.214.171.124 External memory¶
Specifies the SMIF ID (if any) to upgrade the image. The options:
0 – SMIF Disabled
Slave Select – 1
Slave Select – 2
Slave Select – 3
Slave Select – 4
126.96.36.199 Start address¶
The location (Secondary/Slot 1) where the upgrade firmware is stored or staged prior to the bootloader transferring it to the Primary Slot.
188.8.131.52 Slot size (bytes)¶
The size of the upgraded image.
5.8.6 Encrypt upgrade image¶
This check box determines if the upgrade image must be encrypted.
184.108.40.206 Image encryption key ID¶
Specifies the key to use the upgrade image encryption.
Unique Device Key (ID 1)
Group Encryption Key (ID 12)
220.127.116.11 Encrypt peer key path¶
The path to the public key file for image encryption. The key is of the Elliptic Curve Digital Signature Algorithm (ECDSA) type; the file is of the Privacy Enhanced Mail (PEM) format.
5.8.7 Protected SRAM (Configuration and CM0+tabs)¶
Indicates the memory region for the “secure” CM0+ CPU. The user must not change this from the default unless the CM0+ code has been changed for a special case.
The start address of the Protected SRAM location.
18.104.22.168 Size (bytes)¶
The size of the Protected SRAM region.
5.9 Certificates tab¶
The Certificate tab is used to create and add certificates.
5.9.1 Add certificate¶
Clicking the Add Certificate button provides the user with the options to obtain a certificate.
22.214.171.124 Create new certificate¶
Choosing the “Create new certificate” option displays the Certificates window.
Providing a new public key certificate ensures the secure communication over the Internet. Certificate creation will be skipped if a certificate file already exists.
Certificate creation cannot be executed if the target device is not provisioned.
The user completes the following fields:
Subject – The title for the certificate.
Country – The name of the country where the certificate is issued.
State – The name of the state where the certificate is issued.
Organization – The name of the organization where the certificate is issued.
Issuer name – The name of the person by whom the certificate is issued.
Root key path – The path to the private key file.
Device certificate path –The location to store the created certificate.
Encoding – Displays the format of the certificate to be created – PEM or DER. The default is PEM.
The Subject, Country, State, Organization, and Issuer name parameters must include only alphanumeric symbols.
After completing the fields, click the Create certificate button to add a new entry to the certificates table.
126.96.36.199 Load existing certificate¶
Choosing the “Load existing certificate” option displays a file dialog box to allow the user to select an-existing certificate file.
6 Advanced dialog¶
The Advanced dialog contains the parameters used for editing policy files. Two versions of the Advanced dialog display depending on the selected policy file: for Overwrite and Swap upgrade modes. For Swap mode, select a policy file with the swap suffix.
The following describe the configuration parameters available in the Advanced dialog.
Some of them display only under operation in Swap mode (specified in the description).
6.1 SysAP Options¶
These options configure the system access port.
Enabled –Always enabled. The default option – debugging of the CM4 application is always allowed.
Disabled – Always disabled. Debugging of the CM4 application is never allowed.
Allowed – Controlled by the firmware.
6.1.2 Enable flash reads¶
If checked, the SysAP can read the flash memory.
Leaving the SysAP in production will create a security risk.
6.1.3 Enable flash writes¶
If checked, the SysAP can write the flash memory.
6.2 RMA Options¶
These options control if RMA is allowed, which key to use, and what memory to be erased.
6.2.1 RMA allowed¶
Enables or disables the RMA process.
Enabled – Always enabled.
Disabled – Always disabled.
Allowed – Controlled by the firmware.
188.8.131.52 RMA token key ID¶
The IDs to the RMA certificate keys.
6.2.2 Destroy flash region¶
If there are secrets in the user’s flash, the Destroy Flash region option allows erasing the user’s secrets in flash
to prevent their disclosure.
This option does not destroy the device; it only erases flash.
6.2.3 Flash start address¶
Configures the range of flash to be erased during the RMA process.
6.2.4 Flash size (bytes)¶
Configures the range of flash to be erased during the RMA process.
6.3 Startup Options¶
6.3.1 Startup clock¶
Configures the initial clock speed.
6.3.2 Debug listen window¶
Configures the amount of time the device waits for an SWD command during the startup.
6.4 Bootloader Options¶
6.4.1 Bootloader mode¶
Configures the debugging output.
Debug – The bootloader produces debugging messages.
Release – The bootloader does not produce debugging messages.
Custom – This enables the user to build their own bootloader and provision it. This feature is not currently supported.
6.4.2 Signing key¶
The private key to sign the bootloader certificate.
6.4.3 HEX file¶
The bootloader application/program file.
6.4.4 JWT file¶
The bootloader certificate file.
6.4.5 Status partition (Swap mode)¶
An extra flash area to store the Swap status for the upgrade and revert images.
6.5 Reprovisioning Options¶
Enable reprovisioning of bootloader – Check this box to enable the bootloader reprovisioning. This allows the OEM to update the bootloader at a later date (not only during development).
Enable reprovisioning of policies – Check this box to enable the policy reprovisioning. This allows the OEM to reprovision policies at a later date.
6.6 Start WDT in CM0+ (bootloader)¶
This watchdog timer (WDT) is used to protect the device from freezing after updating with an incorrect CM0+ image. If this check box is enabled for the bootloader, the timer is used to reset the device and revert to the previous image. This setting applies only to the bootloader, and it is separate from the Start WDT setting on the Configuration tab.
6.6.1 WDT timeout (ms)¶
The parameter to define the time after which the device resets automatically (if the watchdog timer has not been reset previously by the firmware).
7 Version changes¶
This section lists and describes the changes for each version of this tool.
Fixed minor defects.
Updated the “Installation” section with ways to install CySecureTools for macOS and Linux.
Added Scratch area.
Changed the address format to uppercase.
Updated the “Quick start” section.
Changed the device library file from xml to props.json.
Updated the title from “Secure Policy” Configurator to Secure Policy Configurator.
Updated the MPN name in section “Configuration Parameters” “Start WDT”.
Updated to version 1.10.
Updated to version 1.20.
Updated the “Quick start” section flow – changed the “secure” subdirectory for the application directory.
Updated to version 1.30.