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: parsing a public key
directly or via X.509, or setting up an SSL context. Functions that are
normally only called after such a function (for example, using an already
constructed PK object), 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 0e4ee38..3de7a8f 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -796,6 +796,10 @@
/**
* \brief Parse a private key in PEM or DER format
*
+ * \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.
+ *
* \param ctx The PK context to fill. It must have been initialized
* but not set up.
* \param key Input buffer to parse.
@@ -832,6 +836,10 @@
/**
* \brief Parse a public key in PEM or DER format
*
+ * \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.
+ *
* \param ctx The PK context to fill. It must have been initialized
* but not set up.
* \param key Input buffer to parse.
@@ -861,6 +869,10 @@
/**
* \brief Load and parse a private key
*
+ * \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.
+ *
* \param ctx The PK context to fill. It must have been initialized
* but not set up.
* \param path filename to read the private key from
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 2594964..29ba85a 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -1869,6 +1869,10 @@
* Calling mbedtls_ssl_setup again is not supported, even
* if no session is active.
*
+ * \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.
+ *
* \param ssl SSL context
* \param conf SSL configuration to use
*
diff --git a/include/mbedtls/x509_crl.h b/include/mbedtls/x509_crl.h
index 49bbf61..62694ae 100644
--- a/include/mbedtls/x509_crl.h
+++ b/include/mbedtls/x509_crl.h
@@ -107,6 +107,10 @@
/**
* \brief Parse a DER-encoded CRL and append it to the chained list
*
+ * \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.
+ *
* \param chain points to the start of the chain
* \param buf buffer holding the CRL data in DER format
* \param buflen size of the buffer
@@ -121,6 +125,10 @@
*
* \note Multiple CRLs are accepted only if using PEM format
*
+ * \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.
+ *
* \param chain points to the start of the chain
* \param buf buffer holding the CRL data in PEM or DER format
* \param buflen size of the buffer
@@ -136,6 +144,10 @@
*
* \note Multiple CRLs are accepted only if using PEM format
*
+ * \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.
+ *
* \param chain points to the start of the chain
* \param path filename to read the CRLs from (in PEM or DER encoding)
*
diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h
index 036282f..11e5951 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -341,6 +341,10 @@
* \brief Parse a single DER formatted certificate and add it
* to the end of the provided chained list.
*
+ * \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.
+ *
* \param chain The pointer to the start of the CRT chain to attach to.
* When parsing the first CRT in a chain, this should point
* to an instance of ::mbedtls_x509_crt initialized through
@@ -402,6 +406,10 @@
* \brief Parse a single DER formatted certificate and add it
* to the end of the provided chained list.
*
+ * \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.
+ *
* \param chain The pointer to the start of the CRT chain to attach to.
* When parsing the first CRT in a chain, this should point
* to an instance of ::mbedtls_x509_crt initialized through
@@ -452,6 +460,10 @@
* temporary ownership of the CRT buffer until the CRT
* is destroyed.
*
+ * \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.
+ *
* \param chain The pointer to the start of the CRT chain to attach to.
* When parsing the first CRT in a chain, this should point
* to an instance of ::mbedtls_x509_crt initialized through
@@ -492,6 +504,10 @@
* long as the certificates are enclosed in the PEM specific
* '-----{BEGIN/END} CERTIFICATE-----' delimiters.
*
+ * \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.
+ *
* \param chain The chain to which to add the parsed certificates.
* \param buf The buffer holding the certificate data in PEM or DER format.
* For certificates in PEM encoding, this may be a concatenation
@@ -516,6 +532,10 @@
* of failed certificates it encountered. If none complete
* correctly, the first error is returned.
*
+ * \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.
+ *
* \param chain points to the start of the chain
* \param path filename to read the certificates from
*
diff --git a/include/mbedtls/x509_csr.h b/include/mbedtls/x509_csr.h
index 0c204be..e376000 100644
--- a/include/mbedtls/x509_csr.h
+++ b/include/mbedtls/x509_csr.h
@@ -89,6 +89,10 @@
*
* \note CSR attributes (if any) are currently silently ignored.
*
+ * \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.
+ *
* \param csr CSR context to fill
* \param buf buffer holding the CRL data
* \param buflen size of the buffer
@@ -103,6 +107,10 @@
*
* \note See notes for \c mbedtls_x509_csr_parse_der()
*
+ * \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.
+ *
* \param csr CSR context to fill
* \param buf buffer holding the CRL data
* \param buflen size of the buffer