Style and language updates after review
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
diff --git a/ChangeLog.d/psa-crypto-key-policies.txt b/ChangeLog.d/psa-crypto-key-policies.txt
deleted file mode 100644
index 6186d46..0000000
--- a/ChangeLog.d/psa-crypto-key-policies.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-Features
- * Added PSA_ALG_AEAD_WITH_MINIMUM_LENGTH_TAG and
- PSA_ALG_MAC_WITH_MINIMUM_LENGTH_TAG as usage algorithms for declaring key
- usage in PSA Crypto. These algorithm values describe that a key is allowed
- to be used with any algorithm that matches the specified base algorithm
- (e.g PSA_ALG_CCM for AEAD or PSA_ALG_CMAC for MAC) and has a tag length
- which is at least as long as the one encoded in the MINIMUM_TAG_LENGTH
- usage algorithm.
diff --git a/ChangeLog.d/psa-crypto-new-wildcard-policies.txt b/ChangeLog.d/psa-crypto-new-wildcard-policies.txt
new file mode 100644
index 0000000..f6aced9
--- /dev/null
+++ b/ChangeLog.d/psa-crypto-new-wildcard-policies.txt
@@ -0,0 +1,7 @@
+Features
+ * Added PSA_ALG_AEAD_WITH_MINIMUM_LENGTH_TAG and
+ PSA_ALG_MAC_WITH_MINIMUM_LENGTH_TAG as wildcard algorithms in PSA Crypto.
+ These algorithm values describe that a key is allowed to be used with any
+ algorithm that matches the specified base algorithm (e.g PSA_ALG_CCM for
+ AEAD or PSA_ALG_CMAC for MAC) and has a tag/MAC length which is at least as
+ long as the one encoded in the MINIMUM_TAG_LENGTH wildcard algorithm.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index a8fe59a..4aad094 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -264,12 +264,14 @@
* - 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.
- * - An algorithm value for which PSA_ALG_IS_WILDCARD() evaluates to true
- * allows any algorithm specified by that usage algorithm definition.
- * E.g. a usage algorithm built from PSA_ALG_MAC_WITH_MINIMUM_LENGTH_TAG()
- * allows using the key for any algorithm with the same base MAC algorithm as
- * long as the used algorithm isn't truncated to less than the minimum tag
- * length declared in the usage algorithm.
+ * - An algorithm built from #PSA_ALG_MAC_WITH_MINIMUM_LENGTH_TAG allows
+ * any MAC algorithm from the same base class (e.g. CMAC) which
+ * generates/verifies a MAC length greater than or equal to the length
+ * encoded in the wildcard algorithm.
+ * - An algorithm built from #PSA_ALG_AEAD_WITH_MINIMUM_LENGTH_TAG allows
+ * any AEAD algorithm from the same base class (e.g. CCM) which
+ * generates/verifies a tag length greater than or equal to the length
+ * encoded in the wildcard algorithm.
*
* This function overwrites any algorithm policy
* previously set in \p attributes.
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index 368581c..e804dc4 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -933,32 +933,36 @@
(((mac_alg) & PSA_ALG_MAC_TRUNCATION_MASK) >> PSA_MAC_TRUNCATION_OFFSET)
/* In the encoding of a MAC algorithm, the bit corresponding to
- * PSA_ALG_MAC_MINIMUM_LENGTH_FLAG encodes the fact that the algorithm is
- * a usage algorithm, which allows any algorithm corresponding to the same
- * base class and a tag length greater or equal than the one encoded in
- * PSA_ALG_MAC_TRUNCATION_MASK. */
+ * #PSA_ALG_MAC_MINIMUM_LENGTH_FLAG encodes the fact that the algorithm is
+ * a wildcard algorithm, which allows any algorithm corresponding to the same
+ * base class and having a (potentially truncated) MAC length greater or equal
+ * than the one encoded in #PSA_ALG_MAC_TRUNCATION_MASK. */
#define PSA_ALG_MAC_MINIMUM_LENGTH_FLAG ((psa_algorithm_t)0x00008000)
-/** Macro to build a MAC minimum-tag-length usage algorithm.
+/** Macro to build a MAC minimum-MAC-length wildcard algorithm.
*
- * A mininimum-tag-length MAC usage algorithm contains all MAC algorithms
- * sharing the same base algorithm, and where the tag length of the specific
- * algorithm is equal to or larger then the usage's minimum tag length.
+ * A mininimum-MAC-length MAC wildcard algorithm contains all MAC algorithms
+ * sharing the same base algorithm, and where the (potentially truncated) MAC
+ * length of the specific algorithm is equal to or larger then the wildcard
+ * algorithm's minimum MAC length.
*
* \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).
- * \param tag_length Desired minimum length of the authentication tag in
- * bytes.
+ * \param mac_length Desired minimum length of the message authentication
+ * code in bytes. This must be at most the full length of
+ * the MAC and must be at least an implementation-specified
+ * minimum. The implementation-specified minimum
+ * shall not be zero.
*
- * \return The corresponding MAC usage algorithm with the
+ * \return The corresponding MAC wildcard algorithm with the
* specified minimum length.
- * \return Unspecified if \p alg is not a supported
- * MAC algorithm or if \p tag_length is not valid
+ * \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.
*/
-#define PSA_ALG_MAC_WITH_MINIMUM_LENGTH_TAG(mac_alg, tag_length) \
- ( PSA_ALG_TRUNCATED_MAC(mac_alg, tag_length) | PSA_ALG_MAC_MINIMUM_LENGTH_FLAG )
+#define PSA_ALG_MAC_WITH_MINIMUM_LENGTH_TAG(mac_alg, mac_length) \
+ ( PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length) | PSA_ALG_MAC_MINIMUM_LENGTH_FLAG )
#define PSA_ALG_CIPHER_MAC_BASE ((psa_algorithm_t)0x03c00000)
/** The CBC-MAC construction over a block cipher
@@ -1178,27 +1182,28 @@
ref :
/* In the encoding of an AEAD algorithm, the bit corresponding to
- * PSA_ALG_AEAD_MINIMUM_LENGTH_FLAG encodes the fact that the algorithm is
- * a usage algorithm, which allows any algorithm corresponding to the same
- * base class and a tag length greater or equal than the one encoded in
- * PSA_ALG_AEAD_TAG_LENGTH_MASK. */
+ * #PSA_ALG_AEAD_MINIMUM_LENGTH_FLAG encodes the fact that the algorithm is
+ * a wildcard algorithm, which allows any algorithm corresponding to the same
+ * base class and having a tag length greater than or equal to the one encoded
+ * in #PSA_ALG_AEAD_TAG_LENGTH_MASK. */
#define PSA_ALG_AEAD_MINIMUM_LENGTH_FLAG ((psa_algorithm_t)0x00008000)
-/** Macro to build an AEAD minimum-tag-length usage algorithm.
+/** Macro to build an AEAD minimum-tag-length wildcard algorithm.
*
- * A mininimum-tag-length AEAD usage algorithm contains all AEAD algorithms
+ * A mininimum-tag-length AEAD wildcard algorithm contains all AEAD algorithms
* sharing the same base algorithm, and where the tag length of the specific
- * algorithm is equal to or larger then the usage's minimum tag length.
+ * algorithm is equal to or larger then the minimum tag length specified by the
+ * wildcard 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).
* \param tag_length Desired minimum length of the authentication tag in
* bytes.
*
- * \return The corresponding AEAD usage algorithm with the
+ * \return The corresponding AEAD wildcard algorithm with the
* specified minimum 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.
*/
@@ -1651,14 +1656,14 @@
* \return This macro may return either 0 or 1 if \c alg is not a supported
* algorithm identifier.
*/
-#define PSA_ALG_IS_WILDCARD(alg) \
- (PSA_ALG_IS_HASH_AND_SIGN(alg) ? \
- PSA_ALG_SIGN_GET_HASH(alg) == PSA_ALG_ANY_HASH : \
- (PSA_ALG_IS_MAC(alg) ? \
- (alg & PSA_ALG_MAC_MINIMUM_LENGTH_FLAG) != 0 : \
- (PSA_ALG_IS_AEAD(alg) ? \
- (alg & PSA_ALG_AEAD_MINIMUM_LENGTH_FLAG) != 0 : \
- (alg) == PSA_ALG_ANY_HASH)))
+#define PSA_ALG_IS_WILDCARD(alg) \
+ (PSA_ALG_IS_HASH_AND_SIGN(alg) ? \
+ PSA_ALG_SIGN_GET_HASH(alg) == PSA_ALG_ANY_HASH : \
+ PSA_ALG_IS_MAC(alg) ? \
+ (alg & PSA_ALG_MAC_MINIMUM_LENGTH_FLAG) != 0 : \
+ PSA_ALG_IS_AEAD(alg) ? \
+ (alg & PSA_ALG_AEAD_MINIMUM_LENGTH_FLAG) != 0 : \
+ (alg) == PSA_ALG_ANY_HASH)
/**@}*/
