Trust Provisioning API

Provides support for trust provisioning containers and OEM trust provisioning.

TP Data Containers

Module implementing the TrustProvisioning Data Container.

Data Container

Module implementing the TrustProvisioning Data Container.

class spsdk.tp.data_container.data_container.BaseElement

Bases: object

Base class for items used in data_container.

abstract export()

Serialize object data.

Return type:: bytes

abstract classmethod parse(data)

Reconstruct object from serialized data.

Return type:: Self

class spsdk.tp.data_container.data_container.Container(major=1, minor=0, patch=0)

Bases: BaseElement

TrustProvisioning Data Container.

Initialize the container.

add_auth_entry(auth_type, key)

Add the final data authentication entry.

Parameters:

auth_type (AuthenticationType) – Authentication Type
key (bytes) – Key for authentication

Raises:

SPSDKTpError – Unknown or not-implemented Authentication type

Return type:

None

add_entry(entry)

Add an entry to the container.

Return type:: None

export()

Serialize the container.

Return type:: bytes

get_entries(payload_type)

Get all entries for given payload type.

Return type:: List[DataEntry]

get_entry(payload_type)

Get the first entry for the given type.

Parameters:: payload_type (PayloadType) – Type of an entry to look for
Raises:: SPSDKTpError – Container doesn’t have an entry of required type
Return type:: DataEntry
Returns:: Entry with given type

classmethod parse(data)

Reconstruct container from binary data.

Return type:: Self

validate(key)

Validate signature/authentication code.

Parameters:: key (bytes) – Key for validating signature
Raises:: SPSDKTpError – Unknown or non-implemented Authentication type
Return type:: bool
Returns:: True if signature/authentication code is valid

class spsdk.tp.data_container.data_container.ContainerHeader(major=1, minor=0, patch=0)

Bases: BaseElement

Main container header.

Initialize Container Header with version information.

Parameters:

major (int) – major version, defaults to 1
minor (int) – minor version, defaults to 0
patch (int) – patch re-vision, defaults to 0

FORMAT = '<4B2H': Binary format for entry header (used by the struct module)

SIZE = 8: Total size of the container header

TAG = 51: Tag (magic) indicating start of the container in binary stream

export()

Serialize the container header.

Return type:: bytes

classmethod parse(data)

Reconstruct the container header from binary data.

Return type:: Self

class spsdk.tp.data_container.data_container.DataAuthenticationEntry(payload, payload_type, extra=0)

Bases: DataEntry

Final Data entry used for integrity check.

Initialize Standard Data Entry.

Parameters:

payload (bytes) – Data entry payload
payload_type (int) – Data entry type
extra (int) – Extra information for the entry

TAG = 192

get_auth_type()

Get appropriate Authentication type.

Return type:: int

class spsdk.tp.data_container.data_container.DataAuthenticationEntryV2(payload, payload_type, extra=0)

Bases: DataAuthenticationEntry

Final Data entry V2 used for integrity check.

Initialize Standard Data Entry.

Parameters:

payload (bytes) – Data entry payload
payload_type (int) – Data entry type
extra (int) – Extra information for the entry

get_auth_type()

Get appropriate Authentication type.

Return type:: int

class spsdk.tp.data_container.data_container.DataDestinationEntry(payload, payload_type, destination, destination_type, extra=0)

Bases: DataEntry

Data entry including destination information.

Initialize data entry with destination record.

Parameters:

payload (bytes) – Data entry payload
payload_type (int) – Data entry type
destination (int) – Destination memory address/OTP index
destination_type (DestinationType) – Destination type memory/OTP

TAG = 176

export()

Serialize the entry.

Return type:: bytes

classmethod parse(data)

Reconstruct the entry header from binary data.

Return type:: Self

property total_size: int: Returns total size of the entry (including header and padding).

class spsdk.tp.data_container.data_container.DataEntry(payload, payload_type, extra=0)

Bases: BaseElement

Standard data entry.

Initialize Standard Data Entry.

Parameters:

payload (bytes) – Data entry payload
payload_type (int) – Data entry type
extra (int) – Extra information for the entry

TAG = 160

export()

Serialize the entry.

Return type:: bytes

