Mbed TLS version update

[edersondisouza]

Hi,

Is there any plans to update Mbed TLS to the 4.x series? How would such update work? I'm imagining this could be a big work, given the PSA Crypto split.

Thanks,

[steven-bellock]

One question is, should libspdm offer support for both 3.x and 4.x versions? Or have everyone migrate to 4.x? Note that the transition from Mbed TLS 3.x to 4.x can happen during a libspdm minor release; for example libspdm 4.3 to 4.4.

[daniileg]

Mbed TLS 3.x will not be supported after March 2027: https://lists.trustedfirmware.org/archives/list/mbed-tls-announce@lists.trustedfirmware.org/thread/FBTRXPK7F52PUMNAUZ7LAG3NRGHNAV4B/

It would be helpful to understand the plans for Mbed TLS 4.x support.

[steven-bellock]

Mbed TLS 3.x → 4.x Migration

The Root Cause: A Complete API Paradigm Shift

Mbed TLS 4.0 split the crypto layer into a separate project (TF-PSA-Crypto) and removed every low-level mbedtls_* crypto API. The only supported interface is the PSA Cryptography API (psa/crypto.h). This is not a rename—it is a different programming model:

3.x model	4.x PSA model
Allocate context struct on stack	Import key into global keystore via psa_import_key()
mbedtls_xxx_init() / mbedtls_xxx_free()	Get a psa_key_id_t handle; psa_destroy_key() at end
Pass f_rng, p_rng to every signing/keygen call	Call psa_crypto_init() once; PSA manages global RNG
mbedtls_ecp_keypair / mbedtls_rsa_context	Opaque psa_key_id_t — no direct field access

---

Scope of cryptlib_mbedtls

34 source files, 10,763 lines total.
~3,100 lines are already stubs (SM2, SM3, SM4, EdDSA, PQC) that require no changes.
~7,700 lines of active implementation need migration.

---

File-by-File Impact

File	Lines	Impact	Reason
hash/sha.c	624	Rewrite	mbedtls/sha256.h, mbedtls/sha512.h gone; switch to psa_hash_operation_t
hash/sha3.c	624	Rewrite	mbedtls/sha3.h gone; PSA PSA_ALG_SHA3_*
hmac/hmac_sha.c	709	Rewrite	mbedtls_md_hmac_* removed; PSA key import + psa_mac_operation_t
hmac/hmac_sha3.c	709	Rewrite	Same
pk/ec.c	894	Rewrite	mbedtls/ecp.h, mbedtls/ecdsa.h, mbedtls/ecdh.h all gone
pk/rsa_ext.c	610	Rewrite	mbedtls/rsa.h gone; PSA sign/verify/generate
pk/rsa_basic.c	466	Rewrite	Same
kdf/hkdf_sha.c	386	Rewrite	mbedtls/hkdf.h gone; psa_key_derivation_* multipart operations
kdf/hkdf_sha3.c	386	Rewrite	Same
pk/x509.c	2257	Heavy changes	Headers retained; PK layer changes (pk_rsa(), pk_ec(), pk_get_type(), pk_parse_key() signatures all changed); mbedtls_oid_* removed from public API
cipher/aead_aes_gcm.c	187	Rewrite	mbedtls/gcm.h gone; PSA AEAD key + psa_aead_encrypt/decrypt()
cipher/aead_chacha20_poly1305.c	168	Rewrite	mbedtls/chachapoly.h gone; PSA PSA_ALG_CHACHA20_POLY1305
pk/dh.c	334	Heavy changes	mbedtls/dhm.h gone; psa_raw_key_agreement(PSA_ALG_FFDH, ...) — only RFC 7919 named groups
pem/pem.c	262	Moderate	pem.h retained in TF-PSA-Crypto; pk_parse_key() signature changed (no f_rng/p_rng), pk_rsa()/pk_ec() accessors gone
der/der.c	201	Moderate	mbedtls/bignum.h gone; key material extraction (for DER encoding) requires psa_export_key()/psa_export_public_key() + re-parsing
rand/rand.c	67	Minor	mbedtls/entropy.h + mbedtls/ctr_drbg.h gone; replace with psa_crypto_init() + custom entropy hook mbedtls_platform_get_entropy()

---

Non-Obvious Complications

1. Key material extraction is now opt-in. The current der.c calls mbedtls_rsa_export() and accesses ECP point coordinates via mbedtls_mpi to manually encode DER. With PSA, keys must be created with PSA_KEY_USAGE_EXPORT and extracted via psa_export_key() / psa_export_public_key(), which returns an opaque format that then needs ASN.1 parsing. This is the hardest single design problem.

2. PSA key lifecycle creates new ownership semantics. Every function that currently takes a void *context owning an in-place struct must either (a) store a psa_key_id_t and destroy it on free, or (b) re-import the key on each call. libspdm's crypto abstraction layer was not designed with an external keystore in mind.

3. No MAC clone in PSA. mbedtls_sha256_clone() / mbedtls_sha3_clone() / mbedtls_md_clone() are used throughout the SHA and HMAC files. PSA has psa_hash_clone() but no MAC clone. Any mid-stream HMAC save/restore will need a workaround (e.g., buffering all input and replaying).

4. Config file split. libspdm_mbedtls_config.h uses ~20 MBEDTLS_xxx_C feature macros. In 4.x these migrate to PSA_WANT_xxx macros in a separate psa/crypto_config.h. The CMake build in os_stub/mbedtlslib/ also needs to reference the TF-PSA-Crypto submodule.

5. SHA-3 PSA coverage. PSA spec includes PSA_ALG_SHA3_256/384/512, but support in TF-PSA-Crypto is implementation-defined and needs verification before committing to the approach.

6. mbedtls_x509_crt_parse_der_with_ext_cb needs to be verified as still present in Mbed TLS 4.x (it is in x509_crt.h which is retained, but the callback API may have changed).

---

Complexity Rating: High

This is not a mechanical rename. The PSA API requires a different mental model for key lifecycle, randomness, and key material access. The largest single risks are (1) the DER encoding path that currently inspects raw key components, and (2) any code path that needs mid-stream clone/save of HMAC state, which PSA does not support. Both will require design decisions, not just API substitution.

The good news: ~30% of the files are already stubs, the X.509 parsing layer is retained, and the SPDM DHE groups are all RFC 7919 (so DH is straightforward). A 3.x → 4.x migration is realistic but should be planned as a focused engineering project, not a quick dependency bump.

---

Reference Links

• TF-PSA-Crypto 1.0 migration guide
• PSA transition guide
• Mbed TLS 4.0 migration guide