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/secure_fw/services/crypto/tfm_crypto_api.h b/secure_fw/services/crypto/tfm_crypto_api.h
index d596ed9..488b432 100644
--- a/secure_fw/services/crypto/tfm_crypto_api.h
+++ b/secure_fw/services/crypto/tfm_crypto_api.h
@@ -34,41 +34,55 @@
};
/**
- * \brief Initialises the service
+ * \brief Initialise the service
*
- * \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_init(void);
/**
- * \brief Allocates an operation object
+ * \brief Initialise the Key module
+ *
+ * \return Return values as described in \ref tfm_crypto_err_t
+ */
+enum tfm_crypto_err_t tfm_crypto_init_key(void);
+
+/**
+ * \brief Initialise the Alloc module
+ *
+ * \return Return values as described in \ref tfm_crypto_err_t
+ */
+enum tfm_crypto_err_t tfm_crypto_init_alloc(void);
+
+/**
+ * \brief Allocate an operation object
*
* \param[in] type Type of the operation object to allocate
* \param[out] handle Pointer to the corresponding handle assigned
*
- * \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_operation_alloc(
enum tfm_crypto_operation_type type,
uint32_t *handle);
/**
- * \brief Releases an operation object
+ * \brief Release an operation object
*
* \param[in] handle Pointer to the handle for the release of the
* corresponding object
*
- * \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_operation_release(uint32_t *handle);
/**
- * \brief Looks up an operation object pointer from the corresponding handle
+ * \brief Look up an operation object pointer from the corresponding handle
*
* \param[in] type Type of the operation object to look up
* \param[in] handle Handle to the operation object to look up
* \param[out] oper Double pointer to the corresponding object
*
- * \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_operation_lookup(
enum tfm_crypto_operation_type type,
@@ -82,18 +96,18 @@
* \param[in] data Key data to import
* \param[in] data_length Length in bytes of the data field
*
- * \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_import_key(psa_key_slot_t key,
psa_key_type_t type,
const uint8_t *data,
size_t data_length);
/**
- * \brief Destroy the key on the provided key slot
+ * \brief Destroy the key in the provided key slot
*
* \param[in] key Key slot
*
- * \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_destroy_key(psa_key_slot_t key);
@@ -104,7 +118,7 @@
* \param[out] type Key type associated to the key slot requested
* \param[out] bits Length in bits of the key in the requested slot
*
- * \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_get_key_information(psa_key_slot_t key,
psa_key_type_t *type,
@@ -117,7 +131,7 @@
* \param[in] data_size Length of the buffer pointed to by data
* \param[out] data_length Length of the exported key
*
- * \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_export_key(psa_key_slot_t key,
uint8_t *data,
@@ -125,20 +139,19 @@
size_t *data_length);
/**
* \brief Export the public key contained in the provided key slot
- * for an asymmetric key pair.
+ * for an asymmetric key pair
*
* \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[out] data_length Length of the exported key
*
- * \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_export_public_key(psa_key_slot_t key,
uint8_t *data,
size_t data_size,
size_t *data_length);
-
/**
* \brief Set the initialisation vector on the provided cipher operation
*
@@ -146,7 +159,7 @@
* \param[in] iv Buffer that contains the IV
* \param[in] iv_length Length of the provided IV
*
- * \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_cipher_set_iv(
psa_cipher_operation_t *operation,
@@ -154,13 +167,16 @@
size_t iv_length);
/**
* \brief Set the cipher operation using the provided algorithm and key slot,
- * for encryption context.
+ * for encryption context
*
- * \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
*
- * \return Returns values as described in \ref tfm_crypto_err_t
+ * \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
*/
enum tfm_crypto_err_t tfm_crypto_cipher_encrypt_setup(
psa_cipher_operation_t *operation,
@@ -168,13 +184,16 @@
psa_algorithm_t alg);
/**
* \brief Set the cipher operation using the provided algorithm and key slot,
- * for decryption context.
+ * for decryption context
*
- * \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
*
- * \return Returns values as described in \ref tfm_crypto_err_t
+ * \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
*/
enum tfm_crypto_err_t tfm_crypto_cipher_decrypt_setup(
psa_cipher_operation_t *operation,
@@ -184,16 +203,16 @@
* \brief Update the cipher context with a chunk of input data to create a
* chunk of encrypted output data (for encryption contexts), or to
* decrypt a chunk of encrypted input data to obtain decrypted data
- * (for decryption contexts).
+ * (for decryption contexts)
*
- * \param[in] operation Cipher operation context
- * \param[in] input Buffer containing input data
- * \param[in] input_length Input length
- * \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
+ * \param[in/out] operation Cipher operation context
+ * \param[in] input Buffer containing input data
+ * \param[in] input_length Input length
+ * \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 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_cipher_update(
psa_cipher_operation_t *operation,
@@ -203,15 +222,18 @@
size_t output_size,
size_t *output_length);
/**
- * \brief Finalises a cipher context flushing out any remaining block of
+ * \brief Finalise a cipher context flushing out any remaining block of
* output data
*
- * \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 de-initialises the cipher operation
+ * context provided as parameter
*
- * \return Returns values as described in \ref tfm_crypto_err_t
+ * \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
*/
enum tfm_crypto_err_t tfm_crypto_cipher_finish(
psa_cipher_operation_t *operation,
@@ -219,70 +241,86 @@
size_t output_size,
size_t *output_length);
/**
- * \brief Aborts a cipher operation, clears the operation context provided
+ * \brief Abort a cipher operation, clears the operation context provided
*
- * \param[in] operation Cipher operation context
+ * \note A successful call to this function de-initialises the cipher operation
+ * context provided as parameter
*
- * \return Returns values as described in \ref tfm_crypto_err_t
+ * \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_cipher_abort(
psa_cipher_operation_t *operation);
/**
- * \brief Starts a hash operation with the provided algorithm
+ * \brief Start a hash operation with the provided algorithm
*
- * \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_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
*
* \param[in] 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_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
*
- * \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 de-initialises 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_hash_finish(psa_hash_operation_t *operation,
uint8_t *hash,
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
*
- * \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 de-initialises the hash operation
+ * context provided as parameter. The hash operation is de-initialised
+ * 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_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
*
- * \param[in] operation Hash operation context
+ * \note A successful call to this function de-initialises 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_hash_abort(psa_hash_operation_t *operation);