Add a hash wildcard value for hash-and-sign algorithm

You can use PSA_ALG_ANY_HASH to build the algorithm value for a
hash-and-sign algorithm in a policy. Then the policy allows usage with
this hash-and-sign family with any hash.

Test that PSA_ALG_ANY_HASH-based policies allow a specific hash, but
not a different hash-and-sign family. Test that PSA_ALG_ANY_HASH is
not valid for operations, only in policies.

Author: gilles-peskine-arm

include/psa/crypto_values.h

@@ -641,6 +641,7 @@
     (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_SELECTION)
 
 #define PSA_ALG_HASH_MASK                       ((psa_algorithm_t)0x000000ff)
+
 #define PSA_ALG_MD2                             ((psa_algorithm_t)0x01000001)
 #define PSA_ALG_MD4                             ((psa_algorithm_t)0x01000002)
 #define PSA_ALG_MD5                             ((psa_algorithm_t)0x01000003)
@@ -667,6 +668,40 @@
 /** SHA3-512 */
 #define PSA_ALG_SHA3_512                        ((psa_algorithm_t)0x01000013)
 
+/** Allow any hash algorithm.
+ *
+ * This value may only be used to form the algorithm usage field of a policy
+ * for a signature algorithm that is parametrized by a hash. That is,
+ * suppose that `PSA_xxx_SIGN` is one of the following macros:
+ * - #PSA_ALG_RSA_PKCS1V15_SIGN, #PSA_ALG_RSA_PSS,
+ * - #PSA_ALG_DSA, #PSA_ALG_DETERMINISTIC_DSA,
+ * - #PSA_ALG_ECDSA, #PSA_ALG_DETERMINISTIC_ECDSA.
+ * Then you may create a key as follows:
+ * - Set the key usage field using #PSA_ALG_ANY_HASH, for example:
+ *   ```
+ *   psa_key_policy_set_usage(&policy,
+ *                            PSA_KEY_USAGE_SIGN, //or PSA_KEY_USAGE_VERIFY
+ *                            PSA_xxx_SIGN(PSA_ALG_ANY_HASH));
+ *   psa_set_key_policy(handle, &policy);
+ *   ```
+ * - Import or generate key material.
+ * - Call psa_asymmetric_sign() or psa_asymmetric_verify(), passing
+ *   an algorithm built from `PSA_xxx_SIGN` and a specific hash. Each
+ *   call to sign or verify a message may use a different hash.
+ *   ```
+ *   psa_asymmetric_sign(handle, PSA_xxx_SIGN(PSA_ALG_SHA_256), ...);
+ *   psa_asymmetric_sign(handle, PSA_xxx_SIGN(PSA_ALG_SHA_512), ...);
+ *   psa_asymmetric_sign(handle, PSA_xxx_SIGN(PSA_ALG_SHA3_256), ...);
+ *   ```
+ *
+ * This value may not be used to build other algorithms that are
+ * parametrized over a hash.
+ *
+ * This value may not be used to build an algorithm specification to
+ * perform an operation. It is only valid to build policies.
+ */
+#define PSA_ALG_ANY_HASH                        ((psa_algorithm_t)0x010000ff)
+
 #define PSA_ALG_MAC_SUBCATEGORY_MASK            ((psa_algorithm_t)0x00c00000)
 #define PSA_ALG_HMAC_BASE                       ((psa_algorithm_t)0x02800000)
 /** Macro to build an HMAC algorithm.
@@ -914,6 +949,8 @@
  *
  * \param hash_alg      A hash algorithm (\c PSA_ALG_XXX value such that
  *                      #PSA_ALG_IS_HASH(\p hash_alg) is true).
+ *                      This includes #PSA_ALG_ANY_HASH
+ *                      when specifying the algorithm in a usage policy.
  *
  * \return              The corresponding RSA PKCS#1 v1.5 signature algorithm.
  * \return              Unspecified if \p alg is not a supported
@@ -943,6 +980,8 @@
  *
  * \param hash_alg      A hash algorithm (\c PSA_ALG_XXX value such that
  *                      #PSA_ALG_IS_HASH(\p hash_alg) is true).
+ *                      This includes #PSA_ALG_ANY_HASH
+ *                      when specifying the algorithm in a usage policy.
  *
  * \return              The corresponding RSA PSS signature algorithm.
  * \return              Unspecified if \p alg is not a supported
@@ -961,6 +1000,8 @@
  *
  * \param hash_alg      A hash algorithm (\c PSA_ALG_XXX value such that
  *                      #PSA_ALG_IS_HASH(\p hash_alg) is true).
+ *                      This includes #PSA_ALG_ANY_HASH
+ *                      when specifying the algorithm in a usage policy.
  *
  * \return              The corresponding DSA signature algorithm.
  * \return              Unspecified if \p alg is not a supported
@@ -996,6 +1037,8 @@
  *
  * \param hash_alg      A hash algorithm (\c PSA_ALG_XXX value such that
  *                      #PSA_ALG_IS_HASH(\p hash_alg) is true).
+ *                      This includes #PSA_ALG_ANY_HASH
+ *                      when specifying the algorithm in a usage policy.
  *
  * \return              The corresponding ECDSA signature algorithm.
  * \return              Unspecified if \p alg is not a supported
@@ -1028,6 +1071,8 @@
  *
  * \param hash_alg      A hash algorithm (\c PSA_ALG_XXX value such that
  *                      #PSA_ALG_IS_HASH(\p hash_alg) is true).
+ *                      This includes #PSA_ALG_ANY_HASH
+ *                      when specifying the algorithm in a usage policy.
  *
  * \return              The corresponding deterministic ECDSA signature
  *                      algorithm.
@@ -1341,6 +1386,24 @@
 #define PSA_ALG_IS_ECDH(alg) \
     (PSA_ALG_KEY_AGREEMENT_GET_BASE(alg) == PSA_ALG_ECDH_BASE)
 
+/** Whether the specified algorithm encoding is a wildcard.
+ *
+ * Wildcard values may only be used to set the usage algorithm field in
+ * a policy, not to perform an operation.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \c alg is a wildcard algorithm encoding.
+ * \return 0 if \c alg is a non-wildcard algorithm encoding (suitable for
+ *         an operation).
+ * \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 :   \
+     (alg) == PSA_ALG_ANY_HASH)
+
 /**@}*/
 
 /** \defgroup key_lifetimes Key lifetimes

library/psa_crypto.c

@@ -713,6 +713,29 @@ static psa_status_t psa_get_empty_key_slot( psa_key_handle_t handle,
     return( status );
 }
 
+/** Test whether a policy permits an algorithm.
+ *
+ * The caller must test usage flags separately.
+ */
+static int psa_key_policy_permits( const psa_key_policy_t *policy,
+                                   psa_algorithm_t alg )
+{
+    /* Common case: the policy only allows alg. */
+    if( alg == policy->alg )
+        return( 1 );
+    /* If policy->alg is a hash-and-sign with a wildcard for the hash,
+     * and alg is the same hash-and-sign family with any hash,
+     * then alg is compliant with policy->alg. */
+    if( PSA_ALG_IS_HASH_AND_SIGN( alg ) &&
+        PSA_ALG_SIGN_GET_HASH( policy->alg ) == PSA_ALG_ANY_HASH )
+    {
+        return( ( policy->alg & ~PSA_ALG_HASH_MASK ) ==
+                (         alg & ~PSA_ALG_HASH_MASK ) );
+    }
+    /* If it isn't permitted, it's forbidden. */
+    return( 0 );
+}
+
 /** Retrieve a slot which must contain a key. The key must have allow all the
  * usage flags set in \p usage. If \p alg is nonzero, the key must allow
  * operations with this algorithm. */
@@ -740,7 +763,9 @@ static psa_status_t psa_get_key_from_slot( psa_key_handle_t handle,
         usage &= ~PSA_KEY_USAGE_EXPORT;
     if( ( slot->policy.usage & usage ) != usage )
         return( PSA_ERROR_NOT_PERMITTED );
-    if( alg != 0 && ( alg != slot->policy.alg ) )
+
+    /* Enforce that the usage policy permits the requested algortihm. */
+    if( alg != 0 && ! psa_key_policy_permits( &slot->policy, alg ) )
         return( PSA_ERROR_NOT_PERMITTED );
 
     *p_slot = slot;