Debug Authentication API

Contents

Debug Authentication API#

SPSDK Debug Authentication Tool support module.

This module provides functionality for debug authentication operations, enabling secure debug access control for NXP MCU devices through certificate-based authentication mechanisms.

Module for generating debug credentials#

SPSDK Debug Authentication Tool (DAT) debug credential management.

This module provides functionality for creating, parsing, and managing debug credentials used in NXP’s Debug Authentication Tool. It supports various certificate types including RSA and ECC-based credentials, as well as EdgeLock Enclave specific implementations for secure debug access control.

class spsdk.dat.debug_credential.DebugCredentialCertificate(family, version, uuid, rot_meta, dck_pub, cc_socu, cc_vu, cc_beacon, rot_pub, signature=None, signature_provider=None)#

Bases: FeatureBaseClass

Debug Credential Certificate for secure device authentication.

This class manages debug credential certificates used for secure authentication and authorization of debug access to NXP MCU devices. It handles the creation, validation, and export of debug credentials including public keys, constraints, and digital signatures.

Variables:

  • FEATURE – Database manager feature identifier for DAT operations.

  • ROT_META_CLASS – Root of Trust metadata class reference.

Initialize the DebugCredential object.

Creates a new DebugCredential instance with the specified parameters for secure debug access.

Parameters:

  • family (FamilyRevision) – Target MCU family and revision information.

  • version (ProtocolVersion) – Protocol version for the debug credential.

  • uuid (bytes) – Unique device identifier bytes.

  • rot_meta (RotMeta) – Metadata for Root of Trust configuration.

  • dck_pub (PublicKey) – Debug Credential public key for authentication.

  • cc_socu (int) – SoC Usage credential constraint value.

  • cc_vu (int) – Vendor Usage credential constraint value.

  • cc_beacon (int) – Credential Beacon value bound to this debug credential.

  • rot_pub (PublicKey) – Root of Trust public key for verification.

  • signature (Optional[bytes]) – Optional pre-computed debug credential signature.

  • signature_provider (Optional[SignatureProvider]) – Optional external signature provider for signing.

FEATURE: str = 'dat'#
ROT_META_CLASS#

alias of RotMeta

abstract calculate_hash()#

Calculate the RoT hash.

Return type:

bytes

Returns:

The calculated RoT (Root of Trust) hash as bytes.

static dat_based_on_ele(family)#

Get information if the DAT is based on EdgeLock Enclave hardware.

Parameters:

family (FamilyRevision) – The chip family and revision information.

Return type:

bool

Returns:

True if the ELE is target HW, False otherwise.

abstract export_dck_pub()#

Export Debugger public key (DCK) as bytes.

Return type:

bytes

Returns:

binary representing the DCK key

abstract export_rot_pub()#

Export RoT public key as bytes.

Return type:

bytes

Returns:

binary representing the RoT key

get_config(data_path='./')#

Get configuration for debug credential.

Parameters:

data_path (str) – Path to directory containing configuration data files.

Raises:

SPSDKNotImplementedError – Method is not implemented yet.

Return type:

Config

classmethod get_validation_schemas(family)#

Get list of validation schemas for debug credential configuration.

Retrieves and configures JSON validation schemas specific to the given family, including family-specific properties, SOCC values, and conditional schemas based on ELE (EdgeLock Enclave) support.

Parameters:

family (FamilyRevision) – Family revision for which the JSON schemas will be generated.

Return type:

list[dict[str, Any]]

Returns:

List of validation schemas including family schema, content schema, and optionally SRK CA flag schema for ELE-based families.

classmethod get_validation_schemas_from_cfg(config)#

Get validation schemas based on configuration.

Retrieves the appropriate validation schemas for the debug credential class by first validating the provided configuration against basic schemas, then determining the specific class implementation and returning its validation schemas for the target family.

Parameters:

config (Config) – Configuration object containing debug credential settings

Return type:

list[dict[str, Any]]

Returns:

List of validation schema dictionaries for the determined class

Raises:

SPSDKError – Invalid configuration or unsupported family

classmethod load_cert_block(rot_config_file, family)#

Load certificate block from a file.

The method supports loading from both Root of Trust configuration files and binary certificate block files. It first attempts to parse as a configuration file, and if that fails, tries to parse as a binary certificate block.

Parameters:

  • rot_config_file (str) – Path to Root of Trust configuration file or binary certificate block

  • family (FamilyRevision) – Family revision for the certificate block

Return type:

CertBlock

Returns:

Loaded certificate block object

Raises:

SPSDKError – When unable to create certificate block from the file

classmethod load_from_config(config)#

Create a debug credential object from YAML configuration.

This method processes the configuration to extract family information, ROT metadata, certificates, and signing parameters to construct a complete debug credential object.

Parameters:

config (Config) – Debug credential file configuration containing all necessary parameters.

Raises:

SPSDKError – Invalid configuration or missing required files.

Return type:

Self

Returns:

DebugCredential object configured according to the provided settings.

classmethod parse(data, family=Unknown, Revision: latest)#

Parse the debug credential from raw binary data.

The method first attempts to parse as EdgeLock Enclave V2 format, and if that fails, falls back to standard debug credential parsing based on the protocol version found in the data header.

Parameters:

  • data (bytes) – Raw binary data containing the debug credential.

  • family (FamilyRevision) – Target MCU family revision for credential validation.

Raises:

SPSDKError – When data cannot be parsed as any supported debug credential format.

Return type:

Self

Returns:

Parsed DebugCredential object of the appropriate subclass.

property rot_hash_length: int#

Get Root of Trust debug credential hash length.

Returns:

Hash length in bytes (always 32).

sign()#

Sign the DC data using SignatureProvider.

This method validates that a signature provider is configured, verifies the public key against the root of trust, generates a signature for the debug credential data, and stores the resulting signature.

Raises:

SPSDKError – If signature provider is not set or fails to return a signature.

Return type:

None

property socc: int#

Get the SoC Class value for the current family.

Retrieves the SoC Class (System on Chip Class) identifier from the database for the configured MCU family.

Returns:

SoC Class identifier as integer value.

property srk_count: int#

Get the number of Super Root Keys (SRK).

Returns:

Number of Super Root Keys, always returns 1.

class spsdk.dat.debug_credential.DebugCredentialCertificateEcc(family, version, uuid, rot_meta, dck_pub, cc_socu, cc_vu, cc_beacon, rot_pub, signature=None, signature_provider=None)#

Bases: DebugCredentialCertificate

ECC-specific Debug Credential Certificate implementation.

This class provides ECC (Elliptic Curve Cryptography) specific functionality for debug credential certificates, handling ECC key operations, hash calculations, and certificate data formatting for NXP MCU debug authentication.

Variables:

  • COORDINATE_SIZE – ECC coordinate sizes mapping for different curve types.

  • ROT_META_CLASS – Root of Trust metadata class for ECC operations.

Initialize the DebugCredential object.

Creates a new DebugCredential instance with the specified parameters for secure debug access.

Parameters:

  • family (FamilyRevision) – Target MCU family and revision information.

  • version (ProtocolVersion) – Protocol version for the debug credential.

  • uuid (bytes) – Unique device identifier bytes.

  • rot_meta (RotMeta) – Metadata for Root of Trust configuration.

  • dck_pub (PublicKey) – Debug Credential public key for authentication.

  • cc_socu (int) – SoC Usage credential constraint value.

  • cc_vu (int) – Vendor Usage credential constraint value.

  • cc_beacon (int) – Credential Beacon value bound to this debug credential.

  • rot_pub (PublicKey) – Root of Trust public key for verification.

  • signature (Optional[bytes]) – Optional pre-computed debug credential signature.

  • signature_provider (Optional[SignatureProvider]) – Optional external signature provider for signing.

