.. SPDX-FileCopyrightText: <text>Copyright 2021,2022,2024,2025 Arm Limited and/or its affiliates open-source-office@arm.com</text> SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This file is part of PAF, the Physical Attack Framework.

|BadgeLicence| |CIUbuntu2204| |CIUbuntu2404| |CImacOS14| |CImacOS15|

.. |BadgeLicence| image:: https://img.shields.io/github/license/ARM-software/PAF :alt: PAF licence :target: https://github.com/ARM-software/PAF/blob/main/LICENSE.txt

.. |CIUbuntu2204| image:: https://github.com/ARM-software/PAF/actions/workflows/ubuntu-2204.yml/badge.svg :alt: Last build status on Ubuntu 22.04 (x86 & arm architectures) :target: https://github.com/ARM-software/PAF/actions/workflows/ubuntu-2204.yml

.. |CIUbuntu2404| image:: https://github.com/ARM-software/PAF/actions/workflows/ubuntu-2404.yml/badge.svg :alt: Last build status on Ubuntu 24.04 (x86 & arm architectures) :target: https://github.com/ARM-software/PAF/actions/workflows/ubuntu-2404.yml

.. |CImacOS14| image:: https://github.com/ARM-software/PAF/actions/workflows/macos-14.yml/badge.svg :alt: Last build status on macOS Sonoma (arm architecture) :target: https://github.com/ARM-software/PAF/actions/workflows/macos-14.yml

.. |CImacOS15| image:: https://github.com/ARM-software/PAF/actions/workflows/macos-15.yml/badge.svg :alt: Last build status on macOS Sequoia (arm architecture) :target: https://github.com/ARM-software/PAF/actions/workflows/macos-15.yml

=============================================================================== PAF, the Physical Attack Framework

Welcome to PAF ! PAF is a suite of tools and libraries to learn about physical attacks, such as fault injection and side channels, and hopefully help harden code bases against those threats.

Requirements

To build PAF from source, you will need a C++ compiler compatible with C++17, and CMake <https://cmake.org/>_.

A significant number of the PAF tools assumes that you at least have access to Tarmac traces. These are detailed traces of a program's execution, and they are generated by a number of Arm products, like software models of CPUs (e.g. FastModel).

PAF has the capability to directly drive a FastModel and perform a number of analysis. In order to use this capability, you will need to have access to a FastModel <https://developer.arm.com/tools-and-software/simulation-models/fast-models>_

Building

The simplest way to build PAF is:

.. code-block:: bash

$ cmake -S . -B build $ cmake --build build

A slightly more evolved way of building and testing PAF, in release mode with debug info, using the clang compiler, Ninja build system and producing a compile_commands.json file looks like:

.. code-block:: bash

$ CC=clang CXX=clang++ cmake -S . -B build -G Ninja
-DCMAKE_BUILD_TYPE:STRING=RelWithDebInfo
-DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=ON $ ln -s build/compile_commands.json . $ ninja -C build/ $ ninja -C build/ check

Testing

PAF contains both unit testing and application level testing. Unit testing can be performed using the test target, with no external dependencies. Application level testing is a different story as it requires access to a cross-compiler and a FastModel. If you have access to those, CMake can setup a test environment for you with:

.. code-block:: bash

$ CC=clang CXX=clang++ cmake -S . -B build -G Ninja
-DCMAKE_BUILD_TYPE:STRING=RelWithDebInfo
-DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=ON
-DFVP_MODEL_DIR:PATH=/opt/FastModels/11.12/FVP_MPS2_Cortex-M3_CC312/models/Linux64_GCC-6.4/FVP_MPS2_Cortex-M3_CC312
-DFVP_PLUGINS_DIR:PATH=/opt/FastModels/11.12/FastModelsPortfolio_11.12/plugins/Linux64_GCC-6.4
-DARM_GCC_INSTALL_DIR:PATH=/opt/gcc-arm-none-eabi-10-2020-q4-major

Usage and documentation

For more information on PAF, the tools it provides and how to use them, see the main documentation <doc/index.rst>_.

License

PAF is distributed under the Apache v2.0 License <http://www.apache.org/licenses/LICENSE-2.0>_.

Third party software

PAF uses third party software that is not included in PAF's source code repository. PAF's configure and build system, CMake, will automatically download, configure and build this third party software. As each of those third party software comes with its own specific license, you have to check their licenses comply with your own specific requirements.

The third party software required by PAF is:

• tarmac-trace-utilities <https://github.com/ARM-software/tarmac-trace-utilities>_, licensed under https://github.com/ARM-software/tarmac-trace-utilities/blob/main/LICENSE.txt, is the library that provides PAF with the fondations for efficiently manipulating tarmac traces.

• pyyaml <https://pypi.org/project/PyYAML/>, and pyelftools <https://pypi.org/project/pyelftools/>, and tqdm <https://pypi.org/project/tqdm/>_ are used by run-model.py and ancillary tools.

• GoogleTest <https://github.com/google/googletest>_, licensed under https://github.com/google/googletest/blob/main/LICENSE, is the unit testing framework used by PAF.

• numpy <https://numpy.org/>_, licensed under https://github.com/numpy/numpy/blob/main/LICENSE.txt, is used by some unit tests.

Other third party software that can optionally be used by PAF with PAF's configure and build system:

• GTKWave <https://github.com/gtkwave/gtkwave>_ : PAF uses the fstapi to have support for fst files, as shipped by GTKWave in the src/helpers/fst folder. Quoting GTKWave's LICENSE.txt file::

  the dumpfile processing source code in src/helpers is licensed under the MIT license in order to facilitate greater re-use.

  The default is for CMake to use the fstapi. This can however be disabled by passing at configure time -DWITH_GTKWAVE_FST_SUPPORT:BOOL=OFF to drop fst file format support.

Security

To report security vulnerabilities in this project, follow the guidance in the security policy <SECURITY.rst>_.

Feedback, contributions and support

Please use the GitHub issue tracker associated with this repository for feedback.

Code contributions are most welcomed. Please make sure they stick to the style used in the rest of the PAF code and submit them via GitHub pull requests.