Add policy usage flag to copy a key

include/psa/crypto.h

@@ -733,6 +733,8 @@ psa_status_t psa_destroy_key(psa_key_handle_t handle);
  * - For public keys (key types for which #PSA_KEY_TYPE_IS_PUBLIC_KEY is
  *   true), the format is the same as for psa_export_public_key().
  *
+ * The policy on the key must have the usage flag #PSA_KEY_USAGE_EXPORT set.
+ *
  * \param handle            Handle to the key to export.
  * \param[out] data         Buffer where the key data is to be written.
  * \param data_size         Size of the \p data buffer in bytes.
@@ -743,6 +745,7 @@ psa_status_t psa_destroy_key(psa_key_handle_t handle);
  * \retval #PSA_ERROR_INVALID_HANDLE
  * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
+ *         The key does not have the #PSA_KEY_USAGE_EXPORT flag.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
  *         The size of the \p data buffer is too small. You can determine a
@@ -801,6 +804,9 @@ psa_status_t psa_export_key(psa_key_handle_t handle,
  *   big-endian byte string. The length of the byte string is the length of the
  *   base prime `p` in bytes.
  *
+ * Exporting a public key object or the public part of a key pair is
+ * always permitted, regardless of the key's usage flags.
+ *
  * \param handle            Handle to the key to export.
  * \param[out] data         Buffer where the key data is to be written.
  * \param data_size         Size of the \p data buffer in bytes.
@@ -844,6 +850,16 @@ 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.
+ * This flag is sufficient to permit the copy if the key has the lifetime
+ * #PSA_KEY_LIFETIME_VOLATILE or #PSA_KEY_LIFETIME_PERSISTENT.
+ * Some secure elements do not provide a way to copy a key without
+ * making it extractable from the secure element. If a key is located
+ * in such a secure element, then the key must have both usage flags
+ * #PSA_KEY_USAGE_COPY and #PSA_KEY_USAGE_EXPORT in order to make
+ * a copy of the key outside the secure element.
+ *
  * 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:
@@ -896,6 +912,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,22 @@
  */
 #define PSA_KEY_USAGE_EXPORT                    ((psa_key_usage_t)0x00000001)
 
+/** Whether the key may be copied.
+ *
+ * This flag allows the use of psa_copy_key() to make a copy of the key
+ * with the same policy or a more restrictive policy.
+ *
+ * For lifetimes for which the key is located in a secure element which
+ * enforce the non-exportability of keys, copying a key outside the secure
+ * element also requires the usage flag #PSA_KEY_USAGE_EXPORT.
+ * Copying the key inside the secure element is permitted with just
+ * #PSA_KEY_USAGE_COPY if the secure element supports it.
+ * 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 |
@@ -1595,7 +1596,8 @@ psa_status_t psa_copy_key_to_handle(psa_key_handle_t source_handle,
     psa_key_slot_t *target_slot = NULL;
     psa_key_policy_t new_policy;
     psa_status_t status;
-    status = psa_get_key_from_slot( source_handle, &source_slot, 0, 0 );
+    status = psa_get_key_from_slot( source_handle, &source_slot,
+                                    PSA_KEY_USAGE_COPY, 0 );
     if( status != PSA_SUCCESS )
         return( status );
     status = psa_get_empty_key_slot( target_handle, &target_slot );
@@ -1630,7 +1632,8 @@ psa_status_t psa_copy_key( psa_key_handle_t source_handle,
     psa_key_slot_t *target_slot = NULL;
     psa_key_attributes_t actual_attributes = *specified_attributes;
 
-    status = psa_get_key_from_slot( source_handle, &source_slot, 0, 0 );
+    status = psa_get_key_from_slot( source_handle, &source_slot,
+                                    PSA_KEY_USAGE_COPY, 0 );
     if( status != PSA_SUCCESS )
         goto exit;