Qualcomm Technologies, Inc.

Sectools: Debug Policy Tool

User Guide
80-NM248-6 F
March 27, 2017

Confidential and Proprietary – Qualcomm Technologies, Inc.

NO PUBLIC DISCLOSURE PERMITTED: Please report postings of this document on public servers or websites to:
DocCtrlAgent@qualcomm.com.
Restricted Distribution: Not to be distributed to anyone who is not an employee of either Qualcomm Technologies, Inc. or its
affiliated companies without the express approval of Qualcomm Configuration Management.
Not to be used, copied, reproduced, or modified in whole or in part, nor its contents revealed in any manner to others without the
express written permission of Qualcomm Technologies, Inc.
Qualcomm and MSM are trademarks of Qualcomm Incorporated, registered in the United States and other countries. Other product
and brand names may be trademarks or registered trademarks of their respective owners.
This technical data may be subject to U.S. and international export, re-export, or transfer (“export”) laws. Diversion contrary to U.S.
and international law is strictly prohibited.

Qualcomm Technologies, Inc.

5775 Morehouse Drive
San Diego, CA 92121
U.S.A.

© 2014–2017 Qualcomm Technologies, Inc. All rights reserved.

Revision history

Revision Date Description

A December 2014 Initial release.
B April 2015 Added Revision 2 configuration changes in Section 4.2 (serial number,
flags, and root cert hash).
C June 2015 Added Section 4.4. Updated Section 4.2.
D October 2015 Corrected typing error in Table 4-2.
E May 2016 Updated Sections 2.1, 4.1, 4.2.1, and 4.3.
F March 2017 Added Table 4-2. Updated Sections 2.1, 4.1, 4.2.1, and 4.2.1.6.
Updated Tables 4-3 and 4-4.

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 2

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Contents

1 Introduction...................................................................................................... 5
1.1 Purpose.......................................................................................................................... 5
1.2 Conventions .................................................................................................................. 5
1.3 Technical assistance ...................................................................................................... 5

2 DebugPolicy tool overview ............................................................................. 6

2.1 Key features .................................................................................................................. 6
2.2 System diagram............................................................................................................. 7

3 DebugPolicy tool components ....................................................................... 9

4 Configuration and usage .............................................................................. 10

4.1 Prerequisites ................................................................................................................ 10
4.2 Configurations ............................................................................................................ 10
4.2.1 DebugPolicy configuration file........................................................................ 10
4.2.2 SecImage configuration file ............................................................................. 14
4.3 DebugPolicy tool usage .............................................................................................. 14
4.3.1 Generate a DebugPolicy file and perform self-validation ............................... 15
4.3.2 Validate a DebugPolicy file against config files.............................................. 16
4.3.3 Example commands ......................................................................................... 16
4.4 DebugPolicy file size .................................................................................................. 17

A References..................................................................................................... 18
A.1 Related documents ..................................................................................................... 18
A.2 Acronyms and terms .................................................................................................. 18

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 3

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Sectools: Debug Policy Tool User Guide Contents

Figures
Figure 2-1 DebugPolicy generates debug policy output with preconfigured XMLs ................................... 7
Figure 2-2 DebugPolicy validates debug policy file against given XML .................................................... 8

Tables
Table 4-1 Revision 1 supported flags ........................................................................................................ 12
Table 4-2 Revision 2 supported flags ........................................................................................................ 13
Table 4-3 Revision 3 supported flags ........................................................................................................ 13
Table 4-4 Target revision and ELF signed offset....................................................................................... 17
Table 4-5 DebugPolicy file size formula ................................................................................................... 17

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 4

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
1 Introduction

1.1 Purpose
To enable debugging of commercial secure devices, DebugPolicy file must be applied. The
DebugPolicy tool helps users – both Qualcomm® Technologies, Inc. (QTI) engineers and OEMs
– to easily configure, validate, and generate dp_AP_signed.mbn and/or dp_MSA_signed.mbn to
enable debugging of images on target.

1.2 Conventions
Function declarations, function names, type declarations, attributes, and code samples appear in a
different font, for example, #include.
Code variables appear in angle brackets, for example, <number>.
Shading indicates content that has been added or changed in this revision of the document.

