README_PSOC64.md

Table of Contents

• Main features
• Quick start
• Usage example
• Policy
• Keys
• Command-line interface
  • Tool help
  • Common options
  • Create keys
  • Create provisioning packet
  • Provision device
  • Reprovision device
  • Sign image
  • Convert bin to hex
  • Entrance exam
  • Create a certificate
  • Create image certificate
  • Flash map methods
  • Encrypted programming
    • Create encrypted image
    • Program encrypted image
    • Programming encrypted bootloader
    • Programming encrypted user application
  • CyBootloader and Secure Flash Boot version
  • Sign DAP certificate
  • Transit to RMA
  • Open RMA
  • Read public key from device
  • Read die ID from device
  • Commands to use with HSM
    • Add metadata to image
    • Extract payload for signing
    • Add signature to image
• Using package together with HSM
  • Converting key public numbers to JWK
  • Signing application with HSM
• Closing All Access Ports
• Open CM0 Access Port
• RMA
• CyBootloader
  • Custom Bootloader
  • Encrypted Bootloader

Main features

• Create keys - A key is a file used to authorize access to device data. There must be a common key pair between the secure device and user application. A device must be provisioned with a public key and the user application must be signed with a corresponding private key from the same pair.
• Entrance exam - Passing an entrance exam before provisioning a device is an option to ensure that the device has the valid state.
• Provisioning a device - Provisioning is the act of configuring a device with an authorized set of keys, certificates, and policies.
• Sign a user application - To run a user application on a secure device, the application must be signed with the key provisioned to the device earlier.
• Create a certificate - Create a certificate in the X.509 format: with the device public key inside and signed with the private key. The certificate can be used when connecting to a cloud service.
• Create image certificate - Based on an image, create a JWT that certifies the image's validity.
• Output CyBootloader and Secure Flash Boot version - Outputs CyBootloader and Secure Flash Boot version.

Quick start

1. Set a path to the On-Chip debugger

$ cysecuretools set-ocd --name openocd --path <PATH_TO_OPENOCD_ROOT_DIRECTORY>

Make sure you provide the path to the root directory of OpenOCD (NOT bin directory). Specifying the path is not mandatory if you have ModusToolbox™ installed on your machine. OpenOCD from the ModusToolbox™ directory is used by default.

Example:

$ cysecuretools set-ocd --name openocd --path /Users/username/tools/openocd

2. Define a target

Run the following command and find the name of your target in the list of supported targets.

$ cysecuretools device-list

This target name will be used as a -t option value with each command.

Example:

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p <POLICY> <COMMAND> [OPTIONS]

3. Create a new project

This copies the list of files required to start using the tool to the current working directory.

$ cysecuretools -t <TARGET> init

4. Define the policy

Select the policy with which the device will be provisioned. All available policy files are located in the policy directory of the project.

This policy file will be used as a -p option value with each command.

Example::

$ cysecuretools -t <TARGET> -p policy/policy_single_CM0_CM4_swap.json <COMMAND> [OPTIONS]

5. Create keys

The public key is programmed during the provisioning for further image verification. The private key is used to sign the image with the user application. Create a private key. The public part of the key will be taken from the private during provisioning.

$ cysecuretools -t <TARGET> -p <POLICY> create-keys

6. Provision the device

$ cysecuretools -t <TARGET> -p <POLICY> provision-device

7. Sign the image

$ cysecuretools -t <TARGET> sign-image --image example-blinky.hex --output example-blinky-signed.hex --image-type BOOT

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W init
$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json create-keys
$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json provision-device
$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json sign-image --image example-blinky.hex --output example-blinky-signed.hex --image-type BOOT
$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json re-provision-device

Policy

Policy Types

The package contains the following policy types for the PSoC 64 target:

• for single image bootloader with a Swap upgrade method - policy_single_CM0_CM4_swap.json
• for single image bootloader with a Swap upgrade method and use of external memory - policy_single_CM0_CM4_smif_swap.json
• for multi-image bootloader with a Swap upgrade method and use of external memory - policy_multi_CM0_CM4_swap.json
• for multi-image bootloader with a Swap upgrade method and use of external memory - policy_multi_CM0_CM4_smif_swap.json

