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

-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

-t, --timeout <ms>#

Sets timeout when waiting on data over a serial line. The default is 5000 milliseconds.

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

-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