Image Module API

Contents

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: 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=EnumAppType.APP, 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: 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 value type is incorrect

  • SPSDKError – Raised when there is not an i.MX Boot Image

Return type:

BootImg2

Returns:

BootImg2 object

property plugin: bool#

Plugin.

property size: int#

Size of IMX Boot Image v2..

property version: int#

Version of IMX Boot Image v2.

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

Bases: 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=EnumAppType.APP, 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: List[SegBDS3a]#

BDT.

property csf: SegCSF#

CSF.

export()#

Export Image as binary blob.

Return type:

bytes

property ivt: List[SegIVT3a]#

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 values type is incorrect

  • SPSDKError – Raised when there is not an i.MX Boot Image

Return type:

BootImgBase

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.APP, 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:
Return type:

BootImgBase

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:

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: 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.APP, 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:

BootImgBase

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

None

add_dcd_bin(data)#

Add DCD binary data.

Parameters:

data (bytes) – DCD binary data to be added

Raises:
Return type:

None

add_image(data, img_type=EnumAppType.APP, 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, 2, 2, 14, 45, 37, 438951, 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:
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, 2, 2, 14, 45, 37, 438943, 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:

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=EnumAuthDat.CLR, key_index=1, sig_format=EnumCertFormat.CMS, engine=EnumEngine.ANY, 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.ALL_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:
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.ANY, 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.CLR, cert_fmt=EnumCertFormat.SRK, hash_alg=EnumAlgorithm.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.ENG, hash_alg=EnumAlgorithm.ANY, engine=EnumEngine.ANY, 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.ANY, features=0, uid=0)#

Bases: 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)

class spsdk.image.commands.CmdUnlockAbstract(engine=EnumEngine.ANY, 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 (int) – 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)#

Bases: 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#
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)#

Bases: 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#
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)#

Bases: 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#
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.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:
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.

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:
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)#

Bases: BaseSecretClass

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)#

Bases: BaseSecretClass

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:
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)#

Bases: BaseSecretClass

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:
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)#

Bases: BaseSecretClass

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:
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:
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:
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:
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:
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(family, revision='latest')#

Get memory types data from database.

Parameters:
  • family (str) – Chip family.

  • revision (str) – Optional Chip family revision.

Return type:

Dict

classmethod get_supported_families()#

Return list of supported families.

Return type:

List

Returns:

List of supported families.

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

Get list of supported memory types data from database.

Parameters:
  • family (str) – Chip family.

  • revision (str) – Optional Chip family revision.

Return type:

List[str]

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.ENABLED, 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:
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.CTR, 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