1.3 Technical assistance

For assistance or clarification on information in this document, submit a case to Qualcomm
Technologies, Inc. (QTI) at https://createpoint.qti.qualcomm.com/.
If you do not have access to the CDMATech Support website, register for access or send email to
support.cdmatech@qti.qualcomm.com.

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 5

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
2 DebugPolicy tool overview

The DebugPolicy tool is a standalone tool developed in Python. Its main functionality is
providing the ability to create and sign debug policy images, which is used to enable debugging
on commercial secure devices.

NOTE: MSM8994, MSM8992, and MSM8952 use revision 1, MSM8996 and later uses revision 2 and
MSM8998 and later (chipsets that support Double Signing) use revision 3.

2.1 Key features

The DebugPolicy tool has the following features:
 Configurable Debug Policy data: config file to set fields and flags
 Configurable target dependent data: chipset-specific config file
 ELF wrapped Debug Policy binary
 Signing support of Debug Policy ELF binary
 Config file to specify which certificate to use in signing the AP and MSA Debug Policy ELF
binary
 Support Double Signing (Debug Policy Revision 3). Debug Policy elf file can be signed with
QTI root cert hash and OEM root cert hash.

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 6

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Sectools: Debug Policy Tool User Guide DebugPolicy tool overview

2.2 System diagram

Figure 2-1 illustrates using the DebugPolicy tool to generate DebugPolicy ELF.

sectools

DebugPolicy core cmd line

interface

Data Rule
Model Feeder

debugpolicy.xml Control dp.mbn

secimage.xml Logic (ELF)

CL 1
Generate CL 2 CL 3
dp.mbn

Figure 2-1 DebugPolicy generates debug policy output with preconfigured XMLs

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 7

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Sectools: Debug Policy Tool User Guide DebugPolicy tool overview

Figure 2-2 illustrates using the DebugPolicy tool to validate dp*.mbn against config file.

dp.mbn debugpolicy.xml
secimage.xml
(ELF)

Software Data
Validator Model

Comparator

DebugPolicy core

Valid?

Figure 2-2 DebugPolicy validates debug policy file against given XML

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 8

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
3 DebugPolicy tool components

The DebugPolicy tool includes the following components/folders that are used to generate and
validate debug policy mbn:

<sectools>/
| sectools.py (main tool launcher command interface)
|
| -- config/ (chipset-specific config template directory)
| -- config/<chipset>/ (preconfigured config directory)
| -- config/xsd/ (xsd for config xml)
|
| -- sectools/features/dpc/ (main DebugPolicy core code)
| -- sectools/features/dpc/debugpolicy.py (main DebugPolicy python script)
|
| -- resources/data_prov_assets (assets for signing and encryption)
|
| -- sectools/common/core (infrastrure)
| -- sectools/common/crypto (crypto services)
| -- sectools/common/data_provisioning (data provision)
| -- sectools/common/parsegen (image utilities)
| -- sectools/common/utils (core utilities)

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 9

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
4 Configuration and usage

4.1 Prerequisites
 OpenSSL 1.0.1 for Linux (or later versions); OpenSSL 1.0.1g for Windows is included in the
package
 Python 2.7 (or later version)
 The SecImage tool makes use of the system temporary folder as scratch space to create
intermediate output. Ensure that the tool has permission to write to that directory
 Windows location: %temp% (This is an environment variable.)
 Linux location: /tmp
 A target that supports the DebugPolicy file. Current target support is for MSM8994 and later
 To generate a DebugPolicy elf file that supports double signing, DebugPolicy version 4.x is
required. Current target supports MSM8998, and later chipsets support Double Signing.

4.2 Configurations
Two configuration files, DebugPolicy config file and SecImage config file, are included and
required for each target supported in order to create a debug policy mbn file with the desired
settings for the specified target. The configuration files are chipset-specific and located in the
following directories:
config\<platform>\<platform>_debugpolicy.xml
config\<platform>\<platform>_dbgp_secimage.xml

