User Guide - nxpele

This user guide describes how to use nxpele application. nxpele is a tool to communicate with EdgeLock Enclave hardware on target where is used(like i.MXRT118x). The tool is build up on blhost commands (write-memory, read-memory and ele-message), so it contains standard blhost options to establish connection with ISP mboot.

NXP EdgeLock Enclave - available commands/messages
1	ele-fw-auth
2	generate-keyblob
2.a	DEK
2.b	IEE
2.c	OTFAD
3	get-ele-fw-status
4	get-ele-fw-version
5	get-info
6	ping
7	release-container
8	signed-message
9	start-trng

Command line interface

nxpele

Utility for communication with the EdgeLock Enclave on target over BLHOST.

nxpele [OPTIONS] COMMAND [ARGS]...

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.

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

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)

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

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

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

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

--version: Show the version and exit.

--help: Show this message and exit.

-f, --family <family>

Select the chip family.

Options: mx93 | rt118x

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

ele-fw-auth

Authenticate and execute EdgeLock Enclave firmware.

Firmware could be placed in any memory accessible by ROM code.

nxpele ele-fw-auth [OPTIONS]

Options

-a, --address <address>: Required Address of EdgeLock Enclave firmware container.

generate-keyblob

Group of sub-commands related to generate Keyblob.

nxpele generate-keyblob [OPTIONS] COMMAND [ARGS]...

DEK

Generate DEK keyblob on EdgeLock Enclave.

nxpele generate-keyblob DEK [OPTIONS]

Options

-a, --algorithm <algorithm>

Required Encryption algorithm to wrap key.

Options: AES_CBC | SM4_CBC

-i, --key-id <key_id>: Required Key ID (know also as Key Identifier), the same value has to be provided again when decrypting the generated blob.

-k, --key <key>: Required Key as hexadecimal string or path to file containing key in plain text or in binary

-s, --key-size <key_size>: Required Key size in bits. Table with allowed combination: AES_CBC: [128, 192, 256], SM4_CBC: [128],

-o, --output <output>: Store DEK keyblob into a file. If not used, then value is just printed to console.

IEE

Generate IEE keyblob atomic command on EdgeLock Enclave.

nxpele generate-keyblob IEE [OPTIONS]

Options

-i, --key-id <key_id>: Required Key ID (know also as Key Identifier),the same value has to be provided again when decrypting the generated blob.

-a, --algorithm <algorithm>

Required Encryption algorithm to wrap key.

Options: AES_XTS | AES_CTR

-k, --key <key>: Required AES Key as hexadecimal string or path to file containing key in plain text or in binary

-s, --key-size <key_size>: Required Key size in bits. Table with allowed combination: AES_XTS: [256, 512], AES_CTR: [128, 256],

-c, --counter <counter>: AES 64 bit counter as hexadecimal string or path to file containing key in plain text or in binary

-m, --ctr-mode <ctr_mode>

AES CTR mode in case that is used

Options: CTR_WITH_ADDRESS | CTR_WITHOUT_ADDRESS | CTR_KEY_STREAM

-p, --page-offset <page_offset>: IEE page offset, default is 0

-r, --region-number <region_number>: Required Region number

-b, --bypass: Bypass Encryption

-l, --locked: Lock configuration

-o, --output <output>: Store IEE keyblob into a file. If not used, then value is just printed to console.

IEE-KEYBLOB

Generate IEE keyblob on EdgeLock Enclave.

nxpele generate-keyblob IEE-KEYBLOB [OPTIONS]

Options

-r, --region-number <region_number>: Required Region number

-c, --config <config>: Required Configuration file from NXPIMAGE IEE tool. From the config, all needed values has been loaded.

-o, --output <output>: Store IEE keyblob into a file. If not used, value is just printed to console.

OTFAD

Generate OTFAD keyblob atomic command on EdgeLock Enclave.

This commands send just return raw format of one quarter of whole OTFAD DUK keyblob. For experts only! To get whole working keyblob use OTFAD-KEYBLOB command.

nxpele generate-keyblob OTFAD [OPTIONS]

