Trust Provisioning API

Contents

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:

AuthenticationType

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:

AuthenticationType

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(tag, label, description=None)#

Bases: SpsdkEnum

Destination type setting for DataDestinationEntry.

MEMORY = (0, 'memory', 'Address in memory')#
OTP = (2, 'otp', 'Index in OTP')#
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(tag, label, description=None)#

Bases: SpsdkEnum

Enumeration of all supported Entry types.

AUTHENTICATION = (192, 'authentication', 'Authentication Entry')#
DESTINATION = (176, 'destination', 'Destination Entry')#
STANDARD = (160, 'standard', 'Standard Entry')#
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: NamedTuple

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: NamedTuple

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, 'aes-cmac', 'AES-CMAC')#

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, 'none', 'None')#

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(tag, label, description=None)#

Bases: SpsdkEnum

Available Authentication types.

AES_CMAC = (16, 'aes-cmac', 'AES-CMAC')#
CRC32 = (254, 'crc32', 'CRC32')#
ECDSA_256 = (32, 'ecdsa-256', 'ECDSA / P-256 / SHA-256')#
HMAC_256 = (17, 'hmac-256', 'HMAC / SHA-256')#
NONE = (0, 'none', 'None')#
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, 'crc32', 'CRC32')#

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, 'ecdsa-256', 'ECDSA / P-256 / SHA-256')#

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, 'sha256', 'SHA256')#
TYPE = (17, 'hmac-256', 'HMAC / SHA-256')#

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

  • 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: '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_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

Contents