From d6c503b5bacab9db755679636a21afec37bf10b1 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 21 Jul 2025 16:46:09 +0100 Subject: [PATCH 01/10] Check_key_usage initial Initial draft of the check_key_usage function Signed-off-by: Marcus Streets --- doc/crypto/api/keys/policy.rst | 54 ++++++++++++++++++++++++++++++++-- 1 file changed, 52 insertions(+), 2 deletions(-) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 46fa6122..d8731661 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -1,8 +1,8 @@ -.. SPDX-FileCopyrightText: Copyright 2018-2025 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. header:: psa/crypto - :seq: 170 + :seq: 17 .. _key-policy: @@ -97,6 +97,8 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. - `PSA_KEY_USAGE_DERIVE` - `PSA_KEY_USAGE_VERIFY_DERIVATION` +* The flag `PSA_KEY_USAGE_PAKE_PUBLIC` is used in the function `psa_check_key_usage` to query if a key is of the correct type to use in a PAKE operation. However, the key is supplied as a buffer, not a key object, and therefore the flag is not actually checked. + .. typedef:: uint32_t psa_key_usage_t .. summary:: @@ -267,6 +269,18 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. If this flag is present on all keys used in calls to `psa_key_derivation_input_key()` for a key-derivation operation, then it permits calling `psa_key_derivation_verify_bytes()` or `psa_key_derivation_verify_key()` at the end of the operation. +.. macro:: PSA_KEY_USAGE_PAKE_2 + :definition: ((psa_key_usage_t)0x00010000) + + .. summary:: + Used in the `psa_check_key_usage` function to determine if the key can be used in the second key role in PAKE operations. + + .. versionadded:: 1.4 + + This flag is only used with the `psa_check_key_usage` function. + + As the key in this role is provided in a buffer, this flag is never checked. + .. function:: psa_set_key_usage_flags .. summary:: @@ -302,3 +316,39 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. admonition:: Implementation note This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a ``static inline`` function or a function-like-macro. + +.. function:: psa_check_key_usage + + .. summary:: + Queries the capabilities of a PSA key object. + + .. versionadded:: 1.4 + + .. param:: psa_key_id_t key + a PSA key identifier. + + .. param:: psa_algorithm_t alg + a specific algorithm. + + .. param:: psa_key_usage_t usage + a single PSA_KEY_USAGE_xxx flag. + + .. return:: psa_status_t + + If the supplied key is a key pair, the function checks the appropriate half of the key pair. For example, if the usage flag was `PSA_KEY_USAGE_SIGN_MESSAGE`, it would check the private key. But if it were `PSA_KEY_USAGE_VERIFY_MESSAGE` it would check the public key. + + The algorithm must be fully defined. if the algorithm is a wildcard, the function returns `PSA_ERROR_INVALID_ARGUMENT`. + + The usage flag must correspond to an operation that uses an algorithm. If you select a flag that is not algorithm dependent, like COPY tor EXPORT, the function returns PSA_ERROR_INVALID_ARGUMENT. + + If this implementation does not offer this algorithm, the function returns `PSA_ERROR_NOT_SUPPORTED` without checking the key object. + + If the implementation offers the algorithm, and the key does not exist, the function returns `PSA_ERROR_INVALID_HANDLE`. + + If the implementation offers the algorithm, and the key does exists, but is not of the correct type, the function returns `PSA_ERROR_INVALID_ARGUMENT`. + + If the implementation offers the algorithm, but the key does not have the correct permission, the function returns `PSA_ERROR_NOT_PERMITTED`. + + If the implementation offers the algorimth, and the key is the correct type and has the correct permission, the function returns `PSA_SUCCESS`. + + When checking a public key with a usage flag for an operation where the public key is provided as a buffer, for example, the public key in a derive operation, or the counterparty key in a key establishment, then the function indicates that the operation supports this type of key in this role. It ignores permissions, as all public keys can be exported. \ No newline at end of file From 9926a4e4333b78aea336a174fb88ddc6651737e5 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 21 Jul 2025 21:48:50 +0100 Subject: [PATCH 02/10] check key usage Correcting build errors, needed double ticks not single on statuses. Signed-off-by: Marcus Streets --- doc/crypto/api/keys/policy.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index d8731661..bc441596 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -269,7 +269,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. If this flag is present on all keys used in calls to `psa_key_derivation_input_key()` for a key-derivation operation, then it permits calling `psa_key_derivation_verify_bytes()` or `psa_key_derivation_verify_key()` at the end of the operation. -.. macro:: PSA_KEY_USAGE_PAKE_2 +.. macro:: PSA_KEY_USAGE_PAKE_PUBLIC :definition: ((psa_key_usage_t)0x00010000) .. summary:: @@ -337,18 +337,18 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. If the supplied key is a key pair, the function checks the appropriate half of the key pair. For example, if the usage flag was `PSA_KEY_USAGE_SIGN_MESSAGE`, it would check the private key. But if it were `PSA_KEY_USAGE_VERIFY_MESSAGE` it would check the public key. - The algorithm must be fully defined. if the algorithm is a wildcard, the function returns `PSA_ERROR_INVALID_ARGUMENT`. + The algorithm must be fully defined. if the algorithm is a wildcard, the function returns ``PSA_ERROR_INVALID_ARGUMENT``. - The usage flag must correspond to an operation that uses an algorithm. If you select a flag that is not algorithm dependent, like COPY tor EXPORT, the function returns PSA_ERROR_INVALID_ARGUMENT. + The usage flag must correspond to an operation that uses an algorithm. If you select a flag that is not algorithm dependent, like COPY tor EXPORT, the function returns ``PSA_ERROR_INVALID_ARGUMENT``. - If this implementation does not offer this algorithm, the function returns `PSA_ERROR_NOT_SUPPORTED` without checking the key object. + If this implementation does not offer this algorithm, the function returns ``PSA_ERROR_NOT_SUPPORTED`` without checking the key object. - If the implementation offers the algorithm, and the key does not exist, the function returns `PSA_ERROR_INVALID_HANDLE`. + If the implementation offers the algorithm, and the key does not exist, the function returns ``PSA_ERROR_INVALID_HANDLE``. - If the implementation offers the algorithm, and the key does exists, but is not of the correct type, the function returns `PSA_ERROR_INVALID_ARGUMENT`. + If the implementation offers the algorithm, and the key does exists, but is not of the correct type, the function returns ``PSA_ERROR_INVALID_ARGUMENT``. - If the implementation offers the algorithm, but the key does not have the correct permission, the function returns `PSA_ERROR_NOT_PERMITTED`. + If the implementation offers the algorithm, but the key does not have the correct permission, the function returns ``PSA_ERROR_NOT_PERMITTED``. - If the implementation offers the algorimth, and the key is the correct type and has the correct permission, the function returns `PSA_SUCCESS`. + If the implementation offers the algorimth, and the key is the correct type and has the correct permission, the function returns ``PSA_SUCCESS``. When checking a public key with a usage flag for an operation where the public key is provided as a buffer, for example, the public key in a derive operation, or the counterparty key in a key establishment, then the function indicates that the operation supports this type of key in this role. It ignores permissions, as all public keys can be exported. \ No newline at end of file From 1f3403bf9a3ff3025b21d6c3522c3ca496ff0193 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 21 Jul 2025 21:53:21 +0100 Subject: [PATCH 03/10] it is 2025 Fixing copyright and sequence numbering Signed-off-by: Marcus Streets --- doc/crypto/api/keys/policy.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index bc441596..d05d78e1 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -1,8 +1,8 @@ -.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2018-2025 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. header:: psa/crypto - :seq: 17 + :seq: 170 .. _key-policy: From a3ab679c624dd5dc4fe33f5b366962794ab9555f Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Thu, 31 Jul 2025 15:10:03 +0100 Subject: [PATCH 04/10] Response to comments I did look at putting in a table, but I am not convinced we need it, as in most cases it is obvious. But I am not entirely sure. Signed-off-by: Marcus Streets --- doc/crypto/api/keys/policy.rst | 44 +++++++++++++++++++++------------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index d05d78e1..dab189ee 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -97,7 +97,11 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. - `PSA_KEY_USAGE_DERIVE` - `PSA_KEY_USAGE_VERIFY_DERIVATION` -* The flag `PSA_KEY_USAGE_PAKE_PUBLIC` is used in the function `psa_check_key_usage` to query if a key is of the correct type to use in a PAKE operation. However, the key is supplied as a buffer, not a key object, and therefore the flag is not actually checked. +* The flag `PSA_KEY_USAGE_DERIVE_PUBLIC` it is not checked when calling any of the APIs to carry out a cryptographic operation. However, it is used in the function `psa_check_key_usage` to query if a key is of the correct type for the public role in the specified algorithm, which is may be provided in a buffer and not as a key object. For example PSA_KEY_USAGE_DERIVE_PUBLIC with: + + - ``PSA_ALG_ECDH`` checks that the key can be used as the public share in the ECDH key agreement. There are no checks on permssions as this is provided in a buffer. + - ``PSA_ALG_SPAKE2P_HMAC`` will check that the key can be used in the Verifier role in the SPAKE2+ algorithm. The key must have the `PSA_KEY_USAGE_DERIVE` permission. + - ``PSA_ALG_HKDF`` is invalid, as there is no such role in single-key derivation algorithms. .. typedef:: uint32_t psa_key_usage_t @@ -269,7 +273,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. If this flag is present on all keys used in calls to `psa_key_derivation_input_key()` for a key-derivation operation, then it permits calling `psa_key_derivation_verify_bytes()` or `psa_key_derivation_verify_key()` at the end of the operation. -.. macro:: PSA_KEY_USAGE_PAKE_PUBLIC +.. macro:: PSA_KEY_USAGE_DERIVE_PUBLIC :definition: ((psa_key_usage_t)0x00010000) .. summary:: @@ -320,7 +324,14 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. function:: psa_check_key_usage .. summary:: - Queries the capabilities of a PSA key object. + Queries the capabilities of a key. + + Returns success only if this key object exists and is the correct type for the requested operation and this implementation supports the algorithm and the key has the required permission. + + That is, if the application were to call the identified operation with this key and with all other parameters correct, the operation should succeed. + + This function only checks permissions, it does not attempt to perform the operation, so does not use any resources in the cryptographic engine. + .. versionadded:: 1.4 @@ -333,22 +344,23 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. param:: psa_key_usage_t usage a single PSA_KEY_USAGE_xxx flag. - .. return:: psa_status_t - - If the supplied key is a key pair, the function checks the appropriate half of the key pair. For example, if the usage flag was `PSA_KEY_USAGE_SIGN_MESSAGE`, it would check the private key. But if it were `PSA_KEY_USAGE_VERIFY_MESSAGE` it would check the public key. - - The algorithm must be fully defined. if the algorithm is a wildcard, the function returns ``PSA_ERROR_INVALID_ARGUMENT``. - - The usage flag must correspond to an operation that uses an algorithm. If you select a flag that is not algorithm dependent, like COPY tor EXPORT, the function returns ``PSA_ERROR_INVALID_ARGUMENT``. + .. return:: psa_status_t - If this implementation does not offer this algorithm, the function returns ``PSA_ERROR_NOT_SUPPORTED`` without checking the key object. + .. retval:: PSA_SUCCESS + ``key`` can be used for the requested operation on this implementation. That is the ``alg`` is supported, ``key`` is of the correct type and has the requied permissions for ``useage``. - If the implementation offers the algorithm, and the key does not exist, the function returns ``PSA_ERROR_INVALID_HANDLE``. + .. retval:: PSA_ERROR_INVALID_ARGUMENT + Either ``algorithm`` is a wildcard, + or ``usage`` is an operation that is not algorithm dependent, like COPY or EXPORT. + or ``key`` is not of the correct type for the operation. - If the implementation offers the algorithm, and the key does exists, but is not of the correct type, the function returns ``PSA_ERROR_INVALID_ARGUMENT``. + .. retval:: PSA_ERROR_NOT_SUPPORTED + ``alg`` and ``useage`` together refer to an operation on an algorithm that is not supported by this implementation. - If the implementation offers the algorithm, but the key does not have the correct permission, the function returns ``PSA_ERROR_NOT_PERMITTED``. + .. retval: PSA_ERROR_INVALID_HANDLE: + ``key`` does not exist - If the implementation offers the algorimth, and the key is the correct type and has the correct permission, the function returns ``PSA_SUCCESS``. + .. retval: PSA_ERROR_NOT_PERMITTED + ``key`` does not have the correct permission for the ``useage`` - When checking a public key with a usage flag for an operation where the public key is provided as a buffer, for example, the public key in a derive operation, or the counterparty key in a key establishment, then the function indicates that the operation supports this type of key in this role. It ignores permissions, as all public keys can be exported. \ No newline at end of file + When checking a public key with a usage flag for an operation where the public key is provided as a buffer, for example, the public key in a derive operation, or the counterparty key in a key establishment, then the function indicates that the operation supports this type of key in this role. It ignores permissions, as all public keys can be exported. \ No newline at end of file From 836b05a4beebb9fcd3e557d6ecd15ad01643df4b Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Tue, 9 Sep 2025 11:51:27 +0100 Subject: [PATCH 05/10] Add files via upload Responses to Andrew's comments that were uncommitted. Signed-off-by: Marcus Streets --- doc/crypto/api/keys/policy.rst | 55 +++++++++++++++++----------------- 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index dab189ee..e5d64657 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -97,11 +97,11 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. - `PSA_KEY_USAGE_DERIVE` - `PSA_KEY_USAGE_VERIFY_DERIVATION` -* The flag `PSA_KEY_USAGE_DERIVE_PUBLIC` it is not checked when calling any of the APIs to carry out a cryptographic operation. However, it is used in the function `psa_check_key_usage` to query if a key is of the correct type for the public role in the specified algorithm, which is may be provided in a buffer and not as a key object. For example PSA_KEY_USAGE_DERIVE_PUBLIC with: +* The flag `PSA_KEY_USAGE_DERIVE_PUBLIC` it is not checked when calling any of the APIs to carry out a cryptographic operation. However, it is used in the function `psa_check_key_usage()` to query if a key can be used for the public role in the specified algorithm. Note, in some usages the key in the public role is provided in a buffer and not as a key object. For example `PSA_KEY_USAGE_DERIVE_PUBLIC` with: - - ``PSA_ALG_ECDH`` checks that the key can be used as the public share in the ECDH key agreement. There are no checks on permssions as this is provided in a buffer. - - ``PSA_ALG_SPAKE2P_HMAC`` will check that the key can be used in the Verifier role in the SPAKE2+ algorithm. The key must have the `PSA_KEY_USAGE_DERIVE` permission. - - ``PSA_ALG_HKDF`` is invalid, as there is no such role in single-key derivation algorithms. + - `PSA_ALG_ECDH` checks that the key can be used as the public share in the ECDH key agreement. There are no checks on permissions as this is provided in a buffer. + - `PSA_ALG_SPAKE2P_HMAC` will check that the key can be used in the Verifier role in the SPAKE2+ algorithm. The key must have the `PSA_KEY_USAGE_DERIVE` permission. + - `PSA_ALG_HKDF` is invalid, as there is no such role in single-key derivation algorithms. .. typedef:: uint32_t psa_key_usage_t @@ -277,13 +277,13 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. :definition: ((psa_key_usage_t)0x00010000) .. summary:: - Used in the `psa_check_key_usage` function to determine if the key can be used in the second key role in PAKE operations. + Used in the `psa_check_key_usage()` function to determine if the key can be used in the second key role in PAKE operations. .. versionadded:: 1.4 This flag is only used with the `psa_check_key_usage` function. - As the key in this role is provided in a buffer, this flag is never checked. + This flag is never checked when performing cryptographic operations. .. function:: psa_set_key_usage_flags @@ -324,43 +324,44 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. function:: psa_check_key_usage .. summary:: - Queries the capabilities of a key. - - Returns success only if this key object exists and is the correct type for the requested operation and this implementation supports the algorithm and the key has the required permission. - - That is, if the application were to call the identified operation with this key and with all other parameters correct, the operation should succeed. - - This function only checks permissions, it does not attempt to perform the operation, so does not use any resources in the cryptographic engine. - + Query the capability of a key. .. versionadded:: 1.4 .. param:: psa_key_id_t key - a PSA key identifier. + Identifier of the key to check. .. param:: psa_algorithm_t alg - a specific algorithm. + An algorithm identifier: a value of type `psa_algorithm_t`. .. param:: psa_key_usage_t usage - a single PSA_KEY_USAGE_xxx flag. + A single PSA_KEY_USAGE_xxx flag. .. return:: psa_status_t .. retval:: PSA_SUCCESS - ``key`` can be used for the requested operation on this implementation. That is the ``alg`` is supported, ``key`` is of the correct type and has the requied permissions for ``useage``. + ``key`` can be used for the requested operation on this implementation. .. retval:: PSA_ERROR_INVALID_ARGUMENT - Either ``algorithm`` is a wildcard, - or ``usage`` is an operation that is not algorithm dependent, like COPY or EXPORT. - or ``key`` is not of the correct type for the operation. - - .. retval:: PSA_ERROR_NOT_SUPPORTED - ``alg`` and ``useage`` together refer to an operation on an algorithm that is not supported by this implementation. + * ``alg`` is not a specific cryptographic algorithm. It cannot be a wildcard algorithm. + * ``usage`` is not a valid role for algorithm ``alg``. + * ``key`` is not compatible with ``alg`` and ``usage``. .. retval: PSA_ERROR_INVALID_HANDLE: - ``key`` does not exist + ``key`` is not a valid key identifier. .. retval: PSA_ERROR_NOT_PERMITTED - ``key`` does not have the correct permission for the ``useage`` + ``key`` does not permit the requested usage. + + .. retval:: PSA_ERROR_NOT_SUPPORTED + The implementation does not support using ``key`` with the cryptographic operation associated with ``alg`` and ``usage``. + + Returns success only if this key object exists, is the correct type for the the operation associated with the algorithm and usage, with the required permission, and this implementation supports this key type for this operation. + + This function does not attempt to perform the operation, so does not use any resources in the cryptographic engine. + + The ``alg`` must be a fully specified algorithm, and not a wildcard. + + The ``useage`` must be a valid role within a cryptographic algorithm. It must not be a non-cryptographiic operation such as `PSA_KEY_USAGE_COPY` or `PSA_KEY_USAGE_EXPORT`. - When checking a public key with a usage flag for an operation where the public key is provided as a buffer, for example, the public key in a derive operation, or the counterparty key in a key establishment, then the function indicates that the operation supports this type of key in this role. It ignores permissions, as all public keys can be exported. \ No newline at end of file + When checking a public key with a usage flag for an operation where the public key is provided as a buffer, the function returns ``PSA_SUCCESS`` if the operation supports this type of key in this role. In these cases, the function does not check THE permissions, as all public keys can be exported. This applies to, for example, using the key as the public key in a key agreement. \ No newline at end of file From c4813f5712d30cfe6dc47da481c64c0491b71010 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 10 Sep 2025 22:38:02 +0100 Subject: [PATCH 06/10] Copy-editor update * Fix formatting issues * Ensure consistency with the spec style * Wording adjustments to improve clarity * Add history entry and update reference header --- doc/crypto/api.db/psa/crypto.h | 4 +++ doc/crypto/api/keys/policy.rst | 56 ++++++++++++++++++--------------- doc/crypto/appendix/history.rst | 1 + 3 files changed, 36 insertions(+), 25 deletions(-) diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index 74bb334a..052330fd 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/doc/crypto/api.db/psa/crypto.h @@ -331,6 +331,7 @@ typedef struct psa_custom_key_parameters_t { #define PSA_KEY_USAGE_COPY ((psa_key_usage_t)0x00000002) #define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200) #define PSA_KEY_USAGE_DERIVE ((psa_key_usage_t)0x00004000) +#define PSA_KEY_USAGE_DERIVE_PUBLIC ((psa_key_usage_t)0x00010000) #define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t)0x00000100) #define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t)0x00000001) #define PSA_KEY_USAGE_SIGN_HASH ((psa_key_usage_t)0x00001000) @@ -464,6 +465,9 @@ psa_status_t psa_attach_key(const psa_key_attributes_t * attributes, const uint8_t * label, size_t label_length, psa_key_id_t * key); +psa_status_t psa_check_key_usage(psa_key_id_t key, + psa_algorithm_t alg, + psa_key_usage_t usage); psa_status_t psa_cipher_abort(psa_cipher_operation_t * operation); psa_status_t psa_cipher_decrypt(psa_key_id_t key, psa_algorithm_t alg, diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index e5d64657..06c520b3 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -97,10 +97,16 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. - `PSA_KEY_USAGE_DERIVE` - `PSA_KEY_USAGE_VERIFY_DERIVATION` -* The flag `PSA_KEY_USAGE_DERIVE_PUBLIC` it is not checked when calling any of the APIs to carry out a cryptographic operation. However, it is used in the function `psa_check_key_usage()` to query if a key can be used for the public role in the specified algorithm. Note, in some usages the key in the public role is provided in a buffer and not as a key object. For example `PSA_KEY_USAGE_DERIVE_PUBLIC` with: +* The flag `PSA_KEY_USAGE_DERIVE_PUBLIC` it is not checked when calling any of the APIs to carry out a cryptographic operation. + However, it is used in the function `psa_check_key_usage()` to query if a key can be used for the public role in the specified algorithm. + Note, in some usages the key in the public role is provided in a buffer and not as a key object. - - `PSA_ALG_ECDH` checks that the key can be used as the public share in the ECDH key agreement. There are no checks on permissions as this is provided in a buffer. - - `PSA_ALG_SPAKE2P_HMAC` will check that the key can be used in the Verifier role in the SPAKE2+ algorithm. The key must have the `PSA_KEY_USAGE_DERIVE` permission. + For example, calling `psa_check_key_usage()` with `PSA_KEY_USAGE_DERIVE_PUBLIC` and with: + + - `PSA_ALG_ECDH` checks that the key can be used as the public share in the ECDH key agreement. + There are no checks on permissions as this is provided in a buffer. + - `PSA_ALG_SPAKE2P_HMAC` will check that the key can be used in the Verifier role in the SPAKE2+ algorithm. + The key must have the `PSA_KEY_USAGE_DERIVE` permission. - `PSA_ALG_HKDF` is invalid, as there is no such role in single-key derivation algorithms. .. typedef:: uint32_t psa_key_usage_t @@ -277,13 +283,13 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. :definition: ((psa_key_usage_t)0x00010000) .. summary:: - Used in the `psa_check_key_usage()` function to determine if the key can be used in the second key role in PAKE operations. + Used in the `psa_check_key_usage()` function to determine if the key can be used in the public key role in key-agreement or PAKE operations. .. versionadded:: 1.4 This flag is only used with the `psa_check_key_usage` function. - This flag is never checked when performing cryptographic operations. + This flag is never checked when performing cryptographic operations. .. function:: psa_set_key_usage_flags @@ -324,44 +330,44 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. function:: psa_check_key_usage .. summary:: - Query the capability of a key. + Query the capability of a key. .. versionadded:: 1.4 .. param:: psa_key_id_t key Identifier of the key to check. - .. param:: psa_algorithm_t alg An algorithm identifier: a value of type `psa_algorithm_t`. - .. param:: psa_key_usage_t usage - A single PSA_KEY_USAGE_xxx flag. + A single ``PSA_KEY_USAGE_xxx`` flag. - .. return:: psa_status_t + .. return:: psa_status_t .. retval:: PSA_SUCCESS - ``key`` can be used for the requested operation on this implementation. - + ``key`` can be used for the requested operation on this implementation. .. retval:: PSA_ERROR_INVALID_ARGUMENT - * ``alg`` is not a specific cryptographic algorithm. It cannot be a wildcard algorithm. - * ``usage`` is not a valid role for algorithm ``alg``. - * ``key`` is not compatible with ``alg`` and ``usage``. + The following conditions can result in this error: - .. retval: PSA_ERROR_INVALID_HANDLE: + * ``alg`` is not a specific cryptographic algorithm. + It cannot be a wildcard algorithm. + * ``usage`` is not a valid role for algorithm ``alg``. + * ``key`` is not compatible with ``alg`` and ``usage``. + .. retval: PSA_ERROR_INVALID_HANDLE: ``key`` is not a valid key identifier. - .. retval: PSA_ERROR_NOT_PERMITTED ``key`` does not permit the requested usage. - .. retval:: PSA_ERROR_NOT_SUPPORTED The implementation does not support using ``key`` with the cryptographic operation associated with ``alg`` and ``usage``. - Returns success only if this key object exists, is the correct type for the the operation associated with the algorithm and usage, with the required permission, and this implementation supports this key type for this operation. - - This function does not attempt to perform the operation, so does not use any resources in the cryptographic engine. + Returns success only if this key object exists, is the correct type for the the operation associated with the algorithm and usage, with the required permission, and this implementation supports this key type for this operation. + + This function does not attempt to perform the operation, so does not use any resources in the cryptographic engine. + + The ``alg`` must be a fully specified algorithm, and not a wildcard. - The ``alg`` must be a fully specified algorithm, and not a wildcard. - - The ``useage`` must be a valid role within a cryptographic algorithm. It must not be a non-cryptographiic operation such as `PSA_KEY_USAGE_COPY` or `PSA_KEY_USAGE_EXPORT`. + The ``usage`` must be a valid role within a cryptographic algorithm. + It must not be a non-cryptographic key usage flag such as `PSA_KEY_USAGE_COPY` or `PSA_KEY_USAGE_EXPORT`. - When checking a public key with a usage flag for an operation where the public key is provided as a buffer, the function returns ``PSA_SUCCESS`` if the operation supports this type of key in this role. In these cases, the function does not check THE permissions, as all public keys can be exported. This applies to, for example, using the key as the public key in a key agreement. \ No newline at end of file + When checking a public key for use with an operation where the public key is provided as a buffer, the function returns ``PSA_SUCCESS`` if the operation supports this type of key in this role. + In these cases, the function does not check the key's usage flags, as all public keys can be exported. + This applies to, for example, using the key as the public key in a key agreement. diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index 7c6ded68..338439c1 100644 --- a/doc/crypto/appendix/history.rst +++ b/doc/crypto/appendix/history.rst @@ -18,6 +18,7 @@ Changes to the API ~~~~~~~~~~~~~~~~~~ * Added `psa_attach_key()` to register existing key material as a volatile key within the implementation. +* Added `psa_check_key_usage()` to query a key's capabilities. Clarifications and fixes ~~~~~~~~~~~~~~~~~~~~~~~~ From 171f3740050b76b7f3a3347527b22cbbdfe621a9 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Fri, 12 Sep 2025 11:53:15 +0100 Subject: [PATCH 07/10] Clarifications and fixes to text following review --- doc/crypto/api/keys/policy.rst | 53 +++++++++++++++++++--------------- 1 file changed, 29 insertions(+), 24 deletions(-) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 06c520b3..6d321ea4 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -81,7 +81,7 @@ When a key is used in a cryptographic operation, the application must supply the Key usage flags --------------- -The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. Four kinds of usage flag can be specified: +The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. Five kinds of usage flag can be specified: * The extractable flag `PSA_KEY_USAGE_EXPORT` determines whether the key material can be extracted from the cryptoprocessor, or copied outside of its current security boundary. * The copyable flag `PSA_KEY_USAGE_COPY` determines whether the key material can be copied into a new key, which can have a different lifetime or a more restrictive policy. @@ -97,17 +97,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. - `PSA_KEY_USAGE_DERIVE` - `PSA_KEY_USAGE_VERIFY_DERIVATION` -* The flag `PSA_KEY_USAGE_DERIVE_PUBLIC` it is not checked when calling any of the APIs to carry out a cryptographic operation. - However, it is used in the function `psa_check_key_usage()` to query if a key can be used for the public role in the specified algorithm. - Note, in some usages the key in the public role is provided in a buffer and not as a key object. - - For example, calling `psa_check_key_usage()` with `PSA_KEY_USAGE_DERIVE_PUBLIC` and with: - - - `PSA_ALG_ECDH` checks that the key can be used as the public share in the ECDH key agreement. - There are no checks on permissions as this is provided in a buffer. - - `PSA_ALG_SPAKE2P_HMAC` will check that the key can be used in the Verifier role in the SPAKE2+ algorithm. - The key must have the `PSA_KEY_USAGE_DERIVE` permission. - - `PSA_ALG_HKDF` is invalid, as there is no such role in single-key derivation algorithms. +* The flag `PSA_KEY_USAGE_DERIVE_PUBLIC` is used in the function `psa_check_key_usage()` to query if a key can be used for the public role in the specified algorithm. .. typedef:: uint32_t psa_key_usage_t @@ -280,17 +270,25 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. If this flag is present on all keys used in calls to `psa_key_derivation_input_key()` for a key-derivation operation, then it permits calling `psa_key_derivation_verify_bytes()` or `psa_key_derivation_verify_key()` at the end of the operation. .. macro:: PSA_KEY_USAGE_DERIVE_PUBLIC - :definition: ((psa_key_usage_t)0x00010000) + :definition: ((psa_key_usage_t)0x00000080) .. summary:: - Used in the `psa_check_key_usage()` function to determine if the key can be used in the public key role in key-agreement or PAKE operations. + Used in the `psa_check_key_usage()` function to determine if the key can be used in the public key role in a key-agreement or a PAKE operation. .. versionadded:: 1.4 - This flag is only used with the `psa_check_key_usage` function. - + This flag is only used with the `psa_check_key_usage()` function. This flag is never checked when performing cryptographic operations. + For example, calling `psa_check_key_usage()` with `PSA_KEY_USAGE_DERIVE_PUBLIC` and with: + + * `PSA_ALG_ECDH` checks that the key can be used as the public share in the ECDH key agreement. + There are no checks on permissions as the key share is provided in a buffer. + * `PSA_ALG_SPAKE2P_HMAC` will check that the key can be used in the Verifier role in the SPAKE2+ algorithm. + The key must have the `PSA_KEY_USAGE_DERIVE` permission. + * `PSA_ALG_HKDF` is invalid, as there is no such role in single-key derivation algorithms. + + .. function:: psa_set_key_usage_flags .. summary:: @@ -355,19 +353,26 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. retval: PSA_ERROR_INVALID_HANDLE: ``key`` is not a valid key identifier. .. retval: PSA_ERROR_NOT_PERMITTED - ``key`` does not permit the requested usage. + ``key`` does not permit the requested usage or algorithm. .. retval:: PSA_ERROR_NOT_SUPPORTED The implementation does not support using ``key`` with the cryptographic operation associated with ``alg`` and ``usage``. + .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY + .. retval:: PSA_ERROR_COMMUNICATION_FAILURE + .. retval:: PSA_ERROR_CORRUPTION_DETECTED + .. retval:: PSA_ERROR_STORAGE_FAILURE + .. retval:: PSA_ERROR_DATA_CORRUPT + .. retval:: PSA_ERROR_DATA_INVALID + .. retval:: PSA_ERROR_BAD_STATE + The library requires initializing by a call to `psa_crypto_init()`. - Returns success only if this key object exists, is the correct type for the the operation associated with the algorithm and usage, with the required permission, and this implementation supports this key type for this operation. + Returns success only if this key object exists, is compatible with the operation associated with the algorithm and usage, has the required permission, and this implementation supports this key type for this operation. This function does not attempt to perform the operation, so does not use any resources in the cryptographic engine. - The ``alg`` must be a fully specified algorithm, and not a wildcard. + ``alg`` must be a fully specified algorithm, and not a wildcard. - The ``usage`` must be a valid role within a cryptographic algorithm. - It must not be a non-cryptographic key usage flag such as `PSA_KEY_USAGE_COPY` or `PSA_KEY_USAGE_EXPORT`. + ``usage`` must be a valid role within a cryptographic algorithm. + It must not be a non-cryptographic key usage flag, such as `PSA_KEY_USAGE_COPY` or `PSA_KEY_USAGE_EXPORT`. - When checking a public key for use with an operation where the public key is provided as a buffer, the function returns ``PSA_SUCCESS`` if the operation supports this type of key in this role. - In these cases, the function does not check the key's usage flags, as all public keys can be exported. - This applies to, for example, using the key as the public key in a key agreement. + Note that for the key pair or public key of a valid type in a key agreement function, this function returns :code:`PSA_SUCCESS` for the usage `PSA_KEY_USAGE_DERIVE_PUBLIC`, regardless of the key's policy. + This is because the corresponding API functions take a key buffer as input, not a key object, and the key data can extracted by calling `psa_export_public_key()`, which does not require any usage flag. From eb682141440b0311ab1b37d6c0abda88ecb6d13f Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Fri, 12 Sep 2025 22:41:15 +0100 Subject: [PATCH 08/10] Update header file --- doc/crypto/api.db/psa/crypto.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index 052330fd..43cc5d06 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/doc/crypto/api.db/psa/crypto.h @@ -331,7 +331,7 @@ typedef struct psa_custom_key_parameters_t { #define PSA_KEY_USAGE_COPY ((psa_key_usage_t)0x00000002) #define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200) #define PSA_KEY_USAGE_DERIVE ((psa_key_usage_t)0x00004000) -#define PSA_KEY_USAGE_DERIVE_PUBLIC ((psa_key_usage_t)0x00010000) +#define PSA_KEY_USAGE_DERIVE_PUBLIC ((psa_key_usage_t)0x00000080) #define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t)0x00000100) #define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t)0x00000001) #define PSA_KEY_USAGE_SIGN_HASH ((psa_key_usage_t)0x00001000) From ea64cc455a5875462d738c44b6e8f65361051be8 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 17 Sep 2025 13:37:33 +0100 Subject: [PATCH 09/10] Rework the description of psa_check_key_usage() * Permit key-management usage flag checking * Provide more detail on the parameter validity and compatibility checking. --- doc/crypto/api/keys/policy.rst | 89 +++++++++++++++++++++++----------- 1 file changed, 60 insertions(+), 29 deletions(-) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 6d321ea4..73c868a2 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -81,12 +81,17 @@ When a key is used in a cryptographic operation, the application must supply the Key usage flags --------------- -The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. Five kinds of usage flag can be specified: +The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. There are two kinds of usage flag: -* The extractable flag `PSA_KEY_USAGE_EXPORT` determines whether the key material can be extracted from the cryptoprocessor, or copied outside of its current security boundary. -* The copyable flag `PSA_KEY_USAGE_COPY` determines whether the key material can be copied into a new key, which can have a different lifetime or a more restrictive policy. -* The cacheable flag `PSA_KEY_USAGE_CACHE` determines whether the implementation is permitted to retain non-essential copies of the key material in RAM. This policy only applies to persistent keys. See also :secref:`key-material`. -* The following usage flags determine whether the corresponding operations are permitted with the key: +1. Key-management usage flags. + + - The extractable flag `PSA_KEY_USAGE_EXPORT` determines whether the key material can be extracted from the cryptoprocessor, or copied outside of its current security boundary. + - The copyable flag `PSA_KEY_USAGE_COPY` determines whether the key material can be copied into a new key, which can have a different lifetime or a more restrictive policy. + - The cacheable flag `PSA_KEY_USAGE_CACHE` determines whether the implementation is permitted to retain non-essential copies of the key material in RAM. This policy only applies to persistent keys. See also :secref:`key-material`. + +2. Cryptographic-operation usage flags. + + The following usage flags determine whether the corresponding cryptographic operations are permitted with the key: - `PSA_KEY_USAGE_ENCRYPT` - `PSA_KEY_USAGE_DECRYPT` @@ -97,7 +102,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. - `PSA_KEY_USAGE_DERIVE` - `PSA_KEY_USAGE_VERIFY_DERIVATION` -* The flag `PSA_KEY_USAGE_DERIVE_PUBLIC` is used in the function `psa_check_key_usage()` to query if a key can be used for the public role in the specified algorithm. + The flag `PSA_KEY_USAGE_DERIVE_PUBLIC` is used in the function `psa_check_key_usage()` to query if a key can be used for the public role in the specified algorithm. .. typedef:: uint32_t psa_key_usage_t @@ -124,7 +129,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. summary:: Permission to copy the key. - This flag is required to make a copy of a key using `psa_copy_key()`. + This key-managament usage flag is required to make a copy of a key using `psa_copy_key()`. For a key lifetime that corresponds to a secure element location that enforces the non-exportability of keys, copying a key outside the secure element also requires the usage flag `PSA_KEY_USAGE_EXPORT`. Copying the key within 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. @@ -155,7 +160,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. summary:: Permission to encrypt a message, or perform key encapsulation, with the key. - This flag is required to use the key in a symmetric encryption operation, in an AEAD encryption-and-authentication operation, in an asymmetric encryption operation, or in a key-encapsulation operation. The flag must be present on keys used with the following APIs: + This key-managament usage flag is required to use the key in a symmetric encryption operation, in an AEAD encryption-and-authentication operation, in an asymmetric encryption operation, or in a key-encapsulation operation. The flag must be present on keys used with the following APIs: * `psa_cipher_encrypt()` * `psa_cipher_encrypt_setup()` @@ -172,7 +177,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. summary:: Permission to decrypt a message, or perform key decapsulation, with the key. - This flag is required to use the key in a symmetric decryption operation, in an AEAD decryption-and-verification operation, in an asymmetric decryption operation, or in a key-decapsulation operation. The flag must be present on keys used with the following APIs: + This key-managament usage flag is required to use the key in a symmetric decryption operation, in an AEAD decryption-and-verification operation, in an asymmetric decryption operation, or in a key-decapsulation operation. The flag must be present on keys used with the following APIs: * `psa_cipher_decrypt()` * `psa_cipher_decrypt_setup()` @@ -189,7 +194,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. summary:: Permission to sign a message with the key. - This flag is required to use the key in a MAC calculation operation, or in an asymmetric message signature operation. The flag must be present on keys used with the following APIs: + This cryptographic-operation usage flag is required to use the key in a MAC calculation operation, or in an asymmetric message signature operation. The flag must be present on keys used with the following APIs: * `psa_mac_compute()` * `psa_mac_sign_setup()` @@ -203,7 +208,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. summary:: Permission to verify a message signature with the key. - This flag is required to use the key in a MAC verification operation, or in an asymmetric message signature verification operation. The flag must be present on keys used with the following APIs: + This cryptographic-operation usage flag is required to use the key in a MAC verification operation, or in an asymmetric message signature verification operation. The flag must be present on keys used with the following APIs: * `psa_mac_verify()` * `psa_mac_verify_setup()` @@ -217,7 +222,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. summary:: Permission to sign a message hash with the key. - This flag is required to use the key to sign a pre-computed message hash in an asymmetric signature operation. The flag must be present on keys used with the following APIs: + This cryptographic-operation usage flag is required to use the key to sign a pre-computed message hash in an asymmetric signature operation. The flag must be present on keys used with the following APIs: * `psa_sign_hash()` @@ -231,7 +236,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. summary:: Permission to verify a message hash with the key. - This flag is required to use the key to verify a pre-computed message hash in an asymmetric signature verification operation. The flag must be present on keys used with the following APIs: + This cryptographic-operation usage flag is required to use the key to verify a pre-computed message hash in an asymmetric signature verification operation. The flag must be present on keys used with the following APIs: * `psa_verify_hash()` @@ -245,7 +250,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. summary:: Permission to derive other keys or produce a password hash from this key. - This flag is required to use the key for derivation in a key-derivation operation, or in a key-agreement operation. + This cryptographic-operation usage flag is required to use the key for derivation in a key-derivation operation, or in a key-agreement operation. This flag must be present on keys used with the following APIs: @@ -263,7 +268,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. versionadded:: 1.1 - This flag is required to use the key for verification in a key-derivation operation. + This cryptographic-operation usage flag is required to use the key for verification in a key-derivation operation. This flag must be present on keys used with `psa_key_derivation_verify_key()`. @@ -277,8 +282,8 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. versionadded:: 1.4 - This flag is only used with the `psa_check_key_usage()` function. - This flag is never checked when performing cryptographic operations. + This cryptographic-operation usage flag is only used with the `psa_check_key_usage()` function. + This flag is not currently checked when performing any cryptographic operation. For example, calling `psa_check_key_usage()` with `PSA_KEY_USAGE_DERIVE_PUBLIC` and with: @@ -346,16 +351,23 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. retval:: PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error: - * ``alg`` is not a specific cryptographic algorithm. - It cannot be a wildcard algorithm. - * ``usage`` is not a valid role for algorithm ``alg``. - * ``key`` is not compatible with ``alg`` and ``usage``. + * If ``alg`` is `PSA_ALG_NONE` and ``usage`` is not a key-management usage flag. + * If ``alg`` is not `PSA_ALG_NONE`, then any of the following conditions can result in this error: + + * ``alg`` is not a valid, specific cryptographic algorithm. + It cannot be a wildcard algorithm. + * ``usage`` is not a cryptographic-operation usage flag. + * ``usage`` is not a valid role for algorithm ``alg``. + * ``key`` is not compatible with ``alg`` and ``usage``. .. retval: PSA_ERROR_INVALID_HANDLE: ``key`` is not a valid key identifier. .. retval: PSA_ERROR_NOT_PERMITTED ``key`` does not permit the requested usage or algorithm. .. retval:: PSA_ERROR_NOT_SUPPORTED - The implementation does not support using ``key`` with the cryptographic operation associated with ``alg`` and ``usage``. + The following conditions can result in this error: + + * The implementation does not support algorithm ``alg``. + * The implementation does not support using ``key`` with the operation associated with ``alg`` and ``usage``. .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. retval:: PSA_ERROR_CORRUPTION_DETECTED @@ -365,14 +377,33 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. retval:: PSA_ERROR_BAD_STATE The library requires initializing by a call to `psa_crypto_init()`. - Returns success only if this key object exists, is compatible with the operation associated with the algorithm and usage, has the required permission, and this implementation supports this key type for this operation. - + This function reports whether the implementation supports the use of a key with the operation associated with a provided algorithm and usage. This function does not attempt to perform the operation, so does not use any resources in the cryptographic engine. - ``alg`` must be a fully specified algorithm, and not a wildcard. + If ``usage`` is a key-management usage flag, then: + + * ``alg`` must be `PSA_ALG_NONE`. + * ``key`` must exist, and permit the requested usage flag. + + If ``usage`` is a cryptographic-operation usage flag, then: + + * ``alg`` must be a valid, fully specified algorithm, and not a wildcard. + For example: + + - :code:`PSA_ALG_ECDSA(PSA_ALG_ANY_HASH)` is invalid as it is a wildcard algorithm. + - :code:`PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_GCM, 9)` is invalid as it has an invalid tag-length for GCM. + - :code:`PSA_ALG_SPAKE2P_HMAC(PSA_ALG_SHA_1)` is invalid as SPAKE2+ does have SHA-1 in any cipher-suite. + * ``usage`` must identify a valid role within the algorithm. + For example, if :code:`alg == PSA_ALG_GCM`, the ``usage`` must be either `PSA_KEY_USAGE_ENCRYPT` or `PSA_KEY_USAGE_DECRYPT`, as these are the key-usage policy flags for AEAD functions. + * ``key`` must exist, have a type and size that is compatible with the operation associated with ``alg`` and ``usage``, and have the required permission for the algorithm and usage. + For example: + + - A Edwards25519 key pair is not compatible with :code:`PSA_ALG_ECDSA(PSA_ALG_SHA_256)`. + - A ``512``-bit RSA key pair is not compatible with :code:`PSA_ALG_RSA_OAEP(PSA_ALG_SHA_512)` as the algorithm requires a larger key size. + - A ``512``-bit AES key (double-length key for use in AES-256-XTS) is not compatible with `PSA_ALG_CTR`. - ``usage`` must be a valid role within a cryptographic algorithm. - It must not be a non-cryptographic key usage flag, such as `PSA_KEY_USAGE_COPY` or `PSA_KEY_USAGE_EXPORT`. + .. todo:: Is this asking too much of this function? Could/should we relax some of the validation reqiurements to be recommendations? - Note that for the key pair or public key of a valid type in a key agreement function, this function returns :code:`PSA_SUCCESS` for the usage `PSA_KEY_USAGE_DERIVE_PUBLIC`, regardless of the key's policy. - This is because the corresponding API functions take a key buffer as input, not a key object, and the key data can extracted by calling `psa_export_public_key()`, which does not require any usage flag. + .. note:: + For the key pair or public key of a valid type in a key agreement function, this function returns :code:`PSA_SUCCESS` for the usage `PSA_KEY_USAGE_DERIVE_PUBLIC`, regardless of the key's policy. + This is because the corresponding API functions take a key buffer as input, not a key object, and the key data can extracted by calling `psa_export_public_key()`, which does not require any usage flag. From 09044b4d0a82b71c8d348034bfc74966f8cf252f Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 18 Sep 2025 13:49:55 +0100 Subject: [PATCH 10/10] FIxing typos and resolving todo. --- doc/crypto/api/keys/policy.rst | 35 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 73c868a2..f7482148 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -115,7 +115,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. summary:: Permission to export the key. - This flag permits a key to be moved outside of the security boundary of its current storage location. In particular: + This key-management usage flag permits a key to be moved outside of the security boundary of its current storage location. In particular: * This flag is required to export a key from the cryptoprocessor using `psa_export_key()`. A public key or the public part of a key pair can always be exported regardless of the value of this permission flag. @@ -129,7 +129,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. summary:: Permission to copy the key. - This key-managament usage flag is required to make a copy of a key using `psa_copy_key()`. + This key-management usage flag is required to make a copy of a key using `psa_copy_key()`. For a key lifetime that corresponds to a secure element location that enforces the non-exportability of keys, copying a key outside the secure element also requires the usage flag `PSA_KEY_USAGE_EXPORT`. Copying the key within 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. @@ -139,7 +139,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. summary:: Permission for the implementation to cache the key. - This flag permits the implementation to make additional copies of the key material that are not in storage and not for the purpose of an ongoing operation. Applications can use it as a hint for the cryptoprocessor, to keep a copy of the key around for repeated access. + This key-management usage flag permits the implementation to make additional copies of the key material that are not in storage and not for the purpose of an ongoing operation. Applications can use it as a hint for the cryptoprocessor, to keep a copy of the key around for repeated access. An application can request that cached key material is removed from memory by calling `psa_purge_key()`. @@ -160,7 +160,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. summary:: Permission to encrypt a message, or perform key encapsulation, with the key. - This key-managament usage flag is required to use the key in a symmetric encryption operation, in an AEAD encryption-and-authentication operation, in an asymmetric encryption operation, or in a key-encapsulation operation. The flag must be present on keys used with the following APIs: + This cryptographic-operation usage flag is required to use the key in a symmetric encryption operation, in an AEAD encryption-and-authentication operation, in an asymmetric encryption operation, or in a key-encapsulation operation. The flag must be present on keys used with the following APIs: * `psa_cipher_encrypt()` * `psa_cipher_encrypt_setup()` @@ -177,7 +177,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. summary:: Permission to decrypt a message, or perform key decapsulation, with the key. - This key-managament usage flag is required to use the key in a symmetric decryption operation, in an AEAD decryption-and-verification operation, in an asymmetric decryption operation, or in a key-decapsulation operation. The flag must be present on keys used with the following APIs: + This cryptographic-operation usage flag is required to use the key in a symmetric decryption operation, in an AEAD decryption-and-verification operation, in an asymmetric decryption operation, or in a key-decapsulation operation. The flag must be present on keys used with the following APIs: * `psa_cipher_decrypt()` * `psa_cipher_decrypt_setup()` @@ -351,14 +351,11 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. .. retval:: PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error: - * If ``alg`` is `PSA_ALG_NONE` and ``usage`` is not a key-management usage flag. - * If ``alg`` is not `PSA_ALG_NONE`, then any of the following conditions can result in this error: - - * ``alg`` is not a valid, specific cryptographic algorithm. - It cannot be a wildcard algorithm. - * ``usage`` is not a cryptographic-operation usage flag. - * ``usage`` is not a valid role for algorithm ``alg``. - * ``key`` is not compatible with ``alg`` and ``usage``. + * ``usage`` is a key-management usage flag and ``alg`` is not `PSA_ALG_NONE`. + * ``usage`` is a cryptographic-operation usage flag and ``alg`` is not a valid, specific algorithm. + A 'specific algorithm' is one that is neither `PSA_ALG_NONE` nor a wildcard algorithm. + * ``usage`` is not a valid role for algorithm ``alg``. + * ``key`` is not compatible with ``alg`` and ``usage``. .. retval: PSA_ERROR_INVALID_HANDLE: ``key`` is not a valid key identifier. .. retval: PSA_ERROR_NOT_PERMITTED @@ -378,7 +375,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. The library requires initializing by a call to `psa_crypto_init()`. This function reports whether the implementation supports the use of a key with the operation associated with a provided algorithm and usage. - This function does not attempt to perform the operation, so does not use any resources in the cryptographic engine. + This function does not attempt to perform the operation. If ``usage`` is a key-management usage flag, then: @@ -395,15 +392,17 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. - :code:`PSA_ALG_SPAKE2P_HMAC(PSA_ALG_SHA_1)` is invalid as SPAKE2+ does have SHA-1 in any cipher-suite. * ``usage`` must identify a valid role within the algorithm. For example, if :code:`alg == PSA_ALG_GCM`, the ``usage`` must be either `PSA_KEY_USAGE_ENCRYPT` or `PSA_KEY_USAGE_DECRYPT`, as these are the key-usage policy flags for AEAD functions. - * ``key`` must exist, have a type and size that is compatible with the operation associated with ``alg`` and ``usage``, and have the required permission for the algorithm and usage. + * ``key`` must exist, have a type and size that are compatible with the operation associated with ``alg`` and ``usage``, and have the required permission for the algorithm and usage. For example: - - A Edwards25519 key pair is not compatible with :code:`PSA_ALG_ECDSA(PSA_ALG_SHA_256)`. + - An Edwards25519 key pair is not compatible with :code:`PSA_ALG_ECDSA(PSA_ALG_SHA_256)`. - A ``512``-bit RSA key pair is not compatible with :code:`PSA_ALG_RSA_OAEP(PSA_ALG_SHA_512)` as the algorithm requires a larger key size. - A ``512``-bit AES key (double-length key for use in AES-256-XTS) is not compatible with `PSA_ALG_CTR`. - .. todo:: Is this asking too much of this function? Could/should we relax some of the validation reqiurements to be recommendations? - .. note:: For the key pair or public key of a valid type in a key agreement function, this function returns :code:`PSA_SUCCESS` for the usage `PSA_KEY_USAGE_DERIVE_PUBLIC`, regardless of the key's policy. This is because the corresponding API functions take a key buffer as input, not a key object, and the key data can extracted by calling `psa_export_public_key()`, which does not require any usage flag. + + .. admonition:: Implementation note + + The intended behavior of this function is to include any check that can be made using the accessible key attributes, but without requiring logic or arithmetic using the key material.