PSA Cryptography API Specification

Document history

Date Changes
2019-01-21 Release 1.0 beta 1
2019-02-08
  • Remove obsolete definition PSA_ALG_IS_KEY_SELECTION.
  • psa_key_agreement: document alg parameter.
  • PSA_AEAD_FINISH_OUTPUT_SIZE: remove spurious parameter plaintext_length.
2019-02-08 Document formatting improvements
2019-02-22 Release 1.0 beta 2
2019-03-12 Specify psa_generator_import_key for most key types.
2019-04-09

Change the value of error codes, and some names, to align with other PSA specifications. The name changes are:

2019-05-02

Change the way keys are created to avoid “half-filled” handles that contained key metadata, but no key material. Now, to create a key, first fill in a data structure containing its attributes, then pass this structure to a function that both allocates resources for the key and fills in the key material. This affects the following functions:

  • psa_import_key, psa_generate_key, psa_generator_import_key and psa_copy_key now take an attribute structure (specifically, a pointer to psa_key_attributes_t) to specify key metadata. This replaces the previous method of passing arguments to psa_create_key or to the key material creation function or calling psa_set_key_policy.
  • psa_key_policy_t and functions operating on that type no longer exist. A key’s policy is now accessible as part of its attributes.
  • psa_get_key_information is also replaced by accessing the key’s attributes (retrieved with psa_get_key_attributes).
  • psa_create_key no longer exists. Instead, set the key id attribute and the lifetime attribute before creating the key material.
2019-05-14
  • Allow psa_aead_update to buffer data.
  • New buffer size calculation macros.
2019-05-16
  • Key identifiers are no longer specific to a given lifetime value. psa_open_key no longer takes a lifetime parameter.
  • Define a range of key identifiers for use by applications and a separate range for use by implementations.
2019-05-16

Avoid the unusual terminology “generator”: call them “key derivation operations” instead. Rename a number of functions and other identifiers related to for clarity and consistency:

2019-05-16
  • Clarify the behavior in various corner cases.
  • Document more error conditions.
2019-05-21 Convert TLS1.2 KDF descriptions to multistep key derivation.
2019-05-22 Release 1.0 beta 3

Planned changes for version 1.0

Here is a summary of the changes we are currently planning to make to this specification for version 1.0.

  • Add missing macros to calculate output buffer sizes, IV/nonce sizes, and maximum supported data sizes.
  • Remove the definition of most macros, to give implementations free choice regarding how these macros are implemented, as long as the implementation meets the English-language specification.
  • Remove certain auxiliary macros that are not directly useful to applications, but are currently used as building blocks to define other macros.
  • Correct lists of documented error codes for several functions, and clarify error conditions for many functions.
  • Constrain whether and when an application may have the same persistent key open multiple times.
  • Constrain the permitted implementation behavior when calling a function on an operation object in a state where this function does not make sense, and when a key is destroyed while in use.
  • Declare identifiers for additional cryptographic algorithms.
  • Forbid zero-length keys.
  • Use a standard import/export format for EC keys on Montgomery curves.
  • Mandate certain checks when importing some types of asymmetric keys.
  • Clarifications and improvements to the description of some API elements and to the structure of the document.

Indices