Platform Security Architecture — cryptography and keystore interface  beta 2 — 2019-02-22
Macros | Typedefs | Functions
Key policies

Macros

#define PSA_KEY_POLICY_INIT   {0}
 
#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 struct psa_key_policy_s psa_key_policy_t
 
typedef uint32_t psa_key_usage_t
 Encoding of permitted usage on a key.
 

Functions

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_handle_t handle, const psa_key_policy_t *policy)
 Set the usage policy on a key slot. More...
 
psa_status_t psa_get_key_policy (psa_key_handle_t handle, psa_key_policy_t *policy)
 Get the usage policy for a key slot. More...
 

Detailed Description

Macro Definition Documentation

#define PSA_KEY_POLICY_INIT   {0}

This macro returns a suitable initializer for a key policy object of type psa_key_policy_t.

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

#define PSA_KEY_USAGE_DERIVE   ((psa_key_usage_t)0x00001000)

Whether the key may be used to derive other keys.

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

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

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

#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

typedef struct psa_key_policy_s psa_key_policy_t

The type of the key policy data structure.

Before calling any function on a key policy, the application must initialize it by any of the following means:

  • Set the structure to all-bits-zero, for example:
    1 psa_key_policy_t policy;
    2 memset(&policy, 0, sizeof(policy));
  • Initialize the structure to logical zero values, for example:
    1 psa_key_policy_t policy = {0};
  • Initialize the structure to the initializer PSA_KEY_POLICY_INIT, for example:
    1 psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
  • Assign the result of the function psa_key_policy_init() to the structure, for example:
    1 psa_key_policy_t policy;
    2 policy = psa_key_policy_init();

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_status_t psa_get_key_policy ( psa_key_handle_t  handle,
psa_key_policy_t policy 
)

Get the usage policy for a key slot.

Parameters
handleHandle to the key slot whose policy is being queried.
[out]policyOn success, the key's policy.
Return values
PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
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_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.
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
[in,out]policyThe key policy to modify. It must have been initialized as per the documentation for psa_key_policy_t.
usageThe permitted uses for the key.
algThe algorithm that the key may be used for.
psa_status_t psa_set_key_policy ( psa_key_handle_t  handle,
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
handleHandle to the key whose policy is to be changed.
[in]policyThe policy object to query.
Return values
PSA_SUCCESSSuccess. If the key is persistent, it is implementation-defined whether the policy has been saved to persistent storage. Implementations may defer saving the policy until the key material is created.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_OCCUPIED_SLOT
PSA_ERROR_NOT_SUPPORTED
PSA_ERROR_INVALID_ARGUMENT
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.