SBFile Module API

Module implementing SBFile.

SBFile Version 1

Module implementing SBFile version 1.

class spsdk.sbfile.sb1.BcdVersion3(major=1, minor=0, service=0)

Bases: object

Version in format #.#.#, where # is BCD number (1-4 digits).

Initialize BcdVersion3.

Parameters:

major (int) – number in BCD format, 1-4 decimal digits
minor (int) – number in BCD format, 1-4 decimal digits
service (int) – number in BCD format, 1-4 decimal digits

Raises:

SPSDKError – Invalid version

DEFAULT = '999.999.999'

static from_str(text)

Convert string to BcdVersion instance.

Parameters:: text (str) – version in format #.#.#, where # is 1-4 decimal digits
Return type:: BcdVersion3
Returns:: BcdVersion3 instance
Raises:: SPSDKError – If format is not valid

property nums: Sequence[int]: Return array of version numbers: [major, minor, service].

static to_version(input_version)

Convert different input formats into BcdVersion3 instance.

Parameters:: input_version (Union[BcdVersion3, str]) – either directly BcdVersion3 or string
Raises:: SPSDKError – Raises when the format is unsupported
Return type:: BcdVersion3
Returns:: BcdVersion3 instance

class spsdk.sbfile.sb1.BootSectionV1(section_id, flags=0)

Bases: BaseClass

Boot Section for SB file 1.x.

Initialize BootSectionV1.

Parameters:

section_id (int) – unique section ID, 32-bit int
flags (SecureBootFlagsV1) – see SecureBootFlagsV1

append(cmd)

Append command.

Parameters:: cmd (CmdBaseClass) – to be added
Return type:: None

property bootable: bool: Return whether section is bootable.

property cmd_size: int: Return size of the binary representation of the commands.

property commands: Sequence[CmdBaseClass]: Return sequence of all commands in the section.

export()

Return binary representation of the class (serialization).

Return type:: bytes

property flags: SecureBootFlagsV1: Return section flags.

classmethod parse(data)

Deserialization from binary format.

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

property rom_last_tag: bool

ReturnROM_LAST_TAG flag.

The last section header in an image always has its ROM_LAST_TAG flag set to help the ROM know at what point to stop searching.

property section_id: int: Return unique ID of the section, 32 number.

property size: int: Return size of the binary representation of the section in bytes.

update()

Update settings.

Return type:: None

class spsdk.sbfile.sb1.CmdCall(address=0, argument=0)

Bases: CmdBaseClass

Command Call.

The call statement is used for inserting a bootloader command that executes a function from one of the files that are loaded into the memory.

Initialize Command Call.

property address: int: Return command’s address.

property argument: int: Return command’s argument.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: Command Call object
Raises:: SPSDKError – If incorrect header tag

class spsdk.sbfile.sb1.CmdErase(address=0, length=0, flags=0, mem_id=0)

Bases: CmdBaseClass

Command Erase class.

Initialize Command Erase.

property address: int: Return command’s address.

property flags: int: Return command’s flag.

property length: int: Return command’s count.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: Command Erase object
Raises:: SPSDKError – If incorrect header tag

class spsdk.sbfile.sb1.CmdFill(address, pattern, length=None)

Bases: CmdBaseClass

Command Fill class.

Initialize Command Fill.

Parameters:

address (int) – to write data
pattern (int) – data to be written
length (Optional[int]) – length of data to be filled, defaults to 4

Raises:

SPSDKError – Raised when size is not aligned to 4 bytes

PADDING_VALUE = 0

property address: int: Return address of the command Fill.

export()

Return command in binary form (serialization).

Return type:: bytes

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: Command Fill object
Raises:: SPSDKError – If incorrect header tag

property pattern: bytes: Return binary data to fill.

property raw_size: int: Calculate raw size of header.

class spsdk.sbfile.sb1.CmdJump(address=0, argument=0, spreg=None)

Bases: CmdBaseClass

Command Jump class.

Initialize Command Jump.

property address: int: Return address of the command Jump.

property argument: int: Return command’s argument.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: Command Jump object
Raises:: SPSDKError – If incorrect header tag

property spreg: int | None: Return command’s Stack Pointer.

class spsdk.sbfile.sb1.CmdLoad(address, data, mem_id=0)

Bases: CmdBaseClass

Command Load. The load statement is used to store data into the memory.

Initialize CMD Load.

property address: int: Return address in target processor to load data.

export()

Export command as binary.

Return type:: bytes

property flags: int: Return command’s flag.

classmethod parse(data)

Parse command from bytes.

Parameters:

data (bytes) – Input data as bytes

Return type:

Self

Returns:

CMD Load object

Raises:

SPSDKError – Raised when there is invalid CRC
SPSDKError – When there is incorrect header tag

property raw_size: int: Return aligned size of the command including header and data.

class spsdk.sbfile.sb1.CmdMemEnable(address, size, mem_id)

Bases: CmdBaseClass

Command to configure certain memory.

Initialize CmdMemEnable.

Parameters:

address (int) – source address with configuration data for memory initialization
size (int) – size of configuration data used for memory initialization
mem_id (int) – identification of memory

property address: int: Return command’s address.

property flags: int: Return command’s flag.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: Command Memory Enable object
Raises:: SPSDKError – If incorrect header tag

property size: int: Return command’s size.

class spsdk.sbfile.sb1.CmdNop

Bases: CmdBaseClass

Command NOP class.

Initialize Command Nop.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: CMD Nop object
Raises:: SPSDKError – When there is incorrect header tag

class spsdk.sbfile.sb1.CmdProg(address, mem_id, data_word1, data_word2=0, flags=0)

Bases: CmdBaseClass

Command Program class.

Initialize CMD Prog.

property address: int: Return address in target processor to program data.

property data_word1: int: Return data word 1.

property data_word2: int: Return data word 2.

property flags: int: Return command’s flag.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: parsed command object
Raises:: SPSDKError – If incorrect header tag

class spsdk.sbfile.sb1.CmdReset

Bases: CmdBaseClass

Command Reset class.

Initialize Command Reset.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: Cmd Reset object
Raises:: SPSDKError – If incorrect header tag

class spsdk.sbfile.sb1.CmdTag

Bases: CmdBaseClass

Command TAG class.

It is also used as header for boot section for SB file 1.x.

Initialize Command Tag.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: parsed instance
Raises:: SPSDKError – When there is incorrect header tag

class spsdk.sbfile.sb1.SecureBootFlagsV1

Bases: Enum

Flags for SectionHeader.

NONE = 0

ROM_SECTION_BOOTABLE = 1

ROM_SECTION_CLEARTEXT = 2

class spsdk.sbfile.sb1.SecureBootV1(version='1.0', flags=0, drive_tag=0, product_version='999.999.999', component_version='999.999.999', dek=None, mac=None, digest=b'\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00', timestamp=None)

Bases: BaseClass

SB file 1.x.

Initialize Secure Boot Image V1.x.

Parameters:

version (str) – string in format #.# Major version of the boot image format, currently 1. Minor version of the boot image format, currently 1 or 2.
flags (int) – for the header, 0 by default: Flags associated with the entire image.
product_version (Union[BcdVersion3, str]) – Product version.
component_version (Union[BcdVersion3, str]) – Component version.
drive_tag (int) – For header: identifier for the disk drive or partition containing this image.
dek (Optional[bytes]) – DEK key for encrypted SB file; this is not supported yet
mac (Optional[bytes]) – MAC for encrypted SB file, this is not supported yet
digest (bytes) – SHA-1 digest of all fields of the header (it will be updated before export anyway) The first 16 bytes (of 20 total) also act as the initialization vector for CBC-encrypted regions.
timestamp (Optional[datetime]) – datetime of the file creation, use None for current date/time Fixed value should be used only for regression testing to generate same results

append(section)

Add section into the SB file.

Parameters:: section (BootSectionV1) – to be added
Return type:: None

export(header_padding8=None, auth_padding=None)

Serialization to binary form.

Parameters:

header_padding8 (Optional[bytes]) – optional header padding, 8-bytes; recommended to use None to apply random value
auth_padding (Optional[bytes]) – optional padding used after authentication; recommended to use None to apply random value

Return type:

bytes

Returns:

serialize the instance into binary data

Raises:

SPSDKError – Invalid section data
SPSDKError – Invalid padding length

property first_boot_section_id: int: Return id of first boot section.

classmethod parse(data)

Convert binary data into the instance (deserialization).

Parameters:

data (bytes) – given binary data to be converted

Return type:

Self

Returns:

converted instance

Raises:

SPSDKError – raised when digest does not match
SPSDKError – Raised when section is invalid

property sections: Sequence[BootSectionV1]: Return sequence of all sections on the SB file.

property size: int: Return size of the binary representation in bytes.

update()

Update content.

Return type:: None

validate()

Validate settings.

Raises:: SPSDKError – If the settings is not consistent
Return type:: None

SBFile Version 1 commands

Commands for SBFile.

spsdk.sbfile.sb1.commands.parse_v1_command(data)

Parse SB V1.x command from binary format.

Parameters:: data (bytes) – Input data as bytes
Return type:: CmdBaseClass
Returns:: parsed command object
Raises:: SPSDKError – Raised when there is unsupported command

SBFile Version 1 headers

Secure Boot Header.

class spsdk.sbfile.sb1.headers.BootSectionHeaderV1(section_id=0, flags=0)

Bases: CmdTag

Header of boot section derived from command TAG.

Note: Command TAG was reused to save some code in Boot ROM

Initialize BootSectionHeaderV1.

Parameters:

section_id (int) – unique section ID, 32-bit int
flags (SecureBootFlagsV1) – see SecureBootFlagsV1

SIZE = 16

property bootable: bool: Return whether section is bootable.

property flags: SecureBootFlagsV1: Return section flags.

property num_blocks: int: Return size of the section in number of cipher blocks.

