[PATCH 4/4] docs: Document the PSA crypto backend

[Chaitanya Tata]

From: Chaitanya Tata <Chaitanya.Tata at nordicsemi.no>

Describe the CONFIG_TLS=psa backend: its two-file PSA-first design and the
documented non-PSA boundary (TLS/X.509, bignum and EC-point math via
MbedTLS), how to build the reference MbedTLS 4.x / TF-PSA-Crypto 1.x
libraries and hostap against them, how to run the crypto module tests, and
the current limitations (EAP-FAST/TEAP, DPP2/DPP3 RSA-OAEP/HPKE, IMSI
privacy, OCSP, PKCS#12).

Signed-off-by: Chaitanya Tata <Chaitanya.Tata at nordicsemi.no>
---
 src/crypto/README-psa.md | 113 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 113 insertions(+)
 create mode 100644 src/crypto/README-psa.md

diff --git a/src/crypto/README-psa.md b/src/crypto/README-psa.md
new file mode 100644
index 000000000..ca6309a2f
--- /dev/null
+++ b/src/crypto/README-psa.md
@@ -0,0 +1,113 @@
+# PSA crypto backend (CONFIG_TLS=psa)
+
+This backend implements hostap's `crypto.h` and `tls.h` interfaces on top of
+the Arm **PSA Crypto API**, using **MbedTLS 4.x / TF-PSA-Crypto 1.x** as the
+reference provider. It targets resource-constrained and PSA-based platforms
+(e.g. Nordic nRF Connect SDK with Oberon PSA Crypto + CryptoCell, TF-M),
+where the primitive crypto is exposed through PSA rather than a specific
+library.
+
+Files:
+
+* `crypto_psa.c`         - the portable, PSA-only half of the `crypto.h`
+  implementation (hashes, HMAC, ciphers, AEAD, CMAC, KDFs, RNG, cipher ctx).
+* `crypto_psa_mbedtls.c` - the non-PSA half: bignum, EC-point and finite-field
+  DH math, EC keys and DPP/CSR helpers, using the MbedTLS builtin modules.
+  This is the only file that must change if PSA ever gains these operations
+  (or another provider supplies them).
+* `tls_psa.c`            - the `tls.h` (TLS/X.509) implementation.
+
+## PSA-first, with a documented non-PSA boundary
+
+The PSA Crypto API standardises cryptographic *primitives* only. Three areas
+hostap needs are outside PSA in every PSA implementation, so this backend uses
+MbedTLS (and, for a few primitives, hostap's own bundled code) for them:
+
+1. **TLS protocol and X.509** - not part of PSA. `tls_psa.c` uses
+   `mbedtls_ssl_*` / `mbedtls_x509_*`.
+2. **Arbitrary big-number arithmetic** - PSA has no MPI API. SAE, DPP,
+   EAP-PWD and finite-field DH use the MbedTLS builtin `mbedtls_mpi_*`.
+3. **Explicit EC point arithmetic** - PSA only exposes ECDH/ECDSA as opaque
+   operations. SAE (hunting-and-pecking + H2E), DPP and PASN use the MbedTLS
+   builtin `mbedtls_ecp_*`.
+
+Everything else - hashes, HMAC, AES (ECB/CBC/CTR/GCM/CCM), CMAC, AEAD, KDFs,
+RNG, RSA, ECDSA and high-level ECDH - goes through the portable `psa_*` API.
+That portable core is what a non-MbedTLS PSA provider inherits unchanged; only
+the TLS/X.509 and bignum/EC-point pieces remain MbedTLS-specific today.
+
+MbedTLS 4 removed single-DES, MD4 and the DHM module, and PSA has no
+equivalents, so EAP-MSCHAPv2 (DES), the NT-hash (MD4), TKIP/MPPE (RC4) and
+finite-field DH (WPS, EAP-PWD-FFC, EAP-IKEv2) fall back to hostap's bundled
+`des-internal.c`, `md4-internal.c`, `rc4.c` and `dh_groups.c`/`dh_group5.c`
+(over this backend's `crypto_mod_exp()`), selected via `CONFIG_INTERNAL_DES`,
+`CONFIG_INTERNAL_MD4`, `CONFIG_INTERNAL_RC4` and `CONFIG_INTERNAL_DH_GROUP5`.
+
+## Building the reference MbedTLS / TF-PSA-Crypto
+
+MbedTLS 4.x bundles TF-PSA-Crypto as a submodule and builds three static
+libraries (`libtfpsacrypto`/`libmbedcrypto`, `libmbedx509`, `libmbedtls`):
+
+    git -C mbedtls submodule update --init --recursive
+    cmake -S mbedtls -B mbedtls/build \
+        -DUSE_STATIC_MBEDTLS_LIBRARY=On -DUSE_SHARED_MBEDTLS_LIBRARY=Off \
+        -DENABLE_TESTING=Off -DENABLE_PROGRAMS=Off
+    cmake --build mbedtls/build -j
+
+The default config already enables what this backend needs (PEM parsing,
+NIST-KW, SSL keying-material export, keep-peer-certificate, TLS 1.2/1.3, and
+the PSA_WANT_* algorithm/curve set). The builtin bignum/ECP driver is compiled
+because `PSA_WANT_ECC_*` is enabled; its declarations live in the *private*
+headers under `tf-psa-crypto/drivers/builtin/include`, so that directory must
+be on the include path (see the build configs below). Because those headers
+are private, this backend must be built against the MbedTLS source tree, not
+just an installed prefix.
+
+## Building hostap
+
+See `tests/build/build-wpa_supplicant-psa.config` and
+`tests/build/build-hostapd-psa.config` for complete examples. The essentials:
+
+    CONFIG_TLS=psa
+    CFLAGS += -I$(MBEDTLS_SRC)/include
+    CFLAGS += -I$(MBEDTLS_SRC)/tf-psa-crypto/include
+    CFLAGS += -I$(MBEDTLS_SRC)/tf-psa-crypto/drivers/builtin/include
+    LIBS   += -L$(MBEDTLS_SRC)/build/library
+    CONFIG_INTERNAL_DES=y
+    CONFIG_INTERNAL_MD4=y
+    CONFIG_INTERNAL_RC4=y
+    CONFIG_INTERNAL_DH_GROUP5=y
+
+## Testing
+
+Built with `CONFIG_MODULE_TESTS=y`, the crypto module tests run against this
+backend and pass:
+
+    wpa_supplicant -g /tmp/global &
+    wpa_cli -g /tmp/global    # then send: MODULE_TESTS   (returns OK)
+
+(or use the wpaspy helper: `Ctrl('/tmp/global').request('MODULE_TESTS')`).
+
+## Known limitations
+
+These are documented gaps to be addressed in follow-up work; none affect the
+core WPA2/3 Personal and Enterprise (EAP-TLS/PEAP/TTLS) functionality.
+
+* EAP-FAST and EAP-TEAP are not supported (they need TLS session-ticket key
+  material export that this backend does not yet implement). A hostapd built
+  with CONFIG_TLS=psa must not enable them; the hwsim harness (start.sh)
+  strips them from the RADIUS auth server config automatically.
+* RSA-OAEP is not yet implemented, so:
+  - DPP2 configurator enrollment (which also needs PKCS#7) and DPP3 (HPKE)
+    are unavailable; and
+  - EAP-SIM/AKA IMSI privacy (imsi_privacy_key) is unavailable.
+  PSA does provide PSA_ALG_RSA_OAEP, so this is a straightforward addition in
+  crypto_psa_mbedtls.c (crypto_rsa_key_read()/crypto_rsa_oaep_sha256_*()).
+* OCSP stapling is not supported (not required for WPA3-Enterprise).
+* PKCS#12 and some legacy certificate encodings are not supported.
+
+## History / attribution
+
+Derived from the Zephyr Project hostap MbedTLS port: the original MbedTLS
+wrapper was written by Glenn Strauss; the PSA-based rework was contributed by
+NXP and maintained by Nordic Semiconductor, with contributions from BayLibre.
-- 
2.43.0