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:
spsdk.tp.data_container.data_container.BaseElement
TrustProvisioning Data Container.
Initialize the container.
- add_auth_entry(auth_type, key)
Add the final data authentication entry.
- Parameters
auth_type (
AuthenticationType
) – Authentication Typekey (
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_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
- 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:
spsdk.tp.data_container.data_container.BaseElement
Main container header.
Initialize Container Header with version information.
- Parameters
major (
int
) – major version, defaults to 1minor (
int
) – minor version, defaults to 0patch (
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:
spsdk.tp.data_container.data_container.DataEntry
Final Data entry used for integrity check.
Initialize Standard Data Entry.
- Parameters
payload (
bytes
) – Data entry payloadpayload_type (
int
) – Data entry typeextra (
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:
spsdk.tp.data_container.data_container.DataAuthenticationEntry
Final Data entry V2 used for integrity check.
Initialize Standard Data Entry.
- Parameters
payload (
bytes
) – Data entry payloadpayload_type (
int
) – Data entry typeextra (
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:
spsdk.tp.data_container.data_container.DataEntry
Data entry including destination information.
Initialize data entry with destination record.
- Parameters
payload (
bytes
) – Data entry payloadpayload_type (
int
) – Data entry typedestination (
int
) – Destination memory address/OTP indexdestination_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).
- Return type
int
- class spsdk.tp.data_container.data_container.DataEntry(payload, payload_type, extra=0)
Bases:
spsdk.tp.data_container.data_container.BaseElement
Standard data entry.
Initialize Standard Data Entry.
- Parameters
payload (
bytes
) – Data entry payloadpayload_type (
int
) – Data entry typeextra (
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).
- Return type
int
- class spsdk.tp.data_container.data_container.DestinationHeader(destination, destination_type)
Bases:
spsdk.tp.data_container.data_container.BaseElement
Header used to store destination information.
Initialize the destination record.
- Parameters
destination (
int
) – Destination addressdestination_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:
spsdk.utils.easy_enum.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:
spsdk.tp.data_container.data_container.BaseElement
Common Entry header for all entry types.
Initialize Entry header.
- Parameters
tag (
int
) – Tag indicating entry type, see EntryTypepayload_size (
int
) – Size of entry payload, excluding header and paddingpayload_type (
int
) – Type of entry payloadentry_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:
spsdk.utils.easy_enum.Enum
Enumeration of all supported Entry types.
- AUTHENTICATION = 192
- DESTINATION = 176
- STANDARD = 160
Audit log
Module for generating, processing and verifying TP Audit Log.
- class spsdk.tp.data_container.audit_log.AuditLog(iterable=(), /)
Bases:
List
[spsdk.tp.data_container.audit_log.AuditLogRecord
]Full Audit log, List of AuditLogRecords.
- 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
- 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 fileid_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
- 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
- classmethod from_dict(data)
Create AuditLogRecord from a dictionary.
- Return type
- classmethod from_tuple(data)
Create AuditLogRecord from a tuple.
- Return type
- 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.
- Return type
int
- 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:
spsdk.tp.data_container.data_container_auth.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:
spsdk.utils.easy_enum.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:
spsdk.tp.data_container.data_container_auth._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:
spsdk.tp.data_container.data_container_auth.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:
spsdk.tp.data_container.data_container_auth._HMAC
HMAC-256 Authenticator.
- DATA_LEN = 32
Expected length of Authentication code/signature
- HASHER: Optional[spsdk.crypto.hash.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 fromauth_type (
AuthenticationType
) – Type of Authenticatorkey (
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 validatesignature (
bytes
) – Signature/authentication code to validateauth_type (
AuthenticationType
) – Authenticator to usekey (
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 instancetptarget (
TpTargetInterface
) – TP target instanceinfo_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 familyaudit_log (
str
) – Path to audit logprov_fw (
Optional
[bytes
]) – Use own provisioning firmware, defaults to Noneproduct_fw (
Optional
[bytes
]) – Load also the final product application, defaults to Nonetimeout (
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_RESPONSEtimeout (
int
) – The timeout of operation is seconds, defaults to 60challenge (
Optional
[bytes
]) – Challenge for the response, defaults to Noneoem_key_flags (
int
) – OEM Key flags used for generating the response, defaults to 0save_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 datafamily (
str
) – Chip familytimeout (
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-upkeep_target_open (
bool
) – Keep target device openskip_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 logaudit_log_key (
str
) – Path to public/private key for verificationdestination (
Optional
[str
]) – Path to destination directory for extracted certificatesskip_nxp (
bool
) – Skip extracting the NXP Devattest certificatesskip_oem (
bool
) – Skip extracting the OEM x509 Devattest certificatescert_index (
Optional
[int
]) – Select single OEM certificate to extract, default None = all certificatesencoding (
SPSDKEncoding
) – Certificate encoding, defaults to SPSDK_Encoding.PEMmax_processes (
Optional
[int
]) – Maximum number od parallel process to use, defaults to CPU countinfo_print (
Callable
[[str
],None
]) – Method for printing messagesforce_rewrite (
bool
) – Skip checking for empty destination directory and rewrite existing content
- Raises
SPSDKTpError – Audit log record or chain is invalid
- Return type
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 Nonesettings (
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 Nonesettings (
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