Add documentation describing behavior of not calling psa_crypto_init
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 92d394d..d976d7b 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -323,6 +323,14 @@
* 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 @@
* \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 @@
* 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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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,