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:

mx8ulp | mx93 | mx95 | rt118x

-r, --revision <revision>

Chip revision; if not specified, most recent one will be used

commit

Commit information.

nxpele commit [OPTIONS]

Options

-i, --commit-info <commit_info>

Required Info to be committed. It could be used multiple

Options:

NXP_SRK_REVOCATION | NXP_FW_FUSE | OEM_SRK_REVOCATION | OEM_FW_FUSE

derive-key

Derive key.

Allowed sizes are 16 and 32 bytes.

nxpele derive-key [OPTIONS]

Options

-s, --size <size>

Size of output key

Options:

16 | 32

-c, --key-diversification-context <key_diversification_context>

File path to Key diversification context binary file

-o, --output <output>

Derived key output file.

dump-debug-data

Dump ELE debug buffer data of EdgeLock Enclave firmware.

nxpele dump-debug-data [OPTIONS]

ele-fw-auth

Authenticate and execute EdgeLock Enclave firmware.

Firmware should be placed in any memory accessible by ROM code if ‘-a’ is used, otherwise the correct address will be used.

nxpele ele-fw-auth [OPTIONS]

Options

-a, --address <address>

Address of EdgeLock Enclave firmware container in target memory.

-b, --binary <binary>

File name with binary of EdgeLock Enclave firmware.

enable-apc

Send request to enable APC to EdgeLock Enclave.

nxpele enable-apc [OPTIONS]

enable-rtc

Send request to enable RTC to EdgeLock Enclave.

nxpele enable-rtc [OPTIONS]

forward-lifecycle-update

Forward Lifecycle update to Closed or Locked state.

The Forward Lifecycle update message is used to change the chip lifecycle. It is used for updating the lifecycle state to OEM Closed or OEM Locked.

nxpele forward-lifecycle-update [OPTIONS]

Options

-l, --lifecycle <lifecycle>

Required Lifecycle to switch to value

Options:

OEM_CLOSED | OEM_LOCKED

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

Get stored events in EdgeLock Enclave.

nxpele get-events [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.

oem-cntn-auth

Authenticate OEM container.

Container should be placed in any memory accessible by ROM code

nxpele oem-cntn-auth [OPTIONS]

Options

-a, --address <address>

Address of OEM container in target memory.

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]

reset-apc-context

Send request to reset APC context in EdgeLock Enclave.

nxpele reset-apc-context [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]

verify-image

Verify OEM image.

The Verify Image message is sent to the ELE after a container has been loaded into memory and processed with an Authenticate Container message. This commands the ELE to check the hash on one or more images.

nxpele verify-image [OPTIONS]

Options

-m, --mask <mask>

Used to indicate which images are to be checked. There must be at least one image. If not defined Image_0 will be checked.

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

-i, --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