From ee18b1f5a4332772a8b39e1f4992b4e962fb0cf8 Mon Sep 17 00:00:00 2001 From: Steven Cooreman Date: Mon, 8 Feb 2021 11:44:21 +0100 Subject: [PATCH] Style and language updates after review Signed-off-by: Steven Cooreman --- ChangeLog.d/psa-crypto-key-policies.txt | 8 -- .../psa-crypto-new-wildcard-policies.txt | 7 ++ include/psa/crypto.h | 14 ++-- include/psa/crypto_values.h | 73 ++++++++++--------- 4 files changed, 54 insertions(+), 48 deletions(-) delete mode 100644 ChangeLog.d/psa-crypto-key-policies.txt create mode 100644 ChangeLog.d/psa-crypto-new-wildcard-policies.txt diff --git a/ChangeLog.d/psa-crypto-key-policies.txt b/ChangeLog.d/psa-crypto-key-policies.txt deleted file mode 100644 index 6186d4642..000000000 --- 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 000000000..f6aced99a --- /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 a8fe59a12..4aad09452 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -264,12 +264,14 @@ static psa_key_usage_t psa_get_key_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. - * - 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 368581cd5..e804dc4be 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) /**@}*/