From d6a8f5f1b584444b55d16a0c9068b46d52dbb419 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 14 May 2019 16:25:50 +0200 Subject: [PATCH] Improve description of PSA_KEY_USAGE_COPY Be more clear about when EXPORT is also required. --- include/psa/crypto.h | 13 +++++++------ include/psa/crypto_values.h | 12 +++++++----- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 51a2b0e52c..e87892b632 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -852,12 +852,13 @@ psa_status_t psa_export_public_key(psa_key_handle_t handle, * * 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. + * 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 diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index 766e396d4c..fa0d14d4fb 100644 --- a/include/psa/crypto_values.h +++ b/include/psa/crypto_values.h @@ -1461,13 +1461,15 @@ /** Whether the key may be copied. * - * This flag allows the use of psa_crypto_copy() to make a copy of the key + * 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 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 + * 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. */