i.MXRT118x Debug Authentication example#

I.MX RT118x offers the Debug Authentication Protocol (DAP) as a mechanism to authenticate the debugger (an external entity) which has the credentials approved by the product manufacturer before granting the debug access to the device. This example demonstrates process how to establish Debug Authentication protocol.

The process could be split into following steps:

Introduction#

The fundamental principles of debugging, which require access to the system state and system information, conflict with the principles of security, which require the restriction of access to assets. Thus, many products disable debug access completely before deploying the product. To address these challenges, the chip offers a debug authentication protocol as a mechanism to authenticate the debugger (an external entity) has the credentials approved by the product manufacturer before granting debug access to the device. The debug authentication is a challenge-response scheme and assures that only the debugger in possession of the required debug credentials can successfully authenticate over the debug interface and access restricted parts of the device.

The protocol is divided into steps as described below:

The debugger initiates the Debug Mailbox message exchange by setting the CSW[RESYNCH_REQ] bit and CSW[CHIP_RESET_REQ] bit of DM-AP.
The debugger waits (minimum 30 ms) for the devices to restart and enter debug mailbox request handling loop.
The debugger sends Debug Authentication Start command (command code 10h) to the device.
The device responds back with Debug Authentication Challenge (DAC) packet based on the debug access rights preconfigured in CMPA fields, which are collectively referred as Device Credential Constraints Configuration (DCFG_CC). The response packet also contains a 32 bytes random challenge vector.
The debugger responds to the challenge with a Debug Authentication Response (DAR) message by using an appropriate debug certificate, matching the device identifier in the DAC. The DAR packet contains the debug access permission certificate, also referred as Debug Credential (DC), and a cryptographic signature binding the DC and the challenge vector provided in the DAC.
The device on receiving the DAR, validates the contents by verifying the cryptographic signature of the message using the debugger’s public key present in the embedded the Debug Credential (DC). On successful validation of DAR, the device enables access to the debug domains permitted in the DC

debug_authentication_flow

Prepare the Environment#

%run ../init_notebook.ipynb

import os
import pprint

pp = pprint.PrettyPrinter(indent=4)

WORKSPACE = "workspace/"  # change this to path to your workspace
INPUTS = "inputs/"
VERBOSITY = (
    "-v"  # verbosity of commands, might be -v or -vv for debug or blank for no additional info
)

DCK_KEY_PRIV = "../_data/keys/ecc256/dck_ecc256.pem"  # Private DCK key

DBGMAILBOX_TEMPLATE = (
    WORKSPACE + "nxpdebugmbox_template.yaml"
)  # Template for debug mailbox configuration
DBGMAILBOX_CONFIG = (
    INPUTS + "nxpdebugmbox_rt118x.yaml"
)  # yaml file with configuration used in this example

# DEBUGGER_PROBE = "pyocd" #onboard debugger on EVK-RT118x rev C
DEBUGGER_PROBE = "jlink"
# Only one probe can be connected to the board.

env: JUPYTER_SPSDK=1
Created `%!` as an alias for `%execute`.

EVK Board Overview#

The following picture describes connector placement of RT1180 EVK. Signing key and used SRK definition

The Enablement process could be split into following steps:

1. Generate Keys#

The AHAB is using asymmetric algorithm for image authentication which requires keys generated according to PKI for operation. One of the generated private key must be also used to sing Debug Credential file. Another key pair which must be generated for this example is Debug credential keys (DCKPriv/Pub). The example uses pre-generated ECC-256 SRK and DCK keys. To generate your own keys please refer to How-to-get-keys-using-nxpcrypto example.

2. The template file must be updated to implement desired functionality and add reference to specific keys.#

# Generate template
%! nxpdebugmbox get-template -f rt118x --force -o $DBGMAILBOX_TEMPLATE

nxpdebugmbox get-template -f rt118x --force -o workspace/nxpdebugmbox_template.yaml 
The configuration template file has been created: workspace/nxpdebugmbox_template.yaml

This yaml file must be used to generate Debug Credential file. The OEM is must do it as posses the RoT private keys. Field technician must provide his DCK public key to OEM. The resulting yaml file is available in the “inputs” folder. The figures below illustrates which entries were changed.

I. The template file uses zeroized UUID. To create a debug credential file for specific par run the “get-uuid” command listed below and replace to zeros at the UUID field by the UUID value returned by the command in the yaml file. Vendor usage and cc beacon is not demonstrated in this example.

Key modification

Connect J-link probe into the connector. To read UUID the following command has to be activated (# must be removed).

# Check the nxp debug mailbox tool
# %! nxpdebugmbox -i $DEBUGGER_PROBE get-uuid

II. Keys must be modified in the file. This example uses pregenerated keys. To Generate custom key, please refer to the example: How-to-get-keys-using-nxpcrypto. Reference to RoT public keys, Signing RoT private key (index 1), and DCK public key must be modified in the template file.