COORDINATE_SIZE = {0: 32, 1: 48, 2: 66}#
ROT_META_CLASS#

alias of RotMetaEcc

calculate_hash()#

Calculate the Root of Trust Keys Hash (RoTKH).

The method first attempts to calculate the hash using the rot_meta object. If that fails, it falls back to calculating the hash directly from the exported public key using the appropriate SHA algorithm based on key size.

Raises:

SPSDKError – When rot_meta hash calculation fails and fallback is used.

Return type:

bytes

Returns:

Root of Trust Keys Hash as bytes.

export()#

Export debug credential to binary format.

Serializes the debug credential object into its binary representation for storage or transmission. The credential must be signed before export.

Raises:

SPSDKError – If the debug credential signature is not set.

Return type:

bytes

Returns:

Binary representation of the debug credential.

export_dck_pub()#

Export Debugger public key (DCK) as bytes.

Return type:

bytes

Returns:

Binary representing the DCK key.

export_rot_pub()#

Export RoT public key as bytes.

Return type:

bytes

Returns:

Binary data representing the RoT public key.

get_data_format(include_signature=True)#

Get the format of exported binary data.

Returns a struct format string that describes the binary layout of the debug credential data, including version, SOCC, UUID, control codes, metadata, public keys, and optionally the signature.

Parameters:

include_signature (bool) – Whether to include signature in the format string.

Raises:

SPSDKError – When signature is requested but not set.

Return type:

str

Returns:

Struct format string for binary data packing.

classmethod parse(data, family=Unknown, Revision: latest)#

Parse the debug credential from binary data.

This method deserializes binary data into a DebugCredential object by unpacking the structured format and validating the SOCC (SoC Class) value against the family-specific SOCC.

Parameters:

  • data (bytes) – Raw binary data containing the debug credential structure.

  • family (FamilyRevision) – Target MCU family revision for validation purposes.

Raises:

SPSDKValueError – When SOCC from binary data doesn’t match family SOCC.

Return type:

Self

Returns:

Parsed DebugCredential object with all fields populated.

property rot_hash_length: int#

Get Root of Trust debug credential hash length.

The method determines the hash length based on database configuration and public key size. If the database specifies SHA256 usage, returns 32 bytes. Otherwise, calculates the length from the ECC public key size.

Returns:

Hash length in bytes (32 for SHA256 or calculated from key size).

Raises:

AssertionError – If rot_pub is not an instance of PublicKeyEcc.

class spsdk.dat.debug_credential.DebugCredentialCertificateRsa(family, version, uuid, rot_meta, dck_pub, cc_socu, cc_vu, cc_beacon, rot_pub, signature=None, signature_provider=None)#

Bases: DebugCredentialCertificate

RSA-specific implementation of Debug Credential Certificate.

This class provides RSA cryptographic operations for debug credential certificates, including RSA key handling, hash calculations, and RSA-specific data export formats.

Variables:

ROT_META_CLASS – RSA-specific Root of Trust metadata class type.

Initialize the DebugCredential object.

Creates a new DebugCredential instance with the specified parameters for secure debug access.

Parameters:

  • family (FamilyRevision) – Target MCU family and revision information.

  • version (ProtocolVersion) – Protocol version for the debug credential.

  • uuid (bytes) – Unique device identifier bytes.

  • rot_meta (RotMeta) – Metadata for Root of Trust configuration.

  • dck_pub (PublicKey) – Debug Credential public key for authentication.

  • cc_socu (int) – SoC Usage credential constraint value.

  • cc_vu (int) – Vendor Usage credential constraint value.

  • cc_beacon (int) – Credential Beacon value bound to this debug credential.

  • rot_pub (PublicKey) – Root of Trust public key for verification.

  • signature (Optional[bytes]) – Optional pre-computed debug credential signature.

  • signature_provider (Optional[SignatureProvider]) – Optional external signature provider for signing.

ROT_META_CLASS#

alias of RotMetaRSA

calculate_hash()#

Calculate Root Of Trust Keys Hash.

This method computes the hash of the Root of Trust keys using the associated rotation metadata.

Return type:

bytes

Returns:

Root Of Trust Keys Hash (RoTKH) as bytes.

export()#

Export debug credential to binary form.

Serializes the debug credential object into its binary representation that can be used for provisioning or storage purposes.

Return type:

bytes

Returns:

Binary representation of the debug credential.

Raises:

SPSDKError – When debug credential signature is not set, call the sign method first.

export_dck_pub()#

Export Debugger public key (DCK) as bytes.

The method exports the Debug Credential Key (DCK) public key component in binary format with a 4-byte exponent length.

Raises:

AssertionError – If the DCK public key is not an RSA key instance.

Return type:

bytes

Returns:

Binary representation of the DCK public key.

export_rot_pub()#

Export RoT public key as bytes.

The method exports the Root of Trust (RoT) public key in binary format with a 4-byte exponent length.

Raises:

AssertionError – If the RoT public key is not an RSA public key.

Return type:

bytes

Returns:

Binary representation of the RoT public key.

classmethod get_data_format(version, include_signature=True)#

Get the format of exported binary data.

Constructs a struct format string for packing/unpacking debug credential binary data based on the protocol version and signature inclusion requirements.

Parameters:

  • version (ProtocolVersion) – Protocol version that determines key and signature sizes.

  • include_signature (bool) – Whether to include signature field in the format.

Return type:

str

Returns:

Struct format string for binary data packing/unpacking.

classmethod parse(data, family=Unknown, Revision: latest)#

Parse the debug credential from raw binary data.

The method extracts and validates all components of a debug credential including version, UUID, rotation metadata, public keys, capability constraints, and signature. It also validates that the parsed SOCC matches the expected family SOCC.

Parameters:

  • data (bytes) – Raw binary data containing the debug credential

  • family (FamilyRevision) – Target MCU family revision for validation

Raises:

SPSDKValueError – When parsed SOCC doesn’t match expected family SOCC

Return type:

Self

Returns:

Parsed DebugCredential object with all extracted components

class spsdk.dat.debug_credential.DebugCredentialEdgeLockEnclave(family, version, uuid, rot_meta, dck_pub, cc_socu, cc_vu, cc_beacon, rot_pub, signature=None, signature_provider=None)#

Bases: DebugCredentialCertificateEcc

Debug credential implementation for EdgeLock Enclave devices.

This class provides specialized debug credential functionality for NXP EdgeLock Enclave secure elements, handling ECC-based authentication and credential management with EdgeLock-specific Root of Trust metadata.

Variables:

ROT_META_CLASS – Root of Trust metadata class for EdgeLock Enclave.

Initialize the DebugCredential object.

Creates a new DebugCredential instance with the specified parameters for secure debug access.

Parameters:

  • family (FamilyRevision) – Target MCU family and revision information.

  • version (ProtocolVersion) – Protocol version for the debug credential.

  • uuid (bytes) – Unique device identifier bytes.

  • rot_meta (RotMeta) – Metadata for Root of Trust configuration.

  • dck_pub (PublicKey) – Debug Credential public key for authentication.

  • cc_socu (int) – SoC Usage credential constraint value.

  • cc_vu (int) – Vendor Usage credential constraint value.

  • cc_beacon (int) – Credential Beacon value bound to this debug credential.

  • rot_pub (PublicKey) – Root of Trust public key for verification.

  • signature (Optional[bytes]) – Optional pre-computed debug credential signature.

  • signature_provider (Optional[SignatureProvider]) – Optional external signature provider for signing.

