From c9516fbf13e7c01c76fb5ba2ef3cf83107a1ebba Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Tue, 5 Feb 2019 20:32:06 +0100
Subject: [PATCH] Document exercise_key and fix one incorrect usage

In one place, exercise_key was used in a such a way that if the test
failed inside exercise_key, the test suite would correctly report the
test as failed but would not report the exact location of the failure.
Fix this.

Add documentation for exercise_key that explains how to use it.
---
 tests/suites/test_suite_psa_crypto.function | 30 ++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/tests/suites/test_suite_psa_crypto.function b/tests/suites/test_suite_psa_crypto.function
index 8ca7dcd10..1fd0d7d98 100644
--- a/tests/suites/test_suite_psa_crypto.function
+++ b/tests/suites/test_suite_psa_crypto.function
@@ -771,6 +771,33 @@ exit:
     return( ok );
 }
 
+/** Do smoke tests on a key.
+ *
+ * Perform one of each operation indicated by \p alg (decrypt/encrypt,
+ * sign/verify, or derivation) that is permitted according to \p usage.
+ * \p usage and \p alg should correspond to the expected policy on the
+ * key.
+ *
+ * Export the key if permitted by \p usage, and check that the output
+ * looks sensible. If \p usage forbids export, check that
+ * \p psa_export_key correctly rejects the attempt. If the key is
+ * asymmetric, also check \p psa_export_public_key.
+ *
+ * If the key fails the tests, this function calls the test framework's
+ * `test_fail` function and returns false. Otherwise this function returns
+ * true. Therefore it should be used as follows:
+ * ```
+ * if( ! exercise_key( ... ) ) goto exit;
+ * ```
+ *
+ * \param handle    The key to exercise. It should be capable of performing
+ *                  \p alg.
+ * \param usage     The usage flags to assume.
+ * \param alg       The algorithm to exercise.
+ *
+ * \retval 0 The key failed the smoke tests.
+ * \retval 1 The key passed the smoke tests.
+ */
 static int exercise_key( psa_key_handle_t handle,
                          psa_key_usage_t usage,
                          psa_algorithm_t alg )
@@ -920,7 +947,8 @@ void import_twice( int alg_arg, int usage_arg,
     if( expected_import1_status == PSA_SUCCESS ||
         expected_import2_status == PSA_SUCCESS )
     {
-        TEST_ASSERT( exercise_key( handle, usage, alg ) );
+        if( ! exercise_key( handle, usage, alg ) )
+            goto exit;
     }
 
 exit: