Crypto: Modularise the interaction with crypto primitives
This patch creates an engine layer inside the service to
modularise all the operations that involve cryptography
primitives.
It also updates the service documentation, fixes some minor
issues in the NS crypto interface test suite, and updates the
manifest file for the crypto service removing outdated functions.
Change-Id: Id2d0e2140741debd22c145f816a4df2ab0351b58
Signed-off-by: Antonio de Angelis <antonio.deangelis@arm.com>
diff --git a/interface/include/tfm_crypto_defs.h b/interface/include/tfm_crypto_defs.h
index e9bb955..391df84 100644
--- a/interface/include/tfm_crypto_defs.h
+++ b/interface/include/tfm_crypto_defs.h
@@ -67,16 +67,26 @@
/**
* \brief A macro to translate TFM Crypto service return values to the
- * corresponding PSA return value. The user of this macro needs
+ * corresponding psa_status_t value. The user of this macro needs
* to cast the produced value to psa_status_t explicitly if needed
*
* \return Values specified by \ref psa_status_t
*/
-#define TFM_CRYPTO_PSA_RETURN(val) \
+#define TFM_CRYPTO_ERR_TO_PSA_STATUS(val) \
( (val == TFM_CRYPTO_ERR_PSA_SUCCESS) ? val : \
((val >= (enum tfm_crypto_err_t)TFM_CRYPTO_ERR_PSA_ERROR_OFFSET) ? \
(val - ((enum tfm_crypto_err_t)TFM_CRYPTO_ERR_PSA_ERROR_OFFSET-1)) : \
TFM_CRYPTO_ERR_INVALID) )
+/**
+ * \brief A macro to translate psa_status_t values to the corresponding return
+ * values for the TFM Crypto service
+ *
+ * \return Values specified by \ref enum tfm_crypto_err_t
+ *
+ */
+#define PSA_STATUS_TO_TFM_CRYPTO_ERR(val) \
+ ( (val == PSA_SUCCESS) ? (enum tfm_crypto_err_t)val : \
+ (enum tfm_crypto_err_t)(val + TFM_CRYPTO_ERR_PSA_ERROR_OFFSET) )
#ifdef __cplusplus
}
diff --git a/interface/include/tfm_crypto_veneers.h b/interface/include/tfm_crypto_veneers.h
index bb2c6d4..5079901 100644
--- a/interface/include/tfm_crypto_veneers.h
+++ b/interface/include/tfm_crypto_veneers.h
@@ -19,7 +19,7 @@
#include "crypto_psa_wrappers.h"
/**
- * \brief Import the key data on the provided key slot (veneer function)
+ * \brief Import the key data in the provided key slot (veneer function)
*
* \param[in] key Key slot
* \param[in] type Key type
@@ -57,9 +57,9 @@
/**
* \brief Export the key contained in the provided key slot (veneer function)
*
- * \param[in] key Key slot
+ * \param[in] key Key slot
* \param[out] data Buffer to hold the exported key
- * \param[in] data_size Length of the buffer pointed to by data
+ * \param[in] data_size Length of the buffer pointed to by data
* \param[out] data_length Length of the exported key
*
* \return Return values as described in \ref tfm_crypto_err_t
@@ -86,9 +86,12 @@
* \brief Set the cipher operation using the provided algorithm and key slot,
* for encryption context (veneer function)
*
- * \param[in] operation Cipher operation context
- * \param[in] key Key slot to bind to the cipher context
- * \param[in] alg Algorithm to use for the cipher operation
+ * \note A successful call to this function initialises a cipher operation
+ * context which will be referred using the operation parameter
+ *
+ * \param[out] operation Cipher operation context
+ * \param[in] key Key slot to bind to the cipher context
+ * \param[in] alg Algorithm to use for the cipher operation
*
* \return Return values as described in \ref tfm_crypto_err_t
*/
@@ -100,9 +103,12 @@
* \brief Set the cipher operation using the provided algorithm and key slot,
* for decryption context (veneer function)
*
- * \param[in] operation Cipher operation context
- * \param[in] key Key slot to bind to the cipher context
- * \param[in] alg Algorithm to use for the cipher operation
+ * \note A successful call to this function initialises a cipher operation
+ * context which will be referred using the operation parameter
+ *
+ * \param[out] operation Cipher operation context
+ * \param[in] key Key slot to bind to the cipher context
+ * \param[in] alg Algorithm to use for the cipher operation
*
* \return Return values as described in \ref tfm_crypto_err_t
*/
@@ -127,24 +133,16 @@
struct psa_cipher_update_input *input_s,
struct psa_cipher_update_output *output_s);
/**
- * \brief Abort a cipher operation, clears the operation context provided
- * (veneer function)
- *
- * \param[in] operation Cipher operation context
- *
- * \return Return values as described in \ref tfm_crypto_err_t
- */
-enum tfm_crypto_err_t tfm_crypto_veneer_cipher_abort(
- psa_cipher_operation_t *operation);
-
-/**
* \brief Finalise a cipher context flushing out any remaining block of
* output data (veneer function)
*
- * \param[in] operation Cipher operation context
- * \param[out] output Buffer containing output data
- * \param[in] output_size Size of the output buffer
- * \param[out] output_length Size of the produced output
+ * \note A successful call to this function releases the cipher operation
+ * context provided as parameter
+ *
+ * \param[in/out] operation Cipher operation context
+ * \param[out] output Buffer containing output data
+ * \param[in] output_size Size of the output buffer
+ * \param[out] output_length Size of the produced output
*
* \return Return values as described in \ref tfm_crypto_err_t
*/
@@ -154,40 +152,59 @@
size_t output_size,
size_t *output_length);
/**
+ * \brief Abort a cipher operation, clear the operation context provided
+ * (veneer function)
+ *
+ * \note A successful call to this function releases the cipher operation
+ * context provided as parameter
+ *
+ * \param[in/out] operation Cipher operation context
+ *
+ * \return Return values as described in \ref tfm_crypto_err_t
+ */
+enum tfm_crypto_err_t tfm_crypto_veneer_cipher_abort(
+ psa_cipher_operation_t *operation);
+/**
* \brief Setup a hash operation with the provided algorithm (veneer function)
*
- * \param[in] operation Hash operation context
- * \param[in] alg Algorithm chosen as hash
+ * \note A successful call to this function initialises a hash operation
+ * context which will be referred using the operation parameter
*
- * \return Returns values as described in \ref tfm_crypto_err_t
+ * \param[out] operation Hash operation context
+ * \param[in] alg Algorithm chosen as hash
+ *
+ * \return Return values as described in \ref tfm_crypto_err_t
*/
enum tfm_crypto_err_t tfm_crypto_veneer_hash_setup(
psa_hash_operation_t *operation,
psa_algorithm_t alg);
/**
- * \brief Adds a new input chunk to the data for which the final hash value
+ * \brief Add a new input chunk to the data for which the final hash value
* will be computed (veneer function)
*
- * \param[in] operation Hash operation context
- * \param[in] input Buffer containing the input data
- * \param[in] input_length Size of the provided input data
+ * \param[in/out] operation Hash operation context
+ * \param[in] input Buffer containing the input data
+ * \param[in] input_length Size of the provided input data
*
- * \return Returns values as described in \ref tfm_crypto_err_t
+ * \return Return values as described in \ref tfm_crypto_err_t
*/
enum tfm_crypto_err_t tfm_crypto_veneer_hash_update(
psa_hash_operation_t *operation,
const uint8_t *input,
size_t input_length);
/**
- * \brief Finalises a hash context operation producing the final hash value
+ * \brief Finalise a hash context operation producing the final hash value
* (veneer function)
*
- * \param[in] operation Hash operation context
- * \param[out] hash Buffer containing hash data
- * \param[in] hash_size Size of the hash buffer
- * \param[out] hash_length Size of the produced hash
+ * \note A successful call to this function releases the hash operation
+ * context provided as parameter
*
- * \return Returns values as described in \ref tfm_crypto_err_t
+ * \param[in/out] operation Hash operation context
+ * \param[out] hash Buffer containing hash data
+ * \param[in] hash_size Size of the hash buffer
+ * \param[out] hash_length Size of the produced hash
+ *
+ * \return Return values as described in \ref tfm_crypto_err_t
*/
enum tfm_crypto_err_t tfm_crypto_veneer_hash_finish(
psa_hash_operation_t *operation,
@@ -195,26 +212,33 @@
size_t hash_size,
size_t *hash_length);
/**
- * \brief Finalises a hash context operation, verifying that the final hash
+ * \brief Finalise a hash context operation, verifying that the final hash
* value matches the one provided as input (veneer function)
*
- * \param[in] operation Hash operation context
- * \param[in] hash Buffer containing the provided hash value
- * \param[in] hash_length Size of the provided hash value
+ * \note A successful call to this function releases the hash operation
+ * context provided as parameter. The hash operation is released
+ * also in case TFM_CRYPTO_ERR_PSA_ERROR_INVALID_SIGNATURE is returned
*
- * \return Returns values as described in \ref tfm_crypto_err_t
+ * \param[in/out] operation Hash operation context
+ * \param[in] hash Buffer containing the provided hash value
+ * \param[in] hash_length Size of the provided hash value
+ *
+ * \return Return values as described in \ref tfm_crypto_err_t
*/
enum tfm_crypto_err_t tfm_crypto_veneer_hash_verify(
psa_hash_operation_t *operation,
const uint8_t *hash,
size_t hash_length);
/**
- * \brief Aborts a hash operation, clears the operation context provided
+ * \brief Abort a hash operation, clears the operation context provided
* (veneer function)
*
- * \param[in] operation Hash operation context
+ * \note A successful call to this function releases the hash operation
+ * context provided as parameter
*
- * \return Returns values as described in \ref tfm_crypto_err_t
+ * \param[in/out] operation Hash operation context
+ *
+ * \return Return values as described in \ref tfm_crypto_err_t
*/
enum tfm_crypto_err_t tfm_crypto_veneer_hash_abort(
psa_hash_operation_t *operation);