classmethod parse(data)

Reconstruct the entry from binary data.

Return type:: Self

property total_size: int: Returns total size of the entry (including header and padding).

class spsdk.tp.data_container.data_container.DestinationHeader(destination, destination_type)

Bases: BaseElement

Header used to store destination information.

Initialize the destination record.

Parameters:

destination (int) – Destination address
destination_type (DestinationType) – Destination type, see: DestinationType

FORMAT = '<4BL': Binary format for destination record (used by the struct module)

SIZE = 8: Total size of the destination record

export()

Serialize the destination record.

Return type:: bytes

classmethod parse(data)

Reconstruct the destination record from binary data.

Return type:: Self

class spsdk.tp.data_container.data_container.DestinationType

Bases: Enum

Destination type setting for DataDestinationEntry.

MEMORY = 0

OTP = 2

class spsdk.tp.data_container.data_container.EntryHeader(tag, payload_size, payload_type, entry_extra=0)

Bases: BaseElement

Common Entry header for all entry types.

Initialize Entry header.

Parameters:

tag (int) – Tag indicating entry type, see EntryType
payload_size (int) – Size of entry payload, excluding header and padding
payload_type (int) – Type of entry payload
entry_extra (int) – Extra type specific data

FORMAT = '<H2B2H': Binary format for entry header (used by the struct module)

SIZE = 8: Total size of the entry header

export()

Serialize the entry header.

Return type:: bytes

classmethod parse(data)

Reconstruct the entry header from binary data.

Return type:: Self

stringify_payload_type()

Return a stringified payload type.

Return type:: str

class spsdk.tp.data_container.data_container.EntryType

Bases: Enum

Enumeration of all supported Entry types.

AUTHENTICATION = 192

DESTINATION = 176

STANDARD = 160

spsdk.tp.data_container.data_container.parse_entry(data)

Common parser for all known DataEntry classes.

Return type:: DataEntry

Audit log

Module for generating, processing and verifying TP Audit Log.

class spsdk.tp.data_container.audit_log.AuditLog(iterable=(), /)

Bases: List[AuditLogRecord]

Full Audit log, List of AuditLogRecords.

static load(file_path)

Load AuditLog from a sqlite database file.

Return type:: AuditLog

static properties(file_path)

Return properties of database.

Parameters:: file_path (str) – Path to audit log file.
Raises:: SPSDKTpError – Unable to read properties table
Return type:: AuditLogProperties

static record_count(file_path)

Return number of records in database file.

Return type:: int

static records(file_path, id_slice=None)

Read records from database file.

Parameters:

file_path (str) – Path to database file
id_slice (Optional[Tuple[int, int]]) – Read records with id between (x, y), defaults to None

Yield:

Iterator yielding record ID and record itself

Return type:

Iterator[Tuple[int, AuditLogRecord]]

save(file_path, tp_device_id)

Store AuditLog into a sqlite database file.

Return type:: None

class spsdk.tp.data_container.audit_log.AuditLogCounter(check_count=0, nxp_count=0, oem_count=0)

Bases: object

Counter for Audit Log stats (records verified, certificates exported).

Initialize counters for Audit log verification.

class spsdk.tp.data_container.audit_log.AuditLogProperties(version: int, tp_device_id: str)

Bases: tuple

Properties of the Audit log.

Create new instance of AuditLogProperties(version, tp_device_id)

classmethod from_tuple(data)

Create AuditLogProperties from database tuple.

Raises:: SPSDKTpError – Unexpected number of data members.
Return type:: AuditLogProperties

tp_device_id: str: Alias for field number 1

version: int: Alias for field number 0

class spsdk.tp.data_container.audit_log.AuditLogRecord(nxp_id_cert: bytes, oem_id_certs: List[bytes], prod_counter: bytes, start_hash: bytes, signature: bytes)

Bases: tuple

Single record in the Audit log.

Create new instance of AuditLogRecord(nxp_id_cert, oem_id_certs, prod_counter, start_hash, signature)

as_dict()

Return dictionary suitable for writing into log file.

Return type:: dict

as_tuple()

Return AuditLogRecord as tuple.

Return type:: tuple

