Merge remote-tracking branch 'main' into union-initialization-gcc15-framework-preliminaries

tests/include/test/psa_exercise_key.h

@@ -138,11 +138,22 @@ int mbedtls_test_psa_setup_key_derivation_wrap(
     size_t capacity, int key_destroyable);
 
 /** Perform a key agreement using the given key pair against its public key
- * using psa_raw_key_agreement() and psa_key_agreement().
+ * (not combined with a key derivation).
  *
- * The result is discarded. The purpose of this function is to smoke-test a key.
+ * The result is discarded. Thus this function can be used for smoke-testing
+ * a key, and to validate input validation, but not to validate results.
  *
- * In case of failure, mark the current test case as failed.
+ * Depending on the library version, there can be multiple interfaces for key
+ * agreement. This test function performs the ones that are available amongst:
+ * - psa_raw_key_agreement()
+ * - psa_key_agreement()
+ * - psa_key_agreement_iop_setup() and psa_key_agreement_iop_complete()
+ *
+ * Mark the current test case as failed in the following cases:
+ * - Operational errors such as failure to allocate memory for an intermediate
+ *   buffer.
+ * - Results are not consistent between the methods that are performed:
+ *   different statuses, or inconsistent metadata, or different shared secret.
  *
  * \param alg               A key agreement algorithm compatible with \p key.
  * \param key               A key that allows key agreement with \p alg.
@@ -150,7 +161,7 @@ int mbedtls_test_psa_setup_key_derivation_wrap(
  *                          or the key being destroyed mid-operation will only
  *                          be reported if the error code is unexpected.
  *
- * \return                  \c 1 on success, \c 0 on failure.
+ * \return                  The status from psa_raw_key_agreement().
  */
 psa_status_t mbedtls_test_psa_raw_key_agreement_with_self(
     psa_algorithm_t alg,