Policy Location

After creating a project (by using the init command), the policy files can be found in the policy directory of the project.

Custom Data Sections

Policy file can contain optional list of sections, e.g.:

{
    "custom_data_sections": ["abc", "xyz"],
    "abc":
    {
        ...
    },
    "xyz":
    {
        ...
    }
}

All listed sections content will be added to the provisioning JWT packet. These data sections are simply copied raw without validation or filtering.

Keys

Keys Location

After creating a project (by using the init command), the keys will be located in the keys directory of the project. The keys location can be changed in the policy file. Either an absolute or relative path can be used. A relative path is related to the policy file location.

Example:

{
    "boot_auth": [
        8
    ],
    "boot_keys": [
        { "kid": 8, "key": "../keys/USERAPP_CM4_KEY.json" }
    ],
    "id": 4,
    "monotonic": 0,
    "smif_id": 0,
    "upgrade": true,
    "version": "0.1",
    "rollback_counter": 0,
    "encrypt": true,
    "encrypt_key_id": 1,
    "encrypt_peer": "../keys/dev_pub_key.pem",
    "resources": [
        {
            "type": "BOOT",
            "address": 268435456,
            "size": 327680
        },
        {
            "type": "UPGRADE",
            "address": 268763136,
            "size": 327680
        }
    ]
}

Key IDs

ID	Description
1	Device Private Key for key derivation
2	Device Private Key for signing (Unique per device. This is a copy of Key ID 1.)
3	Cypress Public Key
4	HSM Public Key. In the context of the PSoC 64 "Secure Boot MCU", the HSM key is a key of a device programming engine placed in a physically secure facility. The HSM key bundled with the package has the example purpose only and must not be used in production
5	OEM Public Key
6	Custom Key 1
7	Custom Key 2
8	Custom Key 3
9	Custom Key 4
10	Custom Key 5
11	AES 256-bit Key derived from 128-bit UDS for key derivation (Reserved)
12	Group Encryption Key

ID:

• 1, 2, 3, 11 – These keys cannot be modified. 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.

Command-line interface

This section contains the main CLI commands. More commands can be found in the tool help.

Tool help

To see the list of commands supported for a specific target:

$ cysecuretools -t <TARGET> --help

To see the list of options for a specific command:

$ cysecuretools -t <TARGET> <COMMAND> --help

Common options

The interface provides common options. These options are common for all commands and must precede them:

Name	Description
-t, --target	Device name or family.
-p, --policy	Provisioning policy file.
-v, --verbose	Provides debug-level log.
-q, --quiet	Quiet display option.
--logfile-off	Avoids logging into file.

Create keys

Creates keys specified in the policy file for the image signing.

Command: create-keys

Parameters

Name	Optional/Required	Description
--overwrite / --no-overwrite	optional	Indicates whether overwrite the keys in the output directory if they already exist. If omitted, a prompt will ask whether to overwrite the existing keys.
-o, --out	optional	The output directory for generated keys. By default, the keys location will be as specified in the policy file.
--kid	optional	The ID of the key to create. If not specified, all the keys found in the policy file will be generated.
-a, --algorithm [KeyAlgorithm.EC|KeyAlgorithm.RSA]	optional	Sets algorithm for creating the keys.
--template	optional	A path to a JSON file containing public numbers.

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json create-keys --overwrite

Create provisioning packet

Creates a JWT packet (a file to be programmed into the device during the provisioning procedure). In general, this is a policy, keys, and certificates in the JWT format.

Command: create-provisioning-packet

Parameters

No parameters required.

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json create-provisioning-packet

Provision device

Starts a device provisioning process.

WARNING: This operation can be done with the SECURE UNCLAIMED device only. SECURE UNCLAIMED means it was not provisioned before, so does not have an identity assigned. Once device was provisioned it is considered as a SECURE CLAIMED and further identity assigning is not possible. It can be re-provisioned with the re-provision-device command.

