I have been replicating the definitions of the specification-defined and implementation-defined types and macros from the specification appendix C, and the TF-M and mbedtls header files, into a fork of the example psa/crypto.h provided by the specification. This is at https://github.com/athoelke/psa-api/blob/crypto-std-headers/headers/crypto/1.1/psa/crypto.h. The diff is a helpful way to see what has been provided: https://github.com/ARM-software/psa-api/compare/main...athoelke:crypto-std-headers.

In the modified header I have included a number of helper macros, and a small number of definitions that constrain the sizes of keys. These additions all use a `_PSA_` prefix to distinguish them from the specification identifiers.

Summary of what this adds to the specification example header:

*  The key attributes structure is concrete, and notably does not support the additional permitted algorithm that mbedtls implements. TF-M defines this structure with a nested embedded structure.

*  Key attribute accessors are all static inline functions, and so I replicated this in the header.

*  Operation objects are all indirect (containing an integer handle), which is natural for TF-M, as the operation state is managed inside the crypto service, not the application.

*  The buffer size macros predominantly depend on the set of supported algorithms, keys and key sizes; assuming that the implementation minimizes the amount of input and output buffering during operations.

*  Note that there are a small number of unsupported items: in particular between TF-M and mbedtls, there is no definition for PSA_KEY_DERIVATION_INPUT_CONTEXT, or support for XTS mode.

A couple of observations to start with:

1. Smaller sets of supported algorithms and keys can permit much simpler implementation of these macros, but that defeats the purpose of defining a common header file. When these macros are used with constant parameter values, the complexity is resolved by the compiler, and does not impact code size. However, when any runtime value is used, the effect on code size of using a 'standard, supports everything macro' instead of a 'optimized for this implementation macro' could be substantial.

2. The operation definition in TF-M is not useful for in-application library implementations: these would either want a large operation structure (as mbedtls uses), or for the API object to contain a pointer (not an integer) to an allocated, hidden operation object. To achieve a common header across implementations, only the indirect pointer approach is possible. In turn, this demands that a library implementation is either dependent on dynamic memory allocation, or provides a static pool of operation contexts that must be sufficient for all application use cases.

Regards,

Andrew