4.2.1 DebugPolicy configuration file

The following entries are defined in the <platform>_debugpolicy.xml config file for easy
configuration.

<debugpolicy.xml>
| -- revision: number denoting type of config file to use

Revision 1:
| -- serial_number_start: device serial number range start that applies
| -- serial_number_end: device serial number range end that applies
| -- flags: defines set of flag entries
| -- bit_pos: bit position for a flag [0:63]
| -- value: 0 or 1

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 10

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Sectools: Debug Policy Tool User Guide Configuration and usage

| -- image_id_list: defines a set of image id’s applies, array of 32

| -- image_id 1: hex representation of an image ID, 32 bit
| -- root_cert_hash_list: defines a set of root cert hash signatures
| -- root_cert_hash: hash value of a root certificate (256-bit)
| -- elf: configurable ELF parameters for the debug policy
| -- elf_class: 32 or 64 bit
| -- phys_addr: debug policy’s load address in raw partition (hex)

Revision 2:
| -- flags: defines set of flag entries
| -- bit_pos: bit position for a flag [0:63]
| -- value: 0 or 1
| -- image_id_list: defines a set of image id’s applies, array of 32
| -- image_id: hex representation of an image ID, 32 bit
| -- root_cert_hash_list: defines a set of root cert hash signatures
| -- root_cert_hash: hash value of a root certificate (256-bit)
| -- serial_num_list: defines a set of serial numbers
| -- serial_num: hex representation of a serial number, 32 bit
| -- elf: configurable ELF parameters for the debug policy
| -- elf_class: 32 or 64 bit
| -- phys_addr: debug policy’s load address in raw partition (hex)

Revision 3:
| -- flags: defines set of flag entries
| -- bit_pos: bit position for a flag [0:63]
| -- value: 0 or 1
| -- image_id_list: defines a set of image id’s applies, array of 32
| -- image_id: hex representation of an image ID, 32 bit
| -- root_cert_hash_list: defines a set of root cert hash signatures
| -- root_cert_hash: hash value of a root certificate (256-bit)
| -- serial_num_list: defines a set of serial numbers
| -- serial_num: hex representation of a serial number, 32 bit
| -- root_cert_hash_qti_list: defines a set of root cert hash qti signatures
| -- root_cert_hash_qti: hash value of a root certificate (256-bit)
| -- elf: configurable ELF parameters for the debug policy
| -- elf_class: 32 or 64 bit
| -- phys_addr: debug policy’s load address in raw partition (hex)

1
Must be consistent with image ID defined by signer configuration.

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 11

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Sectools: Debug Policy Tool User Guide Configuration and usage

4.2.1.1 Serial number (Revision 1)

For a specific device, the user can use the MSM™ serial number. For a number of devices within
a range of serial numbers, the user can set start and end for the range to allow multiple devices to
be supported.

NOTE: In DebugPolicy v1.0, both the serial_number_start and serial_number_end values must be the
same, as it only supports enabling the debug policy on a single device.

4.2.1.2 Serial number (Revision 2)

For multiple devices, the user can use the MSM serial numbers in the serial_num_list field. The
user can specify up to 200 unique serial numbers in this list field. All of the corresponding
devices will then be supported by the debug policy.

NOTE: The serial_num_list field is a replacement for the serial_number_start and serial_num_end fields
in Revision 1, as Revision 2 accepts a list of specific serial numbers as opposed to a supported
serial number range.

4.2.1.3 Flags
Flags is a 64-bit value, the most significant 16 bits of which is reserved for OEM use.
Supported flags for the revisions are listed in the following tables:
 Revision 1 (Table 4-1)
 Revision 2 (Table 4-2)
 Revision 3 (Table 4-3)

Table 4-1 Revision 1 supported flags

Flag Description Bit

DP_ENABLE_ONLINE_CRASH_DUMPS Enable crash dumps before boot 0

DP_ENABLE_OFFLINE_CRASH_DUMPS Enable crash dumps during boot 1
DP_ENABLE_LOGS Enable QSEE logging 4
OEM Configurable Flags Open bits for OEM to configure for debugging 48–63

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 12

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Sectools: Debug Policy Tool User Guide Configuration and usage

