Document how PSA identifiers are generally constructed
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h
index 386c7d7..747063b 100644
--- a/include/psa/crypto_types.h
+++ b/include/psa/crypto_types.h
@@ -69,11 +69,17 @@
*/
/** \brief Encoding of a key type.
+ *
+ * Values of this type are generally constructed by macros called
+ * `PSA_KEY_TYPE_xxx`.
*/
typedef uint16_t psa_key_type_t;
/** The type of PSA elliptic curve family identifiers.
*
+ * Values of this type are generally constructed by macros called
+ * `PSA_ECC_FAMILY_xxx`.
+ *
* The curve identifier is required to create an ECC key using the
* PSA_KEY_TYPE_ECC_KEY_PAIR() or PSA_KEY_TYPE_ECC_PUBLIC_KEY()
* macros.
@@ -85,6 +91,9 @@
/** The type of PSA Diffie-Hellman group family identifiers.
*
+ * Values of this type are generally constructed by macros called
+ * `PSA_DH_FAMILY_xxx`.
+ *
* The group identifier is required to create an Diffie-Hellman key using the
* PSA_KEY_TYPE_DH_KEY_PAIR() or PSA_KEY_TYPE_DH_PUBLIC_KEY()
* macros.
@@ -96,6 +105,9 @@
/** \brief Encoding of a cryptographic algorithm.
*
+ * Values of this type are generally constructed by macros called
+ * `PSA_ALG_xxx`.
+ *
* For algorithms that can be applied to multiple key types, this type
* does not encode the key type. For example, for symmetric ciphers
* based on a block cipher, #psa_algorithm_t encodes the block cipher
@@ -142,6 +154,9 @@
* #PSA_KEY_LIFETIME_PERSISTENT is supported if persistent storage is
* available. Other lifetime values may be supported depending on the
* library configuration.
+ *
+ * Values of this type are generally constructed by macros called
+ * `PSA_KEY_LIFETIME_xxx`.
*/
typedef uint32_t psa_key_lifetime_t;
@@ -246,7 +261,11 @@
* @{
*/
-/** \brief Encoding of permitted usage on a key. */
+/** \brief Encoding of permitted usage on a key.
+ *
+ * Values of this type are generally constructed as bitwise-ors of macros
+ * called `PSA_KEY_USAGE_xxx`.
+ */
typedef uint32_t psa_key_usage_t;
/**@}*/
@@ -375,7 +394,11 @@
* @{
*/
-/** \brief Encoding of the step of a key derivation. */
+/** \brief Encoding of the step of a key derivation.
+ *
+ * Values of this type are generally constructed by macros called
+ * `PSA_KEY_DERIVATION_INPUT_xxx`.
+ */
typedef uint16_t psa_key_derivation_step_t;
/**@}*/