classmethod from_data(container_data)

Create AuditLogRecord from TP Data Container.

Return type:: AuditLogRecord

classmethod from_dict(data)

Create AuditLogRecord from a dictionary.

Return type:: AuditLogRecord

classmethod from_tuple(data)

Create AuditLogRecord from a tuple.

Return type:: AuditLogRecord

is_valid(key)

Check if record is valid.

Parameters:: key (PublicKeyEcc) – PEM-encoded public key or public key object
Return type:: bool
Returns:: True if signature checks out

new_hash()

Hash together the relevant pieces of the record.

Return type:: bytes

nxp_id_cert: bytes: Alias for field number 0

oem_id_certs: List[bytes]: Alias for field number 1

prod_counter: bytes: Alias for field number 2

property prod_counter_int: int: Return production counter as an integer.

save(file_path, tp_device_id)

Store record in an sqlite database file.

Return type:: None

signature: bytes: Alias for field number 4

start_hash: bytes: Alias for field number 3

spsdk.tp.data_container.audit_log.sqlite_cursor(file_path)

Yield an cursor to SQLite database.

Parameters:: file_path (str) – Path to SQLite database file
Raises:: SPSDKTpError – Error during SQL operation
Yield:: SQLite cursor
Return type:: Iterator[Cursor]

Data Container Authentication

Module for all Authenticators used in DataContainer.

class spsdk.tp.data_container.data_container_auth.AES_CMAC

Bases: AuthenticationProvider

AES-CMAC Authenticator.

DATA_LEN = 16: Expected length of Authentication code/signature

TYPE = 16: Type of Authenticator, see: AuthenticationType

classmethod sign(data, key)

Generate CMAC authentication code.

Return type:: bytes

classmethod validate(data, signature, key)

Validate CMAC authentication code.

Return type:: bool

class spsdk.tp.data_container.data_container_auth.AuthenticationProvider

Bases: object

Base abstract class for Authenticators.

DATA_LEN = 0: Expected length of Authentication code/signature

TYPE = 0: Type of Authenticator, see: AuthenticationType

abstract classmethod sign(data, key)

Generate signature/authentication code.

Return type:: bytes

abstract classmethod validate(data, signature, key)

Validate signature/authentication code.

Return type:: bool

class spsdk.tp.data_container.data_container_auth.AuthenticationType

Bases: Enum

Available Authentication types.

AES_CMAC = 16

CRC32 = 254

ECDSA_256 = 32

HMAC_256 = 17

NONE = 0

class spsdk.tp.data_container.data_container_auth.CRC32

Bases: _CRC

CRC Authenticator using CRC32 settings.

CRC_NAME = 'crc32'

DATA_LEN = 4: Expected length of Authentication code/signature

TYPE = 254: Type of Authenticator, see: AuthenticationType

class spsdk.tp.data_container.data_container_auth.ECDSA_256

Bases: AuthenticationProvider

ECDSA Authenticator using ECC P-256.

DATA_LEN = 64: Expected length of Authentication code/signature

TYPE = 32: Type of Authenticator, see: AuthenticationType

classmethod sign(data, key)

Generate ECDSA signature.

Return type:: bytes

classmethod validate(data, signature, key)

Validate ECDSA signature.

Return type:: bool

class spsdk.tp.data_container.data_container_auth.HMAC_256

Bases: _HMAC

HMAC-256 Authenticator.

DATA_LEN = 32: Expected length of Authentication code/signature

HASHER: Optional[EnumHashAlgorithm] = 1

TYPE = 17: Type of Authenticator, see: AuthenticationType

spsdk.tp.data_container.data_container_auth.get_auth_data_len(auth_type)

Get expected length of signature/authentication code.

Parameters:: auth_type (AuthenticationType) – Type of authenticator
Raises:: SPSDKTpError – Unknown type of Authenticator
Return type:: int
Returns:: Length of signature/authentication code

spsdk.tp.data_container.data_container_auth.sign(data, auth_type, key)

Generate signature/authentication code.

Parameters:

data (bytes) – Data to create signature/authentication code from
auth_type (AuthenticationType) – Type of Authenticator
key (bytes) – Key used for Authenticator

