ELE message support API

This module contains support for EdgeLock Enclave messages system.

Module with the EdgeLock Enclave messages

EdgeLock Enclave Message.

class spsdk.ele.ele_message.EleMessage

Bases: object

Base class for any EdgeLock Enclave Message.

Message contains a header - tag, command id, size and version.

Class object initialized.

CMD = 0

COMMAND_HEADER_WORDS_COUNT = 1

COMMAND_PAYLOAD_WORDS_COUNT = 0

ELE_MSG_ALIGN = 8

HEADER_FORMAT = '<BBBB'

MAX_COMMAND_DATA_SIZE = 0

MAX_RESPONSE_DATA_SIZE = 0

RESPONSE_HEADER_WORDS_COUNT = 2

RESPONSE_PAYLOAD_WORDS_COUNT = 0

RSP_TAG = 225

TAG = 23

VERSION = 6

property command_address: int: Command address in target memory space.

property command_data: bytes: Command data to be loaded into target memory space.

property command_data_address: int: Command data address in target memory space.

property command_data_size: int: Command data address in target memory space.

property command_words_count: int: Command Words count.

decode_response(response)

Decode response from target.

Parameters:: response (bytes) – Data of response.
Raises:: SPSDKParsingError – Response parse detect some error.
Return type:: None

decode_response_data(response_data)

Decode response data from target.

Note:: The response data are specific per command.
Parameters:: response_data (bytes) – Data of response.
Return type:: None

export()

Exports message to final bytes array.

Return type:: bytes
Returns:: Bytes representation of message object.

static get_msg_crc(payload)

Compute message CRC.

Parameters:: payload (bytes) – The input data to compute CRC on them. Must be 4 bytes aligned.
Return type:: bytes
Returns:: 4 bytes of CRC in little endian format.

property has_command_data: bool: Check if command has additional data.

property has_response_data: bool: Check if response has additional data.

header_export()

Exports message header to bytes.

Return type:: bytes
Returns:: Bytes representation of message header.

info()

Print information including live data.

Return type:: str
Returns:: Information about the message.

property response_address: int: Response address in target memory space.

property response_data_address: int: Response data address in target memory space.

property response_data_size: int: Response data address in target memory space.

response_status()

Print the response status information.

Return type:: str
Returns:: String with response status.

property response_words_count: int: Response Words count.

set_buffer_params(buff_addr, buff_size)

Set the communication buffer parameters to allow command update addresses inside command payload.

Parameters:

buff_addr (int) – Real address of communication buffer in target memory space
buff_size (int) – Size of communication buffer in target memory space

Return type:

None

property status_string: str: Get status in readable string format.

validate()

Validate message.

Return type:: None

validate_buffer_params()

Validate communication buffer parameters.

raises SPSDKValueError: Invalid buffer parameters.

Return type:: None

class spsdk.ele.ele_message.EleMessageEleFwAuthenticate(ele_fw_address)

Bases: EleMessage

Ele firmware authenticate request.

Constructor.

Be aware to have ELE FW in accessible memory for ROM, and do not use the RAM memory used to communicate with ELE.

Parameters:: ele_fw_address (int) – Address in target memory with ele firmware.

CMD = 2

COMMAND_PAYLOAD_WORDS_COUNT = 3

export()

Exports message to final bytes array.

Return type:: bytes
Returns:: Bytes representation of message object.

class spsdk.ele.ele_message.EleMessageGenerateKeyBLob(key_identifier, algorithm, key)

Bases: EleMessage

ELE Message Generate KeyBlob.

Constructor of Generate Key Blob class.

Parameters:

key_identifier (int) – ID of key
algorithm (int) – Select supported algorithm
key (bytes) – Key to be wrapped

CMD = 175

COMMAND_PAYLOAD_WORDS_COUNT = 7

KEYBLOB_NAME = 'Unknown'

KEYBLOB_TAG = 129

KEYBLOB_VERSION = 0

MAX_RESPONSE_DATA_SIZE = 512

SUPPORTED_ALGORITHMS: Dict[int, List[int]] = {}

decode_response_data(response_data)

Decode response data from target.

Note:: The response data are specific per command.
Parameters:: response_data (bytes) – Data of response.
Raises:: SPSDKParsingError – Invalid response detected.
Return type:: None

export()

Exports message to final bytes array.

Return type:: bytes
Returns:: Bytes representation of message object.

classmethod get_supported_algorithms()

Get the list of supported algorithms.

Return type:: List[str]
Returns:: List of supported algorithm names.

classmethod get_supported_key_sizes()

Get table with supported key sizes per algorithm.

Return type:: str
Returns:: Table with supported key size in text.

info()

Print information including live data.

Return type:: str
Returns:: Information about the message.

validate()

Validate generate keyblob message data.

Raises:: SPSDKValueError – Invalid used key size or encryption algorithm
Return type:: None

class spsdk.ele.ele_message.EleMessageGenerateKeyBLobDek(key_identifier, algorithm, key)

Bases: EleMessageGenerateKeyBLob

ELE Message Generate DEK KeyBlob.

Constructor of Generate Key Blob class.

Parameters:

key_identifier (int) – ID of key
algorithm (int) – Select supported algorithm
key (bytes) – Key to be wrapped

KEYBLOB_NAME = 'DEK'

SUPPORTED_ALGORITHMS: Dict[int, List[int]] = {3: [128, 192, 256], 43: [128]}

property command_data: bytes: Command data to be loaded into target memory space.

class spsdk.ele.ele_message.EleMessageGenerateKeyBLobIee(key_identifier, algorithm, key, ctr_mode, aes_counter, page_offset, region_number, bypass=False, locked=False)

Bases: EleMessageGenerateKeyBLob

ELE Message Generate IEE KeyBlob.

Constructor of generate IEE keyblob class.

Parameters:

key_identifier (int) – ID of key
algorithm (int) – Used algorithm
key (bytes) – IEE key
ctr_mode (int) – In case of AES CTR algorithm, the CTR mode must be selected
aes_counter (bytes) – AES counter in case of AES CTR algorithm
page_offset (int) – IEE page offset
region_number (int) – Region number
bypass (bool) – Encryption bypass flag, defaults to False
locked (bool) – Locked flag, defaults to False

KEYBLOB_NAME = 'IEE'

SUPPORTED_ALGORITHMS: Dict[int, List[int]] = {4: [128, 256], 55: [256, 512]}

property command_data: bytes: Command data to be loaded into target memory space.

info()

Print information including live data.

Return type:: str
Returns:: Information about the message.

class spsdk.ele.ele_message.EleMessageGenerateKeyBLobOtfad(key_identifier, key, aes_counter, start_address, end_address, read_only=True, decryption_enabled=True, configuration_valid=True)

Bases: EleMessageGenerateKeyBLob

ELE Message Generate OTFAD KeyBlob.

Constructor of generate OTFAD keyblob class.

Parameters:

key_identifier (int) – ID of Key
key (bytes) – OTFAD key
aes_counter (bytes) – AES counter value
start_address (int) – Start address in memory to be encrypted
end_address (int) – End address in memory to be encrypted
read_only (bool) – Read only flag, defaults to True
decryption_enabled (bool) – Decryption enable flag, defaults to True
configuration_valid (bool) – Configuration valid flag, defaults to True

KEYBLOB_NAME = 'OTFAD'

SUPPORTED_ALGORITHMS: Dict[int, List[int]] = {4: [128]}

property command_data: bytes: Command data to be loaded into target memory space.

info()

Print information including live data.

Return type:: str
Returns:: Information about the message.

validate()

Validate generate OTFAD keyblob.

Return type:: None

class spsdk.ele.ele_message.EleMessageGetFwStatus

Bases: EleMessage

ELE Message Get FW status.

Class object initialized.

CMD = 197

RESPONSE_PAYLOAD_WORDS_COUNT = 1

decode_response(response)

Decode response from target.

Parameters:: response (bytes) – Data of response.
Raises:: SPSDKParsingError – Response parse detect some error.
Return type:: None

response_info()

Print specific information of ELE.

Return type:: str
Returns:: Information about the ELE.

class spsdk.ele.ele_message.EleMessageGetFwVersion

Bases: EleMessage

ELE Message Get FW version.

