Image Module API

Returns:

BootImg3a object

property plg: bool#: PLG.

class spsdk.image.images.BootImg3b(address=0, offset=1024, version=67)#

Bases: BootImgBase

IMX Boot Image v3b.

Initialize boot image object.

Parameters:

address (int) – The start address of img in target memory
offset (int) – The IVT offset
version (int) – The version of boot img format

APP_ALIGN = 4608#

COUNT_OF_CONTAINERS = 2#

CSF_SIZE = 8192#

HEAD_SIZE = {1024: 50176, 4096: 5120}#

IMG_AUTO_ALIGN = 16#

IMG_TYPE_CSF = 1#

IMG_TYPE_DATA = 4#

IMG_TYPE_EXEC = 3#

IMG_TYPE_SCD = 2#

INITIAL_LOAD_ADDR_AP_ROM = 1114112#

INITIAL_LOAD_ADDR_FLEXSPI = 134217728#

INITIAL_LOAD_ADDR_SCU_ROM = 536928256#

PADDING_VAL = 0#

SCFW_FLAGS_A53 = 20267028#

SCFW_FLAGS_A72 = 20267109#

SCFW_FLAGS_M4_0 = 4870498#

SCFW_FLAGS_M4_1 = 5198499#

SCFW_FLAGS_SCFW = 1#

SECTOR_SIZE = 512#

add_image(data, img_type=EnumAppType(tag=4, label='APP', description=None), address=0)#

Add specific image into the main boot image.

Parameters:

data (bytes) – Raw data of image
img_type (EnumAppType) – Type of image
address (int) – address in RAM

Raises:

Exception – raised SCFW is not defined before SCD
Exception – raised when there is unknown image type

Return type:

None

property bdt: list[SegBDS3b]#: BDT.

property csf: SegCSF#: CSF.

export()#

Export.

Return type:: bytes

property ivt: list[SegIVT3b]#: IVT.

classmethod parse(stream, step=256, size=None)#

Parse image from stream buffer or bytes array.

Parameters:

stream (Union[bytes, bytearray, BufferedReader, BytesIO]) – The stream buffer or bytes array
step (int) – Image searching step
size (Optional[int]) – parsing size

Raises:

SPSDKError – When the value is incorrect
SPSDKError – If there is not an i.MX Boot Image

Return type:

Returns:

BootImg3b object

property plg: bool#: PLG.

class spsdk.image.images.BootImg4(address=0, offset=1024)#

Bases: BootImgBase

i.MX Boot Image v4.

Initialize boot image object.

Parameters:

address (int) – The start address of image in target memory
offset (int) – The image offset

add_image(data, img_type, address)#

Add image.

Raises:: NotImplementedError – Not yet implemented
Return type:: None

export()#

Export.

Return type:: bytes

classmethod parse(stream, step=256, size=None)#

Parse image from stream buffer or bytes array.

Parameters:

stream (Union[bytes, bytearray, BufferedReader, BytesIO]) – The stream buffer or bytes array
step (int) – Image searching step
size (Optional[int]) – parsing size

Return type:

Returns:

BootImg4 object

Raises:

SPSDKError – Raised when the value type is incorrect
SPSDKError – If there is not an i.MX Boot Image

class spsdk.image.images.BootImg8m(address=0, offset=1024, version=65, plugin=False)#

Bases: BootImgBase

IMX Boot Image.

Initialize boot image object.

Parameters:

address (int) – The start address of img in target memory
offset (int) – The IVT offset
version (int) – The version of boot img format
plugin (bool) – if plugin

APP_ALIGN = 4096#

CSF_SIZE = 8192#

HEAD_SIZE = {256: 768, 1024: 3072}#

add_image(data, img_type=EnumAppType(tag=4, label='APP', description=None), address=0)#

Add specific image into the main boot image.

Parameters:

data (bytes) – Raw data of img
img_type (EnumAppType) – Type of img
address (int) – address in RAM

Raises:

Exception – raised when data type is unknown

Return type:

None

property app: SegAPP#: APP.

property bdt: SegBDT#: BDT.

property csf: SegCSF#: CSF.

export()#

Export Image as bytes array.

Return type:: bytes
Returns:: bytes

property ivt: SegIVT2#: IVT.

classmethod parse(stream, step=256, size=None)#

Parse image from stream buffer or bytes array.

Parameters:

stream (Union[bytes, bytearray, BufferedReader, BytesIO]) – The stream buffer or bytes array
step (int) – Image searching step
size (Optional[int]) – parsing size

Raises:

SPSDKError – Raised when the value type is incorrect
SPSDKError – Raised when there is not an i.MX Boot Image

Return type:

Returns:

BootImg2 object

property plugin: bool#: Plugin.

property size: int#: Size of IMX Boot Image.

property version: int#: Version of IMX Boot Image.

class spsdk.image.images.BootImgBase(address, offset)#

Bases: object

IMX Boot Image Base.

Initialize boot image object.

Parameters:

address (int) – The start address of img in target memory
offset (int) – The IVT offset

add_image(data, img_type, address)#

Add specific image into the main boot image.

Parameters:

data (bytes) – Raw binary data of the application image
img_type (EnumAppType) – see EnumAppType
address (int) – TBD

Raises:

NotImplementedError – Derived class has to implement this method

Return type:

None

property dcd: SegDCD | None#: Device configuration data (DCD) segment; None if not assigned.

export()#

Binary representation of the instance (serialization).

Raises:: NotImplementedError – Derived class has to implement this method
Return type:: bytes

classmethod parse(stream, step=256, size=None)#

Parse of IMX Boot Image Base.

Raises:: NotImplementedError – Derived class has to implement this method
Return type:: BootImgBase

class spsdk.image.images.BootImgRT(address, offset=4096, version=64, plugin=False)#

Bases: BootImgBase

IMX Boot Image v2.

Initialize boot image object.

Parameters:

address (int) – The start address of img in target memory, where the image is executed
offset (int) – The IVT offset; use IVT_OFFSET_NOR_FLASH for NOR-FLASH or IVT_OFFSET_OTHER
version (int) – The version of boot img format; default value should be used
plugin (bool) – Do not use; see self.plugin property

Raises:

SPSDKError – If invalid IVT offset
SPSDKError – If invalid version
SPSDKError – If Plugin is not supported

BDT_SIZE = 32#

BEE_OFFSET = 1024#

CSF_SIZE = 8192#

DEK_SIZE = 512#

FCB_OFFSETS = (0, 1024)#

IVT_OFFSETS = (0, 1024, 3072, 4096)#

IVT_OFFSET_NOR_FLASH = 4096#

IVT_OFFSET_OTHER = 1024#

IVT_OFFSET_OTHER2 = 3072#

NON_XIP_APP_OFFSET = 4096#

VERSIONS = (64, 65, 66, 67)#

XIP_APP_OFFSET = 8192#

XMCD_IVT_OFFSET = 64#

add_csf_encrypted(version, srk_table, src_key_index, csf_cert, csf_priv_key, img_cert, img_priv_key)#

Add CSF with image encryption.

Before calling, application image and address must be assigned

Parameters:

version (int) – CSF segment version
srk_table (SrkTable) – SRK table of root certificates; must contain min 1, max 4 certificates
src_key_index (int) – index of selected SRK key used for authentication, 0..srk_table.len - 1
csf_cert (bytes) – CSF certificate
csf_priv_key (PrivateKeyRsa) – CSF private key
img_cert (bytes) – IMG certificate
img_priv_key (PrivateKeyRsa) – IMG private key

Raises:

SPSDKError – If invalid length of srk table
SPSDKError – If invalid index of srk table
SPSDKError – If application data is not present

Return type:

None

add_csf_standard_auth(version, srk_table, src_key_index, csf_cert, csf_priv_key, img_cert, img_priv_key)#

Add CSF with standard authentication.

Before calling, application image and address must be assigned

Parameters:

version (int) – CSF segment version
srk_table (SrkTable) – SRK table of root certificates; must contain min 1, max 4 certificates
src_key_index (int) – index of selected SRK key used for authentication
csf_cert (bytes) – CSF certificate
csf_priv_key (PrivateKeyRsa) – CSF private key
img_cert (bytes) – IMG certificate
img_priv_key (PrivateKeyRsa) – IMG private key; decrypted binary data in PEM format

Raises:

SPSDKError – If invalid length of srk table
SPSDKError – If invalid index of selected SRK key
SPSDKError – If application data not present

Return type:

None

add_dcd_bin(data)#

Add DCD binary data.

Parameters:

data (bytes) – DCD binary data to be added

Raises:

SPSDKError – If DCD is already present
SPSDKError – If DCD is not enabled

Return type:

None

add_image(data, img_type=EnumAppType(tag=4, label='APP', description=None), address=-1, dek_key=None, nonce=None)#

Add specific image into the main boot image.

Parameters:

data (bytes) – Raw data of img
img_type (EnumAppType) – value must be EnumAppType.APP, no other options supported in this class
address (int) – start address of the application (entry point); Use -1 to detect the address from the image
dek_key (Optional[bytes]) – key for AES128 image HAB encryption [16 bytes], - use None for non-encrypted images; - use empty bytes to create random key (recommended) - use fixed key for testing to produce stable output
nonce (Optional[bytes]) – initial vector for AEAD HAB encryption, if not specified random value is used; For non-encrypted image use None The parameter should be used only for testing to produce stable output

Raises:

ValueError – if any parameter is not valid
SPSDKError – If invalid image type
SPSDKError – If image was already added
SPSDKError – If entry_addr not detected from image, must be specified explicitly
SPSDKError – If hab is not encrypted
SPSDKError – If nonce is not empty

Return type:

None

static aead_nonce_len(app_data_len)#

Nonce len for AEAD encryption.

Note: The code was taken from CST tool

Return type:: int

property app: SegAPP#: Segment with application image.

property app_offset: int#

Returns:: offset in the binary image, where the application starts.

Please mind: the offset include FCB block (even the FCB block is not exported) The offset is 0x2000 for XIP images and 0x1000 for non-XIP images

property bdt: SegBDT#: Boot Data Table.

property bee: SegBEE#

Returns:: BEE segment that contains configuration of encrypted XIP.

By default, BEE segment is empty. PRDB regions may be specified only for XIP images.

property bee_encrypted: bool#: True if BEE encrypted XIP image (with SW keys); False otherwise; see also hab_encrypted.

property csf: SegCSF | None#: Command Sequence File (CSF), signature block for Secure Boot.

property decrypted_app_data: bytes#

Return decrypted binary application data.

Note: dek key, mac and nonce must be assigned for decryption :raises SPSDKError: If application not present :raises SPSDKError: If invalid length of application data :raises SPSDKError: If Mac or nonce or dek not present

property dek_img_offset: int#: Offset of the DEK key in the image; -1 if DEK key address is available (see dek_ram_address).

property dek_key: bytes | None#: DEK key for encrypted images; None for non-encrypted images.

property dek_ram_address: int#

Address of the DEK key in the RAM memory retrieved from the corresponding command.

-1 if the image does not contain command for DEK key installation

property enabled_csf: SegCSF | None#: Enabled Command Sequence File (CSF) segment; None if CSF is not defined or it is not enabled.

export(zulu=datetime.datetime(2024, 10, 10, 11, 36, 35, 145145, tzinfo=datetime.timezone.utc))#

Export image as bytes array.

Parameters:

zulu (datetime) – optional UTC datetime; should be used only if you need fixed datetime for the test Note: the parameter is applied to CSF only, so it is not used for unsigned images

Raises:

SPSDKError – If the image is not encrypted
SPSDKError – If padding is present
SPSDKError – If invalid alignment of application

Return type:

bytes

Returns:

bytes

export_bee()#

Export BEE segment.

Return type:: bytes
Returns:: binary BEE segment
Raises:: SPSDKError – if any BEE region is configured for images not located in the FLASH

export_csf(data, zulu=datetime.datetime(2024, 10, 10, 11, 36, 35, 145135, tzinfo=datetime.timezone.utc))#

Export CSF segment.

Parameters:

data (bytes) – generated binary data used for creating of signature
zulu (datetime) – current UTC datetime

