Merge pull request #4210 from gilles-peskine-arm/crypto_values-param-names
Fix parameter names after \p in include/psa
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 78c6e3d..7ee3293 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -3465,7 +3465,8 @@
* state and must be aborted by calling psa_key_derivation_abort().
*
* How much output is produced and consumed from the operation, and how
- * the key is derived, depends on the key type:
+ * the key is derived, depends on the key type and on the key size
+ * (denoted \c bits below):
*
* - For key types for which the key is an arbitrary sequence of bytes
* of a given size, this function is functionally equivalent to
@@ -3475,7 +3476,7 @@
* if the implementation provides an isolation boundary then
* the key material is not exposed outside the isolation boundary.
* As a consequence, for these key types, this function always consumes
- * exactly (\p bits / 8) bytes from the operation.
+ * exactly (\c bits / 8) bytes from the operation.
* The following key types defined in this specification follow this scheme:
*
* - #PSA_KEY_TYPE_AES;
@@ -3496,8 +3497,8 @@
* string and process it as specified in RFC 7748 §5.
*
* - For key types for which the key is represented by a single sequence of
- * \p bits bits with constraints as to which bit sequences are acceptable,
- * this function draws a byte string of length (\p bits / 8) bytes rounded
+ * \c bits bits with constraints as to which bit sequences are acceptable,
+ * this function draws a byte string of length (\c bits / 8) bytes rounded
* up to the nearest whole number of bytes. If the resulting byte string
* is acceptable, it becomes the key, otherwise the drawn bytes are discarded.
* This process is repeated until an acceptable byte string is drawn.
diff --git a/include/psa/crypto_compat.h b/include/psa/crypto_compat.h
index 66e6201..ae09a70 100644
--- a/include/psa/crypto_compat.h
+++ b/include/psa/crypto_compat.h
@@ -313,9 +313,9 @@
* number of open keys, the number of open key handles, or available
* memory.
* \retval #PSA_ERROR_DOES_NOT_EXIST
- * There is no persistent key with key identifier \p id.
+ * There is no persistent key with key identifier \p key.
* \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p id is not a valid persistent key identifier.
+ * \p key is not a valid persistent key identifier.
* \retval #PSA_ERROR_NOT_PERMITTED
* The specified key exists, but the application does not have the
* permission to access it. Note that this specification does not
diff --git a/include/psa/crypto_se_driver.h b/include/psa/crypto_se_driver.h
index f5fe029..aaf117f 100644
--- a/include/psa/crypto_se_driver.h
+++ b/include/psa/crypto_se_driver.h
@@ -1061,7 +1061,8 @@
* \brief A function that generates a symmetric or asymmetric key on a secure
* element
*
- * If \p type is asymmetric (#PSA_KEY_TYPE_IS_ASYMMETRIC(\p type) = 1),
+ * If the key type \c type recorded in \p attributes
+ * is asymmetric (#PSA_KEY_TYPE_IS_ASYMMETRIC(\c type) = 1),
* the driver may export the public key at the time of generation,
* in the format documented for psa_export_public_key() by writing it
* to the \p pubkey buffer.
@@ -1364,16 +1365,16 @@
*
* \return #PSA_SUCCESS
* The driver was successfully registered. Applications can now
- * use \p lifetime to access keys through the methods passed to
+ * use \p location to access keys through the methods passed to
* this function.
* \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
- * There is already a registered driver for this value of \p lifetime.
+ * There is already a registered driver for this value of \p location.
* \return #PSA_ERROR_INVALID_ARGUMENT
- * \p lifetime is a reserved value.
+ * \p location is a reserved value.
* \return #PSA_ERROR_NOT_SUPPORTED
* `methods->hal_version` is not supported by this implementation.
* \return #PSA_ERROR_INSUFFICIENT_MEMORY
diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h
index 86467eb..c9de062 100644
--- a/include/psa/crypto_sizes.h
+++ b/include/psa/crypto_sizes.h
@@ -189,7 +189,7 @@
/** This macro returns the maximum supported length of the PSK for the
* TLS-1.2 PSK-to-MS key derivation
- * (#PSA_ALG_TLS12_PSK_TO_MS(\p hash_alg)).
+ * (#PSA_ALG_TLS12_PSK_TO_MS(\c hash_alg)).
*
* The maximum supported length does not depend on the chosen hash algorithm.
*
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index a17bfc2..24b2e18 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -892,7 +892,7 @@
* for policy comparison purposes.
*
* \param mac_alg A MAC algorithm identifier (value of type
- * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
+ * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg)
* is true). This may be a truncated or untruncated
* MAC algorithm.
* \param mac_length Desired length of the truncated MAC in bytes.
@@ -903,7 +903,7 @@
*
* \return The corresponding MAC algorithm with the specified
* length.
- * \return Unspecified if \p alg is not a supported
+ * \return Unspecified if \p mac_alg is not a supported
* MAC algorithm or if \p mac_length is too small or
* too large for the specified MAC algorithm.
*/
@@ -916,12 +916,12 @@
* MAC algorithm.
*
* \param mac_alg A MAC algorithm identifier (value of type
- * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
+ * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg)
* is true). This may be a truncated or untruncated
* MAC algorithm.
*
* \return The corresponding base MAC algorithm.
- * \return Unspecified if \p alg is not a supported
+ * \return Unspecified if \p mac_alg is not a supported
* MAC algorithm.
*/
#define PSA_ALG_FULL_LENGTH_MAC(mac_alg) \
@@ -931,12 +931,12 @@
/** Length to which a MAC algorithm is truncated.
*
* \param mac_alg A MAC algorithm identifier (value of type
- * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
+ * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg)
* is true).
*
* \return Length of the truncated MAC in bytes.
- * \return 0 if \p alg is a non-truncated MAC algorithm.
- * \return Unspecified if \p alg is not a supported
+ * \return 0 if \p mac_alg is a non-truncated MAC algorithm.
+ * \return Unspecified if \p mac_alg is not a supported
* MAC algorithm.
*/
#define PSA_MAC_TRUNCATED_LENGTH(mac_alg) \
@@ -1146,13 +1146,13 @@
* of the ciphertext.
*
* \param aead_alg An AEAD algorithm identifier (value of type
- * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p alg)
+ * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p aead_alg)
* is true).
* \param tag_length Desired length of the authentication tag in bytes.
*
* \return The corresponding AEAD algorithm with the specified
* length.
- * \return Unspecified if \p alg is not a supported
+ * \return Unspecified if \p aead_alg is not a supported
* AEAD algorithm or if \p tag_length is not valid
* for the specified AEAD algorithm.
*/
@@ -1165,13 +1165,12 @@
/** Retrieve the tag length of a specified AEAD algorithm
*
* \param aead_alg An AEAD algorithm identifier (value of type
- * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p alg)
+ * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p aead_alg)
* is true).
*
* \return The tag length specified by the input algorithm.
- * \return Unspecified if \p alg is not a supported
- * AEAD algorithm or if \p tag_length is not valid
- * for the specified AEAD algorithm.
+ * \return Unspecified if \p aead_alg is not a supported
+ * AEAD algorithm.
*/
#define PSA_ALG_AEAD_GET_TAG_LENGTH(aead_alg) \
(((aead_alg) & PSA_ALG_AEAD_TAG_LENGTH_MASK) >> \
@@ -1180,7 +1179,7 @@
/** Calculate the corresponding AEAD algorithm with the default tag length.
*
* \param aead_alg An AEAD algorithm (\c PSA_ALG_XXX value such that
- * #PSA_ALG_IS_AEAD(\p alg) is true).
+ * #PSA_ALG_IS_AEAD(\p aead_alg) is true).
*
* \return The corresponding AEAD algorithm with the default
* tag length for that algorithm.