Open mpg opened 11 months ago
The general wisdom for API transitions is to have one full major version cycle where the new API is stable and the old API is present but deprecated. In Mbed TLS 3, we're at an intermediate stage where the new API is stable but old API is not deprecated.
Because hashes are so ubiquitous, and because we already have code in md.c
that wraps around PSA, I'm in favor of keeping at least MD light as the md.h
of Mbed TLS 4.x. This helps our users, and saves us work for 4.0 (even if we removed md.h
from the public API, we'd very likely keep it internally until we have time to update all the modules that use it).
mbedtls_md_info_t
can be reduced to a single byte. It's already only 8 bytes on typical archictectures.
I'm not sure what to do about HMAC. I don't think it's hard to implement it on top of PSA. (Note that mbedtls_md_clone
doesn't support HMAC, otherwise that would be difficult to implement.) Migrating all the modules that currently call MD and don't have a PSA alternative (hkdf.c
, hmac_drbg.c
, pkcs5.c
) is likely to be more work. So I'd lean towards keeping the MD HMAC interface in 4.x as well.
Migrating all the modules that currently call MD and don't have a PSA alternative (
hkdf.c
,hmac_drbg.c
,pkcs5.c
) is likely to be more work.
Minor: I don't think HKDF belongs on that list: it does have a PSA alternative, whose built-in implementation (currently in psa_crypto.c
) does not depend on hkdf.c
. (So, I think as soon as hkdf.h
is no longer public, we can remove hkdf.c
as well.)
Also, I think migrating internal users of HMAC to PSA is work indeed, but relatively easy work, though.
Note (just for reference, I don't think it influences the decision to keep MD or not): currently (with USE_PSA
), internal users of MD (hashes or HMAC) are:
ecdsa.c
ecjpake.c
entropy.c
hkdf.c
(will disappear though, see above)hmac_drbg.c
pem.c
pk.c
, pk_wrap.c
pkcs12.c
pkcs5.c
pkcs7.c
psa_crypto.c
psa_crypto_ecp.c
psa_crypto_rsa.c
rsa.c
Aw, I think I forgot a work item for "option 2 (remove)": what about uses of types from md.h
in other APIs?
mbedtls_ssl_async_sign_t
takes a parameter of type mbedtls_md_type_t
mbedtls_x509write_crt_set_md_alg()
and mbedtls_x509write_csr_set_md_alg()
both take a parameter of type mbedtls_md_type_t
(there are other such functions in x509.h
but they're internal (should be moved: tracked here).Actually, I say that's a work item for option 2, but that's something we probably still want to do with option 1 anyway.
what about uses of types from md.h in other APIs?
We definitely need to remove those or provide alternatives. md.h
in 4.0 should be a transition path, not something that new applications would have to use.
"This gives users more time to move to PSA. People who were using low-level hash modules need to migrate immediately, but those who were using the generic MD API for hashes and HMAC can migrate at a convenient time between now and 5.0."
Users who want to use md.h
will of course have support in 3.6 until March 2027. If we provide it in 4.0, we have to offer support until probably 2028.
AFAICT it is very low impact to break these cases. In the X.509 case, it's trivial for the user (pass PSA_ALG_xxx
instead of MBEDTLS_MD_xxx
). For the TLS callback, it's a bit more work, but not much more.
So I am in favour of removal.
Keep it as part of the public API until 5.0, but aim to make it a thin wrapper around PSA Crypto (in 4.0 or 4.x).
That's the plan. The cost of keeping it is small and the cost of tearing out of our code base is large.
This issue is meant as a place to discuss what we want to do with MD in 4.0.
There are two main options:
Note: MD currently provides functionality similar to two PSA Crypto families:
psa_hash_xxx()
andpsa_mac_xxx()
(HMAC). It provides both streaming and one-shot API for each family.Note: for low-level hash modules (
sha256.h
etc) I think the plan is to remove them from the public API, regardless of what we do with MD.Rationale for option 1 (keep)
This gives users more time to move to PSA. People who were using low-level hash modules need to migrate immediately, but those who were using the generic MD API for hashes and HMAC can migrate at a convenient time between now and 5.0.
Work needed for option 1 (keep)
In 4.0:
mbedtls_md_info_from_string()
,mbedtls_md_get_name()
- see #8133 item 1mbedtls_md_list()
as well (not used in the library)mbedtls_md_info_t
from the API in order to make it slicker but that would require users to change their code, so it runs against the stated goal. (Alternatively, we can keep the structure but later make it trivial as it has no public field.)In 4.0 or 4.x:
Rationale for option 2 (remove)
This leaves us with only one hashing/HMAC API to maintain, document and test. For new users, this also gives more clarity.
Work needed for option 2 (remove)
In 4.0:
md.h
to an internal location and adapt all files that#include
it.psa/hmac_demo
andhash/md_hmac_demo.c
going in that direction, and an example programpsa_hash.c
.)In 4.0 or 4.x:
Other options