Return type:

bytes

Returns:

binary CFD segment

export_dcd()#

Export DCD segment.

Return type:: bytes
Returns:: binary DCD segment
Raises:: SPSDKError – If DCD padding is not set

export_fcb()#

Export FCB segment.

Return type:: bytes
Returns:: binary FCB segment
Raises:: SPSDKError – If invalid length of data

property fcb: AbstractFCB#: Flash Configuration(Control) Block, binary data; content depends on FLASH type.

static get_app_offset(ivt_offset)#

Return type:: int
Returns:: offset in the binary image, where the application starts.

Please mind: the offset include FCB block (even the FCB block is not exported) The offset is 0x2000 for XIP images and 0x1000 for non-XIP images

Parameters:: ivt_offset (int) – Offset of IVT segment

property hab_encrypted: bool#: True if HAB encrypted; False otherwise; see also bee_encrypted.

property ivt: SegIVT2#: Image Vector Table (IVT) segment.

property ivt_offset: int#: Offset of the Image Vector Table (IVT) in the image.

classmethod parse(stream, step=0, size=None)#

Parse bootable RT image from stream buffer or bytes array.

Parameters:

stream (Union[bytes, bytearray, BufferedReader, BytesIO]) – The stream buffer or bytes array
step (int) – Image searching step (this parameter is not used for RT)
size (Optional[int]) – parsing size; None to parse till the end of the stream

Raises:

SPSDKError – Raised when the value type is incorrect

Return type:

BootImgRT

Returns:

BootImgRT object

property plugin: bool#

Flag whether it is plugin image type; It is not fully supported by SPSDK yet.

Plugin is designed to load a boot image from devices that are not natively supported by boot ROM.

set_flexspi_fcb(data)#

Set FlexSPI external FLASH configuration.

Parameters:: data (Union[bytes, FlexSPIConfBlockFCB]) – FlexSPIConfBlockFCB or binary data representing
Return type:: None

set_xmcd(data)#

Sets the XMCD block.

Return type:: None

property size: int#

Size of the exported binary data.

Please mind, FCB is exported optionally, but it is always included in the size

property version: int#: Version of the image format; must be from BootImgRT.VERSIONS.

property xmcd: SegXMCD | None#: Return the XMCD block.

class spsdk.image.images.KernelImg(address=0, app=None, csf=None, version=65)#

Bases: object

IMX Kernel Image.

Initialize the IMX Kernel Image.

IMAGE_MIN_SIZE = 4096#

property address: int#: Address.

property app: bytes | None#: APP.

property csf: SegCSF#: CSF.

export()#

Export.

Return type:: bytes

property version: int#: Version.

spsdk.image.images.parse(stream, step=256, size=None)#

Common parser for all versions of i.MX boot images.

Parameters:

stream (Union[bytes, bytearray, BufferedReader, BytesIO]) – stream buffer to image
step (int) – Image searching step
size (Optional[int]) – parsing size

Return type:

Returns:

the object of boot image

Raises:

SPSDKError – Raised when the format of string is incorrect
SPSDKError – When not i.MX Boot Image is passed

Image Commands#

Commands for image module.

class spsdk.image.commands.CmdAuthData(flags=EnumAuthDat(tag=0, label='CLR', description='No flags set'), key_index=1, sig_format=EnumCertFormat(tag=197, label='CMS', description='CMS/PKCS#7 signature format'), engine=EnumEngine(tag=0, label='ANY', description='First compatible engine will be selected (no engine configuration parameters are allowed)'), engine_cfg=0, location=0, certificate=None, private_key=None, signature_provider=None)#

Bases: CmdBase

Authenticate data command.

Initialize the Authenticate data command.

append(start_address, size)#

Append of Authenticate data command.

Return type:: None

clear()#

Clear of Authenticate data command.

Return type:: None

property cmd_data_offset: int#: Offset of an additional data (such as signature or MAC, etc) in binary image.

property cmd_data_reference: MAC | Signature | None#

Reference to an additional data (such as certificate, signature, etc).

None if no reference was assigned;
Value type is command-specific

property engine: EnumEngine#: Engine.

export()#

Export to binary form (serialization).

Return type:: bytes
Returns:: binary representation of the command

property flags: EnumAuthDat#: Flag of Authenticate data command.

property key_index: int#: Key index.

property needs_cmd_data_reference: bool#: Whether the command contains a reference to an additional data.

classmethod parse(data)#

Convert binary representation into command (deserialization from binary data).

Parameters:: data (bytes) – being parsed
Return type:: Self
Returns:: parse command

parse_cmd_data(data)#

Parse additional command data from binary data.

Parameters:: data (bytes) – to be parsed
Return type:: Union[MAC, Signature]
Returns:: parsed data object; command-specific: Signature or MAC
Raises:: ExpectedSignatureOrMACError – if unsupported data object is provided

pop(index)#

Pop of Authenticate data command.

Return type:: tuple[int, int]

property signature: MAC | Signature | None#: Signature referenced by location attribute.

update_signature(zulu, data, base_data_addr=4294967295)#

Update signature.

This method must be called from parent to provide data to be signed

Parameters:

zulu (datetime) – current UTC time+date
data (bytes) – currently generated binary data
base_data_addr (int) – base address of the generated data

Raises:

ValueError – When certificate or private key are not assigned
ValueError – When signatures not assigned explicitly
SPSDKError – If incorrect start address
SPSDKError – If incorrect end address
SPSDKError – If incorrect length

Return type:

bool

Returns:

True if length of the signature was unchanged, as this may affect content of the CSF section (pointer to data);

class spsdk.image.commands.CmdBase(tag, param, length=None)#

Bases: BaseClass

Base class for all commands.

Constructor.

Parameters:

tag (CmdTag) – command tag
param (int) – TODO
length (Optional[int]) – of the binary command representation, in bytes

property cmd_data_offset: int#: Offset of an additional data (such as certificate, signature, etc) in binary image.

property cmd_data_reference: BaseSecretClass | None#

Reference to a command data (such as certificate, signature, etc).

None if no reference was assigned; Value type is command-specific

export()#

Export to binary form (serialization).

Return type:: bytes
Returns:: binary representation of the command

property needs_cmd_data_reference: bool#

Whether the command needs a reference to an additional data.

If returns True, the following methods must be implemented: - cmd_data_offset - cmd_data_reference

classmethod parse(data)#

Convert binary representation into command (deserialization from binary data).

Parameters:: data (bytes) – being parsed
Return type:: Self
Returns:: parse command
Raises:: NotImplementedError – Derived class has to implement this method

parse_cmd_data(data)#

Parse additional command data from binary data.

Parameters:: data (bytes) – to be parsed
Raises:: SPSDKError – If cmd_data is not supported by the command
Return type:: Any

property size: int#: Size of command.

property tag: int#: Command tag.

class spsdk.image.commands.CmdCheckData(numbytes=4, ops=EnumCheckOps(tag=1, label='ALL_SET', description='All bits set'), address=0, mask=0, count=None)#

Bases: CmdBase

Check data command.

Initialize the check data command.

Parameters:

numbytes (int) – number of bytes
ops (EnumCheckOps) – type of operation
address (int) – list of tuples: address and value
mask (int) – mask value
count (Optional[int]) – count value

Raises:

SPSDKError – If incorrect number of bytes
SPSDKError – If incorrect operation

export()#

Export to binary form (serialization).

Return type:: bytes
Returns:: binary representation of the command

property num_bytes: int#: Number of bytes.

property ops: EnumCheckOps#: Operation of Check data command.

classmethod parse(data)#

Convert binary representation into command (deserialization from binary data).

Parameters:: data (bytes) – being parsed
Return type:: Self
Returns:: parse command

class spsdk.image.commands.CmdInitialize(engine=EnumEngine(tag=0, label='ANY', description='First compatible engine will be selected (no engine configuration parameters are allowed)'), data=None)#

Bases: CmdBase

Initialize command.

Initialize the initialize command.

append(value)#

Appending of Initialize command.

Raises:: SPSDKError – If value out of range
Return type:: None

clear()#

Clear of Initialize command.

Return type:: None

property engine: EnumEngine#: Engine.

export()#

Export to binary form (serialization).

Return type:: bytes
Returns:: binary representation of the command

classmethod parse(data)#

Convert binary representation into command (deserialization from binary data).

Parameters:: data (bytes) – being parsed
Return type:: Self
Returns:: parse command
Raises:: SPSDKError – If incorrect length of data

pop(index)#

Pop of Initialize command.

Return type:: int
Returns:: value from the index
Raises:: SPSDKError – If incorrect length of data

class spsdk.image.commands.CmdInstallKey(flags=EnumInsKey(tag=0, label='CLR', description='No flags set'), cert_fmt=EnumCertFormat(tag=3, label='SRK', description='SRK certificate format'), hash_alg=EnumAlgorithm(tag=0, label='ANY', description='Algorithm type ANY'), src_index=0, tgt_index=0, location=0)#

Bases: CmdBase

Install key command.

Constructor.

Parameters:

flags (EnumInsKey) – from EnumInsKey
cert_fmt (EnumCertFormat) – format of the certificate; key authentication protocol
hash_alg (EnumAlgorithm) – hash algorithm
src_index (int) – source key (verification key, KEK) index
tgt_index (int) – target key index
location (int) – start address of an additional data such as KEY to be installed; Typically it is relative to CSF start; Might be absolute for DEK key

property certificate_format: EnumCertFormat#: Certificate format.

property certificate_ref: CertificateImg | SrkTable | None#: Corresponding certificate referenced by key-location.

property cmd_data_offset: int#: Offset of an additional data (such as certificate, signature, etc) in binary image.

property cmd_data_reference: CertificateImg | SrkTable | None#

Reference to an additional data (such as certificate, signature, etc).

None if no reference was assigned; Value type is command-specific

export()#

Export to binary form (serialization).

Return type:: bytes
Returns:: binary representation of the command

property flags: EnumInsKey#: Flags.

property hash_algorithm: EnumAlgorithm#: Hash algorithm.

property needs_cmd_data_reference: bool#: Whether the command contains a reference to an additional data.

classmethod parse(data)#

Convert binary representation into command (deserialization from binary data).

Parameters:: data (bytes) – being parsed
Return type:: Self
Returns:: parse command

parse_cmd_data(data)#

Parse additional command data from binary data.

Parameters:: data (bytes) – to be parsed
Return type:: Union[CertificateImg, SrkTable, None]
Returns:: parsed data object; command-specific: certificate or SrkTable to be installed

property source_index: int#

Source key (verification key, KEK) index.

For SRK, it is index of the SRK key (0-3)
For other keys it is index of previously installed target key, typically 0

property target_index: int#: Target key index.

class spsdk.image.commands.CmdNop(param=0)#

Bases: CmdBase

Nop command.

Initialize the nop command.

classmethod parse(data)#

Convert binary representation into command (deserialization from binary data).

Parameters:: data (bytes) – being parsed
Return type:: Self
Returns:: parse command

class spsdk.image.commands.CmdSet(itm=EnumItm(tag=3, label='ENG', description='Preferred engine for a given algorithm'), hash_alg=EnumAlgorithm(tag=0, label='ANY', description='Algorithm type ANY'), engine=EnumEngine(tag=0, label='ANY', description='First compatible engine will be selected (no engine configuration parameters are allowed)'), engine_cfg=0)#

Bases: CmdBase

Set command.

Initialize the set command.

property engine: EnumEngine#: Engine plugin tags.

export()#

Export to binary form (serialization).

Return type:: bytes
Returns:: binary representation of the command

property hash_algorithm: EnumAlgorithm#: Type of hash algorithm.

property itm: EnumItm#: Item of Set command.

classmethod parse(data)#

Convert binary representation into command (deserialization from binary data).

Parameters:: data (bytes) – being parsed
Return type:: Self
Returns:: parse command

class spsdk.image.commands.CmdUnlock(engine=EnumEngine(tag=0, label='ANY', description='First compatible engine will be selected (no engine configuration parameters are allowed)'), features=0, uid=0)#

Generic unlock engine command.

Constructor.

Parameters:

engine (EnumEngine) – to be unlocked
features (int) – mask of features to use by the engine
uid (int) – Unique ID (if needed)

class spsdk.image.commands.CmdUnlockAbstract(engine=EnumEngine(tag=0, label='ANY', description='First compatible engine will be selected (no engine configuration parameters are allowed)'), features=0, uid=0)#

Bases: CmdBase, ABC

Abstract unlock engine command; the command depends on engine type.

Constructor.

Parameters:

engine (EnumEngine) – to be unlocked
features (Union[int, SpsdkEnum]) – engine specific features
uid (int) – Unique ID required by some engine/feature combinations

property engine: EnumEngine#

Engine to be unlocked.

The term engine denotes a peripheral involved in one or more of the following functions: - cryptographic computation - security state management - security alarm handling - access control

export()#

Export to binary form (serialization).

Return type:: bytes
Returns:: binary representation of the command

static need_uid(engine, features)#

Return True if given Engine and Feature requires UID.

Return type:: bool

classmethod parse(data)#

Convert binary representation into command (deserialization from binary data).

Parameters:: data (bytes) – being parsed
Return type:: Self
Returns:: Unlock command

class spsdk.image.commands.CmdUnlockCAAM(features=0)#

Command Unlock for Cryptographic Acceleration and Assurance Module .

Initialize.

Parameters:: features (Union[int, UnlockCAAMFeatures]) – mask of FEATURE_UNLOCK_x constants, defaults to 0

FEATURES#: alias of UnlockCAAMFeatures

property unlock_mfg: bool#: Leave Zero is able Master Key write unlocked.

property unlock_mid: bool#: Leave Job Ring and DECO master ID registers unlocked.

property unlock_rng: bool#: Leave RNG un-instantiated.

class spsdk.image.commands.CmdUnlockOCOTP(features=0, uid=0)#

Command Unlock for On-Chip One-time programable memory (fuses).

Initialize.

Parameters:

features (Union[int, UnlockOCOTPFeatures]) – mask of FEATURE_UNLOCK_x constants, defaults to 0
uid (int) – Unique ID required by some engine/feature combinations

FEATURES#: alias of UnlockOCOTPFeatures

property unlock_csc: bool#: Leave SCS register unlocked.

property unlock_fld_rtn: bool#: Leave Field Return activation unlocked.

property unlock_jtag: bool#: Unlock JTAG using SCS HAB_JDE bit.

property unlock_srk_rvk: bool#: Leave SRK revocation unlocked.

class spsdk.image.commands.CmdUnlockSNVS(features=0)#

Command Unlock Secure Non-Volatile Storage (SNVS) Engine.

Constructor.

Parameters:: features (Union[int, UnlockSNVSFeatures]) – mask of FEATURE_UNLOCK_* constants

FEATURES#: alias of UnlockSNVSFeatures

property unlock_lp_swr: bool#: Leave LP SW reset unlocked.

property unlock_zmk_write: bool#: Leave Zero is able Master Key write unlocked.

class spsdk.image.commands.CmdWriteData(numbytes=4, ops=EnumWriteOps(tag=0, label='WRITE_VALUE', description='Write value'), data=None)#

Bases: CmdBase

Write data command.

Initialize Write Data command.

Parameters:

numbytes (int) – number of bytes. Must be value: 1, 2 or 4
ops (EnumWriteOps) – type of write operation
data (Optional[Iterable[tuple[int, int]]]) – list of tuples: address and value

Raises:

SPSDKError – When incorrect number of bytes
SPSDKError – When incorrect type of operation

append(address, value)#

Append of Write data command.

Return type:: None

clear()#

Clear of Write data command.

Return type:: None

export()#

Export to binary form (serialization).

Return type:: bytes
Returns:: binary representation of the command

property num_bytes: int#: Number of bytes being written by the command.

property ops: EnumWriteOps#: Type of write operation.

classmethod parse(data)#

Convert binary representation into command (deserialization from binary data).

Parameters:: data (bytes) – being parsed
Return type:: Self
Returns:: parse command

pop(index)#

Pop of Write data command.

Return type:: list[int]

class spsdk.image.commands.EnumAuthDat(tag, label, description=None)#

Bases: SpsdkEnum

Flags for Authenticate Data commands.

ABS = (1, 'ABS', 'Absolute signature address')#

CLR = (0, 'CLR', 'No flags set')#

class spsdk.image.commands.EnumCAAM(tag, label, description=None)#

Bases: SpsdkEnum

CAAM Engine Configuration.

DEFAULT = (0, 'DEFAULT')#

DSC_SWAP16 = (128, 'DSC_SWAP16')#

DSC_SWAP8 = (64, 'DSC_SWAP8')#

IN_SWAP16 = (2, 'IN_SWAP16')#

IN_SWAP8 = (1, 'IN_SWAP8')#

OUT_SWAP16 = (16, 'OUT_SWAP16')#

OUT_SWAP8 = (8, 'OUT_SWAP8')#

class spsdk.image.commands.EnumCertFormat(tag, label, description=None)#

Bases: SpsdkEnum

Certificate format tags.

AEAD = (163, 'AEAD', 'Proprietary AEAD MAC format')#

BLOB = (187, 'BLOB', 'SHW-specific wrapped key format')#

CMS = (197, 'CMS', 'CMS/PKCS#7 signature format')#

SRK = (3, 'SRK', 'SRK certificate format')#

X509 = (9, 'X509', 'X.509v3 certificate format')#

class spsdk.image.commands.EnumCheckOps(tag, label, description=None)#

Bases: SpsdkEnum

Enum definition for ‘par’ parameter of Check Data command.

ALL_CLEAR = (0, 'ALL_CLEAR', 'All bits clear')#

ALL_SET = (1, 'ALL_SET', 'All bits set')#

ANY_CLEAR = (2, 'ANY_CLEAR', 'Any bit clear')#

ANY_SET = (3, 'ANY_SET', 'Any bit set')#

class spsdk.image.commands.EnumEngine(tag, label, description=None)#

Bases: SpsdkEnum

Engine plugin tags.

ANY = (0, 'ANY', 'First compatible engine will be selected (no engine configuration parameters are allowed)')#

CAAM = (29, 'CAAM', 'Cryptographic Acceleration and Assurance Module')#

CSU = (10, 'CSU', 'Central Security Unit')#

DCP = (27, 'DCP', 'Data Co-Processor')#

DTCP = (34, 'DTCP', 'DTCP co-processor')#

HDCP = (36, 'HDCP', 'HDCP co-processor')#

OCOTP = (33, 'OCOTP', 'Fuse controller')#

ROM = (54, 'ROM', 'Protected ROM area')#

RTIC = (5, 'RTIC', 'Run-time integrity checker')#

SAHARA = (6, 'SAHARA', 'Crypto accelerator')#

SCC = (3, 'ANY', 'Security controller')#

SNVS = (30, 'SNVS', 'Secure Non-Volatile Storage')#

SRTC = (12, 'SRTC', 'Secure clock')#

SW = (255, 'SW', 'Software engine')#

class spsdk.image.commands.EnumInsKey(tag, label, description=None)#

Bases: SpsdkEnum

Flags for Install Key commands.

ABS = (1, 'ABS', 'Absolute certificate address')#

CFG = (8, 'CFG', 'Key binds to Configuration')#

CID = (64, 'CID', 'Key binds to Caller ID')#

CLR = (0, 'CLR', 'No flags set')#

CSF = (2, 'CSF', 'Install CSF key')#

DAT = (4, 'DAT', 'Key binds to Data Type')#

FID = (16, 'FID', 'Key binds to Fabrication UID')#

HSH = (128, 'HSH', 'Certificate hash present')#

MID = (32, 'MID', 'Key binds to Manufacturing ID')#

class spsdk.image.commands.EnumItm(tag, label, description=None)#

Bases: SpsdkEnum

Engine configuration flags of Set command.

ENG = (3, 'ENG', 'Preferred engine for a given algorithm')#

MID = (1, 'MID', 'Manufacturing ID (MID) fuse locations')#

class spsdk.image.commands.EnumWriteOps(tag, label, description=None)#

Bases: SpsdkEnum

Enum definition for ‘flags’ control flags in ‘par’ parameter of Write Data command.

CLEAR_BITMASK = (2, 'CLEAR_BITMASK', 'Clear bitmask')#

SET_BITMASK = (3, 'SET_BITMASK', 'Set bitmask')#

WRITE_CLEAR_BITS = (1, 'WRITE_CLEAR_BITS', 'Write clear bits')#

WRITE_VALUE = (0, 'WRITE_VALUE', 'Write value')#

exception spsdk.image.commands.ExpectedSignatureOrMACError(desc=None)#

Bases: SPSDKError

CmdAuthData additional data block: expected Signature or MAC object.

Initialize the base SPSDK Exception.

class spsdk.image.commands.UnlockCAAMFeatures(tag, label, description=None)#

Bases: SpsdkEnum

Enum definition for Unlock SNVS features.

MFG = (4, 'MFG', 'Keep manufacturing protection private key in CAAM internal memory.')#

MID = (1, 'MID', 'Leaves Job Ring and DECO master ID registers unlocked')#

RNG = (2, 'RNG', 'Leave RNG uninitialized.')#

class spsdk.image.commands.UnlockOCOTPFeatures(tag, label, description=None)#

Bases: SpsdkEnum

Enum definition for Unlock SNVS features.

FIELD_RETURN = (1, 'FIELD RETURN', 'Leave Field Return activation unlocked.')#

JTAG = (8, 'JTAG', 'Unlock JTAG using SCS HAB_JDE bit.')#

SCS = (4, 'SCS', 'Leave SCS register unlocked.')#

SRK_REVOKE = (2, 'SRK REVOKE', 'Leave SRK revocation unlocked.')#

class spsdk.image.commands.UnlockSNVSFeatures(tag, label, description=None)#

Bases: SpsdkEnum

Enum definition for Unlock SNVS features.

LP_SWR = (1, 'LP SWR', 'Leaves LP SW reset unlocked')#

ZMK_WRITE = (2, 'ZMK WRITE', 'Leaves Zeroisable Master Key write unlocked.')#

spsdk.image.commands.parse_command(data)#

Parse CSF/DCD command.

Parameters:: data (bytes) – binary data to be parsed
Return type:: CmdBase
Returns:: instance of the command
Raises:: SPSDKError – If the command is not valid

Image Headers#

Header.

class spsdk.image.header.CmdHeader(tag, param=0, length=None)#

Bases: Header

Command header.

Constructor.

Parameters:

tag (Union[CmdTag, int]) – command tag
param (int) – TODO
length (Optional[int]) – of the command binary section, in bytes

Raises:

SPSDKError – If invalid command tag

classmethod parse(data, required_tag=None)#

Create Header from binary data.

Parameters:

data (bytes) – binary data to convert into header
required_tag (Optional[int]) – CmdTag, None if not required

Return type:

Self

Returns:

parsed instance

Raises:

SPSDKParsingError – If required header tag does not match
SPSDKError – If invalid tag

property tag: int#: Command tag.

class spsdk.image.header.CmdTag(tag, label, description=None)#

Bases: SpsdkEnum

CSF/DCD Command Tag.

AUT_DAT = (202, 'AUT_DAT', 'Authenticate Data')#

CHK_DAT = (207, 'CHK_DAT', 'Check Data')#

INIT = (180, 'INIT', 'Initialize')#

INS_KEY = (190, 'INS_KEY', 'Install Key')#

NOP = (192, 'NOP', 'No Operation (NOP)')#

SET = (177, 'SET', 'Set')#

UNLK = (178, 'UNLK', 'Unlock')#

WRT_DAT = (204, 'WRT_DAT', 'Write Data')#

class spsdk.image.header.Header(tag=0, param=0, length=None)#

Bases: BaseClass

Header element type.

Constructor.

Parameters:

tag (int) – section tag
param (int) – TODO
length (Optional[int]) – length of the segment or command; if not specified, size of the header is used

Raises:

SPSDKError – If invalid length

FORMAT = '>BHB'#

SIZE = 4#

export()#

Binary representation of the header.

Return type:: bytes

