Changes to the API

Release information

All published versions of this document have been non-confidential.

The change history table lists the changes that have been made to this document.

Date Version Comments
Jan 2019 1.0 beta 1 First public beta release.
Feb 2019 1.0 beta 2 Update for release with other PSA Dev API specifications.
May 2019 1.0 beta 3

Update for release with other PSA API specifications.

  • Alignment with PSA API specifications.
  • Changes to the key creation API.
  • Changes to the handling of key lifetimes.
  • Replaced ‘generators’ with key derivation operations.
Feb 2020 1.0.0

1.0 API finalized.

  • Removed implementation APIs and definitions.
  • Merged key handles with key identifiers.
  • Recoded algorithm identifiers.
  • Restructured key types.
  • Provide buffer size macros for all output buffers.
  • Provide sign-message signature operations.
  • Add functions to suspend and resume hash operations.
  • Reallocated key types and algorithm identifiers.
  • Many minor corrections and clarifications.

The detailed changes in each release are described in the following sections.

Document change history

Changes between 1.0 beta 1 and 1.0 beta 2

Changes to the API

Clarifications

  • psa_key_agreement(): document alg parameter.

Other changes

  • Document formatting improvements.

Changes between 1.0 beta 2 and 1.0 beta 3

Changes to the API

Clarifications

  • Specify psa_generator_import_key() for most key types.
  • Clarify the behavior in various corner cases.
  • Document more error conditions.

Changes between 1.0 beta 3 and 1.0.0

Changes to the API

Clarifications

  • Clarified rules regarding modification of parameters in concurrent environments.
  • Guarantee that psa_destroy_key(PSA_KEY_ID_NULL) always returns PSA_SUCCESS.
  • Clarified the TLS PSK to MS key agreement algorithm.
  • Document the key policy requirements for all APIs that accept a key parameter.
  • Document more of the error codes for each function.

Other changes

  • Require C99 for this specification instead of C89.
  • Removed references to non-standard mbed-crypto header files. The only header file that applications need to include is psa/crypto.h.
  • Reorganized the API reference, grouping the elements in a more natural way.
  • Improved the cross referencing between all of the document sections, and from code snippets to API element descriptions.

Planned changes for version 1.0.x

Future versions of this specification that use a 1.0.x version will describe the same API as this specification. Any changes will not affect application compatibility and will not introduce major features. These updates are intended to add minor requirements on implementations, introduce optional definitions, make corrections, clarify potential or actual ambiguities, or improve the documentation.

These are the changes that we are currently planning to make for version 1.0.x:

  • Declare identifiers for additional cryptographic algorithms.
  • Mandate certain checks when importing some types of asymmetric keys.
  • Specify the computation of algorithm and key type values.
  • Further clarifications on API usage and implementation.

Future additions

Major additions to the API will be defined in future drafts and editions of a 1.x or 2.x version of this specification. Features that are being considered include:

  • Multi-part operations for hybrid cryptography. For example, this includes hash-and-sign for EdDSA, and hybrid encryption for ECIES.
  • A more general interface to key derivation and key exchange. This would enable an application to derive a non-extractable session key from non-extractable secrets, without leaking the intermediate material.
  • Key wrapping mechanisms to extract and import keys in an encrypted and authenticated form.
  • Key discovery mechanisms. This would enable an application to locate a key by its name or attributes.
  • Implementation capability description. This would enable an application to determine the algorithms, key types and storage lifetimes that the implementation provides.
  • An ownership and access control mechanism allowing a multi-client implementation to have privileged clients that are able to manage keys of other clients.