Update documentation
The return values of the functions are updated in the documetation.
All possible return values are added including nested functions' return
values. The values which cannot be returned are removed.
Signed-off-by: gabor-mezei-arm <gabor.mezei@arm.com>
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index b41a20b..66222c5 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -90,10 +90,15 @@
*
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_INVALID
+ * \retval #PSA_ERROR_DATA_CORRUPT
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
*/
psa_status_t psa_crypto_init(void);
@@ -501,7 +506,8 @@
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_INVALID
+ * \retval #PSA_ERROR_DATA_CORRUPT
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
@@ -540,7 +546,7 @@
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* There was an failure in communication with the cryptoprocessor.
* The key material may still be present in the cryptoprocessor.
- * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_INVALID
* The storage is corrupted. Implementations shall make a best effort
* to erase key material even in this stage, however applications
* should be aware that it may be impossible to guarantee that the
@@ -625,6 +631,8 @@
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_DATA_CORRUPT
+ * \retval #PSA_ERROR_DATA_INVALID
* \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
@@ -3556,7 +3564,8 @@
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_INVALID
+ * \retval #PSA_ERROR_DATA_CORRUPT
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
@@ -3721,7 +3730,8 @@
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
- * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_INVALID
+ * \retval #PSA_ERROR_DATA_CORRUPT
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
diff --git a/include/psa/crypto_compat.h b/include/psa/crypto_compat.h
index 339ef27..f593b6d 100644
--- a/include/psa/crypto_compat.h
+++ b/include/psa/crypto_compat.h
@@ -296,7 +296,8 @@
* through implementation-specific means.
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_INVALID
+ * \retval #PSA_ERROR_DATA_CORRUPT
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index b25addc..39d0e67 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -183,8 +183,10 @@
* \retval #PSA_ERROR_NOT_PERMITTED
* The caller is not authorized to register the specified key slot.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_DATA_INVALID
+ * \retval #PSA_ERROR_DATA_CORRUPT
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
diff --git a/include/psa/crypto_se_driver.h b/include/psa/crypto_se_driver.h
index 1fae575..77295b6 100644
--- a/include/psa/crypto_se_driver.h
+++ b/include/psa/crypto_se_driver.h
@@ -1378,6 +1378,9 @@
* `methods->hal_version` is not supported by this implementation.
* \return #PSA_ERROR_INSUFFICIENT_MEMORY
* \return #PSA_ERROR_NOT_PERMITTED
+ * \return #PSA_ERROR_STORAGE_FAILURE
+ * \return #PSA_ERROR_DATA_CORRUPT
+ * \return #PSA_ERROR_INVALID_ARGUMENT
*/
psa_status_t psa_register_se_driver(
psa_key_location_t location,
diff --git a/library/psa_crypto.c b/library/psa_crypto.c
index e1fce90..7258f72 100644
--- a/library/psa_crypto.c
+++ b/library/psa_crypto.c
@@ -2093,6 +2093,14 @@
*
* \retval #PSA_SUCCESS
* The key was successfully created.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
+ * \retval #PSA_ERROR_ALREADY_EXISTS
+ * \retval #PSA_ERROR_DATA_INVALID
+ * \retval #PSA_ERROR_DATA_CORRUPT
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
+ *
* \return If this function fails, the key slot is an invalid state.
* You must call psa_fail_key_creation() to wipe and free the slot.
*/
diff --git a/library/psa_crypto_its.h b/library/psa_crypto_its.h
index 6d94730..3a3f49a 100644
--- a/library/psa_crypto_its.h
+++ b/library/psa_crypto_its.h
@@ -100,6 +100,7 @@
* \retval #PSA_SUCCESS The operation completed successfully
* \retval #PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided `uid` value was not found in the storage
* \retval #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
+ * \retval #PSA_ERROR_DATA_CORRUPT The operation failed because stored data has been corrupted
* \retval #PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided pointers(`p_data`, `p_data_length`)
* is invalid. For example is `NULL` or references memory the caller cannot access.
* In addition, this can also happen if an invalid offset was provided.
diff --git a/library/psa_crypto_se.h b/library/psa_crypto_se.h
index 67fadf8..7104261 100644
--- a/library/psa_crypto_se.h
+++ b/library/psa_crypto_se.h
@@ -155,6 +155,13 @@
*
* \param driver The driver table entry containing the persistent
* data to load from storage.
+ *
+ * \return #PSA_SUCCESS
+ * \return #PSA_ERROR_NOT_SUPPORTED
+ * \return #PSA_ERROR_DOES_NOT_EXIST
+ * \return #PSA_ERROR_STORAGE_FAILURE
+ * \return #PSA_ERROR_DATA_CORRUPT
+ * \return #PSA_ERROR_INVALID_ARGUMENT
*/
psa_status_t psa_load_se_persistent_data(
const psa_se_drv_table_entry_t *driver );
@@ -163,6 +170,14 @@
*
* \param[in] driver The driver table entry containing the persistent
* data to save to storage.
+ *
+ * \return #PSA_SUCCESS
+ * \return #PSA_ERROR_NOT_SUPPORTED
+ * \return #PSA_ERROR_NOT_PERMITTED
+ * \return #PSA_ERROR_NOT_SUPPORTED
+ * \return #PSA_ERROR_INSUFFICIENT_STORAGE
+ * \return #PSA_ERROR_STORAGE_FAILURE
+ * \return #PSA_ERROR_INVALID_ARGUMENT
*/
psa_status_t psa_save_se_persistent_data(
const psa_se_drv_table_entry_t *driver );
diff --git a/library/psa_crypto_storage.c b/library/psa_crypto_storage.c
index aa55f0a..86e416d 100644
--- a/library/psa_crypto_storage.c
+++ b/library/psa_crypto_storage.c
@@ -91,7 +91,8 @@
* \param data_size Size of the \c data buffer in bytes.
*
* \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_INVALID
+ * \retval #PSA_ERROR_DATA_CORRUPT
* \retval #PSA_ERROR_DOES_NOT_EXIST
*/
static psa_status_t psa_crypto_storage_load(
@@ -138,9 +139,11 @@
* that make up the data.
*
* \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
- * \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_ALREADY_EXISTS
+ * \retval #PSA_ERROR_DATA_INVALID
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
+ * \retval #PSA_ERROR_DATA_CORRUPT
*/
static psa_status_t psa_crypto_storage_store( const mbedtls_svc_key_id_t key,
const uint8_t *data,
@@ -211,7 +214,9 @@
* \param[out] data_length The number of bytes that make up the data.
*
* \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
+ * \retval #PSA_ERROR_DATA_CORRUPT
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
*/
static psa_status_t psa_crypto_storage_get_data_length(
const mbedtls_svc_key_id_t key,
diff --git a/library/psa_crypto_storage.h b/library/psa_crypto_storage.h
index fbc94fc..a681690 100644
--- a/library/psa_crypto_storage.h
+++ b/library/psa_crypto_storage.h
@@ -96,8 +96,11 @@
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
- * \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_ALREADY_EXISTS
+ * \retval #PSA_ERROR_DATA_INVALID
+ * \retval #PSA_ERROR_DATA_CORRUPT
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
*/
psa_status_t psa_save_persistent_key( const psa_core_key_attributes_t *attr,
const uint8_t *data,
@@ -124,8 +127,10 @@
*
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_INVALID
+ * \retval #PSA_ERROR_DATA_CORRUPT
* \retval #PSA_ERROR_DOES_NOT_EXIST
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
*/
psa_status_t psa_load_persistent_key( psa_core_key_attributes_t *attr,
uint8_t **data,
@@ -140,7 +145,7 @@
* \retval #PSA_SUCCESS
* The key was successfully removed,
* or the key did not exist.
- * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_INVALID
*/
psa_status_t psa_destroy_persistent_key( const mbedtls_svc_key_id_t key );
@@ -183,9 +188,8 @@
* with the loaded key metadata.
*
* \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_INVALID
*/
psa_status_t psa_parse_key_data_from_storage( const uint8_t *storage_data,
size_t storage_data_length,
@@ -319,6 +323,7 @@
* atomically update the transaction state.
*
* \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_DATA_CORRUPT
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
* \retval #PSA_ERROR_STORAGE_FAILURE
*/
@@ -335,6 +340,9 @@
* \retval #PSA_ERROR_DOES_NOT_EXIST
* There is no ongoing transaction.
* \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_INVALID
+ * \retval #PSA_ERROR_DATA_CORRUPT
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
*/
psa_status_t psa_crypto_load_transaction( void );
