9.8 Key policies

All keys have an associated policy that regulates which operations are permitted on the key. A key policy is composed of two elements:

The policy is part of the key attributes that are managed by a psa_key_attributes_t object.

A highly constrained implementation might not be able to support all the policies that can be expressed through this interface. If an implementation cannot create a key with the required policy, it must return an appropriate error code when the key is created.

9.8.1 Permitted algorithms

The permitted algorithm is encoded using a algorithm identifier, as described in Algorithms.

For most algorithms, this specification only defines policies that restrict keys to a single algorithm, which is consistent with both common practice and security good practice.

If the permitted algorithm is PSA_ALG_NONE, no cryptographic operation is permitted with the key. The key can still be used for non-cryptographic actions such as exporting, if permitted by the usage flags.

For a cryptographic operation, the permitted algorithm value must exactly match the requested algorithm, except in the following cases:

When a key is used in a cryptographic operation, the application supplies the algorithm to use for the operation. The algorithm and operation are checked against the key’s permitted-algorithm policy.

psa_set_key_algorithm (function)

Declare the permitted-algorithm policy for a key.

void psa_set_key_algorithm(psa_key_attributes_t * attributes,
                           psa_algorithm_t alg);

Parameters

attributes

The attribute object to write to.

alg

The permitted algorithm to write.

Returns: void

Description

The permitted-algorithm policy of a key encodes which algorithm or algorithms are permitted to be used with this key.

This function overwrites any permitted-algorithm policy previously set in attributes.

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.

psa_get_key_algorithm (function)

Retrieve the permitted-algorithm policy from key attributes.

psa_algorithm_t psa_get_key_algorithm(const psa_key_attributes_t * attributes);

Parameters

attributes

The key attribute object to query.

Returns: psa_algorithm_t

The algorithm stored in the attribute object.

Description

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.

9.8.2 Key usage flags

The usage flags are encoded in a bitmask, which has the type psa_key_usage_t. There are two kinds of usage flag:

  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 Managing key material.

  2. Cryptographic-operation usage flags.

    The following usage flags determine whether the corresponding cryptographic operations are permitted with the key:

    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.

psa_key_usage_t (typedef)

Encoding of permitted usage on a key.

typedef uint32_t psa_key_usage_t;

PSA_KEY_USAGE_EXPORT (macro)

Permission to export the key.

#define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t)0x00000001)

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.

  • This flag can also be required to make a copy of a key outside of a secure element using psa_copy_key(). See also PSA_KEY_USAGE_COPY.

If a key does not have export permission, implementations must not permit the key to be exported in plain form from the cryptoprocessor, whether through psa_export_key() or through a proprietary interface. The key might still be exportable in a wrapped form, i.e. in a form where it is encrypted by another key.

PSA_KEY_USAGE_COPY (macro)

Permission to copy the key.

#define PSA_KEY_USAGE_COPY ((psa_key_usage_t)0x00000002)

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.

PSA_KEY_USAGE_CACHE (macro)

Permission for the implementation to cache the key.

#define PSA_KEY_USAGE_CACHE ((psa_key_usage_t)0x00000004)

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().

The presence of this usage flag when creating a key is a hint:

  • An implementation is not required to cache keys that have this usage flag.

  • An implementation must not report an error if it does not cache keys.

If this usage flag is not present, the implementation must ensure key material is removed from memory as soon as it is not required for an operation, or for maintenance of a volatile key.

This flag must be preserved when reading back the attributes for all keys, regardless of key type or implementation behavior.

See also Managing key material.

PSA_KEY_USAGE_ENCRYPT (macro)

Permission to encrypt a message, or perform key encapsulation, with the key.

#define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t)0x00000100)

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:

For a key pair, this concerns the public key.

PSA_KEY_USAGE_DECRYPT (macro)

Permission to decrypt a message, or perform key decapsulation, with the key.

#define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200)

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:

For a key pair, this concerns the private key.

PSA_KEY_USAGE_SIGN_MESSAGE (macro)

Permission to sign a message with the key.

#define PSA_KEY_USAGE_SIGN_MESSAGE ((psa_key_usage_t)0x00000400)

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:

For a key pair, this concerns the private key.

PSA_KEY_USAGE_VERIFY_MESSAGE (macro)

Permission to verify a message signature with the key.

#define PSA_KEY_USAGE_VERIFY_MESSAGE ((psa_key_usage_t)0x00000800)

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:

For a key pair, this concerns the public key.

PSA_KEY_USAGE_SIGN_HASH (macro)

Permission to sign a message hash with the key.

#define PSA_KEY_USAGE_SIGN_HASH ((psa_key_usage_t)0x00001000)

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:

This flag automatically sets PSA_KEY_USAGE_SIGN_MESSAGE: if an application sets the flag PSA_KEY_USAGE_SIGN_HASH when creating a key, then the key always has the permissions conveyed by PSA_KEY_USAGE_SIGN_MESSAGE, and the flag PSA_KEY_USAGE_SIGN_MESSAGE will also be present when the application queries the usage flags of the key.

For a key pair, this concerns the private key.

PSA_KEY_USAGE_VERIFY_HASH (macro)

Permission to verify a message hash with the key.

#define PSA_KEY_USAGE_VERIFY_HASH ((psa_key_usage_t)0x00002000)

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:

This flag automatically sets PSA_KEY_USAGE_VERIFY_MESSAGE: if an application sets the flag PSA_KEY_USAGE_VERIFY_HASH when creating a key, then the key always has the permissions conveyed by PSA_KEY_USAGE_VERIFY_MESSAGE, and the flag PSA_KEY_USAGE_VERIFY_MESSAGE will also be present when the application queries the usage flags of the key.

For a key pair, this concerns the public key.

PSA_KEY_USAGE_DERIVE (macro)

Permission to derive other keys or produce a password hash from this key.

#define PSA_KEY_USAGE_DERIVE ((psa_key_usage_t)0x00004000)

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:

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_output_bytes(), psa_key_derivation_output_key(), psa_key_derivation_output_key_custom(), psa_key_derivation_verify_bytes(), or psa_key_derivation_verify_key() at the end of the operation.

PSA_KEY_USAGE_VERIFY_DERIVATION (macro)

Permission to verify the result of a key derivation, including password hashing.

Added in version 1.1.

#define PSA_KEY_USAGE_VERIFY_DERIVATION ((psa_key_usage_t)0x00008000)

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().

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.

PSA_KEY_USAGE_DERIVE_PUBLIC (macro)

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.

Added in version 1.4.

#define PSA_KEY_USAGE_DERIVE_PUBLIC ((psa_key_usage_t)0x00000080)

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:

  • 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.

PSA_KEY_USAGE_WRAP (macro)

Permission to wrap another key with the key.

#define PSA_KEY_USAGE_WRAP ((psa_key_usage_t)0x00010000)

This flag is required to use the key in a key-wrapping operation. The flag must be present on keys used with the following APIs:

PSA_KEY_USAGE_UNWRAP (macro)

Permission to unwrap another key with the key.

#define PSA_KEY_USAGE_UNWRAP ((psa_key_usage_t)0x00020000)

This flag is required to use the key in a key-unwrapping operation. The flag must be present on keys used with the following APIs:

psa_set_key_usage_flags (function)

Declare usage flags for a key.

void psa_set_key_usage_flags(psa_key_attributes_t * attributes,
                             psa_key_usage_t usage_flags);

Parameters

attributes

The attribute object to write to.

usage_flags

The usage flags to write.

Returns: void

Description

Usage flags are part of a key’s policy. They encode what kind of operations are permitted on the key. For more details, see Key policies.

This function overwrites any usage flags previously set in attributes.

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.

psa_get_key_usage_flags (function)

Retrieve the usage flags from key attributes.

psa_key_usage_t psa_get_key_usage_flags(const psa_key_attributes_t * attributes);

Parameters

attributes

The key attribute object to query.

Returns: psa_key_usage_t

The usage flags stored in the attribute object.

Description

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.

psa_check_key_usage (function)

Query the capability of a key.

Added in version 1.4.

psa_status_t psa_check_key_usage(psa_key_id_t key,
                                 psa_algorithm_t alg,
                                 psa_key_usage_t usage);

Parameters

key

Identifier of the key to check.

alg

An algorithm identifier: a value of type psa_algorithm_t.

usage

A single PSA_KEY_USAGE_xxx flag.

Returns: psa_status_t

PSA_SUCCESS

key can be used for the requested operation on this implementation.

PSA_ERROR_BAD_STATE

The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

  • 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.

PSA_ERROR_NOT_SUPPORTED

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.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

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.

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:

Note

For the key pair or public key of a valid type in a key agreement function, this function returns 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.

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.