User Guide - nxpdice#

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

nxpdice serves only as a demo application. It shows how DICE works and can be useful when creating a real-life DICE infrastructure. For purposes of nxpdice application, the target is running a special firmware which allows communication with PC via MBoot protocol. The app also supports running a model of a device. Please refer to the LPC55s3x DICE Notebook

Command line interface#

nxpdice#

Application designed to cover DICE-related operations.

Usage

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

add-device#

Add virtual device to the models_dir.

Usage

nxpdice add-device [OPTIONS]

Options

-md, --models-dir <models_dir>#: Path to folder with MCU model files. When using models the –port option is used as sub-folder name in models-dir

-n, --name <name>#: Required Name for the device

create-models#

Create models directory for debugging purposes.

Usage

nxpdice create-models [OPTIONS]

Options

-md, --models-dir <models_dir>#: Path to directory where to create models directory for debugging purposes

-n, --number <number>#: Required Number of virtual devices to crate for debugging purposes.

-p, --prefix <prefix>#: Prefix for device model names. Number of device will be appended to the prefix.

get-ca-puk#

Get NXP_CUST_DICE_CA_PUK from the device.

Usage

nxpdice get-ca-puk [OPTIONS]

Options

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

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

-f, --family <family>#

[required] Select the chip family.

Options:: lpc55s36 | mcxn247 | mcxn526 | mcxn527 | mcxn536 | mcxn537 | mcxn546 | mcxn547 | mcxn556s | mcxn557s | mcxn946 | mcxn947

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

-md, --models-dir <models_dir>#: Path to folder with MCU model files. When using models the –port option is used as sub-folder name in models-dir

-o, --output <output>#: Required Path where to store the NXP_CUST_DICE_CA_PUK

--rkth <rkth>#: Required HEX value of RKTH

--mldsa#: Get MLDSA public key instead of default ECC PUK

get-families#

Shows the full family info for commands in this group.

Usage

nxpdice get-families [OPTIONS]

Options

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

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

Options:: register-ca-puk | get-ca-puk | register-version | verify | get-response | get-pg-response

get-fmc-config#

Get config file for creating FMC certificate template.

Usage

nxpdice get-fmc-config [OPTIONS]

Options

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

get-fmc-container#

Generate the FMC Alias certificate container.

Usage

nxpdice get-fmc-container [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.

get-pg-response#

Get Prove-Genuinity response from the target.

Usage

nxpdice get-pg-response [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.

-f, --family <family>#

[required] Select the chip family.

Options:: lpc55s36 | mcxn247 | mcxn526 | mcxn527 | mcxn536 | mcxn537 | mcxn546 | mcxn547 | mcxn556s | mcxn557s | mcxn946 | mcxn947

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

-m, --mode <mode>#

Prove genuinity mode

Default:: 'ECDSA'
Options:: ECDSA | Hybrid

-ch, --challenge <challenge>#: Challenge to be used for proving genuinity (16B = 32 chars). If not specified a random challenge will be generated

get-response#

Get DICE response from the device.

Usage

nxpdice get-response [OPTIONS]

Options

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

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

-f, --family <family>#

[required] Select the chip family.

Options:: lpc55s36 | mcxn247 | mcxn526 | mcxn527 | mcxn536 | mcxn537 | mcxn546 | mcxn547 | mcxn556s | mcxn557s | mcxn946 | mcxn947

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

-md, --models-dir <models_dir>#: Path to folder with MCU model files. When using models the –port option is used as sub-folder name in models-dir

--response <response>#: Required Path where to store the DICE response

-c, --challenge <challenge>#: Optional challenge. If not specified a random challenge will be used.

make-fmc-container#

Create TP container from existing template and descriptor.

Usage

nxpdice make-fmc-container [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.

make-idevid-cert#

Create an iDevID certificate from a Prove Genuinity response.

Usage

nxpdice make-idevid-cert [OPTIONS]

Options

-r, --response <response>#: Required Path to the Prove Genuinity response file

-sn, --subject-name <subject_name>#: Required Subject common name for the iDevID certificate

-p, --product-puk <product_puk>#: Path to the product public key file(s)

-cr, --ca-prk-key <ca_prk_key>#: Required Path to the CA private key file for signing

-cu, --ca-puk-key <ca_puk_key>#: Path to the CA public key file for issuer setup

-cn, --ca-name <ca_name>#: CA name for issuer setup

--use-full-der-for-serial#: Use full DER encoding for subject serial number calculation

-o, --output <output>#: Required Path to output the generated iDevID certificate

print#

Print the contents of a Prove Genuinity response or CSR file.

Usage

nxpdice print [OPTIONS]

Options

-r, --response <response>#: Required Path to the Prove Genuinity response or CSR file

register-ca-puk#

Get NXP_CUST_DICE_CA_PUK from the device and register it in the verification service.

Usage

nxpdice register-ca-puk [OPTIONS]

Options

-su, --service-url <service_url>#: DICE verification service URL. Example: http://localhost:8080

-db, --database <database>#: Path to local database instead of service-url.

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

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

-f, --family <family>#

[required] Select the chip family.

Options:: lpc55s36 | mcxn247 | mcxn526 | mcxn527 | mcxn536 | mcxn537 | mcxn546 | mcxn547 | mcxn556s | mcxn557s | mcxn946 | mcxn947

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

-md, --models-dir <models_dir>#: Path to folder with MCU model files. When using models the –port option is used as sub-folder name in models-dir

--rkth <rkth>#: Required HEX value of RKTH

-s, --store-artifact <store_artifact>#: Path where to store artifact (data) generated by the command.

register-version#

Usage

nxpdice register-version [OPTIONS]

Options

-su, --service-url <service_url>#: DICE verification service URL. Example: http://localhost:8080

-db, --database <database>#: Path to local database instead of service-url.

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

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

-f, --family <family>#

[required] Select the chip family.

Options:: lpc55s36 | mcxn247 | mcxn526 | mcxn527 | mcxn536 | mcxn537 | mcxn546 | mcxn547 | mcxn556s | mcxn557s | mcxn946 | mcxn947

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

-md, --models-dir <models_dir>#: Path to folder with MCU model files. When using models the –port option is used as sub-folder name in models-dir

-s, --store-artifact <store_artifact>#: Path where to store artifact (data) generated by the command.

upload-ca-puk#

Upload existing NXP_CUST_DICE_CA_PUK into the verification service.

Usage

nxpdice upload-ca-puk [OPTIONS]

Options

-su, --service-url <service_url>#: DICE verification service URL. Example: http://localhost:8080

-db, --database <database>#: Path to local database instead of service-url.

-c, --ca-puk <ca_puk>#: Required Path to binary file containing NXP_CUST_DICE_CA_PUK key.

upload-response#

Upload existing DICE response for verification.

Usage

nxpdice upload-response [OPTIONS]

Options

-su, --service-url <service_url>#: DICE verification service URL. Example: http://localhost:8080

-db, --database <database>#: Path to local database instead of service-url.

-r, --response <response_file>#: Required Path to binary file containing the DICE response.

upload-version#

Upload existing DICE response to register new FW version, RTF, and HAD.

Usage

nxpdice upload-version [OPTIONS]

Options

-su, --service-url <service_url>#: DICE verification service URL. Example: http://localhost:8080

-db, --database <database>#: Path to local database instead of service-url.

-r, --response <response_file>#: Path to DICE response binary. Info in response will be used to register new version.

verify#

Perform the DICE attestation verification.

Usage

nxpdice verify [OPTIONS]

Options

-su, --service-url <service_url>#: DICE verification service URL. Example: http://localhost:8080

-db, --database <database>#: Path to local database instead of service-url.

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

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

-f, --family <family>#

[required] Select the chip family.

Options:: lpc55s36 | mcxn247 | mcxn526 | mcxn527 | mcxn536 | mcxn537 | mcxn546 | mcxn547 | mcxn556s | mcxn557s | mcxn946 | mcxn947

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

-md, --models-dir <models_dir>#: Path to folder with MCU model files. When using models the –port option is used as sub-folder name in models-dir

-s, --store-artifact <store_artifact>#: Path where to store artifact (data) generated by the command.

verify-csr#

Verify the DICE CSR. Optionally export the DICE Alias keys.

Usage

nxpdice verify-csr [OPTIONS]

Options

-c, --csr-file <csr_file>#: Required Path to the DICE CSR file

-pk, --product-key-file <product_key_file>#: Required Path(s) to NXP PROD public key file(s) for verification

-dk, --dice-ca-key-file <dice_ca_key_file>#: Required Path(s) to DICE CA public key file(s) for verification

-ch, --challenge <challenge>#: Challenge used for proving genuinity (16B = 32 chars). If not specified, challenge check will be skipped.

-ea, --export-alias-keys <export_alias_keys>#: Path to export DICE Alias public keys. (entry serves as a prefix for all DICE Alias keys found in the CSR)

--strict#: Enable strict verification mode

verify-pg-response#

Verify the Prove Genuinity response.

Usage

nxpdice verify-pg-response [OPTIONS]

Options

-r, --response <response>#: Required Path to the Prove Genuinity response file

-k, --key-file <key_file>#: Required Path(s) to public key file(s) for verification

-ch, --challenge <challenge>#: Challenge used for proving genuinity (16B = 32 chars). If not specified, challenge check will be skipped.

User Guide - nxpdice

Contents

User Guide - nxpdice#

Command line interface#

nxpdice#

add-device#

create-models#

get-ca-puk#

get-families#

get-fmc-config#

get-fmc-container#

get-pg-response#

get-response#

make-fmc-container#

make-idevid-cert#

print#

register-ca-puk#

register-version#

upload-ca-puk#

upload-response#

upload-version#

verify#

verify-csr#

verify-pg-response#