NOTE: There is a reprovision field in the policy file, configuring the ability to reprovision a bootloader, keys, and policy. These values cannot be changed once provisioned to the device.

Command: provision-device

Parameters

Name	Optional/Required	Description
--probe-id	optional	The probe serial number. Can be used to specify a probe if more than one device is connected to a computer.
--existing-packet	optional	Skip the provisioning packet creation and use the existing packet.

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json provision-device

Reprovision device

Starts a device re-provisioning process.

Command: re-provision-device

Parameters

Name	Optional/Required	Description
--probe-id	optional	The probe serial number. Can be used to specify a probe if more than one device is connected to a computer.
--existing-packet	optional	Skip the provisioning packet creation and use the existing packet.
--control-dap-cert	optional	The certificate that provides the access to control DAP. For more information refer to Open CM0 Access Port.
--erase-boot	optional	Indicates whether to erase BOOT slot.

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json re-provision-device

Sign image

Signs the user application with a key.

The file specified in the --image option will be signed and saved to the file specified in the --output option. If the --output is not specified, a copy of the original file will be created with the _unsigned suffix and the input file will be signed.

Command: sign-image

Parameters

Name	Optional/Required	Description
--image	required	User application image (hex or bin).
-i, --image-id	optional	The ID of the firmware image in the device. The default value is 1.
--image-type	optional	Indicates which type of an image is signed - boot or upgrade. If omitted, both types will be generated. Accepted only BOOT or UPGRADE values.
-e, --encrypt	optional	Public key PEM-file for the image encryption.
-R, --erased-val	optional	The value that is read back from erased flash.
--boot-record	optional	Represents the role of the software component (e.g. CoFM for coprocessor firmware) [max. 12 characters]
-o, --output	optional	Signed image output file. The option should only be used with --image-type.
--protected-tlv	optional	Custom TLV that will be placed into a protected area. Add the "0x" prefix if the value should be interpreted as an integer, otherwise it will be interpreted as a string. Specify the option multiple times to add multiple TLVs.
--upgrade-mode [swap|overwrite]	optional	Image upgrade mode. The default value is overwrite.
--align [1|2|4|8]	optional	Sets flash alignment. The default value is 8.
--min-erase-size	optional	Sets minimum erase size. Note that this parameter is only applicable for external memory.

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json sign-image --image example-blinky.hex --output example-blinky-signed.hex --image-type BOOT --image-id 1

Convert bin to hex

Converts image of bin format to hex format.

Command: bin2hex

Parameters

Name	Optional/Required	Description
--image	required	Input bin file
-o, --output	required	Output hex file
--offset	optional	Starting address offset for loading bin

Usage example

$ cysecuretools bin2hex --image image.bin --output image.hex --offset 0x20000

Entrance exam

Checks the device life-cycle, Flashboot firmware, and Flash memory state.

Command: entrance-exam

Parameters

Name	Optional/Required	Description
--probe-id	optional	The probe serial number. Can be used to specify a probe if more than one device is connected to a computer.

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json entrance-exam

Create a certificate

Creates a certificate in the X.509 format based on the device public key.

Command: create-certificate

Parameters

Name	Optional/Required	Description
-n, --name	optional	The certificate filename. By default 'psoc_cert.pem'
-e , --encoding	optional	The certificate encoding (PEM, DER). By default 'PEM'
--probe-id	optional	The probe serial number.
--subject-name	optional	The certificate subject name. By default 'Example Certificate'
--country	optional	The certificate country code. By default 'US'
--state	optional	The certificate issuer state. By default 'San Jose'
--organization	optional	The certificate issuer organization. By default 'Cypress Semiconductor'
--issuer-name	optional	The certificate issuer name. By default 'Example Issuer Name'
--private-key	optional	The private key to sign the certificate. By default HSM private key

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json create-certificate -e DER --private-key priv_key.json

Create image certificate

