Image Module API¶

Module implementing functionality of srktool, dcdgen, mkimage and other similar tools.

Image Classes¶

Image.

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

Bases: spsdk.image.images.BootImgBase

IMX Boot Image v2.

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=4, 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 the data type is unknown

Return type

None

property app¶

APP.

Return type: SegAPP

property bdt¶

BDT.

Return type: SegBDT

property csf¶

CSF.

Return type: SegCSF

export()¶

Export image as bytes array.

Return type: bytes
Returns: bytes

info()¶

String representation of the IMX Boot Image v2.

Return type: str

property ivt¶

IVT.

Return type: SegIVT2

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 value type is incorrect
SPSDKError – Raised when there is not an i.MX Boot Image

Return type

BootImg2

Returns

BootImg2 object

property plugin¶

Plugin.

Return type: bool

property size¶

Size of IMX Boot Image v2..

Return type: int

property version¶

Version of IMX Boot Image v2.

Return type: int

class spsdk.image.images.BootImg3a(address=0, offset=1024, version=67)¶

Bases: spsdk.image.images.BootImgBase

i.MX Boot Image v3a.

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_APP = 20275140¶

SCFW_FLAGS_M4_0 = 4870498¶

SCFW_FLAGS_M4_1 = 5198499¶

SCFW_FLAGS_SCFW = 1¶

SECTOR_SIZE = 512¶

add_image(data, img_type=4, 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 when data type is unknown

Return type

None

property bdt¶

BDT.

Return type: List[SegBDS3a]

property csf¶

CSF.

Return type: SegCSF

export()¶

Export Image as binary blob.

Return type: bytes

info()¶

String representation of the i.MX Boot Image v3a.

Return type: str

property ivt¶

IVT.

Return type: List[SegIVT3a]

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 values type is incorrect
SPSDKError – Raised when there is not an i.MX Boot Image

Return type

BootImgBase

Returns

BootImg3a object

property plg¶

PLG.

Return type: bool

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

Bases: spsdk.image.images.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=4, 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¶

BDT.

Return type: List[SegBDS3b]

property csf¶

CSF.

Return type: SegCSF

export()¶

Export.

Return type: bytes

info()¶

String representation of the IMX Boot Image v3b.

Return type: str

property ivt¶

IVT.

Return type: List[SegIVT3b]

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

BootImgBase

Returns

BootImg3b object

property plg¶

PLG.

Return type: bool

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

Bases: spsdk.image.images.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)¶

Not implemented.

Return type: None

export()¶

Export.

Return type: bytes

info()¶

String representation of the i.MX Boot Image v4.

Return type: str

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

BootImgBase

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: spsdk.image.images.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=4, 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¶

APP.

Return type: SegAPP

property bdt¶

BDT.

Return type: SegBDT

property csf¶

CSF.

Return type: SegCSF

export()¶

Export Image as bytes array.

Return type: bytes
Returns: bytes

info()¶

String representation of the IMX Boot Image.

Return type: str

property ivt¶

IVT.

Return type: SegIVT2

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

BootImgBase

Returns

BootImg2 object

property plugin¶

Plugin.

Return type: bool

property size¶

Size of IMX Boot Image.

Return type: int

property version¶

Version of IMX Boot Image.

Return type: int

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

Return type

None

property dcd¶

Device configuration data (DCD) segment; None if not assigned.

Return type: Optional[SegDCD]

export()¶

Binary representation of the instance (serialization).

Return type: bytes

info()¶

Text info about the instance.

Return type: str

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

Parse of IMX Boot Image Base.

Return type: BootImgBase

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

Bases: spsdk.image.images.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, 4096)¶

IVT_OFFSET_NOR_FLASH = 4096¶

IVT_OFFSET_OTHER = 1024¶

NON_XIP_APP_OFFSET = 4096¶

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

XIP_APP_OFFSET = 8192¶

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 (bytes) – CSF private key; decrypted binary data in PEM format
img_cert (bytes) – IMG certificate
img_priv_key (bytes) – IMG private key; decrypted binary data in PEM format

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 (bytes) – CSF private key; decrypted binary data in PEM format
img_cert (bytes) – IMG certificate
img_priv_key (bytes) – 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=4, 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¶

Segment with application image.

Return type: SegAPP

property app_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

property bdt¶

Boot Data Table.

Return type: SegBDT

property bee¶

Return type: 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¶

True if BEE encrypted XIP image (with SW keys); False otherwise; see also hab_encrypted.

Return type: bool

property csf¶

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

Return type: Optional[SegCSF]

property decrypted_app_data¶

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

Return type: bytes

property dek_img_offset¶

Offset of the DEK key in the image; -1 if DEK key address is available (see dek_ram_address).

Return type: int

property dek_key¶

DEK key for encrypted images; None for non-encrypted images.

Return type: Optional[bytes]

property dek_ram_address¶

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

Return type: int

property enabled_csf¶

Enabled Command Sequence File (CSF) segment; None if CSF is not defined or it is not enabled.

Return type: Optional[SegCSF]

export(zulu=datetime.datetime(2021, 9, 7, 13, 50, 35, 784161, tzinfo=datetime.timezone.utc), dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

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
dbg_info (DebugInfo) – optional instance to provide info about exported data

Raises

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

Return type

bytes

Returns

bytes

property fcb¶

Flash Configuration(Control) Block, binary data; content depends on FLASH type.

Return type: AbstractFCB

property hab_encrypted¶

True if HAB encrypted; False otherwise; see also bee_encrypted.

Return type: bool

info()¶

Text info about the instance.

Return type: str

property ivt¶

Image Vector Table (IVT) segment.

Return type: SegIVT2

property ivt_offset¶

Offset of the Image Vector Table (IVT) in the image.

Return type: int

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¶

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.

Return type: bool

set_flexspi_fcb(data)¶

Set FlexSPI external FLASH configuration.

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

property size¶

Size of the exported binary data.

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

Return type: int

property version¶

Version of the image format; must be from BootImgRT.VERSIONS.

Return type: int

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¶

Address.

Return type: int

property app¶

APP.

Return type: Optional[bytes]

property csf¶

CSF.

Return type: SegCSF

export()¶

Export.

Return type: bytes

info()¶

String representation of the IMX Kernel Image.

Return type: None

classmethod parse(data)¶

Parse.

Return type: None

property version¶

Version.

Return type: int

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

BootImgBase

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=0, key_index=1, sig_format=197, engine=0, engine_cfg=0, location=0, certificate=None, private_key_pem_data=None)¶