Class object initialized.

CMD = 157

RESPONSE_PAYLOAD_WORDS_COUNT = 2

decode_response(response)

Decode response from target.

Parameters:: response (bytes) – Data of response.
Raises:: SPSDKParsingError – Response parse detect some error.
Return type:: None

response_info()

Print specific information of ELE.

Return type:: str
Returns:: Information about the ELE.

class spsdk.ele.ele_message.EleMessageGetInfo

Bases: EleMessage

ELE Message Get Info.

Class object initialized.

CMD = 218

COMMAND_PAYLOAD_WORDS_COUNT = 3

MAX_RESPONSE_DATA_SIZE = 256

decode_response_data(response_data)

Decode response data from target.

Note:: The response data are specific per command.
Parameters:: response_data (bytes) – Data of response.
Return type:: None

export()

Exports message to final bytes array.

Return type:: bytes
Returns:: Bytes representation of message object.

response_info()

Print specific information of ELE.

Return type:: str
Returns:: Information about the ELE.

class spsdk.ele.ele_message.EleMessageGetTrngState

Bases: EleMessage

ELE Message Get True Random Generator State.

Class object initialized.

CMD = 163

RESPONSE_PAYLOAD_WORDS_COUNT = 1

decode_response(response)

Decode response from target.

Parameters:: response (bytes) – Data of response.
Raises:: SPSDKParsingError – Response parse detect some error.
Return type:: None

response_info()

Print specific information of ELE.

Return type:: str
Returns:: Information about the TRNG.

class spsdk.ele.ele_message.EleMessagePing

Bases: EleMessage

ELE Message Ping.

Class object initialized.

CMD = 1

class spsdk.ele.ele_message.EleMessageReadCommonFuse(index)

Bases: EleMessage

ELE Message Read common fuse.

Constructor.

Read common fuse.

Parameters:: index (int) – Fuse ID.

CMD = 151

COMMAND_PAYLOAD_WORDS_COUNT = 1

RESPONSE_PAYLOAD_WORDS_COUNT = 1

decode_response(response)

Decode response from target.

Parameters:: response (bytes) – Data of response.
Raises:: SPSDKParsingError – Response parse detect some error.
Return type:: None

export()

Exports message to final bytes array.

Return type:: bytes
Returns:: Bytes representation of message object.

response_info()

Print fuse value.

Return type:: str
Returns:: Read fuse value.

class spsdk.ele.ele_message.EleMessageReadShadowFuse(index)

Bases: EleMessageReadCommonFuse

ELE Message Read shadow fuse.

Constructor.

Read common fuse.

Parameters:: index (int) – Fuse ID.

CMD = 243

export()

Exports message to final bytes array.

Return type:: bytes
Returns:: Bytes representation of message object.

class spsdk.ele.ele_message.EleMessageReleaseContainer

Bases: EleMessage

ELE Message Release container.

Class object initialized.

CMD = 137

class spsdk.ele.ele_message.EleMessageReset

Bases: EleMessage

ELE Message Reset.

Class object initialized.

CMD = 199

RESPONSE_HEADER_WORDS_COUNT = 0

class spsdk.ele.ele_message.EleMessageSigned(signed_msg)

Bases: EleMessage

ELE Message Signed.

Class object initialized.

Parameters:: signed_msg (bytes) – Signed message container.

COMMAND_PAYLOAD_WORDS_COUNT = 2

property command_data: bytes: Command data to be loaded into target memory space.

export()

Exports message to final bytes array.

Return type:: bytes
Returns:: Bytes representation of message object.

info()

Print information including live data.

Return type:: str
Returns:: Information about the message.

class spsdk.ele.ele_message.EleMessageStartTrng

Bases: EleMessage

ELE Message Start True Random Generator.

Class object initialized.

CMD = 163

class spsdk.ele.ele_message.EleMessageWriteFuse(bit_position, bit_length, lock, payload)

Bases: EleMessage

Write Fuse request.

Constructor.

This command allows to write to the fuses. OEM Fuses are accessible depending on the chip lifecycle.

Parameters:

bit_position (int) – Fuse identifier expressed as its position in bit in the fuse map.
bit_length (int) – Number of bits to be written.
lock (bool) – Write lock requirement. When set to 1, fuse words are locked. When unset, no write lock is done.
payload (int) – Data to be written

CMD = 214

COMMAND_PAYLOAD_WORDS_COUNT = 2

export()

Exports message to final bytes array.

Return type:: bytes
Returns:: Bytes representation of message object.

class spsdk.ele.ele_message.EleMessageWriteShadowFuse(index, value)

Bases: EleMessage

Write shadow fuse request.

Constructor.

This command allows to write to the shadow fuses.

Parameters:

index (int) – Fuse identifier expressed as its position in bit in the fuse map.
value (int) – Data to be written.

CMD = 242

COMMAND_PAYLOAD_WORDS_COUNT = 2

export()

Exports message to final bytes array.

Return type:: bytes
Returns:: Bytes representation of message object.

Module with the EdgeLock Enclave message handler with mBoot

EdgeLock Enclave Message handler.

class spsdk.ele.ele_comm.EleMessageHandler(mboot, family, revision='latest')

Bases: object

EdgeLock Enclave Message Handler over MCUBoot.

This class can send the ELE message into target over mBoot and decode the response.

Class object initialized.

Parameters:

mboot (McuBoot) – mBoot device.
family (str) – Target family name.
revision (str) – Target revision, default is use ‘latest’ revision.

static get_supported_families()

Get list of supported target families.

Return type:: List[str]
Returns:: List of supported families.

send_message(msg)

Send message and receive response.

Parameters:

msg (EleMessage) – EdgeLock Enclave message

Raises:

SPSDKError – Invalid response status detected.
SPSDKLengthError – Invalid read back length detected.

Return type:

None

Module with the EdgeLock Enclave message constants

EdgeLock Enclave Message constants.

class spsdk.ele.ele_constants.EleCsalState

Bases: Enum

ELE CSAL state.

ELE_CSAL_ERROR = 3

ELE_CSAL_NOT_READY = 0

ELE_CSAL_ON_GOING = 1

ELE_CSAL_READY = 2

class spsdk.ele.ele_constants.EleFwStatus

Bases: Enum

ELE Firmware status.

ELE_FW_STATUS_IN_PLACE = 1

ELE_FW_STATUS_NOT_IN_PLACE = 0

class spsdk.ele.ele_constants.EleTrngState

Bases: Enum

ELE TRNG state.

ELE_TRNG_ERROR = 4

ELE_TRNG_GENERATING_ENTROPY = 1

ELE_TRNG_PROGRAM = 1

ELE_TRNG_READY = 3

class spsdk.ele.ele_constants.KeyBlobEncryptionAlgorithm

Bases: Enum

ELE KeyBlob encryption algorithms.

AES_CBC = 3

AES_CTR = 4

AES_XTS = 55

SM4_CBC = 43

class spsdk.ele.ele_constants.KeyBlobEncryptionIeeCtrModes

Bases: Enum

IEE Keyblob mode attributes.

AesCTRWAddress = 2

AesCTRWOAddress = 3

AesCTRkeystream = 4

class spsdk.ele.ele_constants.LifeCycle

Bases: Enum

ELE life cycles.

LC_BLANK = 2

LC_BRICKED = 1024

LC_FAB = 4

LC_NXP_FR = 256

LC_NXP_PROV = 8

LC_OEM_CLSD = 64

LC_OEM_FR = 128

LC_OEM_LCKD = 512

LC_OEM_OPEN = 16

LC_OEM_SWC = 32

class spsdk.ele.ele_constants.MessageIDs

Bases: Enum

ELE Messages ID.

ELE_FW_AUTH_REQ = 2

ELE_RELEASE_CONTAINER_REQ = 137

GENERATE_KEY_BLOB_REQ = 175

GET_FW_STATUS_REQ = 197

GET_FW_VERSION_REQ = 157

GET_INFO_REQ = 218

GET_TRNG_STATE_REQ = 163

PING_REQ = 1

READ_COMMON_FUSE = 151

READ_SHADOW_FUSE = 243

RESET_REQ = 199

RETURN_LIFECYCLE_UPDATE_REQ = 160

