Image Module API¶
Module implementing functionality of srktool, dcdgen, mkimage and other similar tools.
Image Classes¶
Image.
-
class
spsdk.image.images.
BootImg2
(address=0, offset=1024, version=65, plugin=False)¶ Bases:
spsdk.image.images.BootImgBase
IMX Boot Image v2.
Initialize boot image object.
- Parameters
address (
int
) – The start address of img in target memoryoffset (
int
) – The IVT offsetversion (
int
) – The version of boot img formatplugin (
bool
) – if plugin
-
APP_ALIGN
= 4096¶
-
CSF_SIZE
= 8192¶
-
HEAD_SIZE
= {256: 768, 1024: 3072}¶
-
add_image
(data, img_type=4, address=0)¶ Add specific image into the main boot image.
- Parameters
data (
bytes
) – Raw data of imgimg_type (
EnumAppType
) – Type of imgaddress (
int
) – address in RAM
- Raises
Exception – Raised when the data type is unknown
- Return type
None
-
export
()¶ Export image as bytes array.
- Return type
bytes
- Returns
bytes
-
info
()¶ String representation of the IMX Boot Image v2.
- Return type
str
-
classmethod
parse
(stream, step=256, size=None)¶ Parse image from stream buffer or bytes array.
- Parameters
stream (
Union
[bytes
,bytearray
,BufferedReader
,BytesIO
]) – The stream buffer or bytes arraystep (
int
) – Image searching stepsize (
Optional
[int
]) – parsing size
- Raises
TypeError – raised when value type is incorrect
Exception – raised when there is not an i.MX Boot Image
- Return type
- Returns
BootImg2 object
-
property
plugin
¶ Plugin.
- Return type
bool
-
property
size
¶ Size of IMX Boot Image v2..
- Return type
int
-
property
version
¶ Version of IMX Boot Image v2.
- Return type
int
-
class
spsdk.image.images.
BootImg3a
(address=0, offset=1024, version=67)¶ Bases:
spsdk.image.images.BootImgBase
i.MX Boot Image v3a.
Initialize boot image object.
- Parameters
address (
int
) – The start address of img in target memoryoffset (
int
) – The IVT offsetversion (
int
) – The version of boot img format
-
APP_ALIGN
= 4608¶
-
COUNT_OF_CONTAINERS
= 2¶
-
CSF_SIZE
= 8192¶
-
HEAD_SIZE
= {1024: 50176, 4096: 5120}¶
-
IMG_AUTO_ALIGN
= 16¶
-
IMG_TYPE_CSF
= 1¶
-
IMG_TYPE_DATA
= 4¶
-
IMG_TYPE_EXEC
= 3¶
-
IMG_TYPE_SCD
= 2¶
-
INITIAL_LOAD_ADDR_AP_ROM
= 1114112¶
-
INITIAL_LOAD_ADDR_FLEXSPI
= 134217728¶
-
INITIAL_LOAD_ADDR_SCU_ROM
= 536928256¶
-
PADDING_VAL
= 0¶
-
SCFW_FLAGS_APP
= 20275140¶
-
SCFW_FLAGS_M4_0
= 4870498¶
-
SCFW_FLAGS_M4_1
= 5198499¶
-
SCFW_FLAGS_SCFW
= 1¶
-
SECTOR_SIZE
= 512¶
-
add_image
(data, img_type=4, address=0)¶ Add specific image into the main boot image.
- Parameters
data (
bytes
) – Raw data of imageimg_type (
EnumAppType
) – Type of imageaddress (
int
) – address in RAM
- Raises
Exception – raised when data type is unknown
- Return type
None
-
export
()¶ Export Image as binary blob.
- Return type
bytes
-
info
()¶ String representation of the i.MX Boot Image v3a.
- Return type
str
-
classmethod
parse
(stream, step=256, size=None)¶ Parse image from stream buffer or bytes array.
- Parameters
stream (
Union
[bytes
,bytearray
,BufferedReader
,BytesIO
]) – The stream buffer or bytes arraystep (
int
) – Image searching stepsize (
Optional
[int
]) – parsing size
- Raises
TypeError – raised when the values type is incorrect
Exception – raised when there is not an i.MX Boot Image
- Return type
- Returns
BootImg3a object
-
property
plg
¶ PLG.
- Return type
bool
-
class
spsdk.image.images.
BootImg3b
(address=0, offset=1024, version=67)¶ Bases:
spsdk.image.images.BootImgBase
IMX Boot Image v3b.
Initialize boot image object.
- Parameters
address (
int
) – The start address of img in target memoryoffset (
int
) – The IVT offsetversion (
int
) – The version of boot img format
-
APP_ALIGN
= 4608¶
-
COUNT_OF_CONTAINERS
= 2¶
-
CSF_SIZE
= 8192¶
-
HEAD_SIZE
= {1024: 50176, 4096: 5120}¶
-
IMG_AUTO_ALIGN
= 16¶
-
IMG_TYPE_CSF
= 1¶
-
IMG_TYPE_DATA
= 4¶
-
IMG_TYPE_EXEC
= 3¶
-
IMG_TYPE_SCD
= 2¶
-
INITIAL_LOAD_ADDR_AP_ROM
= 1114112¶
-
INITIAL_LOAD_ADDR_FLEXSPI
= 134217728¶
-
INITIAL_LOAD_ADDR_SCU_ROM
= 536928256¶
-
PADDING_VAL
= 0¶
-
SCFW_FLAGS_A53
= 20267028¶
-
SCFW_FLAGS_A72
= 20267109¶
-
SCFW_FLAGS_M4_0
= 4870498¶
-
SCFW_FLAGS_M4_1
= 5198499¶
-
SCFW_FLAGS_SCFW
= 1¶
-
SECTOR_SIZE
= 512¶
-
add_image
(data, img_type=4, address=0)¶ Add specific image into the main boot image.
- Parameters
data (
bytes
) – Raw data of imageimg_type (
EnumAppType
) – Type of imageaddress (
int
) – address in RAM
- Raises
Exception – raised SCFW is not defined before SCD
Exception – raised when there is unknown image type
- Return type
None
-
export
()¶ Export.
- Return type
bytes
-
info
()¶ String representation of the IMX Boot Image v3b.
- Return type
str
-
classmethod
parse
(stream, step=256, size=None)¶ Parse image from stream buffer or bytes array.
- Parameters
stream (
Union
[bytes
,bytearray
,BufferedReader
,BytesIO
]) – The stream buffer or bytes arraystep (
int
) – Image searching stepsize (
Optional
[int
]) – parsing size
- Raises
TypeError – When the value is incorrect
Exception – If there is not an i.MX Boot Image
- Return type
- Returns
BootImg3b object
-
property
plg
¶ PLG.
- Return type
bool
-
class
spsdk.image.images.
BootImg4
(address=0, offset=1024)¶ Bases:
spsdk.image.images.BootImgBase
i.MX Boot Image v4.
Initialize boot image object.
- Parameters
address (
int
) – The start address of image in target memoryoffset (
int
) – The image offset
-
add_image
(data, img_type, address)¶ Not implemented.
- Return type
None
-
export
()¶ Export.
- Return type
bytes
-
info
()¶ String representation of the i.MX Boot Image v4.
- Return type
str
-
classmethod
parse
(stream, step=256, size=None)¶ Parse image from stream buffer or bytes array.
- Parameters
stream (
Union
[bytes
,bytearray
,BufferedReader
,BytesIO
]) – The stream buffer or bytes arraystep (
int
) – Image searching stepsize (
Optional
[int
]) – parsing size
- Return type
- Returns
BootImg4 object
- Raises
TypeError – Raised when the value type is incorrect
Exception – If there is not an i.MX Boot Image
-
class
spsdk.image.images.
BootImg8m
(address=0, offset=1024, version=65, plugin=False)¶ Bases:
spsdk.image.images.BootImgBase
IMX Boot Image.
Initialize boot image object.
- Parameters
address (
int
) – The start address of img in target memoryoffset (
int
) – The IVT offsetversion (
int
) – The version of boot img formatplugin (
bool
) – if plugin
-
APP_ALIGN
= 4096¶
-
CSF_SIZE
= 8192¶
-
HEAD_SIZE
= {256: 768, 1024: 3072}¶
-
add_image
(data, img_type=4, address=0)¶ Add specific image into the main boot image.
- Parameters
data (
bytes
) – Raw data of imgimg_type (
EnumAppType
) – Type of imgaddress (
int
) – address in RAM
- Raises
Exception – raised when data type is unknown
- Return type
None
-
export
()¶ Export Image as bytes array.
- Return type
bytes
- Returns
bytes
-
info
()¶ String representation of the IMX Boot Image.
- Return type
str
-
classmethod
parse
(stream, step=256, size=None)¶ Parse image from stream buffer or bytes array.
- Parameters
stream (
Union
[bytes
,bytearray
,BufferedReader
,BytesIO
]) – The stream buffer or bytes arraystep (
int
) – Image searching stepsize (
Optional
[int
]) – parsing size
- Raises
TypeError – raised when the value type is incorrect
Exception – raised when there is not an i.MX Boot Image
- Return type
- Returns
BootImg2 object
-
property
plugin
¶ Plugin.
- Return type
bool
-
property
size
¶ Size of IMX Boot Image.
- Return type
int
-
property
version
¶ Version of IMX Boot Image.
- Return type
int
-
class
spsdk.image.images.
BootImgBase
(address, offset)¶ Bases:
object
IMX Boot Image Base.
Initialize boot image object.
- Parameters
address (
int
) – The start address of img in target memoryoffset (
int
) – The IVT offset
-
add_image
(data, img_type, address)¶ Add specific image into the main boot image.
- Parameters
data (
bytes
) – Raw binary data of the application imageimg_type (
EnumAppType
) – see EnumAppTypeaddress (
int
) – TBD
- Return type
None
-
property
dcd
¶ Device configuration data (DCD) segment; None if not assigned.
- Return type
Optional
[SegDCD
]
-
export
()¶ Binary representation of the instance (serialization).
- Return type
bytes
-
info
()¶ Text info about the instance.
- Return type
str
-
classmethod
parse
(stream, step=256, size=None)¶ Parse of IMX Boot Image Base.
- Return type
-
class
spsdk.image.images.
BootImgRT
(address, offset=4096, version=64, plugin=False)¶ Bases:
spsdk.image.images.BootImgBase
IMX Boot Image v2.
Initialize boot image object.
- Parameters
address (
int
) – The start address of img in target memory, where the image is executedoffset (
int
) – The IVT offset; use IVT_OFFSET_NOR_FLASH for NOR-FLASH or IVT_OFFSET_OTHERversion (
int
) – The version of boot img format; default value should be usedplugin (
bool
) – Do not use; see self.plugin property
-
BDT_SIZE
= 32¶
-
BEE_OFFSET
= 1024¶
-
CSF_SIZE
= 8192¶
-
DEK_SIZE
= 512¶
-
FCB_OFFSETS
= (0, 1024)¶
-
IVT_OFFSETS
= (0, 1024, 4096)¶
-
IVT_OFFSET_NOR_FLASH
= 4096¶
-
IVT_OFFSET_OTHER
= 1024¶
-
NON_XIP_APP_OFFSET
= 4096¶
-
VERSIONS
= (64, 65, 66, 67)¶
-
XIP_APP_OFFSET
= 8192¶
-
add_csf_encrypted
(version, srk_table, src_key_index, csf_cert, csf_priv_key, img_cert, img_priv_key)¶ Add CSF with image encryption.
Before calling, application image and address must be assigned
- Parameters
version (
int
) – CSF segment versionsrk_table (
SrkTable
) – SRK table of root certificates; must contain min 1, max 4 certificatessrc_key_index (
int
) – index of selected SRK key used for authentication, 0..srk_table.len - 1csf_cert (
bytes
) – CSF certificatecsf_priv_key (
bytes
) – CSF private key; decrypted binary data in PEM formatimg_cert (
bytes
) – IMG certificateimg_priv_key (
bytes
) – IMG private key; decrypted binary data in PEM format
- Return type
None
-
add_csf_standard_auth
(version, srk_table, src_key_index, csf_cert, csf_priv_key, img_cert, img_priv_key)¶ Add CSF with standard authentication.
Before calling, application image and address must be assigned
- Parameters
version (
int
) – CSF segment versionsrk_table (
SrkTable
) – SRK table of root certificates; must contain min 1, max 4 certificatessrc_key_index (
int
) – index of selected SRK key used for authenticationcsf_cert (
bytes
) – CSF certificatecsf_priv_key (
bytes
) – CSF private key; decrypted binary data in PEM formatimg_cert (
bytes
) – IMG certificateimg_priv_key (
bytes
) – IMG private key; decrypted binary data in PEM format
- Return type
None
-
add_dcd_bin
(data)¶ Add DCD binary data.
- Parameters
data (
bytes
) – DCD binary data to be added- Return type
None
-
add_image
(data, img_type=4, address=- 1, dek_key=None, nonce=None)¶ Add specific image into the main boot image.
- Parameters
data (
bytes
) – Raw data of imgimg_type (
EnumAppType
) – value must be EnumAppType.APP, no other options supported in this classaddress (
int
) – start address of the application (entry point); Use -1 to detect the address from the imagedek_key (
Optional
[bytes
]) – key for AES128 image HAB encryption [16 bytes], - use None for non-encrypted images; - use empty bytes to create random key (recommended) - use fixed key for testing to produce stable outputnonce (
Optional
[bytes
]) – initial vector for AEAD HAB encryption, if not specified random value is used; For non-encrypted image use None The parameter should be used only for testing to produce stable output
- Raises
ValueError – if any parameter is not valid
- Return type
None
-
static
aead_nonce_len
(app_data_len)¶ Nonce len for AEAD encryption.
Note: The code was taken from CST tool
- Return type
int
-
property
app_offset
¶ - Return type
int
- Returns
offset in the binary image, where the application starts.
Please mind: the offset include FCB block (even the FCB block is not exported) The offset is 0x2000 for XIP images and 0x1000 for non-XIP images
-
property
bee
¶ - Return type
- Returns
BEE segment that contains configuration of encrypted XIP.
By default, BEE segment is empty. PRDB regions may be specified only for XIP images.
-
property
bee_encrypted
¶ True if BEE encrypted XIP image (with SW keys); False otherwise; see also hab_encrypted.
- Return type
bool
-
property
csf
¶ Command Sequence File (CSF), signature block for Secure Boot.
- Return type
Optional
[SegCSF
]
-
property
decrypted_app_data
¶ Return decrypted binary application data.
Note: dek key, mac and nonce must be assigned for decryption
- Return type
bytes
-
property
dek_img_offset
¶ Offset of the DEK key in the image; -1 if DEK key address is available (see dek_ram_address).
- Return type
int
-
property
dek_key
¶ DEK key for encrypted images; None for non-encrypted images.
- Return type
Optional
[bytes
]
-
property
dek_ram_address
¶ Address of the DEK key in the RAM memory retrieved from the corresponding command.
-1 if the image does not contain command for DEK key installation
- Return type
int
-
property
enabled_csf
¶ Enabled Command Sequence File (CSF) segment; None if CSF is not defined or it is not enabled.
- Return type
Optional
[SegCSF
]
-
export
(zulu=datetime.datetime(2021, 7, 15, 10, 2, 30, 4647, tzinfo=datetime.timezone.utc), dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export image as bytes array.
- Parameters
zulu (
datetime
) – optional UTC datetime; should be used only if you need fixed datetime for the test Note: the parameter is applied to CSF only, so it is not used for unsigned imagesdbg_info (
DebugInfo
) – optional instance to provide info about exported data
- Raises
ValueError – If the image is not encrypted
- Return type
bytes
- Returns
bytes
-
property
fcb
¶ Flash Configuration(Control) Block, binary data; content depends on FLASH type.
- Return type
-
property
hab_encrypted
¶ True if HAB encrypted; False otherwise; see also bee_encrypted.
- Return type
bool
-
info
()¶ Text info about the instance.
- Return type
str
-
property
ivt_offset
¶ Offset of the Image Vector Table (IVT) in the image.
- Return type
int
-
classmethod
parse
(stream, step=0, size=None)¶ Parse bootable RT image from stream buffer or bytes array.
- Parameters
stream (
Union
[bytes
,bytearray
,BufferedReader
,BytesIO
]) – The stream buffer or bytes arraystep (
int
) – Image searching step (this parameter is not used for RT)size (
Optional
[int
]) – parsing size; None to parse till the end of the stream
- Raises
TypeError – Raised when the value type is incorrect
- Return type
- Returns
BootImgRT object
-
property
plugin
¶ Flag whether it is plugin image type; It is not fully supported by SPSDK yet.
Plugin is designed to load a boot image from devices that are not natively supported by boot ROM.
- Return type
bool
-
set_flexspi_fcb
(data)¶ Set FlexSPI external FLASH configuration.
- Parameters
data (
Union
[bytes
,FlexSPIConfBlockFCB
]) – FlexSPIConfBlockFCB or binary data representing- Raises
ValueError – if data are not valid Flex SPI configuration block
- Return type
None
-
property
size
¶ Size of the exported binary data.
Please mind, FCB is exported optionally, but it is always included in the size
- Return type
int
-
property
version
¶ Version of the image format; must be from BootImgRT.VERSIONS.
- Return type
int
-
class
spsdk.image.images.
KernelImg
(address=0, app=None, csf=None, version=65)¶ Bases:
object
IMX Kernel Image.
Initialize the IMX Kernel Image.
-
IMAGE_MIN_SIZE
= 4096¶
-
property
address
¶ Address.
- Return type
int
-
property
app
¶ APP.
- Return type
Optional
[bytes
]
-
export
()¶ Export.
- Return type
bytes
-
info
()¶ String representation of the IMX Kernel Image.
- Return type
None
-
classmethod
parse
(data)¶ Parse.
- Return type
None
-
property
version
¶ Version.
- Return type
int
-
-
spsdk.image.images.
parse
(stream, step=256, size=None)¶ Common parser for all versions of i.MX boot images.
- Parameters
stream (
Union
[bytes
,bytearray
,BufferedReader
,BytesIO
]) – stream buffer to imagestep (
int
) – Image searching stepsize (
Optional
[int
]) – parsing size
- Raises
TypeError – raised when the format of string is incorrect
Exception – when not i.MX Boot Image is passed
- Return type
- Returns
the object of boot image
Image Commands¶
Commands for image module.
-
class
spsdk.image.commands.
CmdAuthData
(flags=0, key_index=1, sig_format=197, engine=0, engine_cfg=0, location=0, certificate=None, private_key_pem_data=None)¶ Bases:
spsdk.image.commands.CmdBase
Authenticate data command.
Initialize the Authenticate data command.
-
append
(start_address, size)¶ Append of Authenticate data command.
- Return type
None
-
clear
()¶ Clear of Authenticate data command.
- Return type
None
-
property
cmd_data_offset
¶ Offset of an additional data (such as signature or MAC, etc) in binary image.
- Return type
int
-
property
cmd_data_reference
¶ Reference to an additional data (such as certificate, signature, etc).
None if no reference was assigned;
Value type is command-specific
-
property
engine
¶ Engine.
- Return type
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export to binary form (serialization).
- Parameters
dbg_info (
DebugInfo
) – debug information about exported data- Return type
bytes
- Returns
binary representation of the command
-
property
flags
¶ Flag of Authenticate data command.
- Return type
int
-
info
()¶ Text description of the command.
- Return type
str
-
property
key_index
¶ Key index.
- Return type
int
-
property
needs_cmd_data_reference
¶ Whether the command contains a reference to an additional data.
- Return type
bool
-
classmethod
parse
(data, offset=0)¶ Convert binary representation into command (deserialization from binary data).
- Parameters
data (
bytes
) – being parsedoffset (
int
) – current position to read from data
- Return type
- Returns
parse command
-
parse_cmd_data
(data, offset)¶ Parse additional command data from binary data.
- Parameters
data (
bytes
) – to be parsedoffset (
int
) – start position in data to parse
- Return type
- Returns
parsed data object; command-specific: Signature or MAC
- Raises
ExpectedSignatureOrMACError – if unspported data object is provided
-
pop
(index)¶ Pop of Authenticate data command.
- Return type
Tuple
[int
,int
]
-
property
signature
¶ Signature referenced by location attribute.
-
update_signature
(zulu, data, base_data_addr=4294967295)¶ Update signature.
This method must be called from parent to provide data to be signed
- Parameters
zulu (
datetime
) – current UTC time+datedata (
bytes
) – currently generated binary database_data_addr (
int
) – base address of the generated data
- Raises
ValueError – When certificate or private key are not assigned
ValueError – When signatures not assigned explicitly
- Return type
bool
- Returns
True if length of the signature was unchanged, as this may affect content of the CSF section (pointer to data);
-
-
class
spsdk.image.commands.
CmdBase
(tag, param, length=None)¶ Bases:
object
Base class for all commands.
Constructor.
- Parameters
tag (
CmdTag
) – command tagparam (
int
) – TODOlength (
Optional
[int
]) – of the binary command representation, in bytes
-
property
cmd_data_offset
¶ Offset of an additional data (such as certificate, signature, etc) in binary image.
- Return type
int
-
property
cmd_data_reference
¶ Reference to a command data (such as certificate, signature, etc).
None if no reference was assigned; Value type is command-specific
- Return type
Optional
[BaseClass
]
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export to binary form (serialization).
- Parameters
dbg_info (
DebugInfo
) – debug information about exported data- Return type
bytes
- Returns
binary representation of the command
-
info
()¶ Text representation of the command.
- Return type
str
-
property
needs_cmd_data_reference
¶ Whether the command needs a reference to an additional data.
If returns True, the following methods must be implemented: - cmd_data_offset - cmd_data_reference
- Return type
bool
-
classmethod
parse
(data, offset=0)¶ Convert binary representation into command (deserialization from binary data).
- Parameters
data (
bytes
) – being parsedoffset (
int
) – current position to readd from data
- Return type
- Returns
parse command
-
parse_cmd_data
(data, offset)¶ Parse additional command data from binary data.
- Parameters
data (
bytes
) – to be parsedoffset (
int
) – start position in data to parse
- Raises
TypeError – if cmd_data is not supported by the command
- Return type
Any
-
property
size
¶ Size of command.
- Return type
int
-
class
spsdk.image.commands.
CmdCheckData
(numbytes=4, ops=1, address=0, mask=0, count=None)¶ Bases:
spsdk.image.commands.CmdBase
Check data command.
Initialize the check data command.
- Parameters
numbytes (
int
) – number of bytesops (
int
) – type of operationaddress (
int
) – list of tuples: address and valuemask (
int
) – mask valuecount (
Optional
[int
]) – count value
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export to binary form (serialization).
- Parameters
dbg_info (
DebugInfo
) – debug information about exported data- Return type
bytes
- Returns
binary representation of the command
-
info
()¶ Text description of the command.
- Return type
str
-
property
num_bytes
¶ Number of bytes.
- Return type
int
-
property
ops
¶ Operation of Check data command.
- Return type
int
-
classmethod
parse
(data, offset=0)¶ Convert binary representation into command (deserialization from binary data).
- Parameters
data (
bytes
) – being parsedoffset (
int
) – current position to readd from data
- Return type
- Returns
parse command
-
class
spsdk.image.commands.
CmdInitialize
(engine=0, data=None)¶ Bases:
spsdk.image.commands.CmdBase
Initialize command.
Initialize the initialize command.
-
append
(value)¶ Appending of Initialize command.
- Return type
None
-
clear
()¶ Clear of Initialize command.
- Return type
None
-
property
engine
¶ Engine.
- Return type
int
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export to binary form (serialization).
- Parameters
dbg_info (
DebugInfo
) – debug information about exported data- Return type
bytes
- Returns
binary representation of the command
-
info
()¶ Text description of the command.
- Return type
str
-
classmethod
parse
(data, offset=0)¶ Convert binary representation into command (deserialization from binary data).
- Parameters
data (
bytes
) – being parsedoffset (
int
) – current position to readd from data
- Return type
- Returns
parse command
-
pop
(index)¶ Pop of Initialize command.
- Return type
int
-
-
class
spsdk.image.commands.
CmdInstallKey
(flags=0, cert_fmt=3, hash_alg=0, src_index=0, tgt_index=0, location=0)¶ Bases:
spsdk.image.commands.CmdBase
Install key command.
Constructor.
- Parameters
flags (
EnumInsKey
) – from EnumInsKeycert_fmt (
EnumCertFormat
) – format of the certificate; key authentication protocolhash_alg (
EnumAlgorithm
) – hash algorithmsrc_index (
int
) – source key (verification key, KEK) indextgt_index (
int
) – target key indexlocation (
int
) – start address of an additional data such as KEY to be installed; Typically it is relative to CSF start; Might be absolute for DEK key
-
property
certificate_format
¶ Certificate format.
- Return type
-
property
certificate_ref
¶ Corresponding certificate referenced by key-location.
- Return type
Union
[CertificateImg
,SrkTable
,None
]
-
property
cmd_data_offset
¶ Offset of an additional data (such as certificate, signature, etc) in binary image.
- Return type
int
-
property
cmd_data_reference
¶ Reference to an additional data (such as certificate, signature, etc).
None if no reference was assigned; Value type is command-specific
- Return type
Union
[CertificateImg
,SrkTable
,None
]
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export to binary form (serialization).
- Parameters
dbg_info (
DebugInfo
) – debug information about exported data- Return type
bytes
- Returns
binary representation of the command
-
property
flags
¶ Flags.
- Return type
-
property
hash_algorithm
¶ Hash algorithm.
- Return type
-
info
()¶ Text description of the command.
- Return type
str
-
property
needs_cmd_data_reference
¶ Whether the command contains a reference to an additional data.
- Return type
bool
-
classmethod
parse
(data, offset=0)¶ Convert binary representation into command (deserialization from binary data).
- Parameters
data (
bytes
) – being parsedoffset (
int
) – current position to read from data
- Return type
- Returns
parse command
-
parse_cmd_data
(data, offset)¶ Parse additional command data from binary data.
- Parameters
data (
bytes
) – to be parsedoffset (
int
) – start position in data to parse
- Return type
Union
[CertificateImg
,SrkTable
,None
]- Returns
parsed data object; command-specific: certificate or SrkTable to be installed
-
property
source_index
¶ Source key (verification key, KEK) index.
For SRK, it is index of the SRK key (0-3)
For other keys it is index of previously installed target key, typically 0
- Return type
int
-
property
target_index
¶ Target key index.
- Return type
int
-
class
spsdk.image.commands.
CmdNop
(param=0)¶ Bases:
spsdk.image.commands.CmdBase
Nop command.
Initialize the nop command.
-
info
()¶ Text description of the command.
- Return type
str
-
-
class
spsdk.image.commands.
CmdSet
(itm=3, hash_alg=0, engine=0, engine_cfg=0)¶ Bases:
spsdk.image.commands.CmdBase
Set command.
Initialize the set command.
-
property
engine
¶ Engine plugin tags.
- Return type
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export to binary form (serialization).
- Parameters
dbg_info (
DebugInfo
) – debug information about exported data- Return type
bytes
- Returns
binary representation of the command
-
property
hash_algorithm
¶ Type of hash algorithm.
- Return type
-
info
()¶ Text description of the command.
- Return type
str
-
property
itm
¶ Item of Set command.
- Return type
int
-
property
-
class
spsdk.image.commands.
CmdUnlock
(engine=0, features=0, uid=0)¶ Bases:
spsdk.image.commands.CmdUnlockAbstract
Generic unlock engine command.
Constructor.
- Parameters
engine (
EnumEngine
) – to be unlockedfeatures (
int
) – mask of features to use by the engineuid (
int
) – Unique ID (if needed)
-
info
()¶ Text description of the command.
- Return type
str
-
class
spsdk.image.commands.
CmdUnlockAbstract
(engine=0, features=0, uid=0)¶ Bases:
spsdk.image.commands.CmdBase
,abc.ABC
Abstract unlock engine command; the command depends on engine type.
Constructor.
- Parameters
engine (
EnumEngine
) – to be unlockedfeatures (
int
) – engine specific featuresuid (
int
) – Unique ID required by some engine/feature combinations
-
property
engine
¶ Engine to be unlocked.
The term engine denotes a peripheral involved in one or more of the following functions: - cryptographic computation - security state management - security alarm handling - access control
- Return type
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export to binary form (serialization).
- Parameters
dbg_info (
DebugInfo
) – debug information about exported data- Return type
bytes
- Returns
binary representation of the command
-
info
()¶ Text description of the command.
- Return type
str
-
static
need_uid
(engine, features)¶ Return True if given Engine and Feature requires UID.
- Return type
bool
-
classmethod
parse
(data, offset=0)¶ Convert binary representation into command (deserialization from binary data).
- Parameters
data (
bytes
) – being parsedoffset (
int
) – current position to readd from data
- Return type
- Returns
Unlock command
-
class
spsdk.image.commands.
CmdUnlockCAAM
(features=0)¶ Bases:
spsdk.image.commands.CmdUnlockAbstract
Command Unlock for Cryptographic Acceleration and Assurance Module .
Initialize.
- Parameters
features (
int
) – mask of FEATURE_UNLOCK_x constants, defaults to 0
-
FEATURE_UNLOCK_MFG
= 4¶
-
FEATURE_UNLOCK_MID
= 1¶
-
FEATURE_UNLOCK_RNG
= 2¶
-
info
()¶ Text description of the command.
- Return type
str
-
property
unlock_mfg
¶ Leave Zero is able Master Key write unlocked.
- Return type
bool
-
property
unlock_mid
¶ Leave Job Ring and DECO master ID registers unlocked.
- Return type
bool
-
property
unlock_rng
¶ Leave RNG un-instantiated.
- Return type
bool
-
class
spsdk.image.commands.
CmdUnlockOCOTP
(features=0, uid=0)¶ Bases:
spsdk.image.commands.CmdUnlockAbstract
Command Unlock for On-Chip One-time programable memory (fuses).
Initialize.
- Parameters
features (
int
) – mask of FEATURE_UNLOCK_x constants, defaults to 0uid (
int
) – Unique ID required by some engine/feature combinations
-
FEATURE_UNLOCK_FLD_RTN
= 1¶
-
FEATURE_UNLOCK_JTAG
= 8¶
-
FEATURE_UNLOCK_SCS
= 4¶
-
FEATURE_UNLOCK_SRK_RVK
= 2¶
-
info
()¶ Text description of the command.
- Return type
str
-
property
unlock_csc
¶ Leave SCS register unlocked.
- Return type
bool
-
property
unlock_fld_rtn
¶ Leave Field Return activation unlocked.
- Return type
bool
-
property
unlock_jtag
¶ Unlock JTAG using SCS HAB_JDE bit.
- Return type
bool
-
property
unlock_srk_rvk
¶ Leave SRK revocation unlocked.
- Return type
bool
-
class
spsdk.image.commands.
CmdUnlockSNVS
(features=0)¶ Bases:
spsdk.image.commands.CmdUnlockAbstract
Command Unlock Secure Non-Volatile Storage (SNVS) Engine.
Constructor.
- Parameters
features (
int
) – mask of FEATURE_UNLOCK_* constants
-
FEATURE_UNLOCK_LP_SWR
= 1¶
-
FEATURE_UNLOCK_ZMK_WRITE
= 2¶
-
info
()¶ Text description of the command.
- Return type
str
-
property
unlock_lp_swr
¶ Leave LP SW reset unlocked.
- Return type
bool
-
property
unlock_zmk_write
¶ Leave Zero is able Master Key write unlocked.
- Return type
bool
-
class
spsdk.image.commands.
CmdWriteData
(numbytes=4, ops=0, data=None)¶ Bases:
spsdk.image.commands.CmdBase
Write data command.
Initialize Write Data command.
- Parameters
numbytes (
int
) – number of bytes. Must be value: 1, 2 or 4ops (
int
) – type of write operationdata (
Optional
[Iterable
[Tuple
[int
,int
]]]) – list of tuples: address and value
-
append
(address, value)¶ Append of Write data command.
- Return type
None
-
clear
()¶ Clear of Write data command.
- Return type
None
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export to binary form (serialization).
- Parameters
dbg_info (
DebugInfo
) – debug information about exported data- Return type
bytes
- Returns
binary representation of the command
-
info
()¶ Text description of the command.
- Return type
str
-
property
num_bytes
¶ Number of bytes being written by the command.
- Return type
int
-
property
ops
¶ Type of write operation.
- Return type
int
-
classmethod
parse
(data, offset=0)¶ Convert binary representation into command (deserialization from binary data).
- Parameters
data (
bytes
) – being parsedoffset (
int
) – current position to readd from data
- Return type
- Returns
parse command
-
pop
(index)¶ Pop of Write data command.
- Return type
List
[int
]
-
class
spsdk.image.commands.
EnumAuthDat
¶ Bases:
spsdk.utils.easy_enum.Enum
Flags for Authenticate Data commands.
-
ABS
= 1¶
-
CLR
= 0¶
-
-
class
spsdk.image.commands.
EnumCAAM
¶ Bases:
spsdk.utils.easy_enum.Enum
CAAM Engine Configuration.
-
DEFAULT
= 0¶
-
DSC_SWAP16
= 128¶
-
DSC_SWAP8
= 64¶
-
IN_SWAP16
= 2¶
-
IN_SWAP8
= 1¶
-
OUT_SWAP16
= 16¶
-
OUT_SWAP8
= 8¶
-
-
class
spsdk.image.commands.
EnumCertFormat
¶ Bases:
spsdk.utils.easy_enum.Enum
Certificate format tags.
-
AEAD
= 163¶
-
BLOB
= 187¶
-
CMS
= 197¶
-
SRK
= 3¶
-
X509
= 9¶
-
-
class
spsdk.image.commands.
EnumCheckOps
¶ Bases:
spsdk.utils.easy_enum.Enum
Enum definition for ‘par’ parameter of Check Data command.
-
ALL_CLEAR
= 0¶
-
ALL_SET
= 1¶
-
ANY_CLEAR
= 2¶
-
ANY_SET
= 3¶
-
-
class
spsdk.image.commands.
EnumEngine
¶ Bases:
spsdk.utils.easy_enum.Enum
Engine plugin tags.
-
ANY
= 0¶
-
CAAM
= 29¶
-
CSU
= 10¶
-
DCP
= 27¶
-
DTCP
= 34¶
-
HDCP
= 36¶
-
OCOTP
= 33¶
-
ROM
= 54¶
-
RTIC
= 5¶
-
SAHARA
= 6¶
-
SCC
= 3¶
-
SNVS
= 30¶
-
SRTC
= 12¶
-
SW
= 255¶
-
-
class
spsdk.image.commands.
EnumInsKey
¶ Bases:
spsdk.utils.easy_enum.Enum
Flags for Install Key commands.
-
ABS
= 1¶
-
CFG
= 8¶
-
CID
= 64¶
-
CLR
= 0¶
-
CSF
= 2¶
-
DAT
= 4¶
-
FID
= 16¶
-
HSH
= 128¶
-
MID
= 32¶
-
-
class
spsdk.image.commands.
EnumItm
¶ Bases:
spsdk.utils.easy_enum.Enum
Engine configuration flags of Set command.
-
ENG
= 3¶
-
MID
= 1¶
-
-
class
spsdk.image.commands.
EnumWriteOps
¶ Bases:
spsdk.utils.easy_enum.Enum
Enum definition for ‘flags’ control flags in ‘par’ parameter of Write Data command.
-
CLEAR_BITMASK
= 2¶
-
SET_BITMASK
= 3¶
-
WRITE_CLEAR_BITS
= 1¶
-
WRITE_VALUE
= 0¶
-
-
exception
spsdk.image.commands.
ExpectedSignatureOrMACError
(desc=None)¶ Bases:
spsdk.exceptions.SPSDKError
CmdAuthData additional data block: expected Signature or MAC object.
Initialize the base SPSDK Exception.
Image Headers¶
Header.
-
class
spsdk.image.header.
CmdHeader
(tag, param=0, length=None)¶ Bases:
spsdk.image.header.Header
Command header.
Constructor.
- Parameters
tag (
CmdTag
) – command tagparam (
int
) – TODOlength (
Optional
[int
]) – of the command binary section, in bytes
-
classmethod
parse
(data, offset=0, required_tag=None)¶ Create Header from binary data.
- Parameters
data (
bytes
) – binary data to convert into headeroffset (
int
) – to start reading binary datarequired_tag (
Optional
[int
]) – CmdTag, None if not required
- Return type
- Returns
parsed instance
- Raises
UnparsedException – if required header tag does not match
-
class
spsdk.image.header.
CmdTag
¶ Bases:
spsdk.utils.easy_enum.Enum
CSF/DCD Command Tag.
-
AUT_DAT
= 202¶
-
CHK_DAT
= 207¶
-
INIT
= 180¶
-
INS_KEY
= 190¶
-
NOP
= 192¶
-
SET
= 177¶
-
UNLK
= 178¶
-
WRT_DAT
= 204¶
-
-
exception
spsdk.image.header.
CorruptedException
¶ Bases:
Exception
Corrupted Exception.
-
class
spsdk.image.header.
Header
(tag=0, param=0, length=None)¶ Bases:
object
Header element type.
Constructor.
- Parameters
tag (
int
) – section tagparam (
int
) – TODOlength (
Optional
[int
]) – length of the segment or command; if not specified, size of the header is used
-
FORMAT
= '>BHB'¶
-
SIZE
= 4¶
-
export
()¶ Binary representation of the header.
- Return type
bytes
-
info
()¶ Text representation of the header.
- Return type
str
-
classmethod
parse
(data, offset=0, required_tag=None)¶ Parse header.
- Parameters
data (
bytes
) – Raw data as bytes or bytearrayoffset (
int
) – Offset of input datarequired_tag (
Optional
[int
]) – Check header TAG if specified value or ignore if is None
- Return type
- Returns
Header object
- Raises
UnparsedException – if required header tag does not match
-
property
size
¶ Header size in bytes.
- Return type
int
-
property
tag
¶ - Return type
int
- Returns
section tag: command tag or segment tag, …
-
class
spsdk.image.header.
Header2
(tag=0, param=0, length=None)¶ Bases:
spsdk.image.header.Header
Header element type.
Constructor.
- Parameters
tag (
int
) – section tagparam (
int
) – TODOlength (
Optional
[int
]) – length of the segment or command; if not specified, size of the header is used
-
FORMAT
= '<BHB'¶
-
export
()¶ Binary representation of the header.
- Return type
bytes
-
length
: int¶
-
param
: int¶
-
classmethod
parse
(data, offset=0, required_tag=None)¶ Parse header.
- Parameters
data (
bytes
) – Raw data as bytes or bytearrayoffset (
int
) – Offset of input datarequired_tag (
Optional
[int
]) – Check header TAG if specified value or ignore if is None
- Raises
UnparsedException – Raises an error if required tag is empty or not valid
- Return type
- Returns
Header2 object
-
class
spsdk.image.header.
SegTag
¶ Bases:
spsdk.utils.easy_enum.Enum
Segments Tag.
-
BIC1
= 135¶
-
CRT
= 215¶
-
CSF
= 212¶
-
DCD
= 210¶
-
EVT
= 219¶
-
IVT2
= 209¶
-
IVT3
= 222¶
-
MAC
= 172¶
-
RVT
= 221¶
-
SIG
= 216¶
-
SIGB
= 144¶
-
WRP
= 129¶
-
-
exception
spsdk.image.header.
UnparsedException
¶ Bases:
Exception
Unparsed Exception.
Secret Module¶
Commands and responses used by SDP module.
-
class
spsdk.image.secret.
BaseClass
(tag, version=64)¶ Bases:
object
Base SPSDK class.
Constructor.
- Parameters
tag (
SegTag
) – section TAGversion (
int
) – format version
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Serialization to binary form.
- Parameters
dbg_info (
DebugInfo
) – optional instance allowing to debug exported data; provides commented export- Return type
bytes
- Returns
binary representation of the instance
-
info
()¶ Description about the instance.
- Return type
str
-
property
size
¶ Size of the exported binary data.
- Return type
int
-
property
version
¶ Format version.
- Return type
int
-
property
version_major
¶ Major format version.
- Return type
int
-
property
version_minor
¶ Minor format version.
- Return type
int
-
class
spsdk.image.secret.
CertificateImg
(version=64, data=None)¶ Bases:
spsdk.image.secret.BaseClass
Certificate structure for bootable image.
Initialize the certificate structure for bootable image.
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export.
- Return type
bytes
-
info
()¶ String representation of the CertificateImg.
- Return type
str
-
classmethod
parse
(data, offset=0)¶ Parse.
- Return type
-
property
size
¶ Size of Certificate structure for bootable image.
- Return type
int
-
-
class
spsdk.image.secret.
EnumAlgorithm
¶ Bases:
spsdk.utils.easy_enum.Enum
Algorithm types.
-
AES
= 85¶
-
ANY
= 0¶
-
BLOB
= 113¶
-
CCM
= 102¶
-
CIPHER
= 5¶
-
EC
= 4¶
-
F
= 3¶
-
HASH
= 1¶
-
MODE
= 6¶
-
PKCS1
= 33¶
-
SHA1
= 17¶
-
SHA256
= 23¶
-
SHA512
= 27¶
-
SIG
= 2¶
-
WRAP
= 7¶
-
-
class
spsdk.image.secret.
EnumSRK
¶ Bases:
spsdk.utils.easy_enum.Enum
Entry type in the System Root Key Table.
-
KEY_HASH
= 238¶
-
KEY_PUBLIC
= 225¶
-
-
class
spsdk.image.secret.
MAC
(version=64, nonce_len=0, mac_len=16, data=None)¶ Bases:
spsdk.image.secret.BaseClass
Structure that holds initial parameter for AES encryption/description.
nonce - initialization vector for AEAD AES128 decryption
mac - message authentication code to verify the decryption was successful
Constructor.
- Parameters
version (
int
) – format version, should be 0x4xnonce_len (
int
) – number of NONCE bytesmac_len (
int
) – number of MAC bytesdata (
Optional
[bytes
]) – nonce and mac bytes joined together
-
AES128_BLK_LEN
= 16¶
-
property
data
¶ NONCE and MAC bytes joined together.
- Return type
bytes
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export instance into binary form (serialization).
- Parameters
dbg_info (
DebugInfo
) – optional instance providing debug info about exported content- Return type
bytes
- Returns
binary form
-
info
()¶ Text info about the instance.
- Return type
str
-
property
mac
¶ MAC bytes for the encryption/decryption.
- Return type
bytes
-
property
nonce
¶ NONCE bytes for the encryption/decryption.
- Return type
bytes
-
classmethod
parse
(data, offset=0)¶ Parse binary data and creates the instance (deserialization).
- Parameters
data (
bytes
) – being parsedoffset (
int
) – to start parse the data
- Return type
- Returns
the instance
-
property
size
¶ Size of binary representation in bytes.
- Return type
int
-
update_aead_encryption_params
(nonce, mac)¶ Update AEAD encryption parameters for encrypted image.
- Parameters
nonce (
bytes
) – initialization vector, length depends on image size,mac (
bytes
) – message authentication code used to authenticate uncrypted data, 16 bytes
- Return type
None
-
exception
spsdk.image.secret.
NotImplementedSRKCertificate
(desc=None)¶ Bases:
spsdk.image.secret.SRKException
This SRK public key algorithm is not yet implemented.
Initialize the base SPSDK Exception.
-
exception
spsdk.image.secret.
NotImplementedSRKItem
(desc=None)¶ Bases:
spsdk.image.secret.SRKException
This type of SRK table item is not implemented.
Initialize the base SPSDK Exception.
-
exception
spsdk.image.secret.
NotImplementedSRKPublicKeyType
(desc=None)¶ Bases:
spsdk.image.secret.SRKException
This SRK public key algorithm is not yet implemented.
Initialize the base SPSDK Exception.
-
exception
spsdk.image.secret.
SRKException
(desc=None)¶ Bases:
spsdk.exceptions.SPSDKError
SRK table processing exceptions.
Initialize the base SPSDK Exception.
-
class
spsdk.image.secret.
SecretKeyBlob
(mode, algorithm, flag)¶ Bases:
object
Secret Key Blob.
Initialize Secret Key Blob.
-
property
blob
¶ Data of Secret Key Blob.
- Return type
bytes
-
export
()¶ Export of Secret Key Blob.
- Return type
bytes
-
info
()¶ String representation of the Secret Key Blob.
- Return type
str
-
classmethod
parse
(data, offset=0)¶ Parse of Secret Key Blob.
- Return type
-
property
size
¶ Size of Secret Key Blob.
- Return type
int
-
property
-
class
spsdk.image.secret.
Signature
(version=64, data=None)¶ Bases:
spsdk.image.secret.BaseClass
Class representing a signature.
Initialize the signature.
-
property
data
¶ Signature data.
- Return type
bytes
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export.
- Return type
bytes
-
info
()¶ String representation of the signature.
- Return type
str
-
property
size
¶ Size of a signature.
- Return type
int
-
property
-
class
spsdk.image.secret.
SrkItem
¶ Bases:
object
Base class for items in the SRK Table, see SrkTable class.
We do not inherit from BaseClass because our header parameter is an algorithm identifier, not a version number.
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Serialization to binary form.
- Parameters
dbg_info (
DebugInfo
) – optional instance allowing to debug exported data; provides commented export- Return type
bytes
- Returns
binary representation of the instance
-
classmethod
from_certificate
(cert)¶ Pick up the right implementation of an SRK item.
- Return type
-
hashed_entry
()¶ This SRK item should be replaced with an incomplete entry with its digest.
- Return type
-
info
()¶ Description about the instance.
- Return type
str
-
classmethod
parse
(data, offset=0)¶ Pick up the right implementation of an SRK item.
- Parameters
data (
bytes
) – The bytes array of SRK segmentoffset (
int
) – The offset of input data
- Return type
- Returns
SrkItem: One of the SrkItem subclasses
- Raises
NotImplementedSRKPublicKeyType – Unsupported key algorithm
NotImplementedSRKItem – Unsupported tag
-
sha256
()¶ Export SHA256 hash of the original data.
- Return type
bytes
-
property
size
¶ Size of the exported binary data.
- Return type
int
-
-
class
spsdk.image.secret.
SrkItemHash
(algorithm, digest)¶ Bases:
spsdk.image.secret.SrkItem
Hashed stub of some public key.
This is a valid entry of the SRK table, it represents some public key of unknown algorithm. Can only provide its hashed value of itself.
Build the stub entry with public key hash only.
- Parameters
algorithm (
int
) – int: Hash algorithm, only SHA256 nowdigest (
bytes
) – bytes: Hash digest value
-
property
algorithm
¶ Hashing algorithm used.
- Return type
int
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export.
- Return type
bytes
-
hashed_entry
()¶ This SRK item should be replaced with an incomplete entry with its digest.
- Return type
-
info
()¶ String representation of SrkItemHash.
- Return type
str
-
classmethod
parse
(data, offset=0)¶ Parse SRK table item data.
- Parameters
data (
bytes
) – The bytes array of SRK segmentoffset (
int
) – The offset of input data
- Return type
- Returns
SrkItemHash: SrkItemHash object
- Raises
NotImplementedSRKItem – Unknown tag
-
sha256
()¶ Export SHA256 hash of the original data.
- Return type
bytes
-
property
size
¶ Size of an SRK item.
- Return type
int
-
class
spsdk.image.secret.
SrkItemRSA
(modulus, exponent, flag=0)¶ Bases:
spsdk.image.secret.SrkItem
RSA public key in SRK Table, see SrkTable class.
Initialize the srk table item.
-
property
algorithm
¶ Algorithm.
- Return type
int
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export.
- Return type
bytes
-
property
flag
¶ Flag.
- Return type
int
-
classmethod
from_certificate
(cert)¶ Create SRKItemRSA from certificate.
- Return type
-
hashed_entry
()¶ This SRK item should be replaced with an incomplete entry with its digest.
- Return type
-
info
()¶ String representation of SrkItemRSA.
- Return type
str
-
property
key_length
¶ Key length of Item in SRK Table.
- Return type
int
-
classmethod
parse
(data, offset=0)¶ Parse SRK table item data.
- Parameters
data (
bytes
) – The bytes array of SRK segmentoffset (
int
) – The offset of input data
- Return type
- Returns
SrkItemRSA: SrkItemRSA object
-
sha256
()¶ Export SHA256 hash of the data.
- Return type
bytes
-
property
size
¶ Size of an SRK item.
- Return type
int
-
property
-
class
spsdk.image.secret.
SrkTable
(version=64)¶ Bases:
spsdk.image.secret.BaseClass
SRK table.
Initialize SRT Table.
- Parameters
version (
int
) – format version
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export into binary form (serialization).
- Parameters
dbg_info (
DebugInfo
) – optional instance allowing to debug exported content- Return type
bytes
- Returns
binary representation of the instance
-
export_fuses
()¶ SRK items in binary form, see SRK_fuses.bin file.
- Return type
bytes
-
get_fuse
(index)¶ Retrieve fuse value for the given index.
- Parameters
index (
int
) – of the fuse, 0-7- Return type
int
- Returns
value of the specified fuse; the value is in format, that cane be used as parameter for SDP efuse_read_once or efuse_write_once
-
info
()¶ Text info about the instance.
- Return type
str
-
property
size
¶ Size of SRK table.
- Return type
int
Data Segments¶
Segments within image module.
-
class
spsdk.image.segments.
AbstractFCB
¶ Bases:
spsdk.image.segments.BaseSegment
Abstract class, predecessor for all FCB classes.
Constructor.
-
TAG
= b'FCB'¶
-
property
enabled
¶ Whether FCB is enabled. Note: it is not generated to output is disabled.
- Return type
bool
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export to binary representation (serialization).
- Parameters
dbg_info (
DebugInfo
) – instance allowing to debug output- Return type
bytes
- Returns
binary representation
-
property
space
¶ Return length (in bytes) of the exported data including padding (if any).
- Return type
int
-
-
class
spsdk.image.segments.
BaseSegment
¶ Bases:
abc.ABC
Base segment.
Initialize the base segment.
-
PADDING_VALUE
= 0¶
-
export
()¶ Export interface.
- Return type
bytes
-
info
()¶ String representation of the BaseSegment.
- Return type
str
-
property
padding_len
¶ Length of padding data in bytes (zero for no padding).
- Return type
int
-
classmethod
parse
(buffer)¶ Parse interfaces.
- Return type
-
property
size
¶ Size of base segment.
- Return type
int
-
property
space
¶ Return length (in bytes) of the exported data including padding (if any).
Please mind, padding is exported optionally.
- Return type
int
-
-
class
spsdk.image.segments.
FlexSPIConfBlockFCB
¶ Bases:
spsdk.image.segments.AbstractFCB
Flex SPI configuration block; FCB.
Initialize FlexSPIConfBlockFCB.
-
FORMAT
= '<6BH7I5I4B2I4I6I4H'¶
-
TAG
= b'FCFB'¶
-
VERSION
= b'V\x01\x00\x00'¶
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export into binary form.
- Parameters
dbg_info (
DebugInfo
) – instance allowing to debug output- Return type
bytes
- Returns
binary representation used in the bootable image
-
export_header
()¶ Export FCB header info binary form.
- Return type
bytes
-
info
()¶ String representation of the FlexSPIConfBlockFCB.
- Return type
str
-
classmethod
parse
(buffer)¶ Parse binary data and creates instance of the class.
- Parameters
buffer (
bytes
) – data to be parsed- Return type
- Returns
instance of the class representing the data
- Raises
ValueError – if data are not valid Flex SPI configuration block
-
property
size
¶ Length of the binary exported data without padding.
- Return type
int
-
-
class
spsdk.image.segments.
PaddingFCB
(size, padding_value=0, enabled=True)¶ Bases:
spsdk.image.segments.AbstractFCB
Padding FCB.
Constructor.
- Parameters
size (
int
) – of the exported paddingpadding_value (
int
) – byte value used as padding; 0 by defaultenabled (
bool
) – whether enabled
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export to binary form (serialization).
- Parameters
dbg_info (
DebugInfo
) – instance allowing to debug output format- Return type
bytes
- Returns
binary representation
-
info
()¶ Return text description of the instance.
- Return type
str
-
property
size
¶ Return size of the exported data in bytes.
- Return type
int
-
class
spsdk.image.segments.
SegAPP
(data=None)¶ Bases:
spsdk.image.segments.BaseSegment
APP segment.
Initialize APP segment.
- Parameters
data (
Optional
[bytes
]) – application binary data
-
property
data
¶ Application binary data.
- Return type
Optional
[bytes
]
-
export
()¶ Export segment as bytes array.
- Return type
bytes
- Returns
bytes
-
info
()¶ String representation of the SegAPP.
- Return type
str
-
property
size
¶ Size of APP segment.
- Return type
int
-
class
spsdk.image.segments.
SegBDS3a
¶ Bases:
spsdk.image.segments.BaseSegment
BDS3a segment.
Initialize BDS3a segment.
-
FORMAT
= '<4L'¶
-
HEADER_SIZE
= 16¶
-
IMAGES_MAX_COUNT
= 6¶
-
SIZE
= 256¶
-
export
()¶ Export segment as bytes array.
- Return type
bytes
- Returns
bytes
-
property
header_size
¶ Header’s size of BDS3a segment.
- Return type
int
-
info
()¶ String representation of the SegBDS3a.
- Return type
str
-
classmethod
parse
(data)¶ Parse segment from bytes array.
- Parameters
data (
bytes
) – The bytes array of BDS3a segment- Return type
- Returns
SegBDS3a object
-
property
size
¶ Size of BDS3a segment.
- Return type
int
-
-
class
spsdk.image.segments.
SegBDS3b
¶ Bases:
spsdk.image.segments.BaseSegment
BDS3b segment.
Initialize BDS3b segment.
-
FORMAT
= '<4L'¶
-
HEADER_SIZE
= 16¶
-
IMAGES_MAX_COUNT
= 4¶
-
SIZE
= 240¶
-
export
()¶ Export segment as bytes array.
- Return type
bytes
- Returns
bytes
-
property
header_size
¶ Size of header of BDS3b segment.
- Return type
int
-
info
()¶ String representation of the SegBDS3b.
- Return type
str
-
classmethod
parse
(data)¶ Parse segment from bytes array.
- Parameters
data (
bytes
) – The bytes array of BDS3b segment- Return type
- Returns
SegBDS3b object
-
property
size
¶ Size of BDS3b segment.
- Return type
int
-
-
class
spsdk.image.segments.
SegBDT
(app_start=0, app_length=0, plugin=0)¶ Bases:
spsdk.image.segments.BaseSegment
Boot Data Table segment.
Initialize BDT segment.
- Parameters
app_start (
int
) – first address of the applicationapp_length (
int
) – length of the applicationplugin (
int
) – 0 .. 2
-
FORMAT
= '<3L'¶
-
SIZE
= 12¶
-
export
()¶ Export segment as bytes array.
- Return type
bytes
- Returns
bytes
-
info
()¶ String representation of the SegBDT.
- Return type
str
-
classmethod
parse
(data)¶ Parse segment from bytes array.
- Parameters
data (
bytes
) – The bytes array of BDT segment- Return type
- Returns
SegBDT object
-
property
plugin
¶ Plugin.
- Return type
int
-
property
size
¶ Size of the exported binary data (without padding).
- Return type
int
-
class
spsdk.image.segments.
SegBEE
(regions, max_facs=3)¶ Bases:
spsdk.image.segments.BaseSegment
BEE keys and regions segment.
Constructor.
- Parameters
regions (
Sequence
[BeeRegionHeader
]) – list of regionsmax_facs (
int
) – maximum total number of FAC in all regions, used for validation
-
add_region
(region)¶ Add region.
- Parameters
region (
BeeRegionHeader
) – to be added- Return type
None
-
encrypt_data
(start_addr, data)¶ Encrypt image data located in any PRDB block.
- Parameters
start_addr (
int
) – start address of the data; must be aligned to block sizedata (
bytes
) – to be encrypted
- Return type
bytes
- Returns
encrypted data, aligned to block size; blocks outside any FAC region kept untouched
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Serialization to binary representation.
- Parameters
dbg_info (
DebugInfo
) – instance allowing to provide debug info about exported data- Return type
bytes
- Returns
binary representation of the region (serialization).
-
info
()¶ - Return type
str
- Returns
test description of the instance.
-
classmethod
parse
(data, offset=0, decrypt_keys=[])¶ Deserialization.
- Parameters
data (
bytes
) – binary data to be parsedoffset (
int
) – to start parsing the datadecrypt_keys (
List
[bytes
]) – list of SW_GP keys used to decrypt EKIB The number of keys must match number of regions to be parsed
- Return type
- Returns
instance created from binary data
-
property
size
¶ - Return type
int
- Returns
size of the exported binary data in bytes.
-
update
()¶ Updates internal fields of the instance.
- Return type
None
-
validate
()¶ Validates settings of the instance.
- Raises
ValueError – if number of FAC regions exceeds the limit
- Return type
None
-
class
spsdk.image.segments.
SegBIC1
(version=0)¶ Bases:
spsdk.image.segments.BaseSegment
Boot Images Container segment.
Initialize Boot Images Container segment.
- Parameters
version (
int
) – The version of Header for Boot Images Container
-
FORMAT
= '<LH2B2H'¶
-
MAX_NUM_IMGS
= 6¶
-
SIZE
= 808¶
-
export
()¶ Export segment as bytes array.
- Return type
bytes
- Returns
bytes
-
info
()¶ String representation of the SegBIC1.
- Return type
str
-
classmethod
parse
(data)¶ Parse segment from bytes array.
- Parameters
data (
bytes
) – The bytes array of BIC1 segment- Return type
- Returns
SegBIC1 object
-
property
size
¶ Size.
- Return type
int
-
validate
()¶ Validate segment.
- Return type
None
-
property
version
¶ Version of Boot Images Container segment.
- Return type
int
-
class
spsdk.image.segments.
SegBIM
¶ Bases:
spsdk.image.segments.BaseSegment
BootImage segment.
Initialize BootImage segment.
-
FORMAT
= '<2L2Q2L'¶
-
SIZE
= 128¶
-
export
()¶ Export segment as bytes array.
- Return type
bytes
- Returns
bytes
-
info
()¶ String representation of the SegBIM.
- Return type
str
-
classmethod
parse
(data)¶ Parse segment from bytes array.
- Parameters
data (
bytes
) – The bytes array of BootImage segment- Return type
- Returns
SegBootImage object
-
property
size
¶ Size of BootImage segment.
- Return type
int
-
-
class
spsdk.image.segments.
SegCSF
(version=64, enabled=False)¶ Bases:
spsdk.image.segments.BaseSegment
Command Sequence File (CSF), signature block for Secure Boot.
A script of commands used to guide image authentication and device configuration operations.
Initialize CSF segment.
-
append_command
(cmd)¶ Append CSF command to the segment.
- Parameters
cmd (
CmdBase
) – to be added- Return type
None
-
clear_commands
()¶ Removes= all commands.
- Return type
None
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export segment as bytes array (serialization).
- Parameters
dbg_info (
DebugInfo
) – optional list of strings to produce debug information about exported data- Return type
bytes
- Returns
bytes
-
info
()¶ String representation of the SegCSF.
- Return type
str
-
classmethod
parse
(data, offset=0)¶ Parse segment from bytes array.
- Parameters
data (
bytes
) – The bytes array of CSF segmentoffset (
int
) – to start parsing the data
- Raises
CorruptedException – When there is unknown command
CorruptedException – When command can not be parsed
- Return type
- Returns
SegCSF instance
-
property
size
¶ Size of the binary representation of the segment; 0 is not enabled.
- Return type
int
-
property
space
¶ Size of the binary representation of the segment including padding; 0 is not enabled.
- Return type
int
-
update
(reset_cmddata_offsets)¶ Update the offsets for the export.
- Parameters
reset_cmddata_offsets (
bool
) – True to reset all cmd-data offsets, if cmd-data not specified in the command; False to avoid any reset; Note: reset should be done during parsing process as the data are incomplete- Return type
None
-
update_signatures
(zulu, data, base_data_addr)¶ Update signatures in all CmdAuthData commands.
- Parameters
zulu (
datetime
) – current UTC time+datedata (
bytes
) – currently generated binary data; empty to create “fake” signature to update size of the segmentbase_data_addr (
int
) – base address of the generated data
- Return type
None
-
property
version
¶ Version of CSF segment.
- Return type
int
-
-
class
spsdk.image.segments.
SegDCD
(param=65, enabled=False)¶ Bases:
spsdk.image.segments.BaseSegment
Device configuration data (DCD) segment.
IC configuration data, usually is used to configure DDR/SDRAM memory. Typically this is optional
Initialize DCD segment.
-
append
(cmd)¶ Appending of Device configuration data (DCD) segment.
- Return type
None
-
clear
()¶ Clear of Device configuration data (DCD) segment.
- Return type
None
-
export
()¶ Export segment as bytes array.
- Return type
bytes
- Returns
bytes
-
export_txt
(txt_data=None)¶ Export txt of Device configuration data (DCD) segment.
- Return type
str
-
info
()¶ String representation of the SegDCD.
- Return type
str
-
classmethod
parse
(data)¶ Parse segment from bytes array.
- Parameters
data (
bytes
) – The bytes array of DCD segment- Raises
CorruptedException – Exception caused by corrupted data
- Return type
- Returns
SegDCD object
-
classmethod
parse_txt
(text)¶ Parse segment from text file.
- Parameters
text (
str
) – The string with DCD commands- Return type
- Returns
SegDCD object
-
property
size
¶ Size of Device configuration data (DCD) segment.
- Return type
int
-
property
space
¶ Add space.
- Return type
int
-
-
class
spsdk.image.segments.
SegDcdBuilder
¶ Bases:
object
Builder to create SegDCD from text input.
Initialize SegDcdBuilder.
-
class
spsdk.image.segments.
SegFCB
¶ Bases:
spsdk.image.segments.AbstractFCB
,abc.ABC
FCB.
Initialize FCB segment.
-
FINGERPRINT
= b'NFCB'¶
-
SIZE
= 1024¶
-
property
crc
¶ Cyclic redundancy check.
- Return type
int
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Export to binary form.
- Return type
bytes
-
-
class
spsdk.image.segments.
SegIDS3a
¶ Bases:
spsdk.image.segments.BaseSegment
IDS3a segment.
Initialize IDS3a segment.
-
FORMAT
= '<3Q4L'¶
-
SIZE
= 40¶
-
export
()¶ Export segment as bytes array.
- Return type
bytes
- Returns
bytes
-
info
()¶ String representation of the SegIDS3a.
- Return type
str
-
classmethod
parse
(data)¶ Parse segment from bytes array.
- Parameters
data (
bytes
) – The bytes array of IDS3a segment- Return type
- Returns
SegIDS3a object
-
property
size
¶ Size of IDS3a segment.
- Return type
int
-
-
class
spsdk.image.segments.
SegIDS3b
¶ Bases:
spsdk.image.segments.BaseSegment
IDS3b segment.
Initialize IDS3b segment.
-
FORMAT
= '<3Q2L'¶
-
SIZE
= 32¶
-
export
()¶ Export segment as bytes array.
- Return type
bytes
- Returns
bytes
-
info
()¶ String representation of the SegIDS3b.
- Return type
str
-
classmethod
parse
(data)¶ Parse segment from bytes array.
- Parameters
data (
bytes
) – The bytes array of IDS3b segment- Return type
- Returns
SegIDS3b object
-
property
size
¶ Size of IDS3b segment.
- Return type
int
-
-
class
spsdk.image.segments.
SegIVT2
(version)¶ Bases:
spsdk.image.segments.BaseSegment
Image Vector Table, IVT2 segment.
Initialize IVT2 segment.
- Parameters
version (
int
) – The version of IVT and Image format
-
FORMAT
= '<7L'¶
-
SIZE
= 32¶
-
export
()¶ Export to binary representation (serialization).
- Return type
bytes
- Returns
segment exported as binary data
-
info
()¶ String representation of the SegIVT2.
- Return type
str
-
classmethod
parse
(data)¶ Parse segment from bytes array.
- Parameters
data (
bytes
) – The bytes array of IVT2 segment- Return type
- Returns
SegIVT2 object
-
property
size
¶ Size of the binary data.
- Return type
int
-
validate
()¶ Validate settings of the segment.
- Raises
ValueError – if there is configuration problem
- Return type
None
-
property
version
¶ The version of IVT and Image format.
- Return type
int
-
class
spsdk.image.segments.
SegIVT3a
(param)¶ Bases:
spsdk.image.segments.BaseSegment
IVT3a segment.
Initialize IVT segment.
- Parameters
param (
int
) – The version of IVT and Image format
-
FORMAT
= '<1L5Q'¶
-
SIZE
= 48¶
-
export
()¶ Export segment as bytes array.
- Return type
bytes
- Returns
bytes
-
info
()¶ String representation of the SegIVT3a.
- Return type
str
-
classmethod
parse
(data)¶ Parse segment from bytes array.
- Parameters
data (
bytes
) – The bytes array of IVT3a segment- Return type
- Returns
SegIVT3a object
-
property
size
¶ Size of IVT3a segment.
- Return type
int
-
validate
()¶ Validation of IVT3a segment.
- Return type
None
-
class
spsdk.image.segments.
SegIVT3b
(version)¶ Bases:
spsdk.image.segments.BaseSegment
IVT3b segment.
Initialize IVT segment.
- Parameters
version (
int
) – The version of IVT and Image format
-
FORMAT
= '<1L7Q'¶
-
SIZE
= 64¶
-
export
()¶ Export segment as bytes array.
- Return type
bytes
- Returns
bytes
-
info
()¶ String representation of the SegIVT3b.
- Return type
str
-
classmethod
parse
(data)¶ Parse segment from bytes array.
- Parameters
data (
bytes
) – The bytes array of IVT3b segment- Return type
- Returns
SegIVT3b object
-
property
size
¶ Size of IVT3b segment.
:return size
- Return type
int
-
validate
()¶ Validation of IVT3b segment.
- Return type
None
-
class
spsdk.image.segments.
SegSIGB
(version=0)¶ Bases:
spsdk.image.segments.BaseSegment
SignatureBlock segment.
Initialize SignatureBlock segment.
-
FORMAT
= '<4HL'¶
-
SIZE
= 16¶
-
export
()¶ Export segment as bytes array.
- Return type
bytes
- Returns
bytes
-
info
()¶ String representation of the SegSIGB.
- Return type
str
-
classmethod
parse
(data)¶ Parse segment from bytes array.
- Parameters
data (
bytes
) – The bytes array of SignatureBlock segment- Return type
- Returns
SegSigBlk object
-
property
size
¶ Size of Signature Block segment.
- Return type
int
-
property
version
¶ Version of Signature Block segment.
- Return type
int
-
TrustZone¶
Module provides support for TrustZone configuration data.
-
class
spsdk.image.trustzone.
TrustZone
(tz_type=0, family=None, revision=None, customizations=None, raw_data=None)¶ Bases:
object
Provide creation of binary data to set up the TrustZone engine in CM-33.
Initialize the trustzone.
-
classmethod
custom
(family, customizations, revision=None)¶ Alternate constructor for CUSTOM type of TrustZone.
- Return type
-
export
()¶ Return the TrustZone data as bytes.
- Return type
bytes
-
classmethod
from_binary
(family, raw_data, revision=None)¶ Alternate constructor using existing binary data.
- Return type
-
get_families
()¶ Return list of supported chip families.
- Return type
list
-
get_latest_revision
(family=None)¶ Return latest revision for given family.
- Return type
str
-
get_revisions
(family=None)¶ Return a list of revisions for given family.
- Return type
list
-
sanitize_revision
(family, revision)¶ Sanitize revision.
if the ‘revision’ is None return the latest revision if the ‘revision’ is provided return it as lower-case
- Return type
str
-
static
validate_custom_data
(data, customizations)¶ Check whether all register names in custom data are valid (present in presets).
- Return type
bool
-
classmethod
-
class
spsdk.image.trustzone.
TrustZoneType
¶ Bases:
spsdk.utils.easy_enum.Enum
Enum defining various types of TrustZone types.
-
CUSTOM
= 32¶
-
DISABLED
= 64¶
-
ENABLED
= 0¶
-
Support for BEE encryption for RT10xx devices¶
Contains support for BEE encryption for RT10xx devices.
-
class
spsdk.image.bee.
BeeBaseClass
¶ Bases:
object
BEE base class.
-
export
()¶ - Return type
bytes
- Returns
binary representation of the region (serialization).
-
info
()¶ - Return type
str
- Returns
text description of the instance.
-
classmethod
parse
(data, offset=0)¶ Deserialization.
- Parameters
data (
bytes
) – binary data to be parsedoffset (
int
) – to start parsing the data
- Return type
Any
- Returns
instance created from binary data; this method returns just 0
- Raises
ValueError – if size of the data is not sufficient
-
property
size
¶ - Return type
int
- Returns
size of the exported binary data in bytes.
-
update
()¶ Updates internal fields of the instance.
- Return type
None
-
validate
()¶ Validates the configuration of the instance.
It is recommended to call the method before export and after parsing.
- Return type
None
-
-
class
spsdk.image.bee.
BeeFacRegion
(start=0, length=0, protected_level=0)¶ Bases:
spsdk.image.bee.BeeBaseClass
BEE Factory Access Control (FAC) region.
Constructor.
- Parameters
start (
int
) – Start address of one FAC region, align at 1KB boundary; 32-bit numberlength (
int
) – Length of one FAC region, align at 1KB boundary; 32-bit numberprotected_level (
int
) – Protected level: 0/1/2/3; 32-bit number
-
property
end_addr
¶ - Return type
int
- Returns
end address of the region (which is last address of the region + 1).
-
export
()¶ Exports the binary representation.
- Return type
bytes
-
info
()¶ - Return type
str
- Returns
test description of the instance.
-
classmethod
parse
(data, offset=0)¶ Deserialization.
- Parameters
data (
bytes
) – binary data to be parsedoffset (
int
) – to start parsing the data
- Return type
- Returns
instance created from binary data
- Raises
ValueError – if reserved area is non-zero
-
validate
()¶ Validates the configuration of the instance.
- Return type
None
-
class
spsdk.image.bee.
BeeKIB
(kib_key=None, kib_iv=None)¶ Bases:
spsdk.image.bee.BeeBaseClass
BEE Key block.
Contains keys used to encrypt PRDB content.
Constructor.
- Parameters
kib_key (
Optional
[bytes
]) – AES keykib_iv (
Optional
[bytes
]) – AES initialization vector
-
export
()¶ Exports binary representation of the region (serialization).
- Return type
bytes
-
info
()¶ - Return type
str
- Returns
test description of the instance.
-
classmethod
parse
(data, offset=0)¶ Deserialization.
- Parameters
data (
bytes
) – binary data to be parsedoffset (
int
) – to start parsing the data
- Return type
- Returns
instance created from binary data
-
validate
()¶ Validates settings of the instance.
- Raises
AssertionError – if settings invalid
- Return type
None
-
class
spsdk.image.bee.
BeeProtectRegionBlock
(encr_mode=1, lock_options=0, counter=None)¶ Bases:
spsdk.image.bee.BeeBaseClass
BEE protect region block (PRDB).
Constructor.
- Parameters
encr_mode (
BeeProtectRegionBlockAesMode
) – AES encryption modelock_options (
int
) – Lock options; 32-bit numbercounter (
Optional
[bytes
]) – Counter for AES-CTR mode; 16 bytes; by default, random value is used
-
FAC_REGIONS
= 4¶
-
SIZE
= 256¶
-
TAGH
= 1380206661¶
-
TAGL
= 1598505300¶
-
VERSION
= 1442906112¶
-
add_fac
(fac)¶ Append FAC region.
- Parameters
fac (
BeeFacRegion
) – Factory Access Control to be added- Return type
None
-
encrypt_block
(key, start_addr, data)¶ Encrypt block located in any FAC region.
- Parameters
key (
bytes
) – user for encryptionstart_addr (
int
) – start address of the datadata (
bytes
) – binary block to be encrypted; the block size must be BEE_ENCR_BLOCK_SIZE
- Return type
bytes
- Returns
encrypted block if it is inside any FAC region; untouched block if it is not in any FAC region
-
export
()¶ - Return type
bytes
- Returns
binary representation of the region (serialization).
-
property
fac_count
¶ - Return type
int
- Returns
number of Factory Access Control regions.
-
info
()¶ - Return type
str
- Returns
test description of the instance.
-
classmethod
parse
(data, offset=0)¶ Deserialization.
- Parameters
data (
bytes
) – binary data to be parsedoffset (
int
) – to start parsing the data
- Return type
- Returns
instance created from binary data
- Raises
ValueError – if format does not match
-
update
()¶ Updates start and end address of the encryption region.
- Return type
None
-
validate
()¶ Validates settings of the instance.
- Raises
AssertionError – if settings invalid
- Return type
None
-
class
spsdk.image.bee.
BeeProtectRegionBlockAesMode
¶ Bases:
spsdk.utils.easy_enum.Enum
AES mode selection for BEE PRDB encryption.
-
CTR
= 1¶
-
ECB
= 0¶
-
-
class
spsdk.image.bee.
BeeRegionHeader
(prdb=None, sw_key=None, kib=None)¶ Bases:
spsdk.image.bee.BeeBaseClass
BEE keys and regions header.
Constructor.
- Parameters
prdb (
Optional
[BeeProtectRegionBlock
]) – protect region block; None to use defaultsw_key (
Optional
[bytes
]) – key used to encrypt KIB contentkib (
Optional
[BeeKIB
]) – keys block; None to use default
-
PRDB_OFFSET
= 128¶
-
SIZE
= 1024¶
-
add_fac
(fac)¶ Append FAC region.
- Parameters
fac (
BeeFacRegion
) – to be added- Return type
None
-
encrypt_block
(start_addr, data)¶ Encrypt block located in any FAC region.
- Parameters
start_addr (
int
) – start address of the datadata (
bytes
) – binary block to be encrypted; the block size must be BEE_ENCR_BLOCK_SIZE
- Return type
bytes
- Returns
encrypted block if it is inside any FAC region; untouched block if it is not in any FAC region
-
export
(dbg_info=<spsdk.utils.misc.DebugInfo object>)¶ Serialization to binary representation.
- Parameters
dbg_info (
DebugInfo
) – instance allowing to provide debug info about exported data- Return type
bytes
- Returns
binary representation of the region (serialization).
-
property
fac_regions
¶ - Return type
Sequence
[BeeFacRegion
]- Returns
lift of Factory Access Control regions.
-
info
()¶ - Return type
str
- Returns
test description of the instance.
-
classmethod
parse
(data, offset=0, sw_key=b'')¶ Deserialization.
- Parameters
data (
bytes
) – binary data to be parsedoffset (
int
) – to start parsing the datasw_key (
bytes
) – SW key used to decrypt the EKIB data (the key is marked as SW_GP2 on RT10xx)
- Return type
- Returns
instance created from binary data
-
sw_key_fuses
()¶ - Return type
Sequence
[int
]- Returns
sequence of fuse values for SW key to be burned into processor.
The result is ordered, first value should be burned to the lowest address.
-
update
()¶ Updates internal fields of the instance.
- Return type
None
-
validate
()¶ Validates settings of the instance.
- Raises
AssertionError – if settings invalid
- Return type
None
Support for KeyStore used in MasterBootImage¶
Module provides support for KeyStore used in MasterBootImage.
-
class
spsdk.image.keystore.
KeySourceType
¶ Bases:
spsdk.utils.easy_enum.Enum
Device key source.
-
KEYSTORE
= 1¶
-
OTP
= 0¶
-
-
class
spsdk.image.keystore.
KeyStore
(key_source, key_store=None)¶ Bases:
object
Provide info about KeyStore for MaterBootImage.
Initialize Keystore.
- Parameters
key_source (
KeySourceType
) – device key sourcekey_store (
Optional
[bytes
]) – initial content of the key store in the bootable image; None if empty
- Raises
ValueError – if invalid key-store size
-
KEY_STORE_SIZE
= 1424¶
-
static
derive_enc_image_key
(master_key)¶ Derive “enc_image_key” from master key.
- Parameters
master_key (
bytes
) – stored in OTP- Return type
bytes
- Returns
key used to decrypt encrypted images during boot
-
static
derive_hmac_key
(hmac_key)¶ Derive HMAC from master or user key.
- Parameters
hmac_key (
bytes
) – either master-key (for key_source == OTP) or user key (for key_source == KEYSTORE)- Return type
bytes
- Returns
key used for image header authentication in LoadToRam images
-
static
derive_otfad_kek_key
(master_key, otfad_input)¶ Derive OTFAD KEK key from master key and OTFAD input.
- Parameters
master_key (
bytes
) – 32 bytes key, stored in OTPotfad_input (
bytes
) – 16 bytes input, stored in OTP
- Return type
bytes
- Returns
OTFAD encryption key for FLASH encryption/decryption
-
static
derive_sb_kek_key
(master_key)¶ Derive SBKEK key from master key.
- Parameters
master_key (
bytes
) – 32 bytes key, stored in OTP- Return type
bytes
- Returns
encryption key to handle SB2 file (update capsule)
-
export
()¶ Binary key store content; empty bytes for empty key-store.
- Return type
bytes
-
info
()¶ Information about key store in text form.
- Return type
str
-
property
key_source
¶ Device key source.
- Return type
Master Boot Image¶
Master Boot Image.
-
class
spsdk.image.mbimg.
MasterBootImage
(app, load_addr, image_type=0, trust_zone=None, app_table=None, cert_block=None, priv_key_pem_data=None, hmac_key=None, key_store=None, enable_hw_user_mode_keys=False, ctr_init_vector=None)¶ Bases:
object
Basic representation of Master Boot Image layout.
Constructor.
- Parameters
app (
Union
[bytes
,bytearray
]) – input image (binary)load_addr (
int
) – address in RAM, where ‘RAM’ image will be copied; for XIP images address, where the image is located in FLASH memoryimage_type (
MasterBootImageType
) – type of the master boot imagetrust_zone (
Optional
[TrustZone
]) – TrustZone instance; None to use default settings (TrustZone enabled)app_table (
Optional
[MultipleImageTable
]) – optional table with additional images; None if no additional images neededcert_block (
Optional
[CertBlock
]) – block of certificates; None for unsigned imagepriv_key_pem_data (
Optional
[bytes
]) – private key to sign the image, decrypted binary data in PEM formathmac_key (
Union
[bytes
,str
,None
]) – optional key for HMAC generation (either binary ot HEX string; 32 bytes); None if HMAC is not in the image If key_store.key_source == KeySourceType.KEYSTORE, this is a user-key from key-store If key_store.key_source == KeySourceType.OTP, this is a master-key burned in OTPkey_store (
Optional
[KeyStore
]) – optional key store binary content; None if key store is not in the imageenable_hw_user_mode_keys (
bool
) – flag for controlling secure hardware key bus. If true, then it is possible to access keys on hardware secure bus from non-secure application, else non-secure application will read zeros.ctr_init_vector (
Optional
[bytes
]) – optional initial vector for encryption counter; None to use random vector
- Raises
TypeError – if type is not binary data
ValueError – if images are not loaded from RAM
-
CERTIFICATE_OFFSET
= 40¶
-
CRC_BLOCK_OFFSET
= 40¶
-
HMAC_OFFSET
= 64¶
-
HMAC_SIZE
= 32¶
-
IMAGE_FLAGS_OFFSET
= 36¶
-
IMAGE_LENGTH_OFFSET
= 32¶
-
LOAD_ADDR_OFFSET
= 52¶
-
property
app_len
¶ Length of binary app data; this includes also size of the relocation table.
- Return type
int
-
property
data
¶ Plain, unsigned binary data for the image.
It consists of: - application image - optionally trust zone data Please mind the result does not contain: certification block, HMAC, keystore and signature
- Return type
bytes
-
export
()¶ Master boot image (binary).
- Return type
bytes
-
info
()¶ Text description of the instance.
- Return type
str
-
classmethod
parse
(data, offset=0, **kwargs)¶ Parse.
- Return type
None
-
property
total_len
¶ Total length of the image.
It is sum of: - image length + length of trust zone data - HMAC length - KeyStore length - certificate length (+ for encrypted images also encrypted header and CRT init vector) - signature length
- Return type
int
-
class
spsdk.image.mbimg.
MasterBootImageManifest
(firmware_version, trust_zone, sign_hash_len=None)¶ Bases:
object
MasterBootImage Manifest used in LPC55s3x.
Initialize MBI Manifest object.
- Parameters
firmware_version (
int
) – firmware versionsign_hash_len (
Optional
[int
]) – length of hash used for singing, defaults to Nonetrust_zone (
TrustZone
) – TrustZone instance, defaults to None
-
DIGEST_PRESENT_FLAG
= 2147483648¶
-
FORMAT
= '<4s4L'¶
-
FORMAT_VERSION
= 65536¶
-
MAGIC
= b'imgm'¶
-
export
()¶ Serialize MBI Manifest.
- Return type
bytes
-
class
spsdk.image.mbimg.
MasterBootImageN4Analog
(app, load_addr, dual_boot_version=None, firmware_version=1, sign_hash_len=0, signature_provider=None, **kwargs)¶ Bases:
spsdk.image.mbimg.MasterBootImage
Master Boot Image layout specific for LPC55s3x.
Initialize MBI for LPC55s3x.
- Parameters
app (
bytes
) – application binaryload_addr (
int
) – Addres where to load applicationdual_boot_version (
Optional
[int
]) – Version of dualboot application, defaults to Nonefirmware_version (
int
) – Firmware version, defaults to Nonesign_hash_len (
int
) – Length of hash used for singing, defaults to 0signature_provider (
Optional
[SignatureProvider
]) – Signature provider meant to sign the imagekwargs (
Any
) – keyword arguments passed to MasterBootImage
-
property
data
¶ Plain, unsigned binary data for the image.
It consists of: - application image - image manifest for signed image types - optionally trust zone data Please mind the result does not contain: certification block, HMAC, keystore and signature
- Return type
bytes
-
export
()¶ Master boot image (binary).
- Return type
bytes
-
property
total_len
¶ Return the total (expected) length of the image.
- Return type
int
-
class
spsdk.image.mbimg.
MasterBootImageType
¶ Bases:
spsdk.utils.easy_enum.Enum
Enumeration of various types of MBIs.
-
CRC_RAM_IMAGE
= 2¶
-
CRC_XIP_IMAGE
= 5¶
-
ENCRYPTED_RAM_IMAGE
= 3¶
-
PLAIN_IMAGE
= 0¶
-
SIGNED_RAM_IMAGE
= 1¶
-
SIGNED_XIP_IMAGE
= 4¶
-
SIGNED_XIP_NXP_IMAGE
= 8¶
-
static
has_crc
(image_type)¶ True is the image type contains CRC; False otherwise.
- Return type
bool
-
static
has_hmac
(image_type)¶ Whether the image contains HMAC.
- Return type
bool
-
static
is_copied_to_ram
(image_type)¶ True is the image type is copied and executed in RAM.
- Return type
bool
-
static
is_encrypted
(image_type)¶ True is the image type is encrypted; False otherwise.
- Return type
bool
-
static
is_signed
(image_type)¶ True is the image type is signed; False otherwise.
- Return type
bool
-
static
is_xip
(image_type)¶ True is the image type is executed in place (XIP).
- Return type
bool
-
-
class
spsdk.image.mbimg.
MultipleImageEntry
(img, dst_addr, flags=1)¶ Bases:
object
The class represents an entry in relocation table.
It also contains a corresponding image (binary)
Constructor.
- Parameters
img (
bytes
) – binary image datadst_addr (
int
) – destination addressflags (
int
) – see LTI constants
-
LTI_LOAD
= 1¶
-
property
dst_addr
¶ Destination address.
- Return type
int
-
export_entry
()¶ Export relocation table entry in binary form.
- Return type
bytes
-
export_image
()¶ Binary image aligned to the 4-bytes boundary.
- Return type
bytes
-
property
flags
¶ Flags, currently not used.
- Return type
int
-
property
image
¶ Binary image data.
- Return type
bytes
-
property
is_load
¶ True if entry represents LOAD section.
- Return type
bool
-
property
size
¶ Size of the image (not aligned).
- Return type
int
-
property
src_addr
¶ Source address; this value is calculated automatically when building the image.
- Return type
int
-
class
spsdk.image.mbimg.
MultipleImageTable
¶ Bases:
object
The class allows to merge several images into single image and add relocation table.
It can be used for multicore images (one image for each core) or trustzone images (merging secure and non-secure image)
Initialize the Multiple Image Table.
-
add_entry
(entry)¶ Add entry into relocation table.
- Parameters
entry (
MultipleImageEntry
) – to add- Return type
None
-
property
entries
¶ List of all entries.
- Return type
Sequence
[MultipleImageEntry
]
-
export
(start_addr)¶ Export.
- Parameters
start_addr (
int
) – start address where the images are exported; the value matches source address for the first image- Return type
bytes
- Returns
images with relocation table
-
property
header_version
¶ Format version of the structure for the header.
- Return type
int
-
reloc_table
(start_addr)¶ Relocate table.
- Parameters
start_addr (
int
) – start address of the relocation table- Return type
bytes
- Returns
export relocation table in binary form
-