From f070a5e5d5c7c867e10bd5dc06d924c18763b29e Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Mon, 20 Jun 2022 18:40:45 +0200
Subject: [PATCH] Document how PSA identifiers are generally constructed

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
---
 include/psa/crypto_types.h | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h
index 2cf965d81b..ec6890ad01 100644
--- a/include/psa/crypto_types.h
+++ b/include/psa/crypto_types.h
@@ -70,10 +70,16 @@ typedef int32_t psa_status_t;
  */
 
 /** \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()
@@ -85,6 +91,9 @@ typedef uint16_t psa_key_type_t;
 typedef uint8_t psa_ecc_family_t;
 
 /** 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()
@@ -96,6 +105,9 @@ typedef uint8_t psa_ecc_family_t;
 typedef uint8_t psa_dh_family_t;
 
 /** \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
@@ -143,6 +155,9 @@ typedef uint32_t psa_algorithm_t;
  * #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;
 
@@ -247,7 +262,11 @@ typedef struct
  * @{
  */
 
-/** \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;
 
 /**@}*/
@@ -376,7 +395,11 @@ typedef uint64_t psa_key_slot_number_t;
  * @{
  */
 
-/** \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;
 
 /**@}*/