START_RNG_REQ = 163

WRITE_FUSE = 214

WRITE_SEC_FUSE_REQ = 145

WRITE_SHADOW_FUSE = 242

class spsdk.ele.ele_constants.ResponseIndication

Bases: Enum

ELE Message Response indication.

ELE_ABORT_IND = 255

ELE_APC_ALREADY_ENABLED_FAILURE_IND = 203

ELE_AUTH_SKIPPED_OR_FAILED_FAILURE_IND = 187

ELE_BAD_CERTIFICATE_FAILURE_IND = 252

ELE_BAD_CONTAINER_FAILURE_IND = 247

ELE_BAD_FUSE_ID_FAILURE_IND = 246

ELE_BAD_HASH_FAILURE_IND = 241

ELE_BAD_ID_FAILURE_IND = 191

ELE_BAD_IMAGE_ADDR_FAILURE_IND = 196

ELE_BAD_IMAGE_NUM_FAILURE_IND = 195

ELE_BAD_IMAGE_PARAM_FAILURE_IND = 197

ELE_BAD_IMAGE_TYPE_FAILURE_IND = 198

ELE_BAD_KEY_HASH_FAILURE_IND = 250

ELE_BAD_MONOTONIC_COUNTER_FAILURE_IND = 254

ELE_BAD_PAYLOAD_FAILURE_IND = 177

ELE_BAD_SIGNATURE_FAILURE_IND = 240

ELE_BAD_SRK_SET_FAILURE_IND = 239

ELE_BAD_UID_FAILURE_IND = 253

ELE_BAD_VALUE_FAILURE_IND = 245

ELE_BAD_VERSION_FAILURE_IND = 248

ELE_CORRUPTED_SRK_FAILURE_IND = 208

ELE_CRC_ERROR_IND = 185

ELE_CSTM_FAILURE_IND = 207

ELE_DECRYPTION_FAILURE_IND = 169

ELE_DISABLED_FEATURE_FAILURE_IND = 182

ELE_DMA_FAILURE_IND = 181

ELE_ENCRYPTION_FAILURE_IND = 168

ELE_FW_PING_FAILURE_IND = 26

ELE_INCONSISTENT_PAR_FAILURE_IND = 188

ELE_INVALID_KEY_FAILURE_IND = 249

ELE_INVALID_LIFECYCLE_IND = 242

ELE_INVALID_MESSAGE_FAILURE_IND = 244

ELE_INVALID_OPERATION_FAILURE_IND = 192

ELE_LOCKED_REG_FAILURE_IND = 190

ELE_MSG_TRUNCATED_IND = 194

ELE_MUST_ATTEST_FAILURE_IND = 183

ELE_MUST_SIGNED_FAILURE_IND = 224

ELE_NON_SECURE_STATE_FAILURE_IND = 193

ELE_NO_AUTHENTICATION_FAILURE_IND = 238

ELE_NO_VALID_CONTAINER_FAILURE_IND = 251

ELE_OLD_VERSION_FAILURE_IND = 206

ELE_OTP_INVALID_IDX_FAILURE_IND = 173

ELE_OTP_LOCKED_FAILURE_IND = 171

ELE_OTP_PROGFAIL_FAILURE_IND = 170

ELE_OUT_OF_MEMORY_IND = 209

ELE_PERMISSION_DENIED_FAILURE_IND = 243

ELE_RNG_INST_FAILURE_IND = 189

ELE_RNG_NOT_STARTED_FAILURE_IND = 184

ELE_ROM_PING_FAILURE_IND = 10

ELE_RTC_ALREADY_ENABLED_FAILURE_IND = 204

ELE_TIME_OUT_FAILURE_IND = 176

ELE_UNALIGNED_PAYLOAD_FAILURE_IND = 166

ELE_WRONG_ADDRESS_FAILURE_IND = 180

ELE_WRONG_BOOT_MODE_FAILURE_IND = 205

ELE_WRONG_SIZE_FAILURE_IND = 167

class spsdk.ele.ele_constants.ResponseStatus

Bases: Enum

ELE Message Response status.

ELE_FAILURE_IND = 41

ELE_SUCCESS_IND = 214