classmethod parse(data)

Parse from bytes into BootSectionHeaderV1 object.

Return type:: Self

property rom_last_tag: bool

Return ROM_LAST_TAG flag.

The last section header in an image always has its ROM_LAST_TAG flag set to help the ROM know at what point to stop searching.

property section_id: int: Return unique ID of the section, 32 number.

class spsdk.sbfile.sb1.headers.SectionHeaderItemV1(identifier=0, offset=0, num_blocks=0, flags=0)

Bases: BaseClass

Section header item/row in section header table in in SB file V1.x.

Initialize SectionHeaderItemV1.

Parameters:

identifier (int) – Unique 32-bit identifier for this section.
offset (int) – The starting cipher block for this section’s data from the beginning of the image.
num_blocks (int) – The length of the section data in cipher blocks.
flags (SecureBootFlagsV1) – Flags that apply to the entire section, see SectionHeaderV1Flags

FORMAT = '<4I'

SIZE = 16

property bootable: bool: Return whether section is bootable.

export()

Return serialization to binary format.

Return type:: bytes

property flags: int: Return flags, see SectionHeaderV1Flags.

classmethod parse(data)

Parse binary data into the instance (deserialization).

Parameters:: data (bytes) – to be parsed
Return type:: Self
Returns:: the new instance
Raises:: SPSDKError – If size is not sufficient

property size: int: Return size of exported data in bytes.

class spsdk.sbfile.sb1.headers.SecureBootFlagsV1

Bases: Enum

Flags for SectionHeader.

NONE = 0

ROM_SECTION_BOOTABLE = 1

ROM_SECTION_CLEARTEXT = 2

class spsdk.sbfile.sb1.headers.SecureBootHeaderV1(version='1.0', product_version='999.999.999', component_version='999.999.999', flags=0, drive_tag=0, digest=b'\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00', timestamp=None)

Bases: BaseClass

Secure Boot Header V1.

Initialize SecureBootHeaderV1.

Parameters:

version (str) – of the format: 1.0 or 1.1 or 1.2
product_version (Union[BcdVersion3, str]) – Product version.
component_version (Union[BcdVersion3, str]) – Component version.
flags (int) – Flags associated with the entire image.
drive_tag (int) – Identifier for the disk drive or partition containing this image.
digest (bytes) – SHA-1 digest of all fields of the header, 20 bytes The first 16 bytes (of 20 total) also act as the initialization vector for CBC-encrypted regions.
timestamp (Optional[datetime]) – datetime of the file creation, use None for current date/time Fixed value should be used only for regression testing to generate same results

Raises:

SPSDKError – Invalid header version

export(padding8=None)

Serialization to binary form.

Parameters:: padding8 (Optional[bytes]) – 8 padding bytes used for in the header, None to use random bytes This value shall be used only for regression testing to generate same results
Return type:: bytes
Returns:: Serialize object into bytes

property first_boot_tag_block: int: Return first boot tag block.

property key_dictionary_block: int: Return key dictionary block.

classmethod parse(data)

Convert binary data into the instance (deserialization).

Parameters:

data (bytes) – given binary data to be decoded

Return type:

Self

Returns:

the instance of secure boot header v1

Raises:

SPSDKError – Raised when there is insufficient size
SPSDKError – Raised when there is invalid signature
SPSDKError – Raised when there is unexpected signature

property size: int: Return size of the header in bytes.

SBFile Version 1 images

Secure Boot Image Class.

class spsdk.sbfile.sb1.images.SecureBootV1(version='1.0', flags=0, drive_tag=0, product_version='999.999.999', component_version='999.999.999', dek=None, mac=None, digest=b'\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00', timestamp=None)

Bases: BaseClass

SB file 1.x.

Initialize Secure Boot Image V1.x.

Parameters:

version (str) – string in format #.# Major version of the boot image format, currently 1. Minor version of the boot image format, currently 1 or 2.
flags (int) – for the header, 0 by default: Flags associated with the entire image.
product_version (Union[BcdVersion3, str]) – Product version.
component_version (Union[BcdVersion3, str]) – Component version.
drive_tag (int) – For header: identifier for the disk drive or partition containing this image.
dek (Optional[bytes]) – DEK key for encrypted SB file; this is not supported yet
mac (Optional[bytes]) – MAC for encrypted SB file, this is not supported yet
digest (bytes) – SHA-1 digest of all fields of the header (it will be updated before export anyway) The first 16 bytes (of 20 total) also act as the initialization vector for CBC-encrypted regions.
timestamp (Optional[datetime]) – datetime of the file creation, use None for current date/time Fixed value should be used only for regression testing to generate same results

append(section)

Add section into the SB file.

Parameters:: section (BootSectionV1) – to be added
Return type:: None

export(header_padding8=None, auth_padding=None)

Serialization to binary form.

Parameters:

header_padding8 (Optional[bytes]) – optional header padding, 8-bytes; recommended to use None to apply random value
auth_padding (Optional[bytes]) – optional padding used after authentication; recommended to use None to apply random value

Return type:

bytes

Returns:

serialize the instance into binary data

Raises:

SPSDKError – Invalid section data
SPSDKError – Invalid padding length

property first_boot_section_id: int: Return id of first boot section.

classmethod parse(data)

Convert binary data into the instance (deserialization).

Parameters:

data (bytes) – given binary data to be converted

Return type:

Self

Returns:

converted instance

Raises:

SPSDKError – raised when digest does not match
SPSDKError – Raised when section is invalid

property sections: Sequence[BootSectionV1]: Return sequence of all sections on the SB file.

property size: int: Return size of the binary representation in bytes.

update()

Update content.

Return type:: None

validate()

Validate settings.

Raises:: SPSDKError – If the settings is not consistent
Return type:: None

SBFile Version 1 sections

Boot Selection for SB file.

class spsdk.sbfile.sb1.sections.BootSectionV1(section_id, flags=0)

Bases: BaseClass

Boot Section for SB file 1.x.

Initialize BootSectionV1.

Parameters:

section_id (int) – unique section ID, 32-bit int
flags (SecureBootFlagsV1) – see SecureBootFlagsV1

append(cmd)

Append command.

Parameters:: cmd (CmdBaseClass) – to be added
Return type:: None

property bootable: bool: Return whether section is bootable.

property cmd_size: int: Return size of the binary representation of the commands.

property commands: Sequence[CmdBaseClass]: Return sequence of all commands in the section.

export()

Return binary representation of the class (serialization).

Return type:: bytes

property flags: SecureBootFlagsV1: Return section flags.

classmethod parse(data)

Deserialization from binary format.

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

property rom_last_tag: bool

ReturnROM_LAST_TAG flag.

The last section header in an image always has its ROM_LAST_TAG flag set to help the ROM know at what point to stop searching.

property section_id: int: Return unique ID of the section, 32 number.

property size: int: Return size of the binary representation of the section in bytes.

update()

Update settings.

Return type:: None

SBFile Version 2

Module implementing SB2 and SB2.1 File.

SBFile Version 2 commands

Commands used by SBFile module.

class spsdk.sbfile.sb2.commands.CmdBaseClass(tag)

Bases: BaseClass

Base class for all commands.

Initialize CmdBase.

ROM_MEM_DEVICE_ID_MASK = 65280

ROM_MEM_DEVICE_ID_SHIFT = 8

ROM_MEM_GROUP_ID_MASK = 240

ROM_MEM_GROUP_ID_SHIFT = 4

export()

Return object serialized into bytes.

Return type:: bytes

property header: CmdHeader: Return command header.

property raw_size: int: Return size of the command in binary format (including header).

class spsdk.sbfile.sb2.commands.CmdCall(address=0, argument=0)

Bases: CmdBaseClass

Command Call.

The call statement is used for inserting a bootloader command that executes a function from one of the files that are loaded into the memory.

Initialize Command Call.

property address: int: Return command’s address.

property argument: int: Return command’s argument.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: Command Call object
Raises:: SPSDKError – If incorrect header tag

class spsdk.sbfile.sb2.commands.CmdErase(address=0, length=0, flags=0, mem_id=0)

Bases: CmdBaseClass

Command Erase class.

Initialize Command Erase.

property address: int: Return command’s address.

property flags: int: Return command’s flag.

property length: int: Return command’s count.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: Command Erase object
Raises:: SPSDKError – If incorrect header tag

class spsdk.sbfile.sb2.commands.CmdFill(address, pattern, length=None)

Bases: CmdBaseClass

Command Fill class.

Initialize Command Fill.

Parameters:

address (int) – to write data
pattern (int) – data to be written
length (Optional[int]) – length of data to be filled, defaults to 4

Raises:

SPSDKError – Raised when size is not aligned to 4 bytes

PADDING_VALUE = 0

property address: int: Return address of the command Fill.

export()

Return command in binary form (serialization).

Return type:: bytes

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: Command Fill object
Raises:: SPSDKError – If incorrect header tag

property pattern: bytes: Return binary data to fill.

property raw_size: int: Calculate raw size of header.

class spsdk.sbfile.sb2.commands.CmdHeader(tag, flags=0)

Bases: BaseClass

SBFile command header.

Initialize header.

FORMAT = '<2BH3L'

SIZE = 16

property crc: int: Calculate CRC for the header data.

export()

Export command header as bytes.

Return type:: bytes

classmethod parse(data)

Parse command header from bytes.

Parameters:

data (bytes) – Input data as bytes

Return type:

Self

Returns:

CMDHeader object

Raises:

SPSDKError – raised when size is incorrect
SPSDKError – Raised when CRC is incorrect

class spsdk.sbfile.sb2.commands.CmdJump(address=0, argument=0, spreg=None)

Bases: CmdBaseClass

Command Jump class.

Initialize Command Jump.

property address: int: Return address of the command Jump.

property argument: int: Return command’s argument.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: Command Jump object
Raises:: SPSDKError – If incorrect header tag

property spreg: int | None: Return command’s Stack Pointer.

class spsdk.sbfile.sb2.commands.CmdKeyStoreBackup(address, controller_id)

Bases: CmdKeyStoreBackupRestore

Command to backup keystore from non-volatile memory.

Initialize CmdKeyStoreBackupRestore.

Parameters:

address (int) – where to backup key-store or source for restoring key-store
controller_id (ExtMemId) – ID of the memory to backup key-store or source memory to load key-store back

Raises:

SPSDKError – If invalid address
SPSDKError – If invalid id of memory

classmethod cmd_id()

Return command ID for backup operation.

Return type:: EnumCmdTag

class spsdk.sbfile.sb2.commands.CmdKeyStoreBackupRestore(address, controller_id)

Bases: CmdBaseClass

Shared, abstract implementation for key-store backup and restore command.

Initialize CmdKeyStoreBackupRestore.

Parameters:

address (int) – where to backup key-store or source for restoring key-store
controller_id (ExtMemId) – ID of the memory to backup key-store or source memory to load key-store back

Raises:

SPSDKError – If invalid address
SPSDKError – If invalid id of memory

ROM_MEM_DEVICE_ID_MASK = 65280

ROM_MEM_DEVICE_ID_SHIFT = 8

property address: int: Return address where to backup key-store or source for restoring key-store.

abstract classmethod cmd_id()

Return command ID.

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

property controller_id: int: Return controller ID of the memory to backup key-store or source memory to load key-store back.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: CmdKeyStoreBackupRestore object
Raises:: SPSDKError – When there is invalid header tag

class spsdk.sbfile.sb2.commands.CmdKeyStoreRestore(address, controller_id)

Bases: CmdKeyStoreBackupRestore

Command to restore keystore into non-volatile memory.

Initialize CmdKeyStoreBackupRestore.

Parameters:

address (int) – where to backup key-store or source for restoring key-store
controller_id (ExtMemId) – ID of the memory to backup key-store or source memory to load key-store back

Raises:

SPSDKError – If invalid address
SPSDKError – If invalid id of memory

classmethod cmd_id()

Return command ID for restore operation.

Return type:: EnumCmdTag

class spsdk.sbfile.sb2.commands.CmdLoad(address, data, mem_id=0)

Bases: CmdBaseClass

Command Load. The load statement is used to store data into the memory.

Initialize CMD Load.

property address: int: Return address in target processor to load data.

export()

Export command as binary.

Return type:: bytes

property flags: int: Return command’s flag.

classmethod parse(data)

Parse command from bytes.

Parameters:

data (bytes) – Input data as bytes

Return type:

Self

Returns:

CMD Load object

Raises:

SPSDKError – Raised when there is invalid CRC
SPSDKError – When there is incorrect header tag

property raw_size: int: Return aligned size of the command including header and data.

class spsdk.sbfile.sb2.commands.CmdMemEnable(address, size, mem_id)

Bases: CmdBaseClass

Command to configure certain memory.

Initialize CmdMemEnable.

Parameters:

address (int) – source address with configuration data for memory initialization
size (int) – size of configuration data used for memory initialization
mem_id (int) – identification of memory

property address: int: Return command’s address.

property flags: int: Return command’s flag.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: Command Memory Enable object
Raises:: SPSDKError – If incorrect header tag

property size: int: Return command’s size.

class spsdk.sbfile.sb2.commands.CmdNop

Bases: CmdBaseClass

Command NOP class.

Initialize Command Nop.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: CMD Nop object
Raises:: SPSDKError – When there is incorrect header tag

class spsdk.sbfile.sb2.commands.CmdProg(address, mem_id, data_word1, data_word2=0, flags=0)

Bases: CmdBaseClass

Command Program class.

Initialize CMD Prog.

property address: int: Return address in target processor to program data.

property data_word1: int: Return data word 1.

property data_word2: int: Return data word 2.

property flags: int: Return command’s flag.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: parsed command object
Raises:: SPSDKError – If incorrect header tag

class spsdk.sbfile.sb2.commands.CmdReset

Bases: CmdBaseClass

Command Reset class.

Initialize Command Reset.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: Cmd Reset object
Raises:: SPSDKError – If incorrect header tag

class spsdk.sbfile.sb2.commands.CmdTag

Bases: CmdBaseClass

Command TAG class.

It is also used as header for boot section for SB file 1.x.

Initialize Command Tag.

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: parsed instance
Raises:: SPSDKError – When there is incorrect header tag

class spsdk.sbfile.sb2.commands.CmdVersionCheck(ver_type, version)

Bases: CmdBaseClass

FW Version Check command class.

Validates version of secure or non-secure firmware. The command fails if version is < expected.

Initialize CmdVersionCheck.

Parameters:

ver_type (VersionCheckType) – version check type, see VersionCheckType enum
version (int) – to be checked

Raises:

SPSDKError – If invalid version check type

classmethod parse(data)

Parse command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: Self
Returns:: parsed command object
Raises:: SPSDKError – If incorrect header tag

property type: VersionCheckType: Return type of the check version, see VersionCheckType enumeration.

property version: int: Return minimal version expected.

class spsdk.sbfile.sb2.commands.EnumCmdTag

Bases: Enum

Command tags.

CALL = 5

ERASE = 7

FILL = 3

FW_VERSION_CHECK = 11

JUMP = 4

LOAD = 2

MEM_ENABLE = 9

NOP = 0

PROG = 10

RESET = 8

TAG = 1

WR_KEYSTORE_FROM_NV = 13

WR_KEYSTORE_TO_NV = 12

class spsdk.sbfile.sb2.commands.EnumSectionFlag

Bases: Enum

Section flags.

BOOTABLE = 1

CLEARTEXT = 2

LAST_SECT = 32768

class spsdk.sbfile.sb2.commands.VersionCheckType

Bases: Enum

Select type of the version check: either secure or non-secure firmware to be checked.

NON_SECURE_VERSION = 1

SECURE_VERSION = 0

spsdk.sbfile.sb2.commands.get_device_id(mem_id)

Get device ID from memory ID.

Parameters:: mem_id (int) – memory ID
Return type:: int
Returns:: device ID

spsdk.sbfile.sb2.commands.get_group_id(mem_id)

Get group ID from memory ID.

Parameters:: mem_id (int) – memory ID
Return type:: int
Returns:: group ID

spsdk.sbfile.sb2.commands.get_memory_id(device_id, group_id)

Get memory ID from device ID and group ID.

Parameters:

device_id (int) – device ID
group_id (int) – group ID

Return type:

int

Returns:

memory ID

spsdk.sbfile.sb2.commands.parse_command(data)

Parse SB 2.x command from bytes.

Parameters:: data (bytes) – Input data as bytes
Return type:: CmdBaseClass
Returns:: parsed command object
Raises:: SPSDKError – Raised when there is unsupported command provided

SBFile Version 2 headers

Image header.

class spsdk.sbfile.sb2.headers.ImageHeaderV2(version='2.0', product_version='1.0.0', component_version='1.0.0', build_number=0, flags=8, nonce=None, timestamp=None)

Bases: BaseClass

Image Header V2 class.

Initialize Image Header Version 2.x.

Parameters:

version (str) – The image version value (default: 2.0)
product_version (str) – The product version (default: 1.0.0)
component_version (str) – The component version (default: 1.0.0)
build_number (int) – The build number value (default: 0)
flags (int) – The flags value (default: 0x08)
nonce (Optional[bytes]) – The NONCE value; None if TODO ????
timestamp (Optional[datetime]) – value requested in the test; None to use current value

FORMAT = '<16s4s4s2BH4I4H4sQ12HI4s'

SIGNATURE1 = b'STMP'

SIGNATURE2 = b'sgtl'

SIZE = 96

export(padding=None)

Serialize object into bytes.

Parameters:

padding (Optional[bytes]) – header padding 8 bytes (for testing purposes); None to use random value

Return type:

bytes

Returns:

binary representation

Raises:

SPSDKError – Raised when format is incorrect
SPSDKError – Raised when length of padding is incorrect
SPSDKError – Raised when length of header is incorrect

flags_desc()

Return flag description.

Return type:: str

classmethod parse(data)

Deserialization from binary form.

Parameters:: data (bytes) – binary representation
Return type:: Self
Returns:: parsed instance of the header
Raises:: SPSDKError – Unable to parse data

SBFile Version 2 images

Boot Image V2.0, V2.1.

class spsdk.sbfile.sb2.images.BootImageV20(signed, kek, *sections, product_version='1.0.0', component_version='1.0.0', build_number=0, advanced_params=<spsdk.sbfile.sb2.images.SBV2xAdvancedParams object>)

Bases: BaseClass

Boot Image V2.0 class.

Initialize Secure Boot Image V2.0.

Parameters:

signed (bool) – True if image is signed, False otherwise
kek (bytes) – key for wrapping DEK and MAC keys
product_version (str) – The product version (default: 1.0.0)
component_version (str) – The component version (default: 1.0.0)
build_number (int) – The build number value (default: 0)
advanced_params (SBV2xAdvancedParams) – Advanced parameters for encryption of the SB file, use for tests only
sections (BootSectionV2) – Boot sections

Raises:

SPSDKError – Invalid dek or mac

DEK_MAC_SIZE = 80

HEADER_MAC_SIZE = 32

KEY_BLOB_SIZE = 80

add_boot_section(section)

Add new Boot section into image.

Parameters:

section (BootSectionV2) – Boot section

Raises:

SPSDKError – Raised when section is not instance of BootSectionV2 class
SPSDKError – Raised when boot section has duplicate UID

Return type:

None

property cert_block: CertBlockV1 | None: Return certificate block; None if SB file not signed or block not assigned yet.

property cert_header_size: int: Return image raw size (not aligned) for certificate header.

property dek: bytes: Data encryption key.

export(padding=None)

Serialize image object.

Parameters:

padding (Optional[bytes]) – header padding (8 bytes) for testing purpose; None to use random values (recommended)

Return type:

bytes

Returns:

exported bytes

Raises:

SPSDKError – Raised when there are no boot sections or is not signed or private keys are missing
SPSDKError – Raised when there is invalid dek or mac
SPSDKError – Raised when certificate data is not present
SPSDKError – Raised when there is invalid certificate block
SPSDKError – Raised when there is invalid length of exported data

property header: ImageHeaderV2: Return image header.

property kek: bytes: Return key for wrapping DEK and MAC keys.

property mac: bytes: Message authentication code.

classmethod parse(data, kek=b'')

Parse image from bytes.

Parameters:

data (bytes) – Raw data of parsed image
kek (bytes) – The Key for unwrapping DEK and MAC keys (required)

Return type:

Self

Returns:

parsed image object

Raises:

SPSDKError – raised when header is in wrong format
SPSDKError – raised when there is invalid header version
SPSDKError – raised when signature is incorrect
SPSDKError – Raised when kek is empty
SPSDKError – raised when header’s nonce is not present

property raw_size: int: Return image raw size.

property raw_size_without_signature: int: Return image raw size without signature, used to calculate image blocks.

property signed: bool: Check whether sb is signed + encrypted or only encrypted.

update()

Update boot image.

Return type:: None

class spsdk.sbfile.sb2.images.BootImageV21(kek, *sections, product_version='1.0.0', component_version='1.0.0', build_number=0, advanced_params=<spsdk.sbfile.sb2.images.SBV2xAdvancedParams object>, flags=32776)

Bases: BaseClass

Boot Image V2.1 class.

Initialize Secure Boot Image V2.1.

Parameters:

kek (bytes) – key to wrap DEC and MAC keys
product_version (str) – The product version (default: 1.0.0)
component_version (str) – The component version (default: 1.0.0)
build_number (int) – The build number value (default: 0)
advanced_params (SBV2xAdvancedParams) – optional advanced parameters for encryption; it is recommended to use default value
flags (int) – see flags defined in class.
sections (BootSectionV2) – Boot sections

FLAGS_ENCRYPTED_SIGNED_BIT = 8

FLAGS_SHA_PRESENT_BIT = 32768

HEADER_MAC_SIZE = 32

KEY_BLOB_SIZE = 80

SHA_256_SIZE = 32

add_boot_section(section)

Add new Boot section into image.

Parameters:: section (BootSectionV2) – Boot section to be added
Raises:: SPSDKError – Raised when section is not instance of BootSectionV2 class
Return type:: None

property cert_block: CertBlockV1 | None: Return certificate block; None if SB file not signed or block not assigned yet.

property cert_header_size: int: Return image raw size (not aligned) for certificate header.

property dek: bytes: Data encryption key.

export(padding=None)

Serialize image object.

Parameters:

padding (Optional[bytes]) – header padding (8 bytes) for testing purpose; None to use random values (recommended)

Return type:

bytes

Returns:

exported bytes

Raises:

SPSDKError – Raised when there is no boot section to be added
SPSDKError – Raised when certificate is not assigned
SPSDKError – Raised when private key is not assigned
SPSDKError – Raised when private header’s nonce is invalid
SPSDKError – Raised when private key does not match certificate
SPSDKError – Raised when there is no debug info

classmethod generate_config_template(family)

Generate configuration template.

Parameters:: family (Optional[str]) – Device family.
Return type:: str
Returns:: Dictionary of individual templates (key is name of template, value is template itself).

classmethod get_commands_validation_schemas(family=None)

Create the list of validation schemas.

Parameters:: family (Optional[str]) – Device family filter, if None all commands are returned.
Return type:: List[Dict[str, Any]]
Returns:: List of validation schemas.

static get_supported_families()

Return list of supported families.

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

classmethod get_validation_schemas(family=None)

Create the list of validation schemas.

Parameters:: family (Optional[str]) – Device family
Return type:: List[Dict[str, Any]]
Returns:: List of validation schemas.

property header: ImageHeaderV2: Return image header.

property kek: bytes: Return key to wrap DEC and MAC keys.

classmethod load_from_config(config, key_file_path=None, signature_provider=None, signing_certificate_file_paths=None, root_key_certificate_paths=None, rkth_out_path=None, search_paths=None)

Creates an instance of BootImageV21 from configuration.

Parameters:

config (Dict[str, Any]) – Input standard configuration.
key_file_path (Optional[str]) – path to key file.
signature_provider (Optional[SignatureProvider]) – Signature provider to sign final image
signing_certificate_file_paths (Optional[List[str]]) – signing certificate chain.
root_key_certificate_paths (Optional[List[str]]) – paths to root key certificate(s) for verifying other certificates. Only 4 root key certificates are allowed, others are ignored. One of the certificates must match the first certificate passed in signing_certificate_file_paths.
rkth_out_path (Optional[str]) – output path to hash of hashes of root keys. If set to None, ‘hash.bin’ is created under working directory.
search_paths (Optional[List[str]]) – List of paths where to search for the file, defaults to None

Return type:

BootImageV21

Returns:

Instance of Secure Binary V2.1 class

property mac: bytes: Message authentication code.

classmethod parse(data, offset=0, kek=b'', plain_sections=False)

Parse image from bytes.

Parameters:

data (bytes) – Raw data of parsed image
offset (int) – The offset of input data
kek (bytes) – The Key for unwrapping DEK and MAC keys (required)
plain_sections (bool) – Sections are not encrypted; this is used only for debugging, not supported by ROM code

Return type:

BootImageV21

Returns:

BootImageV21 parsed object

Raises:

SPSDKError – raised when header is in incorrect format
SPSDKError – raised when signature is incorrect
SPSDKError – Raised when kek is empty
SPSDKError – raised when header’s nonce not present”

classmethod parse_sb21_config(config_path, external_files=None)

Create lexer and parser, load the BD file content and parse it.

Parameters:

config_path (str) – Path to configuration file either BD or YAML formatted.
external_files (Optional[List[str]]) – Optional list of external files for BD processing

Return type:

Dict[Any, Any]

Returns:

Dictionary with parsed configuration.

property raw_size: int: Return image raw size (not aligned).

property signed: bool: Return flag whether SB file is signed.

update()

Update BootImageV21.

Return type:: None

class spsdk.sbfile.sb2.images.SBV2xAdvancedParams(dek=None, mac=None, nonce=None, timestamp=None)

Bases: object

The class holds advanced parameters for the SB file encryption.

These parameters are used for the tests; for production, use can use default values (random keys + current time)

Initialize SBV2xAdvancedParams.

Parameters:

dek (Optional[bytes]) – DEK key
mac (Optional[bytes]) – MAC key
nonce (Optional[bytes]) – nonce
timestamp (Optional[datetime]) – fixed timestamp for the header; use None to use current date/time

Raises:

SPSDKError – Invalid dek or mac
SPSDKError – Invalid length of nonce

property dek: bytes: Return DEK key.

property mac: bytes: Return MAC key.

property nonce: bytes: Return NONCE.

property timestamp: datetime: Return timestamp.

SBFile Version 2 sections

Sections within SBfile.

class spsdk.sbfile.sb2.sections.BootSectionV2(uid, *commands, hmac_count=1)

Bases: BaseClass

Boot Section V2.

Initialize BootSectionV2.

Parameters:

uid (int) – section unique identification
commands (CmdBaseClass) – List of commands
hmac_count (int) – The number of HMAC entries

HMAC_SIZE = 32

append(cmd)

Add command to section.

Return type:: None

export(dek=b'', mac=b'', counter=None)

Serialize Boot Section object.

Parameters:

dek (bytes) – The DEK value in bytes (required)
mac (bytes) – The MAC value in bytes (required)
counter (Optional[Counter]) – The counter object (required)

Return type:

bytes

Returns:

exported bytes

Raises:

SPSDKError – raised when dek, mac, counter have invalid format or no commands

property hmac_count: int: Number of HMACs.

property is_last: bool: Check whether the section is the last one.

classmethod parse(data, offset=0, plain_sect=False, dek=b'', mac=b'', counter=None)

Parse Boot Section from bytes.

Parameters:

data (bytes) – Raw data of parsed image
offset (int) – The offset of input data
plain_sect (bool) – If the sections are not encrypted; It is used for debugging only, not supported by ROM code
dek (bytes) – The DEK value in bytes (required)
mac (bytes) – The MAC value in bytes (required)
counter (Optional[Counter]) – The counter object (required)

Return type:

BootSectionV2

Returns:

exported bytes

Raises:

SPSDKError – raised when dek, mac, counter have invalid format

property raw_size: int: Raw size of section.

property uid: int: Boot Section UID.

class spsdk.sbfile.sb2.sections.CertSectionV2(cert_block)

Bases: BaseClass

Certificate Section V2 class.

Initialize CertBlockV1.

HMAC_SIZE = 32

SECT_MARK = 1852270963

property cert_block: CertBlockV1: Return certification block.

export(dek=b'', mac=b'', counter=None)

Serialize Certificate Section object.

Parameters:

dek (bytes) – The DEK value in bytes (required)
mac (bytes) – The MAC value in bytes (required)
counter (Optional[Counter]) – The counter object (required)

Return type:

bytes

Returns:

exported bytes

Raises:

SPSDKError – raised when dek, mac, counter have invalid format
SPSDKError – Raised size of exported bytes is invalid

classmethod parse(data, offset=0, dek=b'', mac=b'', counter=None)

Parse Certificate Section from bytes array.

Parameters:

data (bytes) – Raw data of parsed image
offset (int) – The offset of input data
dek (bytes) – The DEK value in bytes (required)
mac (bytes) – The MAC value in bytes (required)
counter (Optional[Counter]) – The counter object (required)

Return type:

CertSectionV2

Returns:

parsed cert section v2 object

Raises:

SPSDKError – Raised when dek, mac, counter are not valid
SPSDKError – Raised when there is invalid header HMAC, TAG, FLAGS, Mark
SPSDKError – Raised when there is invalid certificate block HMAC

property raw_size: int: Calculate raw size of section.

SBFile Version 3.1.

SB31 module of sbfile.

class spsdk.sbfile.sb31.CmdCall(address)

Bases: BaseCmd

Address will be the address to jump.

Constructor for Command.

Parameters:: address (int) – Input address

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdCall

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdCall

class spsdk.sbfile.sb31.CmdConfigureMemory(address, memory_id=0)

Bases: BaseCmd

Configure memory.

Constructor for command.

Parameters:

address (int) – Input address
memory_id (int) – Memory ID

export()

Export command as bytes.

Return type:: bytes

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdConfigureMemory

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdConfigureMemory

class spsdk.sbfile.sb31.CmdCopy(address, length, destination_address=0, memory_id_from=0, memory_id_to=0)

Bases: BaseCmd

Copy data from one place to another.

Constructor for command.

Parameters:

address (int) – Input address
length (int) – Input length
destination_address (int) – Destination address
memory_id_from (int) – Memory ID
memory_id_to (int) – Memory ID

export()

Export command as bytes.

Return type:: bytes

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdCopy

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdCopy
Raises:: SPSDKError – Invalid padding

class spsdk.sbfile.sb31.CmdErase(address, length, memory_id=0)

Bases: BaseCmd

Erase given address range. The erase will be rounded up to the sector size.

Constructor for command.

Parameters:

address (int) – Input address
length (int) – Input length
memory_id (int) – Memory ID

export()

Export command as bytes.

Return type:: bytes

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdErase

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdErase
Raises:: SPSDKError – Invalid padding

class spsdk.sbfile.sb31.CmdExecute(address)

Bases: BaseCmd

Address will be the jump-to address.

Constructor for Command.

Parameters:: address (int) – Input address

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdExecute

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdExecute

class spsdk.sbfile.sb31.CmdFillMemory(address, length, pattern)

Bases: BaseCmd

Fill memory range by pattern.

Constructor for command.

Parameters:

address (int) – Input address
length (int) – Input length
pattern (int) – Pattern for fill memory with

export()

Export command as bytes.

Return type:: bytes

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdFillMemory

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdErase
Raises:: SPSDKError – Invalid padding

class spsdk.sbfile.sb31.CmdLoad(address, data, memory_id=0)

Bases: CmdLoadBase

Data to write follows the range header.

Constructor for command.

Parameters:

address (int) – Address for the load command
data (bytes) – Data to load
memory_id (int) – Memory ID

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

Union[CmdLoad, CmdLoadHashLocking, CmdLoadCmac]

Returns:

Command object loaded from configuration.

Raises:

SPSDKError – Invalid configuration field.

class spsdk.sbfile.sb31.CmdLoadCmac(address, data, memory_id=0)

Bases: CmdLoadBase

Load cmac. ROM is calculating cmac from loaded data.

Constructor for command.

Parameters:

address (int) – Address for the load command
data (bytes) – Data to load
memory_id (int) – Memory ID

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdLoadCmac

Returns:

Command object loaded from configuration.

Raises:

SPSDKError – Invalid configuration field.

class spsdk.sbfile.sb31.CmdLoadHashLocking(address, data, memory_id=0)

Bases: CmdLoadBase

Load hash. ROM is calculating hash.

Constructor for command.

Parameters:

address (int) – Address for the load command
data (bytes) – Data to load
memory_id (int) – Memory ID

export()

Export command as bytes.

Return type:: bytes

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdLoadHashLocking

Returns:

Command object loaded from configuration.

Raises:

SPSDKError – Invalid configuration field.

class spsdk.sbfile.sb31.CmdLoadKeyBlob(offset, data, key_wrap_id)

Bases: BaseCmd

Load key blob.

Constructor for command.

Parameters:

offset (int) – Input offset
key_wrap_id (int) – Key wrap ID (NXP_CUST_KEK_INT_SK = 16, NXP_CUST_KEK_EXT_SK = 17)
data (bytes) – Wrapped key blob

FORMAT = '<L2H2L'

class KeyTypes(value)

Bases: Enum

KeyTypes for NXP_CUST_KEK_INT_SK, NXP_CUST_KEK_EXT_SK.

NXP_CUST_KEK_EXT_SK = 2

NXP_CUST_KEK_INT_SK = 1

export()

Export command as bytes.

Return type:: bytes

classmethod get_key_id(family, key_name)

Get key ID based on family and key name.

Parameters:

family (str) – chip family
key_name (KeyTypes) – NXP_CUST_KEK_INT_SK or NXP_CUST_KEK_EXT_SK

Return type:

int

Returns:

integer value representing key

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdLoadKeyBlob

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdLoadKeyBlob

class spsdk.sbfile.sb31.CmdProgFuses(address, data)

Bases: CmdLoadBase

Address will be address of fuse register.

Constructor for Command.

Parameters:

address (int) – Input address
data (bytes) – Input data

HAS_MEMORY_ID_BLOCK = False

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdProgFuses

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdProgFuses

class spsdk.sbfile.sb31.CmdProgIfr(address, data)

Bases: CmdLoadBase

Address will be the address into the IFR region.

Constructor for Command.

Parameters:

address (int) – Input address
data (bytes) – Input data as bytes array

HAS_MEMORY_ID_BLOCK = False

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdProgIfr

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdProgFuses

class spsdk.sbfile.sb31.CmdSectionHeader(length, section_uid=1, section_type=1)

Bases: MainCmd

Create section header.

Constructor for Commands section.

Parameters:

section_uid (int) – Input uid
section_type (int) – Input type
length (int) – Input length

FORMAT = '<4L'

SIZE = 16

export()

Export command as bytes.

Return type:: bytes

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdSectionHeader

Returns:

Command object loaded from configuration.

Raises:

SPSDKError – This situation cannot raise (the function here is just MYPY/PYLINT checks).

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Raises:: SPSDKError – Raised when FORMAT is bigger than length of the data without offset
Return type:: Self
Returns:: CmdSectionHeader

class spsdk.sbfile.sb31.EnumCmdTag

Bases: Enum

Contains commands tags.

CALL = 4

CONFIGURE_MEMORY = 11

COPY = 8

ERASE = 1

EXECUTE = 3

FILL_MEMORY = 12

FW_VERSION_CHECK = 13

LOAD = 2

LOAD_CMAC = 7

LOAD_HASH_LOCKING = 9

LOAD_KEY_BLOB = 10

NONE = 0

PROGRAM_FUSES = 5

PROGRAM_IFR = 6

RESET = 14

spsdk.sbfile.sb31.parse_command(data)

Parse command from bytes array.

Parameters:

data (bytes) – Input data as bytes array

Raises:

SPSDKError – Raised when tag is not in cmd_class
SPSDKError – Raised when tag is invalid

Return type:

object

Returns:

object

SBFile Version 3.1. functions

File including helping functions.

class spsdk.sbfile.sb31.functions.KeyDerivationMode

Bases: Enum

Modes for Key derivation.

BLK = 2

KDK = 1

class spsdk.sbfile.sb31.functions.KeyDerivator(pck, timestamp, key_length, kdk_access_rights)

Bases: object

Engine for generating derived keys.

Initialize the KeyDerivator.

Parameters:

pck (bytes) – Part Common Key, base user key for all key derivations
timestamp (int) – Timestamp used for creating the KeyDerivationKey
key_length (int) – Requested key length after derivation (128/256bits)
kdk_access_rights (int) – KeyDerivationKey access rights

get_block_key(block_number)

Derive key for particular block.

Return type:: bytes

spsdk.sbfile.sb31.functions.add_leading_zeros(byte_data, return_size)

Return data with leading zeros.

Parameters:

byte_data (bytes) – Input data as bytes array
return_size (int) –

Return type:

bytes

Returns:

bytes

spsdk.sbfile.sb31.functions.add_trailing_zeros(byte_data, return_size)

Return data with trailing zeros.

Parameters:

byte_data (bytes) – Input data as bytes array
return_size (int) –

Return type:

bytes

Returns:

bytes

spsdk.sbfile.sb31.functions.derive_block_key(kdk, block_number, key_length, kdk_access_rights)

Derive encryption AES key for given block.

Parameters:

kdk (bytes) – Key Derivation Key
block_number (int) – Block number
key_length (int) – Required key length (128/256)
kdk_access_rights (int) – Key Derivation Key access rights (0-3)

Return type:

bytes

Returns:

AES key for given block

spsdk.sbfile.sb31.functions.derive_kdk(pck, timestamp, key_length, kdk_access_rights)

Derive the Key Derivation Key.

Parameters:

pck (bytes) – Part Common Key
timestamp (int) – Timestamp for KDK derivation
key_length (int) – Requested key length (128/256b)
kdk_access_rights (int) – KDK access rights (0-3)

Return type:

bytes

Returns:

Key Derivation Key

SBFile Version 3.1. commands

Module for creation commands.

class spsdk.sbfile.sb31.commands.BaseCmd(address, length, cmd_tag=0)

Bases: MainCmd

Functions for creating cmd intended for inheritance.

Constructor for Commands header.

Parameters:

address (int) – Input address
length (int) – Input length
cmd_tag (int) – Command tag

FORMAT = '<4L'

SIZE = 16

TAG = 1437248085

property address: int: Get address.

export()

Export command as bytes.

Return type:: bytes

classmethod header_parse(cmd_tag, data)

Parse header command from bytes array.

Parameters:

data (bytes) – Input data as bytes array
cmd_tag (int) – Information about command tag

Raises:

SPSDKError – Raised if tag is not equal to required TAG
SPSDKError – Raised if cmd is not equal EnumCmdTag

Return type:

Tuple[int, int]

Returns:

Tuple

property length: int: Get length.

classmethod parse(data)

Deserialize object from bytes array.

Return type:: Self

class spsdk.sbfile.sb31.commands.CmdCall(address)

Bases: BaseCmd

Address will be the address to jump.

Constructor for Command.

Parameters:: address (int) – Input address

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdCall

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdCall

class spsdk.sbfile.sb31.commands.CmdConfigureMemory(address, memory_id=0)

Bases: BaseCmd

Configure memory.

Constructor for command.

Parameters:

address (int) – Input address
memory_id (int) – Memory ID

export()

Export command as bytes.

Return type:: bytes

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdConfigureMemory

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdConfigureMemory

class spsdk.sbfile.sb31.commands.CmdCopy(address, length, destination_address=0, memory_id_from=0, memory_id_to=0)

Bases: BaseCmd

Copy data from one place to another.

Constructor for command.

Parameters:

address (int) – Input address
length (int) – Input length
destination_address (int) – Destination address
memory_id_from (int) – Memory ID
memory_id_to (int) – Memory ID

export()

Export command as bytes.

Return type:: bytes

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdCopy

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdCopy
Raises:: SPSDKError – Invalid padding

class spsdk.sbfile.sb31.commands.CmdErase(address, length, memory_id=0)

Bases: BaseCmd

Erase given address range. The erase will be rounded up to the sector size.

Constructor for command.

Parameters:

address (int) – Input address
length (int) – Input length
memory_id (int) – Memory ID

export()

Export command as bytes.

Return type:: bytes

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdErase

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdErase
Raises:: SPSDKError – Invalid padding

class spsdk.sbfile.sb31.commands.CmdExecute(address)

Bases: BaseCmd

Address will be the jump-to address.

Constructor for Command.

Parameters:: address (int) – Input address

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdExecute

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdExecute

class spsdk.sbfile.sb31.commands.CmdFillMemory(address, length, pattern)

Bases: BaseCmd

Fill memory range by pattern.

Constructor for command.

Parameters:

address (int) – Input address
length (int) – Input length
pattern (int) – Pattern for fill memory with

export()

Export command as bytes.

Return type:: bytes

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdFillMemory

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdErase
Raises:: SPSDKError – Invalid padding

class spsdk.sbfile.sb31.commands.CmdFwVersionCheck(value, counter_id)

Bases: BaseCmd

Check counter value with stored value, if values are not same, SB file is rejected.

Constructor for command.

Parameters:

value (int) – Input value
counter_id (int) – Counter ID (NONSECURE = 1, SECURE = 2)

class CounterID

Bases: Enum

Counter IDs used by the CmdFwVersionCheck command.

BOOTLOADER = 5

NONE = 0

NONSECURE = 1

RADIO = 3

SECURE = 2

SNT = 4

export()

Export command as bytes.

Return type:: bytes

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdFwVersionCheck

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdFwVersionCheck

class spsdk.sbfile.sb31.commands.CmdLoad(address, data, memory_id=0)

Bases: CmdLoadBase

Data to write follows the range header.

Constructor for command.

Parameters:

address (int) – Address for the load command
data (bytes) – Data to load
memory_id (int) – Memory ID

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

Union[CmdLoad, CmdLoadHashLocking, CmdLoadCmac]

Returns:

Command object loaded from configuration.

Raises:

SPSDKError – Invalid configuration field.

class spsdk.sbfile.sb31.commands.CmdLoadBase(cmd_tag, address, data, memory_id=0)

Bases: BaseCmd

Base class for commands loading data.

Constructor for command.

Parameters:

cmd_tag (int) – Command tag for the derived class
address (int) – Address for the load command
data (bytes) – Data to load
memory_id (int) – Memory ID

HAS_MEMORY_ID_BLOCK = True

export()

Export command as bytes.

Return type:: bytes

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

MainCmd

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdLoad
Raises:: SPSDKError – Invalid cmd_tag was found

class spsdk.sbfile.sb31.commands.CmdLoadCmac(address, data, memory_id=0)

Bases: CmdLoadBase

Load cmac. ROM is calculating cmac from loaded data.

Constructor for command.

Parameters:

address (int) – Address for the load command
data (bytes) – Data to load
memory_id (int) – Memory ID

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdLoadCmac

Returns:

Command object loaded from configuration.

Raises:

SPSDKError – Invalid configuration field.

class spsdk.sbfile.sb31.commands.CmdLoadHashLocking(address, data, memory_id=0)

Bases: CmdLoadBase

Load hash. ROM is calculating hash.

Constructor for command.

Parameters:

address (int) – Address for the load command
data (bytes) – Data to load
memory_id (int) – Memory ID

export()

Export command as bytes.

Return type:: bytes

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdLoadHashLocking

Returns:

Command object loaded from configuration.

Raises:

SPSDKError – Invalid configuration field.

class spsdk.sbfile.sb31.commands.CmdLoadKeyBlob(offset, data, key_wrap_id)

Bases: BaseCmd

Load key blob.

Constructor for command.

Parameters:

offset (int) – Input offset
key_wrap_id (int) – Key wrap ID (NXP_CUST_KEK_INT_SK = 16, NXP_CUST_KEK_EXT_SK = 17)
data (bytes) – Wrapped key blob

FORMAT = '<L2H2L'

class KeyTypes(value)

Bases: Enum

KeyTypes for NXP_CUST_KEK_INT_SK, NXP_CUST_KEK_EXT_SK.

NXP_CUST_KEK_EXT_SK = 2

NXP_CUST_KEK_INT_SK = 1

export()

Export command as bytes.

Return type:: bytes

classmethod get_key_id(family, key_name)

Get key ID based on family and key name.

Parameters:

family (str) – chip family
key_name (KeyTypes) – NXP_CUST_KEK_INT_SK or NXP_CUST_KEK_EXT_SK

Return type:

int

Returns:

integer value representing key

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdLoadKeyBlob

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdLoadKeyBlob

class spsdk.sbfile.sb31.commands.CmdProgFuses(address, data)

Bases: CmdLoadBase

Address will be address of fuse register.

Constructor for Command.

Parameters:

address (int) – Input address
data (bytes) – Input data

HAS_MEMORY_ID_BLOCK = False

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdProgFuses

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdProgFuses

class spsdk.sbfile.sb31.commands.CmdProgIfr(address, data)

Bases: CmdLoadBase

Address will be the address into the IFR region.

Constructor for Command.

Parameters:

address (int) – Input address
data (bytes) – Input data as bytes array

HAS_MEMORY_ID_BLOCK = False

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdProgIfr

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: Self
Returns:: CmdProgFuses

class spsdk.sbfile.sb31.commands.CmdReset

Bases: BaseCmd

Reset command, added for SBx.

Constructor for reset command.

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdReset

Returns:

Command object loaded from configuration.

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Return type:: CmdReset
Returns:: CmdReset

class spsdk.sbfile.sb31.commands.CmdSectionHeader(length, section_uid=1, section_type=1)

Bases: MainCmd

Create section header.

Constructor for Commands section.

Parameters:

section_uid (int) – Input uid
section_type (int) – Input type
length (int) – Input length

FORMAT = '<4L'

SIZE = 16

export()

Export command as bytes.

Return type:: bytes

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

CmdSectionHeader

Returns:

Command object loaded from configuration.

Raises:

SPSDKError – This situation cannot raise (the function here is just MYPY/PYLINT checks).

classmethod parse(data)

Parse command from bytes array.

Parameters:: data (bytes) – Input data as bytes array
Raises:: SPSDKError – Raised when FORMAT is bigger than length of the data without offset
Return type:: Self
Returns:: CmdSectionHeader

class spsdk.sbfile.sb31.commands.MainCmd

Bases: BaseClass

Functions for creating cmd intended for inheritance.

classmethod load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

MainCmd

Returns:

Command object loaded from configuration.

Raises:

NotImplementedError – Derived class has to implement this method

spsdk.sbfile.sb31.commands.parse_command(data)

Parse command from bytes array.

Parameters:

data (bytes) – Input data as bytes array

Raises:

SPSDKError – Raised when tag is not in cmd_class
SPSDKError – Raised when tag is invalid

Return type:

object

Returns:

object

SBFile Version 3.1. images

Module used for generation SecureBinary V3.1.

class spsdk.sbfile.sb31.images.SecureBinary31(family, cert_block, firmware_version, signature_provider, pck=None, kdk_access_rights=None, description=None, is_nxp_container=False, flags=0, timestamp=None, is_encrypted=True)

Bases: BaseClass

Secure Binary SB3.1 class.

Constructor for Secure Binary v3.1 data container.

Parameters:

cert_block (CertBlockV21) – Certification block.
firmware_version (int) – Firmware version (must be bigger than current CMPA record).
signature_provider (SignatureProvider) – Signature provider for final sign of SB3.1 image.
pck (Optional[bytes]) – Part Common Key (needed if is_encrypted is True), defaults to None
kdk_access_rights (Optional[int]) – Key Derivation Key access rights (needed if is_encrypted is True), defaults to None
description (Optional[str]) – Custom description up to 16 characters long, defaults to None
is_nxp_container (bool) – NXP provisioning SB file, defaults to False
flags (int) – Flags for SB file, defaults to 0
timestamp (Optional[int]) – Timestamp used for encryption (needed if is_encrypted is True), defaults to None
is_encrypted (bool) – Indicate whether commands should be encrypted or not, defaults to True

PCK_SIZES = [256, 128]

export(cert_block=None)

Generate binary output of SB3.1 file.

Return type:: bytes
Returns:: Content of SB3.1 file in bytes.

classmethod generate_config_template(family)

Generate configuration for selected family.

Parameters:: family (str) – Device family.
Return type:: Dict[str, str]
Returns:: Dictionary of individual templates (key is name of template, value is template itself).

classmethod get_commands_validation_schemas(family)

Create the list of validation schemas.

Parameters:: family (str) – Family description.
Return type:: List[Dict[str, Any]]
Returns:: List of validation schemas.

static get_supported_families()

Return list of supported families.

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

classmethod get_validation_schemas(family)

Create the list of validation schemas.

Parameters:: family (str) – Family description.
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 SB31 supported families.

classmethod load_from_config(config, search_paths=None)

Creates an instance of SecureBinary31 from configuration.

Parameters:

config (Dict[str, Any]) – Input standard configuration.
search_paths (Optional[List[str]]) – List of paths where to search for the file, defaults to None

Return type:

SecureBinary31

Returns:

Instance of Secure Binary V3.1 class

classmethod parse(data)

Deserialize object from bytes array.

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

validate()

Validate the settings of class members.

Raises:: SPSDKError – Invalid configuration of SB3.1 class members.
Return type:: None

class spsdk.sbfile.sb31.images.SecureBinary31Commands(family, hash_type, is_encrypted=True, pck=None, timestamp=None, kdk_access_rights=None)

Bases: BaseClass

Blob containing SB3.1 commands.

Initialize container for SB3.1 commands.

Parameters:

family (str) – Device family
hash_type (EnumHashAlgorithm) – Hash type used in commands binary block
is_encrypted (bool) – Indicate whether commands should be encrypted or not, defaults to True
pck (Optional[bytes]) – Part Common Key (needed if is_encrypted is True), defaults to None
timestamp (Optional[int]) – Timestamp used for encryption (needed if is_encrypted is True), defaults to None
kdk_access_rights (Optional[int]) – Key Derivation Key access rights (needed if is_encrypted is True), defaults to None

Raises:

SPSDKError – Key derivation arguments are not provided if is_encrypted is True
SPSDKValueError – Invalid hash type

DATA_CHUNK_LENGTH = 256

add_command(command)

Add SB3.1 command.

Return type:: None

export()

Export commands as bytes.

Return type:: bytes

get_cmd_blocks_to_export()

Export commands as bytes.

Return type:: List[bytes]

insert_command(index, command)

Insert SB3.1 command.

Return type:: None

load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

None

classmethod parse(data)

Parse binary data into SecureBinary31Commands.

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

process_cmd_blocks_to_export(data_blocks)

Process given data blocks for export.

Return type:: bytes

set_commands(commands)

Set all SB3.1 commands at once.

Return type:: None

validate()

Validate the settings of class members.

Raises:: SPSDKError – Invalid configuration of SB3.1 commands blob class members.
Return type:: None

class spsdk.sbfile.sb31.images.SecureBinary31Header(firmware_version, hash_type, description=None, timestamp=None, is_nxp_container=False, flags=0)

Bases: BaseClass

Header of the SecureBinary V3.1.

Initialize the SecureBinary V3.1 Header.

Parameters:

hash_type (EnumHashAlgorithm) – Hash type used in commands binary block
firmware_version (int) – Firmware version (must be bigger than current CMPA record)
description (Optional[str]) – Custom description up to 16 characters long, defaults to None
timestamp (Optional[int]) – Timestamp (number of seconds since Jan 1st, 200), if None use current time
is_nxp_container (bool) – NXP provisioning SB file, defaults to False
flags (int) – Flags for SB file, defaults to 0

DESCRIPTION_LENGTH = 16

FORMAT_VERSION = '3.1'

HEADER_FORMAT = '<4s2H3LQ4L16s'

HEADER_SIZE = 60

MAGIC = b'sbv3'

property block_size: int: Calculate the the data block size.

property cert_block_offset: int: Calculate the offset to the Certification block.

export()

Serialize the SB file to bytes.

Return type:: bytes

classmethod parse(data)

Parse binary data into SecureBinary31Header.

Raises:: SPSDKError – Unable to parse SB31 Header.
Return type:: Self

update(commands, cert_block)

Updates the volatile fields in header by real commands and certification block data.

Parameters:

commands (SecureBinary31Commands) – SB3.1 Commands block
cert_block (CertBlockV21) – SB3.1 Certification block.

Return type:

None

validate()

Validate the settings of class members.

Raises:: SPSDKError – Invalid configuration of SB3.1 header blob class members.
Return type:: None

SBFile Version X

Module used for generation SecureBinary X.

class spsdk.sbfile.sbx.images.SecureBinaryX(firmware_version, tphsm_blob, description=None, image_type=SecureBinaryXType.OEM_PROVISIONING, signature_provider=None, flags=0, timestamp=None)

Bases: BaseClass

Secure Binary SBX class.

Constructor for Secure Binary vX data container.

Parameters:

tphsm_blob (Optional[TpHsmBlob]) – TP HSM blob
firmware_version (int) – Firmware version.
description (Optional[str]) – Custom description up to 16 characters long, defaults to None
image_type (SecureBinaryXType) – SecureBinaryXType
signature_provider (Optional[SignatureProvider]) – signature provider to final sign of SBX image in case of OEM and NXP_PROVISIONING types
flags (int) – Flags for SB file, defaults to 0
timestamp (Optional[int]) – Timestamp used for encryption (needed if is_encrypted is True), defaults to None

export()

Generate binary output of SBx file.

Raises:: SPSDKError – TPHSM blob must be loaded first
Return type:: bytes
Returns:: Content of SBx file in bytes.

export_header(final_hash=b'\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00')

Export SBx header without signature for encryption on device.

Raises:: SPSDKError – TPHSM blob must be loaded first
Return type:: bytes
Returns:: plain header without signature in bytes

classmethod generate_config_template(family)

Generate configuration for selected family.

Parameters:: family (str) – Family description.
Return type:: Dict[str, str]
Returns:: Dictionary of individual templates (key is name of template, value is template itself).

static get_supported_families()

Return list of supported families.

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

classmethod get_validation_schemas(include_test_configuration=False)

Create the list of validation schemas.

Parameters:: include_test_configuration (bool) – Add also testing configuration schemas.
Return type:: List[Dict[str, Any]]
Returns:: List of validation schemas.

property isk_signed: bool: Return true if SBx is signed by ISK certificate.

classmethod load_from_config(config, search_paths=None)

Creates an instance of SecureBinaryX from configuration.

Parameters:

config (Dict[str, Any]) – Input standard configuration.
search_paths (Optional[List[str]]) – List of paths where to search for the file, defaults to None

Return type:

SecureBinaryX

Returns:

Instance of Secure Binary X class

load_tphsm(tphsm, offset=0)

Load TPHSM blob from binary data.

Parameters:

tphsm (bytes) – TPHSM binary data
offset (int) – offset, defaults to 0

Return type:

None

classmethod parse(data, offset=0)

Deserialize object from bytes array.

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

update_header()

Update SBx header.

Return type:: None

validate()

Validate the settings of class members.

Raises:: SPSDKError – Invalid configuration of SBx class members.
Return type:: None

class spsdk.sbfile.sbx.images.SecureBinaryXCommands

Bases: BaseClass

Blob containing SBX commands.

Initialize container for SBx commands.

Raises:: SPSDKError – Key derivation arguments are not provided if is_encrypted is True

DATA_CHUNK_LENGTH = 256

add_command(command)

Add SBx command.

Return type:: None

export()

Export commands as bytes.

Return type:: bytes

get_cmd_blocks_to_export()

Export commands as bytes.

Return type:: List[bytes]

insert_command(index, command)

Insert SBx command.

Return type:: None

load_from_config(config, search_paths=None)

Load configuration from dictionary.

Parameters:

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

Return type:

None

classmethod parse(data, offset=0)

Parse binary data into SecureBinary31Commands.

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

process_cmd_blocks_to_export(data_blocks)

Process given data blocks for export.

Return type:: bytes

set_commands(commands)

Set all SBx commands at once.

Return type:: None

class spsdk.sbfile.sbx.images.SecureBinaryXHeader(firmware_version, description=None, timestamp=None, image_type=SecureBinaryXType.OEM_PROVISIONING, flags=0)

Bases: BaseClass

Header of the SecureBinary X.

Initialize the SecureBinary X Header.

Parameters:

firmware_version (int) – Firmware version
description (Optional[str]) – Custom description up to 16 characters long, defaults to None
timestamp (Optional[int]) – Timestamp (number of seconds since Jan 1st, 2000), if None use current time
image_type (SecureBinaryXType) – type of the SB file, defaults to OEM_PROVISIONING
flags (int) – Flags for SBx file, defaults to 0

DESCRIPTION_LENGTH = 16

FORMAT_VERSION = '1.0'

HEADER_FORMAT = '<4s2H3LQ3L16s'

HEADER_SIZE = 140

MAGIC = b'sbvx'

calculate_block_size()

Calculate the the data block size.

Return type:: int

export()

Serialize the SB file to bytes.

Return type:: bytes

classmethod parse(data, offset=0)

Parse binary data into SecureBinary31Header.

Raises:: SPSDKError – Unable to parse SB31 Header.
Return type:: SecureBinaryXHeader

update(commands)

Updates the volatile fields in header by real commands.

Parameters:: commands (SecureBinaryXCommands) – SBx Commands block
Return type:: None

validate()

Validate the settings of class members.

Raises:: SPSDKError – Invalid configuration of SBx header blob class members.
Return type:: None

class spsdk.sbfile.sbx.images.SecureBinaryXType(value)

Bases: Enum

Type of the Secure Binary X container.

NXP_PROVISIONING = 1

OEM = 3

OEM_PROVISIONING = 2

class spsdk.sbfile.sbx.images.TpHsmBlob(tphsm_header, signature=None, hmac_key=None)

Bases: BaseClass

TP HSM blob.

Constructor.

Parameters:

tphsm_header (Union[TpHsmBlobHeader, bytes]) – TPHSM header
signature (Optional[bytes]) – blob signature
hmac_key (Optional[str]) – of the certificate

Raises:

SPSDKError – When there is invalid version

FORMAT = '<20s32s'

SIZE = 52

export()

TP HSM blob in binary form.

Return type:: bytes

classmethod parse(data, offset=0)

Deserialize object from bytes array.

Parameters:

data (bytes) – Input data as bytes
offset (int) – The offset of input data (default: 0)

Return type:

TpHsmBlob

Returns:

Certificate Header instance

Raises:

SPSDKParsingError – Unexpected size or signature of data

class spsdk.sbfile.sbx.images.TpHsmBlobHeader(version=1, blob_type=0, oem_enc_data=b'\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00')

Bases: BaseClass

TP HSM blob header.

Constructor.

Parameters:

version (int) – blob version
blob_type (int) – type of the HSM blob
build_number – of the certificate

Raises:

SPSDKError – When there is invalid version

FORMAT = '<2BH16s'

SIGNATURE = b'cert'

SIZE = 20

export()

TP HSM block header in binary form.

Return type:: bytes

classmethod parse(header_data, offset=0)

Deserialize object from bytes array.

Parameters:

header_data (bytes) – Input data as bytes
offset (int) – The offset of input data (default: 0)

Return type:

TpHsmBlobHeader

Returns:

Certificate Header instance

Raises:

SPSDKParsingError – Unexpected size or signature of data

SBFile Version X - DEVHSM

Module is used to generate initialization SBx file.

class spsdk.sbfile.sbx.devhsm.DevHsmSBx(mboot, oem_share_input, info_print, family, cust_mk_sk, container_conf=None, workspace=None, initial_reset=False, final_reset=True)

Bases: DevHsm

Class to handle device HSM provisioning procedure for SBx.

Initialization of device HSM class. It’s designed to create provisioned sbx file.

Parameters:

mboot (McuBoot) – mBoot communication interface.
oem_share_input (bytes) – OEM share input data.
family (str) – chip family
cust_mk_sk (Optional[bytes]) – Customer Master Key Symmetric Key.
container_conf (Optional[str]) – Optional configuration file (to specify user list of SB commands).
workspace (Optional[str]) – Optional folder to store middle results.
initial_reset (bool) – Reset device before DevHSM creation of SB3 file.
final_reset (bool) – Reset device after DevHSM creation of SB3 file.

Raises:

SPSDKError – In case of any problem.

DEVBUFF_GEN_MASTER_ENC_SHARE_OUTPUT_SIZE = 52

DEVBUFF_SB_SIGNATURE_SIZE = 32

create_sb()

Do device hsm process to create provisioning SBX file.

Return type:: None

encrypt_data_blocks(sbx_header, data_cmd_blocks)

Encrypt all data blocks on device.

Parameters:

sbx_header (bytes) – Un Encrypted sbx file header.
data_cmd_blocks (List[bytes]) – List of un-encrypted sbx file command blocks.

Raises:

SPSDKError – In case of any vulnerability.

Return type:

List[bytes]

Returns:

List of encrypted command blocks on device.

export()

Get the Final SB file.

Return type:: bytes
Returns:: Final SB file in bytes.

classmethod generate_config_template(family)

Generate configuration for selected family.

Return type:: Dict[str, str]

oem_generate_master_share(oem_share_input)

Generate on device Encrypted OEM master share outputs.

Parameters:: oem_share_input (bytes) – OEM input (randomize seed)
Raises:: SPSDKError – In case of any vulnerability.
Return type:: bytes
Returns:: Tuple with OEM generate master share outputs.

sign_data_blob(data_to_sign)

Get HSM encryption sign for data blob.

Parameters:: data_to_sign (bytes) – Input data to sign.
Raises:: SPSDKError – In case of any error.
Return type:: bytes
Returns:: Data blob signature (64 bytes).

SBFile - miscellaneous functions

Miscellaneous functions in SBFile module.

class spsdk.sbfile.misc.BcdVersion3(major=1, minor=0, service=0)

Bases: object

Version in format #.#.#, where # is BCD number (1-4 digits).

Initialize BcdVersion3.

Parameters:

major (int) – number in BCD format, 1-4 decimal digits
minor (int) – number in BCD format, 1-4 decimal digits
service (int) – number in BCD format, 1-4 decimal digits

Raises:

SPSDKError – Invalid version

DEFAULT = '999.999.999'

static from_str(text)

Convert string to BcdVersion instance.

Parameters:: text (str) – version in format #.#.#, where # is 1-4 decimal digits
Return type:: BcdVersion3
Returns:: BcdVersion3 instance
Raises:: SPSDKError – If format is not valid

property nums: Sequence[int]: Return array of version numbers: [major, minor, service].

static to_version(input_version)

Convert different input formats into BcdVersion3 instance.

Parameters:: input_version (Union[BcdVersion3, str]) – either directly BcdVersion3 or string
Raises:: SPSDKError – Raises when the format is unsupported
Return type:: BcdVersion3
Returns:: BcdVersion3 instance

class spsdk.sbfile.misc.SecBootBlckSize

Bases: object

Helper methods allowing to convert size to number of blocks and back.

Note: The class is not intended to be instantiated

BLOCK_SIZE = 16

static align(size)

Align given size to block size.

Parameters:: size (int) – in bytes
Return type:: int
Returns:: size aligned up to block size

static align_block_fill_random(data)

Align block size to cipher block size.

Parameters:: data (bytes) – to be aligned
Return type:: bytes
Returns:: data aligned to cipher block size, filled with random values

static is_aligned(size)

Whether size is aligned to cipher block size.

Parameters:: size (int) – given size in bytes
Return type:: bool
Returns:: True if yes, False otherwise

static to_num_blocks(size)

Converts size to number of cipher blocks.

Parameters:: size (int) – to be converted, the size must be aligned to block boundary
Return type:: int
Returns:: corresponding number of cipher blocks
Raises:: SPSDKError – Raised when size is not aligned to block boundary

spsdk.sbfile.misc.pack_timestamp(value)

Converts datetime to millisecond since 1.1.2000.

Parameters:: value (datetime) – datetime to be converted
Return type:: int
Returns:: number of milliseconds since 1.1.2000 00:00:00; 64-bit integer
Raises:: SPSDKError – When there is incorrect result of conversion

spsdk.sbfile.misc.unpack_timestamp(value)

Converts timestamp in milliseconds into datetime.

Parameters:: value (int) – number of milliseconds since 1.1.2000 00:00:00; 64-bit integer
Return type:: datetime
Returns:: corresponding datetime
Raises:: SPSDKError – When there is incorrect result of conversion

SBFile - DEVHSM

Module is used as a baseclass for DEVHSM.

class spsdk.sbfile.devhsm.devhsm.DevHsm(family, workspace=None)

Bases: BaseClass

Base class for DEVHSM.

Device HSM base class constructor.

Parameters:: family (str) – chip family
Workspace:: optional path to workspace

DEVBUFF_CUST_MK_SK_KEY_SIZE = 32

DEVBUFF_DATA_BLOCK_SIZE = 256

DEVBUFF_GEN_MASTER_CUST_CERT_PUK_OUTPUT_SIZE = 64

DEVBUFF_GEN_MASTER_ENC_MASTER_SHARE_OUTPUT_SIZE = 64

DEVBUFF_GEN_MASTER_ENC_SHARE_OUTPUT_SIZE = 48

DEVBUFF_GEN_MASTER_SHARE_INPUT_SIZE = 16

DEVBUFF_HSM_GENKEY_KEYBLOB_PUK_SIZE = 64

DEVBUFF_HSM_GENKEY_KEYBLOB_SIZE = 48

DEVBUFF_SB_SIGNATURE_SIZE = 64

DEVBUFF_SIZE = 256

DEVBUFF_WRAPPED_CUST_MK_SK_KEY_SIZE = 48

RESET_TIMEOUT = 500

command_order()

Update command order based on family.

Return type:: bool

abstract create_sb()

Create SB file.

Return type:: None

abstract export()

Export final SB file.

Return type:: bytes

abstract classmethod generate_config_template(family)

Generate configuration for selected family.

Return type:: Dict[str, str]

static get_cust_mk_sk(key)

Get binary from text or binary file.

Parameters:: key (str) – Binary customer master key symmetric key file.
Return type:: bytes
Returns:: Binary array loaded from file.
Raises:: SPSDKValueError – When invalid input value is recognized.

get_devbuff_base_address(index)

Get devbuff base address.

Return type:: int

get_keyblob_position()

Get keyblob position from database.

Return type:: int

static get_oem_share_input(binary=None)

Get binary from text or binary file.

Parameters:: binary (Optional[str]) – Path to binary file.
Return type:: bytes
Returns:: Binary array loaded from file.
Raises:: SPSDKValueError – When invalid input value is recognized.

static get_supported_families()

Get the list of supported families by Device HSM.

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

abstract oem_generate_master_share(oem_share_input)

Generate on device Encrypted OEM master share outputs.

Return type:: Any

classmethod parse(data)

Deserialize object from bytes array.

Return type:: Self

store_temp_res(file_name, data, group=None)

Storing temporary files into workspace.

Parameters:

file_name (str) – Name of file to store the data.
data (bytes) – Data to store.
group (Optional[str]) – Subfolder name, defaults to None

Return type:

None

update_keyblob_offset()

Update keyblob offset based on family.

Return type:: int

SBFile - DEVHSM utils

Utils for DevHSM.

spsdk.sbfile.devhsm.utils.get_devhsm_class(family)

Get name of DevHsm class based on family.

Parameters:: family (str) – name of the family
Raises:: SPSDKError – If the class is not found
Return type:: Type[Union[DevHsmSB31, DevHsmSBx]]
Returns:: name of the class that supports given family