classmethod parse(data, required_tag=None)#

Parse header.

Parameters:

data (bytes) – Raw data as bytes or bytearray
required_tag (Optional[int]) – Check header TAG if specified value or ignore if is None

Return type:

Self

Returns:

Header object

Raises:

SPSDKParsingError – if required header tag does not match

property size: int#: Header size in bytes.

property tag: int#

Returns:: section tag: command tag or segment tag, …

property tag_name: str#: Returns the header’s tag name.

class spsdk.image.header.Header2(tag=0, param=0, length=None)#

Bases: Header

Header element type.

Constructor.

Parameters:

tag (int) – section tag
param (int) – TODO
length (Optional[int]) – length of the segment or command; if not specified, size of the header is used

Raises:

SPSDKError – If invalid length

FORMAT = '<BHB'#

export()#

Binary representation of the header.

Return type:: bytes

classmethod parse(data, required_tag=None)#

Parse header.

Parameters:

data (bytes) – Raw data as bytes or bytearray
required_tag (Optional[int]) – Check header TAG if specified value or ignore if is None

Raises:

SPSDKParsingError – Raises an error if required tag is empty or not valid

Return type:

Self

Returns:

Header2 object

class spsdk.image.header.SegTag(tag, label, description=None)#

Bases: SpsdkEnum

Segments Tag.

BIC1 = (135, 'BIC1', 'Boot Images Container')#

CRT = (215, 'CRT', 'Certificate')#

CSF = (212, 'CSF', 'Command Sequence File Data')#

DCD = (210, 'DCD', 'Device Configuration Data')#

EVT = (219, 'EVT', 'Event')#

IVT2 = (209, 'IVT2', 'Image Vector Table (Version 2)')#

IVT3 = (222, 'IVT3', 'Image Vector Table (Version 3)')#

MAC = (172, 'MAC', 'Message Authentication Code')#

RVT = (221, 'RVT', 'ROM Vector Table')#

SIG = (216, 'SIG', 'Signature')#

SIGB = (144, 'SIGB', 'Signature block')#

WRP = (129, 'WRP', 'Wrapped Key')#

XMCD = (192, 'XMCD', 'External Memory Configuration Data')#

Secret Module#

Commands and responses used by SDP module.

class spsdk.image.secret.BaseSecretClass(tag, version=64)#

Bases: BaseClass

Base SPSDK class.

Constructor.

Parameters:

tag (SegTag) – section TAG
version (int) – format version

property size: int#

Size of the exported binary data.

Raises:: NotImplementedError – Derived class has to implement this method

property version: int#: Format version.

property version_major: int#: Major format version.

property version_minor: int#: Minor format version.

class spsdk.image.secret.CertificateImg(version=64, data=None)#

Certificate structure for bootable image.

Initialize the certificate structure for bootable image.

export()#

Export.

Return type:: bytes

classmethod parse(data)#

Parse.

Return type:: Self

property size: int#: Size of Certificate structure for bootable image.

class spsdk.image.secret.EnumAlgorithm(tag, label, description=None)#

Bases: SpsdkEnum

Algorithm types.

AES = (85, 'AES', 'AES algorithm ID')#

ANY = (0, 'ANY', 'Algorithm type ANY')#

BLOB = (113, 'BLOB', 'SHW-specific key wrap')#

CCM = (102, 'CCM', 'Counter with CBC-MAC')#

CIPHER = (5, 'CIPHER', 'Cipher algorithm type')#

EC = (4, 'EC', 'Elliptic curve arithmetic')#

ECDSA = (39, 'ECDSA', 'NIST ECDSA signature algorithm')#

F = (3, 'F', 'Finite field arithmetic')#

HASH = (1, 'HASH', 'Hash algorithm type')#

MODE = (6, 'MODE', 'Cipher/hash modes')#

PKCS1 = (33, 'PKCS1', 'PKCS#1 RSA signature algorithm')#

SHA1 = (17, 'SHA1', 'SHA-1 algorithm ID')#

SHA256 = (23, 'SHA256', 'SHA-256 algorithm ID')#

SHA512 = (27, 'SHA512', 'SHA-512 algorithm ID')#

SIG = (2, 'SIG', 'Signature algorithm type')#

WRAP = (7, 'WRAP', 'Key wrap algorithm type')#

class spsdk.image.secret.EnumSRK(tag, label, description=None)#

Bases: SpsdkEnum

Entry type in the System Root Key Table.

KEY_HASH = (238, 'KEY_HASH', 'Any key: hash only')#

KEY_PUBLIC = (225, 'KEY_PUBLIC', 'Public key type: data present')#

class spsdk.image.secret.MAC(version=64, nonce_len=0, mac_len=16, data=None)#

Structure that holds initial parameter for AES encryption/decryption.

nonce - initialization vector for AEAD AES128 decryption
mac - message authentication code to verify the decryption was successful

Constructor.

Parameters:

version (int) – format version, should be 0x4x
nonce_len (int) – number of NONCE bytes
mac_len (int) – number of MAC bytes
data (Optional[bytes]) – nonce and mac bytes joined together

AES128_BLK_LEN = 16#

property data: bytes#: NONCE and MAC bytes joined together.

export()#

Export instance into binary form (serialization).

Return type:: bytes
Returns:: binary form

property mac: bytes#: MAC bytes for the encryption/decryption.

property nonce: bytes#: NONCE bytes for the encryption/decryption.

classmethod parse(data)#

Parse binary data and creates the instance (deserialization).

Parameters:: data (bytes) – being parsed
Return type:: Self
Returns:: the instance

property size: int#: Size of binary representation in bytes.

update_aead_encryption_params(nonce, mac)#

Update AEAD encryption parameters for encrypted image.

Parameters:

nonce (bytes) – initialization vector, length depends on image size,
mac (bytes) – message authentication code used to authenticate decrypted data, 16 bytes

Raises:

SPSDKError – If incorrect length of mac
SPSDKError – If incorrect length of nonce
SPSDKError – If incorrect number of MAC bytes”

Return type:

None

exception spsdk.image.secret.NotImplementedSRKCertificate(desc=None)#

Bases: SRKException

This SRK public key algorithm is not yet implemented.

Initialize the base SPSDK Exception.

exception spsdk.image.secret.NotImplementedSRKItem(desc=None)#

Bases: SRKException

This type of SRK table item is not implemented.

Initialize the base SPSDK Exception.

exception spsdk.image.secret.NotImplementedSRKPublicKeyType(desc=None)#

Bases: SRKException

This SRK public key algorithm is not yet implemented.

Initialize the base SPSDK Exception.

exception spsdk.image.secret.SRKException(desc=None)#

Bases: SPSDKError

SRK table processing exceptions.

Initialize the base SPSDK Exception.

class spsdk.image.secret.SecretKeyBlob(mode, algorithm, flag)#

Bases: object

Secret Key Blob.

Initialize Secret Key Blob.

property blob: bytes#: Data of Secret Key Blob.

export()#

Export of Secret Key Blob.

Return type:: bytes

classmethod parse(data)#

Parse of Secret Key Blob.

Return type:: Self

property size: int#: Size of Secret Key Blob.

class spsdk.image.secret.Signature(version=64, data=None)#

Class representing a signature.

Initialize the signature.

property data: bytes#: Signature data.

export()#

Export.

Return type:: bytes

classmethod parse(data)#

Parse.

Return type:: Self

property size: int#: Size of a signature.

class spsdk.image.secret.SrkItem#

Bases: object

Base class for items in the SRK Table, see SrkTable class.

We do not inherit from BaseClass because our header parameter is an algorithm identifier, not a version number.

export()#

Serialization to binary form.

Return type:: bytes
Returns:: binary representation of the instance
Raises:: NotImplementedError – Derived class has to implement this method

classmethod from_certificate(cert)#

Pick up the right implementation of an SRK item.

Return type:: SrkItem

hashed_entry()#

This SRK item should be replaced with an incomplete entry with its digest.

Raises:: NotImplementedError – Derived class has to implement this method
Return type:: SrkItem

classmethod parse(data)#

Pick up the right implementation of an SRK item.

Parameters:

data (bytes) – The bytes array of SRK segment

Return type:

Self

Returns:

SrkItem: One of the SrkItem subclasses

Raises:

NotImplementedSRKPublicKeyType – Unsupported key algorithm
NotImplementedSRKItem – Unsupported tag

sha256()#

Export SHA256 hash of the original data.

Raises:: NotImplementedError – Derived class has to implement this method
Return type:: bytes

property size: int#

Size of the exported binary data.

Raises:: NotImplementedError – Derived class has to implement this method

class spsdk.image.secret.SrkItemEcc(key_size, x_coordinate, y_coordinate, flag=0)#

Bases: SrkItem

ECC public key in SRK Table, see SrkTable class.

Initialize the srk table item.

ECC_KEY_TYPE = {EccCurve.SECP256R1: 75, EccCurve.SECP384R1: 77, EccCurve.SECP521R1: 78}#

property algorithm: int#: Algorithm.

export()#

Export.

Return type:: bytes

property flag: int#: Flag.

classmethod from_certificate(cert)#

Create SrkItemEcc from certificate.

Return type:: SrkItemEcc

hashed_entry()#

This SRK item should be replaced with an incomplete entry with its digest.

Return type:: SrkItemHash

classmethod parse(data)#

Parse SRK table item data.

Parameters:: data (bytes) – The bytes array of SRK segment
Return type:: Self
Returns:: SrkItemEcc: SrkItemEcc object

sha256()#

Export SHA256 hash of the data.

Return type:: bytes

property size: int#: Size of an SRK item.

class spsdk.image.secret.SrkItemHash(algorithm, digest)#

Bases: SrkItem

Hashed stub of some public key.

This is a valid entry of the SRK table, it represents some public key of unknown algorithm. Can only provide its hashed value of itself.

Build the stub entry with public key hash only.

Parameters:

algorithm (int) – int: Hash algorithm, only SHA256 now
digest (bytes) – bytes: Hash digest value

Raises:

SPSDKError – If incorrect algorithm

property algorithm: int#: Hashing algorithm used.

export()#

Export.

Return type:: bytes

hashed_entry()#

This SRK item should be replaced with an incomplete entry with its digest.

Return type:: SrkItemHash

classmethod parse(data)#

Parse SRK table item data.

Parameters:: data (bytes) – The bytes array of SRK segment
Return type:: Self
Returns:: SrkItemHash: SrkItemHash object
Raises:: NotImplementedSRKItem – Unknown tag

sha256()#

Export SHA256 hash of the original data.

Return type:: bytes

property size: int#: Size of an SRK item.

class spsdk.image.secret.SrkItemRSA(modulus, exponent, flag=0)#

Bases: SrkItem

RSA public key in SRK Table, see SrkTable class.

Initialize the srk table item.

property algorithm: int#: Algorithm.

export()#

Export.

Return type:: bytes

property flag: int#: Flag.

classmethod from_certificate(cert)#

Create SRKItemRSA from certificate.

Return type:: SrkItemRSA

hashed_entry()#

This SRK item should be replaced with an incomplete entry with its digest.

Return type:: SrkItemHash

property key_length: int#: Key length of Item in SRK Table.

classmethod parse(data)#

Parse SRK table item data.

Parameters:: data (bytes) – The bytes array of SRK segment
Return type:: Self
Returns:: SrkItemRSA: SrkItemRSA object

sha256()#

Export SHA256 hash of the data.

Return type:: bytes

property size: int#: Size of an SRK item.

class spsdk.image.secret.SrkTable(version=64)#

SRK table.

Initialize SRT Table.

Parameters:: version (int) – format version

append(srk)#

Add SRK item.

Parameters:: srk (SrkItem) – item to be added
Return type:: None

export()#

Export into binary form (serialization).

Return type:: bytes
Returns:: binary representation of the instance

export_fuses()#

SRK items in binary form, see SRK_fuses.bin file.

Return type:: bytes

get_fuse(index)#

Retrieve fuse value for the given index.

Parameters:

index (int) – of the fuse, 0-7

Return type:

int

Returns:

value of the specified fuse; the value is in format, that cane be used as parameter for SDP efuse_read_once or efuse_write_once

