1 2# PSA Secure Debug: Arm ADAC Test Suite 3 4## Introduction 5 6### ADAC Specification 7 8The [ADAC specification](https://developer.arm.com/documentation/den0101/0001) defines the protocol that allows a target to securely authenticate a debug host. The specification targets software-only layers that are above the physical debug link. 9 10### ADAC test suite 11 12The ADAC test suite checks if a device-side implementation conforms to the behavior described in the ADAC specification. The tests: 13 - Are self-checking and portable, written in C with directed stimulus. 14 - Are expected to run on the host platform only. 15 - Drive the commands from the host platform through the debug link and verify the response obtained from the target platform. 16 - Are available as open source. 17 - And the corresponding abstraction layers are available with an Apache v2.0 license allowing for external contribution. 18 19## Release details 20 - Release Version - 0.8 21 - Code Quality: Beta <br/> 22 23 - The ADAC tests are written for version beta of the ADAC specification. 24 - This test suite is not a substitute for design verification. 25 26## Layers 27 28ADAC tests use a layered software-stack approach to enable porting across different test platforms. The constituents of the layered stack are: 29 - Test suite 30 - Validation Abstraction Layer (VAL) 31 - Platform Abstraction Layer (PAL) 32 33These tests are written on top of VAL and PAL. 34 35The abstraction layers provide platform information and runtime environment to enable execution of the tests. 36 37In this release, PAL implementation for the 'emulation' target uses Unix sockets as the link layer to send commands and receive responses. Arm also provides support for executing the test suite on the 'Musca-b1' hardware board by adding a 'musca_b1' target which uses memory window protocol as the link layer. 38 39You can also write your own abstraction layer implementations to allow ADAC tests to run on other host platforms and support the debug link layer. 40 41## Scenarios 42 43The mapping of the rules to the test cases and the steps followed in the tests are mentioned in the [Scenario document](docs/psa_adac_scenarios.md) present in the docs/ folder. 44 45## Getting started 46 47 48Follow the instructions in the subsequent sections to get a copy of the source code on your local machine and build the tests. <br/> 49See [Arm Authenticated Debug Access Control Test Suite User guide](docs/Arm_Authenticated_Debug_Access_Control_Test_Suite_User_Guide.pdf) to get details on the steps involved in porting the test suite to your platform. 50This test suite is provided as a separate directory within the psa-arch-tests repository. 51 52### Prerequisites 53 54Before starting the test suite build, ensure that the following requirements are met: 55 56- Host Operating System: Ubuntu 16.04.4, RHEL 7, Windows 10 57- Scripting tools: Python 3.7.1 58- Other open-source tools: GNUARM 6.3.1, GCC 5.4.0 32-Bit (Linux Host), MinGW 6.3.0 32-Bit (Windows Host) 59 CMake 3.10 or later 60 61 62## Download source 63To download the main branch of the repository, type the following command: 64 65 git clone https://github.com/ARM-software/psa-arch-tests.git 66 67To download the main branch of the psa-adac repository, navigate to the secure debug directory and type the following command: 68 69 git clone git@github.com:ARMmbed/psa-adac.git 70 71Note: 72 To receive access to the psa-adac repository and some of its dependent submodules, Arm licensees may contact Arm through their partner managers. 73 74 75## Porting steps 76 77See the [Porting Guide](docs/porting_guide_adac_host.md) for porting steps for your host platform. 78See the [User Guide](docs/Arm_Authenticated_Debug_Access_Control_Test_Suite_User_Guide.pdf) in the docs/ folder for additional details. 79 80## Build steps 81 82To build ADAC test suite for a given host platform, execute the following commands: <br/> 83~~~ 84 cd psa-arch-tests/secure-debug 85 git clone git@github.com:ARMmbed/psa-adac.git --recurse-submodules 86 cp psa_adac_ats.patch psa-adac/. 87 cd psa-adac/ 88 git apply psa_adac_ats.patch 89 cd .. 90 mkdir <host_build_dir> 91 cd <host_build_dir> 92 cmake ../ -G<generator-name> -DTARGET=<target-name> -DSUITE=<suite-selection> -DLINK_LAYER_COMM=<link-layer> 93 where: 94 - <generator-name> "Unix Makefiles" - to generate Makefiles for Linux and Cygwin 95 "MinGW Makefiles" - to generate Makefiles for cmd.exe on Windows 96 - <target-name> target to build, as created in the platform/hosts directory 97 - <suite-selection> ADAC - specify the ADAC suite 98 - <link-layer> link layer for the host platform, optional for emulation target 99 100 To build project 101 cmake --build . 102 To clean 103 cmake --build . -- clean 104~~~ 105 106Note: 107 Arm recommends running different build configurations in separate directories. Refer to the host-platform specific README for information on additional build options. 108 109### Build output 110 111The following ADAC test suite build outputs are available under host build directory, as created. 112 113 - psa_adac_test executable 114 - val and platform layer libraries 115 116For running the test suite on the emulation platform, see the [Readme](platform/hosts/emulation/unix_socket/README.md).<br/> 117For running the test suite on the Musca-b1 hardware platform, see the [Readme](platform/hosts/musca_b1/memw_pyocd/README.md).<br/> 118 119Note: 120 - See the psa-adac directory for information on other target platforms. 121 - The keys and the certificate credentials for a supported cryptosystem can be generated using the tools provided in the psa-adac repository. 122 - The test suite is designed to run once per supported cryptosystem. Ensure that the device must be provisioned with the correct certificates installed in the device's RoT. 123 124## Security implication 125 126ADAC test suite may run at higher privilege level. An attacker can utilize these tests to elevate privilege which can potentially reveal the platform Secure attests. To prevent such security vulnerabilities into the production system, it is recommended that ADAC test suite is run on development platforms. If it is run on production system, make sure system is scrubbed after running the test suite. 127 128## License 129 130Arm ADAC Architecture test suite is distributed under Apache v2.0 license. 131The psa-adac code repository is distributed under BSD-3-Clause license. 132 133## Feedback, contributions, and support 134 135 - For feedback, use the GitHub Issue Tracker that is associated with this repository. 136 - For support, send an email to support-psa-arch-tests@arm.com with details. 137 - Arm licensees can contact Arm directly through their partner managers. 138 - Arm welcomes code contributions through GitHub pull requests. 139 140-------------- 141 142*Copyright (c) 2021-2022, Arm Limited and Contributors. All rights reserved.* 143