Raises:

SPSDKTpError – [description]

Return type:

bytes

Returns:

Signature/authentication code

spsdk.tp.data_container.data_container_auth.validate(data, signature, auth_type, key)

Validate signature/authentication code.

Parameters:

data (bytes) – Data to validate
signature (bytes) – Signature/authentication code to validate
auth_type (AuthenticationType) – Authenticator to use
key (bytes) – Key for Authenticator

Raises:

SPSDKTpError – Unknown Authenticator type

Return type:

bool

Returns:

True if signature/authentication code is valid

TP Adapters

Trust provisioning adapters.

TP Config

Trust Provisioning HOST application support.

class spsdk.tp.tpconfig.TrustProvisioningConfig(tpdev, info_print)

Bases: object

Trust provisioning support in none trusted environment.

Trust Provisioning Host support class.

Parameters:

tpdev (TpDevInterface) – [description]
info_print (Callable[[str], None]) – [description]

get_counters(timeout=60)

Seal the provisioning device.

Return type:: None

seal(timeout=60)

Seal the provisioning device.

Return type:: None

setup(timeout=60)

Setup the provisioning device.

Return type:: None

upload(user_config, user_config_dir=None, timeout=60)

Upload the user data into the provisioning device.

Return type:: None

TP Host

Trust Provisioning HOST application support.

class spsdk.tp.tphost.TrustProvisioningHost(tpdev, tptarget, info_print)

Bases: object

Trust provisioning support in none trusted environment.

Trust Provisioning Host support class.

Parameters:

tpdev (TpDevInterface) – TP device instance
tptarget (TpTargetInterface) – TP target instance
info_print (Callable[[str], None]) – Method for printing messages

check_audit_log_owner(audit_log, timeout=60)

Check if this TP Device’s ID is present in the audit log.

Return type:: None

create_audit_log_record(data, audit_log)

Create an audit log record out of data representing ISP_WRAP_DATA container.

Return type:: None

do_provisioning(family, audit_log, prov_fw=None, product_fw=None, timeout=60, save_debug_data=False)

Do provisioning process.

Parameters:

family (str) – Chip family
audit_log (str) – Path to audit log
prov_fw (Optional[bytes]) – Use own provisioning firmware, defaults to None
product_fw (Optional[bytes]) – Load also the final product application, defaults to None
timeout (int) – The timeout of operation is seconds.
save_debug_data (bool) – Save transmitted data in CWD for debugging purposes

Raises:

SPSDKTpError – Device family is not supported
SPSDKTpError – Error during trust-provisioning operation

Return type:

None

erase_memory(family, database)

Erase part(s) of flash memory if needed.

Return type:: None

get_counters(timeout=60)

Seal the provisioning device.

Return type:: None

get_tp_response(response_file, timeout=60, challenge=None, oem_key_flags=0, save_debug_data=False)

Retrieve TP_RESPONSE from the target.

Parameters:

response_file (str) – Path where to store TP_RESPONSE
timeout (int) – The timeout of operation is seconds, defaults to 60
challenge (Optional[bytes]) – Challenge for the response, defaults to None
oem_key_flags (int) – OEM Key flags used for generating the response, defaults to 0
save_debug_data (bool) – Save transmitted data in CWD for debugging purposes

Raises:

SPSDKTpError – Failure to retrieve the response

Return type:

None

load_provisioning_fw(prov_fw, family, timeout=60, database=None, skip_test=True, keep_target_open=True, skip_usb_enumeration=False)

Method loads the provisioning firmware into device.

Parameters:

prov_fw (bytes) – Provisioning Firmware data
family (str) – Chip family
timeout (int) – Timeout for loading provisioning firmware operation in seconds.
database (Optional[Database]) – Database of all supported devices (automatic lookup if not specified)
skip_test (bool) – Skip test for checking that OEM Provisioning Firmware booted-up
keep_target_open (bool) – Keep target device open
skip_usb_enumeration (bool) – Skip USB enumeration after loading the Provisioning firmware

Raises:

SPSDKTpError – The Provisioning firmware doesn’t boot

Return type:

None

update_cfpa_page(family, database)

Update CFPA page according to chip family.

Return type:: None

static verify_extract_log(audit_log, audit_log_key, destination=None, skip_nxp=False, skip_oem=False, cert_index=None, encoding=SPSDKEncoding.PEM, max_processes=None, info_print=<function TrustProvisioningHost.<lambda>>, force_rewrite=True)

Verifying audit log with given key (public/private).

Parameters:

audit_log (str) – Path to audit log
audit_log_key (str) – Path to public/private key for verification
destination (Optional[str]) – Path to destination directory for extracted certificates
skip_nxp (bool) – Skip extracting the NXP Devattest certificates
skip_oem (bool) – Skip extracting the OEM x509 Devattest certificates
cert_index (Optional[int]) – Select single OEM certificate to extract, default None = all certificates
encoding (SPSDKEncoding) – Certificate encoding, defaults to SPSDK_Encoding.PEM
max_processes (Optional[int]) – Maximum number od parallel process to use, defaults to CPU count
info_print (Callable[[str], None]) – Method for printing messages
force_rewrite (bool) – Skip checking for empty destination directory and rewrite existing content

Raises:

SPSDKTpError – Audit log record or chain is invalid

Return type:

AuditLogCounter

TP Utils

Trust Provisioning utilities.

spsdk.tp.utils.get_device_data(key, family=None)

Return an entry from the Trust Provisioning device database.

Return type:: Union[str, int, bool]

spsdk.tp.utils.get_supported_devices()

Return list of supported devices for Trust Provisioning.

Return type:: List[str]

spsdk.tp.utils.get_tp_device_class(name)

Return class of TP device interface by name.

Parameters:: name (str) – Name of the interface.
Return type:: Type[TpDevInterface]
Returns:: TP device interface.

spsdk.tp.utils.get_tp_device_types()

Return list of supported TP device types.

Return type:: List[str]

spsdk.tp.utils.get_tp_devices(tpdev=None, settings=None)

Return a list of active TP Devices fulfilling criteria in ‘settings’.

This functions attempts to open/close the device, please mind possible side-effects.

Parameters:

tpdev (Optional[str]) – Name of TP Device interface, defaults to None
settings (Optional[dict]) – Settings for TP Target, defaults to None

Return type:

List[TpDevInterface]

Returns:

List of active TP Devices

spsdk.tp.utils.get_tp_target_class(name)

Return class of TP target interface by name.

Parameters:: name (str) – Name of the interface.
Return type:: Type[TpTargetInterface]
Returns:: TP target interface.

spsdk.tp.utils.get_tp_target_types()

Return list of supported TP targets.

Return type:: List[str]

spsdk.tp.utils.get_tp_targets(tptarget=None, settings=None)

Return a list of active TP Targets fulfilling criteria in ‘settings’.

This functions attempts to open/close the device, please mind possible side-effects.

Parameters:

tptarget (Optional[str]) – Name of TP Target interface, defaults to None
settings (Optional[dict]) – Settings for TP Target, defaults to None

Return type:

List[TpTargetInterface]

Returns:

List is active TP Targets

spsdk.tp.utils.scan_tp_devices(tpdev=None, settings=None)

The function scans the TP devices on system.

Parameters:

tpdev (Optional[str]) – Selection of one type of TP device, defaults to None (scan all supported).
settings (Optional[dict]) – Additional settings to setup interface, defaults to {}.

Return type:

List[TpIntfDescription]

Returns:

List of active TP device descriptors.

Raises:

SPSDKError – Invalid value of parameter.

spsdk.tp.utils.scan_tp_targets(tptarget=None, settings=None)

The function scans the TP targets on system.

Parameters:

tptarget (Optional[str]) – Selection of one type of TP target, defaults to None (scan all supported).
settings (Optional[dict]) – Additional settings to setup interface, defaults to {}.

Return type:

List[TpIntfDescription]

Returns:

List of active TP devices.

Raises:

SPSDKError – Invalid value of parameter.

spsdk.tp.utils.single_tp_device_adapter()

Return True if there’s only one TP device adapter.

Return type:: bool

spsdk.tp.utils.single_tp_target_adapter()

Return True if there’s only one TP target adapter.

Return type:: bool