NOTE: The following table was added to this document revision.

Table 4-2 Revision 2 supported flags

Flag Description Bit

DP_ENABLE_ONLINE_CRASH_DUMPS Enable crash dumps before boot 0

DP_ENABLE_OFFLINE_CRASH_DUMPS Enable crash dumps during boot 1
DP_ENABLE_JTAG Enable JTAG 2
DP_ENABLE_LOGS Enable QSEE logging 3
OEM Configurable Flags Open bits for OEM to configure for debugging 48–63

Table 4-3 Revision 3 supported flags

Flag Description Bit

DP_ENABLE_ONLINE_CRASH_DUMPS Enable crash dumps before boot 0

DP_ENABLE_OFFLINE_CRASH_DUMPS Enable crash dumps during boot 1
DP_ENABLE_JTAG Enable JTAG 2
DP_ENABLE_LOGS Enable QSEE logging 3
DP_ENABLE_NONSECURE_CRASH_DUMPS Enable crash dumps of memory other than 24
QSEE secure regions; serial numbers are not
required
OEM Configurable Flags Open bits for OEM to configure for debugging 48–63

4.2.1.4 Image ID
For image ID information, refer to Sectools: SecImage Tool User Guide (80-NM248-1).
If the image list is empty, the debug policy certificate hash is used as the root of trust for all
images. If the image list contains one or more image ID values, the debug policy certificate hash
will only be used to authenticate images with an ID found in the list.

4.2.1.5 Root Cert Hash

If the root_cert_hash list is not empty, the hash value is used as the root of trust for image
authentication instead of OEK_PK_HASH or the ROM root array. If multiple values are present,
they will be tried in sequence until one works.
Revision 2:
The number of Root Cert Hashes supplied in the Root Cert Hash List is limited to 4 hashes.

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 13

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Sectools: Debug Policy Tool User Guide Configuration and usage

4.2.1.6 Root Cert Hash QTI (Revision 3)

Root Cert Hash QTI is internal to the QTI. The Root Cert Hash QTI List should not be modified
by OEMs.
Revision 3:
The number of QTI Root Cert Hashes supplied in the QTI Root Cert Hash List is limited to
4 hashes.

4.2.2 SecImage configuration file

The following entries are defined in the <platform>_dbgp_secimage.xml config file for easy
configuration.

<dbgp_secimage.xml>
| --general_properties:
| -- msm_part: defines JTAG ID used to sign the debug policy file
| -- selected_cert_config: defines the signing certificate for signing

| -- images_list: entries for signing AP and MSA DebugPolicy files

| -- image: defines an image with image format and signing attributes
| -- sign_id: sign id used to identify type of DebugPolicy image
| -- image_type: defines type of image
| -- output_file_name: signed output file name
| -- cert_config 2: signing certificate used to sign the DebugPolicy file

To configure customized certificates, refer to Sectools: SecImage Tool User Guide

(80-NM248-1).

4.3 DebugPolicy tool usage

The supported command line options for the DebugPolicy tool are as follows:

sectools.py debugpolicy
--dbgp_config_path=<DebugPolicy config file>
--platform=<platform>
--input_file=<DebugPolicy ELF>
--secimage_config_path=<secimage config file>
--sign_id=<sign id>
--output_dir=<destination directory>
--generate
--sign
--validate
--rch=<hash>

2
Maps to certs in resources\data_prov_assets\Signing\Local.

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 14

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Sectools: Debug Policy Tool User Guide Configuration and usage

–-version
--help
-d (for debug)

Where:
 <DebugPolicy config file> is the path to the <platform>_debugpolicy.xml config file
which contains DebugPolicy parameters and configuration.
 <platform> is the name of the platform for the set of config files to be used (for example,
8994 as <platform> will use config files from the following default directory:
.\config\8994).
 <DebugPolicy ELF> is the DebugPolicy file path to sign or validate.

 <destination directory> is the directory to save DebugPolicy output file and