Raises:

SPSDKError – If incorrect index of the fuse
SPSDKError – If incorrect length of SRK items

classmethod parse(data)#

Parse of SRK table.

Return type:: Self

property size: int#: Size of SRK table.

Data Segments#

Segments within image module.

class spsdk.image.segments.AbstractFCB#

Bases: BaseSegment

Abstract class, predecessor for all FCB classes.

Constructor.

TAG = b'FCB'#

property enabled: bool#: Whether FCB is enabled. Note: it is not generated to output if disabled.

export()#

Export to binary representation (serialization).

Return type:: bytes
Returns:: binary representation
Raises:: NotImplementedError – Derived class has to implement this method

property space: int#: Return length (in bytes) of the exported data including padding (if any).

class spsdk.image.segments.BaseSegment#

Bases: ABC

Base segment.

Initialize the base segment.

PADDING_VALUE = 0#

export()#

Export interface.

Raises:: NotImplementedError – Derived class has to implement this method
Return type:: bytes

property padding_len: int#: Length of padding data in bytes (zero for no padding).

classmethod parse(data)#

Parse interfaces.

Raises:: NotImplementedError – Derived class has to implement this method
Return type:: Self

property size: int#: Size of base segment.

property space: int#

Return length (in bytes) of the exported data including padding (if any).

Please mind, padding is exported optionally.

class spsdk.image.segments.FlexSPIConfBlockFCB#

Bases: AbstractFCB

Flex SPI configuration block; FCB.

Initialize FlexSPIConfBlockFCB.

FORMAT = '<6BH7I5I4B2I4I6I4H'#

TAG = b'FCFB'#

VERSION = b'V\x01\x00\x00'#

export()#

Export into binary form.

Return type:: bytes
Returns:: binary representation used in the bootable image

export_header()#

Export FCB header info binary form.

Return type:: bytes

classmethod parse(data)#

Parse binary data and creates instance of the class.

Parameters:: data (bytes) – data to be parsed
Return type:: Self
Returns:: instance of the class representing the data
Raises:: SPSDKError – If data are not valid Flex SPI configuration block

property size: int#: Length of the binary exported data without padding.

class spsdk.image.segments.PaddingFCB(size, padding_value=0, enabled=True)#

Bases: AbstractFCB

Padding FCB.

Constructor.

Parameters:

size (int) – of the exported padding
padding_value (int) – byte value used as padding; 0 by default
enabled (bool) – whether enabled

Raises:

SPSDKError – If invalid size of the exported padding
SPSDKError – If invalid padding

export()#

Export to binary form (serialization).

Return type:: bytes
Returns:: binary representation

property size: int#: Return size of the exported data in bytes.

class spsdk.image.segments.SegAPP(data=None)#

Bases: BaseSegment

APP segment.

Initialize APP segment.

Parameters:: data (Optional[bytes]) – application binary data

property data: bytes | None#: Application binary data.

export()#

Export segment as bytes array.

Return type:: bytes
Returns:: bytes

property size: int#: Size of APP segment.

class spsdk.image.segments.SegBDS3a#

Bases: BaseSegment

BDS3a segment.

Initialize BDS3a segment.

FORMAT = '<4L'#

HEADER_SIZE = 16#

IMAGES_MAX_COUNT = 6#

SIZE = 256#

export()#

Export segment as bytes array.

Return type:: bytes
Returns:: bytes

property header_size: int#: Header’s size of BDS3a segment.

classmethod parse(data)#

Parse segment from bytes array.

Parameters:: data (bytes) – The bytes array of BDS3a segment
Return type:: Self
Returns:: SegBDS3a object

property size: int#: Size of BDS3a segment.

class spsdk.image.segments.SegBDS3b#

Bases: BaseSegment

BDS3b segment.

Initialize BDS3b segment.

FORMAT = '<4L'#

HEADER_SIZE = 16#

IMAGES_MAX_COUNT = 4#

SIZE = 240#

export()#

Export segment as bytes array.

Return type:: bytes
Returns:: bytes

property header_size: int#: Size of header of BDS3b segment.

classmethod parse(data)#

Parse segment from bytes array.

Parameters:: data (bytes) – The bytes array of BDS3b segment
Return type:: Self
Returns:: SegBDS3b object

property size: int#: Size of BDS3b segment.

class spsdk.image.segments.SegBDT(app_start=0, app_length=0, plugin=0)#

Bases: BaseSegment

Boot Data Table segment.

Initialize BDT segment.

Parameters:

app_start (int) – first address of the application
app_length (int) – length of the application
plugin (int) – 0 .. 2

FORMAT = '<3L'#

SIZE = 12#

export()#

Export segment as bytes array.

Return type:: bytes
Returns:: bytes

classmethod parse(data)#

Parse segment from bytes array.

Parameters:: data (bytes) – The bytes array of BDT segment
Return type:: Self
Returns:: SegBDT object

property plugin: int#: Plugin.

property size: int#: Size of the exported binary data (without padding).

class spsdk.image.segments.SegBEE(regions, max_facs=3)#

Bases: BaseSegment

BEE keys and regions segment.

Constructor.

Parameters:

regions (Sequence[BeeRegionHeader]) – list of regions
max_facs (int) – maximum total number of FAC in all regions, used for validation

add_region(region)#

Add region.

Parameters:: region (BeeRegionHeader) – to be added
Return type:: None

encrypt_data(start_addr, data)#

Encrypt image data located in any PRDB block.

Parameters:

start_addr (int) – start address of the data; must be aligned to block size
data (bytes) – to be encrypted

Return type:

bytes

Returns:

encrypted data, aligned to block size; blocks outside any FAC region kept untouched

Raises:

SPSDKError – If invalid start address

export()#

Serialization to binary representation.

Return type:: bytes
Returns:: binary representation of the region (serialization).

classmethod parse(data, decrypt_keys=None)#

De-serialization.

Parameters:

data (bytes) – binary data to be parsed
decrypt_keys (Optional[list[bytes]]) – list of SW_GP keys used to decrypt EKIB The number of keys must match number of regions to be parsed

Return type:

Self

Returns:

instance created from binary data

property size: int#

Returns:: size of the exported binary data in bytes.

update()#

Updates internal fields of the instance.

Return type:: None

validate()#

Validates settings of the instance.

Raises:: SPSDKError – If number of FAC regions exceeds the limit
Return type:: None

class spsdk.image.segments.SegBIC1(version=0)#

Bases: BaseSegment

Boot Images Container segment.

Initialize Boot Images Container segment.

Parameters:: version (int) – The version of Header for Boot Images Container

FORMAT = '<LH2B2H'#

MAX_NUM_IMGS = 6#

SIZE = 808#

export()#

Export segment as bytes array.

Return type:: bytes
Returns:: bytes

classmethod parse(data)#

Parse segment from bytes array.

Parameters:: data (bytes) – The bytes array of BIC1 segment
Return type:: Self
Returns:: SegBIC1 object

property size: int#: Size.

validate()#

Validate segment.

Return type:: None

property version: int#: Version of Boot Images Container segment.

class spsdk.image.segments.SegBIM#

Bases: BaseSegment

BootImage segment.

Initialize BootImage segment.

FORMAT = '<2L2Q2L'#

SIZE = 128#

export()#

Export segment as bytes array.

Return type:: bytes
Returns:: bytes

classmethod parse(data)#

Parse segment from bytes array.

Parameters:: data (bytes) – The bytes array of BootImage segment
Return type:: Self
Returns:: SegBootImage object

property size: int#: Size of BootImage segment.

class spsdk.image.segments.SegCSF(version=64, enabled=False)#

Bases: BaseSegment

Command Sequence File (CSF), signature block for Secure Boot.

A script of commands used to guide image authentication and device configuration operations.

Initialize CSF segment.

append_command(cmd)#

Append CSF command to the segment.

Parameters:: cmd (CmdBase) – to be added
Raises:: SPSDKError – If invalid command
Return type:: None

clear_commands()#

Removes= all commands.

Return type:: None

property commands: list[CmdBase]#: List of CSF commands in the segment.

export()#

Export segment as bytes array (serialization).

Return type:: bytes
Returns:: bytes

property macs: Iterator[MAC]#: Iterator of all MAC sections.

classmethod parse(data)#

Parse segment from bytes array.

Parameters:

data (bytes) – The bytes array of CSF segment

Raises:

SPSDKCorruptedException – When there is unknown command
SPSDKCorruptedException – When command can not be parsed

Return type:

Self

Returns:

SegCSF instance

property size: int#: Size of the binary representation of the segment; 0 is not enabled.

property space: int#: Size of the binary representation of the segment including padding; 0 is not enabled.

update(reset_cmddata_offsets)#

Update the offsets for the export.

Parameters:: reset_cmddata_offsets (bool) – True to reset all cmd-data offsets, if cmd-data not specified in the command; False to avoid any reset; Note: reset should be done during parsing process as the data are incomplete
Return type:: None

update_signatures(zulu, data, base_data_addr)#

Update signatures in all CmdAuthData commands.

Parameters:

zulu (datetime) – current UTC time+date
data (bytes) – currently generated binary data; empty to create “fake” signature to update size of the segment
base_data_addr (int) – base address of the generated data

Raises:

SPSDKError – If invalid length of data
SPSDKError – If invalid length of data

Return type:

None

property version: int#: Version of CSF segment.

class spsdk.image.segments.SegDCD(param=65, enabled=False)#

Bases: BaseSegment

Device configuration data (DCD) segment.

IC configuration data, usually is used to configure DDR/SDRAM memory. Typically this is optional

Initialize DCD segment.

append(cmd)#

Appending of Device configuration data (DCD) segment.

Return type:: None

clear()#

Clear of Device configuration data (DCD) segment.

Return type:: None

property commands: list[CmdBase]#: Commands of Device configuration data (DCD) segment.

export()#

Export segment as bytes array.

Return type:: bytes
Returns:: bytes

export_txt(txt_data=None)#

Export txt of Device configuration data (DCD) segment.

Return type:: str

property header: Header#: Header of Device configuration data (DCD) segment.

classmethod parse(data)#

Parse segment from bytes array.

Parameters:: data (bytes) – The bytes array of DCD segment
Raises:: SPSDKCorruptedException – Exception caused by corrupted data
Return type:: Self
Returns:: SegDCD object

classmethod parse_txt(text)#

Parse segment from text file.

Parameters:: text (str) – The string with DCD commands
Return type:: SegDCD
Returns:: SegDCD object

pop(index)#

Popping of Device configuration data (DCD) segment.

Return type:: CmdBase

property size: int#: Size of Device configuration data (DCD) segment.

property space: int#: Add space.

class spsdk.image.segments.SegDcdBuilder#

Bases: object

Builder to create SegDCD from text input.

Initialize SegDcdBuilder.

build(text)#

Parse segment from text file and build SegDCD.

Parameters:: text (str) – input text to import
Return type:: SegDCD
Returns:: SegDCD object

class spsdk.image.segments.SegFCB#

Bases: AbstractFCB, ABC

FCB.

Initialize FCB segment.

FINGERPRINT = b'NFCB'#

SIZE = 1024#

property crc: int#: Cyclic redundancy check.

export()#

Export to binary form.

Return type:: bytes

class spsdk.image.segments.SegIDS3a#

Bases: BaseSegment

IDS3a segment.

Initialize IDS3a segment.

FORMAT = '<3Q4L'#

SIZE = 40#

export()#

Export segment as bytes array.

Return type:: bytes
Returns:: bytes

classmethod parse(data)#

Parse segment from bytes array.

Parameters:: data (bytes) – The bytes array of IDS3a segment
Return type:: Self
Returns:: SegIDS3a object

property size: int#: Size of IDS3a segment.

class spsdk.image.segments.SegIDS3b#

Bases: BaseSegment

IDS3b segment.

Initialize IDS3b segment.

FORMAT = '<3Q2L'#

SIZE = 32#

export()#

Export segment as bytes array.

Return type:: bytes
Returns:: bytes

classmethod parse(data)#

Parse segment from bytes array.

