README.md
1# psasim
2
3PSASIM 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`.
4In 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.
5
6The 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.
7## Limitations
8
9In the current implementation:
10
11- Only Linux PC is supported.
12- There can be only 1 client connected to 1 server.
13- 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.
14- Server is not secure at all: keys and operation structs are stored on the RAM, so they can easily be dumped.
15
16## Testing
17
18Please refer to `tests/scripts/components-psasim.sh` for guidance on how to build & test PSASIM:
19
20- `component_test_psasim()`: builds the server and a couple of test clients which are used to evaluate some basic PSA Crypto API commands.
21- `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.
22
23## How to update automatically generated files
24
25A significant portion of the intermediate code of PSASIM is auto-generated using Perl. In particular:
26
27- `psa_sim_serialise.[c|h]`:
28 - Generated by `psa_sim_serialise.pl`.
29 - These files provide the serialisation/deserialisation support that is required to pass functions' parameters between client and server.
30- `psa_sim_crypto_[client|server].c` and `psa_functions_codes.h`:
31 - Generated by `psa_sim_generate.pl`.
32 - `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.
33
34These files need to be regenerated whenever some PSA Crypto API is added/deleted/modified. The procedure is as follows:
35
36- `psa_sim_serialise.[c|h]`:
37 - go to `<mbedtls-root>/tests/psa-client-server/psasim/src/`
38 - run `./psa_sim_serialise.pl h > psa_sim_serialise.h`
39 - run `./psa_sim_serialise.pl c > psa_sim_serialise.c`
40- `psa_sim_crypto_[client|server].c` and `psa_functions_codes.h`:
41 - go to Mbed TLS' root folder
42 - run `./tests/psa-client-server/psasim/src/psa_sim_generate.pl`
43