From a170d927ddb07fdc682c30907f5b731fd1c52c70 Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Thu, 12 Sep 2019 16:59:37 +0200
Subject: [PATCH] Clarify how key creation functions use attributes and what 0
 means

Clarify how key creation functions use attributes. Explain the meaning
of attribute values, espcially what 0 means in each field where it has
a special meaning. Explain what an algorithm usage policy can be (an
algorithm, a wildcard with ANY_HASH, or 0).
---
 include/psa/crypto.h       | 19 ++++++++++++++++---
 include/psa/crypto_types.h | 11 ++++++-----
 2 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 71bad3b7a..c21809ce1 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -226,7 +226,14 @@ static psa_key_usage_t psa_get_key_usage_flags(
 /** Declare the permitted algorithm policy for a key.
  *
  * The permitted algorithm policy of a key encodes which algorithm or
- * algorithms are permitted to be used with this key.
+ * algorithms are permitted to be used with this key. The following
+ * algorithm policies are supported:
+ * - 0 does not allow any cryptographic operation with the key. The key
+ *   may be used for non-cryptographic actions such as exporting (if
+ *   permitted by the usage flags).
+ * - An algorithm value permits this particular algorithm.
+ * - An algorithm wildcard built from #PSA_ALG_ANY_HASH allows the specified
+ *   signature scheme with any hash algorithm.
  *
  * This function overwrites any algorithm policy
  * previously set in \p attributes.
@@ -266,6 +273,8 @@ static psa_algorithm_t psa_get_key_algorithm(
  *
  * \param[out] attributes       The attribute structure to write to.
  * \param type                  The key type to write.
+ *                              If this is 0, the key type in \p attributes
+ *                              becomes unspecified.
  */
 static void psa_set_key_type(psa_key_attributes_t *attributes,
                              psa_key_type_t type);
@@ -281,6 +290,8 @@ static void psa_set_key_type(psa_key_attributes_t *attributes,
  *
  * \param[out] attributes       The attribute structure to write to.
  * \param bits                  The key size in bits.
+ *                              If this is 0, the key size in \p attributes
+ *                              becomes unspecified.
  */
 static void psa_set_key_bits(psa_key_attributes_t *attributes,
                              size_t bits);
@@ -464,7 +475,6 @@ psa_status_t psa_close_key(psa_key_handle_t handle);
  * minimize the risk that an invalid input is accidentally interpreted
  * according to a different format.
  *
-
  * \param[in] attributes    The attributes for the new key.
  *                          The key size is always determined from the
  *                          \p data buffer.
@@ -3365,6 +3375,9 @@ psa_status_t psa_key_derivation_output_bytes(
  *
  * This function calculates output bytes from a key derivation algorithm
  * and uses those bytes to generate a key deterministically.
+ * The key's location, usage policy, type and size are taken from
+ * \p attributes.
+ *
  * If you view the key derivation's output as a stream of bytes, this
  * function destructively reads as many bytes as required from the
  * stream.
@@ -3607,7 +3620,7 @@ psa_status_t psa_generate_random(uint8_t *output,
  * \brief Generate a key or key pair.
  *
  * The key is generated randomly.
- * Its location, policy, type and size are taken from \p attributes.
+ * Its location, usage policy, type and size are taken from \p attributes.
  *
  * The following type-specific considerations apply:
  * - For RSA keys (#PSA_KEY_TYPE_RSA_KEY_PAIR),
diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h
index b79c3b523..b6b61984b 100644
--- a/include/psa/crypto_types.h
+++ b/include/psa/crypto_types.h
@@ -206,11 +206,12 @@ typedef uint32_t psa_key_usage_t;
  * values:
  *
  * - lifetime: #PSA_KEY_LIFETIME_VOLATILE.
- * - key identifier: unspecified.
- * - type: \c 0.
- * - key size: \c 0.
- * - usage flags: \c 0.
- * - algorithm: \c 0.
+ * - key identifier: 0 (which is not a valid key identifier).
+ * - type: \c 0 (meaning that the type is unspecified).
+ * - key size: \c 0 (meaning that the size is unspecified).
+ * - usage flags: \c 0 (which allows no usage except exporting a public key).
+ * - algorithm: \c 0 (which allows no cryptographic usage, but allows
+ *   exporting).
  *
  * A typical sequence to create a key is as follows:
  * -# Create and initialize an attribute structure.