ROT_META_CLASS#

alias of RotMetaEdgeLockEnclave

calculate_hash()#

Calculate Root Of Trust Keys Hash.

This method computes the hash of the Root Of Trust keys using the associated metadata.

Return type:

bytes

Returns:

Root Of Trust Keys Hash (RoTKH) as bytes.

export()#

Export debug credential to binary format for storage or transmission.

Serializes the debug credential object into its binary representation according to the specified data format. The credential must be properly signed before export.

Raises:

SPSDKError – Debug credential signature is not set.

Return type:

bytes

Returns:

Binary representation of the debug credential.

get_data_format(include_signature=True)#

Get the format of exported binary data.

Constructs a struct format string for packing the debug credential data into binary format. The format includes version, SOCC, UUID, control codes, RoT metadata, DCK public key, and optionally the signature.

Parameters:

include_signature (bool) – Whether to include signature in the format string.

Raises:

SPSDKError – If signature is requested but not set.

Return type:

str

Returns:

Struct format string for binary data packing.

classmethod parse(data, family=Unknown, Revision: latest)#

Parse the debug credential from binary data.

The method parses binary data containing a debug credential structure, validates the SOCC (SoC Class) value against the family, and constructs a DebugCredential object with all parsed components.

Parameters:

  • data (bytes) – Raw binary data containing the debug credential structure.

  • family (FamilyRevision) – Target MCU family revision for validation.

Raises:

SPSDKValueError – When SOCC from binary data doesn’t match family SOCC.

Return type:

Self

Returns:

Parsed DebugCredential object with all components initialized.

property rot_hash_length: int#

Root of Trust debug credential hash length.

Returns:

Hash length in bytes (always 32).

class spsdk.dat.debug_credential.DebugCredentialEdgeLockEnclaveV2(family, certificate)#

Bases: DebugCredentialCertificate

Debug Credential for EdgeLock Enclave version 2 with Post-Quantum Cryptography support.

This class represents a debug credential specifically designed for EdgeLock Enclave (ELE) version 2, which includes support for Post-Quantum Cryptography (PQC). It manages the creation and validation of debug credentials used for secure debugging operations on NXP MCUs with ELE v2 security subsystem.

Variables:

  • SUB_FEATURE – Feature identifier for ELE with PQC support.

  • ROT_META_CLASS – Root of Trust metadata class used for this credential type.

Constructor for EdgeLock Enclave version 2 debug credential class.

Initializes a debug credential instance with the specified family revision and certificate. The certificate must contain a valid SRKRecordV2 public key.

Parameters:

  • family (FamilyRevision) – Target MCU family and revision information.

  • certificate (AhabCertificate) – AHAB certificate containing the public key and UUID for the credential.

Raises:

AssertionError – If certificate.public_key_0 is not an instance of SRKRecordV2.

ROT_META_CLASS#

alias of RotMetaDummy

SUB_FEATURE: Optional[str] = 'ele_pqc'#
property beacon: int#

Get the beacon value from the debug credential SOCU field.

Extracts and returns the beacon value from the certificate’s permission data by unpacking the third 32-bit little-endian value.

Returns:

Beacon value extracted from the SOCU field.

calculate_hash()#

Calculate the RoT hash.

Return type:

bytes

Returns:

The calculated Root of Trust hash as bytes.

export()#

Export debug credential to binary form.

Serializes the debug credential certificate into its binary representation for storage or transmission.

Return type:

bytes

Returns:

Binary representation of the debug credential certificate.

export_dck_pub()#

Export Debugger public key (DCK) as bytes.

Return type:

bytes

Returns:

Binary representing the DCK key.

export_rot_pub()#

Export RoT public key as bytes.

Return type:

bytes

Returns:

Binary representing the RoT key.

classmethod get_validation_schemas(family)#

Get list of validation schemas for Debug Credential configuration.

The method retrieves and customizes validation schemas based on the target family, including AHAB certificate schemas and family-specific configurations. It handles special cases like beacon usage and vendor usage instead of fuse version.

Parameters:

family (FamilyRevision) – Family revision for which the JSON schema will be generated.

Return type:

list[dict[str, Any]]

Returns:

List of validation schemas with family-specific customizations.

classmethod load_from_config(config)#

Create a debug credential object from YAML configuration.

The method processes configuration data to create a debug credential with proper family-specific settings, including SOCC/SOCU values, beacon configuration, and permission data based on the target device family capabilities.

Parameters:

config (Config) – Debug credential file configuration containing device family, SOCU value, beacon settings, and other credential parameters.

Return type:

Self

Returns:

DebugCredential object configured for the specified device family.

classmethod parse(data, family=Unknown, Revision: latest)#

Parse the debug credential from raw binary data.

This method creates a DebugCredential object by parsing the provided binary data using the appropriate certificate class for the specified chip family.

Parameters:

  • data (bytes) – Raw binary data containing the debug credential.

  • family (FamilyRevision) – Chip family revision for proper parsing context.

Return type:

Self

Returns:

Parsed DebugCredential object.

sign()#

Sign the DC data using SignatureProvider.

This method updates the certificate fields and applies the digital signature to the Debug Credential data structure using the configured signature provider.

Raises:

SPSDKError – If signature generation fails or certificate update fails.

Return type:

None

property socc: int#

Get the SoCC (SoC Class) field from debug credential.

What is SoCC:

A unique identifier for a set of SoCs that require no SoC-specific differentiation in their debug authentication. The main usage is to allow a different set of debug domains and options to be negotiated between the device configuration and credentials. If the granularity of debug control warrants it, a class can contain a single revision of a single SoC model.

Extracts and returns the SoCC value from the first 4 bytes of the certificate’s permission data using little-endian byte order.

Returns:

SoCC field value as integer.

property socu: int#

Get the SoCU (SoC Usage) field from debug credential.

What is SoCu:

A CC (constraint) value that is a bit mask, and whose bits are used in an SoC-specific manner. These bits are typically used for controlling which debug domains are accessed via the authentication protocol. Device-specific debug options can also be managed in this way.

The SoCU field is extracted from the permission data section of the certificate by unpacking the first 12 bytes and returning the second 32-bit value.

Returns:

SoCU field value as integer.

property srk_count: int#

Get the number of Super Root Keys (SRK).

Returns:

Number of Super Root Keys, currently always returns 0.

Module with Debug Authentication Challenge (DAC) Packet#

SPSDK Debug Authentication Challenge (DAC) packet implementation.

This module provides functionality for creating and handling Debug Authentication Challenge packets used in the debug authentication protocol across NXP MCU devices.

class spsdk.dat.dac_packet.DebugAuthenticationChallenge(family, version, socc, uuid, rotid_rkh_revocation, rotid_rkth_hash, cc_soc_pinned, cc_soc_default, cc_vu, challenge)#

Bases: object

Debug Authentication Challenge packet for secure device access.

This class represents a challenge packet used in the Debug Authentication (DAT) protocol to establish secure communication with NXP MCU devices. It encapsulates device-specific information including SoC class, UUID, rotation keys, and challenge data required for authentication.

Initialize the DebugAuthenticationChallenge object.

