yuzu-emu/mbedtls
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update documentation in legacy_or_psa.h

Browse source 
- Some things that were indicated as in the near future are now done.
- Clarify when these macros are needed and when they're not.
- Prepare to make the header public.

Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
This commit is contained in:
Manuel Pégourié-Gonnard 2022-09-15 11:11:00 +02:00
parent 1dc37258de
commit c42c7e660e
2 changed files with 31 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
docs/architecture/psa-migration/strategy.md
View file

@ -345,7 +345,7 @@ available. Data related to a certain hash (OID, sizes, translations) should
only be included in the build if it is possible to use that hash in some way.
In order to cater to these new needs, new families of macros are introduced in
`library/legacy_or_psa.h`, see its documentation for details.
`legacy_or_psa.h`, see its documentation for details.
It should be noted that there are currently:
- too many different ways of computing a hash (low-level, MD, PSA);
@ -358,6 +358,16 @@ This is a temporary situation until we move to a place where everything is
based on PSA Crypto. In the meantime, long and explicit names where chosen for
the new macros in the hope of avoiding confusion.
Note: the new macros supplement but do not replace the existing macros:
- code that always uses PSA Crypto (for example, code specific to TLS 1.3)
should use `PSA_WANT_xxx`;
- code that always uses the legacy API (for exmaple, crypto modules that have
not undergone step 1 yet) should use `MBEDTLS_xxx_C`;
- code that may use one of the two APIs, either based on
`MBEDTLS_USE_PSA_CRYPTO` (X.509, TLS 1.2, shared between TLS 1.2 and 1.3),
or based on availability (crypto modules after step 1), should use one of the
new macros from `legacy_or_psa.h`.
Executing step 3 will mostly consist of using the right dependency macros in
the right places (once the previous steps are done).

33
library/legacy_or_psa.h
View file

@ -1,6 +1,6 @@
/**
* Internal macros to express dependencies for code and tests
* that may use either the legacy API or PSA in various builds.
* Macros to express dependencies for code and tests that may use either the
* legacy API or PSA in various builds; mostly for internal use.
*
* Copyright The Mbed TLS Contributors
* SPDX-License-Identifier: Apache-2.0
@ -19,6 +19,18 @@
*/
/*
* Note: applications who are targetting a specific configurations do not need
* to use these macros; instead they should directly use the functions they
* know are available in their configuration.
*
* Note: code that is purely based on PSA Crypto (psa_xxx() functions)
* does not need to use these macros; instead it should use the relevant
* PSA_WANT_xxx macros.
*
* Note: code that is purely based on the legacy crypto APIs (mbedtls_xxx())
* does not need to use these macros; instead it should use the relevant
* MBEDTLS_xxx_ macros.
*
* These macros are for code that wants to use <crypto feature> and will do so
* using <legacy API> or PSA depending on <condition>, where:
* - <crypto feature> will generally be an algorithm (SHA-256, ECDH) but may
@ -36,15 +48,10 @@
* - TLS 1.2 will compute hashes using either mbedtls_md_xxx() (and
* mbedtls_sha256_xxx()) or psa_aead_xxx() depending on whether
* MBEDTLS_USE_PSA_CRYPTO is defined;
* - RSA PKCS#1 v2.1 will, in the near future*, compute hashes (for padding)
* using either `mbedtls_md()` if it's available, or `psa_hash_compute()`
* otherwise;
* - PEM decoding of PEM-encrypted keys will, in the near future*, compute MD5
* hashes using either `mbedtls_md5_xxx()` if it's available, or
* `psa_hash_xxx()` otherwise.
* *See docs/architecture/psa-migration/strategy.md, section "Supporting
* builds with drivers without the software implementation", strategy for step
* 1 (libmbedcrypto except the RNG subsystem).
* - RSA PKCS#1 v2.1 will compute hashes (for padding) using either
* `mbedtls_md()` if it's available, or `psa_hash_compute()` otherwise;
* - PEM decoding of PEM-encrypted keys will compute MD5 hashes using either
* `mbedtls_md5_xxx()` if it's available, or `psa_hash_xxx()` otherwise.
*
* Note: the macros are essential to express test dependencies. Inside code,
* we could instead just use the equivalent pre-processor condition, but
@ -70,9 +77,9 @@
* MBEDTLS_HAS_ALG_MD5_VIA_LOWLEVEL_OR_PSA
*
* Note: every time it's possible to use, say SHA-256, via the MD API, then
* it's also possible to used it via the low-level API. So, code that wants to
* it's also possible to use it via the low-level API. So, code that wants to
* use SHA-256 via both APIs only needs to depend on the MD macro. Also, it
* just so happens that all the choosing which API to use based on
* just so happens that all the code choosing which API to use based on
* MBEDTLS_USE_PSA_CRYPTO (X.509, TLS 1.2/shared), always uses the abstraction
* layer (sometimes in addition to the low-level API), so we don't need the
* MBEDTLS_HAS_feature_VIA_LOWLEVEL_OR_PSA_BASED_ON_USE_PSA macros.