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 it is used, for example: i.MX RT1180 or i.MX 93.

Nxpele supports three modes of communication:

mboot mode - nxpele communicates with EdgeLock Enclave using mboot commands (i.MX RT1180).

In order to use the nxpele in mboot mode, flashloader must be loaded to target memory. It relies on mboot commands (write-memory, read-memory and ele-message), so it contains standard blhost options to establish connection with ISP mboot.

uboot_serial mode - nxpele communicates with EdgeLock Enclave using u-boot serial console.

In order to use the nxpele in uboot mode, u-boot serial console must be enabled. U-Boot must be built with support for AHAB. (CONFIG_AHAB_UBOOT=y) This implementation relies on “ele_message” command in U-Boot console.

uboot_fastboot mode - nxpele communicates with EdgeLock Enclave using u-boot fastboot.

In order to use the nxpele in uboot_fastboot mode, u-boot fastboot must be enabled. U-Boot must be built with support for AHAB. (CONFIG_AHAB_UBOOT=y) and console multiplexing must be enabled (CONFIG_CONSOLE_MUX=y). This is the fastest method to communicate with EdgeLock Enclave.

For more information about building the u-boot with AHAB support, please refer to the U-Boot documentation. https://docs.u-boot.org/en/latest/build/gcc.html

Nxpele supports following commands:

NXP EdgeLock Enclave - available commands#
Command	Description
get-families	Shows the full families information for commands in this group.
batch	Invoke nxpele commands defined in command file.
ping	Send general EdgeLock Enclave PING message.
enable-apc	Send request to enable APC to EdgeLock Enclave.
enable-rtc	Send request to enable RTC to EdgeLock Enclave.
reset-apc-context	Send request to reset APC context in EdgeLock Enclave.
reset	Send general EdgeLock Enclave RESET message.
get-ele-fw-status	Get status of EdgeLock Enclave firmware.
get-ele-trng-state	Get status of EdgeLock Enclave TRNG.
get-ele-fw-version	Get version of EdgeLock Enclave firmware.
get-info	Get information from EdgeLock Enclave.
ele-fw-auth	Authenticate and execute EdgeLock Enclave firmware.
dump-debug-data	Dump ELE debug buffer data of EdgeLock Enclave firmware.
read-common-fuse	Read common fuse from EdgeLock Enclave.
read-shadow-fuse	Read shadow fuse from EdgeLock Enclave.
oem-cntn-auth	Authenticate OEM container.
commit	Commit information.
derive-key	Derive key.
verify-image	Verify OEM image.
release-container	Release EdgeLock Enclave firmware message.
forward-lifecycle-update	Forward Lifecycle update to Closed or Locked state.
signed-message	Send signed message to EdgeLock Enclave.
get-events	Get stored events in EdgeLock Enclave.
start-trng	Start True Random Number Generator in EdgeLock Enclave message.
load-keyblob	Load EdgeLock Enclave keyblob to hardware.
generate-keyblob	Group of sub-commands related to generate Keyblob.
write-fuse	Write one fuse by specifying index and data to be written.
write-shadow-fuse	Write one shadow fuse by specifying index and data to be written.

Command line interface#

nxpele#

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

nxpele [OPTIONS] COMMAND [ARGS]...

Options

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

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

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

-d, --device <device>#

Select connection method for ELE communication, otherwise default from DB will be used

Options:: mboot | uboot_serial | uboot_fastboot

--buffer-addr <buffer_addr>#: Override default buffer address for ELE communication

--buffer-size <buffer_size>#: Override default buffer size for ELE communication

--fb-addr <fb_addr>#: Override default buffer address for fastboot

--fb-size <fb_size>#: Override default buffer size for fastboot

-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:: mimx8ulp | mimx9131 | mimx9352 | mimx9596 | mimxrt1181 | mimxrt1182 | mimxrt1187 | mimxrt1189

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

batch#

Invoke nxpele commands defined in command file.

Command file contains one nxpele command per line. example: “write-fuse –index=129 –data=0x7021b4a5”

Comments are supported. Everything after ‘#’ is a comment (just like in Python/Shell)

Note: This is an early experimental format, it may change at any time.

COMMAND_FILE - path to nxpele command file

nxpele batch [OPTIONS] COMMAND_FILE

Arguments

COMMAND_FILE#: Required argument

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-families#

Shows the full family info for commands in this group.

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

-b, --binary <binary>#: Alternative to defining address, this option get the binary file, load it into device and run authentication.

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

User Guide - nxpele

Contents

User Guide - nxpele#

Command line interface#

nxpele#

batch#

commit#

derive-key#

dump-debug-data#

ele-fw-auth#

enable-apc#

enable-rtc#

forward-lifecycle-update#

generate-keyblob#

DEK#

IEE#

IEE-KEYBLOB#

OTFAD#

OTFAD-KEYBLOB#

get-ele-fw-status#

get-ele-fw-version#

get-ele-trng-state#

get-events#

get-families#

get-info#

load-keyblob#

oem-cntn-auth#

ping#

read-common-fuse#

read-shadow-fuse#

release-container#

reset#

reset-apc-context#

signed-message#

start-trng#

verify-image#

write-fuse#

write-shadow-fuse#