Options

-i, --key-id <key_id>: Required Key ID (know also as Key Identifier): Byte 0: Index of the OTFAD key struct (0 .. 3). Important when the key scrambling is enabled. Byte 1: 0x1 - FlexSPI 1, 0x2 - FlexSPI 2. Bytes 2-3: reserved

-k, --key <key>: Required AES 128 key as hexadecimal string or path to file containing key in plain text or in binary

-c, --counter <counter>: Required AES 64 bit counter as hexadecimal string or path to file containing key in plain text or in binary

-s, --start-address <start_address>: Required Start address of OTFAD. Address must be aligned to 1KB block

-e, --end-address <end_address>: Required End address of OTFAD. Address must be aligned to 1KB block

-r, --read-only: Configuration is read only

-d, --decryption_enabled: Decryption is enabled

-v, --valid: Configuration is valid

-o, --output <output>: Store OTFAD keyblob into a file. If not used, value is just printed to console.

OTFAD-KEYBLOB

Generate OTFAD keyblob on EdgeLock Enclave.

nxpele generate-keyblob OTFAD-KEYBLOB [OPTIONS]

Options

-i, --flexspi-index <flexspi_index>: Index of used FlexSPI peripheral. Typically 1 or 2.

-c, --config <config>: Required Configuration file from NXPIMAGE OTFAD tool. From the config, all needed values has been loaded.

-o, --output <output>: Store OTFAD keyblob into a file. If not used, value is just printed to console.

get-ele-fw-status

Get status of EdgeLock Enclave firmware.

nxpele get-ele-fw-status [OPTIONS]

get-ele-fw-version

Get version of EdgeLock Enclave firmware.

nxpele get-ele-fw-version [OPTIONS]

get-ele-trng-state

Get status of EdgeLock Enclave TRNG.

nxpele get-ele-trng-state [OPTIONS]

get-info

Get information from EdgeLock Enclave.

nxpele get-info [OPTIONS]

load-keyblob

Load EdgeLock Enclave keyblob to hardware.

The command ‘Load key blob’ is used to inject some keys in specific HW blocks. Currently only the IEE HW is supported. The expected blob must have been previously created by using the ‘Generate Key Blob’ command.

nxpele load-keyblob [OPTIONS]

Options

-i, --key-id <key_id>: Required Key ID (know also as Key Identifier), the same value has to be provided again when decrypting the generated blob.

-b, --binary <binary>: Required Binary file with EdgeLock Enclave keyblob to be loaded to HW.

ping

Send general EdgeLock Enclave PING message.

nxpele ping [OPTIONS]

read-common-fuse

Read common fuse from EdgeLock Enclave.

Not all fuses could be read by this command, just some of them are supported.

nxpele read-common-fuse [OPTIONS]

Options

-i, --index <index>: Required Fuse index.

read-shadow-fuse

Read shadow fuse from EdgeLock Enclave.

Not all fuses could be read by this command, just some of them are supported.

nxpele read-shadow-fuse [OPTIONS]

Options

-i, --index <index>: Required Fuse index.

release-container

Release EdgeLock Enclave firmware message.

nxpele release-container [OPTIONS]

reset

Send general EdgeLock Enclave RESET message.

nxpele reset [OPTIONS]

signed-message

Send signed message to EdgeLock Enclave.

Signed message could be created by ‘nxpimage signed-msg’ tool.

nxpele signed-message [OPTIONS]

Options

-b, --binary <binary>: Required Binary file with signed message container.

start-trng

Start True Random Number Generator in EdgeLock Enclave message.

nxpele start-trng [OPTIONS]

write-fuse

Write one fuse by specifying index and data to be written.

nxpele write-fuse [OPTIONS]

Options

-d, --data <data>: Required Data to be written

-p, --index <index>: Required Index of the fuse to be written

--lock: Write lock fuse

write-shadow-fuse

Write one shadow fuse by specifying index and data to be written.

nxpele write-shadow-fuse [OPTIONS]

Options

-d, --data <data>: Required Data to be written

-i, --index <index>: Required Index of the fuse to be written