Command-line operations#
The Secure Provisioning Tool also offers a command-line interface, enabling integration in automated environments or customization of the image building and burning procedure. Operation requires a verb (command) identifying the top-level operation (building, flashing, provisioning, generating keys or detecting the list of USB devices) and additional operation-specific options.
Note
This chapter shows commands that are run in a terminal.
Each command line begins with a prompt character: > for Windows or $ for Linux and macOS.
Do not type this leading character, it only marks the start of a command and is not part of the command itself.
To display the available commands, arguments, and examples, run the following command from the command prompt:
> C:\NXP\SEC_Provi_26.09\bin\securep.exe --help
Or in Linux and macOS:
$ /opt/nxp/SEC_Provi_26.09/bin/securep --help
To display the available arguments for a specific command, run the following command from the command prompt:
> C:\NXP\SEC_Provi_26.09\bin\securep.exe <command> --help
Or in Linux and macOS:
$ /opt/nxp/SEC_Provi_26.09/bin/securep <command> --help
To avoid repetition, the remainder of this section uses Windows examples only, since usage is nearly identical on all platforms.
Note: The location of the SEC Tool application is subject to the installation folder.
All the supported commands and arguments used in the command line as described in chapters below can also be specified in a separate configuration JSON file. This JSON file is then passed as a command-line argument. For more information see Examples of args-file JSON usage.
CLI arguments#
This section describes CLI arguments that are used globally or shared across multiple commands.
Argument specified in JSON file#
Argument |
Description |
|---|---|
|
Path to the JSON file with CLI arguments, allowing you to specify all arguments in one file. The path is absolute or relative to the current working directory. The file format is specified by |
Arguments for the processor selection#
Argument |
Description |
|---|---|
|
Target board (implicit specification of the processor). During creation of new workspace, the board argument is used to configure default values for the board. |
|
Target processor. |
To display the list of supported processors and boards, use the securep devices-info processors command.
Arguments for the boot device selection#
Argument |
Description |
|---|---|
|
Predefined boot memory. Run |
|
File with boot memory configuration. |
|
Boot memory type, one of the following types: |
Arguments for connection selection#
Argument |
Description |
|---|---|
|
Connect to the target over USB HID device denoted by VID/PID. USB HID connection is default. VID/PID can be specified in decimal form (for example, |
|
Connect to the target over UART. Specify the COM port (see |
|
Connect to the target over UART with a specified baud rate. |
|
Connect to the target over I2C via USB bridge. Specify the I2C device address and clock in kHz. The SIO device is autoselected if the |
|
Connect to the target over SPI through a USB bridge. Specify SPI clock in kHz, polarity (SPI CPOL option) and phase (SPI CPHA option). The SIO device is autoselected if the |
|
Connect to the target over USB-SIO (I2C or SPI) via a specified SIO device. |
Environment variables in filepath-based arguments#
The SEC Tool accepts environment variables in all arguments specifying paths, for example:
> securep.exe -w /workspaces/mcuxprovi --device MIMX9596 --boot-device-type
onchip_ram --boot-type unsigned build --additional-images
additional_images_cfg.json --ele-firmware
"${MCUX_SDK_16}\firmware\edgelock\mx95a0-ahab-container.img" --save-settings
CLI commands#
The tool supports the following CLI commands:
Build command#
With the build command, you can perform actions that you can otherwise perform in the Build image view of SEC, that is, building a bootable image and preparing data for provisioning.
Argument |
Description |
|---|---|
|
Show help message and exit. |
|
Path to JSON with configuration of additional images for the build. The file format is specified by the schema |
|
JSON file with the BEE configuration. See the |
|
Secure boot type. Run |
|
Path to JSON file with USER CFPA configuration. It is recommended to export the file from the PFR Configuration dialog. |
|
Path to JSON file with USER CMPA configuration. It is recommended to export the file from the PFR Configuration dialog. |
|
Path to the public CSF key file used for signing the image. If not specified, it is derived from the img-cert pathname according to the HAB4 PKI Tree naming convention. |
|
Path to the Device Configuration Data binary file. |
|
32/48/64 HEX characters: data encryption key used for AHAB encryption. The argument is applicable for processors with the AHAB security system. |
|
JSON file with dual image boot configuration; file format is specified by |
|
Path to the EdgeLock Enclave (ELE) firmware file. The argument is applicable for encrypted boot types for processors with the AHAB security system. |
|
Version of the application image firmware. |
|
JSON file with the IEE configuration. See the |
|
Error code to be ignored (displayed as a warning). Use with caution, may cause unexpected or wrong behavior. Works only in CLI mode. The list of supported error codes is displayed using command |
|
The version of the bootable image can be either in 4-bytes format, for example, |
|
Path to the public IMG key file that is used for signing the image. For processors with a dual key schema, use the path to the primary key for signing pair identification. It is recommended to use the command with a workspace with already initialized key management. If the keys are not specified in the workspace settings file, they are imported. |
|
JSON file with PRINCE configuration; file format is specified by |
|
32-bit value: Keyblob encryption key identifier. The argument is applicable for processors with the AHAB security system. |
|
Key source for RT5xx/6xx secured images |
|
Requested life-cycle state of the processor. The list of supported IDs is displayed using command |
|
32 HEX characters: Seed used to initialize the MISR (Multiple Input Signature Register) used during image signing. |
|
Path to the SB file with NBU firmware used for NBU firmware provisioning. Supported for devices with NBU firmware stored in on-chip flash. |
|
JSON file with the OTFAD configuration. See the |
|
Path to JSON file with USER OTP configuration. It is recommended to export the file from the OTP Configuration dialog. |
|
JSON file with PRINCE configuration. See |
|
Path to JSON file with USER ROMCFG configuration. It is recommended to export the file from the IFR Configuration dialog. |
|
Save workspace settings. |
|
64 HEX characters: Key used as key encryption key to handle SB2 file; Needed only for Secure Binary images; If not specified, it is read from workspace. |
|
Generate build script only, do not launch it. |
|
The HAB encryption algorithm, default is processor-specific. Possible values: |
|
Source image path for building the boot image. |
|
Start address of the executable image data within the source image. Applicable and required only for binary source images. |
|
Target image path for building the boot image. |
|
Trust provisioning type. Possible values: |
|
Either |
|
Key applicable for RT5xx/6xx secured images: for OTP key-source it represents the master key; for key-store it represents the key used for the signature |
|
Increase output verbosity |
|
Workspace location, path to the workspace directory. Note: Any settings from the workspace are loaded automatically. All command-line parameters can be used to override loaded settings. |
|
JSON file with the XIP Encryption with OTPMK configuration. See the |
|
Path to YAML or binary file with the XMCD configuration (simplified or full), or use the special value |
For processor selection arguments, see Arguments for processor selection.
For boot-device arguments, see Arguments for boot device selection.
Write command#
With the write command, you can perform actions that you can otherwise perform in the Write image view of SEC, that is, provisioning the chip and writing a bootable image.
Argument |
Description |
|---|---|
|
Show help message and exit. |
|
Source image path to be uploaded to the target. |
|
JSON file with parameters needed in write and fuses to be burnt by write script (or shadow registers). See the |
|
Requested life-cycle state of the processor. The list of supported IDs is displayed using command |
|
Trust provisioning type. Possible values: |
|
Increase output verbosity. |
|
Secure boot type. Run |
|
Generate script only, do not launch. |
|
Workspace location. Note: Any settings from the workspace are loaded automatically. All command-line parameters can be used to override loaded settings. |
|
Select a debug probe. Use |
For processor selection arguments, see Arguments for processor selection.
For boot-device arguments, see Arguments for boot device selection.
For connection arguments, see Arguments for connection selection
Note: For connection to the board, a USB or Serial port has to be specified. If nothing is specified, USB autodetection is applied.
Generate keys command#
With the generate command, you can perform actions that you can otherwise perform in the Generate Keys view. Compared to the GUI, command-line functionality is restricted.
Argument |
Description |
|---|---|
|
Show help message and exit. |
|
File with the keys configuration. Note: For the keys configuration see JSON schema located in |
|
Secure boot type. Run |
|
Generate script only, do not launch. |
|
Workspace location. Note: Any settings from the workspace are loaded automatically. All command-line parameters can be used to override loaded settings. |
For processor selection arguments, see Arguments for processor selection.
For boot-device arguments, see Arguments for boot device selection.
Manufacture command#
The manufacture command allows running the selected script several times in parallel, each time for a different connection.
Argument |
Description |
|---|---|
|
Show help message and exit. |
|
Initialize flashloader before running the script. |
|
Path to the script to be executed. This option is recommended when USB is used, because it also handles changes to the USB path after the flashloader is initialized. |
|
Parameters of the script. For more information, see Manufacturing Tool. |
|
List of all connections devices to be used in manufacturing, in format |
Devices info command#
With the devices-info command, you can get information about supported processors and their supported boot devices.
Mode |
Description |
|---|---|
|
Information about supported processors and their supported boot devices. This mode is default. |
|
Information about supported boot devices memory. |
Argument |
Description |
|---|---|
|
Show help message and exit. |
|
Format of the output. The default value is |
|
Path to a file where to store the output. If not provided, the output is printed to STDOUT. |
For processor selection arguments, see Arguments for processor selection.
Test connection command#
The test-connection command performs a processor-specific connection test. The device must be specified either in the workspace or via the command-line option. If no connection is specified in the workspace or as an option, the default connection is used. The connection test is successful if a matching device is connected and is in ISP mode.
Argument |
Description |
|---|---|
|
Show help message and exit. |
|
Increase output verbosity. |
|
Workspace location. |
For processor selection arguments, see Arguments for processor selection.
Detect USB devices command#
The detect command identifies any processor connected via USB. For detection to succeed, the processor must be in ISP mode.
Start flashloader command#
The start-flashloader command starts the flashloader on the i.MX RT processors.
Argument |
Description |
|---|---|
|
Show help message and exit. |
|
Increase output verbosity |
|
Workspace location. |
|
Generate script only, do not launch. |
For processor selection arguments, see Arguments for processor selection.
For connection arguments, see Arguments for connection selection.
Apply settings command#
Command apply-settings supports two main use cases
Modifying an existing workspace
Creating a new workspace
For modifying an existing workspace, specify the path to the workspace and the options to change. General options can be used for this purpose.
For creating a new workspace, at minimum, the boot-device and device options must be specified.
Argument |
Description |
|---|---|
|
Show help message and exit. |
|
Increase output verbosity. |
|
Workspace location. |
|
Requested life-cycle state of the processor. The list of supported IDs is displayed using command |
|
Trust provisioning type. Possible values: |
|
Secure boot type. Run |
For processor selection arguments, see Arguments for processor selection.
For boot-device arguments, see Arguments for boot device selection.
For connection arguments see, Arguments for connection selection.
Create workspace in GUI command#
Command create-workspace-gui will open a dialog for creating a new workspace in GUI with predefined values from the arguments.
Argument |
Description |
|---|---|
|
Show help message and exit. |
|
Workspace location. |
|
(Optional) Path to the source image for building the boot image. |
For processor selection arguments, see Arguments for processor selection.
Debug authentication command#
The debug-auth command allows to specify the configuration for the debug authentication (in GUI) and open the debug port if the configuration is specified.
Usage of the command: securep debug-auth <SUB_COMMAND> <DEBUG_PROBE_ID> --beacon <BEACON>, where
<SUB_COMMAND>is eitherconfigure-in-guioropenconfigure-in-gui: to open the configuration dialog and specify the parameters for debug authentication; the parameters are stored in the workspace. The command is the same as main menu > Tools > Debug Authentication command in the tool.
open: to open the debug port. If this command is used for the first time and configuration is not yet specified, it opens the debug configuration GUI automatically. Otherwise, it opens a debug port (without any GUI).
<DEBUG_PROBE_ID>is an identifier (serial number) of the debug probe used for the authentication process.<BEACON>is an optional integer parameter for the debug mailbox passed to the processor during the debug authentication; its value is application-specific.
Command-line examples#
Example: How to build and write an image for configuration stored in the workspace folder#
In this example, it is assumed that the GUI was already used to prepare complete configuration within a workspace (keys generated, build image configured, write image configured).
> securep.exe -w /workspaces/mcuxprovi build
> securep.exe -w /workspaces/mcuxprovi write
Print CLI examples command#
To print many additional CLI examples, use the following command:
> securep.exe print-cli-examples
Examples of args-file JSON usage#
The following examples demonstrate the usage of an args-file JSON file in place of direct command-line arguments. In each case, the original command-line invocation is shown first, followed by the equivalent args-file command and the contents of the JSON file.
Build example#
Example CLI arguments for build:
> securep.exe -w /workspaces/mcuxprovi --device MIMX9596 --boot-device-type
onchip_ram --boot-type unsigned build --additional-images
additional_images_cfg.json --ele-firmware mx95a0-ahab-container.img
--save-settings
Equivalent args-file argument for above build arguments:
> securep.exe --args-file args_file_build.json
args_file_build.json content (only the first additional image is listed):
{
"cli_args": {
"-w": "/workspaces/mcuxprovi",
"--device": "MIMX9596",
"--boot-device-type": "onchip_ram",
"--boot-type": "unsigned",
"build": [],
"--additional-images": {
"images": [
{
"entry_type": "oei_ddr",
"container_set": "#1",
"extra_settings": {
"lpddr_imem_path": "${ENV_VAR_DDR}/lpddr5_imem_v202311.bin",
"lpddr_imem_qb_path": "${ENV_VAR_DDR}/lpddr5_imem_qb_v202311.bin",
"lpddr_dmem_path": "${ENV_VAR_DDR}/lpddr5_dmem_v202311.bin",
"lpddr_dmem_qb_path": "${ENV_VAR_DDR}/lpddr5_dmem_qb_v202311.bin",
"oei_ddr_path": "source_images/oei-m33-ddr.bin"
}
}
]
},
"--ele-firmware": "source_images/mx95a0-ahab-container.img",
"--save-settings": []
}
}
Write example#
Example CLI arguments for write:
> securep.exe -w /workspaces/mcuxprovi --device MIMX9596 --boot-device-type
onchip_ram --boot-type unsigned write --source-image bootable_images/flash.bin
Equivalent args-file argument for above write arguments:
> securep.exe -w /workspaces/mcuxprovi --args-file args_file_write.json
args_file_write.json content:
{
"cli_args": {
"--device": "MIMX9596",
"--boot-device-type": "onchip_ram",
"--boot-type": "unsigned",
"write": [],
"--source-image": "bootable_images/flash.bin"
}
}
Arguments passed directly in the command line are combined with arguments in the args-file. However, the same argument cannot be specified in both places at once.
Command-line tools#
The SEC tool depends on the following command-line tools to generate keys and build/write the image:
openssl: Key generation.
spsdk: Secure Provisioning SDK. For more information, see main menu > Help > SPSDK Online Documentation in GUI. The following CLI tools are available as part of SPSDK:
blhost: Replacement for the legacy blhost tool.
dk6prog: Tool for reading and programming flash memory of DK6 target devices.
el2go-host: Managing the EdgeLock 2GO provisioning operations.
lpcprog: Utility for communication with the bootloader on LPC8xx target.
nxpcrypto: Operations with keys and certificates.
nxpdebugmbox: Debug mailbox and debug credential file generator tool.
nxpdevhsm: Creates an SB3 provisioning file for initial device provisioning by the OEM.
nxpdevscan: Utility that detects NXP devices connected to the host PC over USB, UART, I2C, and SPI connections
nxpdice: Application designed to cover DICE-related operations.
nxpele: Utility for communication with the EdgeLock Enclave on target.
nxpfuses: NXP Fuse Tool.
nxpimage: Builds bootable image and SB files.
nxpmemcfg: Collection of utilities for memory configuration operations.
nxpshe: NXP tool for working with SHE (Secure Hardware Extension).
nxpuuu: The application for image deployment for i.MX MPUs. It is based on libUUU (universal update utility).
nxpwpc: Utility covering WPC operations.
pfr: Generates protected flash region files (cmpa/cfpa) and IFR.
sdphost: Replacement for the legacy sdphost utility.
sdpshost: Utility for communication with ROM on i.MX targets using SDPS protocol (i.MX8/9).
shadowregs: Shadow registers control tool.
spsdk: Main entry point for all SPSDK applications. Additionally provides access to
utils.
imgtool: MCUboot’s image signing and key management.