Sei sulla pagina 1di 18
Qualcomm Technologies, Inc. Sectools: Debug Policy Tool User Guide 80-NM248-6 F March 27, 2017 Confidential

Qualcomm Technologies, Inc.

Qualcomm Technologies, Inc. Sectools: Debug Policy Tool User Guide 80-NM248-6 F March 27, 2017 Confidential and
Qualcomm Technologies, Inc. Sectools: Debug Policy Tool User Guide 80-NM248-6 F March 27, 2017 Confidential and

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:

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.

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

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

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.

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.

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
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

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?
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

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)

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

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.

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

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 QSEE secure regions; serial numbers are not required

24

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.

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.

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.

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

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

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