Parameters:

  • family (FamilyRevision) – Target MCU family and revision information.

  • version (ProtocolVersion) – Protocol version (for RSA: 1.0, for ECC: 2.0, 2.1, 2.2).

  • socc (int) – SoC Class that this credential applies to.

  • uuid (bytes) – Unique device identifier bytes.

  • rotid_rkh_revocation (int) – State of certificate revocation field.

  • rotid_rkth_hash (bytes) – Hash of ROTH metadata.

  • cc_soc_pinned (int) – State of lock bits in the debugger configuration field.

  • cc_soc_default (int) – State of the debugger configuration field.

  • cc_vu (int) – Vendor usage associated with this credential.

  • challenge (bytes) – Randomly generated bytes from the target device.

export()#

Export the DebugAuthenticationChallenge into bytes.

The method serializes all DAC packet fields into a binary format using little-endian byte order. Version fields are swapped if required based on the swapped_version flag.

Return type:

bytes

Returns:

Binary representation of the DebugAuthenticationChallenge packet.

static get_rot_hash_length(family, major_ver, minor_ver)#

Get Root of Trust hash length for specified family and version.

The method determines the appropriate hash length based on the chip family configuration and DAT version. Some families always use SHA-256 (32 bytes), while others may use longer hashes depending on the version.

Parameters:

  • family (FamilyRevision) – The chip family revision identifier.

  • major_ver (int) – Major version of the DAT format.

  • minor_ver (int) – Minor version of the DAT format.

Return type:

int

Returns:

Length of Root of Trust hash in bytes.

classmethod parse(data, family=Unknown, Revision: latest)#

Parse raw bytes into a DebugAuthenticationChallenge object.

The method unpacks binary data according to the DAC packet format, handling version swapping for certain SoC families and extracting all challenge fields.

Parameters:

  • data (bytes) – Raw binary data containing the DAC packet

  • family (FamilyRevision) – The MCU/MPU family revision for proper parsing

Return type:

Self

Returns:

DebugAuthenticationChallenge object with parsed data

Module with Debug Authentication Response (DAR) Packet#

SPSDK Debug Authentication Response (DAR) packet implementation.

This module provides classes for creating and handling Debug Authentication Response packets used in the debug authentication process across NXP MCUs. It supports multiple cryptographic algorithms including RSA and various ECC curves, as well as EdgeLock Enclave V2 authentication responses.

class spsdk.dat.dar_packet.DebugAuthenticateResponse(family, debug_credential, auth_beacon, dac, sign_provider)#

Bases: FeatureBaseClass

Debug Authenticate Response packet for secure debug authentication.

This class manages the creation and processing of DAR (Debug Authenticate Response) packets used in NXP MCU secure debug authentication flow. It combines debug credentials, authentication challenges, and digital signatures to enable authorized debug access.

Variables:

FEATURE – Database manager feature identifier for DAT operations.

Initialize the DebugAuthenticateResponse object.

Parameters:

  • family (FamilyRevision) – Family revision of the target chip for DAR processing.

  • debug_credential (DebugCredentialCertificate) – Debug credential certificate object containing authentication data.

  • auth_beacon (int) – Authentication beacon value (will be truncated to 16 bits if exceeds 0xFFFF).

  • dac (DebugAuthenticationChallenge) – Debug authentication challenge object.

  • sign_provider (Optional[SignatureProvider]) – Optional signature provider for cryptographic operations.

FEATURE: str = 'dat'#
export()#

Export DAR packet to binary form.

Serializes the DAR packet by combining common data and signature into a binary representation suitable for transmission or storage.

Return type:

bytes

Returns:

Binary representation of the DAR packet.

get_config(data_path='./')#

Create configuration of the Feature.

Parameters:

data_path (str) – Path to directory containing configuration data files.

Raises:

SPSDKNotImplementedError – Method is not implemented in base class.

Return type:

Config

classmethod get_validation_schemas(family)#

Get validation schemas for DAR packet configuration.

The method retrieves and configures validation schemas for DAR (Debug Authentication Response) packet based on the specified family. It combines general family schema with DAR-specific classic schema and updates family validation rules.

Parameters:

family (FamilyRevision) – Family description containing chip family and revision information.

Raises:

SPSDKError – Family or revision is not supported.

Return type:

list[dict[str, Any]]

Returns:

List of validation schemas containing family and DAR classic schemas.

classmethod get_validation_schemas_from_cfg(config)#

Get validation schema based on configuration.

If the class doesn’t behave generally, just override this implementation.

Parameters:

config (Config) – Valid configuration object containing family and device settings.

Raises:

SPSDKError – Invalid configuration or unsupported family.

Return type:

list[dict[str, Any]]

Returns:

List of validation schema dictionaries for the specified configuration.

classmethod load_from_config(config, dac=None)#

Create Debug Authentication Response object from configuration.

Loads and validates configuration parameters to construct a Debug Authentication Response (DAR) object with proper cryptographic setup and credentials.

Parameters:

  • config (Config) – Debug authentication response configuration dictionaries.

  • dac (Optional[DebugAuthenticationChallenge]) – Debug Authentication Challenge object required for response creation.

Raises:

SPSDKValueError – When DAC object is not provided.

Return type:

Self

Returns:

Debug authentication response object.

classmethod parse(data)#

Parse DAR packet from binary data.

This is an abstract method that must be implemented by derived classes to handle specific DAR packet formats.

Parameters:

data (bytes) – Binary data containing the DAR packet to parse.

Raises:

SPSDKNotImplementedError – Always raised as this is an abstract method.

Return type:

Self

verify()#

Validate Debug Authentication Response against Debug Credential and Challenge data.

This comprehensive validation method performs cross-verification of multiple debug authentication components to ensure data consistency and security compliance. The verifier systematically checks: - Protocol Version Compatibility: Ensures DAC (Debug Authentication Challenge) and DC (Debug Credential) use compatible protocol versions - SoC Class (SOCC) Validation: Verifies that the SoC Class values match between DAC, DC, and the target chip family specifications - Device UUID Consistency: Confirms that device unique identifiers are consistent across all authentication components, with special handling for general/wildcard UUIDs - Root of Trust Hash Verification: Validates that the Root of Trust Key Hash (RoTKH) matches between the challenge and credential data

The method uses the DAR instance’s debug_credential, dac, and family attributes to perform validation. It generates detailed verification results with specific error messages, warnings for non-critical issues (like general UUIDs), and success confirmations for valid components.

Return type:

Verifier

Returns:

Verifier object containing detailed validation results and status for each checked component.

class spsdk.dat.dar_packet.DebugAuthenticateResponseECC(family, debug_credential, auth_beacon, dac, sign_provider)#

Bases: DebugAuthenticateResponse

Debug Authentication Response for Elliptic Curve Cryptography.

This class implements the Debug Authentication Response (DAR) packet specifically for elliptic curve cryptographic operations, extending the base DAR functionality with ECC-specific key handling and signature generation.

Variables:

  • KEY_LENGTH – Length of the ECC key in bytes.

  • CURVE – Default elliptic curve specification used for cryptographic operations.

Initialize the DebugAuthenticateResponse object.

Parameters:

  • family (FamilyRevision) – Family revision of the target chip for DAR processing.

  • debug_credential (DebugCredentialCertificate) – Debug credential certificate object containing authentication data.

  • auth_beacon (int) – Authentication beacon value (will be truncated to 16 bits if exceeds 0xFFFF).

  • dac (DebugAuthenticationChallenge) – Debug authentication challenge object.

  • sign_provider (Optional[SignatureProvider]) – Optional signature provider for cryptographic operations.

CURVE = 'secp256r1'#
KEY_LENGTH = 0#
class spsdk.dat.dar_packet.DebugAuthenticateResponseECC_256(family, debug_credential, auth_beacon, dac, sign_provider)#

Bases: DebugAuthenticateResponseECC

