Platform Security Architecture — cryptography and keystore interface  Working draft
Macros | Typedefs | Functions
Key policies

Macros

#define PSA_KEY_USAGE_EXPORT   ((psa_key_usage_t)0x00000001)
 
#define PSA_KEY_USAGE_ENCRYPT   ((psa_key_usage_t)0x00000100)
 
#define PSA_KEY_USAGE_DECRYPT   ((psa_key_usage_t)0x00000200)
 
#define PSA_KEY_USAGE_SIGN   ((psa_key_usage_t)0x00000400)
 
#define PSA_KEY_USAGE_VERIFY   ((psa_key_usage_t)0x00000800)
 
#define PSA_KEY_USAGE_DERIVE   ((psa_key_usage_t)0x00001000)
 

Typedefs

typedef uint32_t psa_key_usage_t
 Encoding of permitted usage on a key.
 
typedef struct psa_key_policy_s psa_key_policy_t
 

Functions

void psa_key_policy_init (psa_key_policy_t *policy)
 Initialize a key policy structure to a default that forbids all usage of the key. More...
 
void psa_key_policy_set_usage (psa_key_policy_t *policy, psa_key_usage_t usage, psa_algorithm_t alg)
 Set the standard fields of a policy structure. More...
 
psa_key_usage_t psa_key_policy_get_usage (const psa_key_policy_t *policy)
 Retrieve the usage field of a policy structure. More...
 
psa_algorithm_t psa_key_policy_get_algorithm (const psa_key_policy_t *policy)
 Retrieve the algorithm field of a policy structure. More...
 
psa_status_t psa_set_key_policy (psa_key_slot_t key, const psa_key_policy_t *policy)
 Set the usage policy on a key slot. More...
 
psa_status_t psa_get_key_policy (psa_key_slot_t key, psa_key_policy_t *policy)
 Get the usage policy for a key slot. More...
 

Detailed Description

Macro Definition Documentation

◆ PSA_KEY_USAGE_DECRYPT

#define PSA_KEY_USAGE_DECRYPT   ((psa_key_usage_t)0x00000200)

Whether the key may be used to decrypt a message.

This flag allows the key to be used for a symmetric decryption operation, for an AEAD decryption-and-verification operation, or for an asymmetric decryption operation, if otherwise permitted by the key's type and policy.

For a key pair, this concerns the private key.

◆ PSA_KEY_USAGE_DERIVE

#define PSA_KEY_USAGE_DERIVE   ((psa_key_usage_t)0x00001000)

Whether the key may be used to derive other keys.

◆ PSA_KEY_USAGE_ENCRYPT

#define PSA_KEY_USAGE_ENCRYPT   ((psa_key_usage_t)0x00000100)

Whether the key may be used to encrypt a message.

This flag allows the key to be used for a symmetric encryption operation, for an AEAD encryption-and-authentication operation, or for an asymmetric encryption operation, if otherwise permitted by the key's type and policy.

For a key pair, this concerns the public key.

◆ PSA_KEY_USAGE_EXPORT

#define PSA_KEY_USAGE_EXPORT   ((psa_key_usage_t)0x00000001)

Whether the key may be exported.

A public key or the public part of a key pair may always be exported regardless of the value of this permission flag.

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

◆ PSA_KEY_USAGE_SIGN

#define PSA_KEY_USAGE_SIGN   ((psa_key_usage_t)0x00000400)

Whether the key may be used to sign a message.

This flag allows the key to be used for a MAC calculation operation or for an asymmetric signature operation, if otherwise permitted by the key's type and policy.

For a key pair, this concerns the private key.

◆ PSA_KEY_USAGE_VERIFY

#define PSA_KEY_USAGE_VERIFY   ((psa_key_usage_t)0x00000800)

Whether the key may be used to verify a message signature.

This flag allows the key to be used for a MAC verification operation or for an asymmetric signature verification operation, if otherwise permitted by by the key's type and policy.

For a key pair, this concerns the public key.

Typedef Documentation

◆ psa_key_policy_t

typedef struct psa_key_policy_s psa_key_policy_t

The type of the key policy data structure.

This is an implementation-defined struct. Applications should not make any assumptions about the content of this structure except as directed by the documentation of a specific implementation.

Function Documentation

◆ psa_get_key_policy()

psa_status_t psa_get_key_policy ( psa_key_slot_t  key,
psa_key_policy_t policy 
)

Get the usage policy for a key slot.

Parameters
keyThe key slot whose policy is being queried.
[out]policyOn success, the key's policy.
Return values
PSA_SUCCESS
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED

◆ psa_key_policy_get_algorithm()

psa_algorithm_t psa_key_policy_get_algorithm ( const psa_key_policy_t policy)

Retrieve the algorithm field of a policy structure.

Parameters
[in]policyThe policy object to query.
Returns
The permitted algorithm for a key with this policy.

◆ psa_key_policy_get_usage()

psa_key_usage_t psa_key_policy_get_usage ( const psa_key_policy_t policy)

Retrieve the usage field of a policy structure.

Parameters
[in]policyThe policy object to query.
Returns
The permitted uses for a key with this policy.

◆ psa_key_policy_init()

void psa_key_policy_init ( psa_key_policy_t policy)

Initialize a key policy structure to a default that forbids all usage of the key.

Parameters
[out]policyThe policy object to initialize.

◆ psa_key_policy_set_usage()

void psa_key_policy_set_usage ( psa_key_policy_t policy,
psa_key_usage_t  usage,
psa_algorithm_t  alg 
)

Set the standard fields of a policy structure.

Note that this function does not make any consistency check of the parameters. The values are only checked when applying the policy to a key slot with psa_set_key_policy().

Parameters
[out]policyThe policy object to modify.
usageThe permitted uses for the key.
algThe algorithm that the key may be used for.

◆ psa_set_key_policy()

psa_status_t psa_set_key_policy ( psa_key_slot_t  key,
const psa_key_policy_t policy 
)

Set the usage policy on a key slot.

This function must be called on an empty key slot, before importing, generating or creating a key in the slot. Changing the policy of an existing key is not permitted.

Implementations may set restrictions on supported key policies depending on the key type and the key slot.

Parameters
keyThe key slot whose policy is to be changed.
[in]policyThe policy object to query.
Return values
PSA_SUCCESS
PSA_ERROR_OCCUPIED_SLOT
PSA_ERROR_NOT_SUPPORTED
PSA_ERROR_INVALID_ARGUMENT
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED