SBFile Module API

Module implementing SBFile.

SBFile Commands

Commands used by SBFile module.

class spsdk.sbfile.commands.CmdBaseClass(tag)

Bases: spsdk.utils.crypto.abstract.BaseClass

Base class for all commands.

Initialize CmdBase.

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

Return object serialized into bytes.

Return type

bytes

property header

Return command header.

Return type

CmdHeader

info()

Return text info about the instance.

Return type

str

abstract classmethod parse(data, offset=0)

Deserialize object from binary.

Return type

CmdBaseClass

property raw_size

Return size of the command in binary format (including header).

Return type

int

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

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

Return command’s address.

Return type

int

property argument

Return command’s argument.

Return type

int

classmethod parse(data, offset=0)

Parse command from bytes.

Parameters

  • data (bytes) – Input data as bytes

  • offset (int) – The offset of input data

Return type

CmdCall

Returns

Command Call object

Raises

SPSDKError – If incorrect header tag

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

Bases: spsdk.sbfile.commands.CmdBaseClass

Command Erase class.

Initialize Command Erase.

property address

Return command’s address.

Return type

int

property flags

Return command’s flag.

Return type

int

property length

Return command’s count.

Return type

int

classmethod parse(data, offset=0)

Parse command from bytes.

Parameters

  • data (bytes) – Input data as bytes

  • offset (int) – The offset of input data

Return type

CmdErase

Returns

Command Erase object

Raises

SPSDKError – If incorrect header tag

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

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

Return address of the command Fill.

Return type

int

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

Return command in binary form (serialization).

Return type

bytes

classmethod parse(data, offset=0)

Parse command from bytes.

Parameters

  • data (bytes) – Input data as bytes

  • offset (int) – The offset of input data

Return type

CmdFill

Returns

Command Fill object

Raises

SPSDKError – If incorrect header tag

property pattern

Return binary data to fill.

Return type

bytes

property raw_size

Calculate raw size of header.

Return type

int

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

Bases: object

SBFile command header.

Initialize header.

FORMAT = '<2BH3L'
SIZE = 16
property crc

Calculate CRC for the header data.

Return type

int

export()

Export command header as bytes.

Return type

bytes

classmethod parse(data, offset=0)

Parse command header from bytes.

Parameters

  • data (bytes) – Input data as bytes

  • offset (int) – The offset of input data

Return type

CmdHeader

Returns

CMDHeader object

Raises

  • Exception – raised when size is incorrect

  • SPSDKError – Raised when CRC is incorrect

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

Bases: spsdk.sbfile.commands.CmdBaseClass

Command Jump class.

Initialize Command Jump.

property address

Return address of the command Jump.

Return type

int

property argument

Return command’s argument.

Return type

int

classmethod parse(data, offset=0)

Parse command from bytes.

Parameters

  • data (bytes) – Input data as bytes

  • offset (int) – The offset of input data

Return type

CmdJump

Returns

Command Jump object

Raises

SPSDKError – If incorrect header tag

property spreg

Return command’s Stack Pointer.

Return type

Optional[int]

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

Bases: spsdk.sbfile.commands.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.commands.CmdKeyStoreBackupRestore(address, controller_id)

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

Return address where to backup key-store or source for restoring key-store.

Return type

int

abstract classmethod cmd_id()

Return command ID.

Return type

EnumCmdTag

property controller_id

Return controller ID of the memory to backup key-store or source memory to load key-store back.

Return type

int

classmethod parse(data, offset=0)

Parse command from bytes.

Parameters

  • data (bytes) – Input data as bytes

  • offset (int) – The offset of input data

Return type

CmdKeyStoreBackupRestore

Returns

CmdKeyStoreBackupRestore object

Raises

SPSDKError – When there is invalid header tag

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

Bases: spsdk.sbfile.commands.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.commands.CmdLoad(address, data)

Bases: spsdk.sbfile.commands.CmdBaseClass

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

Initialize CMD Load.

property address

Return address in target processor to load data.

Return type

int

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

Export command as binary.

Return type

bytes

classmethod parse(data, offset=0)

Parse command from bytes.

Parameters

  • data (bytes) – Input data as bytes

  • offset (int) – The offset of input data

