tests/psa-client-server/psasim/README.md

# psasim

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.

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

In the current implementation:

- 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.

## Testing

Please refer to `tests/scripts/components-psasim.sh` for guidance on how to build & test PSASIM:

- `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.

## How to update automatically generated files

A significant portion of the intermediate code of PSASIM is auto-generated using Perl. In particular:

- `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.

These files need to be regenerated whenever some PSA Crypto API is added/deleted/modified. The procedure is as follows:

- `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`