Creates Bootloader image certificate.

Command: image-certificate

Parameters

Name	Optional/Required	Description
-i, --image	required	The bootloader image path.
-k, --key	required	The private key for certificate signing.
-o, --cert	optional	The output certificate file path.
-v, --version	optional	The image version.
--image-id	optional	The image ID.
-d, --exp-date	optional	The certificate expiration date.

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json image-certificate -i CypressBootloader_CM0p.hex --key ../keys/key.json -o CypressBootloader_CM0p.jwt --version "1.0.0.200" --image-id 0 --exp-date "Jan 1 2031"

Encrypted programming

The encrypted programming consists of two steps:

• Create encrypted image
• Program encrypted image

Create encrypted image

Creates encrypted image for encrypted programming.

Command: encrypt-image

Parameters

Name	Optional/Required	Description
-i, --image	required	The image to encrypt.
-h, --host-key-id	required	Host private key ID (4 - HSM, 5 - OEM).
-d, --device-key-id	required	Device public key ID (1 - device, 12 - group).
--key-length	optional	Derived key length.
-o, --encrypted-image	required	Output file of encrypted image for encrypted programming.
--padding-value	optional	Value for image padding.
--probe-id	optional	Probe serial number. Used to read device public key from device.

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json encrypt-image -i BlinkyApp.hex -h 4 -d 1 -o encrypted_image.txt

Program encrypted image

Programs encrypted image.

Command: encrypted-programming

Parameters

Name	Optional/Required	Description
-i, --encrypted-image	required	The encrypted image to program.
--probe-id	optional	Probe serial number.

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json encrypted-programming -i encrypted_image.txt

Programming encrypted bootloader

During device provisioning, the bootloader can be programmed in encrypted format. This requires following steps:

1. Create image certificate for your custom bootloader application (refer Create image certificate).

2. Encrypt bootloader application (refer Create encrypted image).

3. Update policy with the encrypted bootloader file:

   In the policy file, set the bootloader mode to custom and provide bootloader program file (hex_path) and image certificate (jwt_path). To indicate that the image is encrypted, set encrypted field to true. If custom bootloader is not encrypted, set encrypted field to false or do not specify it. Absolute or relative path can be used. Relative path is related to the policy file location.

   "cy_bootloader":
    {
        "mode": "custom",
        "hex_path": "encrypted_image.txt",
        "jwt_path": "CypressBootloader_CM0p.jwt",
        "encrypted": true
    },

Programming encrypted user application

This requires following steps:

1. Encrypt application (refer Create encrypted image).

