readme.rst - shared/psa-adac - TrustedFirmware Git Browser

 ##################################
 Authenticated Debug Access Control
 ##################################

 ************
 Introduction
 ************

 Introducing security in debug is about making sure that only authorized people
 have access to select parts of firmware and hardware. The Trusted Firmware-M
 software implementation contained in this project is designed to be a
 reference implementation.

 ADAC aims at making sure that debug capabilities do not become attack vectors.
 Debug security cannot be an afterthought when designing an SoC and the kind of
 debug solution needed is driven by the threat models for the device use case.

 The ADAC architecture is designed to be flexible to meet varying vendor needs,
 adaptable to work with many different hardware and software components, and
 scalable from small embedded or IoT systems to complex server environments.
 At the same time, it strives to be simple and resilient against attack.

 `Authenticated Debug Access Control`_ (ADAC).

 **********
 Components
 **********

 The repository contains software componenets, of the ADAC protocol, towards
 the target side. The following components are included in this repo:

 * Secure Debug Authenticator (SDA)
 * ADAC protocol core
 * Supported target platforms
     * trusted-firmware-m: dipdha platform
 * Transport layer
     * `SDC-600 Secure Debug Channel`_

 ********************
 Directory structures
 ********************

 - psa-adac
     - core
     - sda
 - target
     - target name
         - files implementing platform interface of psa-adac/core and psa-adac/sda
         - psa_adac_platform.h: place where platform specific incoming and outgoing calls can be declared
 - transport
     - files implementing transport interface of psa-adac/core and psa-adac/sda
     - various implementations of transport layer for communication with the host can be hosted here
 - template_hal_files
     - template files for hal api definitions


 ************************
 Integration instructions
 ************************

 Build options
 =============

 Build from the adac repository
 ----------------------------------

 Configure:

 .. code-block::

     cmake -B <build_dir> -S . -DCMAKE_BUILD_TYPE=Debug -DPSA_ADAC_TARGET=<target_name> -DPSA_ADAC_MBEDTLS_INCLUDE=<path to mbedtls include>

 Build and install:

 .. code-block::

     cmake --build <build_dir> -- install

 Static library will be installation at:

 .. code-block::

     <build_dir>/install/lib/lib_<target_name>.a

 Build as cmake target
 ---------------------

 .. code-block::

     add_subdirectory(${PLATFORM_PSA_ADAC_SOURCE_PATH} ${PLATFORM_PSA_ADAC_BUILD_PATH})
     target_link_libraries(<target_name>-psa-adac
         PRIVATE
             <caller of adac entry point>
     )

 Configuration variables
 =======================

 PSA_ADAC_TOOLCHAIN
 ------------------
 When OFF, the build will not include toolchain files from the
 adac repository. User can decide to choose the toolchain configuration from the
 adac repository or can also provide its own toolchain configuration files.

 PSA_ADAC_TARGET
 ---------------
 Name of the target. Support for the target should exist inside
 the ./target/ directory.

 PSA_ADAC_MBEDTLS_INCLUDE
 ------------------------
 Path to mbedtls include directory (`MBEDTLS Repository`_)

 .. code-block::

     <mbedtls>/include


 HAL integration
 ===============

 psa-adac/sda and psa-adac/core depends on the following inteface:

 platform.h
 ----------
 Defines the interface to the platform. A template file for the inteface
 can be found inside template directory.

 psa_adac_crypto_api.h
 ---------------------
 Defines the interface to the cryptographic supported required
 by the adac protocol implementation.

 A target should provide the implementation of these HAL APIs. An example for platform.h
 api implementation can be find inside corstone1000 target directory. And example for
 crypto api implementaion can be find inside `Trusted-Firmware-M`_ repository. Further
 such integration of crypto apis, based on software (ex: mbedtls) as well as based on
 hardware accelerattion, can also be hosted as part of this repository.

 msg_interface.h
 ---------------
 Defines the interface to the transport layer. The transport layer supports the communication
 between host and the target. The file, msg_interface.h, only contains the interface used
 by the target, i.e. psa-adac/core and psa-adac/sda. Various implementation of transport
 layer can be hosted inside ./trasport/ directory. For ex: corstone1000 uses transport based
 on SDC600 COMPORT.

 Integration to the secure debug workflow
 ========================================

 The entry function definition to start the secure debug flow and any other dependency,
 a target is free to declare such apis inside the file: psa_adac_platform.h

 Corstone1000 psa_adac_platform.h is one such example.


 Target examples
 ===============

 Build instructions for Corstone1000 platform inside trusted-firmware-m
 ----------------------------------------------------------------------

 Configure:

 .. code-block::

     cmake -B <build_dir> -S . -DCMAKE_BUILD_TYPE=Debug -DPSA_ADAC_TARGET=trusted-firmware-m -DTFM_PLATFORM=arm/corstone1000 -DPSA_ADAC_MBEDTLS_INCLUDE=<mbedtls>/include

 Build and install:

 .. code-block::

     cmake --build <build_dir> -- install

 Build library:

 .. code-block::

     build/install/lib/libtrusted-firmware-m-psa-adac.a

 The library generated contains secure debug support for Corstone1000 platform
 which can be linked to Corstone1000's trusted-firmware-m build.

 .. _Authenticated Debug Access Control: https://developer.arm.com/documentation/den0101/latest
 .. _SDC-600 Secure Debug Channel: https://www.arm.com/products/silicon-ip-system/coresight-debug-trace/sdc-600
 .. _MBEDTLS Repository: https://github.com/ARMmbed/mbedtls.git
 .. _Trusted-Firmware-M : https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/

 *Copyright (c) 2021, Arm Limited. All rights reserved.*
	##################################
	Authenticated Debug Access Control
	##################################

	************
	Introduction
	************

	Introducing security in debug is about making sure that only authorized people
	have access to select parts of firmware and hardware. The Trusted Firmware-M
	software implementation contained in this project is designed to be a
	reference implementation.

	ADAC aims at making sure that debug capabilities do not become attack vectors.
	Debug security cannot be an afterthought when designing an SoC and the kind of
	debug solution needed is driven by the threat models for the device use case.

	The ADAC architecture is designed to be flexible to meet varying vendor needs,
	adaptable to work with many different hardware and software components, and
	scalable from small embedded or IoT systems to complex server environments.
	At the same time, it strives to be simple and resilient against attack.

	`Authenticated Debug Access Control`_ (ADAC).

	**********
	Components
	**********

	The repository contains software componenets, of the ADAC protocol, towards
	the target side. The following components are included in this repo:

	* Secure Debug Authenticator (SDA)
	* ADAC protocol core
	* Supported target platforms
	* trusted-firmware-m: dipdha platform
	* Transport layer
	* `SDC-600 Secure Debug Channel`_

	********************
	Directory structures
	********************

	- psa-adac
	- core
	- sda
	- target
	- target name
	- files implementing platform interface of psa-adac/core and psa-adac/sda
	- psa_adac_platform.h: place where platform specific incoming and outgoing calls can be declared
	- transport
	- files implementing transport interface of psa-adac/core and psa-adac/sda
	- various implementations of transport layer for communication with the host can be hosted here
	- template_hal_files
	- template files for hal api definitions


	************************
	Integration instructions
	************************

	Build options
	=============

	Build from the adac repository
	----------------------------------

	Configure:

	.. code-block::

	cmake -B <build_dir> -S . -DCMAKE_BUILD_TYPE=Debug -DPSA_ADAC_TARGET=<target_name> -DPSA_ADAC_MBEDTLS_INCLUDE=<path to mbedtls include>

	Build and install:

	.. code-block::

	cmake --build <build_dir> -- install

	Static library will be installation at:

	.. code-block::

	<build_dir>/install/lib/lib_<target_name>.a

	Build as cmake target
	---------------------

	.. code-block::

	add_subdirectory(${PLATFORM_PSA_ADAC_SOURCE_PATH} ${PLATFORM_PSA_ADAC_BUILD_PATH})
	target_link_libraries(<target_name>-psa-adac
	PRIVATE
	<caller of adac entry point>
	)

	Configuration variables
	=======================

	PSA_ADAC_TOOLCHAIN
	------------------
	When OFF, the build will not include toolchain files from the
	adac repository. User can decide to choose the toolchain configuration from the
	adac repository or can also provide its own toolchain configuration files.

	PSA_ADAC_TARGET
	---------------
	Name of the target. Support for the target should exist inside
	the ./target/ directory.

	PSA_ADAC_MBEDTLS_INCLUDE
	------------------------
	Path to mbedtls include directory (`MBEDTLS Repository`_)

	.. code-block::

	<mbedtls>/include


	HAL integration
	===============

	psa-adac/sda and psa-adac/core depends on the following inteface:

	platform.h
	----------
	Defines the interface to the platform. A template file for the inteface
	can be found inside template directory.

	psa_adac_crypto_api.h
	---------------------
	Defines the interface to the cryptographic supported required
	by the adac protocol implementation.

	A target should provide the implementation of these HAL APIs. An example for platform.h
	api implementation can be find inside corstone1000 target directory. And example for
	crypto api implementaion can be find inside `Trusted-Firmware-M`_ repository. Further
	such integration of crypto apis, based on software (ex: mbedtls) as well as based on
	hardware accelerattion, can also be hosted as part of this repository.

	msg_interface.h
	---------------
	Defines the interface to the transport layer. The transport layer supports the communication
	between host and the target. The file, msg_interface.h, only contains the interface used
	by the target, i.e. psa-adac/core and psa-adac/sda. Various implementation of transport
	layer can be hosted inside ./trasport/ directory. For ex: corstone1000 uses transport based
	on SDC600 COMPORT.

	Integration to the secure debug workflow
	========================================

	The entry function definition to start the secure debug flow and any other dependency,
	a target is free to declare such apis inside the file: psa_adac_platform.h

	Corstone1000 psa_adac_platform.h is one such example.


	Target examples
	===============

	Build instructions for Corstone1000 platform inside trusted-firmware-m
	----------------------------------------------------------------------

	Configure:

	.. code-block::

	cmake -B <build_dir> -S . -DCMAKE_BUILD_TYPE=Debug -DPSA_ADAC_TARGET=trusted-firmware-m -DTFM_PLATFORM=arm/corstone1000 -DPSA_ADAC_MBEDTLS_INCLUDE=<mbedtls>/include

	Build and install:

	.. code-block::

	cmake --build <build_dir> -- install

	Build library:

	.. code-block::

	build/install/lib/libtrusted-firmware-m-psa-adac.a

	The library generated contains secure debug support for Corstone1000 platform
	which can be linked to Corstone1000's trusted-firmware-m build.

	.. _Authenticated Debug Access Control: https://developer.arm.com/documentation/den0101/latest
	.. _SDC-600 Secure Debug Channel: https://www.arm.com/products/silicon-ip-system/coresight-debug-trace/sdc-600
	.. _MBEDTLS Repository: https://github.com/ARMmbed/mbedtls.git
	.. _Trusted-Firmware-M : https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/

	Copyright (c) 2021, Arm Limited. All rights reserved.