From 1861709e5cb389f548515103ab8938c7517677c6 Mon Sep 17 00:00:00 2001 From: itayzafrir Date: Sun, 16 Sep 2018 12:22:41 +0300 Subject: [PATCH] Add documentation describing behavior of not calling psa_crypto_init --- include/psa/crypto.h | 77 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 92d394d5a..d976d7b18 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -323,6 +323,14 @@ typedef int32_t psa_status_t; * Applications may call this function more than once. Once a call * succeeds, subsequent calls are guaranteed to succeed. * + * If the application calls other functions before calling psa_crypto_init(), + * the behavior is undefined. Implementations are encouraged to either perform + * the operation as if the library had been initialized or to return + * #PSA_ERROR_BAD_STATE or some other applicable error. In particular, + * implementations should not return a success status if the lack of + * initialization may have security implications, for example due to improper + * seeding of the random number generator. + * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_COMMUNICATION_FAILURE @@ -1105,6 +1113,9 @@ typedef uint32_t psa_algorithm_t; * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_import_key(psa_key_slot_t key, psa_key_type_t type, @@ -1144,6 +1155,9 @@ psa_status_t psa_import_key(psa_key_slot_t key, * a communication failure occurred. The cryptoprocessor may have * been compromised. * \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 + * results in this error code. */ psa_status_t psa_destroy_key(psa_key_slot_t key); @@ -1165,6 +1179,9 @@ psa_status_t psa_destroy_key(psa_key_slot_t key); * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_get_key_information(psa_key_slot_t key, psa_key_type_t *type, @@ -1260,6 +1277,9 @@ psa_status_t psa_get_key_information(psa_key_slot_t key, * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_export_key(psa_key_slot_t key, uint8_t *data, @@ -1359,6 +1379,9 @@ psa_status_t psa_export_key(psa_key_slot_t key, * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_export_public_key(psa_key_slot_t key, uint8_t *data, @@ -1497,6 +1520,9 @@ psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy); * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_set_key_policy(psa_key_slot_t key, const psa_key_policy_t *policy); @@ -1511,6 +1537,9 @@ psa_status_t psa_set_key_policy(psa_key_slot_t key, * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_get_key_policy(psa_key_slot_t key, psa_key_policy_t *policy); @@ -1555,6 +1584,9 @@ typedef uint32_t psa_key_lifetime_t; * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_get_key_lifetime(psa_key_slot_t key, psa_key_lifetime_t *lifetime); @@ -1583,6 +1615,9 @@ psa_status_t psa_get_key_lifetime(psa_key_slot_t key, * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_set_key_lifetime(psa_key_slot_t key, psa_key_lifetime_t lifetime); @@ -1858,6 +1893,9 @@ typedef struct psa_mac_operation_s psa_mac_operation_t; * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation, psa_key_slot_t key, @@ -1907,6 +1945,9 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation, * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation, psa_key_slot_t key, @@ -2104,6 +2145,9 @@ typedef struct psa_cipher_operation_s psa_cipher_operation_t; * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, psa_key_slot_t key, @@ -2154,6 +2198,9 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation, psa_key_slot_t key, @@ -2398,6 +2445,9 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation); * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_aead_encrypt(psa_key_slot_t key, psa_algorithm_t alg, @@ -2452,6 +2502,9 @@ psa_status_t psa_aead_encrypt(psa_key_slot_t key, * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_aead_decrypt(psa_key_slot_t key, psa_algorithm_t alg, @@ -2516,6 +2569,9 @@ psa_status_t psa_aead_decrypt(psa_key_slot_t key, * \retval #PSA_ERROR_TAMPERING_DETECTED * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY * \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 + * results in this error code. */ psa_status_t psa_asymmetric_sign(psa_key_slot_t key, psa_algorithm_t alg, @@ -2556,6 +2612,9 @@ psa_status_t psa_asymmetric_sign(psa_key_slot_t key, * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_asymmetric_verify(psa_key_slot_t key, psa_algorithm_t alg, @@ -2611,6 +2670,9 @@ psa_status_t psa_asymmetric_verify(psa_key_slot_t key, * \retval #PSA_ERROR_TAMPERING_DETECTED * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY * \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 + * results in this error code. */ psa_status_t psa_asymmetric_encrypt(psa_key_slot_t key, psa_algorithm_t alg, @@ -2664,6 +2726,9 @@ psa_status_t psa_asymmetric_encrypt(psa_key_slot_t key, * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY * \retval #PSA_ERROR_INVALID_PADDING * \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 + * results in this error code. */ psa_status_t psa_asymmetric_decrypt(psa_key_slot_t key, psa_algorithm_t alg, @@ -2815,6 +2880,9 @@ psa_status_t psa_generator_read(psa_crypto_generator_t *generator, * \retval PSA_ERROR_HARDWARE_FAILURE * \retval PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_generator_import_key(psa_key_slot_t key, psa_key_type_t type, @@ -2889,6 +2957,9 @@ psa_status_t psa_generator_abort(psa_crypto_generator_t *generator); * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_key_derivation(psa_crypto_generator_t *generator, psa_key_slot_t key, @@ -2924,6 +2995,9 @@ psa_status_t psa_key_derivation(psa_crypto_generator_t *generator, * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_generate_random(uint8_t *output, size_t output_size); @@ -2979,6 +3053,9 @@ typedef struct { * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED * \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 + * results in this error code. */ psa_status_t psa_generate_key(psa_key_slot_t key, psa_key_type_t type,