Return type

CmdLoad

Returns

CMD Load object

Raises

  • SPSDKError – Raised when there is invalid CRC

  • SPSDKError – When there is incorrect header tag

property raw_size

Return aligned size of the command including header and data.

Return type

int

class spsdk.sbfile.commands.CmdMemEnable(address, size, mem_type)

Bases: spsdk.sbfile.commands.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_type (MemId) – identification of external memory type, see enum for details

property address

Return command’s address.

Return type

int

property mem_type

Return memory to be enabled.

Return type

MemId

classmethod parse(data, offset=0)

Parse command from bytes.

Parameters

  • data (bytes) – Input data as bytes

  • offset (int) – The offset of input data

Return type

CmdMemEnable

Returns

Command Memory Enable object

Raises

SPSDKError – If incorrect header tag

property size

Return command’s size.

Return type

int

class spsdk.sbfile.commands.CmdNop

Bases: spsdk.sbfile.commands.CmdBaseClass

Command NOP class.

Initialize Command Nop.

classmethod parse(data, offset=0)

Parse command from bytes.

Parameters

  • data (bytes) – Input data as bytes

  • offset (int) – The offset of input data

Return type

CmdNop

Returns

CMD Nop object

Raises

SPSDKError – When there is incorrect header tag

class spsdk.sbfile.commands.CmdProg

Bases: spsdk.sbfile.commands.CmdBaseClass

Command Program class.

Initialize Cmd Program.

classmethod parse(data, offset=0)

Parse command from bytes.

Parameters

  • data (bytes) – Input data as bytes

  • offset (int) – The offset of input data

Return type

CmdProg

Returns

parsed command object

Raises

SPSDKError – If incorrect header tag

class spsdk.sbfile.commands.CmdReset

Bases: spsdk.sbfile.commands.CmdBaseClass

Command Reset class.

Initialize Command Reset.

classmethod parse(data, offset=0)

Parse command from bytes.

Parameters

  • data (bytes) – Input data as bytes

  • offset (int) – The offset of input data

Return type

CmdReset

Returns

Cmd Reset object

Raises

SPSDKError – If incorrect header tag

class spsdk.sbfile.commands.CmdTag

Bases: spsdk.sbfile.commands.CmdBaseClass

Command TAG class.

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

Initialize Command Tag.

classmethod parse(data, offset=0)

Parse command from bytes.

Parameters

  • data (bytes) – Input data as bytes

  • offset (int) – The offset of input data

Return type

CmdTag

Returns

parsed instance

Raises

SPSDKError – When there is incorrect header tag

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

Bases: spsdk.sbfile.commands.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, offset=0)

Parse command from bytes.

Parameters

  • data (bytes) – Input data as bytes

  • offset (int) – The offset of input data

Return type

CmdVersionCheck

Returns

parsed command object

Raises

SPSDKError – If incorrect header tag

property type

Return type of the check version, see VersionCheckType enumeration.

Return type

VersionCheckType

property version

Return minimal version expected.

Return type

int

class spsdk.sbfile.commands.EnumCmdTag

Bases: spsdk.utils.easy_enum.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.commands.EnumSectionFlag

Bases: spsdk.utils.easy_enum.Enum

Section flags.

BOOTABLE = 1
CLEARTEXT = 2
LAST_SECT = 32768
class spsdk.sbfile.commands.VersionCheckType

Bases: spsdk.utils.easy_enum.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.commands.parse_command(data, offset=0)

Parse SB 2.x command from bytes.

Parameters

  • data (bytes) – Input data as bytes

  • offset (int) – The offset of input data to start parsing

Return type

CmdBaseClass

Returns

parsed command object

Raises

SPSDKError – Raised when there is unsupported command provided

SBFile Headers

Image header.

class spsdk.sbfile.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: spsdk.utils.crypto.abstract.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

info()

Get info of Header as string.

Return type

str

classmethod parse(data, offset=0)

Deserialization from binary form.

Parameters

  • data (bytes) – binary representation

  • offset (int) – to start parsing data

Return type

ImageHeaderV2

Returns

parsed instance of the header

Raises

Exception – raised when size/signature is incorrect

SBFile Segments

Sections within SBfile.

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

Bases: spsdk.utils.crypto.abstract.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, dbg_info=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)

  • dbg_info (Optional[List[str]]) – Optional[List[str]] optional list to export debug information about content in text format

Return type

bytes

Returns

exported bytes

Raises

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

property hmac_count

Number of HMACs.

Return type

int

info()

Get object info.

Return type

str

property is_last

Check whether the section is the last one.

Return type

bool

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

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

property raw_size

Raw size of section.

Return type

int

property uid

Boot Section UID.

Return type

int

class spsdk.sbfile.sections.CertSectionV2(cert_block)

Bases: spsdk.utils.crypto.abstract.BaseClass

Certificate Section V2 class.

Initialize CertBlockV2.

HMAC_SIZE = 32
SECT_MARK = 1852270963
property cert_block

Return certification block.

Return type

CertBlockV2

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

  • Exception – raised when dek, mac, counter have invalid format

  • SPSDKError – Raised size of exported bytes is invalid

info()

Get object info.

Return type

str

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

Calculate raw size of section.

Return type

int

SBFile Images

Boot Image V2.0, V2.1.

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

Bases: spsdk.utils.crypto.abstract.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

Return certificate block; None if SB file not signed or block not assigned yet.

Return type

Optional[CertBlockV2]

property cert_header_size

Return image raw size (not aligned) for certificate header.

Return type

int

property dek

Data encryption key.

Return type

bytes

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

Return image header.

Return type

ImageHeaderV2

info()

Return text description of the instance.

Return type

str

property kek

Return key for wrapping DEK and MAC keys.

Return type

bytes

property mac

Message authentication code.

Return type

bytes

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

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)

Return type

BootImageV20

Returns

parsed image object

Raises

  • Exception – raised when header is in wrong format

  • Exception – raised when there is invalid header version

  • Exception – raised when signature is incorrect

  • SPSDKError – Raised when kek is empty

  • Exception – raised when header’s nonce is not present

property private_key_pem_data

Return private key data for signed images, decrypted in PEM format.

Return type

Optional[bytes]

property raw_size

Return image raw size.

Return type

int

property raw_size_without_signature

Return image raw size without signature, used to calculate image blocks.

Return type

int

property signed

Check whether sb is signed + encrypted or only encrypted.

Return type

bool

update()

Update boot image.

Return type

None

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

Bases: spsdk.utils.crypto.abstract.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

Return certificate block; None if SB file not signed or block not assigned yet.

Return type

Optional[CertBlockV2]

property cert_header_size

Return image raw size (not aligned) for certificate header.

Return type

int

property dek

Data encryption key.

Return type

bytes

export(padding=None, dbg_info=None)

Serialize image object.

Parameters

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

  • dbg_info (Optional[List[str]]) – optional list, where debug info is exported in text form

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

property header

Return image header.

Return type

ImageHeaderV2

info()

Return text description of the instance.

Return type

str

property kek

Return key to wrap DEC and MAC keys.

Return type

bytes

property mac

Message authentication code.

Return type

bytes

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

  • Exception – raised when header is in incorrect format

  • Exception – raised when signature is incorrect

  • SPSDKError – Raised when kek is empty

  • Exception – raised when header’s nonce not present”

property private_key_pem_data

Return binary data of private key for signing; decrypted binary data in PEM format.

None if not assigned yet or image not signed.

Return type

Optional[bytes]

property raw_size

Return image raw size (not aligned).

Return type

int

property signed

Return flag whether SB file is signed.

Return type

bool

update()

Update BootImageV21.

Return type

None

class spsdk.sbfile.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

Return DEK key.

Return type

bytes

property mac

Return MAC key.

Return type

bytes

property nonce

Return NONCE.

Return type

bytes

property timestamp

Return timestamp.

Return type

datetime

SBFile Version 3.1.

SB31 module of sbfile.

class spsdk.sbfile.sb31.CmdCall(address)

Bases: spsdk.sbfile.sb31.commands.BaseCmd

Address will be the address to jump.

Constructor for Command.

Parameters

address (int) – Input address

info()

Get info of command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdCall

Returns

CmdCall

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

Bases: spsdk.sbfile.sb31.commands.BaseCmd

Configure memory.

Constructor for command.

Parameters

  • address (int) – Input address

  • memory_id (int) – Memory ID

export()

Export command as bytes.

Return type

bytes

info()

Get info of command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdConfigureMemory

Returns

CmdConfigureMemory

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

Bases: spsdk.sbfile.sb31.commands.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

info()

Get info of command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdCopy

Returns

CmdCopy

Raises

SPSDKError – Invalid padding

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

Bases: spsdk.sbfile.sb31.commands.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

info()

Get info of command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdErase

Returns

CmdErase

Raises

SPSDKError – Invalid padding

class spsdk.sbfile.sb31.CmdExecute(address)

Bases: spsdk.sbfile.sb31.commands.BaseCmd

Address will be the jump-to address.

Constructor for Command.

Parameters

address (int) – Input address

info()

Get info of command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdExecute

Returns

CmdExecute

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

Bases: spsdk.sbfile.sb31.commands.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

info()

Get info of command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdFillMemory

Returns

CmdErase

Raises

SPSDKError – Invalid padding

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

Bases: spsdk.sbfile.sb31.commands.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

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

Bases: spsdk.sbfile.sb31.commands.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

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

Bases: spsdk.sbfile.sb31.commands.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

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

Bases: spsdk.sbfile.sb31.commands.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 KeyWraps

Bases: spsdk.utils.easy_enum.Enum

KeyWrap IDs used by the CmdLoadKeyBlob command.

NXP_CUST_KEK_EXT_SK = 17
NXP_CUST_KEK_INT_SK = 16
export()

Export command as bytes.

Return type

bytes

info()

Get info of command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdLoadKeyBlob

Returns

CmdLoadKeyBlob

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

Bases: spsdk.sbfile.sb31.commands.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 parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdProgFuses

Returns

CmdProgFuses

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

Bases: spsdk.sbfile.sb31.commands.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 parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdProgIfr

Returns

CmdProgFuses

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

Bases: spsdk.sbfile.sb31.commands.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

info()

Get info of Section header.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Raises

SPSDKError – Raised when FORMAT is bigger than length of the data without offset

Return type

CmdSectionHeader

Returns

CmdSectionHeader

class spsdk.sbfile.sb31.EnumCmdTag

Bases: spsdk.utils.easy_enum.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

SBFile Version 3.1. functions

File including helping functions.

class spsdk.sbfile.sb31.functions.KeyDerivationMode

Bases: spsdk.utils.easy_enum.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: spsdk.sbfile.sb31.commands.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

Get address.

Return type

int

export()

Export command as bytes.

Return type

bytes

classmethod header_parse(cmd_tag, data, offset=0)

Parse header command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

  • 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

info()

Get info of command.

Return type

str

property length

Get length.

Return type

int

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

Bases: spsdk.sbfile.sb31.commands.BaseCmd

Address will be the address to jump.

Constructor for Command.

Parameters

address (int) – Input address

info()

Get info of command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdCall

Returns

CmdCall

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

Bases: spsdk.sbfile.sb31.commands.BaseCmd

Configure memory.

Constructor for command.

Parameters

  • address (int) – Input address

  • memory_id (int) – Memory ID

export()

Export command as bytes.

Return type

bytes

info()

Get info of command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdConfigureMemory

Returns

CmdConfigureMemory

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

Bases: spsdk.sbfile.sb31.commands.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

info()

Get info of command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdCopy

Returns

CmdCopy

Raises

SPSDKError – Invalid padding

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

Bases: spsdk.sbfile.sb31.commands.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

info()

Get info of command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdErase

Returns

CmdErase

Raises

SPSDKError – Invalid padding

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

Bases: spsdk.sbfile.sb31.commands.BaseCmd

Address will be the jump-to address.

Constructor for Command.

Parameters

address (int) – Input address

info()

Get info of command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdExecute

Returns

CmdExecute

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

Bases: spsdk.sbfile.sb31.commands.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

info()

Get info of command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdFillMemory

Returns

CmdErase

Raises

SPSDKError – Invalid padding

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

Bases: spsdk.sbfile.sb31.commands.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 COUNTER_ID

Bases: spsdk.utils.easy_enum.Enum

Counter IDs used by the CmdFwVersionCheck command.

BOOTLOADER = 3
NONE = 0
NONSECURE = 1
RADIO = 3
SECURE = 2
SNT = 4
export()

Export command as bytes.

Return type

bytes

info()

Get info of command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdFwVersionCheck

Returns

CmdFwVersionCheck

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

Bases: spsdk.sbfile.sb31.commands.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

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

Bases: spsdk.sbfile.sb31.commands.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

info()

Get info about the load command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdLoadBase

Returns

CmdLoad

Raises

SPSDKError – Invalid cmd_tag was found

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

Bases: spsdk.sbfile.sb31.commands.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

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

Bases: spsdk.sbfile.sb31.commands.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

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

Bases: spsdk.sbfile.sb31.commands.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 KeyWraps

Bases: spsdk.utils.easy_enum.Enum

KeyWrap IDs used by the CmdLoadKeyBlob command.

NXP_CUST_KEK_EXT_SK = 17
NXP_CUST_KEK_INT_SK = 16
export()

Export command as bytes.

Return type

bytes

info()

Get info of command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdLoadKeyBlob

Returns

CmdLoadKeyBlob

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

Bases: spsdk.sbfile.sb31.commands.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 parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdProgFuses

Returns

CmdProgFuses

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

Bases: spsdk.sbfile.sb31.commands.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 parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Return type

CmdProgIfr

Returns

CmdProgFuses

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

Bases: spsdk.sbfile.sb31.commands.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

info()

Get info of Section header.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

Raises

SPSDKError – Raised when FORMAT is bigger than length of the data without offset

Return type

CmdSectionHeader

Returns

CmdSectionHeader

class spsdk.sbfile.sb31.commands.MainCmd

Bases: object

Functions for creating cmd intended for inheritance.

export()

Export command as bytes.

Return type

bytes

abstract info()

Get info of command.

Return type

str

classmethod parse(data, offset=0)

Parse command from bytes array.

Return type

object

spsdk.sbfile.sb31.commands.parse_command(data, offset=0)

Parse command from bytes array.

Parameters

  • data (bytes) – Input data as bytes array

  • offset (int) – The offset of input data

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.SecureBinary31Commands(curve_name, is_encrypted=True, pck=None, timestamp=None, kdk_access_rights=None)

Bases: spsdk.utils.crypto.abstract.BaseClass

Blob containing SB3.1 commands.

Initialize container for SB3.1 commands.

Parameters

  • curve_name (str) – Name of the ECC curve used for Secure binary (secp256r1/secp384r1)

  • 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

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]

info()

Get string information for commands in the container.

Return type

str

classmethod parse(data, offset=0)

Parse binary data into SecureBinary31Commands.

Raises

NotImplementedError – Not yet implemented

Return type

SecureBinary31Commands

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

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

Bases: spsdk.utils.crypto.abstract.BaseClass

Header of the SecureBinary V3.1.

Initialize the SecureBinary V3.1 Header.

Parameters

  • firmware_version (int) – Firmaware version (must be bigger than current CMPA record)

  • curve_name (str) – Name of the ECC curve used for Secure binary (secp256r1/secp384r1)

  • description (Optional[str]) – Custom description up to 16 characters long, defaults to None

  • timestamp (Optional[int]) – Timestap (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 (currently un-used), defaults to 0

DESCRIPTION_LENGTH = 16
FORMAT_VERSION = '3.1'
HEADER_FORMAT = '<4s2H3LQ4L16s'
HEADER_SIZE = 60
MAGIC = b'sbv3'
calculate_block_size()

Calculate the the data block size.

Return type

int

calculate_cert_block_offset()

Calculate the offset to the Certification block.

Return type

int

export()

Serialize the SB file to bytes.

Return type

bytes

info()

Get info of SB v31 as a string.

Return type

str

classmethod parse(data, offset=0)

Parse binary data into SecureBinary31Header.

Raises

NotImplementedError – Not yet implemented

Return type

SecureBinary31Header