Bases: spsdk.image.commands.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¶

Offset of an additional data (such as signature or MAC, etc) in binary image.

Return type: int

property cmd_data_reference¶

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

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

Return type: Union[MAC, Signature, None]

property engine¶

Engine.

Return type: EnumEngine

export(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export to binary form (serialization).

Parameters: dbg_info (DebugInfo) – debug information about exported data
Return type: bytes
Returns: binary representation of the command

property flags¶

Flag of Authenticate data command.

Return type: int

info()¶

Text description of the command.

Return type: str

property key_index¶

Key index.

Return type: int

property needs_cmd_data_reference¶

Whether the command contains a reference to an additional data.

Return type: bool

classmethod parse(data, offset=0)¶

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

Parameters

data (bytes) – being parsed
offset (int) – current position to read from data

Return type

CmdAuthData

Returns

parse command

parse_cmd_data(data, offset)¶

Parse additional command data from binary data.

Parameters

data (bytes) – to be parsed
offset (int) – start position in data to parse

Return type

Union[MAC, Signature]

Returns

parsed data object; command-specific: Signature or MAC

Raises

ExpectedSignatureOrMACError – if unspported data object is provided

pop(index)¶

Pop of Authenticate data command.

Return type: Tuple[int, int]

property signature¶

Signature referenced by location attribute.

Return type: Union[MAC, Signature, None]

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

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¶

Offset of an additional data (such as certificate, signature, etc) in binary image.

Return type: int

property cmd_data_reference¶

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

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

Return type: Optional[BaseClass]

export(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export to binary form (serialization).

Parameters: dbg_info (DebugInfo) – debug information about exported data
Return type: bytes
Returns: binary representation of the command

info()¶

Text representation of the command.

Return type: str

property needs_cmd_data_reference¶

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

Return type: bool

classmethod parse(data, offset=0)¶

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

Parameters

data (bytes) – being parsed
offset (int) – current position to readd from data

Return type

CmdBase

Returns

parse command

parse_cmd_data(data, offset)¶

Parse additional command data from binary data.

Parameters

data (bytes) – to be parsed
offset (int) – start position in data to parse

Raises

SPSDKError – If cmd_data is not supported by the command

Return type

Any

property size¶

Size of command.

Return type: int

property tag¶

Command tag.

Return type: CmdTag

class spsdk.image.commands.CmdCheckData(numbytes=4, ops=1, address=0, mask=0, count=None)¶

Bases: spsdk.image.commands.CmdBase

Check data command.

Initialize the check data command.

Parameters

numbytes (int) – number of bytes
ops (int) – 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(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export to binary form (serialization).

Parameters: dbg_info (DebugInfo) – debug information about exported data
Return type: bytes
Returns: binary representation of the command

info()¶

Text description of the command.

Return type: str

property num_bytes¶

Number of bytes.

Return type: int

property ops¶

Operation of Check data command.

Return type: int

classmethod parse(data, offset=0)¶

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

Parameters

data (bytes) – being parsed
offset (int) – current position to readd from data

Return type

CmdCheckData

Returns

parse command

class spsdk.image.commands.CmdInitialize(engine=0, data=None)¶

Bases: spsdk.image.commands.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¶

Engine.

Return type: int

export(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export to binary form (serialization).

Parameters: dbg_info (DebugInfo) – debug information about exported data
Return type: bytes
Returns: binary representation of the command

info()¶

Text description of the command.

Return type: str

classmethod parse(data, offset=0)¶

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

Parameters

data (bytes) – being parsed
offset (int) – current position to readd from data

Return type

CmdInitialize

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=0, cert_fmt=3, hash_alg=0, src_index=0, tgt_index=0, location=0)¶

Bases: spsdk.image.commands.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¶

Certificate format.

Return type: EnumCertFormat

property certificate_ref¶

Corresponding certificate referenced by key-location.

Return type: Union[CertificateImg, SrkTable, None]

property cmd_data_offset¶

Offset of an additional data (such as certificate, signature, etc) in binary image.

Return type: int

property cmd_data_reference¶

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

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

Return type: Union[CertificateImg, SrkTable, None]

export(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export to binary form (serialization).

Parameters: dbg_info (DebugInfo) – debug information about exported data
Return type: bytes
Returns: binary representation of the command

property flags¶

Flags.

Return type: EnumInsKey

property hash_algorithm¶

Hash algorithm.

Return type: EnumAlgorithm

info()¶

Text description of the command.

Return type: str

property needs_cmd_data_reference¶

Whether the command contains a reference to an additional data.

Return type: bool

classmethod parse(data, offset=0)¶

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

Parameters

data (bytes) – being parsed
offset (int) – current position to read from data

Return type

CmdBase

Returns

parse command

parse_cmd_data(data, offset)¶

Parse additional command data from binary data.

Parameters

data (bytes) – to be parsed
offset (int) – start position in data to parse

Return type

Union[CertificateImg, SrkTable, None]

Returns

parsed data object; command-specific: certificate or SrkTable to be installed

property source_index¶

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

Return type: int

property target_index¶

Target key index.

Return type: int

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

Bases: spsdk.image.commands.CmdBase

Nop command.

Initialize the nop command.

info()¶

Text description of the command.

Return type: str

classmethod parse(data, offset=0)¶

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

Parameters

data (bytes) – being parsed
offset (int) – current position to readd from data

Return type

CmdNop

Returns

parse command

class spsdk.image.commands.CmdSet(itm=3, hash_alg=0, engine=0, engine_cfg=0)¶

Bases: spsdk.image.commands.CmdBase

Set command.

Initialize the set command.

property engine¶

Engine plugin tags.

Return type: EnumEngine

export(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export to binary form (serialization).

Parameters: dbg_info (DebugInfo) – debug information about exported data
Return type: bytes
Returns: binary representation of the command

property hash_algorithm¶

Type of hash algorithm.

Return type: EnumAlgorithm

info()¶

Text description of the command.

Return type: str

property itm¶

Item of Set command.

Return type: int

classmethod parse(data, offset=0)¶

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

Parameters

data (bytes) – being parsed
offset (int) – current position to readd from data

Return type

CmdSet

Returns

parse command

class spsdk.image.commands.CmdUnlock(engine=0, features=0, uid=0)¶

Bases: spsdk.image.commands.CmdUnlockAbstract

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)

info()¶

Text description of the command.

Return type: str

class spsdk.image.commands.CmdUnlockAbstract(engine=0, features=0, uid=0)¶

Bases: spsdk.image.commands.CmdBase, abc.ABC

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

Constructor.

Parameters

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

property engine¶

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

Return type: EnumEngine

export(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export to binary form (serialization).

Parameters: dbg_info (DebugInfo) – debug information about exported data
Return type: bytes
Returns: binary representation of the command

info()¶

Text description of the command.

Return type: str

static need_uid(engine, features)¶

Return True if given Engine and Feature requires UID.

Return type: bool

classmethod parse(data, offset=0)¶

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

Parameters

data (bytes) – being parsed
offset (int) – current position to readd from data

Return type

CmdUnlockAbstract

Returns

Unlock command

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

Bases: spsdk.image.commands.CmdUnlockAbstract

Command Unlock for Cryptographic Acceleration and Assurance Module .

Initialize.

Parameters: features (int) – mask of FEATURE_UNLOCK_x constants, defaults to 0

FEATURE_UNLOCK_MFG = 4¶

FEATURE_UNLOCK_MID = 1¶

FEATURE_UNLOCK_RNG = 2¶

info()¶

Text description of the command.

Return type: str

property unlock_mfg¶

Leave Zero is able Master Key write unlocked.

Return type: bool

property unlock_mid¶

Leave Job Ring and DECO master ID registers unlocked.

Return type: bool

property unlock_rng¶

Leave RNG un-instantiated.

Return type: bool

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

Bases: spsdk.image.commands.CmdUnlockAbstract

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

Initialize.

Parameters

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

FEATURE_UNLOCK_FLD_RTN = 1¶

FEATURE_UNLOCK_JTAG = 8¶

FEATURE_UNLOCK_SCS = 4¶

FEATURE_UNLOCK_SRK_RVK = 2¶

info()¶

Text description of the command.

Return type: str

property unlock_csc¶

Leave SCS register unlocked.

Return type: bool

property unlock_fld_rtn¶

Leave Field Return activation unlocked.

Return type: bool

property unlock_jtag¶

Unlock JTAG using SCS HAB_JDE bit.

Return type: bool

property unlock_srk_rvk¶

Leave SRK revocation unlocked.

Return type: bool

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

Bases: spsdk.image.commands.CmdUnlockAbstract

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

Constructor.

Parameters: features (int) – mask of FEATURE_UNLOCK_* constants

FEATURE_UNLOCK_LP_SWR = 1¶

FEATURE_UNLOCK_ZMK_WRITE = 2¶

info()¶

Text description of the command.

Return type: str

property unlock_lp_swr¶

Leave LP SW reset unlocked.

Return type: bool

property unlock_zmk_write¶

Leave Zero is able Master Key write unlocked.

Return type: bool

class spsdk.image.commands.CmdWriteData(numbytes=4, ops=0, data=None)¶

Bases: spsdk.image.commands.CmdBase

Write data command.

Initialize Write Data command.

Parameters

numbytes (int) – number of bytes. Must be value: 1, 2 or 4
ops (int) – 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(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export to binary form (serialization).

Parameters: dbg_info (DebugInfo) – debug information about exported data
Return type: bytes
Returns: binary representation of the command

info()¶

Text description of the command.

Return type: str

property num_bytes¶

Number of bytes being written by the command.

Return type: int

property ops¶

Type of write operation.

Return type: int

classmethod parse(data, offset=0)¶

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

Parameters

data (bytes) – being parsed
offset (int) – current position to readd from data

Return type

CmdWriteData

Returns

parse command

pop(index)¶

Pop of Write data command.

Return type: List[int]

class spsdk.image.commands.EnumAuthDat¶

Bases: spsdk.utils.easy_enum.Enum

Flags for Authenticate Data commands.

ABS = 1¶

CLR = 0¶

class spsdk.image.commands.EnumCAAM¶

Bases: spsdk.utils.easy_enum.Enum

CAAM Engine Configuration.

DEFAULT = 0¶

DSC_SWAP16 = 128¶

DSC_SWAP8 = 64¶

IN_SWAP16 = 2¶

IN_SWAP8 = 1¶

OUT_SWAP16 = 16¶

OUT_SWAP8 = 8¶

class spsdk.image.commands.EnumCertFormat¶

Bases: spsdk.utils.easy_enum.Enum

Certificate format tags.

AEAD = 163¶

BLOB = 187¶

CMS = 197¶

SRK = 3¶

X509 = 9¶

class spsdk.image.commands.EnumCheckOps¶

Bases: spsdk.utils.easy_enum.Enum

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

ALL_CLEAR = 0¶

ALL_SET = 1¶

ANY_CLEAR = 2¶

ANY_SET = 3¶

class spsdk.image.commands.EnumEngine¶

Bases: spsdk.utils.easy_enum.Enum

Engine plugin tags.

ANY = 0¶

CAAM = 29¶

CSU = 10¶

DCP = 27¶

DTCP = 34¶

HDCP = 36¶

OCOTP = 33¶

ROM = 54¶

RTIC = 5¶

SAHARA = 6¶

SCC = 3¶

SNVS = 30¶

SRTC = 12¶

SW = 255¶

class spsdk.image.commands.EnumInsKey¶

Bases: spsdk.utils.easy_enum.Enum

Flags for Install Key commands.

ABS = 1¶

CFG = 8¶

CID = 64¶

CLR = 0¶

CSF = 2¶

DAT = 4¶

FID = 16¶

HSH = 128¶

MID = 32¶

class spsdk.image.commands.EnumItm¶

Bases: spsdk.utils.easy_enum.Enum

Engine configuration flags of Set command.

ENG = 3¶

MID = 1¶

class spsdk.image.commands.EnumWriteOps¶

Bases: spsdk.utils.easy_enum.Enum

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

CLEAR_BITMASK = 2¶

SET_BITMASK = 3¶

WRITE_CLEAR_BITS = 1¶

WRITE_VALUE = 0¶

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

Bases: spsdk.exceptions.SPSDKError

CmdAuthData additional data block: expected Signature or MAC object.

Initialize the base SPSDK Exception.

spsdk.image.commands.parse_command(data, offset=0)¶

Parse CSF/DCD command.

Parameters

data (bytes) – binary data to be parsed
offset (int) – to start parsing

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: spsdk.image.header.Header

Command header.

Constructor.

Parameters

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

Raises

SPSDKError – If invalid command tag

classmethod parse(data, offset=0, required_tag=None)¶

Create Header from binary data.

Parameters

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

Return type

Header

Returns

parsed instance

Raises

UnparsedException – if required header tag does not match
SPSDKError – If invalid tag

property tag¶

Command tag.

Return type: CmdTag

class spsdk.image.header.CmdTag¶

Bases: spsdk.utils.easy_enum.Enum

CSF/DCD Command Tag.

AUT_DAT = 202¶

CHK_DAT = 207¶

INIT = 180¶

INS_KEY = 190¶

NOP = 192¶

SET = 177¶

UNLK = 178¶

WRT_DAT = 204¶

exception spsdk.image.header.CorruptedException¶

Bases: Exception

Corrupted Exception.

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

Bases: object

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

info()¶

Text representation of the header.

Return type: str

classmethod parse(data, offset=0, required_tag=None)¶

Parse header.

Parameters

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

Return type

Header

Returns

Header object

Raises

UnparsedException – if required header tag does not match

property size¶

Header size in bytes.

Return type: int

property tag¶

Return type: int
Returns: section tag: command tag or segment tag, …

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

Bases: spsdk.image.header.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

length: int¶

param: int¶

classmethod parse(data, offset=0, required_tag=None)¶

Parse header.

Parameters

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

Raises

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

Return type

Header

Returns

Header2 object

class spsdk.image.header.SegTag¶

Bases: spsdk.utils.easy_enum.Enum

Segments Tag.

BIC1 = 135¶

CRT = 215¶

CSF = 212¶

DCD = 210¶

EVT = 219¶

IVT2 = 209¶

IVT3 = 222¶

MAC = 172¶

RVT = 221¶

SIG = 216¶

SIGB = 144¶

WRP = 129¶

exception spsdk.image.header.UnparsedException¶

Bases: Exception

Unparsed Exception.

Secret Module¶

Commands and responses used by SDP module.

class spsdk.image.secret.BaseClass(tag, version=64)¶

Bases: object

Base SPSDK class.

Constructor.

Parameters

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

export(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Serialization to binary form.

Parameters: dbg_info (DebugInfo) – optional instance allowing to debug exported data; provides commented export
Return type: bytes
Returns: binary representation of the instance

info()¶

Description about the instance.

Return type: str

property size¶

Size of the exported binary data.

Return type: int

property version¶

Format version.

Return type: int

property version_major¶

Major format version.

Return type: int

property version_minor¶

Minor format version.

Return type: int

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

Bases: spsdk.image.secret.BaseClass

Certificate structure for bootable image.

Initialize the certificate structure for bootable image.

export(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export.

Return type: bytes

info()¶

String representation of the CertificateImg.

Return type: str

classmethod parse(data, offset=0)¶

Parse.

Return type: CertificateImg

property size¶

Size of Certificate structure for bootable image.

Return type: int

class spsdk.image.secret.EnumAlgorithm¶

Bases: spsdk.utils.easy_enum.Enum

Algorithm types.

AES = 85¶

ANY = 0¶

BLOB = 113¶

CCM = 102¶

CIPHER = 5¶

EC = 4¶

F = 3¶

HASH = 1¶

MODE = 6¶

PKCS1 = 33¶

SHA1 = 17¶

SHA256 = 23¶

SHA512 = 27¶

SIG = 2¶

WRAP = 7¶

class spsdk.image.secret.EnumSRK¶

Bases: spsdk.utils.easy_enum.Enum

Entry type in the System Root Key Table.

KEY_HASH = 238¶

KEY_PUBLIC = 225¶

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

Bases: spsdk.image.secret.BaseClass

Structure that holds initial parameter for AES encryption/description.

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¶

NONCE and MAC bytes joined together.

Return type: bytes

export(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export instance into binary form (serialization).

Parameters: dbg_info (DebugInfo) – optional instance providing debug info about exported content
Return type: bytes
Returns: binary form

info()¶

Text info about the instance.

Return type: str

property mac¶

MAC bytes for the encryption/decryption.

Return type: bytes

property nonce¶

NONCE bytes for the encryption/decryption.

Return type: bytes

classmethod parse(data, offset=0)¶

Parse binary data and creates the instance (deserialization).

Parameters

data (bytes) – being parsed
offset (int) – to start parse the data

Return type

MAC

Returns

the instance

property size¶

Size of binary representation in bytes.

Return type: int

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 uncrypted 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: spsdk.image.secret.SRKException

This SRK public key algorithm is not yet implemented.

Initialize the base SPSDK Exception.

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

Bases: spsdk.image.secret.SRKException

This type of SRK table item is not implemented.

Initialize the base SPSDK Exception.

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

Bases: spsdk.image.secret.SRKException

This SRK public key algorithm is not yet implemented.

Initialize the base SPSDK Exception.

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

Bases: spsdk.exceptions.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¶

Data of Secret Key Blob.

Return type: bytes

export()¶

Export of Secret Key Blob.

Return type: bytes

info()¶

String representation of the Secret Key Blob.

Return type: str

classmethod parse(data, offset=0)¶

Parse of Secret Key Blob.

Return type: SecretKeyBlob

property size¶

Size of Secret Key Blob.

Return type: int

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

Bases: spsdk.image.secret.BaseClass

Class representing a signature.

Initialize the signature.

property data¶

Signature data.

Return type: bytes

export(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export.

Return type: bytes

info()¶

String representation of the signature.

Return type: str

classmethod parse(data, offset=0)¶

Parse.

Return type: Signature

property size¶

Size of a signature.

Return type: int

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(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Serialization to binary form.

Parameters: dbg_info (DebugInfo) – optional instance allowing to debug exported data; provides commented export
Return type: bytes
Returns: binary representation of the instance

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.

Return type: SrkItem

info()¶

Description about the instance.

Return type: str

classmethod parse(data, offset=0)¶

Pick up the right implementation of an SRK item.

Parameters

data (bytes) – The bytes array of SRK segment
offset (int) – The offset of input data

Return type

SrkItem

Returns

SrkItem: One of the SrkItem subclasses

Raises

NotImplementedSRKPublicKeyType – Unsupported key algorithm
NotImplementedSRKItem – Unsupported tag

sha256()¶

Export SHA256 hash of the original data.

Return type: bytes

property size¶

Size of the exported binary data.

Return type: int

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

Bases: spsdk.image.secret.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¶

Hashing algorithm used.

Return type: int

export(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export.

Return type: bytes

hashed_entry()¶

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

Return type: SrkItemHash

info()¶

String representation of SrkItemHash.

Return type: str

classmethod parse(data, offset=0)¶

Parse SRK table item data.

Parameters

data (bytes) – The bytes array of SRK segment
offset (int) – The offset of input data

Return type

SrkItemHash

Returns

SrkItemHash: SrkItemHash object

Raises

NotImplementedSRKItem – Unknown tag

sha256()¶

Export SHA256 hash of the original data.

Return type: bytes

property size¶

Size of an SRK item.

Return type: int

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

Bases: spsdk.image.secret.SrkItem

RSA public key in SRK Table, see SrkTable class.

Initialize the srk table item.

property algorithm¶

Algorithm.

Return type: int

export(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export.

Return type: bytes

property flag¶

Flag.

Return type: int

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

info()¶

String representation of SrkItemRSA.

Return type: str

property key_length¶

Key length of Item in SRK Table.

Return type: int

classmethod parse(data, offset=0)¶

Parse SRK table item data.

Parameters

data (bytes) – The bytes array of SRK segment
offset (int) – The offset of input data

Return type

SrkItemRSA

Returns

SrkItemRSA: SrkItemRSA object

sha256()¶

Export SHA256 hash of the data.

Return type: bytes

property size¶

Size of an SRK item.

Return type: int

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

Bases: spsdk.image.secret.BaseClass

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(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export into binary form (serialization).

Parameters: dbg_info (DebugInfo) – optional instance allowing to debug exported content
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

info()¶

Text info about the instance.

Return type: str

classmethod parse(data, offset=0)¶

Parse of SRK table.

Return type: SrkTable

property size¶

Size of SRK table.

Return type: int

Data Segments¶

Segments within image module.

class spsdk.image.segments.AbstractFCB¶

Bases: spsdk.image.segments.BaseSegment

Abstract class, predecessor for all FCB classes.

Constructor.

TAG = b'FCB'¶

property enabled¶

Whether FCB is enabled. Note: it is not generated to output is disabled.

Return type: bool

export(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export to binary representation (serialization).

Parameters: dbg_info (DebugInfo) – instance allowing to debug output
Return type: bytes
Returns: binary representation

property space¶

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

Return type: int

class spsdk.image.segments.BaseSegment¶

Bases: abc.ABC

Base segment.

Initialize the base segment.

PADDING_VALUE = 0¶

export()¶

Export interface.

Return type: bytes

info()¶

String representation of the BaseSegment.

Return type: str

property padding_len¶

Length of padding data in bytes (zero for no padding).

Return type: int

classmethod parse(buffer)¶

Parse interfaces.

Return type: BaseSegment

property size¶

Size of base segment.

Return type: int

property space¶

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

Please mind, padding is exported optionally.

Return type: int

class spsdk.image.segments.FlexSPIConfBlockFCB¶

Bases: spsdk.image.segments.AbstractFCB

Flex SPI configuration block; FCB.

Initialize FlexSPIConfBlockFCB.

FORMAT = '<6BH7I5I4B2I4I6I4H'¶

TAG = b'FCFB'¶

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

export(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export into binary form.

Parameters: dbg_info (DebugInfo) – instance allowing to debug output
Return type: bytes
Returns: binary representation used in the bootable image

export_header()¶

Export FCB header info binary form.

Return type: bytes

info()¶

String representation of the FlexSPIConfBlockFCB.

Return type: str

classmethod parse(buffer)¶

Parse binary data and creates instance of the class.

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

property size¶

Length of the binary exported data without padding.

Return type: int

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

Bases: spsdk.image.segments.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(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export to binary form (serialization).

Parameters: dbg_info (DebugInfo) – instance allowing to debug output format
Return type: bytes
Returns: binary representation

info()¶

Return text description of the instance.

Return type: str

property size¶

Return size of the exported data in bytes.

Return type: int

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

Bases: spsdk.image.segments.BaseSegment

APP segment.

Initialize APP segment.

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

property data¶

Application binary data.

Return type: Optional[bytes]

export()¶

Export segment as bytes array.

Return type: bytes
Returns: bytes

info()¶

String representation of the SegAPP.

Return type: str

property size¶

Size of APP segment.

Return type: int

class spsdk.image.segments.SegBDS3a¶

Bases: spsdk.image.segments.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¶

Header’s size of BDS3a segment.

Return type: int

info()¶

String representation of the SegBDS3a.

Return type: str

classmethod parse(data)¶

Parse segment from bytes array.

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

property size¶

Size of BDS3a segment.

Return type: int

class spsdk.image.segments.SegBDS3b¶

Bases: spsdk.image.segments.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¶

Size of header of BDS3b segment.

Return type: int

info()¶

String representation of the SegBDS3b.

Return type: str

classmethod parse(data)¶

Parse segment from bytes array.

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

property size¶

Size of BDS3b segment.

Return type: int

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

Bases: spsdk.image.segments.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

info()¶

String representation of the SegBDT.

Return type: str

classmethod parse(data)¶

Parse segment from bytes array.

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

property plugin¶

Plugin.

Return type: int

property size¶

Size of the exported binary data (without padding).

Return type: int

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

Bases: spsdk.image.segments.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(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Serialization to binary representation.

Parameters: dbg_info (DebugInfo) – instance allowing to provide debug info about exported data
Return type: bytes
Returns: binary representation of the region (serialization).

info()¶

Return type: str
Returns: test description of the instance.

classmethod parse(data, offset=0, decrypt_keys=[])¶

Deserialization.

Parameters

data (bytes) – binary data to be parsed
offset (int) – to start parsing the data
decrypt_keys (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

SegBEE

Returns

instance created from binary data

property size¶

Return type: 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: spsdk.image.segments.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

info()¶

String representation of the SegBIC1.

Return type: str

classmethod parse(data)¶

Parse segment from bytes array.

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

property size¶

Size.

Return type: int

validate()¶

Validate segment.

Return type: None

property version¶

Version of Boot Images Container segment.

Return type: int

class spsdk.image.segments.SegBIM¶

Bases: spsdk.image.segments.BaseSegment

BootImage segment.

Initialize BootImage segment.

FORMAT = '<2L2Q2L'¶

SIZE = 128¶

export()¶

Export segment as bytes array.

Return type: bytes
Returns: bytes

info()¶

String representation of the SegBIM.

Return type: str

classmethod parse(data)¶

Parse segment from bytes array.

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

property size¶

Size of BootImage segment.

Return type: int

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

Bases: spsdk.image.segments.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 of CSF commands in the segment.

Return type: List[CmdBase]

export(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export segment as bytes array (serialization).

Parameters: dbg_info (DebugInfo) – optional list of strings to produce debug information about exported data
Return type: bytes
Returns: bytes

info()¶

String representation of the SegCSF.

Return type: str

property macs¶

Iterator of all MAC sections.

Return type: Iterator[MAC]

classmethod parse(data, offset=0)¶

Parse segment from bytes array.

Parameters

data (bytes) – The bytes array of CSF segment
offset (int) – to start parsing the data

Raises

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

Return type

SegCSF

Returns

SegCSF instance

property size¶

Size of the binary representation of the segment; 0 is not enabled.

Return type: int

property space¶

Size of the binary representation of the segment including padding; 0 is not enabled.

Return type: int

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¶

Version of CSF segment.

Return type: int

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

Bases: spsdk.image.segments.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¶

Commands of Device configuration data (DCD) segment.

Return type: List[CmdBase]

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 of Device configuration data (DCD) segment.

Return type: Header

info()¶

String representation of the SegDCD.

Return type: str

classmethod parse(data)¶

Parse segment from bytes array.

Parameters: data (bytes) – The bytes array of DCD segment
Raises: CorruptedException – Exception caused by corrupted data
Return type: SegDCD
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¶

Size of Device configuration data (DCD) segment.

Return type: int

property space¶

Add space.

Return type: int

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
Raises: SyntaxError – if input format is not valid

class spsdk.image.segments.SegFCB¶

Bases: spsdk.image.segments.AbstractFCB, abc.ABC

FCB.

Initialize FCB segment.

FINGERPRINT = b'NFCB'¶

SIZE = 1024¶

property crc¶

Cyclic redundancy check.

Return type: int

export(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Export to binary form.

Return type: bytes

class spsdk.image.segments.SegIDS3a¶

Bases: spsdk.image.segments.BaseSegment

IDS3a segment.

Initialize IDS3a segment.

FORMAT = '<3Q4L'¶

SIZE = 40¶

export()¶

Export segment as bytes array.

Return type: bytes
Returns: bytes

info()¶

String representation of the SegIDS3a.

Return type: str

classmethod parse(data)¶

Parse segment from bytes array.

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

property size¶

Size of IDS3a segment.

Return type: int

class spsdk.image.segments.SegIDS3b¶

Bases: spsdk.image.segments.BaseSegment

IDS3b segment.

Initialize IDS3b segment.

FORMAT = '<3Q2L'¶

SIZE = 32¶

export()¶

Export segment as bytes array.

Return type: bytes
Returns: bytes

info()¶

String representation of the SegIDS3b.

Return type: str

classmethod parse(data)¶

Parse segment from bytes array.

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

property size¶

Size of IDS3b segment.

Return type: int

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

Bases: spsdk.image.segments.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

info()¶

String representation of the SegIVT2.

Return type: str

classmethod parse(data)¶

Parse segment from bytes array.

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

property size¶

Size of the binary data.

Return type: int

validate()¶

Validate settings of the segment.

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

property version¶

The version of IVT and Image format.

Return type: int

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

Bases: spsdk.image.segments.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 of IVT3a segment.

Return type: Header

info()¶

String representation of the SegIVT3a.

Return type: str

classmethod parse(data)¶

Parse segment from bytes array.

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

property size¶

Size of IVT3a segment.

Return type: int

validate()¶

Validation of IVT3a segment.

Return type: None

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

Bases: spsdk.image.segments.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 of IVT3b segment.

Return type: Header

info()¶

String representation of the SegIVT3b.

Return type: str

classmethod parse(data)¶

Parse segment from bytes array.

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

property size¶

Size of IVT3b segment.

:return size

Return type: int

validate()¶

Validation of IVT3b segment.

Return type: None

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

Bases: spsdk.image.segments.BaseSegment

SignatureBlock segment.

Initialize SignatureBlock segment.

FORMAT = '<4HL'¶

SIZE = 16¶

export()¶

Export segment as bytes array.

Return type: bytes
Returns: bytes

info()¶

String representation of the SegSIGB.

Return type: str

classmethod parse(data)¶

Parse segment from bytes array.

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

property size¶

Size of Signature Block segment.

Return type: int

property version¶

Version of Signature Block segment.

Return type: int

TrustZone¶

Module provides support for TrustZone configuration data.

class spsdk.image.trustzone.TrustZone(tz_type=0, family=None, revision=None, 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=None)¶

Alternate constructor for CUSTOM type of TrustZone.

Return type: TrustZone

classmethod disabled()¶

Alternate constructor for DISABLED type of TrustZone.

Return type: TrustZone

classmethod enabled()¶

Alternate constructor for ENABLED type of TrustZone.

Return type: TrustZone

export()¶

Return the TrustZone data as bytes.

Return type: bytes

classmethod from_binary(family, raw_data, revision=None)¶

Alternate constructor using existing binary data.

Return type: TrustZone

get_families()¶

Return list of supported chip families.

Return type: list

get_latest_revision(family=None)¶

Return latest revision for given family.

Return type: str

get_revisions(family=None)¶

Return a list of revisions for given family.

Return type: list

sanitize_revision(family, revision)¶

Sanitize revision.

if the ‘revision’ is None return the latest revision if the ‘revision’ is provided return it as lower-case

Return type: str

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¶

Bases: spsdk.utils.easy_enum.Enum

Enum defining various types of TrustZone types.

CUSTOM = 32¶

DISABLED = 64¶

ENABLED = 0¶

Support for BEE encryption for RT10xx devices¶

Contains support for BEE encryption for RT10xx devices.

class spsdk.image.bee.BeeBaseClass¶

Bases: object

BEE base class.

export()¶

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

info()¶

Return type: str
Returns: text description of the instance.

classmethod parse(data, offset=0)¶

Deserialization.

Parameters

data (bytes) – binary data to be parsed
offset (int) – to start parsing the data

Return type

Any

Returns

instance created from binary data; this method returns just 0

Raises

SPSDKError – If size of the data is not sufficient

property size¶

Return type: 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: spsdk.image.bee.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¶

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

export()¶

Exports the binary representation.

Return type: bytes

info()¶

Return type: str
Returns: test description of the instance.

classmethod parse(data, offset=0)¶

Deserialization.

Parameters

data (bytes) – binary data to be parsed
offset (int) – to start parsing the data

Return type

BeeFacRegion

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: spsdk.image.bee.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

info()¶

Return type: str
Returns: test description of the instance.

classmethod parse(data, offset=0)¶

Deserialization.

Parameters

data (bytes) – binary data to be parsed
offset (int) – to start parsing the data

Return type

BeeKIB

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.BeeProtectRegionBlock(encr_mode=1, lock_options=0, counter=None)¶

Bases: spsdk.image.bee.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¶

Return type: int
Returns: number of Factory Access Control regions.

info()¶

Return type: str
Returns: test description of the instance.

classmethod parse(data, offset=0)¶

Deserialization.

Parameters

data (bytes) – binary data to be parsed
offset (int) – to start parsing the data

Return type

BeeProtectRegionBlock

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¶

Bases: spsdk.utils.easy_enum.Enum

AES mode selection for BEE PRDB encryption.

CTR = 1¶

ECB = 0¶

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

Bases: spsdk.image.bee.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 = 1024¶

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(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶

Serialization to binary representation.

Parameters: dbg_info (DebugInfo) – instance allowing to provide debug info about exported data
Return type: bytes
Returns: binary representation of the region (serialization).

property fac_regions¶

Return type: Sequence[BeeFacRegion]
Returns: lift of Factory Access Control regions.

info()¶

Return type: str
Returns: test description of the instance.

classmethod parse(data, offset=0, sw_key=b'')¶

Deserialization.

Parameters

data (bytes) – binary data to be parsed
offset (int) – to start parsing the data
sw_key (bytes) – SW key used to decrypt the EKIB data (the key is marked as SW_GP2 on RT10xx)

Return type

BeeRegionHeader

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¶

Bases: spsdk.utils.easy_enum.Enum

Device key source.

KEYSTORE = 1¶

OTP = 0¶

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¶

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

info()¶

Information about key store in text form.

Return type: str

property key_source¶

Device key source.

Return type: KeySourceType

Master Boot Image¶

Master Boot Image.

class spsdk.image.mbimg.MasterBootImage(app, load_addr, image_type=0, trust_zone=None, app_table=None, cert_block=None, priv_key_pem_data=None, hmac_key=None, key_store=None, enable_hw_user_mode_keys=False, ctr_init_vector=None)¶

Bases: object

Basic representation of Master Boot Image layout.

Constructor.

Parameters

app (Union[bytes, bytearray]) – input image (binary)
load_addr (int) – address in RAM, where ‘RAM’ image will be copied; for XIP images address, where the image is located in FLASH memory
image_type (MasterBootImageType) – type of the master boot image
trust_zone (Optional[TrustZone]) – TrustZone instance; None to use default settings (TrustZone enabled)
app_table (Optional[MultipleImageTable]) – optional table with additional images; None if no additional images needed
cert_block (Optional[CertBlock]) – block of certificates; None for unsigned image
priv_key_pem_data (Optional[bytes]) – private key to sign the image, decrypted binary data in PEM format
hmac_key (Union[bytes, str, None]) – optional key for HMAC generation (either binary ot HEX string; 32 bytes); None if HMAC is not in the image If key_store.key_source == KeySourceType.KEYSTORE, this is a user-key from key-store If key_store.key_source == KeySourceType.OTP, this is a master-key burned in OTP
key_store (Optional[KeyStore]) – optional key store binary content; None if key store is not in the image
enable_hw_user_mode_keys (bool) – flag for controlling secure hardware key bus. If true, then it is possible to access keys on hardware secure bus from non-secure application, else non-secure application will read zeros.
ctr_init_vector (Optional[bytes]) – optional initial vector for encryption counter; None to use random vector

Raises

SPSDKError – If type is not binary data
SPSDKError – If images are not loaded from RAM
SPSDKError – If invalid address

CERTIFICATE_OFFSET = 40¶

CRC_BLOCK_OFFSET = 40¶

HMAC_OFFSET = 64¶

HMAC_SIZE = 32¶

IMAGE_FLAGS_OFFSET = 36¶

IMAGE_LENGTH_OFFSET = 32¶

LOAD_ADDR_OFFSET = 52¶

property app_len¶

Length of binary app data; this includes also size of the relocation table.

Return type: int

property data¶

Plain, unsigned binary data for the image.

It consists of: - application image - optionally trust zone data Please mind the result does not contain: certification block, HMAC, keystore and signature

Return type: bytes

export()¶

Master boot image (binary).

Raises

SPSDKError – If private key not present
SPSDKError – If wrong private key

Return type

bytes

Returns

exported bytes

info()¶

Text description of the instance.

Return type: str

classmethod parse(data, offset=0, **kwargs)¶

Parse.

Return type: None

property total_len¶

Total length of the image.

It is sum of: - image length + length of trust zone data - HMAC length - KeyStore length - certificate length (+ for encrypted images also encrypted header and CRT init vector) - signature length

Return type: int

class spsdk.image.mbimg.MasterBootImageManifest(firmware_version, trust_zone, sign_hash_len=None)¶

Bases: object

MasterBootImage Manifest used in LPC55s3x.

Initialize MBI Manifest object.

Parameters

firmware_version (int) – firmware version
sign_hash_len (Optional[int]) – length of hash used for singing, defaults to None
trust_zone (TrustZone) – TrustZone instance, defaults to None

DIGEST_PRESENT_FLAG = 2147483648¶

FORMAT = '<4s4L'¶

FORMAT_VERSION = 65536¶

MAGIC = b'imgm'¶

export()¶

Serialize MBI Manifest.

Return type: bytes

class spsdk.image.mbimg.MasterBootImageN4Analog(app, load_addr, firmware_version, sign_hash_len=0, signature_provider=None, **kwargs)¶

Bases: spsdk.image.mbimg.MasterBootImage

Master Boot Image layout specific for LPC55s3x.

Initialize MBI for LPC55s3x.

Parameters

app (bytes) – application binary
load_addr (int) – Address where to load application
firmware_version (int) – Firmware version, defaults to None
sign_hash_len (int) – Length of hash used for singing, defaults to 0
signature_provider (Optional[SignatureProvider]) – Signature provider meant to sign the image
kwargs (Any) – keyword arguments passed to MasterBootImage

Raises

SPSDKError – If trustZone was not set in parent class

property data¶

Plain, unsigned binary data for the image.

It consists of: - application image - image manifest for signed image types - optionally trust zone data Please mind the result does not contain: certification block, HMAC, keystore and signature :raises SPSDKError: If certificate Block is not set :raises SPSDKError: If masterBootImageManifest is not set :raises SPSDKError: If signature provider is not set :raises SPSDKError: If signature is not set

Return type: bytes

export()¶

Master boot image (binary).

Return type: bytes

property total_len¶

Return the total (expected) length of the image.

Raises

SPSDKError – If MasterBootImageManifest is not set
SPSDKError – If certificate Block is not set

Return type

int

Returns

total length of the image

class spsdk.image.mbimg.MasterBootImageType¶

Bases: spsdk.utils.easy_enum.Enum

Enumeration of various types of MBIs.

CRC_RAM_IMAGE = 2¶

CRC_XIP_IMAGE = 5¶

ENCRYPTED_RAM_IMAGE = 3¶

PLAIN_IMAGE = 0¶

SIGNED_RAM_IMAGE = 1¶

SIGNED_XIP_IMAGE = 4¶

SIGNED_XIP_NXP_IMAGE = 8¶

static has_crc(image_type)¶

True is the image type contains CRC; False otherwise.

Return type: bool

static has_hmac(image_type)¶

Whether the image contains HMAC.

Return type: bool

static is_copied_to_ram(image_type)¶

True is the image type is copied and executed in RAM.

Return type: bool

static is_encrypted(image_type)¶

True is the image type is encrypted; False otherwise.

Return type: bool

static is_signed(image_type)¶

True is the image type is signed; False otherwise.

Return type: bool

static is_xip(image_type)¶

True is the image type is executed in place (XIP).

Return type: bool

class spsdk.image.mbimg.MultipleImageEntry(img, dst_addr, flags=1)¶

Bases: object

The class represents an entry in relocation table.

It also contains a corresponding image (binary)

Constructor.

Parameters

img (bytes) – binary image data
dst_addr (int) – destination address
flags (int) – see LTI constants

Raises

SPSDKError – If invalid destination address
SPSDKError – Other section types (INIT) are not supported

LTI_LOAD = 1¶

property dst_addr¶

Destination address.

Return type: int

export_entry()¶

Export relocation table entry in binary form.

Return type: bytes

export_image()¶

Binary image aligned to the 4-bytes boundary.

Return type: bytes

property flags¶

Flags, currently not used.

Return type: int

property image¶

Binary image data.

Return type: bytes

property is_load¶

True if entry represents LOAD section.

Return type: bool

property size¶

Size of the image (not aligned).

Return type: int

property src_addr¶

Source address; this value is calculated automatically when building the image.

Return type: int

class spsdk.image.mbimg.MultipleImageTable¶

Bases: object

The class allows to merge several images into single image and add relocation table.

It can be used for multicore images (one image for each core) or trustzone images (merging secure and non-secure image)

Initialize the Multiple Image Table.

add_entry(entry)¶

Add entry into relocation table.

Parameters: entry (MultipleImageEntry) – to add
Return type: None

property entries¶

List of all entries.

Return type: Sequence[MultipleImageEntry]

export(start_addr)¶

Export.

Parameters: start_addr (int) – start address where the images are exported; the value matches source address for the first image
Return type: bytes
Returns: images with relocation table
Raises: SPSDKError – If there is no entry for export

property header_version¶

Format version of the structure for the header.

Return type: int

reloc_table(start_addr)¶

Relocate table.

Parameters: start_addr (int) – start address of the relocation table
Return type: bytes
Returns: export relocation table in binary form