Parameters:: data (bytes) – The bytes array of IDS3b segment
Return type:: Self
Returns:: SegIDS3b object

property size: int#: Size of IDS3b segment.

class spsdk.image.segments.SegIVT2(version)#

Bases: BaseSegment

Image Vector Table, IVT2 segment.

Initialize IVT2 segment.

Parameters:: version (int) – The version of IVT and Image format

FORMAT = '<7L'#

SIZE = 32#

export()#

Export to binary representation (serialization).

Return type:: bytes
Returns:: segment exported as binary data

classmethod parse(data)#

Parse segment from bytes array.

Parameters:: data (bytes) – The bytes array of IVT2 segment
Return type:: Self
Returns:: SegIVT2 object

property size: int#: Size of the binary data.

validate()#

Validate settings of the segment.

Raises:: SPSDKError – If there is configuration problem
Return type:: None

property version: int#: The version of IVT and Image format.

class spsdk.image.segments.SegIVT3a(param)#

Bases: BaseSegment

IVT3a segment.

Initialize IVT segment.

Parameters:: param (int) – The version of IVT and Image format

FORMAT = '<1L5Q'#

SIZE = 48#

export()#

Export segment as bytes array.

Return type:: bytes
Returns:: bytes

property header: Header#: Header of IVT3a segment.

classmethod parse(data)#

Parse segment from bytes array.

Parameters:: data (bytes) – The bytes array of IVT3a segment
Return type:: Self
Returns:: SegIVT3a object

property size: int#: Size of IVT3a segment.

validate()#

Validation of IVT3a segment.

Return type:: None

class spsdk.image.segments.SegIVT3b(version)#

Bases: BaseSegment

IVT3b segment.

Initialize IVT segment.

Parameters:: version (int) – The version of IVT and Image format

FORMAT = '<1L7Q'#

SIZE = 64#

export()#

Export segment as bytes array.

Return type:: bytes
Returns:: bytes

property header: Header#: Header of IVT3b segment.

classmethod parse(data)#

Parse segment from bytes array.

Parameters:: data (bytes) – The bytes array of IVT3b segment
Return type:: Self
Returns:: SegIVT3b object

property size: int#

Size of IVT3b segment.

:return size

validate()#

Validation of IVT3b segment.

Return type:: None

class spsdk.image.segments.SegSIGB(version=0)#

Bases: BaseSegment

SignatureBlock segment.

Initialize SignatureBlock segment.

FORMAT = '<4HL'#

SIZE = 16#

export()#

Export segment as bytes array.

Return type:: bytes
Returns:: bytes

classmethod parse(data)#

Parse segment from bytes array.

Parameters:: data (bytes) – The bytes array of SignatureBlock segment
Return type:: Self
Returns:: SegSigBlk object

property size: int#: Size of Signature Block segment.

property version: int#: Version of Signature Block segment.

class spsdk.image.segments.SegXMCD(header, config_data)#

Bases: BaseSegment

External Memory Configuration Data Segment.

Initialize XMCD Segment.

Parameters:

header (XMCDHeader) – XMCD Header
config_data (bytes) – XMCD configuration data

TAG = 192#

export()#

Export segment as bytes (serialization).

Return type:: bytes

classmethod parse(data)#

Parse XMCD from binary data.

Return type:: Self

class spsdk.image.segments.XMCDHeader(interface=0, instance=0, block_type=0, block_size=4)#

Bases: object

External Memory Configuration Data Header.

Initialize XMCD Header.

Parameters:

interface (int) – Type of the XMCD instance (0 - FlexSPI, 1 - SEMC), defaults to 0
instance (int) – Number of the interface instance, defaults to 0
block_type (int) – Type of XMCD data (0 - Simplified, 1 - Full), defaults to 0
block_size (int) – XMCD data block size, defaults to 4

Raises:

SPSDKValueError – If the given interface is not supported
SPSDKValueError – If the given block type is not supported

FORMAT = '<4B'#

SIZE = 4#

TAG = 12#

property config_data_size: int#: Size of XMCD config data blob.

export()#

Export segment’s header as bytes (serialization).

Return type:: bytes

classmethod parse(data)#

Parse XMCD Header from binary data.

Return type:: Self

Image Segments#

This module contains generic implementation of image segment.

class spsdk.image.segments_base.SegmentBase(family, revision)#

Bases: BaseClass

Base class for image segment.

Segment base Constructor.

Parameters:

family (str) – Chip family.
revision (str) – Optional Chip family revision.

Raises:

SPSDKValueError – Unsupported family.

FEATURE = 'unknown'#

abstract create_config()#

Create current configuration YAML.

Return type:: str
Returns:: Configuration of segment.

export()#

Export block binary.

Return type:: bytes
Returns:: Binary representation of segment.

classmethod get_memory_types_config(family, revision='latest')#

Get memory types data from database.

Parameters:

family (str) – Chip family.
revision (str) – Optional Chip family revision.

Return type:

dict[str, dict]

classmethod get_supported_families()#

Return list of supported families.

Return type:: list
Returns:: List of supported families.

classmethod get_supported_memory_types(family=None, revision='latest')#

Get list of supported memory types data from database.

Parameters:

family (Optional[str]) – Chip family.
revision (str) – Optional Chip family revision.

Return type:

list[MemoryType]

abstract static load_from_config(config)#

Load configuration file.

Parameters:: config (dict) – Segment configuration file.
Return type:: Any
Returns:: Segment object.

abstract property registers: Registers#: Registers of segment.

TrustZone#

Module provides support for TrustZone configuration data.

class spsdk.image.trustzone.TrustZone(family='Unknown', revision='latest', tz_type=TrustZoneType(tag=0, label='ENABLED', description='TrustZone enabled with default settings'), customizations=None, raw_data=None)#

Bases: object

Provide creation of binary data to set up the TrustZone engine in CM-33.

Initialize the trustzone.

classmethod custom(family, customizations, revision='latest')#

Alternate constructor for CUSTOM type of TrustZone.

Return type:: TrustZone

classmethod disabled()#

Alternate constructor for DISABLED type of TrustZone.

Return type:: TrustZone
Returns:: TrustZone object

classmethod enabled()#

Alternate constructor for ENABLED type of TrustZone.

Return type:: TrustZone
Returns:: TrustZone object

export()#

Return the TrustZone data as bytes.

Return type:: bytes

classmethod from_binary(family, raw_data, revision='latest')#

Alternate constructor using existing binary data.

Return type:: TrustZone

classmethod from_config(config_data)#

Alternate constructor using configuration data.

Raises:: SPSDKError – Invalid configuration file.
Return type:: TrustZone
Returns:: TrustZone class instance.

classmethod generate_config_template(family, revision='latest')#

Generate configuration for selected family.

Parameters:

family (str) – Family description.
revision (str) – Chip revision specification, as default, latest is used.

Raises:

SPSDKError – Revision is not supported.

Return type:

dict[str, str]

Returns:

Dictionary of individual templates (key is name of template, value is template itself).

classmethod get_preset_data_size(family, revision='latest')#

Get size of preset data in binary form.

Parameters:

family (str) – Family description.
revision (str) – Chip revision specification, as default, latest is used.

Raises:

SPSDKValueError – Family or revision is not supported.

Return type:

int

Returns:

Size of TZ data.

static get_supported_families()#

Return list of supported families.

Return type:: list[str]

classmethod get_validation_schemas(family, revision='latest')#

Create the validation schema.

Parameters:

family (str) – Family description.
revision (str) – Chip revision specification, as default, latest is used.

Raises:

SPSDKError – Family or revision is not supported.

Return type:

list[dict[str, Any]]

Returns:

List of validation schemas.

classmethod get_validation_schemas_family()#

Create the validation schema just for supported families.

Return type:: list[dict[str, Any]]
Returns:: List of validation schemas for TZ supported families.

static validate_custom_data(data, customizations)#

Check whether all register names in custom data are valid (present in presets).

Return type:: bool

class spsdk.image.trustzone.TrustZoneType(tag, label, description=None)#

Bases: SpsdkEnum

Enum defining various types of TrustZone types.

CUSTOM = (1, 'CUSTOM', 'TrustZone enabled with custom settings')#

DISABLED = (2, 'DISABLED', 'Disabled')#

ENABLED = (0, 'ENABLED', 'TrustZone enabled with default settings')#

Support for BEE encryption for RT10xx devices#

Contains support for BEE encryption.

class spsdk.image.bee.BeeBaseClass#

Bases: object

BEE base class.

classmethod check_data_to_parse(data)#

Deserialization.

Parameters:: data (bytes) – binary data to be parsed
Raises:: SPSDKError – If size of the data is not sufficient
Return type:: None

export()#

Return type:: bytes
Returns:: binary representation of the region (serialization).

classmethod get_size()#

Return type:: int
Returns:: size of the exported binary data in bytes.

property size: int#

Returns:: size of the exported binary data in bytes.

update()#

Updates internal fields of the instance.

Return type:: None

validate()#

Validates the configuration of the instance.

It is recommended to call the method before export and after parsing.

Return type:: None

class spsdk.image.bee.BeeFacRegion(start=0, length=0, protected_level=0)#

Bases: BeeBaseClass

BEE Factory Access Control (FAC) region.

Constructor.

Parameters:

start (int) – Start address of one FAC region, align at 1KB boundary; 32-bit number
length (int) – Length of one FAC region, align at 1KB boundary; 32-bit number
protected_level (int) – Protected level: 0/1/2/3; 32-bit number

property end_addr: int#

Returns:: end address of the region (which is last address of the region + 1).

export()#

Exports the binary representation.

Return type:: bytes

classmethod parse(data)#

Deserialization.

Parameters:: data (bytes) – binary data to be parsed
Return type:: Self
Returns:: instance created from binary data
Raises:: SPSDKError – If reserved area is non-zero

validate()#

Validates the configuration of the instance.

Return type:: None

class spsdk.image.bee.BeeKIB(kib_key=None, kib_iv=None)#

Bases: BeeBaseClass

BEE Key block.

Contains keys used to encrypt PRDB content.

Constructor.

Parameters:

kib_key (Optional[bytes]) – AES key
kib_iv (Optional[bytes]) – AES initialization vector

export()#

Exports binary representation of the region (serialization).

Return type:: bytes

classmethod parse(data)#

Deserialization.

Parameters:: data (bytes) – binary data to be parsed
Return type:: Self
Returns:: instance created from binary data

validate()#

Validates settings of the instance.

Raises:

SPSDKError – If invalid length of kib key
SPSDKError – If invalid length of kib iv

Return type:

None

class spsdk.image.bee.BeeNxp(headers, input_image, base_address)#

Bases: object

BeeNxp class.

Constructor.

Parameters:

headers (list[Optional[BeeRegionHeader]]) – list of BEE Region Headers
input_image (bytes) – Input image to be encrypted
base_address (int) – Base address of the image

static check_overlaps(bee_headers, start_addr)#

Check for overlaps in regions.

Parameters:

bee_headers (list[Optional[BeeRegionHeader]]) – List of BeeRegionHeader
start_addr (int) – start address of a region to be checked

Raises:

SPSDKOverlapError – if the address is inside any region

Return type:

None

export_headers()#

Export BEE headers.

Return type:: list[Optional[bytes]]
Returns:: BEE region headers

export_image()#

Export encrypted binary image.

Return type:: bytes
Returns:: encrypted image

static generate_config_template()#

Generate BEE configuration template.

Return type:: str
Returns:: Dictionary of individual templates (key is name of template, value is template itself).

static get_supported_families()#

Get all supported families for BEE.

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

static get_validation_schemas()#

Get list of validation schemas.

Return type:: list[dict[str, Any]]
Returns:: Validation list of schemas.

static load_from_config(config, search_paths=None)#

Converts the configuration into an BEE image object.

“config” contains dictionary of configurations.

Raises:

SPSDKError – if the count of BEE engines is invalid.

Parameters:

config (dict[str, Any]) – Configuration dictionary.
search_paths (Optional[list[str]]) – List of paths where to search for the file, defaults to None

Return type:

BeeNxp

Returns:

initialized BeeNxp object.