Debug Authentication Response for ECC P-256 curve.

This class implements Debug Authentication Response (DAR) functionality specifically for Elliptic Curve Cryptography using the P-256 curve with 256-bit keys.

Variables:

  • KEY_LENGTH – Length of the cryptographic key in bytes (32 bytes for 256-bit keys).

  • CURVE – The elliptic curve specification used for cryptographic operations.

Initialize the DebugAuthenticateResponse object.

Parameters:

  • family (FamilyRevision) – Family revision of the target chip for DAR processing.

  • debug_credential (DebugCredentialCertificate) – Debug credential certificate object containing authentication data.

  • auth_beacon (int) – Authentication beacon value (will be truncated to 16 bits if exceeds 0xFFFF).

  • dac (DebugAuthenticationChallenge) – Debug authentication challenge object.

  • sign_provider (Optional[SignatureProvider]) – Optional signature provider for cryptographic operations.

CURVE = 'secp256r1'#
KEY_LENGTH = 32#
class spsdk.dat.dar_packet.DebugAuthenticateResponseECC_384(family, debug_credential, auth_beacon, dac, sign_provider)#

Bases: DebugAuthenticateResponseECC

Debug Authentication Response handler for ECC P-384 curve operations.

This class implements Debug Authentication Response (DAR) functionality specifically for elliptic curve cryptography using the NIST P-384 curve with 384-bit key sizes.

Variables:

  • KEY_LENGTH – Length of the cryptographic key in bytes (48 bytes for P-384).

  • CURVE – The elliptic curve identifier used for cryptographic operations.

Initialize the DebugAuthenticateResponse object.

Parameters:

  • family (FamilyRevision) – Family revision of the target chip for DAR processing.

  • debug_credential (DebugCredentialCertificate) – Debug credential certificate object containing authentication data.

  • auth_beacon (int) – Authentication beacon value (will be truncated to 16 bits if exceeds 0xFFFF).

  • dac (DebugAuthenticationChallenge) – Debug authentication challenge object.

  • sign_provider (Optional[SignatureProvider]) – Optional signature provider for cryptographic operations.

CURVE = 'secp384r1'#
KEY_LENGTH = 48#
class spsdk.dat.dar_packet.DebugAuthenticateResponseECC_521(family, debug_credential, auth_beacon, dac, sign_provider)#

Bases: DebugAuthenticateResponseECC

Debug Authentication Response for ECC P-521 curve.

This class implements debug authentication response handling specifically for elliptic curve cryptography using the NIST P-521 curve with 521-bit keys.

Variables:

  • KEY_LENGTH – Length of the ECC P-521 key in bytes (66 bytes).

  • CURVE – The elliptic curve identifier for NIST P-521 curve.

Initialize the DebugAuthenticateResponse object.

Parameters:

  • family (FamilyRevision) – Family revision of the target chip for DAR processing.

  • debug_credential (DebugCredentialCertificate) – Debug credential certificate object containing authentication data.

  • auth_beacon (int) – Authentication beacon value (will be truncated to 16 bits if exceeds 0xFFFF).

  • dac (DebugAuthenticationChallenge) – Debug authentication challenge object.

  • sign_provider (Optional[SignatureProvider]) – Optional signature provider for cryptographic operations.

CURVE = 'secp521r1'#
KEY_LENGTH = 66#
class spsdk.dat.dar_packet.DebugAuthenticateResponseEdgelockEnclaveV2(family, debug_credential, auth_beacon, dac, sign_message)#

Bases: DebugAuthenticateResponse

Debug Authentication Response for EdgeLock Enclave devices using AHAB v2.

This class implements the Debug Authentication Response (DAR) protocol specifically for NXP devices equipped with EdgeLock Enclave security subsystem that utilize AHAB (Advanced High Assurance Boot) signed message format version 2. It handles the creation and export of authentication responses required for secure debug access to protected MCU resources.

Initialize DAR packet for EdgeLock Enclave devices with AHAB v2.

Constructor for Debug Authentication Response (DAR) packet specifically designed for devices using EdgeLock Enclave with Authentication Header Boot (AHAB) version 2.

Parameters:

  • family (FamilyRevision) – Target MCU family and revision information

  • debug_credential (DebugCredentialCertificate) – Debug credential certificate for authentication

  • auth_beacon (int) – Authentication beacon value for the debug session

  • dac (DebugAuthenticationChallenge) – Debug authentication challenge data

  • sign_message (SignedMessage) – Signed message containing authentication data

export()#

Export to binary form (serialization).

The method updates the sign message fields and exports the object as bytes.

Return type:

bytes

Returns:

The exported bytes from object.

classmethod get_validation_schemas(family)#

Create the validation schemas for DAR packet configuration.

This method builds a list of validation schemas by combining family schema, modified SignedMessage schema, AHAB debug certificate schema, and optionally ELE authentication beacon schema based on family capabilities.

Parameters:

family (FamilyRevision) – Family description containing device family and revision information.

Raises:

SPSDKError – Family or revision is not supported.

Return type:

list[dict[str, Any]]

Returns:

List of validation schemas for DAR packet configuration.

classmethod load_from_config(config, dac=None)#

Load debug authentication response from configuration.

The method creates a Debug Authentication Response (DAR) object by processing the configuration and combining it with the Debug Authentication Challenge (DAC). It handles beacon configuration, loads debug credentials, and creates a signed message for the authentication response.

Parameters:

  • config (Config) – Debug authentication response configuration dictionaries.

  • dac (Optional[DebugAuthenticationChallenge]) – Debug Authentication Challenge object containing UUID and challenge vector.

Raises:

SPSDKValueError – If DAC object is not provided.

Return type:

Self

Returns:

Debug authentication response object.

class spsdk.dat.dar_packet.DebugAuthenticateResponseRSA(family, debug_credential, auth_beacon, dac, sign_provider)#

Bases: DebugAuthenticateResponse

Debug Authenticate Response packet with RSA-specific implementation.

This class extends the base DebugAuthenticateResponse to handle RSA cryptographic operations and data structures specific to RSA-based debug authentication protocols.

Initialize the DebugAuthenticateResponse object.

Parameters:

  • family (FamilyRevision) – Family revision of the target chip for DAR processing.

  • debug_credential (DebugCredentialCertificate) – Debug credential certificate object containing authentication data.

  • auth_beacon (int) – Authentication beacon value (will be truncated to 16 bits if exceeds 0xFFFF).

  • dac (DebugAuthenticationChallenge) – Debug authentication challenge object.

  • sign_provider (Optional[SignatureProvider]) – Optional signature provider for cryptographic operations.

Module for NXP SPDK DebugMailbox support#

SPSDK Debug Mailbox communication interface.

This module provides functionality for communicating with NXP MCU debug mailbox through debug probes, enabling secure provisioning and debugging operations. Key components: - DebugMailbox: Main class for debug mailbox communication - DebugMailboxError: Exception handling for mailbox operations

class spsdk.dat.debug_mailbox.DebugMailbox(debug_probe, family, reset=True, moredelay=0.0, op_timeout=1000)#

Bases: object

Debug Mailbox communication interface for NXP MCU devices.

This class provides a standardized interface for communicating with the debug mailbox functionality present in NXP MCU devices. It handles the low-level protocol operations, register access, and synchronization required for debug authentication and provisioning operations through the debug probe connection. The debug mailbox enables secure communication between external tools and the device’s ROM code or secure firmware, supporting operations like authentication challenges, key provisioning, and secure debug unlock procedures.

Initialize DebugMailbox object.

Establishes connection to the debug mailbox by performing resynchronization request and waiting for acknowledgement from ROM code.

Parameters:

  • debug_probe (DebugProbe) – Debug probe instance for communication.

  • family (FamilyRevision) – Chip family and revision information.

  • reset (bool) – Do reset of debug mailbox during initialization, defaults to True.

  • moredelay (float) – Time of extra delay after reset sequence in seconds, defaults to 0.0.

  • op_timeout (int) – Atomic operation timeout in milliseconds, defaults to 1000.

Raises:

SPSDKIOError – Connection timeout or communication failure with debug mailbox.

close()#

Close the debug mailbox session.

This method properly closes the connection to the debug probe and cleans up any associated resources.

Return type:

None

dbgmlbx_reg_read(addr=0)#

Read debug mailbox access port register.

This function reads a debug mailbox register through the debug probe interface to support various debug probes in the SPSDK library.

Parameters:

addr (int) – The register address to read from.

Return type:

int

Returns:

The read value of addressed register (4 bytes).

dbgmlbx_reg_write(addr=0, data=0)#

Write debug mailbox access port register.

Writes data to a specified register address in the debug mailbox access port using the configured debug probe’s CoreSight interface.

Parameters:

  • addr (int) – Register address to write to.

  • data (int) – Data value to write into the register.

Return type:

None

get_dbgmlbx_ap()#

Decorator function that secures getting the correct DEBUG MAILBOX AP index for first use.

The decorator automatically detects the debug mailbox access port index by trying predefined possible indices and validating against the expected IDR register value. If no valid access port is found, it raises an exception.

Parameters:

func – The function to be decorated that requires debug mailbox access.

Raises:

SPSDKError – When debug mailbox access port cannot be found.

Returns:

Decorated function wrapper.

read_idr()#

Read IDR of debug mailbox.

Reads the Identification Register (IDR) value from the debug mailbox Access Port and validates it against the expected value. Issues a warning if the values don’t match.

Return type:

int

Returns:

IDR value of debug mailbox AP.

spin_read(reg)#

Perform atomic read operation from debug mailbox register.

This method continuously attempts to read from the specified register until successful or timeout occurs. It handles transient errors by retrying with a small delay.

Parameters:

reg (int) – Register address to read from.

Return type:

int

Returns:

Value read from the register.

Raises:

SPSDKTimeoutError – When read operation exceeds defined operation timeout.

spin_write(reg, value)#

Perform atomic write operation to debug mailbox.

The method writes data to the specified register and waits for the ROM code to process the request. It includes retry logic with timeout handling to ensure reliable operation.

Parameters:

  • reg (int) – Register address to write to.

  • value (int) – Value to write to the register.

Raises:

SPSDKTimeoutError – When write operation exceeds defined operation timeout.

Return type:

None

exception spsdk.dat.debug_mailbox.DebugMailboxError#

Bases: RuntimeError

Debug Mailbox operation error exception.

Exception raised when Debug Mailbox operations fail due to communication errors, invalid responses, or hardware-related issues during secure provisioning operations.

Module with commands for Debug Mailbox#

SPSDK Debug Mailbox command implementations.

This module provides command classes for interacting with NXP MCU debug mailboxes, including authentication, flash operations, and debug session management.

class spsdk.dat.dm_commands.DebugAuthenticationResponse(dm, paramlen)#

Bases: DebugMailboxCommand

Debug authentication response command for secure debug mailbox communication.

This class represents a response message in the debug authentication protocol, handling the reply from the target device during secure debug session establishment.

Variables:

CMD – Command identifier for debug authentication response (0x11).

Initialize Debug Mailbox command.

Parameters:

  • dm (DebugMailbox) – Debug mailbox instance for communication.

  • paramlen (int) – Length of command parameters in bytes.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (17, 'DBG_AUTH_RESP', 'Debug Authentication Response')#
class spsdk.dat.dm_commands.DebugAuthenticationStart(dm, resplen=26)#

Bases: DebugMailboxCommand

Debug authentication start command for secure debug access.

This command initiates the debug authentication process in the debug mailbox, allowing secure access to debug features on NXP MCUs. The command supports different hash algorithms (SHA256/SHA384) with configurable response lengths.

Variables:

CMD – Command identifier for debug authentication start operation.

Initialize Debug Mailbox command.

Sets up the command with the specified Debug Mailbox instance and response length. The response length determines the expected size of the command response in words, with default supporting SHA256 (26 words = 104 bytes) and optional SHA384 support (30 words = 120 bytes).

Parameters:

  • dm (DebugMailbox) – Debug Mailbox instance to use for command execution.

  • resplen (int) – Expected response length in words, defaults to 26 for SHA256.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (16, 'DBG_AUTH_START', 'Start Debug Authentication')#
class spsdk.dat.dm_commands.DebugMailboxCommand(dm, paramlen=0, resplen=0, delay=None, response_delay=None)#

Bases: object

Debug Mailbox command executor for NXP MCU communication.

This class provides a standardized interface for executing debug mailbox commands on NXP MCUs. It handles command formatting, parameter validation, timing delays, and response processing for reliable debug mailbox communication.

Variables:

  • DELAY_DEFAULT – Default delay after sending a command in seconds.

  • CMD – Command identifier for the debug mailbox operation.

Initialize Debug Mailbox command.

Sets up the command with the specified debug mailbox instance and configuration parameters for command execution timing and data lengths.

Parameters:

  • dm (DebugMailbox) – Debug mailbox instance for command execution.

  • paramlen (int) – Length of command parameters in bytes, defaults to 0.

  • resplen (int) – Expected length of response data in bytes, defaults to 0.

  • delay (Optional[float]) – Custom delay before command execution in seconds, uses default if None.

  • response_delay (Optional[float]) – Custom delay after command execution in seconds, optional.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (0, 'GENERAL', 'Dummy command')#
DELAY_DEFAULT = 0.03#
run(params=None)#

Execute debug mailbox command with optional parameters.

Sends command to debug mailbox, handles parameter transmission, waits for response, and validates the communication protocol. Supports both legacy and new protocol versions with proper error handling and acknowledgment sequences.

Parameters:

params (Optional[list[int]]) – Optional list of integer parameters to send with the command.

Raises:

SPSDKError – When parameter length mismatch, device communication errors, status codes indicate failure, or protocol validation fails.

Return type:

list[Any]

Returns:

List of response values from the debug mailbox command execution.

run_safe(raise_if_failure=True, **args)#

Run a command and abort on first failure instead of looping forever.

This method provides a safe wrapper around the run method that handles timeout exceptions gracefully and prevents infinite loops on command failures.

Parameters:

  • raise_if_failure (bool) – If True, re-raises timeout exceptions; if False, logs errors and returns None.

  • args (Any) – Additional keyword arguments passed to the underlying run method.

Raises:

SPSDKTimeoutError – When a timeout occurs and raise_if_failure is True.

Return type:

Optional[list[Any]]

Returns:

Result from the run method on success, None on timeout when raise_if_failure is False.

class spsdk.dat.dm_commands.DebugMailboxCommandID(tag, label, description=None)#

Bases: SpsdkEnum

Debug Mailbox command identifier enumeration.

This enumeration defines all available command IDs used in the Debug Mailbox protocol for NXP MCUs. Each command includes an ID value, name, and description covering basic operations, mode control, authentication, flash operations, and provisioning functionality.

DBG_AUTH_RESP = (17, 'DBG_AUTH_RESP', 'Debug Authentication Response')#
DBG_AUTH_START = (16, 'DBG_AUTH_START', 'Start Debug Authentication')#
ENTER_BLANK_DEBUG_AUTH = (8, 'ENTER_BLANK_DEBUG_AUTH', 'Enter Blank Debug Authentication')#
ENTER_ISP_MODE = (5, 'ENTER_ISP_MODE', 'Enter In-System Programming mode')#
ERASE_FLASH = (3, 'ERASE_FLASH', 'Erase entire Flash memory')#
ERASE_ONE_SECTOR = (11, 'ERASE_ONE_SECTOR', 'Erase a single Flash sector')#
EXIT = (4, 'EXIT', 'Exit Debug Mailbox')#
GENERAL = (0, 'GENERAL', 'Dummy command')#
GET_CRP_LEVEL = (2, 'GET_CRP_LEVEL', 'Get Code Read Protection Level')#
NXP_DBG_AUTH_RESP = (19, 'NXP_DBG_AUTH_RESP', 'NXP-specific Debug Authentication Response')#
NXP_DBG_AUTH_START = (18, 'NXP_DBG_AUTH_START', 'NXP-specific Debug Authentication Start')#
NXP_EXEC_PROV_FW = (21, 'NXP_EXEC_PROV_FW', 'Execute Provisioning NXP Firmware')#
NXP_SSF_INSERT_CERT = (20, 'NXP_SSF_INSERT_CERT', 'Create self-signed certificate as part of Self sign flow ')#
SET_BRICKED_MODE = (22, 'SET_BRICKED_MODE', 'Set device bricked mode')#
SET_FA_MODE = (6, 'SET_FA_MODE', 'Set Fault Analysis mode')#
START = (1, 'START', 'Start Debug Mailbox')#
START_DBG_SESSION = (7, 'START_DBG_SESSION', 'Start Debug Session')#
WRITE_TO_FLASH = (9, 'WRITE_TO_FLASH', 'Write data to Flash memory')#
class spsdk.dat.dm_commands.DebugMailboxCommandID2(tag, label, description=None)#

Bases: SpsdkEnum

Debug Mailbox Command ID enumeration for specific device implementations.

This enumeration defines command identifiers used by the Debug Mailbox interface for devices that require alternative command implementations compared to the standard command set.

NXP_EXEC_PROV_FW = (19, 'NXP_EXEC_PROV_FW', 'Execute Provisioning NXP Firmware')#
NXP_SSF_INSERT_DUK = (18, 'NXP_SSF_INSERT_DUK', 'Create NXP PUF AC code store area as part of Self sign flow (SSF)')#
class spsdk.dat.dm_commands.EnterBlankDebugAuthentication(dm)#

Bases: DebugMailboxCommand

Debug mailbox command for entering blank debug authentication mode.

This command initiates blank debug authentication, which allows debug access without requiring authentication credentials. This is typically used in development scenarios where security restrictions need to be bypassed.

Variables:

CMD – Command identifier for blank debug authentication entry.

Initialize the debug mailbox command.

Parameters:

dm (DebugMailbox) – Debug mailbox instance to be used for command execution.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (8, 'ENTER_BLANK_DEBUG_AUTH', 'Enter Blank Debug Authentication')#
class spsdk.dat.dm_commands.EnterISPMode(dm)#

Bases: DebugMailboxCommand

Debug Mailbox command for entering In-System Programming mode.

This command instructs the target device to enter ISP mode, allowing for firmware updates and programming operations through the debug mailbox interface.

Variables:

CMD – Command identifier for Enter ISP Mode operation.

Initialize the debug mailbox command.

Parameters:

dm (DebugMailbox) – Debug mailbox instance to be used for command execution.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (5, 'ENTER_ISP_MODE', 'Enter In-System Programming mode')#
class spsdk.dat.dm_commands.EraseFlash(dm)#

Bases: DebugMailboxCommand

Debug Mailbox command for erasing flash memory.

This command provides functionality to erase flash memory through the debug mailbox interface, allowing secure provisioning operations to clear flash content before programming new data.

Variables:

CMD – Command identifier for erase flash operation.

Initialize the debug mailbox command.

Parameters:

dm (DebugMailbox) – Debug mailbox instance to be used for command execution.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (3, 'ERASE_FLASH', 'Erase entire Flash memory')#
class spsdk.dat.dm_commands.EraseOneSector(dm)#

Bases: DebugMailboxCommand

Debug mailbox command for erasing a single flash memory sector.

This command provides functionality to erase one specific sector in the target device’s flash memory through the debug mailbox interface.

Variables:

CMD – Command identifier for erase one sector operation.

Initialize the debug mailbox command.

Parameters:

dm (DebugMailbox) – Debug mailbox instance to be used for command execution.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (11, 'ERASE_ONE_SECTOR', 'Erase a single Flash sector')#
class spsdk.dat.dm_commands.ExitDebugMailbox(dm, paramlen=0, resplen=0, delay=None, response_delay=None)#

Bases: DebugMailboxCommand

Debug mailbox command for exiting debug mode.

This command instructs the target device to exit the debug mailbox communication mode and return to normal operation.

Variables:

CMD – Command identifier for exit debug mailbox operation.

Initialize Debug Mailbox command.

Sets up the command with the specified debug mailbox instance and configuration parameters for command execution timing and data lengths.

Parameters:

  • dm (DebugMailbox) – Debug mailbox instance for command execution.

  • paramlen (int) – Length of command parameters in bytes, defaults to 0.

  • resplen (int) – Expected length of response data in bytes, defaults to 0.

  • delay (Optional[float]) – Custom delay before command execution in seconds, uses default if None.

  • response_delay (Optional[float]) – Custom delay after command execution in seconds, optional.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (4, 'EXIT', 'Exit Debug Mailbox')#
class spsdk.dat.dm_commands.GetCRPLevel(dm, paramlen=0, resplen=0, delay=None, response_delay=None)#

Bases: DebugMailboxCommand

Debug Mailbox command for retrieving Code Read Protection (CRP) level.

This command queries the target device to obtain the current CRP level, which determines the level of code protection and debug access restrictions applied to the MCU.

Variables:

CMD – Command identifier for Get CRP Level operation.

Initialize Debug Mailbox command.

Sets up the command with the specified debug mailbox instance and configuration parameters for command execution timing and data lengths.

Parameters:

  • dm (DebugMailbox) – Debug mailbox instance for command execution.

  • paramlen (int) – Length of command parameters in bytes, defaults to 0.

  • resplen (int) – Expected length of response data in bytes, defaults to 0.

  • delay (Optional[float]) – Custom delay before command execution in seconds, uses default if None.

  • response_delay (Optional[float]) – Custom delay after command execution in seconds, optional.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (2, 'GET_CRP_LEVEL', 'Get Code Read Protection Level')#
class spsdk.dat.dm_commands.NxpDebugAuthenticationResponse(dm, paramlen)#

Bases: DebugMailboxCommand

NXP Debug Authentication Response command for debug mailbox communication.

This class represents a response command used in the NXP debug authentication process, handling the authentication response data through the debug mailbox interface.

Variables:

CMD – Command identifier for NXP debug authentication response (0x13).

Initialize Debug Mailbox command.

Parameters:

  • dm (DebugMailbox) – Debug mailbox instance for communication.

  • paramlen (int) – Length of command parameters in bytes.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (19, 'NXP_DBG_AUTH_RESP', 'NXP-specific Debug Authentication Response')#
class spsdk.dat.dm_commands.NxpDebugAuthenticationStart(dm, resplen=26)#

Bases: DebugMailboxCommand

NXP Debug Authentication Start command for debug mailbox operations.

