psa: Fix references to macros in comments
This commit tries to fix the usage of #MACRO_NAME
to reference macros in comments.
Signed-off-by: Ronald Cron <ronald.cron@arm.com>
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index f1f5bd8..0a7f3c8 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -467,9 +467,9 @@
* implementation-defined.
*
* \param source_key The key to copy. It must allow the usage
- * PSA_KEY_USAGE_COPY. If a private or secret key is
+ * #PSA_KEY_USAGE_COPY. If a private or secret key is
* being copied outside of a secure element it must
- * also allow PSA_KEY_USAGE_EXPORT.
+ * also allow #PSA_KEY_USAGE_EXPORT.
* \param[in] attributes The attributes for the new key.
* They are used as follows:
* - The key type and size may be 0. If either is
@@ -535,7 +535,7 @@
* key will cause the multipart operation to fail.
*
* \param key Identifier of the key to erase. If this is \c 0, do nothing and
- * return PSA_SUCCESS.
+ * return #PSA_SUCCESS.
*
* \retval #PSA_SUCCESS
* \p key was a valid identifier and the key material that it
@@ -704,7 +704,7 @@
* The policy on the key must have the usage flag #PSA_KEY_USAGE_EXPORT set.
*
* \param key Identifier of the key to export. It must allow the
- * usage PSA_KEY_USAGE_EXPORT, unless it is a public
+ * usage #PSA_KEY_USAGE_EXPORT, unless it is a public
* key.
* \param[out] data Buffer where the key data is to be written.
* \param data_size Size of the \p data buffer in bytes.
@@ -1596,7 +1596,7 @@
* #psa_cipher_operation_t object to provide other forms of IV.
*
* \param key Identifier of the key to use for the operation.
- * It must allow the usage PSA_KEY_USAGE_ENCRYPT.
+ * It must allow the usage #PSA_KEY_USAGE_ENCRYPT.
* \param alg The cipher algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_CIPHER(\p alg) is true).
@@ -1643,7 +1643,7 @@
* \param key Identifier of the key to use for the operation.
* It must remain valid until the operation
* terminates. It must allow the usage
- * PSA_KEY_USAGE_DECRYPT.
+ * #PSA_KEY_USAGE_DECRYPT.
* \param alg The cipher algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_CIPHER(\p alg) is true).
@@ -1764,7 +1764,7 @@
* \param key Identifier of the key to use for the operation.
* It must remain valid until the operation
* terminates. It must allow the usage
- * PSA_KEY_USAGE_ENCRYPT.
+ * #PSA_KEY_USAGE_ENCRYPT.
* \param alg The cipher algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_CIPHER(\p alg) is true).
@@ -1828,7 +1828,7 @@
* \param key Identifier of the key to use for the operation.
* It must remain valid until the operation
* terminates. It must allow the usage
- * PSA_KEY_USAGE_DECRYPT.
+ * #PSA_KEY_USAGE_DECRYPT.
* \param alg The cipher algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_CIPHER(\p alg) is true).
@@ -2070,7 +2070,7 @@
*
* \param key Identifier of the key to use for the
* operation. It must allow the usage
- * PSA_KEY_USAGE_ENCRYPT.
+ * #PSA_KEY_USAGE_ENCRYPT.
* \param alg The AEAD algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(\p alg) is true).
@@ -2132,7 +2132,7 @@
*
* \param key Identifier of the key to use for the
* operation. It must allow the usage
- * PSA_KEY_USAGE_DECRYPT.
+ * #PSA_KEY_USAGE_DECRYPT.
* \param alg The AEAD algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(\p alg) is true).
@@ -2277,7 +2277,7 @@
* \param key Identifier of the key to use for the operation.
* It must remain valid until the operation
* terminates. It must allow the usage
- * PSA_KEY_USAGE_ENCRYPT.
+ * #PSA_KEY_USAGE_ENCRYPT.
* \param alg The AEAD algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(\p alg) is true).
@@ -2286,7 +2286,7 @@
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (it must be inactive).
- * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p key is not compatible with \p alg.
@@ -2344,7 +2344,7 @@
* \param key Identifier of the key to use for the operation.
* It must remain valid until the operation
* terminates. It must allow the usage
- * PSA_KEY_USAGE_DECRYPT.
+ * #PSA_KEY_USAGE_DECRYPT.
* \param alg The AEAD algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(\p alg) is true).
@@ -2353,7 +2353,7 @@
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (it must be inactive).
- * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p key is not compatible with \p alg.
@@ -2396,7 +2396,7 @@
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (it must be an active aead encrypt
- operation, with no nonce set).
+ * operation, with no nonce set).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p nonce buffer is too small.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2830,7 +2830,7 @@
*
* \param key Identifier of the key to use for the operation.
* It must be an asymmetric key pair. The key must
- * allow the usage PSA_KEY_USAGE_SIGN_HASH.
+ * allow the usage #PSA_KEY_USAGE_SIGN_HASH.
* \param alg A signature algorithm that is compatible with
* the type of \p key.
* \param[in] hash The hash or message to sign.
@@ -2881,7 +2881,8 @@
*
* \param key Identifier of the key to use for the operation. It
* must be a public key or an asymmetric key pair. The
- * key must allow the usage PSA_KEY_USAGE_VERIFY_HASH.
+ * key must allow the usage
+ * #PSA_KEY_USAGE_VERIFY_HASH.
* \param alg A signature algorithm that is compatible with
* the type of \p key.
* \param[in] hash The hash or message whose signature is to be
@@ -2922,7 +2923,7 @@
* \param key Identifer of the key to use for the operation.
* It must be a public key or an asymmetric key
* pair. It must allow the usage
- * PSA_KEY_USAGE_ENCRYPT.
+ * #PSA_KEY_USAGE_ENCRYPT.
* \param alg An asymmetric encryption algorithm that is
* compatible with the type of \p key.
* \param[in] input The message to encrypt.
@@ -2982,7 +2983,7 @@
*
* \param key Identifier of the key to use for the operation.
* It must be an asymmetric key pair. It must
- * allow the usage PSA_KEY_USAGE_DECRYPT.
+ * allow the usage #PSA_KEY_USAGE_DECRYPT.
* \param alg An asymmetric encryption algorithm that is
* compatible with the type of \p key.
* \param[in] input The message to decrypt.
@@ -3288,7 +3289,7 @@
* \param step Which step the input data is for.
* \param key Identifier of the key. It must have an
* appropriate type for step and must allow the
- * usage PSA_KEY_USAGE_DERIVE.
+ * usage #PSA_KEY_USAGE_DERIVE.
*
* \retval #PSA_SUCCESS
* Success.
@@ -3340,7 +3341,7 @@
* input of the type given by \p step.
* \param step Which step the input data is for.
* \param private_key Identifier of the private key to use. It must
- * allow the usage PSA_KEY_USAGE_DERIVE.
+ * allow the usage #PSA_KEY_USAGE_DERIVE.
* \param[in] peer_key Public key of the peer. The peer key must be in the
* same format that psa_import_key() accepts for the
* public key type corresponding to the type of
@@ -3610,7 +3611,7 @@
* #PSA_ALG_IS_RAW_KEY_AGREEMENT(\p alg)
* is true).
* \param private_key Identifier of the private key to use. It must
- * allow the usage PSA_KEY_USAGE_DERIVE.
+ * allow the usage #PSA_KEY_USAGE_DERIVE.
* \param[in] peer_key Public key of the peer. It must be
* in the same format that psa_import_key()
* accepts. The standard formats for public
diff --git a/include/psa/crypto_accel_driver.h b/include/psa/crypto_accel_driver.h
index 1a193c5..4488ea8 100644
--- a/include/psa/crypto_accel_driver.h
+++ b/include/psa/crypto_accel_driver.h
@@ -75,7 +75,7 @@
* \param[in,out] p_context A structure that will contain the
* hardware-specific hash context
*
- * \retval PSA_SUCCESS Success.
+ * \retval #PSA_SUCCESS Success.
*/
typedef psa_status_t (*psa_drv_hash_setup_t)(psa_drv_hash_context_t *p_context);
@@ -120,7 +120,7 @@
* \param[out] p_output_length The number of bytes placed in `p_output` after
* success
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
*/
typedef psa_status_t (*psa_drv_hash_finish_t)(psa_drv_hash_context_t *p_context,
@@ -188,7 +188,7 @@
* to be used in the operation
* \param[in] key_length The size in bytes of the key material
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
*/
typedef psa_status_t (*psa_drv_accel_mac_setup_t)(psa_drv_accel_mac_context_t *p_context,
@@ -235,7 +235,7 @@
* \param[in] mac_length The size in bytes of the buffer that has been
* allocated for the `p_mac` buffer
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
*/
typedef psa_status_t (*psa_drv_accel_mac_finish_t)(psa_drv_accel_mac_context_t *p_context,
@@ -261,7 +261,7 @@
* \param[in] mac_length The size in bytes of the data in the `p_mac`
* buffer
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* The operation completed successfully and the comparison matched
*/
typedef psa_status_t (*psa_drv_accel_mac_finish_verify_t)(psa_drv_accel_mac_context_t *p_context,
@@ -335,7 +335,7 @@
* \param[in] p_mac The MAC data to be compared
* \param[in] mac_length The length in bytes of the `p_mac` buffer
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* The operation completed successfully and the comparison matched
*/
typedef psa_status_t (*psa_drv_accel_mac_verify_t)(const uint8_t *p_input,
@@ -396,7 +396,7 @@
* to be used in the operation
* \param[in] key_data_size The size in bytes of the key material
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_accel_cipher_setup_t)(psa_drv_accel_cipher_context_t *p_context,
psa_encrypt_or_decrypt_t direction,
@@ -419,7 +419,7 @@
* \param[in] p_iv A buffer containing the initialization vecotr
* \param[in] iv_length The size in bytes of the contents of `p_iv`
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_accel_cipher_set_iv_t)(psa_drv_accel_cipher_context_t *p_context,
const uint8_t *p_iv,
@@ -448,7 +448,7 @@
* \param[out] p_output_length After completion, will contain the number
* of bytes placed in the `p_output` buffer
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_accel_cipher_update_t)(psa_drv_accel_cipher_context_t *p_context,
const uint8_t *p_input,
@@ -477,7 +477,7 @@
* \param[out] p_output_length After completion, will contain the number of
* bytes placed in the `p_output` buffer
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_accel_cipher_finish_t)(psa_drv_accel_cipher_context_t *p_context,
uint8_t *p_output,
@@ -499,7 +499,7 @@
* \param[in,out] p_context A hardware-specific structure for the
* previously started cipher operation
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_accel_cipher_abort_t)(psa_drv_accel_cipher_context_t *p_context);
@@ -659,7 +659,7 @@
* \param[out] p_signature_length On success, the number of bytes
* that make up the returned signature value
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_accel_asymmetric_sign_t)(const uint8_t *p_key,
size_t key_size,
@@ -697,7 +697,7 @@
* \param[in] p_signature Buffer containing the signature to verify
* \param[in] signature_length Size of the `p_signature` buffer in bytes
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* The signature is valid.
*/
typedef psa_status_t (*psa_drv_accel_asymmetric_verify_t)(const uint8_t *p_key,
@@ -748,7 +748,7 @@
* \param[out] p_output_length On success, the number of bytes
* that make up the returned output
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_accel_asymmetric_encrypt_t)(const uint8_t *p_key,
size_t key_size,
@@ -800,7 +800,7 @@
* \param[out] p_output_length On success, the number of bytes
* that make up the returned output
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_accel_asymmetric_decrypt_t)(const uint8_t *p_key,
size_t key_size,
diff --git a/include/psa/crypto_entropy_driver.h b/include/psa/crypto_entropy_driver.h
index 6175044..9b6546e 100644
--- a/include/psa/crypto_entropy_driver.h
+++ b/include/psa/crypto_entropy_driver.h
@@ -47,7 +47,7 @@
* containing any context information for
* the implementation
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_entropy_init_t)(void *p_context);
@@ -75,7 +75,7 @@
* \param[out] p_received_entropy_bits The amount of entropy (in bits)
* actually provided in `p_buffer`
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_entropy_get_bits_t)(void *p_context,
uint8_t *p_buffer,
diff --git a/include/psa/crypto_se_driver.h b/include/psa/crypto_se_driver.h
index 46b2d64..1fae575 100644
--- a/include/psa/crypto_se_driver.h
+++ b/include/psa/crypto_se_driver.h
@@ -178,7 +178,7 @@
* \param[in] algorithm The algorithm to be used to underly the MAC
* operation
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
*/
typedef psa_status_t (*psa_drv_se_mac_setup_t)(psa_drv_se_context_t *drv_context,
@@ -213,7 +213,7 @@
* \param[out] p_mac_length After completion, will contain the number of
* bytes placed in the `p_mac` buffer
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
*/
typedef psa_status_t (*psa_drv_se_mac_finish_t)(void *op_context,
@@ -230,10 +230,10 @@
* will be compared against
* \param[in] mac_length The size in bytes of the value stored in `p_mac`
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* The operation completed successfully and the MACs matched each
* other
- * \retval PSA_ERROR_INVALID_SIGNATURE
+ * \retval #PSA_ERROR_INVALID_SIGNATURE
* The operation completed successfully, but the calculated MAC did
* not match the provided MAC
*/
@@ -264,7 +264,7 @@
* \param[out] p_mac_length After completion, will contain the number of
* bytes placed in the `output` buffer
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
*/
typedef psa_status_t (*psa_drv_se_mac_generate_t)(psa_drv_se_context_t *drv_context,
@@ -289,10 +289,10 @@
* be compared against
* \param[in] mac_length The size in bytes of `mac`
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* The operation completed successfully and the MACs matched each
* other
- * \retval PSA_ERROR_INVALID_SIGNATURE
+ * \retval #PSA_ERROR_INVALID_SIGNATURE
* The operation completed successfully, but the calculated MAC did
* not match the provided MAC
*/
@@ -384,8 +384,8 @@
* \param[in] direction Indicates whether the operation is an encrypt
* or decrypt
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_NOT_SUPPORTED
*/
typedef psa_status_t (*psa_drv_se_cipher_setup_t)(psa_drv_se_context_t *drv_context,
void *op_context,
@@ -406,7 +406,7 @@
* \param[in] p_iv A buffer containing the initialization vector
* \param[in] iv_length The size (in bytes) of the `p_iv` buffer
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_se_cipher_set_iv_t)(void *op_context,
const uint8_t *p_iv,
@@ -428,7 +428,7 @@
* \param[out] p_output_length After completion, will contain the number
* of bytes placed in the `p_output` buffer
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_se_cipher_update_t)(void *op_context,
const uint8_t *p_input,
@@ -449,7 +449,7 @@
* \param[out] p_output_length After completion, will contain the number of
* bytes placed in the `p_output` buffer
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_se_cipher_finish_t)(void *op_context,
uint8_t *p_output,
@@ -484,8 +484,8 @@
* \param[in] output_size The allocated size in bytes of the `p_output`
* buffer
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_NOT_SUPPORTED
*/
typedef psa_status_t (*psa_drv_se_cipher_ecb_t)(psa_drv_se_context_t *drv_context,
psa_key_slot_number_t key_slot,
@@ -553,7 +553,7 @@
* \param[out] p_signature_length On success, the number of bytes
* that make up the returned signature value
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_se_asymmetric_sign_t)(psa_drv_se_context_t *drv_context,
psa_key_slot_number_t key_slot,
@@ -578,7 +578,7 @@
* \param[in] p_signature Buffer containing the signature to verify
* \param[in] signature_length Size of the `p_signature` buffer in bytes
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* The signature is valid.
*/
typedef psa_status_t (*psa_drv_se_asymmetric_verify_t)(psa_drv_se_context_t *drv_context,
@@ -617,7 +617,7 @@
* \param[out] p_output_length On success, the number of bytes that make up
* the returned output
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_se_asymmetric_encrypt_t)(psa_drv_se_context_t *drv_context,
psa_key_slot_number_t key_slot,
@@ -657,7 +657,7 @@
* \param[out] p_output_length On success, the number of bytes
* that make up the returned output
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_se_asymmetric_decrypt_t)(psa_drv_se_context_t *drv_context,
psa_key_slot_number_t key_slot,
@@ -1195,7 +1195,7 @@
* \param[in] source_key The key to be used as the source material for
* the key derivation
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_se_key_derivation_setup_t)(psa_drv_se_context_t *drv_context,
void *op_context,
@@ -1215,7 +1215,7 @@
* \param[in] p_collateral A buffer containing the collateral data
* \param[in] collateral_size The size in bytes of the collateral
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_se_key_derivation_collateral_t)(void *op_context,
uint32_t collateral_id,
@@ -1230,7 +1230,7 @@
* \param[in] dest_key The slot where the generated key material
* should be placed
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_se_key_derivation_derive_t)(void *op_context,
psa_key_slot_number_t dest_key);
@@ -1244,7 +1244,7 @@
* \param[out] p_output_length Upon success, contains the number of bytes of
* key material placed in `p_output`
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
*/
typedef psa_status_t (*psa_drv_se_key_derivation_export_t)(void *op_context,
uint8_t *p_output,
@@ -1353,7 +1353,7 @@
* \param location The location value through which this driver will
* be exposed to applications.
* This driver will be used for all keys such that
- * `location == PSA_KEY_LIFETIME_LOCATION( lifetime )`.
+ * `location == #PSA_KEY_LIFETIME_GET_LOCATION( lifetime )`.
* The value #PSA_KEY_LOCATION_LOCAL_STORAGE is reserved
* and may not be used for drivers. Implementations
* may reserve other values.
@@ -1362,22 +1362,22 @@
* module keeps running. It is typically a global
* constant.
*
- * \return PSA_SUCCESS
+ * \return #PSA_SUCCESS
* The driver was successfully registered. Applications can now
* use \p lifetime to access keys through the methods passed to
* this function.
- * \return PSA_ERROR_BAD_STATE
+ * \return #PSA_ERROR_BAD_STATE
* This function was called after the initialization of the
* cryptography module, and this implementation does not support
* driver registration at this stage.
- * \return PSA_ERROR_ALREADY_EXISTS
+ * \return #PSA_ERROR_ALREADY_EXISTS
* There is already a registered driver for this value of \p lifetime.
- * \return PSA_ERROR_INVALID_ARGUMENT
+ * \return #PSA_ERROR_INVALID_ARGUMENT
* \p lifetime is a reserved value.
- * \return PSA_ERROR_NOT_SUPPORTED
+ * \return #PSA_ERROR_NOT_SUPPORTED
* `methods->hal_version` is not supported by this implementation.
- * \return PSA_ERROR_INSUFFICIENT_MEMORY
- * \return PSA_ERROR_NOT_PERMITTED
+ * \return #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \return #PSA_ERROR_NOT_PERMITTED
*/
psa_status_t psa_register_se_driver(
psa_key_location_t location,
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index 9828768..580b89e 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -1452,7 +1452,7 @@
* a key derivation function.
* Usually, raw key agreement algorithms are constructed directly with
* a \c PSA_ALG_xxx macro while non-raw key agreement algorithms are
- * constructed with PSA_ALG_KEY_AGREEMENT().
+ * constructed with #PSA_ALG_KEY_AGREEMENT().
*
* \param alg An algorithm identifier (value of type #psa_algorithm_t).
*
diff --git a/library/psa_crypto_core.h b/library/psa_crypto_core.h
index 8d1f1bb..86d804b 100644
--- a/library/psa_crypto_core.h
+++ b/library/psa_crypto_core.h
@@ -130,10 +130,10 @@
*
* \param[in,out] slot The key slot to wipe.
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success. This includes the case of a key slot that was
* already fully wiped.
- * \retval PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
*/
psa_status_t psa_wipe_key_slot( psa_key_slot_t *slot );
diff --git a/library/psa_crypto_invasive.h b/library/psa_crypto_invasive.h
index c609c77..2b4ee1f 100644
--- a/library/psa_crypto_invasive.h
+++ b/library/psa_crypto_invasive.h
@@ -62,12 +62,12 @@
* It is called by mbedtls_psa_crypto_free().
* By default this is mbedtls_entropy_free().
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
- * \retval PSA_ERROR_NOT_PERMITTED
+ * \retval #PSA_ERROR_NOT_PERMITTED
* The caller does not have the permission to configure
* entropy sources.
- * \retval PSA_ERROR_BAD_STATE
+ * \retval #PSA_ERROR_BAD_STATE
* The library has already been initialized.
*/
psa_status_t mbedtls_psa_crypto_configure_entropy_sources(
diff --git a/library/psa_crypto_its.h b/library/psa_crypto_its.h
index b671d63..11703a0 100644
--- a/library/psa_crypto_its.h
+++ b/library/psa_crypto_its.h
@@ -72,12 +72,12 @@
*
* \return A status indicating the success/failure of the operation
*
- * \retval PSA_SUCCESS The operation completed successfully
- * \retval PSA_ERROR_NOT_PERMITTED The operation failed because the provided `uid` value was already created with PSA_STORAGE_WRITE_ONCE_FLAG
- * \retval PSA_ERROR_NOT_SUPPORTED The operation failed because one or more of the flags provided in `create_flags` is not supported or is not valid
- * \retval PSA_ERROR_INSUFFICIENT_STORAGE The operation failed because there was insufficient space on the storage medium
- * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
- * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided pointers(`p_data`)
+ * \retval #PSA_SUCCESS The operation completed successfully
+ * \retval #PSA_ERROR_NOT_PERMITTED The operation failed because the provided `uid` value was already created with PSA_STORAGE_WRITE_ONCE_FLAG
+ * \retval #PSA_ERROR_NOT_SUPPORTED The operation failed because one or more of the flags provided in `create_flags` is not supported or is not valid
+ * \retval #PSA_ERROR_INSUFFICIENT_STORAGE The operation failed because there was insufficient space on the storage medium
+ * \retval #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
+ * \retval #PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided pointers(`p_data`)
* is invalid, for example is `NULL` or references memory the caller cannot access
*/
psa_status_t psa_its_set(psa_storage_uid_t uid,
@@ -97,11 +97,11 @@
*
* \return A status indicating the success/failure of the operation
*
- * \retval PSA_SUCCESS The operation completed successfully
- * \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided `uid` value was not found in the storage
- * \retval PSA_ERROR_INVALID_SIZE The operation failed because the data associated with provided uid is larger than `data_size`
- * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
- * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided pointers(`p_data`, `p_data_length`)
+ * \retval #PSA_SUCCESS The operation completed successfully
+ * \retval #PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided `uid` value was not found in the storage
+ * \retval #PSA_ERROR_INVALID_SIZE The operation failed because the data associated with provided uid is larger than `data_size`
+ * \retval #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
+ * \retval #PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided pointers(`p_data`, `p_data_length`)
* is invalid. For example is `NULL` or references memory the caller cannot access.
* In addition, this can also happen if an invalid offset was provided.
*/
@@ -119,10 +119,10 @@
*
* \return A status indicating the success/failure of the operation
*
- * \retval PSA_SUCCESS The operation completed successfully
- * \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided uid value was not found in the storage
- * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
- * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided pointers(`p_info`)
+ * \retval #PSA_SUCCESS The operation completed successfully
+ * \retval #PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided uid value was not found in the storage
+ * \retval #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
+ * \retval #PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided pointers(`p_info`)
* is invalid, for example is `NULL` or references memory the caller cannot access
*/
psa_status_t psa_its_get_info(psa_storage_uid_t uid,
@@ -135,10 +135,10 @@
*
* \return A status indicating the success/failure of the operation
*
- * \retval PSA_SUCCESS The operation completed successfully
- * \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided key value was not found in the storage
- * \retval PSA_ERROR_NOT_PERMITTED The operation failed because the provided key value was created with PSA_STORAGE_WRITE_ONCE_FLAG
- * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
+ * \retval #PSA_SUCCESS The operation completed successfully
+ * \retval #PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided key value was not found in the storage
+ * \retval #PSA_ERROR_NOT_PERMITTED The operation failed because the provided key value was created with PSA_STORAGE_WRITE_ONCE_FLAG
+ * \retval #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
*/
psa_status_t psa_its_remove(psa_storage_uid_t uid);
diff --git a/library/psa_crypto_slot_management.c b/library/psa_crypto_slot_management.c
index b6f76ad..6f6ba07 100644
--- a/library/psa_crypto_slot_management.c
+++ b/library/psa_crypto_slot_management.c
@@ -86,17 +86,17 @@
*
* For volatile key identifiers, only one key slot is queried as a volatile
* key with identifier key_id can only be stored in slot of index
- * ( key_id - PSA_KEY_ID_VOLATILE_MIN ).
+ * ( key_id - #PSA_KEY_ID_VOLATILE_MIN ).
*
* \param key Key identifier to query.
* \param[out] p_slot On success, `*p_slot` contains a pointer to the
* key slot containing the description of the key
* identified by \p key.
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* The pointer to the key slot containing the description of the key
* identified by \p key was returned.
- * \retval PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_INVALID_HANDLE
* \p key is not a valid key identifier.
* \retval #PSA_ERROR_DOES_NOT_EXIST
* There is no key with key identifier \p key in the key slots.
diff --git a/library/psa_crypto_slot_management.h b/library/psa_crypto_slot_management.h
index 9470b3e..2b90ce8 100644
--- a/library/psa_crypto_slot_management.h
+++ b/library/psa_crypto_slot_management.h
@@ -33,7 +33,7 @@
*
* The last PSA_KEY_SLOT_COUNT identifiers of the implementation range
* of key identifiers are reserved for volatile key identifiers.
- * A volatile key identifier is equal to PSA_KEY_ID_VOLATILE_MIN plus the
+ * A volatile key identifier is equal to #PSA_KEY_ID_VOLATILE_MIN plus the
* index of the key slot containing the volatile key definition.
*/
@@ -97,7 +97,7 @@
/** Initialize the key slot structures.
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Currently this function always succeeds.
*/
psa_status_t psa_initialize_key_slots( void );
diff --git a/library/psa_crypto_storage.c b/library/psa_crypto_storage.c
index 2ab5903..1ebd20e 100644
--- a/library/psa_crypto_storage.c
+++ b/library/psa_crypto_storage.c
@@ -90,9 +90,9 @@
* \param[out] data Buffer where the data is to be written.
* \param data_size Size of the \c data buffer in bytes.
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_STORAGE_FAILURE
- * \retval PSA_ERROR_DOES_NOT_EXIST
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
*/
static psa_status_t psa_crypto_storage_load(
const mbedtls_svc_key_id_t key, uint8_t *data, size_t data_size )
@@ -137,10 +137,10 @@
* \param data_length The number of bytes
* that make up the data.
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_INSUFFICIENT_STORAGE
- * \retval PSA_ERROR_STORAGE_FAILURE
- * \retval PSA_ERROR_ALREADY_EXISTS
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_ALREADY_EXISTS
*/
static psa_status_t psa_crypto_storage_store( const mbedtls_svc_key_id_t key,
const uint8_t *data,
@@ -210,8 +210,8 @@
* is to be obtained.
* \param[out] data_length The number of bytes that make up the data.
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_STORAGE_FAILURE
*/
static psa_status_t psa_crypto_storage_get_data_length(
const mbedtls_svc_key_id_t key,
diff --git a/library/psa_crypto_storage.h b/library/psa_crypto_storage.h
index 3def1b5..fbc94fc 100644
--- a/library/psa_crypto_storage.h
+++ b/library/psa_crypto_storage.h
@@ -93,11 +93,11 @@
* \param[in] data Buffer containing the key data.
* \param data_length The number of bytes that make up the key data.
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_INSUFFICIENT_STORAGE
- * \retval PSA_ERROR_STORAGE_FAILURE
- * \retval PSA_ERROR_ALREADY_EXISTS
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_ALREADY_EXISTS
*/
psa_status_t psa_save_persistent_key( const psa_core_key_attributes_t *attr,
const uint8_t *data,
@@ -122,10 +122,10 @@
* \param[out] data Pointer to an allocated key data buffer on return.
* \param[out] data_length The number of bytes that make up the key data.
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_STORAGE_FAILURE
- * \retval PSA_ERROR_DOES_NOT_EXIST
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
*/
psa_status_t psa_load_persistent_key( psa_core_key_attributes_t *attr,
uint8_t **data,
@@ -137,10 +137,10 @@
* \param key Persistent identifier of the key to remove
* from persistent storage.
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* The key was successfully removed,
* or the key did not exist.
- * \retval PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_STORAGE_FAILURE
*/
psa_status_t psa_destroy_persistent_key( const mbedtls_svc_key_id_t key );
@@ -182,10 +182,10 @@
* \param[out] attr On success, the attribute structure is filled
* with the loaded key metadata.
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_INSUFFICIENT_STORAGE
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_STORAGE_FAILURE
*/
psa_status_t psa_parse_key_data_from_storage( const uint8_t *storage_data,
size_t storage_data_length,