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).
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 71bad3b..c21809c 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -226,7 +226,14 @@
/** 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 @@
*
* \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 @@
*
* \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 @@
* 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 @@
*
* 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 @@
* \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 b79c3b5..b6b6198 100644
--- a/include/psa/crypto_types.h
+++ b/include/psa/crypto_types.h
@@ -206,11 +206,12 @@
* 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.