This class implements the debug authentication start command that initiates the authentication process for NXP debug operations through the debug mailbox interface. It handles the initial phase of secure debug authentication.

Variables:

CMD – Command identifier for NXP debug authentication start operation.

Initialize Debug Mailbox command.

Sets up the command with specified debug mailbox instance and response length. The response length determines the hash algorithm used: 26 words (104 bytes) for SHA256 or 30 words (120 bytes) for SHA384.

Parameters:

  • dm (DebugMailbox) – Debug mailbox instance for communication.

  • resplen (int) – Expected response length in words, defaults to 26 for SHA256.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (18, 'NXP_DBG_AUTH_START', 'NXP-specific Debug Authentication Start')#
class spsdk.dat.dm_commands.NxpExecuteProvisioningFw(dm, paramlen=0, resplen=0, delay=None, response_delay=None)#

Bases: DebugMailboxCommand

Debug mailbox command for executing provisioning firmware.

This command triggers the execution of provisioning firmware on NXP MCU devices through the debug mailbox interface, enabling secure provisioning operations.

Variables:

CMD – Command identifier for NXP execute provisioning firmware operation.

Initialize Debug Mailbox command.

Sets up the command with the specified debug mailbox instance and configuration parameters for command execution timing and data lengths.

Parameters:

  • dm (DebugMailbox) – Debug mailbox instance for command execution.

  • paramlen (int) – Length of command parameters in bytes, defaults to 0.

  • resplen (int) – Expected length of response data in bytes, defaults to 0.

  • delay (Optional[float]) – Custom delay before command execution in seconds, uses default if None.

  • response_delay (Optional[float]) – Custom delay after command execution in seconds, optional.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (19, 'NXP_EXEC_PROV_FW', 'Execute Provisioning NXP Firmware')#
class spsdk.dat.dm_commands.NxpSsfInsertCert(dm, paramlen=8, resplen=696, response_delay=1.0)#

Bases: DebugMailboxCommand

NXP Self-Signed Flow certificate insertion command.

This debug mailbox command handles the creation and insertion of self-signed certificates as part of NXP’s Self Sign Flow (SSF) provisioning process for secure boot operations.

Variables:

CMD – Command identifier for NXP SSF certificate insertion operation.

Initialize the debug mailbox command.

Sets up the command with specified parameter length, response length, and response delay for debug mailbox communication.

Parameters:

  • dm (DebugMailbox) – Debug mailbox instance for communication.

  • paramlen (int) – Length of command parameters in bytes.

  • resplen (int) – Expected response length in bytes.

  • response_delay (float) – Delay in seconds to wait for response.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (20, 'NXP_SSF_INSERT_CERT', 'Create self-signed certificate as part of Self sign flow ')#
class spsdk.dat.dm_commands.NxpSsfInsertDuk(dm, paramlen=8, resplen=16)#

Bases: DebugMailboxCommand

NXP SSF Insert DUK debug mailbox command.

This class implements the NXP Self Sign Flow (SSF) Insert Device Unique Key (DUK) command for creating PUF AC code store area through the debug mailbox interface.

Variables:

CMD – Debug mailbox command identifier for NXP SSF Insert DUK operation.

Initialize the debug mailbox command.

Parameters:

  • dm (DebugMailbox) – Debug mailbox instance for communication.

  • paramlen (int) – Length of command parameters in bytes, defaults to 8.

  • resplen (int) – Length of expected response in bytes, defaults to 16.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (18, 'NXP_SSF_INSERT_DUK', 'Create NXP PUF AC code store area as part of Self sign flow (SSF)')#
class spsdk.dat.dm_commands.SetBrickedMode(dm, paramlen=0, resplen=0, delay=None, response_delay=None)#

Bases: DebugMailboxCommand

Class for SetBrickedMode.

Initialize Debug Mailbox command.

Sets up the command with the specified debug mailbox instance and configuration parameters for command execution timing and data lengths.

Parameters:

  • dm (DebugMailbox) – Debug mailbox instance for command execution.

  • paramlen (int) – Length of command parameters in bytes, defaults to 0.

  • resplen (int) – Expected length of response data in bytes, defaults to 0.

  • delay (Optional[float]) – Custom delay before command execution in seconds, uses default if None.

  • response_delay (Optional[float]) – Custom delay after command execution in seconds, optional.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (22, 'SET_BRICKED_MODE', 'Set device bricked mode')#
class spsdk.dat.dm_commands.SetFaultAnalysisMode(dm, paramlen=0)#

Bases: DebugMailboxCommand

Debug mailbox command for setting fault analysis mode.

This command configures the fault analysis mode in the target device’s debug mailbox, enabling or disabling fault analysis capabilities for debugging and diagnostic purposes.

Variables:

CMD – Command identifier for set fault analysis mode operation.

Initialize Debug Mailbox command.

Parameters:

  • dm (DebugMailbox) – Debug mailbox instance for communication.

  • paramlen (int) – Length of command parameters in bytes, defaults to 0.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (6, 'SET_FA_MODE', 'Set Fault Analysis mode')#
class spsdk.dat.dm_commands.StartDebugMailbox(dm, paramlen=0, resplen=0, delay=None, response_delay=None)#

Bases: DebugMailboxCommand

Debug mailbox command for starting debug session.

This command initiates the debug mailbox communication protocol, enabling debug operations on the target device.

Variables:

CMD – Command identifier for start debug mailbox operation.

Initialize Debug Mailbox command.

Sets up the command with the specified debug mailbox instance and configuration parameters for command execution timing and data lengths.

Parameters:

  • dm (DebugMailbox) – Debug mailbox instance for command execution.

  • paramlen (int) – Length of command parameters in bytes, defaults to 0.

  • resplen (int) – Expected length of response data in bytes, defaults to 0.

  • delay (Optional[float]) – Custom delay before command execution in seconds, uses default if None.

  • response_delay (Optional[float]) – Custom delay after command execution in seconds, optional.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (1, 'START', 'Start Debug Mailbox')#
class spsdk.dat.dm_commands.StartDebugSession(dm, paramlen=0, resplen=0, delay=None, response_delay=None)#

Bases: DebugMailboxCommand

Debug mailbox command for starting a debug session.

This command initiates a debug session through the debug mailbox interface, allowing debugger tools to establish communication with the target device.

Variables:

CMD – Command identifier for start debug session operation.

Initialize Debug Mailbox command.

Sets up the command with the specified debug mailbox instance and configuration parameters for command execution timing and data lengths.

Parameters:

  • dm (DebugMailbox) – Debug mailbox instance for command execution.

  • paramlen (int) – Length of command parameters in bytes, defaults to 0.

  • resplen (int) – Expected length of response data in bytes, defaults to 0.

  • delay (Optional[float]) – Custom delay before command execution in seconds, uses default if None.

  • response_delay (Optional[float]) – Custom delay after command execution in seconds, optional.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (7, 'START_DBG_SESSION', 'Start Debug Session')#
class spsdk.dat.dm_commands.WriteToFlash(dm)#

Bases: DebugMailboxCommand

Debug Mailbox command for writing data to flash memory.

This command handles the write-to-flash operation through the debug mailbox interface, allowing data to be programmed into the target device’s flash memory during debug or provisioning operations.

Variables:

CMD – Command identifier for write-to-flash operation.

Initialize the debug mailbox command.

Parameters:

dm (DebugMailbox) – Debug mailbox instance to be used for command execution.

CMD: Union[DebugMailboxCommandID, DebugMailboxCommandID2] = (9, 'WRITE_TO_FLASH', 'Write data to Flash memory')#
Contents