User Guide - nxpshe#

This user’s guide describes how to use nxpshe application.

Command line interface#

nxpshe#

NXP tool for working with SHE (Secure Hardware Extension).

Usage

nxpshe [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.

calc-boot-mac#

Calculate Boot MAC using provided key and data.

Usage

nxpshe calc-boot-mac [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.

-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.

-k, --key <KEY|FILE>#: Required AES key used for MAC calculation (BOOT_MAC_KEY). The key is a hex-string either directly on command line or in a text file.

-d, --data <data>#: Required Path to application image.

-o, --output <output>#: Output file for calculated boot MAC

derive-key#

Derive a SHE key from master key.

Usage

nxpshe derive-key [OPTIONS]

Options

-k, --master-key <KEY|FILE>#: Required Master key for key derivation (hex string or file path)

-t, --type <key_type>#

Required Type of derived key

Options:: ENC | MAC | DBG

-o, --output <output>#: Output file for derived key

get-families#

Shows the full family info for commands in this group.

Usage

nxpshe get-families [OPTIONS]

Options

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

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

Options:: get-template | setup

get-template#

Generate a template configuration for SHE protocol operations.

Usage

nxpshe get-template [OPTIONS]

Options

-f, --family <family>#

[required] Select the chip family.

Options:: mcxe245 | mcxe246 | mcxe247

-r, --revision <revision>#: Chip revision; if not specified, most recent one will be used

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

--force#: Force overwriting of existing files.

reset#

Reset SHE key storage configuration.

Usage

nxpshe reset [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.

-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.

-k, --master-key <KEY|FILE>#: Required Master key for SHE key storage reset (hex string or file path)

set-boot-mode#

Set boot mode from the data and boot mode configuration.

Usage

nxpshe set-boot-mode [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.

-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.

-bm, --boot-mode <boot_mode>#

Required Secure hardware extension boot mode

Options:: strict | serial | parallel

-d, --data <data>#: Required Path to application image.

setup#

Setup SHE key storage configuration.

Usage

nxpshe setup [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.

-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.

-k, --max-key-count <max_key_count>#

Required Maximum number of keys to setup

Options:: 0 | 5 | 10 | 20

-f, --family <family>#

[required] Select the chip family.

Options:: mcxe245 | mcxe246 | mcxe247

update#

Perform SHE update operation using provided configuration.

Usage

nxpshe update [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.

-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.

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

-oc, --override-config <key_path=value>#: Allows override the individual configuration settings. The use is simple: ‘key_path=value’, like ‘family=mimxrt595s’ or in structural configuration with separating character ‘/’ like ‘containers/0/binary_container=my_container.bin’. It could be used multiple times.

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

--force#: Force overwriting of existing files.

verify#

Verify SHE update messages.

Usage

nxpshe verify [OPTIONS]

Options

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

-oc, --override-config <key_path=value>#: Allows override the individual configuration settings. The use is simple: ‘key_path=value’, like ‘family=mimxrt595s’ or in structural configuration with separating character ‘/’ like ‘containers/0/binary_container=my_container.bin’. It could be used multiple times.

-m4, --message4 <message4>#: Required Path to M4 message file

-m5, --message5 <message5>#: Required Path to M5 message file

User Guide - nxpshe

Contents

User Guide - nxpshe#

Command line interface#

nxpshe#

calc-boot-mac#

derive-key#

get-families#

get-template#

reset#

set-boot-mode#

setup#

update#

verify#