1#########################################
2ADAC (Authenticated Debug Access Control)
3#########################################
4
5************
6Introduction
7************
8
9Background
10==========
11In order to make sure debug capabilities of any system do not become attack
12vectors, PSA provides reference ADAC system architecture. It specifies
13functional layers that reside above actual physical link.
14
15Authenticated Debug Access Control (ADAC), also referred to as Secure Debug, is
16a protocol that provides a way to use strong authentication to restrict device
17debug access to only authorized entities. Across various life cycle states of
18target device, it permits appropriate access to finely configured domains.
19
20Requirements
21============
22Debug capabilities must achieve several safety goals to be fully resilient.
23It requires
24
251. Strong authentication
262. Finely grained hardware and firmware domains
273. Enforcing debug limitations
28
29ADAC protocol is fully flexible to meet the above goals.  But depending on the
30system design and topology, it must be implemented so to meet varying attack
31surface.
32
33ADAC Components (Host Side)
34===========================
35
36- ``Secure Debug Manager (SDM)``:  SDM is the host side component adac protocol
37  implementation. Its API is implemented in below external github repository.
38
39  ``git@github.com:ARM-software/sdm-api.git``.
40
41An example implementation for SDM library is in below external github repository.
42
43  ``git@github.com:ARM-software/secure-debug-manager.git``.
44
45ADAC Components (Target Side)
46=============================
47
48- ``Secure Debug Authenticator (SDA)``:  SDA is the target side component that
49  implements ADAC protocol. It is implemented in below external repository.
50  It authenticates all input credentials and applies specific debug permissions.
51
52  ``https://git.trustedfirmware.org/shared/psa-adac.git``.
53
54SDA integration
55===============
56
57The above mentioned SDA repository includes required HAL updates for a few
58supported platforms along with transport layer protocol. Hence, the API to
59initiate the connection with the host debugger and to perform
60the authentication process is platform-specific.
61
62For example for musca b1 platform, the API to integrate is:
63
64- ``tfm_to_psa_adac_musca_b1_secure_debug()``
65
66Once the device is Secured, opening up the debug ports poses a risk to
67active confidential production secrets. So on debug request, a system reset is
68required, and most of the time, SDA code is expected to reside in the
69boot loader (BL2) or equivalent.
70
71However RSE platform has some implemenentation constraints due to which SDA is
72integrated in runtime service.
73For more details, please refer to the Implementation Constraints section in the
74:doc:`ADAC Implementation for RSE <TF-M-Extras:partitions/adac_impl_for_rse>`
75
76Please follow the below link for further information on SDA implementation.
77
78| `psa-adac read me`_
79
80.. _psa-adac read me:
81  https://developer.arm.com/documentation/den0101/latest
82
83*********
84Reference
85*********
86
87| `ADAC specification`_
88
89.. _ADAC specification:
90  https://developer.arm.com/documentation/den0101/latest
91
92--------------
93
94*Copyright (c) 2022-2024, Arm Limited. All rights reserved.*
95