Skip to content

Support wildcard hash in signature policies #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jan 28, 2019
Merged

Support wildcard hash in signature policies #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d35b489
New macro PSA_ALG_IS_HASH_AND_SIGN
gilles-peskine-arm Jan 14, 2019
30f77cd
Add a hash wildcard value for hash-and-sign algorithm
gilles-peskine-arm Jan 14, 2019
870f5dc
Add missing test dependency
gilles-peskine-arm Jan 23, 2019
eb2d4b9
Test that HASH_ANY is not meaningful for OAEP
gilles-peskine-arm Jan 24, 2019
763fb9a
Improve the description of PSA_ALG_ANY_HASH
gilles-peskine-arm Jan 28, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 85 additions & 2 deletions include/psa/crypto_values.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -667,6 +668,44 @@
/** SHA3-512 */
#define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x01000013)

/** In a hash-and-sign algorithm policy, allow any hash algorithm.
*
* This value may be used to form the algorithm usage field of a policy
* for a signature algorithm that is parametrized by a hash. The key
* may then be used to perform operations using the same signature
* algorithm parametrized with any supported hash.
*
* That is, suppose that `PSA_xxx_SIGNATURE` 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 and use 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_SIGNATURE(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_SIGNATURE` and a specific hash. Each
* call to sign or verify a message may use a different hash.
* ```
* psa_asymmetric_sign(handle, PSA_xxx_SIGNATURE(PSA_ALG_SHA_256), ...);
* psa_asymmetric_sign(handle, PSA_xxx_SIGNATURE(PSA_ALG_SHA_512), ...);
* psa_asymmetric_sign(handle, PSA_xxx_SIGNATURE(PSA_ALG_SHA3_256), ...);
* ```
*
* This value may not be used to build other algorithms that are
* parametrized over a hash. For any valid use of this macro to build
* an algorithm `\p alg`, #PSA_ALG_IS_HASH_AND_SIGN(\p alg) is true.
*
* 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.
Expand Down Expand Up @@ -914,6 +953,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
Expand Down Expand Up @@ -943,6 +984,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
Expand All @@ -961,6 +1004,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
Expand Down Expand Up @@ -996,6 +1041,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
Expand Down Expand Up @@ -1028,6 +1075,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.
Expand All @@ -1046,6 +1095,23 @@
#define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) \
(PSA_ALG_IS_ECDSA(alg) && !PSA_ALG_ECDSA_IS_DETERMINISTIC(alg))

/** Whether the specified algorithm is a hash-and-sign algorithm.
*
* Hash-and-sign algorithms are public-key signature algorithms structured
* in two parts: first the calculation of a hash in a way that does not
* depend on the key, then the calculation of a signature from the
* hash value and the key.
*
* \param alg An algorithm identifier (value of type #psa_algorithm_t).
*
* \return 1 if \p alg is a hash-and-sign algorithm, 0 otherwise.
* This macro may return either 0 or 1 if \p alg is not a supported
* algorithm identifier.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we decide if this is going to return a 0 or a 1 now, when alg is not a supported algorithm identifier, instead of leaving it up to implementations? How about always 0 in such cases? I see advantage for applications in making the behavior predictable, but does the advantage of flexibility for implementations outweigh this?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a macro which returns a constant expression so that it can be used to calculate static buffer sizes in applications that don't need runtime algorithm agility. So it must be implemented based on some simple bit patterns, not based on what some cryptoprocessor has to say about the algorithm. In particular, this macro cannot determine whether an algorithm is supported, so it can't return 0 for all unsupported algorithms. There is no clear semantic rule to choose between 0 and 1 for an unsupported algorithm, hence the specification leaves the result undefined in that case.

This consideration applies to all the PSA_ALG_IS_xxx macros.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shucks

*/
#define PSA_ALG_IS_HASH_AND_SIGN(alg) \
(PSA_ALG_IS_RSA_PSS(alg) || PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) || \
PSA_ALG_IS_DSA(alg) || PSA_ALG_IS_ECDSA(alg))

/** Get the hash used by a hash-and-sign signature algorithm.
*
* A hash-and-sign algorithm is a signature algorithm which is
Expand All @@ -1065,8 +1131,7 @@
* if it is not supported by the implementation.
*/
#define PSA_ALG_SIGN_GET_HASH(alg) \
(PSA_ALG_IS_RSA_PSS(alg) || PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) || \
PSA_ALG_IS_DSA(alg) || PSA_ALG_IS_ECDSA(alg) ? \
(PSA_ALG_IS_HASH_AND_SIGN(alg) ? \
((alg) & PSA_ALG_HASH_MASK) == 0 ? /*"raw" algorithm*/ 0 : \
((alg) & PSA_ALG_HASH_MASK) | PSA_ALG_CATEGORY_HASH : \
0)
Expand Down Expand Up @@ -1325,6 +1390,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
Expand Down
27 changes: 26 additions & 1 deletion library/psa_crypto.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. */
Expand Down Expand Up @@ -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;
Expand Down
Loading