User Guide - nxpdevhsm#

This user’s guide describes how to interface with the MCU bootloader to provisioned chip using nxpdevhsm application.

The nxpdevhsm application is a command-line utility used on the host computer to use device HSM process to get provisioning SB3.

Communication#

The nxpdevhsm application is using blhost application and all supported communication interfaces that blhost offers(UART, USB, LPCUSBSIO[IC, SPI])

blhost - USB#

blhost could be connected to MCU Bootloader over USB HID.

USB device identification in SPSDK

blhost - UART#

blhost could be connected to MCU bootloader over UART.

UART device identification in SPSDK

blhost - LPCUSBSIO#

LPCUSBSIO - LPC USB Serial I/O(LPCUSBSIO), a firmware built in LPC Link2. The LPCUSBSIO acts as a bus translator, and establishes connection with blhost over USB-HID, and the MCU bootloader device over I2C and SPI.

Note

For more information about supported communication interface check the blhost application documentation.

Command line interface#

nxpdevhsm#

Nxpdevhsm application is designed to create SB3 provisioning file for initial provisioning of device by OEM.

nxpdevhsm [OPTIONS] COMMAND [ARGS]...

Options

-v, --verbose#: Print more detailed information

-vv, --debug#: Display more debugging information.

--version#: Show the version and exit.

--help#: Show this message and exit.

generate#

Generate provisioning SB file.

nxpdevhsm generate [OPTIONS]

Options

-p, --port <COM[,speed>#: Serial port configuration. Default baud rate is 57600. Use ‘nxpdevscan’ utility to list devices on serial port.

-u, --usb <VID:PID|USB_PATH|DEV_NAME>#: USB device identifier. | Following formats are supported: <vid>, <vid:pid> or <vid,pid>, device/instance path, device name. | <vid>: hex or dec string; e.g. 0x0AB12, 43794. | <vid/pid>: hex or dec string; e.g. 0x0AB12:0x123, 1:3451. | Use ‘nxpdevscan’ utility to list connected device names.

This option can be omitted if ‘–family’ option is used.

-sd, --sdio <SDIO_PATH|DEV_NAME>#: SDIO device identifier.

Following formats are supported: device/instance path, device name.

device/instance path: device string; e.g. /dev/mcu-sdio.

Use ‘nxpdevscan’ utility to list connected device names.

-l, --lpcusbsio <usb,VID:PID|USB_PATH|SER_NUM,]spi|i2c>#

USB-SIO bridge interface.

Optional USB device filtering formats: [usb,vid:pid|usb_path|serial_number]

Following serial interfaces are supported:

spi[index][,port,pin,speed_kHz,polarity,phase]
- index … optional index of SPI peripheral. Example: “spi1” (default=0)
- port … bridge GPIO port used as SPI SSEL(default=0)
- pin  … bridge GPIO pin used as SPI SSEL
default SSEL is set to 0.15 which works
for the LPCLink2 bridge. The MCULink OB
bridge ignores the SSEL value anyway.(default=15)
- speed_kHz … SPI clock in kHz (default 1000)
- polarity … SPI CPOL option (default=1)
- phase … SPI CPHA option (default=1)
- nirq_port … nIRQ port number (default None)
- nirq_pin … nIRQ pin number (default None)

i2c[index][,address,speed_kHz]
- index … optional index of I2C peripheral. Example: “i2c1” (default=0)
- address … I2C device address (default 0x10)
- speed_kHz … I2C clock in kHz (default 100)
- nirq_port … nIRQ port number (default None)
- nirq_pin … nIRQ pin number (default None)

Following types of interface configuration formats are supported:
- string with coma separated arguments i.e. spi1,0,15,1000,1
- string with coma separated keyword arguments (the order may not be maintained) i.e.spi1,port=0,speed_kHz=1000,nirq_port=1,nirq_pin=7
- string with combination of coma separated arguments and keyword arguments i.e.spi1,0,15,nirq_port=1,nirq_pin=7

