Use cases
This section contains the following use cases:
- Use case 1: Shifting non-secure app to secure region and signing
- Use case 2: Signing two images located in the internal flash and in the external flash
- Use case 3: Signing hex containing EEPROM segment
- Use case 4: Signing encrypted image with HSM
Use case 1: Shifting non-secure app to secure region and signing
There are two segments in the image. The first one is located in the secure memory region. The second one in the non-secure. The following JSON shows how to shift data from the non-secure memory region to secure memory region.
{ "schema-version": 1.0,
"content": [
{
"name" : "CM33_Secure_CM33_Non_Secure",
"description": "Use case 1: Shifting non-secure app to secure region and signing",
"enabled": true,
"commands": [
{ "command": "shift",
"inputs": [
{ "description": "CM33 Secure + CM33 Non-Secure application",
"file": "app-path/cm33s_cm33ns.hex",
"address" : "0x2201F000"
}
],
"outputs" : [
{ "description": "Application shifted to secure region",
"address" : "0x3201F000",
"file" : "out-path/cm33s_cm33ns_shifted.hex"
}
]
},
{
"command": "sign",
"inputs": [
{ "description": "Shifted CM33 Secure + CM33 Non-Secure application",
"file": "out-path/cm33s_cm33ns_shifted.hex"
}
],
"outputs" : [
{ "description": "Signed CM33 Secure + CM33 Non-Secure",
"signer-key" : "/key-path/signing_private_key.pem",
"format" : "ihex",
"file" : "out-path/cm33s_cm33ns_signed.hex",
"header-size": "0x400",
"fill-value": "0x00"
}
]
}
]
}
]
}
Use case 2: Signing two images located in the internal flash and in the external flash
This use case shows how to sign both non-contiguous segments. The first one is located in the internal memory, and the second one in the external memory. The signing result may be a very large file because the data are converted to a binary format. Following JSON shows how to split the segments, sign each of them, and then combine back to a single file.
{
"schema-version": 1.0,
"content": [
{
"name" : "Signed Internal and External Flash Applications",
"description": "Use case 2: Signing two images located in the internal flash and in the external flash",
"enabled": true,
"commands": [
{ "command": "hex-segment",
"inputs": [
{ "description": "Extract Internal Flash segment",
"file": "app-path/ble_app_psoc64.hex",
"address" : "0x10000000"
}
],
"outputs" : [
{ "description": "Save Flash segment",
"format" : "ihex",
"file" : "out-path/internal.hex"
}
]
},
{
"command": "hex-segment",
"inputs": [
{ "description": "Extract External Flash segment",
"file": "app-path/ble_app_psoc64.hex",
"address" : "0x18000000"
}
],
"outputs" : [
{ "description": "Save EEPROM segment",
"format" : "ihex",
"file" : "out-path/external.hex"
}
]
}, {
"command": "sign",
"inputs": [
{ "description": "Signs Internal Flash Application",
"file": "out-path/internal.hex"
}
],
"outputs" : [
{ "description": "Signed Internal Flash Application",
"signer-key" : "/key-path/signing_private_key.pem",
"format" : "ihex",
"file" : "out-path/internal_signed.hex"
}
]
},
{
"command": "sign",
"inputs": [
{ "description": "Signs External Flash Application",
"file": "out-path/external.hex"
}
],
"outputs" : [
{ "description": "Signed External Flash Application",
"signer-key" : "/key-path/signing_private_key.pem",
"format" : "ihex",
"file" : "out-path/external_signed.hex"
}
]
},
{
"command": "merge",
"inputs": [
{ "description": "Signed Internal Flash Application",
"file": "out-path/internal_signed.hex"
},
{ "description": "Signed External Flash Application",
"file": "out-path/external_signed.hex"
}
],
"outputs" : [
{ "description": "Combine signed Internal & External Flash Apps",
"format" : "ihex",
"file" : "out-path/ble_app_psoc64_signed.hex"
}
]
}
]
}
]
}
Use case 3: Signing hex containing EEPROM segment
There are two segments: the internal flash segment and the EEPROM segment. We need to sign the internal flash application only.
{
"schema-version": 1.0,
"content": [
{
"name" : "EEPROM",
"description": "Use case 2: Signing hex containing EEPROM segment",
"enabled": true,
"commands": [
{
"command": "hex-segment",
"inputs": [
{
"description": "Extract Flash segment",
"file": "app-path/ble_app_psoc64.hex",
"address" : "0x10000000"
}
],
"outputs" : [
{
"description": "Save Flash segment",
"format" : "ihex",
"file" : "out-path/flash.hex"
}
]
},
{
"command": "hex-segment",
"inputs": [
{
"description": "Extract EEPROM segment",
"file": "app-path/ble_app_psoc64.hex",
"address" : "0x14000000"
}
],
"outputs" : [
{
"description": "Save EEPROM segment",
"format" : "ihex",
"file" : "out-path/eeprom.hex"
}
]
},
{
"command": "sign",
"inputs": [
{
"description": "Signs Flash application",
"file": "out-path/flash.hex"
}
],
"outputs" : [
{
"description": "Signed Flash application",
"signer-key" : "/key-path/signing_private_key.pem",
"format" : "ihex",
"file" : "out-path/flash_signed.hex"
}
]
},
{
"command": "merge",
"inputs": [
{
"description": "Signed Flash segment",
"file": "out-path/flash_signed.hex"
},
{
"description": "Unsigned EEPROM segment",
"file": "out-path/eeprom.hex"
}
],
"outputs" : [
{
"description": "Combined signed Flash app and unsigned EEPROM",
"format" : "ihex",
"file" : "out-path/ble_app_psoc64_signed.hex"
}
]
}
]
}
]
}
Use case 4: Signing encrypted image with HSM
In this case, we are creating an unsigned encrypted image, then sign it with HSM. To create an unsigned image use the sign command, but without the signing-key property. The result of the Sign image command are two unsigned images in the MCUboot format - encrypted and decrypted. The encrypted one is the image we are going to attach the signature generated by HSM. The decrypted one is the image we have to provide to HSM for signing. The signature is calculated from the non-encrypted data.
- The Extract payload command extracts from the decrypted image the part to be signed (header, body, protected TLV).
- The Custom script command signs the payload with HSM and saves the signature to the signature.bin file.
- The Add signature command adds the signature returned by HSM to the encrypted MCUboot format image.
{
"schema-version": 1.0,
"content": [
{
"name" : "BootloaderHSM",
"description": "Use case 3: Signing image with HSM",
"enabled": true,
"commands": [
{
"command": "sign",
"inputs": [
{
"description": "Path to the input hex file",
"file": "bootloader_path/bootloader.hex"
}
],
"outputs" : [
{
"description": "Save encrypted bootloader and binary payload to sign on HSM",
"header-size": "0x400",
"fill-value": "0x00",
"slot-size": "0x20000",
"pad": true,
"encryption-key": "key-path/public_key.pem",
"format" : "ihex",
"file" : "out-path/encryptedBoot.hex",
"decrypted" : "out-path/decryptedBoot.bin"
}
]
}, {
"command": "custom-script",
"inputs": [
{
"description": "Signing with HSM command. The command does not have the 'outputs' property. If necessary, the outputs are handled by the command line.",
"command-line": "cxitool.exe Dev=3001@127.0.0.1 LogonPass=USR_0000,2222 Group=SLOT_0000 Spec=2 InFile=decryptedBoot.bin Signature=signature.bin,raw Sign=SHA256,on_hsm,PSS"
}
]
},
{
"command": "add-signature",
"inputs": [
{
"description": "Encrypted unsigned bootloader",
"file": "out-path/encryptedBoot.hex"
},
{
"description": "Signature returned by HSM",
"file": "signature.bin"
}
],
"outputs" : [
{
"description": "Final image signed with HSM",
"format" : "ihex",
"file" : "out-path/boot_encrypted_signed.hex"
}
]
}
]
}
]
}