Document the need to call psa_crypto_init() with USE_PSA_CRYPTO
When MBEDTLS_USE_PSA_CRYPTO is enabled, the application must call
psa_crypto_init() before directly or indirectly calling cipher or PK code
that will use PSA under the hood. Document this explicitly for some
functions.
To avoid clutter, this commit only documents the need to call
psa_crypto_init() in common, non-obvious cases: using a PK object that was
not constructed using PSA, X.509 processing, or setting up an SSL context.
Functions that are normally only called after such a function (for example,
using a cipher or PK context constructed from a PSA key), or where the need
for PSA is obvious because they take a key ID as argument, do not need more
explicit documentaion.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h
index a226e71..ec83551 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -402,6 +402,11 @@
* Use \c mbedtls_pk_verify_ext( MBEDTLS_PK_RSASSA_PSS, ... )
* to verify RSASSA_PSS signatures.
*
+ * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
+ * subsystem must have been initialized by calling
+ * psa_crypto_init() before calling this function,
+ * if the key might be an ECC (ECDSA) key.
+ *
* \note If hash_len is 0, then the length associated with md_alg
* is used instead, or an error returned if it is invalid.
*