Writing code that works for both Mbed Crypto 1.1 and 2.0 APIs

[laurencelundblade]

Description

Some environments still use the PSA Crypto 1.1 API, particularly TF-M. The 1.1 and 2.0 APIs are close enough that it is worth making the code that calls functions defined in crypto.h common, but there is no preprocessor symbol in crypto.h (that I can see) that could be used for code that needs to be conditional on one version or the other of the API.

This was recently added to PSA Crypto 2.0 #define PSA_CRYPTO_API_VERSION_MAJOR 1 If this were defined to be 2 instead of 1, I would have thought this was the symbol I wanted, but it seems more about sub versioning below the 1.1 vs 2.0 distinction.

Further it is commented as The major version of this implementation of the PSA Crypto API which is even more confusing. The PSA Crypto API is an abstract API, not an implementation, right? So what is this the version of the API or the mbed implementation?

I'm working off-target on MacOS with Xcode to eventually run on target on lots of ARM CPUs, but that doesn't affect the anything here (it's really nice that both versions of the mbed library work off-target like this).

Issue request type

[ ] Question
[X] Enhancement
[ ] Bug

[gilles-peskine-arm]

Did you mean versions of Mbed Crypto (the library)? PSA Crypto (the interface) is still at 1.0 beta3 (latest official release of the document, although Mbed Crypto already implements many changes that have been made since then). PSA Crypto 1.0 final coming out in 2020Q1, and we don't plan to maintain backward compatibility with beta APIs.

Mbed Crypto release versions are not aligned with PSA Crypto API versions. PSA_CRYPTO_API_VERSION_MAJOR is the PSA Crypto API version. There is no MBED_CRYPTO_VERSION. There is MBEDTLS_VERSION_MAJOR and MBEDTLS_VERSION_MINOR but they're side effects of how we synchronize shared files between Mbed TLS and Mbed Crypto, so they aren't really meaningful.

We do maintain some compatibility in Mbed Crypto when practical. Backward compatibility definitions are now in psa/crypto_compat.h.

In practice, most if not all changes have involved defining new macros or renaming macros, which gives you more precise control since you can make your code conditional on the relevant feature, rather than indirectly based on a version number. Have you found changes where this isn't good enough?

[ciarmcom]

Internal Jira reference: https://jira.arm.com/browse/IOTCRYPT-1029

[laurencelundblade]

Hi. Appreciate the quick response!

I'm trying write code that runs against the tip of this repository and against TF-M, specifically https://git.trustedfirmware.org/trusted-firmware-m.git/. It is running against both now. The differences are:

• psa_verify_hash vs psa_asymmetric_verify
• psa_sign_hash vs psa_asymmetric_sign
• psa_get_key_attributes plus psa_get_key_bits vs psa_get_key_information
• A bunch of stuff related to psa_import_key

I got a tar of mbed crypto 1.1 from the releases section of this repository. Works nicely off-target for me. It is the same as what TF-M has. It seems correct to say that mbed 1.1 has an old incompatible version of crypto.h that is not really supported for use in this way (even though TF-M uses it heavily). crypto_compat.h helps some, but is far from a solution.

I did look for a repository for the PSA crypto interface. I was hoping that might shed some light on all this, but I couldn't find one. Is it just part of mbed crypto?

I've diffed the two versions of crypto.h looking for a #define I could reliably use to distinguish the two, but nothing seems safe to rely on going forward.

It seems I just have to give instructions to the user of my SW to know which version of mbed they are using and select build options accordingly.

Appreciate any suggestions. Apologies if I'm missing something.

[laurencelundblade]

So I ended up hinging the conditionality off of PSA_GENERATOR_UNBRIDLED_CAPACITY which is defined in the crypto.h in MBed 1.1, but not in MBed 2.0. It is not ideal, but I figure 1.1 will eventually fall out of use and what is in MBed 2.0 is very close to final.

You can see the full extend of the code for backwards compatibility to 1.1 here: https://github.com/laurencelundblade/t_cose/blob/master/crypto_adapters/t_cose_psa_crypto.c

Also here: https://github.com/laurencelundblade/t_cose/blob/master/examples/t_cose_basic_example_psa.c

[gilles-peskine-arm]

This issue is about backward compatibilty in Mbed Crypto which is no longer a maintained product, so it is moot. Mbed Crypto has been merged back into Mbed TLS which has robust rules for backward compatibility.