DebugPolicy run logs. If it is not set, the default output directory, /debugpolicy_output, will
be used in the directory where the DebugPolicy tool runs.
 dp_AP_signed.mbn, dp_MSA_signed.mbn, and dp_unsigned.mbn will be generated.
 If –d is specified, DebugPolicy will generate the debug files in the /debug directory of the
destination path.
 If –rch=<hash> is provided with validation, root cert hash value is compared for the signed
DebugPolicy file.
 --sign_id=<sign id> is used along with generate, sign, and validate operations.

 --sign_id with –-generate: Generates the signed DebugPolicy file with given input
sign_id.
 --sign_id with –-sign: Signs/Resigns the DebugPolicy file with given input sign_id.

 --sign_id with –-validate: The input DebugPolicy file is validated with given input
sign_id.

4.3.1 Generate a DebugPolicy file and perform self-validation

sectools.py debugpolicy
--platform=<platform>
--generate
--validate

Or, specify each config file:

sectools.py debugpolicy
--dbgp_config_path=config\<platform>\<platform>_debugpolicy.xml
--secimage_config_path=config\<platform>\<platform>_dbgp_secimage.xml
--generate
--validate

The DebugPolicy (ELF) .mbn and DebugPolicy_log.txt can be found at the default output
directory.

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 15

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Sectools: Debug Policy Tool User Guide Configuration and usage

4.3.2 Validate a DebugPolicy file against config files

sectools.py debugpolicy
--platform=<platform>
--input_file=<DebugPolicy file path>
--validate

Or, specify each config file:

sectools.py debugpolicy
--dbgp_config_path=config\<platform>\<platform>_debugpolicy.xml
--secimage_config_path=config\<platform>\<platform>_dbgp_secimage.xml
--input_file=<DebugPolicy file path>
--validate

In the command prompt, the DebugPolicy tool will indicate if the given signed debug policy file
is valid or not; it will also compare against debugpolicy.xml and print config mismatch if any.

4.3.3 Example commands

 To generate dp_ap_signed.mbn and dp_msa_signed.mbn (for example, 8994)

sectools.py debugpolicy –p 8994 –ga

Or, specify each config file:

sectools.py debugpolicy –c config\8994\8994_debugpolicy.xml –e

config\8994\8994_dbgp_secimage.xml –ga

 To validate a DebugPolicy file (for example, 8994)

sectools.py debugpolicy –p 8994 –f c:\build\dp_AP_signed.mbn –a

Or, specify each config file:

sectools.py debugpolicy –c config\8994\8994_debugpolicy.xml –e

config\8994\8994_dbgp_secimage.xml –f c:\build\dp_AP_signed.mbn –a

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 16

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Sectools: Debug Policy Tool User Guide Configuration and usage

4.4 DebugPolicy file size

ELF signed offset for Revision 1, Revision 2, and Revision 3 are shown in Table 4-4.
Debug Policy file size formula are shown in Table 4-5.

Table 4-4 Target revision and ELF signed offset

Target/Chipset Revision ELF signed offset
(Hex bytes)

MSM8952 V1 0x3000
MSM8992 V1 0x3000
MSM8994 V1 0x3000
MSM8996 V2 0x3000
MSM8998 V3 0x3000
SDM660 V3 0x3000
SDM630 V3 0x3000

Table 4-5 DebugPolicy file size formula

Revision DebugPolicy file Signed DebugPolicy file Comments

V1 168 + n * 32 (0xA8 + n *0x20) 0xA8 + n *0x20 + 0x3000 root cert hash count = n
root cert hash size = 32 bytes
V2 960 (0x3C0) 0x3C0 + 0x3000 Fixed
V3 1092 (0x444) 0x444 + 0x3000 Fixed

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 17

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
A References

A.1 Related documents

Title Number

Qualcomm Technologies, Inc.

Sectools: SecImage Tool User Guide 80-NM248-1
MSM8994/MSM8992 Debug Policy 80-NU498-1

A.2 Acronyms and terms

Acronym or term Definition
QSEE Qualcomm Secure Execution Environment

80-NM248-6 F Confidential and Proprietary – Qualcomm Technologies, Inc. 18

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION