From 371a1aab87dbd730f21dbcec330e3a5cd40ff5e9 Mon Sep 17 00:00:00 2001 From: Valerio Setti Date: Tue, 4 Mar 2025 10:14:29 +0100 Subject: [PATCH] psasim: update README file The README file content dates back to the early stages of PSASIM development. Since then a lot of things have changed, so the README file required a complete rewrite. Signed-off-by: Valerio Setti --- tests/psa-client-server/psasim/README.md | 77 +++++++++--------------- 1 file changed, 29 insertions(+), 48 deletions(-) diff --git a/tests/psa-client-server/psasim/README.md b/tests/psa-client-server/psasim/README.md index 1b950d6b1d..db49ae9473 100644 --- a/tests/psa-client-server/psasim/README.md +++ b/tests/psa-client-server/psasim/README.md @@ -1,61 +1,42 @@ # psasim -This tool simulates a PSA Firmware Framework implementation. -It allows you to develop secure partitions and their clients on a desktop computer. -It should be able to run on all systems that support POSIX and System V IPC: -e.g. macOS, Linux, FreeBSD, and perhaps Windows 10 WSL2. +PSASIM holds necessary C source and header files which allows to test Mbed TLS in a "pure crypto client" scenario, i.e `MBEDTLS_PSA_CRYPTO_CLIENT && !MBEDTLS_PSA_CRYPTO_C`. +In practical terms it means that this allow to build PSASIM with Mbed TLS sources and get 2 Linux applications, a client and a server, which are connected through Linux's shared memeory, and in which the client relies on the server to perform all PSA Crypto operations. -Please note that the code in this directory is maintained by the Mbed TLS / PSA Crypto project solely for the purpose of testing the use of Mbed TLS with client/service separation. We do not recommend using this code for any other purpose. In particular: +The goal of PSASIM is _not_ to provide a ready-to-use solution for anyone looking to implement the pure crypto client structure (see [Limitations](#limitations) for details), but to provide an example of TF-PSA-Crypto RPC (Remote Procedure Call) implementation using Mbed TLS. +## Limitations -* This simulator is not intended to pass or demonstrate compliance. -* This code is only intended for simulation and does not have any security goals. It does not isolate services from clients. +In the current implementation: -## Building +- Only Linux PC is supported. +- There can be only 1 client connected to 1 server. +- Shared memory is the only communication medium allowed. Others can be implemented (ex: net sockets), but in terms of simulation speed shared memory proved to be the fastest. +- Server is not secure at all: keys and operation structs are stored on the RAM, so they can easily be dumped. -To build and run the test program make sure you have `make`, `python` and a -C compiler installed and then enter the following commands: +## Testing -```sh -make run -``` +Please refer to `tests/scripts/components-psasim.sh` for guidance on how to build & test PSASIM: -Optionally the `DEBUG=1` command line option can be enabled to increase verbosity: +- `component_test_psasim()`: builds the server and a couple of test clients which are used to evaluate some basic PSA Crypto API commands. +- `component_test_suite_with_psasim()`: builds the server and _all_ the usual test suites (those found under the `/tests/suites/*` folder) which are used by the CI and runs them. A small subset of test suites (`test_suite_constant_time_hmac`,`test_suite_lmots`,`test_suite_lms`) are being skipped, for CI turnover time optimization. They can be run locally if required. -```sh -make DEBUG=1 run -``` +## How to update automatically generated files -Once done with the test, it is possible to clean all the generated files with: +A significant portion of the intermediate code of PSASIM is auto-generated using Perl. In particular: -```sh -make clean -``` +- `psa_sim_serialise.[c|h]`: + - Generated by `psa_sim_serialise.pl`. + - These files provide the serialisation/deserialisation support that is required to pass functions' parameters between client and server. +- `psa_sim_crypto_[client|server].c` and `psa_functions_codes.h`: + - Generated by `psa_sim_generate.pl`. + - `psa_sim_crypto_[client|server].c` provide interfaces for PSA Crypto APIs on client and server sides, while `psa_functions_codes.h` simply enumerates all PSA Crypto APIs. -## Features +These files need to be regenerated whenever some PSA Crypto API is added/deleted/modified. The procedure is as follows: -The implemented API is intended to be compliant with PSA-FF 1.0.0 with the exception of a couple of things that are a work in progress: - -* `psa_notify` support -* "strict" policy in manifest - -The only supported "interrupts" are POSIX signals, which act -as a "virtual interrupt". - -The standard PSA RoT APIs are not included (e.g. cryptography, attestation, lifecycle etc). - -## Design - -The code is designed to be readable rather than fast or secure. -In this implementation only one message is delivered to a -RoT service at a time. -The code is not thread-safe. - -## Unsupported features - -Because this is a simulator there are a few things that -can't be reasonably emulated: - -* Manifest MMIO regions are unsupported -* Manifest priority field is ignored -* Partition IDs are in fact POSIX `pid_t`, which are only assigned at runtime, - making it infeasible to populate pid.h with correct values. +- `psa_sim_serialise.[c|h]`: + - go to `/tests/psa-client-server/psasim/src/` + - run `./psa_sim_serialise.pl h > psa_sim_serialise.h` + - run `./psa_sim_serialise.pl c > psa_sim_serialise.c` +- `psa_sim_crypto_[client|server].c` and `psa_functions_codes.h`: + - go to Mbed TLS' root folder + - run `./tests/psa-client-server/psasim/src/psa_sim_generate.pl`