E. Changes to the API

E.1. Document change history

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

E.1.1. Changes between 1.2.0 and 1.2.1

Clarifications and fixes

E.1.2. Changes between 1.1.2 and 1.2.0

Changes to the API

Clarifications and fixes

E.1.3. Changes between 1.1.1 and 1.1.2

Clarifications and fixes

Other changes

  • Moved the documentation of supported key import/export formats to a separate section of the specification. See Key formats.

E.1.4. Changes between 1.1.0 and 1.1.1

Changes to the API

Other changes

  • Relicensed the document under Attribution-ShareAlike 4.0 International with a patent license derived from Apache License 2.0. See License.

  • Adopted a standard set of Adversarial models for the Security Risk Assessment. See Adversarial models.

E.1.5. Changes between 1.0.1 and 1.1.0

Changes to the API

Clarifications and fixes

Other changes

  • Add new appendix describing the encoding of algorithm identifiers and key types. See Algorithm and key type encoding.

  • Migrated cryptographic operation summaries to the start of the appropriate operation section, and out of the Functionality overview.

  • Included a Security Risk Assessment for the Crypto API.

E.1.6. 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.

  • Clarify the requirements for implementations that support concurrent execution of API calls.

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.

E.1.7. 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.

E.1.8. Changes between 1.0 beta 2 and 1.0 beta 3

Changes to the API

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

    • PSA_ERROR_UNKNOWN_ERRORPSA_ERROR_GENERIC_ERROR

    • PSA_ERROR_OCCUPIED_SLOTPSA_ERROR_ALREADY_EXISTS

    • PSA_ERROR_EMPTY_SLOTPSA_ERROR_DOES_NOT_EXIST

    • PSA_ERROR_INSUFFICIENT_CAPACITYPSA_ERROR_INSUFFICIENT_DATA

    • PSA_ERROR_TAMPERING_DETECTEDPSA_ERROR_CORRUPTION_DETECTED

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

  • Allow psa_aead_update() to buffer data.

  • New buffer size calculation macros.

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

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

  • Convert TLS1.2 KDF descriptions to multi-part key derivation.

Clarifications

  • Specify psa_generator_import_key() for most key types.

  • Clarify the behavior in various corner cases.

  • Document more error conditions.

E.1.9. 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.

E.2. Planned changes for version 1.2.x

Future versions of this specification that use a 1.2.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 might be included in a version 1.2.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.

E.3. 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.

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