class spsdk.image.bee.BeeProtectRegionBlock(encr_mode=BeeProtectRegionBlockAesMode(tag=1, label='CTR', description=None), lock_options=0, counter=None)#

Bases: BeeBaseClass

BEE protect region block (PRDB).

Constructor.

Parameters:

encr_mode (BeeProtectRegionBlockAesMode) – AES encryption mode
lock_options (int) – Lock options; 32-bit number
counter (Optional[bytes]) – Counter for AES-CTR mode; 16 bytes; by default, random value is used

FAC_REGIONS = 4#

SIZE = 256#

TAGH = 1380206661#

TAGL = 1598505300#

VERSION = 1442906112#

add_fac(fac)#

Append FAC region.

Parameters:: fac (BeeFacRegion) – Factory Access Control to be added
Return type:: None

encrypt_block(key, start_addr, data)#

Encrypt block located in any FAC region.

Parameters:

key (bytes) – user for encryption
start_addr (int) – start address of the data
data (bytes) – binary block to be encrypted; the block size must be BEE_ENCR_BLOCK_SIZE

Return type:

bytes

Returns:

encrypted block if it is inside any FAC region; untouched block if it is not in any FAC region

Raises:

SPSDKError – When incorrect length of binary block
SPSDKError – When encryption mode different from AES/CTR provided
SPSDKError – When invalid length of key
SPSDKError – When invalid range of region

export()#

Return type:: bytes
Returns:: binary representation of the region (serialization).

property fac_count: int#

Returns:: number of Factory Access Control regions.

classmethod get_size()#

Return type:: int
Returns:: size of the exported binary data in bytes.

is_inside_region(start_addr)#

Returns true if the start address lies within any FAC region.

Parameters:: start_addr (int) – start address of the data
Return type:: bool

classmethod parse(data)#

Deserialization.

Parameters:: data (bytes) – binary data to be parsed
Return type:: Self
Returns:: instance created from binary data
Raises:: SPSDKError – If format does not match

update()#

Updates start and end address of the encryption region.

Return type:: None

validate()#

Validates settings of the instance.

Return type:: None

class spsdk.image.bee.BeeProtectRegionBlockAesMode(tag, label, description=None)#

Bases: SpsdkEnum

AES mode selection for BEE PRDB encryption.

CTR = (1, 'CTR')#

ECB = (0, 'ECB')#

class spsdk.image.bee.BeeRegionHeader(prdb=None, sw_key=None, kib=None)#

Bases: BeeBaseClass

BEE keys and regions header.

Constructor.

Parameters:

prdb (Optional[BeeProtectRegionBlock]) – protect region block; None to use default
sw_key (Optional[bytes]) – key used to encrypt KIB content
kib (Optional[BeeKIB]) – keys block; None to use default

PRDB_OFFSET = 128#

SIZE = 512#

add_fac(fac)#

Append FAC region.

Parameters:: fac (BeeFacRegion) – to be added
Return type:: None

encrypt_block(start_addr, data)#

Encrypt block located in any FAC region.

Parameters:

start_addr (int) – start address of the data
data (bytes) – binary block to be encrypted; the block size must be BEE_ENCR_BLOCK_SIZE

Return type:

bytes

Returns:

encrypted block if it is inside any FAC region; untouched block if it is not in any FAC region

export()#

Serialization to binary representation.

Return type:: bytes
Returns:: binary representation of the region (serialization).

property fac_regions: Sequence[BeeFacRegion]#

Returns:: lift of Factory Access Control regions.

classmethod get_size()#

Return type:: int
Returns:: size of the exported binary data in bytes.

is_inside_region(start_addr)#

Returns true if the start address lies within any FAC region.

Parameters:: start_addr (int) – start address of the data
Return type:: bool

classmethod parse(data, sw_key=b'')#

Deserialization.

Parameters:

data (bytes) – binary data to be parsed
sw_key (bytes) – SW key used to decrypt the EKIB data

Return type:

Self

Returns:

instance created from binary data

Raises:

SPSDKError – If invalid sw key

sw_key_fuses()#

Return type:: Sequence[int]
Returns:: sequence of fuse values for SW key to be burned into processor.

The result is ordered, first value should be burned to the lowest address.

update()#

Updates internal fields of the instance.

Return type:: None

validate()#

Validates settings of the instance.

Raises:: SPSDKError – If settings invalid
Return type:: None

Support for KeyStore used in MasterBootImage#

Module provides support for KeyStore used in MasterBootImage.

class spsdk.image.keystore.KeySourceType(tag, label, description=None)#

Bases: SpsdkEnum

Device key source.

KEYSTORE = (1, 'KEYSTORE', 'Device keys stored in KeyStore')#

OTP = (0, 'OTP', 'Device keys stored in OTP')#

class spsdk.image.keystore.KeyStore(key_source, key_store=None)#

Bases: object

Provide info about KeyStore for MaterBootImage.

Initialize Keystore.

Parameters:

key_source (KeySourceType) – device key source
key_store (Optional[bytes]) – initial content of the key store in the bootable image; None if empty

Raises:

SPSDKError – If invalid key-store size
SPSDKError – KeyStore can be initialized only if key_source == KEYSTORE

KEY_STORE_SIZE = 1424#

OTFAD_KEY_SIZE = 16#

OTP_MASTER_KEY_SIZE = 32#

SBKEK_SIZE = 32#

static derive_enc_image_key(master_key)#

Derive “enc_image_key” from master key.

Parameters:: master_key (bytes) – stored in OTP
Return type:: bytes
Returns:: key used to decrypt encrypted images during boot
Raises:: SPSDKError – If invalid length of master key

static derive_hmac_key(hmac_key)#

Derive HMAC from master or user key.

Parameters:: hmac_key (bytes) – either master-key (for key_source == OTP) or user key (for key_source == KEYSTORE)
Return type:: bytes
Returns:: key used for image header authentication in LoadToRam images
Raises:: SPSDKError – If invalid length of hmac key

static derive_otfad_kek_key(master_key, otfad_input)#

Derive OTFAD KEK key from master key and OTFAD input.

Parameters:

master_key (bytes) – 32 bytes key, stored in OTP
otfad_input (bytes) – 16 bytes input, stored in OTP

Return type:

bytes

Returns:

OTFAD encryption key for FLASH encryption/decryption

Raises:

SPSDKError – If invalid length of master key
SPSDKError – If invalid length of input

static derive_sb_kek_key(master_key)#

Derive SBKEK key from master key.

Parameters:: master_key (bytes) – 32 bytes key, stored in OTP
Return type:: bytes
Returns:: encryption key to handle SB2 file (update capsule)
Raises:: SPSDKError – If invalid length of master key

export()#

Binary key store content; empty bytes for empty key-store.

Return type:: bytes

property key_source: KeySourceType#: Device key source.

Master Boot Image#

Master Boot Image.

class spsdk.image.mbi.mbi.MasterBootImage(**kwargs)#

Bases: object

Master Boot Image Interface.

Initialization of MBI.

Parameters:: kwargs (Any) – Various input parameters based on used dynamic class.

IMAGE_TYPE = (0, 'Plain Image (either XIP or Load-to-RAM)')#

app: Optional[bytes]#

property app_len: int#

Compute application data length.

Returns:: Final image data length.

app_table: Optional[MultipleImageTable]#

cert_block: Union[CertBlockV1, CertBlockV21, CertBlockVx, None]#

collect_data: Callable[[], BinaryImage]#

create_config(output_folder)#

Create configuration file and its data files from the MBI class.

Parameters:: output_folder (str) – Output folder to store the parsed data
Return type:: dict[str, Any]
Returns:: Configuration dictionary.

disassemble_image: Callable[[bytes], None]#

encrypt: Callable[[BinaryImage, bool], BinaryImage]#

export()#

Export final bootable image.

Return type:: bytes
Returns:: Bootable Image in bytes.

export_image()#

Export final bootable image.

Return type:: BinaryImage
Returns:: Bootable Image in Binary Image format.

finalize: Callable[[BinaryImage, bool], BinaryImage]#

classmethod get_image_type(family, data, revision='latest')#

Get image type from MBI data and family.

Parameters:

family (str) – device family to be fetched from DB
data (bytes) – MBI raw data
revision (str) – Optional chip family revision.

Return type:

int

Returns:

Image type int representation

classmethod get_validation_schemas(family)#

Create the validation schema for current image type.

Parameters:: family (str) – Family description.
Return type:: list[dict[str, Any]]
Returns:: Validation schema.

classmethod get_validation_schemas_family()#

Create the validation family schema for current image type.

Return type:: list[dict[str, Any]]
Returns:: Validation schema.

classmethod hash()#

Unique identifier for MasterBootImage class based on mixins.

Return type:: str
Returns:: Acronym for each MBI base class separated by “-”

load_from_config(config, search_paths=None)#

Load configuration from dictionary.

Parameters:

config (dict[str, Any]) – Dictionary with configuration fields.
search_paths (Optional[list[str]]) – List of paths where to search for the file, defaults to None

Return type:

None

static parse(family, data, dek=None, revision='latest')#

Parse the final image to individual fields.

Parameters:

family (str) – Device family
data (bytes) – Final Image in bytes
dek (Optional[str]) – The decryption key for encrypted images
revision (str) – Optional chip family revision.

Raises:

SPSDKParsingError – Cannot determinate the decoding class

Return type:

MasterBootImage

Returns:

MBI parsed class

post_encrypt: Callable[[BinaryImage, bool], BinaryImage]#

property rkth: bytes | None#

Get Root Key Table Hash from certificate block if present.

Returns:: Root Key Table Hash as hex string.

sign: Callable[[BinaryImage, bool], BinaryImage]#

property total_len: int#

Compute Master Boot Image data length.

Returns:: Final image data length.

property total_length_for_cert_block: int#

Compute Master Boot Image data length.

Returns:: Final image data length.

validate()#

Validate the setting of image.

Return type:: None

spsdk.image.mbi.mbi.create_mbi_class(name, family, revision='latest')#

Create Master Boot image class.

Parameters:

name (str) – Name of Class
family (str) – Name of chip family
revision (str) – Optional chip family revision.

Return type:

Type[MasterBootImage]

Returns:

Master Boot Image class

spsdk.image.mbi.mbi.get_all_mbi_classes()#

Get all Master Boot Image supported classes.

Return type:: list[Type[MasterBootImage]]
Returns:: List with all MBI Classes.

spsdk.image.mbi.mbi.get_mbi_class(config)#

Get Master Boot Image class.

Raises:: SPSDKUnsupportedImageType – The invalid configuration.
Return type:: Type[MasterBootImage]
Returns:: MBI Class.

spsdk.image.mbi.mbi.get_mbi_classes(family, revision='latest')#

Get all Master Boot Image supported classes for chip family.

Parameters:

family (str) – Chip family.
revision (str) – Optional chip family revision.

Raises:

SPSDKValueError – The invalid family.

Return type:

dict[str, tuple[Type[MasterBootImage], str, str]]

Returns:

Dictionary with key like image name and values are Tuple with it’s MBI Class and target and authentication type.

spsdk.image.mbi.mbi.mbi_generate_config_templates(family, revision='latest')#

Generate all possible configuration for selected family.

Parameters:

family (str) – Family description.
revision (str) – Optional chip family revision.

Return type:

dict[str, str]

Returns:

Dictionary of individual templates (key is name of template, value is template itself).

spsdk.image.mbi.mbi.mbi_get_supported_families()#

Get supported families by MBI.

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

Master Boot Image - miscellaneous functions#

Misc.

exception spsdk.image.misc.NotEnoughBytesException(desc=None)#

Bases: RawDataException

Read_raw_data could not read enough data.

Initialize the base SPSDK Exception.

exception spsdk.image.misc.RawDataException(desc=None)#

Bases: SPSDKError

Raw data read failed.

Initialize the base SPSDK Exception.

exception spsdk.image.misc.StreamReadFailed(desc=None)#

Bases: RawDataException

Read_raw_data could not read stream.

Initialize the base SPSDK Exception.

spsdk.image.misc.dict_diff(main, mod)#

Return a difference between two dictionaries if key is not present in main, it’s skipped.

