Command-line operations

SEC also offers a command-line interface, enabling integration in automated environments or customization of image building/burning procedure. Operation requires a verb identifying the top-level operation (building, flashing, provisioning, generating keys or detecting the list of USB devices) and additional operation-specific options.

To display the available commands, arguments, and examples, run the following command from the command prompt:

c:/nxp/MCUX_Provi_v4.1/bin/securep.exe -h

To display the available arguments for a specific command, run the following command from the command prompt:

c:/nxp/MCUX_Provi_v4.1/bin/securep.exe <command> -h

Note: The location of the file 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, see Example how to use the args-file argument.

Table args-file argument

Argument

Description

–args-file ARGS_FILE

Path to the JSON file with CLI arguments allowing to specify all arguments in one file. The path is absolute or relative to the current working directory. The file format is specified by schema/cli_args_file_schema_v?.json.

Build

With the build command, you can perform actions that you can otherwise perform in the Build image view of SEC.

The following arguments are available to the build command:

Table Build-specific arguments

Argument

Description

-h, –help

Show this help message and exit.

–additional-images-cfg

Path to JSON with configuration of additional images for the build. The file format is specified by the schema schema/additional_images_schema_v?.json.

–bee-user-keys-config BEE_USER_KEYS_CONFIG

JSON file with the BEE configuration. See the schema/bee_image_encryption_schema_v2.json in the installation folder. The parameter is applicable for encrypted XIP (BEE user keys) boot type only.

–boot-type VALUE

Secure boot type. Run securep –help to see all supported boot types.

–cfpa-cfg CFPA_CFG

Path to JSON file with USER CFPA configuration. It is recommended to export the file from the PFR Configuration dialog.

–cmpa-cfg/–cfpa-cfg PATH

Path to JSON file with PFR configuration of the given CMPA/CFPA page. It is recommended to export the file from the PFR Configuration dialog.

–cmpa-cfg CMPA_CFG

Path to JSON file with USER CMPA configuration. It is recommended to export the file from the PFR Configuration dialog.

–csf-cert CSF_CERT

Path to the public CSF key file that is used for signing the image. If not specified then it is derived from the img-cert pathname according to the HAB4 PKI Tree naming convention.

–dcd DCD

Path to the Device Configuration Data binary file.

–dekkey DEKKEY

32/48/64 HEX characters: data encryption key used for AHAB encryption. The argument is applicable for processors with the AHAB security system.

–device name of the selected processor

Target processor

–dual-image-boot-cfg DUAL_IMAGE_BOOT_CFG

JSON file with dual image boot configuration; file format is specified by schema/dual_image_boot_schema_v?.json. The argument is applicable for processors that supports dual image boot

–ele-firmware ELE_FIRMWARE

Path to the EdgeLock Enclave (ELE) firmware file. The argument is applicable for encrypted boot types for processors with the AHAB security system.

–firmware-version FIRMWARE_VERSION

Version of the application image firmware. The argument is applicable for K32W1xx, KW45xx, LPC55S3x, RT118x, MCXN94x, MCXN54x, RW61x processors.

–iee-config IEE_CONFIG

JSON file with the IEE configuration. See the schema/iee_image_encryption_schema_v?.json in the installation folder. The parameter is applicable for IEE encrypted boot type only.

–image-version IMAGE_VERSION

The version of the bootable image can be either in 4-bytes format, for example, 0xFFFE0001 (the lower 2 bytes are the real version number, and the upper 2 bytes are the invert value of lower 2 bytes) or just the real version number (2 bytes). The argument is only applicable for processors that support the image version on the build tab.

–img-cert IMG_CERT

Path to the public IMG key file that is used for signing the image. 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.

–iped-cfg IPED_CFG

JSON file with PRINCE configuration; file format is specified by schema/prince_config_schema_v?.json

–keyblob-keyid KEYBLOB_KEYID

32-bits value: Keyblob encryption key identifier. The argument is applicable for processors with the AHAB security system.

–keysource {OTP, KeyStore}

Key source for RT5xx/6xx secured images

–life-cycle VALUE

Requested life-cycle state of the processor, one of closed_deploy_infield_shadows,infield_locked_shadows,open_develop,reduced,closed_deploy_infield,infield_locked,closed_level_4.

–otfad-config OTFAD_CONFIG

JSON file with the OTFAD configuration. See the schema/otfad_image_encryption_schema_v?.json in the installation folder. The parameter is applicable for OTFAD encrypted boot type only.

–otp-cfg OTP_CFG

Path to JSON file with USER OTP configuration. It is recommended to export the file from the OTP Configuration dialog.

–prince-cfg PRINCE_CFG

JSON file with PRINCE configuration. See bin/schema/prince_config_schema_v<version>.json in the SEC installation folder.

–romcfg-cfg ROMCFG_CFG

Path to JSON file with USER ROMCFG configuration. It is recommended to export the file from the IFR Configuration dialog.

–save-settings

Save workspace settings.

–sbkek/–cust_mk_sk/–sb3kdk SBKEK

64 HEX characters: Key used as key encryption key to handle SB2 file; Needed only for Secure Binary images; If not specified, it is taken from workspace

–script-only

Generate script only, do not launch

–secret-key-type {AES-128, AES-192, AES-256}

The HAB encryption algorithm, default is processor-specific.

–source-image SOURCE_IMAGE

Source image for building the boot image.

–start-address START_ADDRESS

Start address of the executable image data within the source image. Applicable and required only for binary source images.

–target-image TARGET_IMAGE

Target image for building the boot image.

–trust-provi {disabled, smart_card, device_hsm}, el2go_indirect

Trust provisioning type. el2go_indirect stands for Edgelock2GO proxt flow.

–trust-zone TRUST_ZONE

Either ‘disabled’ (for the TrustZone disabled image) or ‘default’ (for the TrustZone enabled image with default data from the processor) or path to the custom TrustZone configuration JSON or YAML file (for the TrustZone enabled image with custom configuration)

–userkey USERKEY

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 signature

-v, –verbose

Increase output verbosity

-w WORKSPACE, –workspace WORKSPACE

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.

–xip-enc-otpmk-config XIP_ENC_OTPMK_CONFIG

JSON file with the XIP Encryption with OTPMK configuration. See the schema/xip_enc_otpmk_schema_v?.json in the installation folder. The argument is applicable for XIP encrypted (BEE OTPMK) and XIP encrypted (OTFAD OTPMK) boot types only.

–xmcd-cfg XMCD_CFG

Path to YAML or binary file with the XMCD configuration (simplified or full); for file format, see the SPSDK command nxpimage bootable-image xmcd get-templates. The argument is only applicable for RT116x, RT117x, and RT118x processors.

Table Boot-device arguments (mutually exclusive)

Argument

Description

–boot-device VALUE

Predefined boot memory. Run securep –help to see all supported boot memories.

–boot-device-file BOOT_DEVICE_FILE

File with boot memory configuration

–boot-device-type {flex-spi-nor, flex_spi_nand, onchip_memory, sdhc_sd_card,semc_nand}

Boot memory type. Default-predefined boot memory of this type is set.

Write

With the write command, you can perform actions that you can otherwise perform in the Write image view of SEC.

The following arguments are available to the write command:

Table Write-specific arguments

Argument

Description

-h, –help

Show this help message and exit

–source-image SOURCE_IMAGE

Source image to be uploaded to the target

–write-params-cfg WRITE_PARAMS_CFG

JSON file with parameters needed in write and fuses to be burnt by write script (or shadow registers). See the schema/write_parameters_schema_v?.json in the installation folder.

–life-cycle VALUE

Requested life-cycle state of the processor, one of open_develop, closed_deploy_infield, infield_locked.

–trust-provi {disabled,smart_card,device_hsm}

Trust provisioning type.

-v, –verbose

Increase output verbosity

–device name of the selected processor

Target processor

–boot-type VALUE

Secure boot type. Run securep –help to see all supported boot types.

–script-only

Generate script only, do not launch

-w WORKSPACE, –workspace WORKSPACE

Workspace location. Note: Any settings from the workspace are loaded automatically. All command-line parameters can be used to override loaded settings.

–debug-probe

Select a debug probe. Use `–debug-probe auto` to select any debug probe. Use `–debug-probe invalid` to list all connected debug probes.

For boot-device arguments, see Table Boot-device arguments (mutually exclusive)

Table Connection arguments (mutually exclusive)

Argument

Description

–usb VID PID

Connect to target over USB HID device denoted by vid/pid. USB HID connection is default. vid/pid can be specified in decimal form (for example, ‘123’) or hexadecimal form (for example, ‘0xbeef’).

–uart UART

Connect to target over UART. Specify COM port (see –baud-rate argument). Example: –uart COM3

–i2c address speed_kHz

Connect to target over I2C via USB bridge. Specify I2C device address and clock in kHz. SIO device is autoselected if the –sio-device argument is not specified. Example: –i2c 0x10 400

–spi speed_kHz polarity phase

Connect to target over SPI via USB bridge. Specify SPI clock in kHz, polarity (SPI CPOL option) and phase (SPI CPHA option). SIO device is autoselected if the –sio-device argument is not specified. Example: –sp i 1000 1 1

–baud-rate BAUD_RATE

Connect to target over UART with a specified baud rate. –uart argument has to be specified too. Example: –baud-rate 9600

–sio-device SIO_DEVICE

Connect to target over USB-SIO (I2C or SPI) via a specified SIO device. –i2c or –spi argument has to be specified too. Example: –sio-device HID\VID_1FC9&PID_0090&MI_03\7&96E050B&0&0000

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

With the Generate command, you can perform actions that you can otherwise perform in the Generate Keys view. Compared to GUI, command-line functionality is restricted.

The following arguments are available to the generate command:

Table generate-specific arguments

Argument

Description

-h, –help

Show this help message and exit

–keys-cfg KEYS_CFG JSON

File with the keys configuration

–device name of the selected processor

Target processor

–boot-type VALUE

Secure boot type. Run securep –help to see all supported boot types.

–script-only

Generate script only, do not launch

-w WORKSPACE, –workspace WORKSPACE

Workspace location. Note: Any settings from the workspace are loaded automatically. All command-line parameters can be used to override loaded settings.

For boot-device arguments, see Table Boot-device arguments (mutually exclusive)

Manufacture

Manufacture command allows running the selected script several times in parallel, each time for a different connection. The following arguments are available to the manufacture command:

Table Manufacture-specific arguments

Argument

Description

-h, –help

Show this help message and exit

–script_path SCRIPT_PATH

Path to the script to be executed

–script_params SCRIPT_PARAMS

Parameters of the script. For more information, see Manufacturing Tool.

–connections CONNECTIONS [CONNECTIONS …]

List of all connections devices to be used in manufacturing, in format “-p <port>,<baud>” or “-u <usb-path>” or “-l usb,<usb-path>,spi[,<port>,<pin>,<speed_kHz>,<polarity>,<phase>]” or “-l usb,<usb-path>,i2c[,<address>,<speed_kHz>]”. To find all available USB/USB-SIO connections, automatically use “-u <autodetect-all-USBs>” or “-l usb,<autodetect-all-USBSIOs>,spi[,<port>,<pin>,<speed_kHz>,<polarity>,<phase>]” or “-l usb,<autodetect-all-USBSIOs>,i2c[,<address>,<speed_kHz>]”. The options for autodetection cannot be combined with the other options. Parameters and default values for SIO operation are described in the SPSDK documentation.

Devices info

With the devices-info command, you can get information about supported processors and their supported boot devices.

The following arguments are available for the devices-info command:

Argument

Description

-h, –help

Show this help message and exit.

–device DEVICE

Device name substring that is searched in processor name and processor variants. If not provided, info for all processors is returned.

–format {json,txt}

Format of the output. Default is json for the file output, txt for STDOUT.

–output OUTPUT

Path to a file where to store the output. If not provided, the output is printed to STDOUT.

Environment variables in filepath-based arguments

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

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

For detailed examples, use the following command:

securep.exe print-cli-examples

Example how to use args-file argument

In the following examples, CLI arguments are converted to the JSON file.

Arguments in the command line 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

Usage of 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": []
  }
}

Arguments in command line for write:

securep.exe -w /workspaces/mcuxprovi --device MIMX9596 --boot-device-type
onchip_ram --boot-type unsigned write --source-image bootable_images/flash.bin

Usage of 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 together with arguments in the args-file. Arguments cannot be specified in both places.

Command-line tools

SEC uses 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. The following tools are available as part of SPSDK:

  • blhost : Replacement for the legacy blhost tool

  • el2go-host : Managing the EdgeLock 2GO provisioning operations

  • ifr : Generating the content of the flash region file (ROMCFG)

  • nxpcrypto : Operations with keys and certificates

  • nxpdebugmbox : Debug mailbox and debug credential file generator tool

  • nxpdevhsm : The application is designed to create an SB3 provisioning file for initial provisioning of the device by the OEM.

  • nxpdevscan : Utility that detects NXP devices connected to the host PC over USB, UART, I2C, and SPI connections

  • nxpele : Utility for communication with the EdgeLock Enclave on target

  • nxpimage : Builds bootable image and SB files

  • nxpuuu : The application for image deployment for i.MX MPUs. It is based on libUUU (universal update utility).

  • pfr : Generating protected flash region files (cmpa/cfpa)

  • sdphost : Replacement for the legacy sdphost tool

  • shadowregs : Shadow registers control tool.

  • tpconfig : Configuration of Smart Card for trust provisioning

  • tphost : Trust provisioning operation

imgtool : MCUboot’s image signing and key management

uuu : NXP i.MX Chip image-deploy tools for i.MX MPUs