2. Update policy with the encrypted bootloader file:

   In the policy file pre_build field add user_apps field as shown below. To indicate that the image is encrypted, set encrypted_ field to true. If the application is not encrypted, set encrypted field to false. Absolute or relative path can be used. Relative path is related to the policy file location.

   "pre_build": {
        ...
        "user_apps": [
            { "encrypted": true, "app": "encrypted_image.txt" },
            { "encrypted": true, "app": "encrypted_image.txt" }
   }

CyBootloader and Secure Flash Boot version

Outputs CyBootloader version bundled with the package. Outputs CyBootloader and Secure Flash Boot version programmed into device.

Command: version

Parameters

Name	Optional/Required	Description
--probe-id	optional	Probe serial number.

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W version

Sign certificate

Signs JSON certificate with the private key.

Command: sign-cert

Parameters

Name	Optional/Required	Description
--template	required	Certificate template.
-k, --key-id	required	Private Key ID to sign the certificate with (1 - DEVICE, 4 - HSM, 5 - OEM, 12 - GROUP).
-o, --output	optional	Filename where to save the JWT. If not specified, the input file name with "jwt" extension will be used.

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json sign-cert --template packets/control_dap_cert.json --output packets/control_dap_cert.jwt --key-id 5

Transit to RMA

Transits device to the RMA lifecycle stage using system AP. See the RMA section for the complete flow.

After each reset ROM boot code will wait on OpenRMA system call to open full access. See RMA usage instructions for the complete flow.

Command transit-to-rma

Parameters

Name	Optional/Required	Description
-c, --cert	required	Path to debug certificate.
--probe-id	optional	Probe serial number.

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W transit-to-rma --cert packets/control_dap_cert.jwk

Open RMA

Enables full access to device in RMA lifecycle stage using system AP. See the RMA section for the complete flow.

Command open-to-rma

Parameters

Name	Optional/Required	Description
-c, --cert	required	Path to debug certificate.
--probe-id	optional	Probe serial number.

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W open-rma --cert packets/control_dap_cert.jwk

Read public key from device

Reads public key from device.

Command read-public-key

Parameters

Name	Optional/Required	Description
-k, --key-id	required	Key ID to read (1 - DEVICE, 4 - HSM, 5 - OEM, 12 - GROUP).
-f, --key-format	optional	Key format (jwk or pem). Default is 'jwk'.
-o, --out-file	optional	Filename where to save the key. If not specified, the log file is used for output.
--probe-id	optional	Probe serial number.

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W read-public-key --key-id 5 --out-file oem_pub.jwk

or

$ cysecuretools -t CY8CKIT-064B0S2-4343W read-public-key --key-id 5 --key-format pem --out-file oem_pub.pem

Read die ID from device

Reads die ID from device.

Command: read-die-id

Parameters

Name	Optional/Required	Description
-o, --out-file	optional	Filename where to save die ID. If not specified, the log file is used for output.
--probe-id	optional	Probe serial number.

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W read-die-id -o die_id.json

Commands to use with HSM

Add metadata to image

Adds metadata to image (header, protected and unprotected TLVs) to convert it into MCUboot format.

Command: image-metadata

Parameters

Name	Optional/Required	Description
--image	required	User application image (hex or bin).
-i, --image-id	optional	The ID of the firmware image in the device. The default value is 1.
--image-type	required	Indicates which type of an image is signed - boot or upgrade.
-e, --encrypt	optional	Public key PEM-file for the image encryption.
-R, --erased-val	optional	The value that is read back from erased flash.
--upgrade-mode	optional	Image upgrade mode (overwrite or swap). The default value is overwrite.
--align	optional	Flash alignment (1, 2, 4, 8). The default value is 8.
--boot-record	optional	Represents the role of the software component (e.g. CoFM for coprocessor firmware) [max. 12 characters]
--pubkey	optional	Public key for the further image verification (PEM format). If not specified, user custom key from the policy will be used.
-o, --output	required	Binary (bin) file where to save the image with metadata.
--decrypted	optional	A path where to save decrypted image payload (bin). Must be used for signing encrypted images.
--tlv	optional	Custom TLV that will be placed into an unprotected area. Add the "0x" prefix if the value should be interpreted as an integer, otherwise it will be interpreted as a string. Specify the option multiple times to add multiple TLVs.
--protected-tlv	optional	Custom TLV that will be placed into a protected area. Add the "0x" prefix if the value should be interpreted as an integer, otherwise it will be interpreted as a string. Specify the option multiple times to add multiple TLVs.

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json image-metadata --image BlinkyApp.hex --output BlinkyApp_meta.bin --pubkey keys/USERAPP_CM4_KEY.pem --image-type BOOT --image-id 1

Extract payload for signing

Extract a part of the image that has to be signed.

Command: extract-payload

Parameters

Name	Optional/Required	Description
--image	required	Image with MCUboot metadata (bin).
-o, --output	required	A path where to save image that has to be signed (bin).

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W extract-payload --image BlinkyApp_meta.bin --output BlinkyApp_payload.bin

Add signature to image

Adds signature saved to a binary file into existing MCUboot format image.

Command: add-signature

Parameters

Name	Optional/Required	Description
--image	required	Image with metadata (bin).
-s, --signature	required	Binary file containing signature.
-o, --output	required	A path where to save image with the signature (bin).

Usage example

$ cysecuretools -t CY8CKIT-064B0S2-4343W add-signature --image BlinkyApp_meta.bin --output BlinkyApp_signed.bin --signature ec_signature_asn.bin

Using package together with HSM

To protect your private keys, the cryptographic operations can be delegated to a Hardware Security Module (HSM). The flow of using the package with an HSM is different from the standard flow because of the necessity to sign the image using different tool, provided by HSM vendor. HSM gets an image as an input, then signs it, and returns a signature without a payload. Then this signature has to be added to the payload in a specific format.

Converting key public numbers to JWK

If the HSM provider exports public part of the key as a modulus and exponent, this data must be converted to the PEM format.

Example of the Utimaco CryptoServer public key format:

# ECC key
CURVE=secp256r1
PUB=0445415FFCCD599E39BE05D303F43BACE8E0CD25999D56F2A8D923195582ADAB8415E56C7B0488CD9BC95550B9B4CA3F524C2F8E1E4EE40E64E977D0F7F205619F

Copy the public numbers from the exported key to the ec_key_tmpl.json file located in the packets directory of your project and convert it to JWK:

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json create-keys --template packets/ec_key_tmpl.json

Signing application with HSM

The flow:

1. Export the HSM public key to a file using tools provided by HSM vendor.
2. Convert the exported key to the JWK format.
3. Provision/reprovision device using generated public key.
4. Add metadata to the image (header, protected and unprotected TLVs) to convert it into MCUboot format.
5. Extract payload - extract a part of the image that has to be signed.
6. Sign the payload with HSM.
7. Add the signature returned by HSM to the image with metadata, created in the fourth step.

Step 1

Using the tools provided by your HSM vendor, export the public key numbers to a file. The key will be added to the image for further verification.

Step 2

If your HSM vendor allows exporting public keys directly to the JWK format, then this step can be skipped. However, if the HSM vendor exports the public part of the key as a numbers, this data must be converted to the JWK format (see Converting key public numbers to JWK).

Step 3

For the further image verification the public key need to be provisioned/reprovisioned to the device.

Provisioning:

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json provision-device

Reprovisioning:

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json re-provision-device

Step 4

Add metadata to the image - mcuboot header, protected TLV, and unprotected TLV.

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json image-metadata --image BlinkyApp.hex --output BlinkyApp_meta.bin --pubkey keys/USERAPP_CM4_KEY.pem --image-type BOOT --image-id 1

IMPORTANT: in case of using image encryption, provide output file for the decrypted payload. Image signature is calculated based on decrypted data.

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json image-metadata --image BlinkyApp.hex --output BlinkyApp_meta.bin --pubkey keys/USERAPP_CM4_KEY.pem --image-type BOOT --image-id 1 --encrypt keys/dev_pub_key.pem --decrypted BlinkyApp_decrypted.bin

NOTE: next steps manipulate with binary files.

Step 5

The MCUboot format image consists of the part that has to be signed, and the part that has not to be signed. To calculate the signature correctly, from the image extract a part that has to be signed.

$ cysecuretools -t CY8CKIT-064B0S2-4343W extract-payload --image BlinkyApp_meta.bin --output BlinkyApp_payload.bin

IMPORTANT: in case of using image encryption, make sure to specify the decrypted payload to HSM. Image signature is calculated based on decrypted data.

$ cysecuretools -t CY8CKIT-064B0S2-4343W extract-payload --image BlinkyApp_decrypted.bin --output BlinkyApp_payload.bin

Step 6

Use the tools provided by your HSM vendor to sign the payload with the HSM. Save the signature returned by the HSM to a file. The format of the MCUboot signature is ASN.1 (binary decoded).

Step 7

Run the add-signature command and provide the signature file created by the HSM. As an input image use the image with metadata created in the step #4.

$ cysecuretools -t CY8CKIT-064B0S2-4343W add-signature --image BlinkyApp_meta.bin --output BlinkyApp_signed.bin --signature ec_signature_asn.bin

Closing All Access Ports

Often it is necessary to close all access ports during provisioning. After closing the access ports, there will be no way to program application. In this case, the application can be programmed during the provisioning process, when the access ports are open. Refer Programming encrypted user application.

Open CM0 Access Port

System AP must be enabled since it is used to open CM0 AP.

There is a way to close CM0 access port and allow to open it using a certificate. To close CM0 port with the ability of further opening, provision the device with the following configuration of m0p in the policy file:

"m0p" : {
    "permission" : "allowed",
    "control" : "certificate",
    "key" : 5
}

The above configuration means that the CM0 AP can be opened with certificate. The certificate must be signed with the key with ID 5. The certificate can be found in the packets directory (look for control_dap_cert.json).

Sign DAP certificate

Once device was provisioned with the above m0p configuration, the AP can be opened with the certificate.

To sign the DAP certificate refer to Sign certificate section. The key ID used to sign the certificate must match the key ID specified in the policy file m0p properties.

Re-provision and open CM0 access port

Re-provision device using the certificate to open CM0 access port for programming bootloader program file.

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json re-provision-device --control-dap-cert packets/control_dap_cert.jwt

NOTE: The access port opens for a short time to program bootloader during re-provisioning.

RMA

Following is the flow for the transition device to the RMA lifecycle stage and open DAP.

1. Create a certificate

For the transition of the device into the RMA lifecycle stage you need to create a certificate, which contains the device DIE_ID and is signed with the key specified in the rma section of the policy. The certificate template is located in the packets directory of the project. control_dap_cert.json defines the DIE_ID of the devices the certificate can be applied to. The default template min and max values are applicable for all devices. Modify it for specific devices only if needed.

Default Template

{
  "auth": {
    "die_id": {
      "max": {
        "day": 255,
        "lot": 16777215,
        "month": 255,
        "wafer": 255,
        "xpos": 255,
        "year": 255,
        "ypos": 255
      },
      "min": {
        "day": 0,
        "lot": 0,
        "month": 0,
        "wafer": 0,
        "xpos": 0,
        "year": 0,
        "ypos": 0
      }
    }
  }
}

Signing

Make sure you use the ID of the key specified in the rma section of the policy the device has been provisioned with.

$ cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json sign-cert --template packets/control_dap_cert.json --output packets/control_dap_cert.jwt --key-id 5

2. Transition to RMA

Transition a part from the SECURE to the RMA lifecycle stage. Before the transitioning fuses and flash will be destroyed as specified in the destroy_fuses and destroy_flash sections of the device policy.

$ cysecuretools -t CY8CKIT-064B0S2-4343W transit-to-rma --cert packets/control_dap_cert.jwk

3. Open RMA

To open the DAP of the device in the RMA lifecycle stage use the same certificate as for the transition to RMA.

$ cysecuretools -t CY8CKIT-064B0S2-4343W open-rma --cert packets/control_dap_cert.jwk

After successful DAP opening, DO NOT reset the device and launch a debug session with a debugger.

CyBootloader

By default, the tools use release mode of CyBootloader. This does not output CyBootloader logs to the serial port, but it has a smaller size. The debug mode of CyBootloader allows seeing its logs using the serial port with the baud rate 115200. To change CyBootloader mode, change the cy_bootloader field in the policy file:

for the debug mode

"cy_bootloader":
{
    "mode": "debug"
}

for the release mode

"cy_bootloader":
{
    "mode": "release"
}

Custom Bootloader

To use a custom bootloader, specify value custom in the cy_bootloader mode field. Also, it requires the specifying bootloader image (hex_path) and its certificate (jwt_path). A bootloader image certificate is a JWT file that confirms the image's validity. To create an image certificate, use the image certificate creation command.

"cy_bootloader":
{
    "mode": "custom",
    "hex_path": "../prebuilt/CyBootloader_WithLogs/CypressBootloader_CM0p.hex",
    "jwt_path": "../prebuilt/CyBootloader_WithLogs/CypressBootloader_CM0p.jwt"
}

Encrypted Bootloader

Refer Programming encrypted bootloader.