New usage flag PSA_KEY_USAGE_COPY
Document the new flag and allow its use.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index ba2692c..51a2b0e 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -850,6 +850,15 @@
* 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 @@
* \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