ARMmbed/mbedtls
1
0
Fork 0
mirror of https://github.com/ARMmbed/mbedtls.git synced 2025-05-09 16:41:19 +08:00
Code Issues Releases Wiki Activity

Merge pull request #10032 from valeriosetti/psasim-doc-update

Browse Source 
psasim: update README file
This commit is contained in:
Manuel Pégourié-Gonnard 2025-03-28 09:11:13 +00:00 committed by GitHub
commit 064f68ec85
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 29 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
tests/psa-client-server/psasim/README.md
View File

@ -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 `<mbedtls-root>/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 `<mbedtls-root>/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`