Return type:: dict

spsdk.image.misc.hexdump_fmt(data, tab=4, length=16, sep=':')#

Dump some potentially larger data in hex.

Return type:: str

spsdk.image.misc.modulus_fmt(modulus, tab=4, length=15, sep=':')#

Modulus format.

Return type:: str

spsdk.image.misc.read_raw_data(stream, length, index=None, no_seek=False)#

Read raw data.

Return type:: bytes

spsdk.image.misc.read_raw_segment(buffer, segment_tag, index=None)#

Read raw segment.

Return type:: bytes

Master Boot Image - mixin classes#

Master Boot Image.

class spsdk.image.mbi.mbi_mixin.Mbi_ExportMixin#

Bases: object

Base MBI Export Mixin class.

collect_data()#

Collect basic data to create image.

Return type:: BinaryImage
Returns:: Collected raw image.

disassemble_image(image)#

Disassemble image to individual parts from image.

Parameters:: image (bytes) – Image.
Return type:: None

encrypt(image, revert=False)#

Encrypt image if needed.

Parameters:

image (BinaryImage) – Input raw image to encrypt.
revert (bool) – Revert the operation if possible.

Return type:

Returns:

Encrypted image.

finalize(image, revert=False)#

Finalize the image for export.

This part could add HMAC/KeyStore etc.

Parameters:

image (BinaryImage) – Input image.
revert (bool) – Revert the operation if possible.

Return type:

Returns:

Finalized image suitable for export.

post_encrypt(image, revert=False)#

Optionally do some post encrypt image updates.

Parameters:

image (BinaryImage) – Encrypted image.
revert (bool) – Revert the operation if possible.

Return type:

Returns:

Updated encrypted image.

sign(image, revert=False)#

Sign image (by signature or CRC).

Parameters:

image (BinaryImage) – Image to sign.
revert (bool) – Revert the operation if possible.

Return type:

Returns:

Optionally signed image.

class spsdk.image.mbi.mbi_mixin.Mbi_ExportMixinApp#

Export Mixin to handle simple application data.

app: Optional[bytes]#

collect_data()#

Collect application data including update IVT.

Return type:: BinaryImage
Returns:: Image with updated IVT.

total_len: Any#

update_ivt: Callable[[bytes, int, int], bytes]#

class spsdk.image.mbi.mbi_mixin.Mbi_ExportMixinAppBcaFcf#

Export Mixin to handle simple application data with BCA and FCF.

IMG_BCA_OFFSET: int#

IMG_DATA_START: int#

IMG_DIGEST_OFFSET: int#

IMG_DUK_BLOCK_OFFSET: int#

IMG_FCF_LIFECYCLE_OFFSET: int#

IMG_FCF_OFFSET: int#

IMG_FCF_SIZE: int#

IMG_ISK_HASH_OFFSET: int#

IMG_ISK_OFFSET: int#

IMG_SIGNATURE_OFFSET: int#

IMG_WPC_MFG_CA_CERT_OFFSET: int#

IMG_WPC_PU_CERT_OFFSET: int#

IMG_WPC_ROOT_CA_CERT_HASH_OFFSET: int#

app: Optional[bytes]#

collect_data()#

Collect application data.

Return type:: BinaryImage
Returns:: Binary Image with updated BCA and FCF.

disassemble_image(image)#

Disassemble image to individual parts from image.

Parameters:: image (bytes) – Image.
Return type:: None

just_header: bool#

total_len: int#

update_bca: Callable[[bytes, int], bytes]#

update_fcf: Callable[[bytes], bytes]#

class spsdk.image.mbi.mbi_mixin.Mbi_ExportMixinAppCertBlockManifest#

Export Mixin to handle simple application data, Certification block and Manifest.

app: Optional[bytes]#

app_len: int#

cert_block: Union[CertBlockV1, CertBlockV21, None]#

collect_data()#

Collect application data, Certification Block and Manifest including update IVT.

Raises:: SPSDKError – When either application data or certification block or manifest is missing
Return type:: BinaryImage
Returns:: Image with updated IVT and added Certification Block with Manifest.

data_to_sign: Optional[bytes]#

disassemble_image(image)#

Disassemble image to individual parts from image.

Parameters:: image (bytes) – Image.
Return type:: None

disassembly_app_data: Callable[[bytes], bytes]#

finalize(image, revert=False)#

Finalize the image for export by adding HMAC a optionally KeyStore.

Parameters:

image (BinaryImage) – Input image.
revert (bool) – Revert the operation if possible.

Return type:

Returns:

Finalized image suitable for export.

ivt_table: Mbi_MixinIvt#

manifest: Optional[TypeVar(T_Manifest, MasterBootImageManifest, MasterBootImageManifestDigest, MasterBootImageManifestCrc)]#

total_len: int#

class spsdk.image.mbi.mbi_mixin.Mbi_ExportMixinAppFcf#

Export Mixin to handle simple application data with FCF.

IMG_BCA_OFFSET: int#

IMG_DATA_START: int#

IMG_DIGEST_OFFSET: int#

IMG_DUK_BLOCK_OFFSET: int#

IMG_FCF_LIFECYCLE_OFFSET: int#

IMG_FCF_OFFSET: int#

IMG_FCF_SIZE: int#

IMG_ISK_HASH_OFFSET: int#

IMG_ISK_OFFSET: int#

IMG_SIGNATURE_OFFSET: int#

IMG_WPC_MFG_CA_CERT_OFFSET: int#

IMG_WPC_PU_CERT_OFFSET: int#

IMG_WPC_ROOT_CA_CERT_HASH_OFFSET: int#

app: Optional[bytes]#

collect_data()#

Get app data and update FCF.

Return type:: BinaryImage
Returns:: Binary Image with updated FCF.

update_fcf: Callable[[bytes], bytes]#

class spsdk.image.mbi.mbi_mixin.Mbi_ExportMixinAppTrustZone#

Export Mixin to handle simple application data and TrustZone.

app: Optional[bytes]#

app_table: MultipleImageTable#

clean_ivt: Callable[[bytes], bytes]#

collect_data()#

Collect application data and TrustZone including update IVT.

Return type:: BinaryImage
Returns:: Image with updated IVT and added TrustZone.

disassemble_image(image)#

Disassemble image to individual parts from image.

Parameters:: image (bytes) – Image.
Return type:: None

disassembly_app_data: Callable[[bytes], bytes]#

total_len: Any#

trust_zone: TrustZone#

update_ivt: Callable[[bytes, int, int], bytes]#

class spsdk.image.mbi.mbi_mixin.Mbi_ExportMixinAppTrustZoneCertBlock#

Export Mixin to handle simple application data, TrustZone and Certification block.

app: Optional[bytes]#

app_len: int#

app_table: MultipleImageTable#

cert_block: Union[CertBlockV1, CertBlockV21, None]#

collect_data()#

Collect application data and TrustZone including update IVT.

Return type:: BinaryImage
Returns:: Image with updated IVT and added TrustZone.

disassemble_image(image)#

Disassemble image to individual parts from image.

Parameters:: image (bytes) – Image.
Return type:: None

disassembly_app_data: Callable[[bytes], bytes]#

ivt_table: Mbi_MixinIvt#

total_len: int#

total_length_for_cert_block: int#

trust_zone: TrustZone#

class spsdk.image.mbi.mbi_mixin.Mbi_ExportMixinAppTrustZoneCertBlockEncrypt#

Export Mixin to handle simple application data, TrustZone and Certification block.

HMAC_OFFSET: int#

app: Optional[bytes]#

app_len: int#

app_table: MultipleImageTable#

cert_block: Union[CertBlockV1, CertBlockV21, None]#

collect_data()#

Collect application data and TrustZone including update IVT.

Return type:: BinaryImage
Returns:: Image with updated IVT and added TrustZone.

ctr_init_vector: bytes#

disassemble_image(image)#

Disassemble image to individual parts from image.

Parameters:: image (bytes) – Image.
Return type:: None

disassembly_app_data: Callable[[bytes], bytes]#

encrypt(image, revert=False)#

Encrypt image if needed.

Parameters:

image (BinaryImage) – Input raw image to encrypt.
revert (bool) – Revert the operation if possible.

Return type:

Returns:

Encrypted image.

family: str#

hmac_key: Optional[bytes]#

property img_len: int#: Image length of encrypted legacy image.

ivt_table: Mbi_MixinIvt#

key_store: Optional[KeyStore]#

post_encrypt(image, revert=False)#

Optionally do some post encrypt image updates.

Parameters:

image (BinaryImage) – Encrypted image.
revert (bool) – Revert the operation if possible.

Return type:

Returns:

Updated encrypted image.

revision: str#

total_len: int#

trust_zone: TrustZone#

class spsdk.image.mbi.mbi_mixin.Mbi_ExportMixinCrcSign#

Export Mixin to handle sign by CRC.

IVT_CRC_CERTIFICATE_OFFSET: int#

sign(image, revert=False)#

Do simple calculation of CRC and return updated image with it.

Parameters:

image (BinaryImage) – Input raw image.
revert (bool) – Revert the operation if possible.

Return type:

Returns:

Image enriched by CRC in IVT table.

update_crc_val_cert_offset: Callable[[bytes, int], bytes]#

class spsdk.image.mbi.mbi_mixin.Mbi_ExportMixinCrcSignBca#

Export Mixin to handle sign by CRC in BCA.

IMG_BCA_OFFSET: int#

IMG_DATA_START: int#

sign(image, revert=False)#

Do simple calculation of CRC and return updated image with it.

Parameters:

image (BinaryImage) – Input raw image.
revert (bool) – Revert the operation if possible.

Return type:

Returns:

Image enriched by CRC of application.

class spsdk.image.mbi.mbi_mixin.Mbi_ExportMixinEccSign#

Export Mixin to handle sign by ECC.

cert_block: Union[CertBlockV1, CertBlockV21, None]#

data_to_sign: Optional[bytes]#

sign(image, revert=False)#

Do calculation of ECC signature and return updated image with it.

Parameters:

image (BinaryImage) – Input raw image.
revert (bool) – Revert the operation if possible.

Return type:

Returns:

Image enriched by ECC signature at end of image.

signature_provider: Optional[SignatureProvider]#

class spsdk.image.mbi.mbi_mixin.Mbi_ExportMixinEccSignVx#

Export Mixin to handle sign by ECC.

IMG_BCA_OFFSET: int#

IMG_DATA_START: int#

IMG_DIGEST_OFFSET: int#

IMG_DIGEST_SIZE: int#

IMG_ISK_HASH_OFFSET: int#

IMG_ISK_HASH_SIZE: int#

IMG_ISK_OFFSET: int#

IMG_SIGNED_HEADER_END: int#

add_hash: bool#

app: Optional[bytes]#

cert_block: CertBlockVx#

sign(image, revert=False)#

Do calculation of ECC signature and digest and return updated image with it.

Parameters:

image (BinaryImage) – Input raw image.
revert (bool) – Revert the operation if possible.

Return type:

Returns:

Image enriched by ECC signature and SHA256 digest.

signature_provider: Optional[SignatureProvider]#

class spsdk.image.mbi.mbi_mixin.Mbi_ExportMixinHmacKeyStoreFinalize#

Export Mixin to handle finalize by HMAC and optionally KeyStore.

HMAC_OFFSET: int#

HMAC_SIZE: int#

compute_hmac: Callable[[bytes], bytes]#

finalize(image, revert=False)#

Finalize the image for export by adding HMAC a optionally KeyStore.

Parameters:

image (BinaryImage) – Input image.
revert (bool) – Revert the operation if possible.

Return type:

Returns:

Finalized image suitable for export.

ivt_table: Mbi_MixinIvt#

key_store: Optional[KeyStore]#

class spsdk.image.mbi.mbi_mixin.Mbi_ExportMixinRsaSign#

Export Mixin to handle sign by RSA.

cert_block: Union[CertBlockV1, CertBlockV21, None]#

sign(image, revert=False)#

Do calculation of RSA signature and return updated image with it.

Parameters:

image (BinaryImage) – Input raw image.
revert (bool) – Revert the operation if possible.

Return type: