From 2853849498e8a69ff237c52cea29b23d488cb307 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 11 Jul 2018 17:34:00 +0200 Subject: [PATCH 01/16] Doxygen: linkify references to macro names --- include/psa/crypto.h | 380 +++++++++++++++++++++---------------------- 1 file changed, 190 insertions(+), 190 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index a30af423a..f1c836834 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -301,12 +301,12 @@ typedef int32_t psa_status_t; * Applications may call this function more than once. Once a call * succeeds, subsequent calls are guaranteed to succeed. * - * \retval PSA_SUCCESS - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED - * \retval PSA_ERROR_INSUFFICIENT_ENTROPY + * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY */ psa_status_t psa_crypto_init(void); @@ -354,7 +354,7 @@ typedef uint32_t psa_key_type_t; * used for. * * HMAC keys should generally have the same size as the underlying hash. - * This size can be calculated with `PSA_HASH_SIZE(alg)` where + * This size can be calculated with #PSA_HASH_SIZE(`alg`) where * `alg` is the HMAC algorithm or the underlying hash algorithm. */ #define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x02000001) /** Key for an cipher, AEAD or MAC algorithm based on the AES block cipher. @@ -802,21 +802,21 @@ typedef uint32_t psa_algorithm_t; * \param data Buffer containing the key data. * \param data_length Size of the \c data buffer in bytes. * - * \retval PSA_SUCCESS + * \retval #PSA_SUCCESS * Success. - * \retval PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_NOT_SUPPORTED * The key type or key size is not supported, either by the * implementation in general or in this particular slot. - * \retval PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_INVALID_ARGUMENT * The key slot is invalid, * or the key data is not correctly formatted. - * \retval PSA_ERROR_OCCUPIED_SLOT + * \retval #PSA_ERROR_OCCUPIED_SLOT * There is already a key in the specified slot. - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_INSUFFICIENT_STORAGE - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_INSUFFICIENT_STORAGE + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_import_key(psa_key_slot_t key, psa_key_type_t type, @@ -836,22 +836,22 @@ psa_status_t psa_import_key(psa_key_slot_t key, * * \param key The key slot to erase. * - * \retval PSA_SUCCESS + * \retval #PSA_SUCCESS * The slot's content, if any, has been erased. - * \retval PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_NOT_PERMITTED * The slot holds content and cannot be erased because it is * read-only, either due to a policy or due to physical restrictions. - * \retval PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_INVALID_ARGUMENT * The specified slot number does not designate a valid slot. - * \retval PSA_ERROR_COMMUNICATION_FAILURE + * \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_STORAGE_FAILURE * 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 * key material is not recoverable in such cases. - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_TAMPERING_DETECTED * An unexpected condition which is not a storage corruption or * a communication failure occurred. The cryptoprocessor may have * been compromised. @@ -870,11 +870,11 @@ psa_status_t psa_destroy_key(psa_key_slot_t key); * This may be a null pointer, in which case the key size * is not written. * - * \retval PSA_SUCCESS - * \retval PSA_ERROR_EMPTY_SLOT - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_EMPTY_SLOT + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_get_key_information(psa_key_slot_t key, psa_key_type_t *type, @@ -912,12 +912,12 @@ psa_status_t psa_get_key_information(psa_key_slot_t key, * \param data_length On success, the number of bytes * that make up the key data. * - * \retval PSA_SUCCESS - * \retval PSA_ERROR_EMPTY_SLOT - * \retval PSA_ERROR_NOT_PERMITTED - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_EMPTY_SLOT + * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_export_key(psa_key_slot_t key, uint8_t *data, @@ -943,12 +943,12 @@ psa_status_t psa_export_key(psa_key_slot_t key, * \param data_length On success, the number of bytes * that make up the key data. * - * \retval PSA_SUCCESS - * \retval PSA_ERROR_EMPTY_SLOT - * \retval PSA_ERROR_INVALID_ARGUMENT - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_EMPTY_SLOT + * \retval #PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_export_public_key(psa_key_slot_t key, uint8_t *data, @@ -1075,13 +1075,13 @@ typedef uint32_t psa_key_lifetime_t; * \param key Slot to query. * \param lifetime On success, the lifetime value. * - * \retval PSA_SUCCESS + * \retval #PSA_SUCCESS * Success. - * \retval PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_INVALID_ARGUMENT * The key slot is invalid. - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_get_key_lifetime(psa_key_slot_t key, psa_key_lifetime_t *lifetime); @@ -1095,20 +1095,20 @@ psa_status_t psa_get_key_lifetime(psa_key_slot_t key, * \param key Slot whose lifetime is to be changed. * \param lifetime The lifetime value to set for the given key slot. * - * \retval PSA_SUCCESS + * \retval #PSA_SUCCESS * Success. - * \retval PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_INVALID_ARGUMENT * The key slot is invalid, * or the lifetime value is invalid. - * \retval PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_NOT_SUPPORTED * The implementation does not support the specified lifetime value, * at least for the specified key slot. - * \retval PSA_ERROR_OCCUPIED_SLOT + * \retval #PSA_ERROR_OCCUPIED_SLOT * The slot contains a key, and the implementation does not support * changing the lifetime of an occupied slot. - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_set_key_lifetime(psa_key_slot_t key, psa_key_lifetime_t lifetime); @@ -1132,7 +1132,7 @@ typedef struct psa_hash_operation_s psa_hash_operation_t; * * \param alg A hash algorithm (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_HASH(alg) is true), or an HMAC algorithm - * (`PSA_ALG_HMAC(hash_alg)` where `hash_alg` is a + * (#PSA_ALG_HMAC(`hash_alg`) where `hash_alg` is a * hash algorithm). * * \return The hash size for the specified hash algorithm. @@ -1185,14 +1185,14 @@ typedef struct psa_hash_operation_s psa_hash_operation_t; * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value * such that #PSA_ALG_IS_HASH(alg) is true). * - * \retval PSA_SUCCESS + * \retval #PSA_SUCCESS * Success. - * \retval PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_NOT_SUPPORTED * \c alg is not supported or is not a hash algorithm. - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_hash_setup(psa_hash_operation_t *operation, psa_algorithm_t alg); @@ -1207,14 +1207,14 @@ psa_status_t psa_hash_setup(psa_hash_operation_t *operation, * \param input Buffer containing the message fragment to hash. * \param input_length Size of the \c input buffer in bytes. * - * \retval PSA_SUCCESS + * \retval #PSA_SUCCESS * Success. - * \retval PSA_ERROR_BAD_STATE + * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (not started, or already completed). - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_hash_update(psa_hash_operation_t *operation, const uint8_t *input, @@ -1244,18 +1244,18 @@ psa_status_t psa_hash_update(psa_hash_operation_t *operation, * #PSA_HASH_SIZE(alg) where \c alg is the * hash algorithm that is calculated. * - * \retval PSA_SUCCESS + * \retval #PSA_SUCCESS * Success. - * \retval PSA_ERROR_BAD_STATE + * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (not started, or already completed). - * \retval PSA_ERROR_BUFFER_TOO_SMALL + * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \c hash buffer is too small. You can determine a * sufficient buffer size by calling #PSA_HASH_SIZE(alg) * where \c alg is the hash algorithm that is calculated. - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_hash_finish(psa_hash_operation_t *operation, uint8_t *hash, @@ -1281,17 +1281,17 @@ psa_status_t psa_hash_finish(psa_hash_operation_t *operation, * \param hash Buffer containing the expected hash value. * \param hash_length Size of the \c hash buffer in bytes. * - * \retval PSA_SUCCESS + * \retval #PSA_SUCCESS * The expected hash is identical to the actual hash of the message. - * \retval PSA_ERROR_INVALID_SIGNATURE + * \retval #PSA_ERROR_INVALID_SIGNATURE * The hash of the message was calculated successfully, but it * differs from the expected hash. - * \retval PSA_ERROR_BAD_STATE + * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (not started, or already completed). - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_hash_verify(psa_hash_operation_t *operation, const uint8_t *hash, @@ -1311,12 +1311,12 @@ psa_status_t psa_hash_verify(psa_hash_operation_t *operation, * * \param operation Active hash operation. * - * \retval PSA_SUCCESS - * \retval PSA_ERROR_BAD_STATE + * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_BAD_STATE * \c operation is not an active hash operation. - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_hash_abort(psa_hash_operation_t *operation); @@ -1365,18 +1365,18 @@ typedef struct psa_mac_operation_s psa_mac_operation_t; * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value * such that #PSA_ALG_IS_MAC(alg) is true). * - * \retval PSA_SUCCESS + * \retval #PSA_SUCCESS * Success. - * \retval PSA_ERROR_EMPTY_SLOT - * \retval PSA_ERROR_NOT_PERMITTED - * \retval PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_EMPTY_SLOT + * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_ARGUMENT * \c key is not compatible with \c alg. - * \retval PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_NOT_SUPPORTED * \c alg is not supported or is not a MAC algorithm. - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation, psa_key_slot_t key, @@ -1413,18 +1413,18 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation, * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value * such that #PSA_ALG_IS_MAC(alg) is true). * - * \retval PSA_SUCCESS + * \retval #PSA_SUCCESS * Success. - * \retval PSA_ERROR_EMPTY_SLOT - * \retval PSA_ERROR_NOT_PERMITTED - * \retval PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_EMPTY_SLOT + * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_ARGUMENT * \c key is not compatible with \c alg. - * \retval PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_NOT_SUPPORTED * \c alg is not supported or is not a MAC algorithm. - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation, psa_key_slot_t key, @@ -1490,18 +1490,18 @@ typedef struct psa_cipher_operation_s psa_cipher_operation_t; * \param alg The cipher algorithm to compute (\c PSA_ALG_XXX value * such that #PSA_ALG_IS_CIPHER(alg) is true). * - * \retval PSA_SUCCESS + * \retval #PSA_SUCCESS * Success. - * \retval PSA_ERROR_EMPTY_SLOT - * \retval PSA_ERROR_NOT_PERMITTED - * \retval PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_EMPTY_SLOT + * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_ARGUMENT * \c key is not compatible with \c alg. - * \retval PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_NOT_SUPPORTED * \c alg is not supported or is not a cipher algorithm. - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, psa_key_slot_t key, @@ -1538,18 +1538,18 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, * \param alg The cipher algorithm to compute (\c PSA_ALG_XXX value * such that #PSA_ALG_IS_CIPHER(alg) is true). * - * \retval PSA_SUCCESS + * \retval #PSA_SUCCESS * Success. - * \retval PSA_ERROR_EMPTY_SLOT - * \retval PSA_ERROR_NOT_PERMITTED - * \retval PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_EMPTY_SLOT + * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_ARGUMENT * \c key is not compatible with \c alg. - * \retval PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_NOT_SUPPORTED * \c alg is not supported or is not a cipher algorithm. - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation, psa_key_slot_t key, @@ -1632,18 +1632,18 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation); * \param ciphertext_length On success, the size of the output * in the \b ciphertext buffer. * - * \retval PSA_SUCCESS + * \retval #PSA_SUCCESS * Success. - * \retval PSA_ERROR_EMPTY_SLOT - * \retval PSA_ERROR_NOT_PERMITTED - * \retval PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_EMPTY_SLOT + * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_ARGUMENT * \c key is not compatible with \c alg. - * \retval PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_NOT_SUPPORTED * \c alg is not supported or is not an AEAD algorithm. - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_aead_encrypt( psa_key_slot_t key, psa_algorithm_t alg, @@ -1683,20 +1683,20 @@ psa_status_t psa_aead_encrypt( psa_key_slot_t key, * \param plaintext_length On success, the size of the output * in the \b plaintext buffer. * - * \retval PSA_SUCCESS + * \retval #PSA_SUCCESS * Success. - * \retval PSA_ERROR_EMPTY_SLOT - * \retval PSA_ERROR_INVALID_SIGNATURE + * \retval #PSA_ERROR_EMPTY_SLOT + * \retval #PSA_ERROR_INVALID_SIGNATURE * The ciphertext is not authentic. - * \retval PSA_ERROR_NOT_PERMITTED - * \retval PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_ARGUMENT * \c key is not compatible with \c alg. - * \retval PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_NOT_SUPPORTED * \c alg is not supported or is not an AEAD algorithm. - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_aead_decrypt( psa_key_slot_t key, psa_algorithm_t alg, @@ -1755,20 +1755,20 @@ psa_status_t psa_aead_decrypt( psa_key_slot_t key, * \param signature_length On success, the number of bytes * that make up the returned signature value. * - * \retval PSA_SUCCESS - * \retval PSA_ERROR_BUFFER_TOO_SMALL + * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \c signature buffer is too small. You can * determine a sufficient buffer size by calling * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) * where \c key_type and \c key_bits are the type and bit-size * respectively of \c key. - * \retval PSA_ERROR_NOT_SUPPORTED - * \retval PSA_ERROR_INVALID_ARGUMENT - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED - * \retval PSA_ERROR_INSUFFICIENT_ENTROPY + * \retval #PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY */ psa_status_t psa_asymmetric_sign(psa_key_slot_t key, psa_algorithm_t alg, @@ -1808,17 +1808,17 @@ psa_status_t psa_asymmetric_sign(psa_key_slot_t key, * \param signature Buffer containing the signature to verify. * \param signature_length Size of the \c signature buffer in bytes. * - * \retval PSA_SUCCESS + * \retval #PSA_SUCCESS * The signature is valid. - * \retval PSA_ERROR_INVALID_SIGNATURE + * \retval #PSA_ERROR_INVALID_SIGNATURE * The calculation was perfomed successfully, but the passed * signature is not a valid signature. - * \retval PSA_ERROR_NOT_SUPPORTED - * \retval PSA_ERROR_INVALID_ARGUMENT - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_asymmetric_verify(psa_key_slot_t key, psa_algorithm_t alg, @@ -1860,20 +1860,20 @@ psa_status_t psa_asymmetric_verify(psa_key_slot_t key, * \param output_length On success, the number of bytes * that make up the returned output. * - * \retval PSA_SUCCESS - * \retval PSA_ERROR_BUFFER_TOO_SMALL + * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \c output buffer is too small. You can * determine a sufficient buffer size by calling * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) * where \c key_type and \c key_bits are the type and bit-size * respectively of \c key. - * \retval PSA_ERROR_NOT_SUPPORTED - * \retval PSA_ERROR_INVALID_ARGUMENT - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED - * \retval PSA_ERROR_INSUFFICIENT_ENTROPY + * \retval #PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY */ psa_status_t psa_asymmetric_encrypt(psa_key_slot_t key, psa_algorithm_t alg, @@ -1910,21 +1910,21 @@ psa_status_t psa_asymmetric_encrypt(psa_key_slot_t key, * \param output_length On success, the number of bytes * that make up the returned output. * - * \retval PSA_SUCCESS - * \retval PSA_ERROR_BUFFER_TOO_SMALL + * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \c output buffer is too small. You can * determine a sufficient buffer size by calling * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) * where \c key_type and \c key_bits are the type and bit-size * respectively of \c key. - * \retval PSA_ERROR_NOT_SUPPORTED - * \retval PSA_ERROR_INVALID_ARGUMENT - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED - * \retval PSA_ERROR_INSUFFICIENT_ENTROPY - * \retval PSA_ERROR_INVALID_PADDING + * \retval #PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY + * \retval #PSA_ERROR_INVALID_PADDING */ psa_status_t psa_asymmetric_decrypt(psa_key_slot_t key, psa_algorithm_t alg, @@ -1954,12 +1954,12 @@ psa_status_t psa_asymmetric_decrypt(psa_key_slot_t key, * \param output Output buffer for the generated data. * \param output_size Number of bytes to generate and output. * - * \retval PSA_SUCCESS - * \retval PSA_ERROR_NOT_SUPPORTED - * \retval PSA_ERROR_INSUFFICIENT_ENTROPY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_generate_random(uint8_t *output, size_t output_size); @@ -1979,8 +1979,8 @@ psa_status_t psa_generate_random(uint8_t *output, * \param parameters_size Size of the buffer that \p parameters * points to, in bytes. * - * For any symmetric key type (type such that - * `PSA_KEY_TYPE_IS_ASYMMETRIC(type)` is false), \c parameters must be + * For any symmetric key type (a type such that + * #PSA_KEY_TYPE_IS_ASYMMETRIC(`type`) is false), \c parameters must be * \c NULL. For asymmetric key types defined by this specification, * the parameter type and the default parameters are defined by the * table below. For vendor-defined key types, the vendor documentation @@ -1990,14 +1990,14 @@ psa_status_t psa_generate_random(uint8_t *output, * ---- | -------------- | ------- | --------------------------------------- * `PSA_KEY_TYPE_RSA_KEYPAIR` | `unsigned int` | Public exponent | 65537 * - * \retval PSA_SUCCESS - * \retval PSA_ERROR_NOT_SUPPORTED - * \retval PSA_ERROR_INVALID_ARGUMENT - * \retval PSA_ERROR_INSUFFICIENT_MEMORY - * \retval PSA_ERROR_INSUFFICIENT_ENTROPY - * \retval PSA_ERROR_COMMUNICATION_FAILURE - * \retval PSA_ERROR_HARDWARE_FAILURE - * \retval PSA_ERROR_TAMPERING_DETECTED + * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_generate_key(psa_key_slot_t key, psa_key_type_t type, From 5d1888ebc547535294f20e9041680911b5d99e1b Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 12 Jul 2018 00:32:42 +0200 Subject: [PATCH 02/16] Rename PSA_ALG_STREAM_CIPHER -> PSA_ALG_STREAM_CIPHER_BASE Follow the usual naming convention: PSA_ALG_xxx_BASE for a constant that isn't an algorithm, just used to build one. --- include/psa/crypto.h | 5 +++-- library/psa_crypto.c | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index f1c836834..95fe42d69 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -610,13 +610,14 @@ typedef uint32_t psa_algorithm_t; #define PSA_ALG_CFB_BASE ((psa_algorithm_t)0x04000002) #define PSA_ALG_OFB_BASE ((psa_algorithm_t)0x04000003) #define PSA_ALG_XTS_BASE ((psa_algorithm_t)0x04000004) -#define PSA_ALG_STREAM_CIPHER ((psa_algorithm_t)0x04800000) + +#define PSA_ALG_STREAM_CIPHER_BASE ((psa_algorithm_t)0x04800000) #define PSA_ALG_CTR ((psa_algorithm_t)0x04800001) #define PSA_ALG_ARC4 ((psa_algorithm_t)0x04800002) #define PSA_ALG_IS_STREAM_CIPHER(alg) \ (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_CIPHER_SUBCATEGORY_MASK)) == \ - PSA_ALG_STREAM_CIPHER) + PSA_ALG_STREAM_CIPHER_BASE) #define PSA_ALG_CCM ((psa_algorithm_t)0x06000001) #define PSA_ALG_GCM ((psa_algorithm_t)0x06000002) diff --git a/library/psa_crypto.c b/library/psa_crypto.c index 9145a6df1..50a99904c 100644 --- a/library/psa_crypto.c +++ b/library/psa_crypto.c @@ -1191,7 +1191,7 @@ static const mbedtls_cipher_info_t *mbedtls_cipher_info_from_psa( switch( alg ) { - case PSA_ALG_STREAM_CIPHER: + case PSA_ALG_STREAM_CIPHER_BASE: mode = MBEDTLS_MODE_STREAM; break; case PSA_ALG_CBC_BASE: From 5ce3e59dfe3d79e2a0196cea426bd9fdf25be492 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 12 Jul 2018 00:35:06 +0200 Subject: [PATCH 03/16] Doc: PSA_ALG_IS_HASH is unspecified if alg is not *supported* --- include/psa/crypto.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 95fe42d69..fb7edf83c 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -531,7 +531,7 @@ typedef uint32_t psa_algorithm_t; * \param alg An algorithm identifier (value of type #psa_algorithm_t). * * \return 1 if \c alg is a hash algorithm, 0 otherwise. - * This macro may return either 0 or 1 if \c alg is not a valid + * This macro may return either 0 or 1 if \c alg is not a supported * algorithm identifier. */ #define PSA_ALG_IS_HASH(alg) \ From dcd149432700c971d2709eb1533f4b5896d448c9 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 12 Jul 2018 00:30:52 +0200 Subject: [PATCH 04/16] Doc: write documentation for many macros and functions As of this commit, all #identifier links in the documentation are resolved. --- include/psa/crypto.h | 437 +++++++++++++++++++++++++++++++++++++ include/psa/crypto_sizes.h | 54 ++++- 2 files changed, 490 insertions(+), 1 deletion(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index fb7edf83c..34ab8e112 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -339,11 +339,13 @@ typedef uint32_t psa_key_type_t; #define PSA_KEY_TYPE_VENDOR_FLAG ((psa_key_type_t)0x80000000) #define PSA_KEY_TYPE_CATEGORY_MASK ((psa_key_type_t)0x7e000000) + /** Raw data. * * A "key" of this type cannot be used for any cryptographic operation. * Applications may use this type to store arbitrary data in the keystore. */ #define PSA_KEY_TYPE_RAW_DATA ((psa_key_type_t)0x02000000) + #define PSA_KEY_TYPE_CATEGORY_SYMMETRIC ((psa_key_type_t)0x04000000) #define PSA_KEY_TYPE_CATEGORY_ASYMMETRIC ((psa_key_type_t)0x06000000) #define PSA_KEY_TYPE_PAIR_FLAG ((psa_key_type_t)0x01000000) @@ -357,12 +359,14 @@ typedef uint32_t psa_key_type_t; * This size can be calculated with #PSA_HASH_SIZE(`alg`) where * `alg` is the HMAC algorithm or the underlying hash algorithm. */ #define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x02000001) + /** Key for an cipher, AEAD or MAC algorithm based on the AES block cipher. * * The size of the key can be 16 bytes (AES-128), 24 bytes (AES-192) or * 32 bytes (AES-256). */ #define PSA_KEY_TYPE_AES ((psa_key_type_t)0x04000001) + /** Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES). * * The size of the key can be 8 bytes (single DES), 16 bytes (2-key 3DES) or @@ -373,9 +377,11 @@ typedef uint32_t psa_key_type_t; * is weak and deprecated and should only be used in legacy protocols. */ #define PSA_KEY_TYPE_DES ((psa_key_type_t)0x04000002) + /** Key for an cipher, AEAD or MAC algorithm based on the * Camellia block cipher. */ #define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x04000003) + /** Key for the RC4 stream cipher. * * Note that RC4 is weak and deprecated and should only be used in @@ -386,15 +392,19 @@ typedef uint32_t psa_key_type_t; #define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x06010000) /** RSA key pair (private and public key). */ #define PSA_KEY_TYPE_RSA_KEYPAIR ((psa_key_type_t)0x07010000) + /** DSA public key. */ #define PSA_KEY_TYPE_DSA_PUBLIC_KEY ((psa_key_type_t)0x06020000) /** DSA key pair (private and public key). */ #define PSA_KEY_TYPE_DSA_KEYPAIR ((psa_key_type_t)0x07020000) + #define PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE ((psa_key_type_t)0x06030000) #define PSA_KEY_TYPE_ECC_KEYPAIR_BASE ((psa_key_type_t)0x07030000) #define PSA_KEY_TYPE_ECC_CURVE_MASK ((psa_key_type_t)0x0000ffff) +/** Elliptic curve key pair. */ #define PSA_KEY_TYPE_ECC_KEYPAIR(curve) \ (PSA_KEY_TYPE_ECC_KEYPAIR_BASE | (curve)) +/** Elliptic curve public key. */ #define PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) \ (PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE | (curve)) @@ -526,6 +536,7 @@ typedef uint32_t psa_algorithm_t; #define PSA_ALG_IS_VENDOR_DEFINED(alg) \ (((alg) & PSA_ALG_VENDOR_FLAG) != 0) + /** Whether the specified algorithm is a hash algorithm. * * \param alg An algorithm identifier (value of type #psa_algorithm_t). @@ -536,18 +547,82 @@ typedef uint32_t psa_algorithm_t; */ #define PSA_ALG_IS_HASH(alg) \ (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_HASH) + +/** Whether the specified algorithm is a MAC algorithm. + * + * \param alg An algorithm identifier (value of type #psa_algorithm_t). + * + * \return 1 if \c alg is a MAC algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \c alg is not a supported + * algorithm identifier. + */ #define PSA_ALG_IS_MAC(alg) \ (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_MAC) + +/** Whether the specified algorithm is a symmetric cipher algorithm. + * + * \param alg An algorithm identifier (value of type #psa_algorithm_t). + * + * \return 1 if \c alg is a symmetric cipher algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \c alg is not a supported + * algorithm identifier. + */ #define PSA_ALG_IS_CIPHER(alg) \ (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_CIPHER) + +/** Whether the specified algorithm is an authenticated encryption + * with associated data (AEAD) algorithm. + * + * \param alg An algorithm identifier (value of type #psa_algorithm_t). + * + * \return 1 if \c alg is an AEAD algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \c alg is not a supported + * algorithm identifier. + */ #define PSA_ALG_IS_AEAD(alg) \ (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_AEAD) + +/** Whether the specified algorithm is a public-key signature algorithm. + * + * \param alg An algorithm identifier (value of type #psa_algorithm_t). + * + * \return 1 if \c alg is a public-key signature algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \c alg is not a supported + * algorithm identifier. + */ #define PSA_ALG_IS_SIGN(alg) \ (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_SIGN) + +/** Whether the specified algorithm is a public-key encryption algorithm. + * + * \param alg An algorithm identifier (value of type #psa_algorithm_t). + * + * \return 1 if \c alg is a public-key encryption algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \c alg is not a supported + * algorithm identifier. + */ #define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg) \ (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION) + +/** Whether the specified algorithm is a key agreement algorithm. + * + * \param alg An algorithm identifier (value of type #psa_algorithm_t). + * + * \return 1 if \c alg is a key agreement algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \c alg is not a supported + * algorithm identifier. + */ #define PSA_ALG_IS_KEY_AGREEMENT(alg) \ (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_AGREEMENT) + +/** Whether the specified algorithm is a key derivation algorithm. + * + * \param alg An algorithm identifier (value of type #psa_algorithm_t). + * + * \return 1 if \c alg is a key derivation algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \c alg is not a supported + * algorithm identifier. + */ #define PSA_ALG_IS_KEY_DERIVATION(alg) \ (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_DERIVATION) @@ -583,15 +658,35 @@ typedef uint32_t psa_algorithm_t; */ #define PSA_ALG_HMAC(hash_alg) \ (PSA_ALG_HMAC_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) + #define PSA_ALG_HMAC_HASH(hmac_alg) \ (PSA_ALG_CATEGORY_HASH | ((hmac_alg) & PSA_ALG_HASH_MASK)) + +/** Whether the specified algorithm is an HMAC algorithm. + * + * HMAC is a family of MAC algorithms that are based on a hash function. + * + * \param alg An algorithm identifier (value of type #psa_algorithm_t). + * + * \return 1 if \c alg is an HMAC algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \c alg is not a supported + * algorithm identifier. + */ #define PSA_ALG_IS_HMAC(alg) \ (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_MAC_SUBCATEGORY_MASK)) == \ PSA_ALG_HMAC_BASE) + #define PSA_ALG_CIPHER_MAC_BASE ((psa_algorithm_t)0x02c00000) #define PSA_ALG_CBC_MAC ((psa_algorithm_t)0x02c00001) #define PSA_ALG_CMAC ((psa_algorithm_t)0x02c00002) #define PSA_ALG_GMAC ((psa_algorithm_t)0x02c00003) + +/** Whether the specified algorithm is a MAC algorithm based on a block cipher. + * + * \return 1 if \c alg is a MAC algorithm based on a block cipher, 0 otherwise. + * This macro may return either 0 or 1 if \c alg is not a supported + * algorithm identifier. + */ #define PSA_ALG_IS_CIPHER_MAC(alg) \ (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_MAC_SUBCATEGORY_MASK)) == \ PSA_ALG_CIPHER_MAC_BASE) @@ -600,21 +695,71 @@ typedef uint32_t psa_algorithm_t; #define PSA_ALG_BLOCK_CIPHER_BASE ((psa_algorithm_t)0x04000000) #define PSA_ALG_BLOCK_CIPHER_MODE_MASK ((psa_algorithm_t)0x000000ff) #define PSA_ALG_BLOCK_CIPHER_PADDING_MASK ((psa_algorithm_t)0x003f0000) + +/** Use a block cipher mode without padding. + * + * This padding mode may only be used with messages whose lengths are a + * whole number of blocks for the chosen block cipher. + */ #define PSA_ALG_BLOCK_CIPHER_PAD_NONE ((psa_algorithm_t)0x00000000) #define PSA_ALG_BLOCK_CIPHER_PAD_PKCS7 ((psa_algorithm_t)0x00010000) + +/** Whether the specified algorithm is a block cipher. + * + * A block cipher is a symmetric cipher that encrypts or decrypts messages + * by chopping them into fixed-size blocks. Processing a message requires + * applying a _padding mode_ to transform the message into one whose + * length is a whole number of blocks. To construct an algorithm + * identifier for a block cipher, apply a bitwise-or between the block + * cipher mode and the padding mode. For example, CBC with PKCS#7 padding + * is `PSA_ALG_CBC_BASE | PSA_ALG_BLOCK_CIPHER_PAD_PKCS7`. + * + * The transformation applied to each block is determined by the key type. + * For example, to use AES-128-CBC-PKCS7, use the algorithm above with + * a key of type #PSA_KEY_TYPE_AES and a length of 128 bits (16 bytes). + * + * \param alg An algorithm identifier (value of type #psa_algorithm_t). + * + * \return 1 if \c alg is a block cipher algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \c alg is not a supported + * algorithm identifier or if it is not a symmetric cipher algorithm. + */ #define PSA_ALG_IS_BLOCK_CIPHER(alg) \ (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_CIPHER_SUBCATEGORY_MASK)) == \ PSA_ALG_BLOCK_CIPHER_BASE) +/** The CBC block cipher mode. + */ #define PSA_ALG_CBC_BASE ((psa_algorithm_t)0x04000001) #define PSA_ALG_CFB_BASE ((psa_algorithm_t)0x04000002) #define PSA_ALG_OFB_BASE ((psa_algorithm_t)0x04000003) #define PSA_ALG_XTS_BASE ((psa_algorithm_t)0x04000004) #define PSA_ALG_STREAM_CIPHER_BASE ((psa_algorithm_t)0x04800000) +/** The CTR stream cipher mode. + * + * CTR is a stream cipher which is built from a block cipher. The + * underlying block cipher is determined by the key type. For example, + * to use AES-128-CTR, use this algorithm with + * a key of type #PSA_KEY_TYPE_AES and a length of 128 bits (16 bytes). + */ #define PSA_ALG_CTR ((psa_algorithm_t)0x04800001) +/** The ARC4 stream cipher algorithm. + */ #define PSA_ALG_ARC4 ((psa_algorithm_t)0x04800002) +/** Whether the specified algorithm is a stream cipher. + * + * A stream cipher is a symmetric cipher that encrypts or decrypts messages + * by applying a bitwise-xor with a stream of bytes that is generated + * from a key. + * + * \param alg An algorithm identifier (value of type #psa_algorithm_t). + * + * \return 1 if \c alg is a stream cipher algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \c alg is not a supported + * algorithm identifier or if it is not a symmetric cipher algorithm. + */ #define PSA_ALG_IS_STREAM_CIPHER(alg) \ (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_CIPHER_SUBCATEGORY_MASK)) == \ PSA_ALG_STREAM_CIPHER_BASE) @@ -647,6 +792,7 @@ typedef uint32_t psa_algorithm_t; #define PSA_ALG_RSA_PKCS1V15_SIGN_RAW PSA_ALG_RSA_PKCS1V15_SIGN_BASE #define PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) \ (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_PKCS1V15_SIGN_BASE) + #define PSA_ALG_RSA_PSS_BASE ((psa_algorithm_t)0x10030000) /** RSA PSS signature with hashing. * @@ -777,8 +923,25 @@ typedef uint32_t psa_algorithm_t; ((alg) & PSA_ALG_HASH_MASK) | PSA_ALG_CATEGORY_HASH : \ 0) +/** RSA PKCS#1 v1.5 encryption. + */ #define PSA_ALG_RSA_PKCS1V15_CRYPT ((psa_algorithm_t)0x12020000) + #define PSA_ALG_RSA_OAEP_BASE ((psa_algorithm_t)0x12030000) +/** RSA OAEP encryption. + * + * This is the encryption scheme defined by RFC 8017 + * (PKCS#1: RSA Cryptography Specifications) under the name + * RSAES-OAEP, with the message generation function MGF1. + * + * \param hash_alg The hash algorithm (\c PSA_ALG_XXX value such that + * #PSA_ALG_IS_HASH(\p hash_alg) is true) to use + * for MGF1. + * + * \return The corresponding RSA OAEP signature algorithm. + * \return Unspecified if \p alg is not a supported + * hash algorithm. + */ #define PSA_ALG_RSA_OAEP(hash_alg) \ (PSA_ALG_RSA_OAEP_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) #define PSA_ALG_IS_RSA_OAEP(alg) \ @@ -979,24 +1142,42 @@ typedef uint32_t psa_key_usage_t; #define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t)0x00000001) /** Whether the key may be used to encrypt a message. + * + * This flag allows the key to be used for a symmetric encryption operation, + * for an AEAD encryption-and-authentication operation, + * or for an asymmetric encryption operation, + * if otherwise permitted by the key's type and policy. * * For a key pair, this concerns the public key. */ #define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t)0x00000100) /** Whether the key may be used to decrypt a message. + * + * This flag allows the key to be used for a symmetric decryption operation, + * for an AEAD decryption-and-verification operation, + * or for an asymmetric decryption operation, + * if otherwise permitted by the key's type and policy. * * For a key pair, this concerns the private key. */ #define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200) /** Whether the key may be used to sign a message. + * + * This flag allows the key to be used for a MAC calculation operation + * or for an asymmetric signature operation, + * if otherwise permitted by the key's type and policy. * * For a key pair, this concerns the private key. */ #define PSA_KEY_USAGE_SIGN ((psa_key_usage_t)0x00000400) /** Whether the key may be used to verify a message signature. + * + * This flag allows the key to be used for a MAC verification operation + * or for an asymmetric signature verification operation, + * if otherwise permitted by by the key's type and policy. * * For a key pair, this concerns the public key. */ @@ -1023,8 +1204,10 @@ void psa_key_policy_set_usage(psa_key_policy_t *policy, psa_key_usage_t usage, psa_algorithm_t alg); +/** \brief Retrieve the usage field of a policy structure. */ psa_key_usage_t psa_key_policy_get_usage(psa_key_policy_t *policy); +/** \brief Retrieve the algorithm field of a policy structure. */ psa_algorithm_t psa_key_policy_get_algorithm(psa_key_policy_t *policy); /** \brief Set the usage policy on a key slot. @@ -1431,19 +1614,131 @@ psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation, psa_key_slot_t key, psa_algorithm_t alg); +/** Add a message fragment to a multipart MAC operation. + * + * The application must call psa_mac_sign_setup() or psa_mac_verify_setup() + * before calling this function. + * + * If this function returns an error status, the operation becomes inactive. + * + * \param operation Active MAC operation. + * \param input Buffer containing the message fragment to add to + * the MAC calculation. + * \param input_length Size of the \c input buffer in bytes. + * + * \retval #PSA_SUCCESS + * Success. + * \retval #PSA_ERROR_BAD_STATE + * The operation state is not valid (not started, or already completed). + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED + */ psa_status_t psa_mac_update(psa_mac_operation_t *operation, const uint8_t *input, size_t input_length); +/** Finish the calculation of the MAC of a message. + * + * The application must call psa_mac_sign_setup() before calling this function. + * This function calculates the MAC of the message formed by concatenating + * the inputs passed to preceding calls to psa_mac_update(). + * + * When this function returns, the operation becomes inactive. + * + * \warning Applications should not call this function if they expect + * a specific value for the MAC. Call psa_mac_verify_finish() instead. + * Beware that comparing integrity or authenticity data such as + * MAC values with a function such as \c memcmp is risky + * because the time taken by the comparison may leak information + * about the MAC value which could allow an attacker to guess + * a valid MAC and thereby bypass security controls. + * + * \param operation Active MAC operation. + * \param mac Buffer where the MAC value is to be written. + * \param mac_size Size of the \p mac buffer in bytes. + * \param mac_length On success, the number of bytes + * that make up the MAC value. This is always + * #PSA_MAC_FINAL_SIZE(\c key_type, \c key_bits, \p alg) + * where \c key_type and \c key_bits are the type and + * bit-size respectively of \c key and `alg` is the + * MAC algorithm that is calculated. + * + * \retval #PSA_SUCCESS + * Success. + * \retval #PSA_ERROR_BAD_STATE + * The operation state is not valid (not started, or already completed). + * \retval #PSA_ERROR_BUFFER_TOO_SMALL + * The size of the \c mac buffer is too small. You can determine a + * sufficient buffer size by calling PSA_MAC_FINAL_SIZE(). + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED + */ psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation, uint8_t *mac, size_t mac_size, size_t *mac_length); +/** Finish the calculation of the MAC of a message and compare it with + * an expected value. + * + * The application must call psa_mac_verify_setup() before calling this function. + * This function calculates the MAC of the message formed by concatenating + * the inputs passed to preceding calls to psa_mac_update(). It then + * compares the calculated MAC with the expected MAC passed as a + * parameter to this function. + * + * When this function returns, the operation becomes inactive. + * + * \note Implementations shall make the best effort to ensure that the + * comparison between the actual MAC and the expected MAC is performed + * in constant time. + * + * \param operation Active MAC operation. + * \param mac Buffer containing the expected MAC value. + * \param mac_length Size of the \c mac buffer in bytes. + * + * \retval #PSA_SUCCESS + * The expected MAC is identical to the actual MAC of the message. + * \retval #PSA_ERROR_INVALID_SIGNATURE + * The MAC of the message was calculated successfully, but it + * differs from the expected MAC. + * \retval #PSA_ERROR_BAD_STATE + * The operation state is not valid (not started, or already completed). + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED + */ psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation, const uint8_t *mac, size_t mac_length); +/** Abort a MAC operation. + * + * This function may be called at any time after psa_mac_sign_setup() + * or psa_mac_verify_setup(). + * Aborting an operation frees all associated resources except for the + * \c operation structure itself. + * + * Implementation should strive to be robust and handle inactive MAC + * operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However, + * application writers should beware that uninitialized memory may happen + * to be indistinguishable from an active MAC operation, and the behavior + * of psa_mac_abort() is undefined in this case. + * + * \param operation Active MAC operation. + * + * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_BAD_STATE + * \c operation is not an active MAC operation. + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED + */ psa_status_t psa_mac_abort(psa_mac_operation_t *operation); /**@}*/ @@ -1556,15 +1851,104 @@ psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation, psa_key_slot_t key, psa_algorithm_t alg); +/** Generate an IV for a symmetric encryption operation. + * + * This function generates a random IV (initialization vector), nonce + * or initial counter value for the encryption operation as appropriate + * for the chosen algorithm, key type and key size. + * + * The application must call psa_cipher_encrypt_setup() before + * calling this function. + * + * If this function returns an error status, the operation becomes inactive. + * + * \param operation Active cipher operation. + * \param iv Buffer where the generated IV is to be written. + * \param iv_size Size of the \c iv buffer in bytes. + * \param iv_length On success, the number of bytes of the generated IV. + * + * \retval #PSA_SUCCESS + * Success. + * \retval #PSA_ERROR_BAD_STATE + * The operation state is not valid (not started, or IV already set). + * \retval #PSA_ERROR_BUFFER_TOO_SMALL + * The size of the \c output buffer is too small. + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED + */ psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation, unsigned char *iv, size_t iv_size, size_t *iv_length); +/** Set the IV for a symmetric encryption or decryption operation. + * + * This function sets the random IV (initialization vector), nonce + * or initial counter value for the encryption or decryption operation. + * + * The application must call psa_cipher_encrypt_setup() before + * calling this function. + * + * If this function returns an error status, the operation becomes inactive. + * + * \note When encrypting, applications should use psa_cipher_generate_iv() + * instead of this function, unless implementing a protocol that requires + * a non-random IV. + * + * \param operation Active cipher operation. + * \param iv Buffer containing the IV to use. + * \param iv_length Size of the IV in bytes. + * + * \retval #PSA_SUCCESS + * Success. + * \retval #PSA_ERROR_BAD_STATE + * The operation state is not valid (not started, or IV already set). + * \retval #PSA_ERROR_INVALID_ARGUMENT + * The size of the \c iv is not acceptable for the chosen algorithm, + * or the chosen algorithm does not use an IV. + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED + */ psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation, const unsigned char *iv, size_t iv_length); +/** Encrypt or decrypt a message fragment in an active cipher operation. + * + * The application must call psa_cipher_encrypt_setup() or + * psa_cipher_decrypt_setup() before calling this function. The choice + * of setup function determines whether this function encrypts or + * decrypts its input. After calling a setup function, if the chosen + * algorithm requires an IV, the application must call + * psa_cipher_generate_iv() or psa_cipher_set_iv(). + * + * If this function returns an error status, the operation becomes inactive. + * + * \param operation Active cipher operation. + * \param input Buffer containing the message fragment to + * encrypt or decrypt. + * \param input_length Size of the \c input buffer in bytes. + * \param output Buffer where the output is to be written. + * \param output_size Size of the \c output buffer in bytes. + * \param output_length On success, the number of bytes + * that make up the returned output. + * + * \retval #PSA_SUCCESS + * Success. + * \retval #PSA_ERROR_BAD_STATE + * The operation state is not valid (not started, IV required but + * not set, or already completed). + * \retval #PSA_ERROR_BUFFER_TOO_SMALL + * The size of the \p output buffer is too small. + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED + */ psa_status_t psa_cipher_update(psa_cipher_operation_t *operation, const uint8_t *input, size_t input_length, @@ -1572,11 +1956,64 @@ psa_status_t psa_cipher_update(psa_cipher_operation_t *operation, size_t output_size, size_t *output_length); +/** Finish encrypting or decrypting a message in a cipher operation. + * + * The application must call psa_cipher_encrypt_setup() or + * psa_cipher_decrypt_setup() before calling this function. The choice + * of setup function determines whether this function encrypts or + * decrypts its input. + * + * This function finishes the encryption or decryption of the message + * formed by concatenating the inputs passed to preceding calls to + * psa_cipher_update(). + * + * When this function returns, the operation becomes inactive. + * + * \param operation Active cipher operation. + * \param output Buffer where the output is to be written. + * \param output_size Size of the \c output buffer in bytes. + * \param output_length On success, the number of bytes + * that make up the returned output. + * + * \retval #PSA_SUCCESS + * Success. + * \retval #PSA_ERROR_BAD_STATE + * The operation state is not valid (not started, IV required but + * not set, or already completed). + * \retval #PSA_ERROR_BUFFER_TOO_SMALL + * The size of the \p output buffer is too small. + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED + */ psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation, uint8_t *output, size_t output_size, size_t *output_length); +/** Abort a cipher operation. + * + * This function may be called at any time after + * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(). + * Aborting an operation frees all associated resources except for the + * \c operation structure itself. + * + * Implementation should strive to be robust and handle inactive cipher + * operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However, + * application writers should beware that uninitialized memory may happen + * to be indistinguishable from an active cipher operation, and the behavior + * of psa_cipher_abort() is undefined in this case. + * + * \param operation Active cipher operation. + * + * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_BAD_STATE + * \c operation is not an active cipher operation. + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED + */ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation); /**@}*/ diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h index 574d3e55c..ab5b17e19 100644 --- a/include/psa/crypto_sizes.h +++ b/include/psa/crypto_sizes.h @@ -237,17 +237,69 @@ * sensible size or 0. * If the parameters are not valid, the * return value is unspecified. - * */ #define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \ (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \ PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \ ((void)alg, 0)) +/** Safe output buffer size for psa_asymmetric_encrypt(). + * + * This macro returns a safe buffer size for a ciphertext produced using + * a key of the specified type and size, with the specified algorithm. + * Note that the actual size of the ciphertext may be smaller, depending + * on the algorithm. + * + * \warning This function may call its arguments multiple times or + * zero times, so you should not pass arguments that contain + * side effects. + * + * \param key_type An asymmetric key type (this may indifferently be a + * key pair type or a public key type). + * \param key_bits The size of the key in bits. + * \param alg The signature algorithm. + * + * \return If the parameters are valid and supported, return + * a buffer size in bytes that guarantees that + * psa_asymmetric_encrypt() will not fail with + * #PSA_ERROR_BUFFER_TOO_SMALL. + * If the parameters are a valid combination that is not supported + * by the implementation, this macro either shall return either a + * sensible size or 0. + * If the parameters are not valid, the + * return value is unspecified. + */ #define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \ (PSA_KEY_TYPE_IS_RSA(key_type) ? \ ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \ 0) + +/** Safe output buffer size for psa_asymmetric_decrypt(). + * + * This macro returns a safe buffer size for a ciphertext produced using + * a key of the specified type and size, with the specified algorithm. + * Note that the actual size of the ciphertext may be smaller, depending + * on the algorithm. + * + * \warning This function may call its arguments multiple times or + * zero times, so you should not pass arguments that contain + * side effects. + * + * \param key_type An asymmetric key type (this may indifferently be a + * key pair type or a public key type). + * \param key_bits The size of the key in bits. + * \param alg The signature algorithm. + * + * \return If the parameters are valid and supported, return + * a buffer size in bytes that guarantees that + * psa_asymmetric_decrypt() will not fail with + * #PSA_ERROR_BUFFER_TOO_SMALL. + * If the parameters are a valid combination that is not supported + * by the implementation, this macro either shall return either a + * sensible size or 0. + * If the parameters are not valid, the + * return value is unspecified. + */ #define PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \ (PSA_KEY_TYPE_IS_RSA(key_type) ? \ PSA_BITS_TO_BYTES(key_bits) - PSA_RSA_MINIMUM_PADDING_SIZE(alg) : \ From 7256e6c9a4421800768a180b533ba7f315c9048a Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 12 Jul 2018 00:34:26 +0200 Subject: [PATCH 05/16] Doc: fix formatting of some macro arguments in explanations --- include/psa/crypto.h | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 34ab8e112..4c8cc40fd 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -356,7 +356,7 @@ typedef uint32_t psa_key_type_t; * used for. * * HMAC keys should generally have the same size as the underlying hash. - * This size can be calculated with #PSA_HASH_SIZE(`alg`) where + * This size can be calculated with #PSA_HASH_SIZE(\p alg) where * `alg` is the HMAC algorithm or the underlying hash algorithm. */ #define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x02000001) @@ -650,7 +650,7 @@ typedef uint32_t psa_algorithm_t; * For example, `PSA_ALG_HMAC(PSA_ALG_SHA256)` is HMAC-SHA-256. * * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that - * #PSA_ALG_IS_HASH(alg) is true). + * #PSA_ALG_IS_HASH(\p hash_alg) is true). * * \return The corresponding HMAC algorithm. * \return Unspecified if \p alg is not a supported @@ -775,7 +775,7 @@ typedef uint32_t psa_algorithm_t; * RSASSA-PKCS1-v1_5. * * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that - * #PSA_ALG_IS_HASH(alg) is true). + * #PSA_ALG_IS_HASH(\p hash_alg) is true). * * \return The corresponding RSA PKCS#1 v1.5 signature algorithm. * \return Unspecified if \p alg is not a supported @@ -803,7 +803,7 @@ typedef uint32_t psa_algorithm_t; * salted hash, and for the mask generation. * * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that - * #PSA_ALG_IS_HASH(alg) is true). + * #PSA_ALG_IS_HASH(\p hash_alg) is true). * * \return The corresponding RSA PSS signature algorithm. * \return Unspecified if \p alg is not a supported @@ -821,7 +821,7 @@ typedef uint32_t psa_algorithm_t; * with a random per-message secret number (*k*). * * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that - * #PSA_ALG_IS_HASH(alg) is true). + * #PSA_ALG_IS_HASH(\p hash_alg) is true). * * \return The corresponding DSA signature algorithm. * \return Unspecified if \p alg is not a supported @@ -852,7 +852,7 @@ typedef uint32_t psa_algorithm_t; * in big-endian order (most significant octet first). * * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that - * #PSA_ALG_IS_HASH(alg) is true). + * #PSA_ALG_IS_HASH(\p hash_alg) is true). * * \return The corresponding ECDSA signature algorithm. * \return Unspecified if \p alg is not a supported @@ -884,7 +884,7 @@ typedef uint32_t psa_algorithm_t; * #PSA_ALG_ECDSA(\c hash_alg) only for signature, not for verification. * * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that - * #PSA_ALG_IS_HASH(alg) is true). + * #PSA_ALG_IS_HASH(\p hash_alg) is true). * * \return The corresponding deterministic ECDSA signature * algorithm. @@ -908,7 +908,7 @@ typedef uint32_t psa_algorithm_t; * itself. * * \param alg A signature algorithm (\c PSA_ALG_XXX value such that - * #PSA_ALG_IS_SIGN(alg) is true). + * #PSA_ALG_IS_SIGN(\p alg) is true). * * \return The underlying hash algorithm if \p alg is a hash-and-sign * algorithm. @@ -1315,7 +1315,7 @@ typedef struct psa_hash_operation_s psa_hash_operation_t; * This is also the hash size that psa_hash_verify() expects. * * \param alg A hash algorithm (\c PSA_ALG_XXX value such that - * #PSA_ALG_IS_HASH(alg) is true), or an HMAC algorithm + * #PSA_ALG_IS_HASH(\p alg) is true), or an HMAC algorithm * (#PSA_ALG_HMAC(`hash_alg`) where `hash_alg` is a * hash algorithm). * @@ -1367,7 +1367,7 @@ typedef struct psa_hash_operation_s psa_hash_operation_t; * * \param operation The operation object to use. * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value - * such that #PSA_ALG_IS_HASH(alg) is true). + * such that #PSA_ALG_IS_HASH(\p alg) is true). * * \retval #PSA_SUCCESS * Success. @@ -1422,10 +1422,10 @@ psa_status_t psa_hash_update(psa_hash_operation_t *operation, * * \param operation Active hash operation. * \param hash Buffer where the hash is to be written. - * \param hash_size Size of the \c hash buffer in bytes. + * \param hash_size Size of the \p hash buffer in bytes. * \param hash_length On success, the number of bytes * that make up the hash value. This is always - * #PSA_HASH_SIZE(alg) where \c alg is the + * #PSA_HASH_SIZE(`alg`) where `alg` is the * hash algorithm that is calculated. * * \retval #PSA_SUCCESS @@ -1434,7 +1434,7 @@ psa_status_t psa_hash_update(psa_hash_operation_t *operation, * The operation state is not valid (not started, or already completed). * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \c hash buffer is too small. You can determine a - * sufficient buffer size by calling #PSA_HASH_SIZE(alg) + * sufficient buffer size by calling #PSA_HASH_SIZE(\c alg) * where \c alg is the hash algorithm that is calculated. * \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_COMMUNICATION_FAILURE @@ -1595,7 +1595,7 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation, * \param operation The operation object to use. * \param key Slot containing the key to use for the operation. * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value - * such that #PSA_ALG_IS_MAC(alg) is true). + * such that #PSA_ALG_IS_MAC(\p alg) is true). * * \retval #PSA_SUCCESS * Success. @@ -1784,7 +1784,7 @@ typedef struct psa_cipher_operation_s psa_cipher_operation_t; * \param operation The operation object to use. * \param key Slot containing the key to use for the operation. * \param alg The cipher algorithm to compute (\c PSA_ALG_XXX value - * such that #PSA_ALG_IS_CIPHER(alg) is true). + * such that #PSA_ALG_IS_CIPHER(\p alg) is true). * * \retval #PSA_SUCCESS * Success. @@ -1832,7 +1832,7 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, * \param operation The operation object to use. * \param key Slot containing the key to use for the operation. * \param alg The cipher algorithm to compute (\c PSA_ALG_XXX value - * such that #PSA_ALG_IS_CIPHER(alg) is true). + * such that #PSA_ALG_IS_CIPHER(\p alg) is true). * * \retval #PSA_SUCCESS * Success. @@ -2026,7 +2026,7 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation); * * \param alg An AEAD algorithm * (\c PSA_ALG_XXX value such that - * #PSA_ALG_IS_AEAD(alg) is true). + * #PSA_ALG_IS_AEAD(\p alg) is true). * * \return The tag size for the specified algorithm. * If the AEAD algorithm does not have an identified @@ -2047,7 +2047,7 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation); * \param key Slot containing the key to use. * \param alg The AEAD algorithm to compute * (\c PSA_ALG_XXX value such that - * #PSA_ALG_IS_AEAD(alg) is true). + * #PSA_ALG_IS_AEAD(\p alg) is true). * \param nonce Nonce or IV to use. * \param nonce_length Size of the \p nonce buffer in bytes. * \param additional_data Additional data that will be authenticated @@ -2100,7 +2100,7 @@ psa_status_t psa_aead_encrypt( psa_key_slot_t key, * \param key Slot containing the key to use. * \param alg The AEAD algorithm to compute * (\c PSA_ALG_XXX value such that - * #PSA_ALG_IS_AEAD(alg) is true). + * #PSA_ALG_IS_AEAD(\p alg) is true). * \param nonce Nonce or IV to use. * \param nonce_length Size of the \p nonce buffer in bytes. * \param additional_data Additional data that has been authenticated @@ -2197,7 +2197,7 @@ psa_status_t psa_aead_decrypt( psa_key_slot_t key, * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \c signature buffer is too small. You can * determine a sufficient buffer size by calling - * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) + * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) * where \c key_type and \c key_bits are the type and bit-size * respectively of \c key. * \retval #PSA_ERROR_NOT_SUPPORTED @@ -2302,7 +2302,7 @@ psa_status_t psa_asymmetric_verify(psa_key_slot_t key, * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \c output buffer is too small. You can * determine a sufficient buffer size by calling - * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) + * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) * where \c key_type and \c key_bits are the type and bit-size * respectively of \c key. * \retval #PSA_ERROR_NOT_SUPPORTED @@ -2418,7 +2418,7 @@ psa_status_t psa_generate_random(uint8_t *output, * points to, in bytes. * * For any symmetric key type (a type such that - * #PSA_KEY_TYPE_IS_ASYMMETRIC(`type`) is false), \c parameters must be + * #PSA_KEY_TYPE_IS_ASYMMETRIC(\p type) is false), \c parameters must be * \c NULL. For asymmetric key types defined by this specification, * the parameter type and the default parameters are defined by the * table below. For vendor-defined key types, the vendor documentation From aa7bc47f738bc4c91a127b2a29029c5a8af63045 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 12 Jul 2018 00:54:56 +0200 Subject: [PATCH 06/16] Add missing const on policy_get_xxx function parameter --- include/psa/crypto.h | 4 ++-- library/psa_crypto.c | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 4c8cc40fd..e57f5647e 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -1205,10 +1205,10 @@ void psa_key_policy_set_usage(psa_key_policy_t *policy, psa_algorithm_t alg); /** \brief Retrieve the usage field of a policy structure. */ -psa_key_usage_t psa_key_policy_get_usage(psa_key_policy_t *policy); +psa_key_usage_t psa_key_policy_get_usage(const psa_key_policy_t *policy); /** \brief Retrieve the algorithm field of a policy structure. */ -psa_algorithm_t psa_key_policy_get_algorithm(psa_key_policy_t *policy); +psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy); /** \brief Set the usage policy on a key slot. * diff --git a/library/psa_crypto.c b/library/psa_crypto.c index 50a99904c..fce9e3c82 100644 --- a/library/psa_crypto.c +++ b/library/psa_crypto.c @@ -2585,12 +2585,12 @@ void psa_key_policy_set_usage( psa_key_policy_t *policy, policy->alg = alg; } -psa_key_usage_t psa_key_policy_get_usage( psa_key_policy_t *policy ) +psa_key_usage_t psa_key_policy_get_usage( const psa_key_policy_t *policy ) { return( policy->usage ); } -psa_algorithm_t psa_key_policy_get_algorithm( psa_key_policy_t *policy ) +psa_algorithm_t psa_key_policy_get_algorithm( const psa_key_policy_t *policy ) { return( policy->alg ); } From edd11a14aad385d508b85986580f432f1ac2e187 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 12 Jul 2018 01:08:58 +0200 Subject: [PATCH 07/16] Doc: add [in] or [out] annotations to pointer arguments --- include/psa/crypto.h | 327 ++++++++++++++++++++++--------------------- 1 file changed, 166 insertions(+), 161 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index e57f5647e..c2144fb49 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -963,7 +963,7 @@ typedef uint32_t psa_algorithm_t; * valid slot for a key of the chosen type. It must * be unoccupied. * \param type Key type (a \c PSA_KEY_TYPE_XXX value). - * \param data Buffer containing the key data. + * \param[in] data Buffer containing the key data. * \param data_length Size of the \c data buffer in bytes. * * \retval #PSA_SUCCESS @@ -1027,10 +1027,10 @@ psa_status_t psa_destroy_key(psa_key_slot_t key); * * \param key Slot whose content is queried. This must * be an occupied key slot. - * \param type On success, the key type (a \c PSA_KEY_TYPE_XXX value). + * \param[out] type On success, the key type (a \c PSA_KEY_TYPE_XXX value). * This may be a null pointer, in which case the key type * is not written. - * \param bits On success, the key size in bits. + * \param[out] bits On success, the key size in bits. * This may be a null pointer, in which case the key size * is not written. * @@ -1069,12 +1069,12 @@ psa_status_t psa_get_key_information(psa_key_slot_t key, * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the format * is the DER representation defined by RFC 5280 as SubjectPublicKeyInfo. * - * \param key Slot whose content is to be exported. This must - * be an occupied key slot. - * \param data Buffer where the key data is to be written. - * \param data_size Size of the \c data buffer in bytes. - * \param data_length On success, the number of bytes - * that make up the key data. + * \param key Slot whose content is to be exported. This must + * be an occupied key slot. + * \param[out] data Buffer where the key data is to be written. + * \param data_size Size of the \c data buffer in bytes. + * \param[out] data_length On success, the number of bytes + * that make up the key data. * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_EMPTY_SLOT @@ -1100,12 +1100,12 @@ psa_status_t psa_export_key(psa_key_slot_t key, * the format is the DER representation of the public key defined by RFC 5280 * as SubjectPublicKeyInfo. * - * \param key Slot whose content is to be exported. This must - * be an occupied key slot. - * \param data Buffer where the key data is to be written. - * \param data_size Size of the \c data buffer in bytes. - * \param data_length On success, the number of bytes - * that make up the key data. + * \param key Slot whose content is to be exported. This must + * be an occupied key slot. + * \param[out] data Buffer where the key data is to be written. + * \param data_size Size of the \c data buffer in bytes. + * \param[out] data_length On success, the number of bytes + * that make up the key data. * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_EMPTY_SLOT @@ -1257,7 +1257,7 @@ typedef uint32_t psa_key_lifetime_t; * The assignment of lifetimes to slots is implementation-dependent. * * \param key Slot to query. - * \param lifetime On success, the lifetime value. + * \param[out] lifetime On success, the lifetime value. * * \retval #PSA_SUCCESS * Success. @@ -1365,9 +1365,9 @@ typedef struct psa_hash_operation_s psa_hash_operation_t; * - A failed call to psa_hash_update(). * - A call to psa_hash_finish(), psa_hash_verify() or psa_hash_abort(). * - * \param operation The operation object to use. - * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value - * such that #PSA_ALG_IS_HASH(\p alg) is true). + * \param[out] operation The operation object to use. + * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value + * such that #PSA_ALG_IS_HASH(\p alg) is true). * * \retval #PSA_SUCCESS * Success. @@ -1387,9 +1387,9 @@ psa_status_t psa_hash_setup(psa_hash_operation_t *operation, * * If this function returns an error status, the operation becomes inactive. * - * \param operation Active hash operation. - * \param input Buffer containing the message fragment to hash. - * \param input_length Size of the \c input buffer in bytes. + * \param[in,out] operation Active hash operation. + * \param[in] input Buffer containing the message fragment to hash. + * \param input_length Size of the \c input buffer in bytes. * * \retval #PSA_SUCCESS * Success. @@ -1420,13 +1420,13 @@ psa_status_t psa_hash_update(psa_hash_operation_t *operation, * about the hashed data which could allow an attacker to guess * a valid hash and thereby bypass security controls. * - * \param operation Active hash operation. - * \param hash Buffer where the hash is to be written. - * \param hash_size Size of the \p hash buffer in bytes. - * \param hash_length On success, the number of bytes - * that make up the hash value. This is always - * #PSA_HASH_SIZE(`alg`) where `alg` is the - * hash algorithm that is calculated. + * \param[in,out] operation Active hash operation. + * \param[out] hash Buffer where the hash is to be written. + * \param hash_size Size of the \p hash buffer in bytes. + * \param[out] hash_length On success, the number of bytes + * that make up the hash value. This is always + * #PSA_HASH_SIZE(`alg`) where `alg` is the + * hash algorithm that is calculated. * * \retval #PSA_SUCCESS * Success. @@ -1461,9 +1461,9 @@ psa_status_t psa_hash_finish(psa_hash_operation_t *operation, * comparison between the actual hash and the expected hash is performed * in constant time. * - * \param operation Active hash operation. - * \param hash Buffer containing the expected hash value. - * \param hash_length Size of the \c hash buffer in bytes. + * \param[in,out] operation Active hash operation. + * \param[in] hash Buffer containing the expected hash value. + * \param hash_length Size of the \c hash buffer in bytes. * * \retval #PSA_SUCCESS * The expected hash is identical to the actual hash of the message. @@ -1493,7 +1493,7 @@ psa_status_t psa_hash_verify(psa_hash_operation_t *operation, * to be indistinguishable from an active hash operation, and the behavior * of psa_hash_abort() is undefined in this case. * - * \param operation Active hash operation. + * \param[in,out] operation Active hash operation. * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_BAD_STATE @@ -1544,10 +1544,10 @@ typedef struct psa_mac_operation_s psa_mac_operation_t; * - A failed call to psa_mac_update(). * - A call to psa_mac_sign_finish() or psa_mac_abort(). * - * \param operation The operation object to use. - * \param key Slot containing the key to use for the operation. - * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value - * such that #PSA_ALG_IS_MAC(alg) is true). + * \param[out] operation The operation object to use. + * \param key Slot containing the key to use for the operation. + * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value + * such that #PSA_ALG_IS_MAC(alg) is true). * * \retval #PSA_SUCCESS * Success. @@ -1592,10 +1592,10 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation, * - A failed call to psa_mac_update(). * - A call to psa_mac_verify_finish() or psa_mac_abort(). * - * \param operation The operation object to use. - * \param key Slot containing the key to use for the operation. - * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value - * such that #PSA_ALG_IS_MAC(\p alg) is true). + * \param[out] operation The operation object to use. + * \param key Slot containing the key to use for the operation. + * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value + * such that #PSA_ALG_IS_MAC(\p alg) is true). * * \retval #PSA_SUCCESS * Success. @@ -1621,10 +1621,10 @@ psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation, * * If this function returns an error status, the operation becomes inactive. * - * \param operation Active MAC operation. - * \param input Buffer containing the message fragment to add to - * the MAC calculation. - * \param input_length Size of the \c input buffer in bytes. + * \param[in,out] operation Active MAC operation. + * \param[in] input Buffer containing the message fragment to add to + * the MAC calculation. + * \param input_length Size of the \c input buffer in bytes. * * \retval #PSA_SUCCESS * Success. @@ -1655,15 +1655,15 @@ psa_status_t psa_mac_update(psa_mac_operation_t *operation, * about the MAC value which could allow an attacker to guess * a valid MAC and thereby bypass security controls. * - * \param operation Active MAC operation. - * \param mac Buffer where the MAC value is to be written. - * \param mac_size Size of the \p mac buffer in bytes. - * \param mac_length On success, the number of bytes - * that make up the MAC value. This is always - * #PSA_MAC_FINAL_SIZE(\c key_type, \c key_bits, \p alg) - * where \c key_type and \c key_bits are the type and - * bit-size respectively of \c key and `alg` is the - * MAC algorithm that is calculated. + * \param[in,out] operation Active MAC operation. + * \param[out] mac Buffer where the MAC value is to be written. + * \param mac_size Size of the \p mac buffer in bytes. + * \param[out] mac_length On success, the number of bytes + * that make up the MAC value. This is always + * #PSA_MAC_FINAL_SIZE(\c key_type, \c key_bits, \p alg) + * where \c key_type and \c key_bits are the type and + * bit-size respectively of \c key and `alg` is the + * MAC algorithm that is calculated. * * \retval #PSA_SUCCESS * Success. @@ -1697,9 +1697,9 @@ psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation, * comparison between the actual MAC and the expected MAC is performed * in constant time. * - * \param operation Active MAC operation. - * \param mac Buffer containing the expected MAC value. - * \param mac_length Size of the \c mac buffer in bytes. + * \param[in,out] operation Active MAC operation. + * \param[in] mac Buffer containing the expected MAC value. + * \param mac_length Size of the \c mac buffer in bytes. * * \retval #PSA_SUCCESS * The expected MAC is identical to the actual MAC of the message. @@ -1730,7 +1730,7 @@ psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation, * to be indistinguishable from an active MAC operation, and the behavior * of psa_mac_abort() is undefined in this case. * - * \param operation Active MAC operation. + * \param[in,out] operation Active MAC operation. * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_BAD_STATE @@ -1781,10 +1781,11 @@ typedef struct psa_cipher_operation_s psa_cipher_operation_t; * or psa_cipher_update(). * - A call to psa_cipher_finish() or psa_cipher_abort(). * - * \param operation The operation object to use. - * \param key Slot containing the key to use for the operation. - * \param alg The cipher algorithm to compute (\c PSA_ALG_XXX value - * such that #PSA_ALG_IS_CIPHER(\p alg) is true). + * \param[out] operation The operation object to use. + * \param key Slot containing the key to use for the operation. + * \param alg The cipher algorithm to compute + * (\c PSA_ALG_XXX value such that + * #PSA_ALG_IS_CIPHER(\p alg) is true). * * \retval #PSA_SUCCESS * Success. @@ -1829,10 +1830,11 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, * - A failed call to psa_cipher_update(). * - A call to psa_cipher_finish() or psa_cipher_abort(). * - * \param operation The operation object to use. - * \param key Slot containing the key to use for the operation. - * \param alg The cipher algorithm to compute (\c PSA_ALG_XXX value - * such that #PSA_ALG_IS_CIPHER(\p alg) is true). + * \param[out] operation The operation object to use. + * \param key Slot containing the key to use for the operation. + * \param alg The cipher algorithm to compute + * (\c PSA_ALG_XXX value such that + * #PSA_ALG_IS_CIPHER(\p alg) is true). * * \retval #PSA_SUCCESS * Success. @@ -1862,10 +1864,11 @@ psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation, * * If this function returns an error status, the operation becomes inactive. * - * \param operation Active cipher operation. - * \param iv Buffer where the generated IV is to be written. - * \param iv_size Size of the \c iv buffer in bytes. - * \param iv_length On success, the number of bytes of the generated IV. + * \param[in,out] operation Active cipher operation. + * \param[out] iv Buffer where the generated IV is to be written. + * \param iv_size Size of the \c iv buffer in bytes. + * \param[out] iv_length On success, the number of bytes of the + * generated IV. * * \retval #PSA_SUCCESS * Success. @@ -1897,9 +1900,9 @@ psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation, * instead of this function, unless implementing a protocol that requires * a non-random IV. * - * \param operation Active cipher operation. - * \param iv Buffer containing the IV to use. - * \param iv_length Size of the IV in bytes. + * \param[in,out] operation Active cipher operation. + * \param[in] iv Buffer containing the IV to use. + * \param iv_length Size of the IV in bytes. * * \retval #PSA_SUCCESS * Success. @@ -1928,14 +1931,14 @@ psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation, * * If this function returns an error status, the operation becomes inactive. * - * \param operation Active cipher operation. - * \param input Buffer containing the message fragment to - * encrypt or decrypt. - * \param input_length Size of the \c input buffer in bytes. - * \param output Buffer where the output is to be written. - * \param output_size Size of the \c output buffer in bytes. - * \param output_length On success, the number of bytes - * that make up the returned output. + * \param[in,out] operation Active cipher operation. + * \param[in] input Buffer containing the message fragment to + * encrypt or decrypt. + * \param input_length Size of the \c input buffer in bytes. + * \param[out] output Buffer where the output is to be written. + * \param output_size Size of the \c output buffer in bytes. + * \param[out] output_length On success, the number of bytes + * that make up the returned output. * * \retval #PSA_SUCCESS * Success. @@ -1969,11 +1972,11 @@ psa_status_t psa_cipher_update(psa_cipher_operation_t *operation, * * When this function returns, the operation becomes inactive. * - * \param operation Active cipher operation. - * \param output Buffer where the output is to be written. - * \param output_size Size of the \c output buffer in bytes. - * \param output_length On success, the number of bytes - * that make up the returned output. + * \param[in,out] operation Active cipher operation. + * \param[out] output Buffer where the output is to be written. + * \param output_size Size of the \c output buffer in bytes. + * \param[out] output_length On success, the number of bytes + * that make up the returned output. * * \retval #PSA_SUCCESS * Success. @@ -2005,7 +2008,7 @@ psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation, * to be indistinguishable from an active cipher operation, and the behavior * of psa_cipher_abort() is undefined in this case. * - * \param operation Active cipher operation. + * \param[in,out] operation Active cipher operation. * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_BAD_STATE @@ -2048,15 +2051,15 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation); * \param alg The AEAD algorithm to compute * (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_AEAD(\p alg) is true). - * \param nonce Nonce or IV to use. + * \param[in] nonce Nonce or IV to use. * \param nonce_length Size of the \p nonce buffer in bytes. - * \param additional_data Additional data that will be authenticated + * \param[in] additional_data Additional data that will be authenticated * but not encrypted. * \param additional_data_length Size of \p additional_data in bytes. - * \param plaintext Data that will be authenticated and + * \param[in] plaintext Data that will be authenticated and * encrypted. * \param plaintext_length Size of \p plaintext in bytes. - * \param ciphertext Output buffer for the authenticated and + * \param[out] ciphertext Output buffer for the authenticated and * encrypted data. The additional data is not * part of this output. For algorithms where the * encrypted data and the authentication tag @@ -2067,7 +2070,7 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation); * This must be at least * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg, * \p plaintext_length). - * \param ciphertext_length On success, the size of the output + * \param[out] ciphertext_length On success, the size of the output * in the \b ciphertext buffer. * * \retval #PSA_SUCCESS @@ -2101,24 +2104,24 @@ psa_status_t psa_aead_encrypt( psa_key_slot_t key, * \param alg The AEAD algorithm to compute * (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_AEAD(\p alg) is true). - * \param nonce Nonce or IV to use. + * \param[in] nonce Nonce or IV to use. * \param nonce_length Size of the \p nonce buffer in bytes. - * \param additional_data Additional data that has been authenticated + * \param[in] additional_data Additional data that has been authenticated * but not encrypted. * \param additional_data_length Size of \p additional_data in bytes. - * \param ciphertext Data that has been authenticated and + * \param[in] ciphertext Data that has been authenticated and * encrypted. For algorithms where the * encrypted data and the authentication tag * are defined as separate inputs, the buffer * must contain the encrypted data followed * by the authentication tag. * \param ciphertext_length Size of \p ciphertext in bytes. - * \param plaintext Output buffer for the decrypted data. + * \param[out] plaintext Output buffer for the decrypted data. * \param plaintext_size Size of the \p plaintext buffer in bytes. * This must be at least * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg, * \p ciphertext_length). - * \param plaintext_length On success, the size of the output + * \param[out] plaintext_length On success, the size of the output * in the \b plaintext buffer. * * \retval #PSA_SUCCESS @@ -2174,24 +2177,24 @@ psa_status_t psa_aead_decrypt( psa_key_slot_t key, * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg) * to determine the hash algorithm to use. * - * \param key Key slot containing an asymmetric key pair. - * \param alg A signature algorithm that is compatible with - * the type of \c key. - * \param hash The hash or message to sign. - * \param hash_length Size of the \c hash buffer in bytes. - * \param salt A salt or label, if supported by the signature - * algorithm. - * If the signature algorithm does not support a - * salt, pass \c NULL. - * If the signature algorithm supports an optional - * salt and you do not want to pass a salt, - * pass \c NULL. - * \param salt_length Size of the \c salt buffer in bytes. - * If \c salt is \c NULL, pass 0. - * \param signature Buffer where the signature is to be written. - * \param signature_size Size of the \c signature buffer in bytes. - * \param signature_length On success, the number of bytes - * that make up the returned signature value. + * \param key Key slot containing an asymmetric key pair. + * \param alg A signature algorithm that is compatible with + * the type of \c key. + * \param[in] hash The hash or message to sign. + * \param hash_length Size of the \c hash buffer in bytes. + * \param[in] salt A salt or label, if supported by the + * signature algorithm. + * If the signature algorithm does not support + * a salt, pass \c NULL. + * If the signature algorithm supports an + * optional salt and you do not want to pass + * a salt, pass \c NULL. + * \param salt_length Size of the \c salt buffer in bytes. + * If \c salt is \c NULL, pass 0. + * \param[out] signature Buffer where the signature is to be written. + * \param signature_size Size of the \c signature buffer in bytes. + * \param[out] signature_length On success, the number of bytes + * that make up the returned signature value. * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_BUFFER_TOO_SMALL @@ -2231,10 +2234,10 @@ psa_status_t psa_asymmetric_sign(psa_key_slot_t key, * asymmetric key pair. * \param alg A signature algorithm that is compatible with * the type of \c key. - * \param hash The hash or message whose signature is to be + * \param[in] hash The hash or message whose signature is to be * verified. * \param hash_length Size of the \c hash buffer in bytes. - * \param salt A salt or label, if supported by the signature + * \param[in] salt A salt or label, if supported by the signature * algorithm. * If the signature algorithm does not support a * salt, pass \c NULL. @@ -2243,7 +2246,7 @@ psa_status_t psa_asymmetric_sign(psa_key_slot_t key, * pass \c NULL. * \param salt_length Size of the \c salt buffer in bytes. * If \c salt is \c NULL, pass 0. - * \param signature Buffer containing the signature to verify. + * \param[in] signature Buffer containing the signature to verify. * \param signature_length Size of the \c signature buffer in bytes. * * \retval #PSA_SUCCESS @@ -2275,28 +2278,29 @@ psa_status_t psa_asymmetric_verify(psa_key_slot_t key, /** * \brief Encrypt a short message with a public key. * - * \param key Key slot containing a public key or an asymmetric - * key pair. - * \param alg An asymmetric encryption algorithm that is - * compatible with the type of \c key. - * \param input The message to encrypt. - * \param input_length Size of the \c input buffer in bytes. - * \param salt A salt or label, if supported by the encryption - * algorithm. - * If the algorithm does not support a - * salt, pass \c NULL. - * If the algorithm supports an optional - * salt and you do not want to pass a salt, - * pass \c NULL. + * \param key Key slot containing a public key or an + * asymmetric key pair. + * \param alg An asymmetric encryption algorithm that is + * compatible with the type of \c key. + * \param[in] input The message to encrypt. + * \param input_length Size of the \c input buffer in bytes. + * \param[in] salt A salt or label, if supported by the + * encryption algorithm. + * If the algorithm does not support a + * salt, pass \c NULL. + * If the algorithm supports an optional + * salt and you do not want to pass a salt, + * pass \c NULL. * - * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is - * supported. - * \param salt_length Size of the \c salt buffer in bytes. - * If \c salt is \c NULL, pass 0. - * \param output Buffer where the encrypted message is to be written. - * \param output_size Size of the \c output buffer in bytes. - * \param output_length On success, the number of bytes - * that make up the returned output. + * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is + * supported. + * \param salt_length Size of the \c salt buffer in bytes. + * If \c salt is \c NULL, pass 0. + * \param[out] output Buffer where the encrypted message is to + * be written. + * \param output_size Size of the \c output buffer in bytes. + * \param[out] output_length On success, the number of bytes + * that make up the returned output. * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_BUFFER_TOO_SMALL @@ -2326,27 +2330,28 @@ psa_status_t psa_asymmetric_encrypt(psa_key_slot_t key, /** * \brief Decrypt a short message with a private key. * - * \param key Key slot containing an asymmetric key pair. - * \param alg An asymmetric encryption algorithm that is - * compatible with the type of \c key. - * \param input The message to decrypt. - * \param input_length Size of the \c input buffer in bytes. - * \param salt A salt or label, if supported by the encryption - * algorithm. - * If the algorithm does not support a - * salt, pass \c NULL. - * If the algorithm supports an optional - * salt and you do not want to pass a salt, - * pass \c NULL. + * \param key Key slot containing an asymmetric key pair. + * \param alg An asymmetric encryption algorithm that is + * compatible with the type of \c key. + * \param[in] input The message to decrypt. + * \param input_length Size of the \c input buffer in bytes. + * \param[in] salt A salt or label, if supported by the + * encryption algorithm. + * If the algorithm does not support a + * salt, pass \c NULL. + * If the algorithm supports an optional + * salt and you do not want to pass a salt, + * pass \c NULL. * - * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is - * supported. - * \param salt_length Size of the \c salt buffer in bytes. - * If \c salt is \c NULL, pass 0. - * \param output Buffer where the decrypted message is to be written. - * \param output_size Size of the \c output buffer in bytes. - * \param output_length On success, the number of bytes - * that make up the returned output. + * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is + * supported. + * \param salt_length Size of the \c salt buffer in bytes. + * If \c salt is \c NULL, pass 0. + * \param[out] output Buffer where the decrypted message is to + * be written. + * \param output_size Size of the \c output buffer in bytes. + * \param[out] output_length On success, the number of bytes + * that make up the returned output. * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_BUFFER_TOO_SMALL @@ -2389,7 +2394,7 @@ psa_status_t psa_asymmetric_decrypt(psa_key_slot_t key, * * \note To generate a key, use psa_generate_key() instead. * - * \param output Output buffer for the generated data. + * \param[out] output Output buffer for the generated data. * \param output_size Number of bytes to generate and output. * * \retval #PSA_SUCCESS @@ -2410,7 +2415,7 @@ psa_status_t psa_generate_random(uint8_t *output, * be unoccupied. * \param type Key type (a \c PSA_KEY_TYPE_XXX value). * \param bits Key size in bits. - * \param parameters Extra parameters for key generation. The + * \param[in] parameters Extra parameters for key generation. The * interpretation of this parameter depends on * \c type. All types support \c NULL to use * the default parameters specified below. From 53d991e655b9141aad6d719629521606f312907e Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 12 Jul 2018 01:14:59 +0200 Subject: [PATCH 08/16] generate_key: rename \p parameters to \p extra \p parameters is a confusing name for a function parameter. Rename it to \p extra. --- include/psa/crypto.h | 15 ++++++++------- library/psa_crypto.c | 14 +++++++------- 2 files changed, 15 insertions(+), 14 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index c2144fb49..ff85924aa 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -2415,21 +2415,22 @@ psa_status_t psa_generate_random(uint8_t *output, * be unoccupied. * \param type Key type (a \c PSA_KEY_TYPE_XXX value). * \param bits Key size in bits. - * \param[in] parameters Extra parameters for key generation. The + * \param[in] extra Extra parameters for key generation. The * interpretation of this parameter depends on * \c type. All types support \c NULL to use * the default parameters specified below. - * \param parameters_size Size of the buffer that \p parameters - * points to, in bytes. + * \param extra_size Size of the buffer that \p extra + * points to, in bytes. Note that if \p extra is + * \c NULL then \p extra_size must be zero. * * For any symmetric key type (a type such that - * #PSA_KEY_TYPE_IS_ASYMMETRIC(\p type) is false), \c parameters must be + * #PSA_KEY_TYPE_IS_ASYMMETRIC(\p type) is false), \p extra must be * \c NULL. For asymmetric key types defined by this specification, * the parameter type and the default parameters are defined by the * table below. For vendor-defined key types, the vendor documentation * shall define the parameter type and the default parameters. * - * Type | Parameter type | Meaning | Parameters used if `parameters == NULL` + * Type | Parameter type | Meaning | Parameters used if `extra == NULL` * ---- | -------------- | ------- | --------------------------------------- * `PSA_KEY_TYPE_RSA_KEYPAIR` | `unsigned int` | Public exponent | 65537 * @@ -2445,8 +2446,8 @@ psa_status_t psa_generate_random(uint8_t *output, psa_status_t psa_generate_key(psa_key_slot_t key, psa_key_type_t type, size_t bits, - const void *parameters, - size_t parameters_size); + const void *extra, + size_t extra_size); /**@}*/ diff --git a/library/psa_crypto.c b/library/psa_crypto.c index fce9e3c82..a256ad7ee 100644 --- a/library/psa_crypto.c +++ b/library/psa_crypto.c @@ -2964,13 +2964,13 @@ psa_status_t psa_generate_random( uint8_t *output, psa_status_t psa_generate_key( psa_key_slot_t key, psa_key_type_t type, size_t bits, - const void *parameters, - size_t parameters_size ) + const void *extra, + size_t extra_size ) { key_slot_t *slot; psa_status_t status; - if( parameters == NULL && parameters_size != 0 ) + if( extra == NULL && extra_size != 0 ) return( PSA_ERROR_INVALID_ARGUMENT ); status = psa_get_empty_key_slot( key, &slot ); @@ -3010,10 +3010,10 @@ psa_status_t psa_generate_key( psa_key_slot_t key, int exponent = 65537; if( bits > PSA_VENDOR_RSA_MAX_KEY_BITS ) return( PSA_ERROR_NOT_SUPPORTED ); - if( parameters != NULL ) + if( extra != NULL ) { - const unsigned *p = parameters; - if( parameters_size != sizeof( *p ) ) + const unsigned *p = extra; + if( extra_size != sizeof( *p ) ) return( PSA_ERROR_INVALID_ARGUMENT ); if( *p > INT_MAX ) return( PSA_ERROR_INVALID_ARGUMENT ); @@ -3048,7 +3048,7 @@ psa_status_t psa_generate_key( psa_key_slot_t key, mbedtls_ecp_curve_info_from_grp_id( grp_id ); mbedtls_ecp_keypair *ecp; int ret; - if( parameters != NULL ) + if( extra != NULL ) return( PSA_ERROR_NOT_SUPPORTED ); if( grp_id == MBEDTLS_ECP_DP_NONE || curve_info == NULL ) return( PSA_ERROR_NOT_SUPPORTED ); From 4c317f4b4c5dd3dce1b755bb12ad939ca1a7710e Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 12 Jul 2018 01:24:09 +0200 Subject: [PATCH 09/16] generate_key: define a structure type for RSA extra parameters --- include/psa/crypto.h | 11 ++++++++++- library/psa_crypto.c | 12 ++++++++---- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index ff85924aa..b190907cf 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -2407,6 +2407,15 @@ psa_status_t psa_asymmetric_decrypt(psa_key_slot_t key, psa_status_t psa_generate_random(uint8_t *output, size_t output_size); +/** Extra parameters for RSA key generation. + * + * You may pass a pointer to a structure of this type as the `extra` + * parameter to psa_generate_key(). + */ +typedef struct { + uint32_t e; /**! Public exponent value. Default: 65537. */ +} psa_generate_key_extra_rsa; + /** * \brief Generate a key or key pair. * @@ -2432,7 +2441,7 @@ psa_status_t psa_generate_random(uint8_t *output, * * Type | Parameter type | Meaning | Parameters used if `extra == NULL` * ---- | -------------- | ------- | --------------------------------------- - * `PSA_KEY_TYPE_RSA_KEYPAIR` | `unsigned int` | Public exponent | 65537 + * `PSA_KEY_TYPE_RSA_KEYPAIR` | #psa_generate_key_extra_rsa | Public exponent | 65537 * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_NOT_SUPPORTED diff --git a/library/psa_crypto.c b/library/psa_crypto.c index a256ad7ee..eb140ea2c 100644 --- a/library/psa_crypto.c +++ b/library/psa_crypto.c @@ -3012,12 +3012,16 @@ psa_status_t psa_generate_key( psa_key_slot_t key, return( PSA_ERROR_NOT_SUPPORTED ); if( extra != NULL ) { - const unsigned *p = extra; + const psa_generate_key_extra_rsa *p = extra; if( extra_size != sizeof( *p ) ) return( PSA_ERROR_INVALID_ARGUMENT ); - if( *p > INT_MAX ) - return( PSA_ERROR_INVALID_ARGUMENT ); - exponent = *p; +#if INT_MAX < 0xffffffff + /* Check that the uint32_t value passed by the caller fits + * in the range supported by this implementation. */ + if( p->e > INT_MAX ) + return( PSA_ERROR_NOT_SUPPORTED ); +#endif + exponent = p->e; } rsa = mbedtls_calloc( 1, sizeof( *rsa ) ); if( rsa == NULL ) From 3fa675cd971941c58405f6f30ee69cca62c8fc78 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 12 Jul 2018 01:31:03 +0200 Subject: [PATCH 10/16] Doc: generate_key: improve documentation of \p extra --- include/psa/crypto.h | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index b190907cf..3cd516097 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -2427,22 +2427,27 @@ typedef struct { * \param[in] extra Extra parameters for key generation. The * interpretation of this parameter depends on * \c type. All types support \c NULL to use - * the default parameters specified below. + * default parameters. Implementation that support + * the generation of vendor-specific key types + * that allow extra parameters shall document + * the format of these extra parameters and + * the default values. For standard parameters, + * the meaning of \p extra is as follows: + * - For a symmetric key type (a type \c type such + * that #PSA_KEY_TYPE_IS_ASYMMETRIC(\p type) is + * false), \p extra must be \c NULL. + * - For an elliptic curve key type (a type \c type + * such that #PSA_KEY_TYPE_IS_ECC(\p type) is + * false), \p extra must be \c NULL. + * - For an RSA key, \p extra is an optional + * #psa_generate_key_extra_rsa structure + * specifying the public exponent. The + * default public exponent used when \p extra + * is \c NULL is 65537. * \param extra_size Size of the buffer that \p extra * points to, in bytes. Note that if \p extra is * \c NULL then \p extra_size must be zero. * - * For any symmetric key type (a type such that - * #PSA_KEY_TYPE_IS_ASYMMETRIC(\p type) is false), \p extra must be - * \c NULL. For asymmetric key types defined by this specification, - * the parameter type and the default parameters are defined by the - * table below. For vendor-defined key types, the vendor documentation - * shall define the parameter type and the default parameters. - * - * Type | Parameter type | Meaning | Parameters used if `extra == NULL` - * ---- | -------------- | ------- | --------------------------------------- - * `PSA_KEY_TYPE_RSA_KEYPAIR` | #psa_generate_key_extra_rsa | Public exponent | 65537 - * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_NOT_SUPPORTED * \retval #PSA_ERROR_INVALID_ARGUMENT From fa4070c50bd17d2d1c231e752a3f5e11709fd0f6 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 12 Jul 2018 19:23:03 +0200 Subject: [PATCH 11/16] Doc: Fix some \c name that should have been \p name --- include/psa/crypto.h | 174 +++++++++++++++++++++---------------------- 1 file changed, 87 insertions(+), 87 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 3cd516097..fa2765667 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -492,7 +492,7 @@ typedef uint16_t psa_ecc_curve_t; * \param type A cipher key type (value of type #psa_key_type_t). * * \return The block size for a block cipher, or 1 for a stream cipher. - * The return value is undefined if \c type is not a supported + * The return value is undefined if \p type is not a supported * cipher key type. * * \note It is possible to build stream cipher algorithms on top of a block @@ -541,8 +541,8 @@ typedef uint32_t psa_algorithm_t; * * \param alg An algorithm identifier (value of type #psa_algorithm_t). * - * \return 1 if \c alg is a hash algorithm, 0 otherwise. - * This macro may return either 0 or 1 if \c alg is not a supported + * \return 1 if \p alg is a hash algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \p alg is not a supported * algorithm identifier. */ #define PSA_ALG_IS_HASH(alg) \ @@ -552,8 +552,8 @@ typedef uint32_t psa_algorithm_t; * * \param alg An algorithm identifier (value of type #psa_algorithm_t). * - * \return 1 if \c alg is a MAC algorithm, 0 otherwise. - * This macro may return either 0 or 1 if \c alg is not a supported + * \return 1 if \p alg is a MAC algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \p alg is not a supported * algorithm identifier. */ #define PSA_ALG_IS_MAC(alg) \ @@ -563,8 +563,8 @@ typedef uint32_t psa_algorithm_t; * * \param alg An algorithm identifier (value of type #psa_algorithm_t). * - * \return 1 if \c alg is a symmetric cipher algorithm, 0 otherwise. - * This macro may return either 0 or 1 if \c alg is not a supported + * \return 1 if \p alg is a symmetric cipher algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \p alg is not a supported * algorithm identifier. */ #define PSA_ALG_IS_CIPHER(alg) \ @@ -575,8 +575,8 @@ typedef uint32_t psa_algorithm_t; * * \param alg An algorithm identifier (value of type #psa_algorithm_t). * - * \return 1 if \c alg is an AEAD algorithm, 0 otherwise. - * This macro may return either 0 or 1 if \c alg is not a supported + * \return 1 if \p alg is an AEAD algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \p alg is not a supported * algorithm identifier. */ #define PSA_ALG_IS_AEAD(alg) \ @@ -586,8 +586,8 @@ typedef uint32_t psa_algorithm_t; * * \param alg An algorithm identifier (value of type #psa_algorithm_t). * - * \return 1 if \c alg is a public-key signature algorithm, 0 otherwise. - * This macro may return either 0 or 1 if \c alg is not a supported + * \return 1 if \p alg is a public-key signature algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \p alg is not a supported * algorithm identifier. */ #define PSA_ALG_IS_SIGN(alg) \ @@ -597,8 +597,8 @@ typedef uint32_t psa_algorithm_t; * * \param alg An algorithm identifier (value of type #psa_algorithm_t). * - * \return 1 if \c alg is a public-key encryption algorithm, 0 otherwise. - * This macro may return either 0 or 1 if \c alg is not a supported + * \return 1 if \p alg is a public-key encryption algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \p alg is not a supported * algorithm identifier. */ #define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg) \ @@ -608,8 +608,8 @@ typedef uint32_t psa_algorithm_t; * * \param alg An algorithm identifier (value of type #psa_algorithm_t). * - * \return 1 if \c alg is a key agreement algorithm, 0 otherwise. - * This macro may return either 0 or 1 if \c alg is not a supported + * \return 1 if \p alg is a key agreement algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \p alg is not a supported * algorithm identifier. */ #define PSA_ALG_IS_KEY_AGREEMENT(alg) \ @@ -619,8 +619,8 @@ typedef uint32_t psa_algorithm_t; * * \param alg An algorithm identifier (value of type #psa_algorithm_t). * - * \return 1 if \c alg is a key derivation algorithm, 0 otherwise. - * This macro may return either 0 or 1 if \c alg is not a supported + * \return 1 if \p alg is a key derivation algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \p alg is not a supported * algorithm identifier. */ #define PSA_ALG_IS_KEY_DERIVATION(alg) \ @@ -668,8 +668,8 @@ typedef uint32_t psa_algorithm_t; * * \param alg An algorithm identifier (value of type #psa_algorithm_t). * - * \return 1 if \c alg is an HMAC algorithm, 0 otherwise. - * This macro may return either 0 or 1 if \c alg is not a supported + * \return 1 if \p alg is an HMAC algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \p alg is not a supported * algorithm identifier. */ #define PSA_ALG_IS_HMAC(alg) \ @@ -683,8 +683,8 @@ typedef uint32_t psa_algorithm_t; /** Whether the specified algorithm is a MAC algorithm based on a block cipher. * - * \return 1 if \c alg is a MAC algorithm based on a block cipher, 0 otherwise. - * This macro may return either 0 or 1 if \c alg is not a supported + * \return 1 if \p alg is a MAC algorithm based on a block cipher, 0 otherwise. + * This macro may return either 0 or 1 if \p alg is not a supported * algorithm identifier. */ #define PSA_ALG_IS_CIPHER_MAC(alg) \ @@ -720,8 +720,8 @@ typedef uint32_t psa_algorithm_t; * * \param alg An algorithm identifier (value of type #psa_algorithm_t). * - * \return 1 if \c alg is a block cipher algorithm, 0 otherwise. - * This macro may return either 0 or 1 if \c alg is not a supported + * \return 1 if \p alg is a block cipher algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \p alg is not a supported * algorithm identifier or if it is not a symmetric cipher algorithm. */ #define PSA_ALG_IS_BLOCK_CIPHER(alg) \ @@ -756,8 +756,8 @@ typedef uint32_t psa_algorithm_t; * * \param alg An algorithm identifier (value of type #psa_algorithm_t). * - * \return 1 if \c alg is a stream cipher algorithm, 0 otherwise. - * This macro may return either 0 or 1 if \c alg is not a supported + * \return 1 if \p alg is a stream cipher algorithm, 0 otherwise. + * This macro may return either 0 or 1 if \p alg is not a supported * algorithm identifier or if it is not a symmetric cipher algorithm. */ #define PSA_ALG_IS_STREAM_CIPHER(alg) \ @@ -878,10 +878,10 @@ typedef uint32_t psa_algorithm_t; * The representation of a signature is the same as with #PSA_ALG_ECDSA(). * * Note that when this algorithm is used for verification, signatures - * made with randomized ECDSA (#PSA_ALG_ECDSA(\c hash_alg)) with the + * made with randomized ECDSA (#PSA_ALG_ECDSA(\p hash_alg)) with the * same private key are accepted. In other words, - * #PSA_ALG_DETERMINISTIC_ECDSA(\c hash_alg) differs from - * #PSA_ALG_ECDSA(\c hash_alg) only for signature, not for verification. + * #PSA_ALG_DETERMINISTIC_ECDSA(\p hash_alg) differs from + * #PSA_ALG_ECDSA(\p hash_alg) only for signature, not for verification. * * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_HASH(\p hash_alg) is true). @@ -964,7 +964,7 @@ typedef uint32_t psa_algorithm_t; * be unoccupied. * \param type Key type (a \c PSA_KEY_TYPE_XXX value). * \param[in] data Buffer containing the key data. - * \param data_length Size of the \c data buffer in bytes. + * \param data_length Size of the \p data buffer in bytes. * * \retval #PSA_SUCCESS * Success. @@ -1072,7 +1072,7 @@ psa_status_t psa_get_key_information(psa_key_slot_t key, * \param key Slot whose content is to be exported. This must * be an occupied key slot. * \param[out] data Buffer where the key data is to be written. - * \param data_size Size of the \c data buffer in bytes. + * \param data_size Size of the \p data buffer in bytes. * \param[out] data_length On success, the number of bytes * that make up the key data. * @@ -1103,7 +1103,7 @@ psa_status_t psa_export_key(psa_key_slot_t key, * \param key Slot whose content is to be exported. This must * be an occupied key slot. * \param[out] data Buffer where the key data is to be written. - * \param data_size Size of the \c data buffer in bytes. + * \param data_size Size of the \p data buffer in bytes. * \param[out] data_length On success, the number of bytes * that make up the key data. * @@ -1372,7 +1372,7 @@ typedef struct psa_hash_operation_s psa_hash_operation_t; * \retval #PSA_SUCCESS * Success. * \retval #PSA_ERROR_NOT_SUPPORTED - * \c alg is not supported or is not a hash algorithm. + * \p alg is not supported or is not a hash algorithm. * \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE @@ -1389,7 +1389,7 @@ psa_status_t psa_hash_setup(psa_hash_operation_t *operation, * * \param[in,out] operation Active hash operation. * \param[in] input Buffer containing the message fragment to hash. - * \param input_length Size of the \c input buffer in bytes. + * \param input_length Size of the \p input buffer in bytes. * * \retval #PSA_SUCCESS * Success. @@ -1433,7 +1433,7 @@ psa_status_t psa_hash_update(psa_hash_operation_t *operation, * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (not started, or already completed). * \retval #PSA_ERROR_BUFFER_TOO_SMALL - * The size of the \c hash buffer is too small. You can determine a + * The size of the \p hash buffer is too small. You can determine a * sufficient buffer size by calling #PSA_HASH_SIZE(\c alg) * where \c alg is the hash algorithm that is calculated. * \retval #PSA_ERROR_INSUFFICIENT_MEMORY @@ -1463,7 +1463,7 @@ psa_status_t psa_hash_finish(psa_hash_operation_t *operation, * * \param[in,out] operation Active hash operation. * \param[in] hash Buffer containing the expected hash value. - * \param hash_length Size of the \c hash buffer in bytes. + * \param hash_length Size of the \p hash buffer in bytes. * * \retval #PSA_SUCCESS * The expected hash is identical to the actual hash of the message. @@ -1485,7 +1485,7 @@ psa_status_t psa_hash_verify(psa_hash_operation_t *operation, * * This function may be called at any time after psa_hash_setup(). * Aborting an operation frees all associated resources except for the - * \c operation structure itself. + * \p operation structure itself. * * Implementation should strive to be robust and handle inactive hash * operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However, @@ -1497,7 +1497,7 @@ psa_status_t psa_hash_verify(psa_hash_operation_t *operation, * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_BAD_STATE - * \c operation is not an active hash operation. + * \p operation is not an active hash operation. * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED @@ -1554,9 +1554,9 @@ typedef struct psa_mac_operation_s psa_mac_operation_t; * \retval #PSA_ERROR_EMPTY_SLOT * \retval #PSA_ERROR_NOT_PERMITTED * \retval #PSA_ERROR_INVALID_ARGUMENT - * \c key is not compatible with \c alg. + * \p key is not compatible with \p alg. * \retval #PSA_ERROR_NOT_SUPPORTED - * \c alg is not supported or is not a MAC algorithm. + * \p alg is not supported or is not a MAC algorithm. * \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE @@ -1624,7 +1624,7 @@ psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation, * \param[in,out] operation Active MAC operation. * \param[in] input Buffer containing the message fragment to add to * the MAC calculation. - * \param input_length Size of the \c input buffer in bytes. + * \param input_length Size of the \p input buffer in bytes. * * \retval #PSA_SUCCESS * Success. @@ -1670,7 +1670,7 @@ psa_status_t psa_mac_update(psa_mac_operation_t *operation, * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (not started, or already completed). * \retval #PSA_ERROR_BUFFER_TOO_SMALL - * The size of the \c mac buffer is too small. You can determine a + * The size of the \p mac buffer is too small. You can determine a * sufficient buffer size by calling PSA_MAC_FINAL_SIZE(). * \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_COMMUNICATION_FAILURE @@ -1699,7 +1699,7 @@ psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation, * * \param[in,out] operation Active MAC operation. * \param[in] mac Buffer containing the expected MAC value. - * \param mac_length Size of the \c mac buffer in bytes. + * \param mac_length Size of the \p mac buffer in bytes. * * \retval #PSA_SUCCESS * The expected MAC is identical to the actual MAC of the message. @@ -1722,7 +1722,7 @@ psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation, * This function may be called at any time after psa_mac_sign_setup() * or psa_mac_verify_setup(). * Aborting an operation frees all associated resources except for the - * \c operation structure itself. + * \p operation structure itself. * * Implementation should strive to be robust and handle inactive MAC * operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However, @@ -1734,7 +1734,7 @@ psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation, * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_BAD_STATE - * \c operation is not an active MAC operation. + * \p operation is not an active MAC operation. * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED @@ -1792,9 +1792,9 @@ typedef struct psa_cipher_operation_s psa_cipher_operation_t; * \retval #PSA_ERROR_EMPTY_SLOT * \retval #PSA_ERROR_NOT_PERMITTED * \retval #PSA_ERROR_INVALID_ARGUMENT - * \c key is not compatible with \c alg. + * \p key is not compatible with \p alg. * \retval #PSA_ERROR_NOT_SUPPORTED - * \c alg is not supported or is not a cipher algorithm. + * \p alg is not supported or is not a cipher algorithm. * \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE @@ -1841,9 +1841,9 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, * \retval #PSA_ERROR_EMPTY_SLOT * \retval #PSA_ERROR_NOT_PERMITTED * \retval #PSA_ERROR_INVALID_ARGUMENT - * \c key is not compatible with \c alg. + * \p key is not compatible with \p alg. * \retval #PSA_ERROR_NOT_SUPPORTED - * \c alg is not supported or is not a cipher algorithm. + * \p alg is not supported or is not a cipher algorithm. * \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE @@ -1866,7 +1866,7 @@ psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation, * * \param[in,out] operation Active cipher operation. * \param[out] iv Buffer where the generated IV is to be written. - * \param iv_size Size of the \c iv buffer in bytes. + * \param iv_size Size of the \p iv buffer in bytes. * \param[out] iv_length On success, the number of bytes of the * generated IV. * @@ -1909,7 +1909,7 @@ psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation, * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (not started, or IV already set). * \retval #PSA_ERROR_INVALID_ARGUMENT - * The size of the \c iv is not acceptable for the chosen algorithm, + * The size of \p iv is not acceptable for the chosen algorithm, * or the chosen algorithm does not use an IV. * \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_COMMUNICATION_FAILURE @@ -1934,9 +1934,9 @@ psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation, * \param[in,out] operation Active cipher operation. * \param[in] input Buffer containing the message fragment to * encrypt or decrypt. - * \param input_length Size of the \c input buffer in bytes. + * \param input_length Size of the \p input buffer in bytes. * \param[out] output Buffer where the output is to be written. - * \param output_size Size of the \c output buffer in bytes. + * \param output_size Size of the \p output buffer in bytes. * \param[out] output_length On success, the number of bytes * that make up the returned output. * @@ -1974,7 +1974,7 @@ psa_status_t psa_cipher_update(psa_cipher_operation_t *operation, * * \param[in,out] operation Active cipher operation. * \param[out] output Buffer where the output is to be written. - * \param output_size Size of the \c output buffer in bytes. + * \param output_size Size of the \p output buffer in bytes. * \param[out] output_length On success, the number of bytes * that make up the returned output. * @@ -2000,7 +2000,7 @@ psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation, * This function may be called at any time after * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(). * Aborting an operation frees all associated resources except for the - * \c operation structure itself. + * \p operation structure itself. * * Implementation should strive to be robust and handle inactive cipher * operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However, @@ -2012,7 +2012,7 @@ psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation, * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_BAD_STATE - * \c operation is not an active cipher operation. + * \p operation is not an active cipher operation. * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED @@ -2078,9 +2078,9 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation); * \retval #PSA_ERROR_EMPTY_SLOT * \retval #PSA_ERROR_NOT_PERMITTED * \retval #PSA_ERROR_INVALID_ARGUMENT - * \c key is not compatible with \c alg. + * \p key is not compatible with \p alg. * \retval #PSA_ERROR_NOT_SUPPORTED - * \c alg is not supported or is not an AEAD algorithm. + * \p alg is not supported or is not an AEAD algorithm. * \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE @@ -2131,9 +2131,9 @@ psa_status_t psa_aead_encrypt( psa_key_slot_t key, * The ciphertext is not authentic. * \retval #PSA_ERROR_NOT_PERMITTED * \retval #PSA_ERROR_INVALID_ARGUMENT - * \c key is not compatible with \c alg. + * \p key is not compatible with \p alg. * \retval #PSA_ERROR_NOT_SUPPORTED - * \c alg is not supported or is not an AEAD algorithm. + * \p alg is not supported or is not an AEAD algorithm. * \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE @@ -2179,9 +2179,9 @@ psa_status_t psa_aead_decrypt( psa_key_slot_t key, * * \param key Key slot containing an asymmetric key pair. * \param alg A signature algorithm that is compatible with - * the type of \c key. + * the type of \p key. * \param[in] hash The hash or message to sign. - * \param hash_length Size of the \c hash buffer in bytes. + * \param hash_length Size of the \p hash buffer in bytes. * \param[in] salt A salt or label, if supported by the * signature algorithm. * If the signature algorithm does not support @@ -2189,20 +2189,20 @@ psa_status_t psa_aead_decrypt( psa_key_slot_t key, * If the signature algorithm supports an * optional salt and you do not want to pass * a salt, pass \c NULL. - * \param salt_length Size of the \c salt buffer in bytes. - * If \c salt is \c NULL, pass 0. + * \param salt_length Size of the \p salt buffer in bytes. + * If \p salt is \c NULL, pass 0. * \param[out] signature Buffer where the signature is to be written. - * \param signature_size Size of the \c signature buffer in bytes. + * \param signature_size Size of the \p signature buffer in bytes. * \param[out] signature_length On success, the number of bytes * that make up the returned signature value. * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_BUFFER_TOO_SMALL - * The size of the \c signature buffer is too small. You can + * The size of the \p signature buffer is too small. You can * determine a sufficient buffer size by calling * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) * where \c key_type and \c key_bits are the type and bit-size - * respectively of \c key. + * respectively of \p key. * \retval #PSA_ERROR_NOT_SUPPORTED * \retval #PSA_ERROR_INVALID_ARGUMENT * \retval #PSA_ERROR_INSUFFICIENT_MEMORY @@ -2233,10 +2233,10 @@ psa_status_t psa_asymmetric_sign(psa_key_slot_t key, * \param key Key slot containing a public key or an * asymmetric key pair. * \param alg A signature algorithm that is compatible with - * the type of \c key. + * the type of \p key. * \param[in] hash The hash or message whose signature is to be * verified. - * \param hash_length Size of the \c hash buffer in bytes. + * \param hash_length Size of the \p hash buffer in bytes. * \param[in] salt A salt or label, if supported by the signature * algorithm. * If the signature algorithm does not support a @@ -2244,10 +2244,10 @@ psa_status_t psa_asymmetric_sign(psa_key_slot_t key, * If the signature algorithm supports an optional * salt and you do not want to pass a salt, * pass \c NULL. - * \param salt_length Size of the \c salt buffer in bytes. - * If \c salt is \c NULL, pass 0. + * \param salt_length Size of the \p salt buffer in bytes. + * If \p salt is \c NULL, pass 0. * \param[in] signature Buffer containing the signature to verify. - * \param signature_length Size of the \c signature buffer in bytes. + * \param signature_length Size of the \p signature buffer in bytes. * * \retval #PSA_SUCCESS * The signature is valid. @@ -2281,9 +2281,9 @@ psa_status_t psa_asymmetric_verify(psa_key_slot_t key, * \param key Key slot containing a public key or an * asymmetric key pair. * \param alg An asymmetric encryption algorithm that is - * compatible with the type of \c key. + * compatible with the type of \p key. * \param[in] input The message to encrypt. - * \param input_length Size of the \c input buffer in bytes. + * \param input_length Size of the \p input buffer in bytes. * \param[in] salt A salt or label, if supported by the * encryption algorithm. * If the algorithm does not support a @@ -2294,21 +2294,21 @@ psa_status_t psa_asymmetric_verify(psa_key_slot_t key, * * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is * supported. - * \param salt_length Size of the \c salt buffer in bytes. - * If \c salt is \c NULL, pass 0. + * \param salt_length Size of the \p salt buffer in bytes. + * If \p salt is \c NULL, pass 0. * \param[out] output Buffer where the encrypted message is to * be written. - * \param output_size Size of the \c output buffer in bytes. + * \param output_size Size of the \p output buffer in bytes. * \param[out] output_length On success, the number of bytes * that make up the returned output. * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_BUFFER_TOO_SMALL - * The size of the \c output buffer is too small. You can + * The size of the \p output buffer is too small. You can * determine a sufficient buffer size by calling * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) * where \c key_type and \c key_bits are the type and bit-size - * respectively of \c key. + * respectively of \p key. * \retval #PSA_ERROR_NOT_SUPPORTED * \retval #PSA_ERROR_INVALID_ARGUMENT * \retval #PSA_ERROR_INSUFFICIENT_MEMORY @@ -2332,9 +2332,9 @@ psa_status_t psa_asymmetric_encrypt(psa_key_slot_t key, * * \param key Key slot containing an asymmetric key pair. * \param alg An asymmetric encryption algorithm that is - * compatible with the type of \c key. + * compatible with the type of \p key. * \param[in] input The message to decrypt. - * \param input_length Size of the \c input buffer in bytes. + * \param input_length Size of the \p input buffer in bytes. * \param[in] salt A salt or label, if supported by the * encryption algorithm. * If the algorithm does not support a @@ -2345,8 +2345,8 @@ psa_status_t psa_asymmetric_encrypt(psa_key_slot_t key, * * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is * supported. - * \param salt_length Size of the \c salt buffer in bytes. - * If \c salt is \c NULL, pass 0. + * \param salt_length Size of the \p salt buffer in bytes. + * If \p salt is \c NULL, pass 0. * \param[out] output Buffer where the decrypted message is to * be written. * \param output_size Size of the \c output buffer in bytes. @@ -2355,11 +2355,11 @@ psa_status_t psa_asymmetric_encrypt(psa_key_slot_t key, * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_BUFFER_TOO_SMALL - * The size of the \c output buffer is too small. You can + * The size of the \p output buffer is too small. You can * determine a sufficient buffer size by calling * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) * where \c key_type and \c key_bits are the type and bit-size - * respectively of \c key. + * respectively of \p key. * \retval #PSA_ERROR_NOT_SUPPORTED * \retval #PSA_ERROR_INVALID_ARGUMENT * \retval #PSA_ERROR_INSUFFICIENT_MEMORY @@ -2426,17 +2426,17 @@ typedef struct { * \param bits Key size in bits. * \param[in] extra Extra parameters for key generation. The * interpretation of this parameter depends on - * \c type. All types support \c NULL to use + * \p type. All types support \c NULL to use * default parameters. Implementation that support * the generation of vendor-specific key types * that allow extra parameters shall document * the format of these extra parameters and * the default values. For standard parameters, * the meaning of \p extra is as follows: - * - For a symmetric key type (a type \c type such + * - For a symmetric key type (a type such * that #PSA_KEY_TYPE_IS_ASYMMETRIC(\p type) is * false), \p extra must be \c NULL. - * - For an elliptic curve key type (a type \c type + * - For an elliptic curve key type (a type * such that #PSA_KEY_TYPE_IS_ECC(\p type) is * false), \p extra must be \c NULL. * - For an RSA key, \p extra is an optional From dda3bd344d42165c696b65b67b957aaec0fb89e5 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 12 Jul 2018 19:40:46 +0200 Subject: [PATCH 12/16] Doc: Minor formatting and copy fixes --- include/psa/crypto.h | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index fa2765667..43d8d0986 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -647,7 +647,7 @@ typedef uint32_t psa_algorithm_t; #define PSA_ALG_HMAC_BASE ((psa_algorithm_t)0x02800000) /** Macro to build an HMAC algorithm. * - * For example, `PSA_ALG_HMAC(PSA_ALG_SHA256)` is HMAC-SHA-256. + * For example, #PSA_ALG_HMAC(#PSA_ALG_SHA_256) is HMAC-SHA-256. * * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_HASH(\p hash_alg) is true). @@ -702,6 +702,7 @@ typedef uint32_t psa_algorithm_t; * whole number of blocks for the chosen block cipher. */ #define PSA_ALG_BLOCK_CIPHER_PAD_NONE ((psa_algorithm_t)0x00000000) + #define PSA_ALG_BLOCK_CIPHER_PAD_PKCS7 ((psa_algorithm_t)0x00010000) /** Whether the specified algorithm is a block cipher. @@ -736,6 +737,7 @@ typedef uint32_t psa_algorithm_t; #define PSA_ALG_XTS_BASE ((psa_algorithm_t)0x04000004) #define PSA_ALG_STREAM_CIPHER_BASE ((psa_algorithm_t)0x04800000) + /** The CTR stream cipher mode. * * CTR is a stream cipher which is built from a block cipher. The @@ -744,6 +746,7 @@ typedef uint32_t psa_algorithm_t; * a key of type #PSA_KEY_TYPE_AES and a length of 128 bits (16 bytes). */ #define PSA_ALG_CTR ((psa_algorithm_t)0x04800001) + /** The ARC4 stream cipher algorithm. */ #define PSA_ALG_ARC4 ((psa_algorithm_t)0x04800002) @@ -1660,9 +1663,9 @@ psa_status_t psa_mac_update(psa_mac_operation_t *operation, * \param mac_size Size of the \p mac buffer in bytes. * \param[out] mac_length On success, the number of bytes * that make up the MAC value. This is always - * #PSA_MAC_FINAL_SIZE(\c key_type, \c key_bits, \p alg) + * #PSA_MAC_FINAL_SIZE(\c key_type, \c key_bits, \c alg) * where \c key_type and \c key_bits are the type and - * bit-size respectively of \c key and `alg` is the + * bit-size respectively of the key and \c alg is the * MAC algorithm that is calculated. * * \retval #PSA_SUCCESS @@ -1875,7 +1878,7 @@ psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation, * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (not started, or IV already set). * \retval #PSA_ERROR_BUFFER_TOO_SMALL - * The size of the \c output buffer is too small. + * The size of the \p iv buffer is too small. * \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE @@ -2357,7 +2360,7 @@ psa_status_t psa_asymmetric_encrypt(psa_key_slot_t key, * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p output buffer is too small. You can * determine a sufficient buffer size by calling - * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) + * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) * where \c key_type and \c key_bits are the type and bit-size * respectively of \p key. * \retval #PSA_ERROR_NOT_SUPPORTED @@ -2439,8 +2442,9 @@ typedef struct { * - For an elliptic curve key type (a type * such that #PSA_KEY_TYPE_IS_ECC(\p type) is * false), \p extra must be \c NULL. - * - For an RSA key, \p extra is an optional - * #psa_generate_key_extra_rsa structure + * - For an RSA key (\p type is + * #PSA_KEY_TYPE_RSA_KEYPAIR), \p extra is an + * optional #psa_generate_key_extra_rsa structure * specifying the public exponent. The * default public exponent used when \p extra * is \c NULL is 65537. From 6ac73a912bda829756b6d6772c28c64727d2f4d2 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 12 Jul 2018 19:47:19 +0200 Subject: [PATCH 13/16] Doc: add some missing documentation of function and macro parameters --- include/psa/crypto.h | 44 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 43d8d0986..4b2e9a0aa 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -682,6 +682,8 @@ typedef uint32_t psa_algorithm_t; #define PSA_ALG_GMAC ((psa_algorithm_t)0x02c00003) /** Whether the specified algorithm is a MAC algorithm based on a block cipher. + * + * \param alg An algorithm identifier (value of type #psa_algorithm_t). * * \return 1 if \p alg is a MAC algorithm based on a block cipher, 0 otherwise. * This macro may return either 0 or 1 if \p alg is not a supported @@ -1194,7 +1196,10 @@ typedef uint32_t psa_key_usage_t; typedef struct psa_key_policy_s psa_key_policy_t; /** \brief Initialize a key policy structure to a default that forbids all - * usage of the key. */ + * usage of the key. + * + * \param[out] policy The policy object to initialize. + */ void psa_key_policy_init(psa_key_policy_t *policy); /** \brief Set the standard fields of a policy structure. @@ -1202,15 +1207,29 @@ void psa_key_policy_init(psa_key_policy_t *policy); * Note that this function does not make any consistency check of the * parameters. The values are only checked when applying the policy to * a key slot with psa_set_key_policy(). + * + * \param[out] policy The policy object to modify. + * \param usage The permitted uses for the key. + * \param alg The algorithm that the key may be used for. */ void psa_key_policy_set_usage(psa_key_policy_t *policy, psa_key_usage_t usage, psa_algorithm_t alg); -/** \brief Retrieve the usage field of a policy structure. */ +/** \brief Retrieve the usage field of a policy structure. + * + * \param[in] policy The policy object to query. + * + * \return The permitted uses for a key with this policy. + */ psa_key_usage_t psa_key_policy_get_usage(const psa_key_policy_t *policy); -/** \brief Retrieve the algorithm field of a policy structure. */ +/** \brief Retrieve the algorithm field of a policy structure. + * + * \param[in] policy The policy object to query. + * + * \return The permitted algorithm for a key with this policy. + */ psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy); /** \brief Set the usage policy on a key slot. @@ -1221,11 +1240,30 @@ psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy); * * Implementations may set restrictions on supported key policies * depending on the key type and the key slot. + * + * \param key The key slot whose policy is to be changed. + * \param[in] policy The policy object to query. + * + * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_OCCUPIED_SLOT + * \retval #PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_set_key_policy(psa_key_slot_t key, const psa_key_policy_t *policy); /** \brief Get the usage policy for a key slot. + * + * \param key The key slot whose policy is being queried. + * \param[out] policy On success, the key's policy. + * + * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_COMMUNICATION_FAILURE + * \retval #PSA_ERROR_HARDWARE_FAILURE + * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_get_key_policy(psa_key_slot_t key, psa_key_policy_t *policy); From 9ac9426731a58cee9b13b7184e457c00fc54ac52 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 12 Jul 2018 20:15:32 +0200 Subject: [PATCH 14/16] Doc: clarify the preconditions for psa_cipher_update --- include/psa/crypto.h | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 4b2e9a0aa..8a80620dd 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -1963,12 +1963,12 @@ psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation, /** Encrypt or decrypt a message fragment in an active cipher operation. * - * The application must call psa_cipher_encrypt_setup() or - * psa_cipher_decrypt_setup() before calling this function. The choice - * of setup function determines whether this function encrypts or - * decrypts its input. After calling a setup function, if the chosen - * algorithm requires an IV, the application must call - * psa_cipher_generate_iv() or psa_cipher_set_iv(). + * Before calling this function, you must: + * 1. Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(). + * The choice of setup function determines whether this function + * encrypts or decrypts its input. + * 2. If the algorithm requires an IV, call psa_cipher_generate_iv() + * (recommended when encrypting) or psa_cipher_set_iv(). * * If this function returns an error status, the operation becomes inactive. * From be42f312a81d2ac628ad05de20fbd0c398ee794a Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 13 Jul 2018 14:38:15 +0200 Subject: [PATCH 15/16] Doxygen: use \c foo in preference to `foo` for consistency --- include/psa/crypto.h | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 8a80620dd..d5bda81f9 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -97,7 +97,7 @@ typedef int32_t psa_status_t; /** An output buffer is too small. * - * Applications can call the `PSA_xxx_SIZE` macro listed in the function + * Applications can call the \c PSA_xxx_SIZE macro listed in the function * description to determine a sufficient buffer size. * * Implementations should preferably return this error code only @@ -356,8 +356,8 @@ typedef uint32_t psa_key_type_t; * used for. * * HMAC keys should generally have the same size as the underlying hash. - * This size can be calculated with #PSA_HASH_SIZE(\p alg) where - * `alg` is the HMAC algorithm or the underlying hash algorithm. */ + * This size can be calculated with #PSA_HASH_SIZE(\c alg) where + * \c alg is the HMAC algorithm or the underlying hash algorithm. */ #define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x02000001) /** Key for an cipher, AEAD or MAC algorithm based on the AES block cipher. @@ -1357,7 +1357,7 @@ typedef struct psa_hash_operation_s psa_hash_operation_t; * * \param alg A hash algorithm (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_HASH(\p alg) is true), or an HMAC algorithm - * (#PSA_ALG_HMAC(`hash_alg`) where `hash_alg` is a + * (#PSA_ALG_HMAC(\c hash_alg) where \c hash_alg is a * hash algorithm). * * \return The hash size for the specified hash algorithm. @@ -1466,7 +1466,7 @@ psa_status_t psa_hash_update(psa_hash_operation_t *operation, * \param hash_size Size of the \p hash buffer in bytes. * \param[out] hash_length On success, the number of bytes * that make up the hash value. This is always - * #PSA_HASH_SIZE(`alg`) where `alg` is the + * #PSA_HASH_SIZE(\c alg) where \c alg is the * hash algorithm that is calculated. * * \retval #PSA_SUCCESS @@ -2450,7 +2450,7 @@ psa_status_t psa_generate_random(uint8_t *output, /** Extra parameters for RSA key generation. * - * You may pass a pointer to a structure of this type as the `extra` + * You may pass a pointer to a structure of this type as the \c extra * parameter to psa_generate_key(). */ typedef struct { From b82ab6f402535f5b262fb2f1faa70c7f8ac0b402 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 13 Jul 2018 15:33:43 +0200 Subject: [PATCH 16/16] Improve documentation of abort functions Explicitly state that calling abort is safe after initializing to zero. Explicitly state that calling abort on an inactive operation is safe, and replace "active" by "initialized" in the description of the parameter. Get rid of the recommendation for implementers to try to handle uninitialized structures safely. It's good advice in principle but cannot be achieved in a robust way and the wording was confusing. --- include/psa/crypto.h | 70 ++++++++++++++++++++++++++++---------------- 1 file changed, 44 insertions(+), 26 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index d5bda81f9..8ac817a6e 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -1524,17 +1524,23 @@ psa_status_t psa_hash_verify(psa_hash_operation_t *operation, /** Abort a hash operation. * - * This function may be called at any time after psa_hash_setup(). * Aborting an operation frees all associated resources except for the - * \p operation structure itself. + * \p operation structure itself. Once aborted, the operation object + * can be reused for another operation by calling + * psa_hash_setup() again. * - * Implementation should strive to be robust and handle inactive hash - * operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However, - * application writers should beware that uninitialized memory may happen - * to be indistinguishable from an active hash operation, and the behavior - * of psa_hash_abort() is undefined in this case. + * You may call this function any time after the operation object has + * been initialized by any of the following methods: + * - A call to psa_hash_setup(), whether it succeeds or not. + * - Initializing the \c struct to all-bits-zero. + * - Initializing the \c struct to logical zeros, e.g. + * `psa_hash_operation_t operation = {0}`. * - * \param[in,out] operation Active hash operation. + * In particular, calling psa_hash_abort() after the operation has been + * terminated by a call to psa_hash_abort(), psa_hash_finish() or + * psa_hash_verify() is safe and has no effect. + * + * \param[in,out] operation Initialized hash operation. * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_BAD_STATE @@ -1760,18 +1766,24 @@ psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation, /** Abort a MAC operation. * - * This function may be called at any time after psa_mac_sign_setup() - * or psa_mac_verify_setup(). * Aborting an operation frees all associated resources except for the - * \p operation structure itself. + * \p operation structure itself. Once aborted, the operation object + * can be reused for another operation by calling + * psa_mac_sign_setup() or psa_mac_verify_setup() again. * - * Implementation should strive to be robust and handle inactive MAC - * operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However, - * application writers should beware that uninitialized memory may happen - * to be indistinguishable from an active MAC operation, and the behavior - * of psa_mac_abort() is undefined in this case. + * You may call this function any time after the operation object has + * been initialized by any of the following methods: + * - A call to psa_mac_sign_setup() or psa_mac_verify_setup(), whether + * it succeeds or not. + * - Initializing the \c struct to all-bits-zero. + * - Initializing the \c struct to logical zeros, e.g. + * `psa_mac_operation_t operation = {0}`. * - * \param[in,out] operation Active MAC operation. + * In particular, calling psa_mac_abort() after the operation has been + * terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or + * psa_mac_verify_finish() is safe and has no effect. + * + * \param[in,out] operation Initialized MAC operation. * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_BAD_STATE @@ -2038,18 +2050,24 @@ psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation, /** Abort a cipher operation. * - * This function may be called at any time after - * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(). * Aborting an operation frees all associated resources except for the - * \p operation structure itself. + * \p operation structure itself. Once aborted, the operation object + * can be reused for another operation by calling + * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again. * - * Implementation should strive to be robust and handle inactive cipher - * operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However, - * application writers should beware that uninitialized memory may happen - * to be indistinguishable from an active cipher operation, and the behavior - * of psa_cipher_abort() is undefined in this case. + * You may call this function any time after the operation object has + * been initialized by any of the following methods: + * - A call to psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(), + * whether it succeeds or not. + * - Initializing the \c struct to all-bits-zero. + * - Initializing the \c struct to logical zeros, e.g. + * `psa_cipher_operation_t operation = {0}`. * - * \param[in,out] operation Active cipher operation. + * In particular, calling psa_cipher_abort() after the operation has been + * terminated by a call to psa_cipher_abort() or psa_cipher_finish() + * is safe and has no effect. + * + * \param[in,out] operation Initialized cipher operation. * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_BAD_STATE