-cb, --can <interface[,channel,bitrate,rxid,txid>#: CAN Bus settings

interface[,channel,bitrate,rxid,txid]

- interface … CAN interface name (refer to python-can library)

- channel … CAN channel number

- bitrate … CAN bitrate (default=1000000)

- rxid … default arbitration ID for RX (default=0x123)

- txid … default arbitration ID for TX (default=0x321)

-b, --buspal <spi[,speed,polarity,phase,lsb|msb] | i2c[,address,speed>#: Buspal settings

-x, --plugin <identifier=PLUGIN_IDENTIFIER[,param1=value1,param2=value2>#

Plugin interface settings.

Following format of plugin setting is supported:

identifier=<PLUGIN_IDENTIFIER>[,<key1>=<value1>,<key2>=<value2>,…]
- <PLUGIN_IDENTIFIER>: Corresponds to the ‘identifier’ attribute of the plugin class
- <key1>=<value1>: Represent a single interface parameter

Optional interface settings:
- Any number of optional <key>=<value> scan settings separated by comma can be defined
- The <key>=<value> pairs are used as keyword parameters for ‘scan’ method of a plugin class

-t, --timeout <ms>#: Sets timeout when waiting on data over a serial line. The default is 5000 milliseconds.

-f, --family <family>#

Select the chip family.

Options:: lpc55s36 | mc56f81866 | mc56f81868 | mcxn235 | mcxn236 | mcxn546 | mcxn547 | mcxn946 | mcxn947 | mimxrt798s | mwct20d2 | mwct20d2a | rw610 | rw612

-k, --key <key>#: Customer Master Key Symmetric Key secret file (32-bytes long binary file). CUST_MK_SK (provisioned by OEM, known by OEM). This is a 256-bit pre-shared AES key provisioned by OEM. CUST_MK_SK is used to derive FW image encryption keys.

-i, --oem-share-input <oem_share_input>#: OEM share input file to use as a seed to randomize the provisioning process (16-bytes long binary file).

-e, --enc-oem-master-share <enc_oem_master_share>#: Path to Encrypted OEM MASTER SHARE binary.

-w, --workspace <workspace>#: Workspace folder to store temporary files, that could be used for future review.

-ir, --initial-reset, -IR, --no-init-reset#: Reset device BEFORE DevHSM operation. The DevHSM operation can run only once between resets. Do not enable this option on Linux/Mac when using USB. By default this reset is DISABLED.

-fr, --final-reset, -FR, --no-final-reset#: Reset device AFTER DevHSM operation. This reset is required if you need to use the device after DevHSM operation for other security related operations (e.g. receive-sb-file). By default this reset is ENABLED.

-ba, --buffer-address <buffer_address>#: Override the communication buffer base address. The default address is family-specific.

-o, --output <output>#: Path to a file, where to store the output.

-c, --config <config>#: Path to the YAML/JSON configuration file.

get-cust-fw-auth#

Generate CUST FW AUTH key.

nxpdevhsm get-cust-fw-auth [OPTIONS]

Options

-p, --port <COM[,speed>#: Serial port configuration. Default baud rate is 57600. Use ‘nxpdevscan’ utility to list devices on serial port.

-u, --usb <VID:PID|USB_PATH|DEV_NAME>#: USB device identifier. | Following formats are supported: <vid>, <vid:pid> or <vid,pid>, device/instance path, device name. | <vid>: hex or dec string; e.g. 0x0AB12, 43794. | <vid/pid>: hex or dec string; e.g. 0x0AB12:0x123, 1:3451. | Use ‘nxpdevscan’ utility to list connected device names.

This option can be omitted if ‘–family’ option is used.

-sd, --sdio <SDIO_PATH|DEV_NAME>#: SDIO device identifier.

Following formats are supported: device/instance path, device name.

device/instance path: device string; e.g. /dev/mcu-sdio.

Use ‘nxpdevscan’ utility to list connected device names.

-l, --lpcusbsio <usb,VID:PID|USB_PATH|SER_NUM,]spi|i2c>#

USB-SIO bridge interface.

Optional USB device filtering formats: [usb,vid:pid|usb_path|serial_number]

Following serial interfaces are supported:

spi[index][,port,pin,speed_kHz,polarity,phase]
- index … optional index of SPI peripheral. Example: “spi1” (default=0)
- port … bridge GPIO port used as SPI SSEL(default=0)
- pin  … bridge GPIO pin used as SPI SSEL
default SSEL is set to 0.15 which works
for the LPCLink2 bridge. The MCULink OB
bridge ignores the SSEL value anyway.(default=15)
- speed_kHz … SPI clock in kHz (default 1000)
- polarity … SPI CPOL option (default=1)
- phase … SPI CPHA option (default=1)
- nirq_port … nIRQ port number (default None)
- nirq_pin … nIRQ pin number (default None)

i2c[index][,address,speed_kHz]
- index … optional index of I2C peripheral. Example: “i2c1” (default=0)
- address … I2C device address (default 0x10)
- speed_kHz … I2C clock in kHz (default 100)
- nirq_port … nIRQ port number (default None)
- nirq_pin … nIRQ pin number (default None)

Following types of interface configuration formats are supported:
- string with coma separated arguments i.e. spi1,0,15,1000,1
- string with coma separated keyword arguments (the order may not be maintained) i.e.spi1,port=0,speed_kHz=1000,nirq_port=1,nirq_pin=7
- string with combination of coma separated arguments and keyword arguments i.e.spi1,0,15,nirq_port=1,nirq_pin=7

-cb, --can <interface[,channel,bitrate,rxid,txid>#: CAN Bus settings

interface[,channel,bitrate,rxid,txid]

- interface … CAN interface name (refer to python-can library)

- channel … CAN channel number

- bitrate … CAN bitrate (default=1000000)

- rxid … default arbitration ID for RX (default=0x123)

- txid … default arbitration ID for TX (default=0x321)

-b, --buspal <spi[,speed,polarity,phase,lsb|msb] | i2c[,address,speed>#: Buspal settings

-x, --plugin <identifier=PLUGIN_IDENTIFIER[,param1=value1,param2=value2>#

Plugin interface settings.

Following format of plugin setting is supported:

identifier=<PLUGIN_IDENTIFIER>[,<key1>=<value1>,<key2>=<value2>,…]
- <PLUGIN_IDENTIFIER>: Corresponds to the ‘identifier’ attribute of the plugin class
- <key1>=<value1>: Represent a single interface parameter

Optional interface settings:
- Any number of optional <key>=<value> scan settings separated by comma can be defined
- The <key>=<value> pairs are used as keyword parameters for ‘scan’ method of a plugin class

-t, --timeout <ms>#: Sets timeout when waiting on data over a serial line. The default is 5000 milliseconds.

-f, --family <family>#

Select the chip family.

Options:: lpc55s36 | mcxn235 | mcxn236 | mcxn546 | mcxn547 | mcxn946 | mcxn947 | mimxrt798s | rw610 | rw612

-i, --oem-share-input <oem_share_input>#: Path to OEM_SEED binary.

-e, --enc-oem-master-share <enc_oem_master_share>#: Path to OEM ENC MASTER SHARE.

-o, --output <output>#: Required Path to a directory, where to store generated/parsed files.

get-families#

Shows the full family info for commands in this group.

nxpdevhsm get-families [OPTIONS]

Options

-c, --cmd-name <cmd_name>#

Choose the command name to get full information about NXP families support.

Options:: generate | get-template | gen-master-share | set-master-share | wrap-cust-mk-sk | get-cust-fw-auth

get-template#

Create template of configuration in YAML format.

The template file name is specified as argument of this command.

nxpdevhsm get-template [OPTIONS]

Options

-f, --family <family>#

Select the chip family.

Options:: lpc55s36 | mc56f81866 | mc56f81868 | mcxn235 | mcxn236 | mcxn546 | mcxn547 | mcxn946 | mcxn947 | mimxrt798s | mwct20d2 | mwct20d2a | rw610 | rw612

-o, --output <output>#: Required Path to a file, where to store the output.

--force#: Force overwriting of existing files.

wrap-cust-mk-sk#

Wrap CUST_MK_SK key.

nxpdevhsm wrap-cust-mk-sk [OPTIONS]

Options

-p, --port <COM[,speed>#: Serial port configuration. Default baud rate is 57600. Use ‘nxpdevscan’ utility to list devices on serial port.

-u, --usb <VID:PID|USB_PATH|DEV_NAME>#: USB device identifier. | Following formats are supported: <vid>, <vid:pid> or <vid,pid>, device/instance path, device name. | <vid>: hex or dec string; e.g. 0x0AB12, 43794. | <vid/pid>: hex or dec string; e.g. 0x0AB12:0x123, 1:3451. | Use ‘nxpdevscan’ utility to list connected device names.

This option can be omitted if ‘–family’ option is used.

-sd, --sdio <SDIO_PATH|DEV_NAME>#: SDIO device identifier.

Following formats are supported: device/instance path, device name.

device/instance path: device string; e.g. /dev/mcu-sdio.

Use ‘nxpdevscan’ utility to list connected device names.

-l, --lpcusbsio <usb,VID:PID|USB_PATH|SER_NUM,]spi|i2c>#

USB-SIO bridge interface.

Optional USB device filtering formats: [usb,vid:pid|usb_path|serial_number]

Following serial interfaces are supported:

spi[index][,port,pin,speed_kHz,polarity,phase]
- index … optional index of SPI peripheral. Example: “spi1” (default=0)
- port … bridge GPIO port used as SPI SSEL(default=0)
- pin  … bridge GPIO pin used as SPI SSEL
default SSEL is set to 0.15 which works
for the LPCLink2 bridge. The MCULink OB
bridge ignores the SSEL value anyway.(default=15)
- speed_kHz … SPI clock in kHz (default 1000)
- polarity … SPI CPOL option (default=1)
- phase … SPI CPHA option (default=1)
- nirq_port … nIRQ port number (default None)
- nirq_pin … nIRQ pin number (default None)

i2c[index][,address,speed_kHz]
- index … optional index of I2C peripheral. Example: “i2c1” (default=0)
- address … I2C device address (default 0x10)
- speed_kHz … I2C clock in kHz (default 100)
- nirq_port … nIRQ port number (default None)
- nirq_pin … nIRQ pin number (default None)

Following types of interface configuration formats are supported:
- string with coma separated arguments i.e. spi1,0,15,1000,1
- string with coma separated keyword arguments (the order may not be maintained) i.e.spi1,port=0,speed_kHz=1000,nirq_port=1,nirq_pin=7
- string with combination of coma separated arguments and keyword arguments i.e.spi1,0,15,nirq_port=1,nirq_pin=7

-cb, --can <interface[,channel,bitrate,rxid,txid>#: CAN Bus settings

interface[,channel,bitrate,rxid,txid]

- interface … CAN interface name (refer to python-can library)

- channel … CAN channel number

- bitrate … CAN bitrate (default=1000000)

- rxid … default arbitration ID for RX (default=0x123)

- txid … default arbitration ID for TX (default=0x321)

-b, --buspal <spi[,speed,polarity,phase,lsb|msb] | i2c[,address,speed>#: Buspal settings

-x, --plugin <identifier=PLUGIN_IDENTIFIER[,param1=value1,param2=value2>#

Plugin interface settings.

Following format of plugin setting is supported:

identifier=<PLUGIN_IDENTIFIER>[,<key1>=<value1>,<key2>=<value2>,…]
- <PLUGIN_IDENTIFIER>: Corresponds to the ‘identifier’ attribute of the plugin class
- <key1>=<value1>: Represent a single interface parameter

Optional interface settings:
- Any number of optional <key>=<value> scan settings separated by comma can be defined
- The <key>=<value> pairs are used as keyword parameters for ‘scan’ method of a plugin class

-t, --timeout <ms>#: Sets timeout when waiting on data over a serial line. The default is 5000 milliseconds.

-f, --family <family>#

Select the chip family.

Options:: lpc55s36 | mcxn235 | mcxn236 | mcxn546 | mcxn547 | mcxn946 | mcxn947 | mimxrt798s | rw610 | rw612

-i, --cust-mk-sk <cust_mk_sk>#: Required

-o, --output <output>#: Required Path to a directory, where to store generated/parsed files.

User Guide - nxpdevhsm

Contents

User Guide - nxpdevhsm#

Communication#

blhost - USB#

blhost - UART#

blhost - LPCUSBSIO#

Command line interface#

nxpdevhsm#

gen-master-share#

generate#

get-cust-fw-auth#

get-families#

get-template#

set-master-share#

wrap-cust-mk-sk#