Changes to the API

Document change history

This section provides the detailed changes made between published version of the document.

Changes between 1.0.0 and 1.0.1

Changes to the API

Clarifications and fixes

  • Provided citation references for all cryptographic algorithms in the specification.

  • Provided precise key size information for all key types.

  • Permitted implementations to store and export long HMAC keys in hashed form.

  • Provided details for initialization vectors in all unauthenticated cipher algorithms.

  • Provided details for nonces in all AEAD algorithms.

  • Clarified the input steps for HKDF.

  • Provided details of signature algorithms, include requirements when using with psa_sign_hash() and psa_verify_hash().

  • Provided details of key agreement algorithms, and how to use them.

  • Aligned terminology relating to key policies, to clarify the combination of the usage flags and permitted algorithm in the policy.

  • Clarified the use of the individual key attributes for all of the key creation functions.

  • Restructured the description for psa_key_derivation_output_key(), to clarify the handling of the excess bits in ECC key generation when needing a string of bits whose length is not a multiple of 8.

  • Referenced the correct buffer size macros for psa_export_key().

  • Removed the use of the PSA_ERROR_DOES_NOT_EXIST error.

  • Clarified concurrency rules.

  • Document that psa_key_derivation_output_key() does not return PSA_ERROR_NOT_PERMITTED if the secret input is the result of a key agreement. This matches what was already documented for PSA_KEY_DERIVATION_INPUT_SECRET.

  • Relax the requirement to use the defined key derivation methods in psa_key_derivation_output_key(): implementation-specific KDF algorithms can use implementation-defined methods to derive the key material.

Other changes

  • Provided a glossary of terms.

  • Provided a table of references.

  • Restructured the Key management reference chapter.

    • Moved individual attribute types, values and accessor functions into their own sections.

    • Placed permitted algorithms and usage flags into Key policies.

    • Moved most introductory material from the Functionality overview into the relevant API sections.

Changes between 1.0 beta 3 and 1.0.0

Changes to the API


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

Changes between 1.0 beta 2 and 1.0 beta 3

Changes to the API


  • 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 1 and 1.0 beta 2

Changes to the API


  • psa_key_agreement(): document alg parameter.

Other changes

  • Document formatting improvements.

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.