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
-
info
()¶ Return text info about the instance.
- Return type
str
-
abstract classmethod
parse
(data, offset=0)¶ Deserialize object from binary.
- Return type
-
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
-
property
-
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
-
property
-
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 datapattern (
int
) – data to be writtenlength (
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 bytesoffset (
int
) – The offset of input data
- Return type
- 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
-
-
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 bytesoffset (
int
) – The offset of input data
- Return type
- Returns
Command Jump object
- Raises
SPSDKError – If incorrect header tag
-
property
spreg
¶ Return command’s Stack Pointer.
- Return type
Optional
[int
]
-
property
-
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-storecontroller_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
-
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-storecontroller_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
-
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 bytesoffset (
int
) – The offset of input data
- Return type
- 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-storecontroller_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
-
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 bytesoffset (
int
) – The offset of input data
- Return type
- 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
-
property
-
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 initializationsize (
int
) – size of configuration data used for memory initializationmem_type (
MemId
) – identification of external memory type, see enum for details
-
property
address
¶ Return command’s address.
- Return type
int
-
classmethod
parse
(data, offset=0)¶ Parse command from bytes.
- Parameters
data (
bytes
) – Input data as bytesoffset (
int
) – The offset of input data
- Return type
- 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.
-
class
spsdk.sbfile.commands.
CmdProg
¶ Bases:
spsdk.sbfile.commands.CmdBaseClass
Command Program class.
Initialize Cmd Program.
-
class
spsdk.sbfile.commands.
CmdReset
¶ Bases:
spsdk.sbfile.commands.CmdBaseClass
Command Reset class.
Initialize Command Reset.
-
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.
-
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 enumversion (
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 bytesoffset (
int
) – The offset of input data
- Return type
- Returns
parsed command object
- Raises
SPSDKError – If incorrect header tag
-
property
type
¶ Return type of the check version, see VersionCheckType enumeration.
- Return type
-
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 bytesoffset (
int
) – The offset of input data to start parsing
- Return type
- 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 representationoffset (
int
) – to start parsing data
- Return type
- 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 identificationcommands (
CmdBaseClass
) – List of commandshmac_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 imageoffset (
int
) – The offset of input dataplain_sect (
bool
) – If the sections are not encrypted; It is used for debugging only, not supported by ROM codedek (
bytes
) – The DEK value in bytes (required)mac (
bytes
) – The MAC value in bytes (required)counter (
Optional
[Counter
]) – The counter object (required)
- Return type
- 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 imageoffset (
int
) – The offset of input datadek (
bytes
) – The DEK value in bytes (required)mac (
bytes
) – The MAC value in bytes (required)counter (
Optional
[Counter
]) – The counter object (required)
- Return type
- 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 otherwisekek (
bytes
) – key for wrapping DEK and MAC keysproduct_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 onlysections (
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
-
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 imageoffset (
int
) – The offset of input datakek (
bytes
) – The Key for unwrapping DEK and MAC keys (required)
- Return type
- 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 keysproduct_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 valueflags (
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
-
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 imageoffset (
int
) – The offset of input datakek (
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
- 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 keymac (
Optional
[bytes
]) – MAC keynonce (
Optional
[bytes
]) – noncetimestamp (
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
-
class
spsdk.sbfile.sb31.
CmdConfigureMemory
(address, memory_id=0)¶ Bases:
spsdk.sbfile.sb31.commands.BaseCmd
Configure memory.
Constructor for command.
- Parameters
address (
int
) – Input addressmemory_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 arrayoffset (
int
) – The offset of input data
- Return type
- 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 addresslength (
int
) – Input lengthdestination_address (
int
) – Destination addressmemory_id_from (
int
) – Memory IDmemory_id_to (
int
) – Memory ID
-
export
()¶ Export command as bytes.
- Return type
bytes
-
info
()¶ Get info of command.
- Return type
str
-
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 addresslength (
int
) – Input lengthmemory_id (
int
) – Memory ID
-
export
()¶ Export command as bytes.
- Return type
bytes
-
info
()¶ Get info of command.
- Return type
str
-
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 arrayoffset (
int
) – The offset of input data
- Return type
- 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 addresslength (
int
) – Input lengthpattern (
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 arrayoffset (
int
) – The offset of input data
- Return type
- 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 commanddata (
bytes
) – Data to loadmemory_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 commanddata (
bytes
) – Data to loadmemory_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 commanddata (
bytes
) – Data to loadmemory_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 offsetkey_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 arrayoffset (
int
) – The offset of input data
- Return type
- 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 addressdata (
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 arrayoffset (
int
) – The offset of input data
- Return type
- 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 addressdata (
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 arrayoffset (
int
) – The offset of input data
- Return type
- 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 uidsection_type (
int
) – Input typelength (
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 arrayoffset (
int
) – The offset of input data
- Raises
SPSDKError – Raised when FORMAT is bigger than length of the data without offset
- Return type
- 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 derivationstimestamp (
int
) – Timestamp used for creating the KeyDerivationKeykey_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 arrayreturn_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 arrayreturn_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 Keyblock_number (
int
) – Block numberkey_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 Keytimestamp (
int
) – Timestamp for KDK derivationkey_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 addresslength (
int
) – Input lengthcmd_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 arrayoffset (
int
) – The offset of input datacmd_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
-
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 addressmemory_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 arrayoffset (
int
) – The offset of input data
- Return type
- 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 addresslength (
int
) – Input lengthdestination_address (
int
) – Destination addressmemory_id_from (
int
) – Memory IDmemory_id_to (
int
) – Memory ID
-
export
()¶ Export command as bytes.
- Return type
bytes
-
info
()¶ Get info of command.
- Return type
str
-
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 addresslength (
int
) – Input lengthmemory_id (
int
) – Memory ID
-
export
()¶ Export command as bytes.
- Return type
bytes
-
info
()¶ Get info of command.
- Return type
str
-
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 arrayoffset (
int
) – The offset of input data
- Return type
- 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 addresslength (
int
) – Input lengthpattern (
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 arrayoffset (
int
) – The offset of input data
- Return type
- 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 valuecounter_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 arrayoffset (
int
) – The offset of input data
- Return type
- 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 commanddata (
bytes
) – Data to loadmemory_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 classaddress (
int
) – Address for the load commanddata (
bytes
) – Data to loadmemory_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 arrayoffset (
int
) – The offset of input data
- Return type
- 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 commanddata (
bytes
) – Data to loadmemory_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 commanddata (
bytes
) – Data to loadmemory_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 offsetkey_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 arrayoffset (
int
) – The offset of input data
- Return type
- 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 addressdata (
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 arrayoffset (
int
) – The offset of input data
- Return type
- 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 addressdata (
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 arrayoffset (
int
) – The offset of input data
- Return type
- 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 uidsection_type (
int
) – Input typelength (
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 arrayoffset (
int
) – The offset of input data
- Raises
SPSDKError – Raised when FORMAT is bigger than length of the data without offset
- Return type
- 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 arrayoffset (
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 Truepck (
Optional
[bytes
]) – Part Common Key (needed if is_encrypted is True), defaults to Nonetimestamp (
Optional
[int
]) – Timestamp used for encryption (needed if is_encrypted is True), defaults to Nonekdk_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
-
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 Nonetimestamp (
Optional
[int
]) – Timestap (number of seconds since Jan 1st, 200), if None use current timeis_nxp_container (
bool
) – NXP provisioning SB file, defaults to Falseflags (
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