New usage flag PSA_KEY_USAGE_COPY

Document the new flag and allow its use.

include/psa/crypto.h

@@ -850,6 +850,15 @@ psa_status_t psa_export_public_key(psa_key_handle_t handle,
  * this function may be used to share a key with a different party,
  * subject to implementation-defined restrictions on key sharing.
  *
+ * The policy on the source key must have the usage flag
+ * #PSA_KEY_USAGE_COPY set.
+ * In addition, some lifetimes also require the source key to have the
+ * usage flag #PSA_KEY_USAGE_EXPORT, because otherwise the source key
+ * is locked inside a secure processing environment and cannot be
+ * extracted. For keys with the lifetime #PSA_KEY_LIFETIME_VOLATILE or
+ * #PSA_KEY_LIFETIME_PERSISTENT, the usage flag #PSA_KEY_USAGE_COPY
+ * is sufficient to permit the copy.
+ *
  * The resulting key may only be used in a way that conforms to
  * both the policy of the original key and the policy specified in
  * the \p attributes parameter:
@@ -902,6 +911,8 @@ psa_status_t psa_export_public_key(psa_key_handle_t handle,
  *         \p attributes specifies a key type, domain parameters or key size
  *         which does not match the attributes of the source key.
  * \retval #PSA_ERROR_NOT_PERMITTED
+ *         The source key does not have the #PSA_KEY_USAGE_COPY usage flag.
+ * \retval #PSA_ERROR_NOT_PERMITTED
  *         The source key is not exportable and its lifetime does not
  *         allow copying it to the target's lifetime.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY

include/psa/crypto_values.h

@@ -1459,6 +1459,20 @@
  */
 #define PSA_KEY_USAGE_EXPORT                    ((psa_key_usage_t)0x00000001)
 
+/** Whether the key may be copied.
+ *
+ * This flag allows the use of psa_crypto_copy() to make a copy of the key
+ * with the same policy or a more restrictive policy.
+ *
+ * For some lifetimes, copying a key also requires the usage flag
+ * #PSA_KEY_USAGE_EXPORT, because otherwise the source key
+ * is locked inside a secure processing environment and cannot be
+ * extracted. For keys with the lifetime #PSA_KEY_LIFETIME_VOLATILE or
+ * #PSA_KEY_LIFETIME_PERSISTENT, the usage flag #PSA_KEY_USAGE_COPY
+ * is sufficient to permit the copy.
+ */
+#define PSA_KEY_USAGE_COPY                      ((psa_key_usage_t)0x00000002)
+
 /** Whether the key may be used to encrypt a message.
  *
  * This flag allows the key to be used for a symmetric encryption operation,

library/psa_crypto.c

@@ -1344,6 +1344,7 @@ static psa_status_t psa_set_key_policy_internal(
     const psa_key_policy_t *policy )
 {
     if( ( policy->usage & ~( PSA_KEY_USAGE_EXPORT |
+                             PSA_KEY_USAGE_COPY |
                              PSA_KEY_USAGE_ENCRYPT |
                              PSA_KEY_USAGE_DECRYPT |
                              PSA_KEY_USAGE_SIGN |