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¶
Fix the example implementation of
PSA_ALG_KEY_AGREEMENT_GET_BASE()
andPSA_ALG_KEY_AGREEMENT_GET_KDF()
in Example macro implementations, to give correct results for key agreements combined with PBKDF2.Remove the dependency on the underlying hash algorithm in definition of HMAC keys, and their behavior on import and export. Transferred the responsibility for truncating over-sized HMAC keys to the application. See
PSA_KEY_TYPE_HMAC
.Rewrite the description of
PSA_ALG_CTR
, to clarify how to use the API to set the appropriate IV for different application use cases.
E.1.2. Changes between 1.1.2 and 1.2.0¶
Changes to the API¶
Added
psa_key_agreement()
for standalone key agreement that outputs to a new key object. Also addedPSA_ALG_IS_STANDALONE_KEY_AGREEMENT()
as a synonym forPSA_ALG_IS_RAW_KEY_AGREEMENT()
.Added support for the XChaCha20 cipher and XChaCha20-Poly1305 AEAD algorithms. See
PSA_KEY_TYPE_XCHACHA20
andPSA_ALG_XCHACHA20_POLY1305
.Added support for zigbee Specification [ZIGBEE] cryptographic algorithms. See
PSA_ALG_AES_MMO_ZIGBEE
andPSA_ALG_CCM_STAR_NO_TAG
.Defined key derivation algorithms based on the Counter mode recommendations in NIST Special Publication 800-108r1: Recommendation for Key Derivation Using Pseudorandom Functions [SP800-108]. See
PSA_ALG_SP800_108_COUNTER_HMAC()
andPSA_ALG_SP800_108_COUNTER_CMAC
.Added support for TLS 1.2 ECJPAKE-to-PMS key-derivation. See
PSA_ALG_TLS12_ECJPAKE_TO_PMS
.Changed the policy for
psa_key_derivation_verify_bytes()
andpsa_key_derivation_verify_key()
, so that these functions are also permitted when an input key has thePSA_KEY_USAGE_DERIVE
usage flag.Removed the special treatment of
PSA_ERROR_INVALID_SIGNATURE
for key derivation operations. A verification failure inpsa_key_derivation_verify_bytes()
andpsa_key_derivation_verify_key()
now puts the operation into an error state.
Clarifications and fixes¶
Clarified the behavior of a key derivation operation when there is insufficient capacity for a call to
psa_key_derivation_output_bytes()
,psa_key_derivation_output_key()
,psa_key_derivation_verify_bytes()
, orpsa_key_derivation_verify_key()
.Reserved the value
0
for most enum-like integral types.Changed terminology for clarification: a ‘raw key agreement’ algorithm is now a ‘standalone key agreement’, and a ‘full key agreement’ is a ‘combined key agreement’.
E.1.3. Changes between 1.1.1 and 1.1.2¶
Clarifications and fixes¶
Clarified the requirements on the
hash
parameter in thepsa_sign_hash()
andpsa_verify_hash()
functions.Explicitly described the handling of input and output in
psa_cipher_update()
, consistent with the documentation ofpsa_aead_update()
.Clarified the behavior of operation objects following a call to a setup function. Provided a diagram to illustrate multi-part operation states.
Clarified the key policy requirement for
PSA_ALG_ECDSA_ANY
.Clarified
PSA_KEY_USAGE_EXPORT
: “it permits moving a key outside of its current security boundary”. This improves understanding of why it is not only required forpsa_export_key()
, but can also be required forpsa_copy_key()
in some situations.
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¶
Extended
PSA_ALG_TLS12_PSK_TO_MS
to support TLS cipher suites that mix a key exchange with a pre-shared key.Added a new key derivation input step
PSA_KEY_DERIVATION_INPUT_OTHER_SECRET
.Added new algorithm families
PSA_ALG_HKDF_EXTRACT
andPSA_ALG_HKDF_EXPAND
for protocols that require the two parts of HKDF separately.
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¶
Relaxation when a raw key agreement is used as a key’s permitted-algorithm policy. This now also permits the key agreement to be combined with any key derivation algorithm. See
PSA_ALG_FFDH
andPSA_ALG_ECDH
.Provide wildcard permitted-algorithm polices for MAC and AEAD that can specify a minimum MAC or tag length. The following elements are added to the API:
Added support for password-hashing and key-stretching algorithms, as key derivation operations.
Added key types
PSA_KEY_TYPE_PASSWORD
,PSA_KEY_TYPE_PASSWORD_HASH
andPSA_KEY_TYPE_PEPPER
, to support use of these new types of algorithm.Add key derivation input steps
PSA_KEY_DERIVATION_INPUT_PASSWORD
andPSA_KEY_DERIVATION_INPUT_COST
.Added
psa_key_derivation_input_integer()
to support numerical inputs to a key derivation operation.Added functions
psa_key_derivation_verify_bytes()
andpsa_key_derivation_verify_key()
to compare derivation output data within the cryptoprocessor.Added usage flag
PSA_KEY_USAGE_VERIFY_DERIVATION
for using keys with the new verification functions.Modified the description of existing key derivation APIs to enable the use of key derivation functionality.
Added algorithms
PSA_ALG_PBKDF2_HMAC()
andPSA_ALG_PBKDF2_AES_CMAC_PRF_128
to implement the PBKDF2 password-hashing algorithm.Add support for twisted Edwards Elliptic curve keys, and the associated EdDSA signature algorithms. The following elements are added to the API:
Added an identifier for
PSA_KEY_TYPE_ARIA
.Added
PSA_ALG_RSA_PSS_ANY_SALT()
, which creates the same signatures asPSA_ALG_RSA_PSS()
, but permits any salt length when verifying a signature. Also added the helper macrosPSA_ALG_IS_RSA_PSS_ANY_SALT()
andPSA_ALG_IS_RSA_PSS_STANDARD_SALT()
, and extendedPSA_ALG_IS_RSA_PSS()
to detect both variants of the RSA-PSS algorithm.
Clarifications and fixes¶
Described the use of header files and the general API conventions. See Library conventions.
Added details for SHA-512/224 to the hash suspend state. See Hash suspend state.
Removed ambiguities from support macros that provide buffer sizes, and improved consistency of parameter domain definition.
Clarified the length of salt used for creating
PSA_ALG_RSA_PSS()
signatures, and that verification requires the same length of salt in the signature.Documented the use of
PSA_ERROR_INVALID_ARGUMENT
when the input data to an operation exceeds the limit specified by the algorithm.Clarified how the
PSA_ALG_RSA_OAEP()
algorithm uses the hash algorithm parameter.Fixed error in
psa_key_derivation_setup()
documentation: combined key agreement and key derivation algorithms are valid for the Crypto API.Added and clarified documentation for error conditions across the API.
Clarified the distinction between
PSA_ALG_IS_HASH_AND_SIGN()
andPSA_ALG_IS_SIGN_HASH()
.Clarified the behavior of
PSA_ALG_IS_HASH_AND_SIGN()
with a wildcard algorithm policy parameter.Documented the use of
PSA_ALG_RSA_PKCS1V15_SIGN_RAW
with thePSA_ALG_RSA_PKCS1V15_SIGN
(
PSA_ALG_ANY_HASH
)
wildcard policy.Clarified the way that
PSA_ALG_CCM
determines the value of the CCM configuration parameter L. Clarified that nonces generated bypsa_aead_generate_nonce()
can be shorter than the default nonce length provided byPSA_AEAD_NONCE_LENGTH()
.
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¶
Added subtypes
psa_key_persistence_t
andpsa_key_location_t
for key lifetimes, and defined standard values for these attributes.Added identifiers for
PSA_ALG_SM3
andPSA_KEY_TYPE_SM4
.
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()
andpsa_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 of8
.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 returnPSA_ERROR_NOT_PERMITTED
if the secret input is the result of a key agreement. This matches what was already documented forPSA_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¶
Added
PSA_CRYPTO_API_VERSION_MAJOR
andPSA_CRYPTO_API_VERSION_MINOR
to report the Crypto API version.Removed
PSA_ALG_GMAC
algorithm identifier.Removed internal implementation macros from the API specification:
PSA_AEAD_TAG_LENGTH_OFFSET
PSA_ALG_AEAD_FROM_BLOCK_FLAG
PSA_ALG_AEAD_TAG_LENGTH_MASK
PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE
PSA_ALG_CATEGORY_AEAD
PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION
PSA_ALG_CATEGORY_CIPHER
PSA_ALG_CATEGORY_HASH
PSA_ALG_CATEGORY_KEY_AGREEMENT
PSA_ALG_CATEGORY_KEY_DERIVATION
PSA_ALG_CATEGORY_MAC
PSA_ALG_CATEGORY_MASK
PSA_ALG_CATEGORY_SIGN
PSA_ALG_CIPHER_FROM_BLOCK_FLAG
PSA_ALG_CIPHER_MAC_BASE
PSA_ALG_CIPHER_STREAM_FLAG
PSA_ALG_DETERMINISTIC_ECDSA_BASE
PSA_ALG_ECDSA_BASE
PSA_ALG_ECDSA_IS_DETERMINISTIC
PSA_ALG_HASH_MASK
PSA_ALG_HKDF_BASE
PSA_ALG_HMAC_BASE
PSA_ALG_IS_KEY_DERIVATION_OR_AGREEMENT
PSA_ALG_IS_VENDOR_DEFINED
PSA_ALG_KEY_AGREEMENT_MASK
PSA_ALG_KEY_DERIVATION_MASK
PSA_ALG_MAC_SUBCATEGORY_MASK
PSA_ALG_MAC_TRUNCATION_MASK
PSA_ALG_RSA_OAEP_BASE
PSA_ALG_RSA_PKCS1V15_SIGN_BASE
PSA_ALG_RSA_PSS_BASE
PSA_ALG_TLS12_PRF_BASE
PSA_ALG_TLS12_PSK_TO_MS_BASE
PSA_ALG_VENDOR_FLAG
PSA_BITS_TO_BYTES
PSA_BYTES_TO_BITS
PSA_ECDSA_SIGNATURE_SIZE
PSA_HMAC_MAX_HASH_BLOCK_SIZE
PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE
PSA_KEY_EXPORT_DSA_KEY_PAIR_MAX_SIZE
PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE
PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE
PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE
PSA_KEY_EXPORT_RSA_KEY_PAIR_MAX_SIZE
PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE
PSA_KEY_TYPE_CATEGORY_FLAG_PAIR
PSA_KEY_TYPE_CATEGORY_KEY_PAIR
PSA_KEY_TYPE_CATEGORY_MASK
PSA_KEY_TYPE_CATEGORY_PUBLIC_KEY
PSA_KEY_TYPE_CATEGORY_RAW
PSA_KEY_TYPE_CATEGORY_SYMMETRIC
PSA_KEY_TYPE_DH_GROUP_MASK
PSA_KEY_TYPE_DH_KEY_PAIR_BASE
PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE
PSA_KEY_TYPE_ECC_CURVE_MASK
PSA_KEY_TYPE_ECC_KEY_PAIR_BASE
PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE
PSA_KEY_TYPE_IS_VENDOR_DEFINED
PSA_KEY_TYPE_VENDOR_FLAG
PSA_MAC_TRUNCATED_LENGTH
PSA_MAC_TRUNCATION_OFFSET
PSA_ROUND_UP_TO_MULTIPLE
PSA_RSA_MINIMUM_PADDING_SIZE
PSA_VENDOR_ECC_MAX_CURVE_BITS
PSA_VENDOR_RSA_MAX_KEY_BITS
Remove the definition of implementation-defined macros from the specification, and clarified the implementation requirements for these macros in Implementation-specific macros.
Macros with implementation-defined values are indicated by
/* implementation-defined value */
in the API prototype. The implementation must provide the implementation.Macros for algorithm and key type construction and inspection have specification-defined values. This is indicated by
/* specification-defined value */
in the API prototype. Example definitions of these macros is provided in Example macro implementations.
Changed the semantics of multi-part operations.
Formalize the standard pattern for multi-part operations.
Require all errors to result in an error state, requiring a call to
psa_xxx_abort()
to reset the object.Define behavior in illegal and impossible operation states, and for copying and reusing operation objects.
Although the API signatures have not changed, this change requires modifications to application flows that handle error conditions in multi-part operations.
Merge the key identifier and key handle concepts in the API.
Replaced all references to key handles with key identifiers, or something similar.
Replaced all uses of
psa_key_handle_t
withpsa_key_id_t
in the API, and removes thepsa_key_handle_t
type.Removed
psa_open_key
andpsa_close_key
.Added
PSA_KEY_ID_NULL
for the never valid zero key identifier.Document rules related to destroying keys whilst in use.
Added the
PSA_KEY_USAGE_CACHE
usage flag and the relatedpsa_purge_key()
API.Added clarification about caching keys to non-volatile memory.
Renamed
PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN
toPSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE
.Relax definition of implementation-defined types.
This is indicated in the specification by
/* implementation-defined type */
in the type definition.The specification only defines the name of implementation-defined types, and does not require that the implementation is a C struct.
Zero-length keys are not permitted. Attempting to create one will now result in an error.
Relax the constraints on inputs to key derivation:
psa_key_derivation_input_bytes()
can be used for secret input steps. This is necessary if a zero-length input is required by the application.psa_key_derivation_input_key()
can be used for non-secret input steps.
Multi-part cipher operations now require that the IV is passed using
psa_cipher_set_iv()
, the option to provide this as part of the input topsa_cipher_update()
has been removed.The format of the output from
psa_cipher_encrypt()
, and input topsa_cipher_decrypt()
, is documented.Support macros to calculate the size of output buffers, IVs and nonces.
Macros to calculate a key and/or algorithm specific result are provided for all output buffers. The new macros are:
Macros that evaluate to a maximum type-independent buffer size are provided. The new macros are:
AEAD output buffer size macros are now parameterized on the key type as well as the algorithm:
Some existing macros have been renamed to ensure that the name of the support macros are consistent. The following macros have been renamed:
PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH()
→PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG()
PSA_ALG_AEAD_WITH_TAG_LENGTH()
→PSA_ALG_AEAD_WITH_SHORTENED_TAG()
PSA_KEY_EXPORT_MAX_SIZE()
→PSA_EXPORT_KEY_OUTPUT_SIZE()
PSA_HASH_SIZE()
→PSA_HASH_LENGTH()
PSA_MAC_FINAL_SIZE()
→PSA_MAC_LENGTH()
PSA_BLOCK_CIPHER_BLOCK_SIZE()
→PSA_BLOCK_CIPHER_BLOCK_LENGTH()
PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE
→PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE
Documentation of the macros and of related APIs has been updated to reference the related API elements.
Provide hash-and-sign operations as well as sign-the-hash operations. The API for asymmetric signature has been changed to clarify the use of the new functions.
The existing asymmetric signature API has been renamed to clarify that this is for signing a hash that is already computed:
PSA_KEY_USAGE_SIGN
→PSA_KEY_USAGE_SIGN_HASH
PSA_KEY_USAGE_VERIFY
→PSA_KEY_USAGE_VERIFY_HASH
psa_asymmetric_sign()
→psa_sign_hash()
psa_asymmetric_verify()
→psa_verify_hash()
New APIs added to provide the complete message signing operation:
New Support macros to identify which algorithms can be used in which signing API:
Renamed support macros that apply to both signing APIs:
PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE()
→PSA_SIGN_OUTPUT_SIZE()
PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE
→PSA_SIGNATURE_MAX_SIZE
The usage flag values have been changed, including for
PSA_KEY_USAGE_DERIVE
.
Restructure
psa_key_type_t
and reassign all key type values.psa_key_type_t
changes from 32-bit to 16-bit integer.Reassigned the key type categories.
Add a parity bit to the key type to ensure that valid key type values differ by at least 2 bits.
16-bit elliptic curve ids (
psa_ecc_curve_t
) replaced by 8-bit ECC curve family ids (psa_ecc_family_t
). 16-bit Diffie-Hellman group ids (psa_dh_group_t
) replaced by 8-bit DH group family ids (psa_dh_family_t
).These ids are no longer related to the IANA Group Registry specification.
The new key type values do not encode the key size for ECC curves or DH groups. The key bit size from the key attributes identify a specific ECC curve or DH group within the family.
The following macros have been removed:
PSA_DH_GROUP_FFDHE2048
PSA_DH_GROUP_FFDHE3072
PSA_DH_GROUP_FFDHE4096
PSA_DH_GROUP_FFDHE6144
PSA_DH_GROUP_FFDHE8192
PSA_ECC_CURVE_BITS
PSA_ECC_CURVE_BRAINPOOL_P256R1
PSA_ECC_CURVE_BRAINPOOL_P384R1
PSA_ECC_CURVE_BRAINPOOL_P512R1
PSA_ECC_CURVE_CURVE25519
PSA_ECC_CURVE_CURVE448
PSA_ECC_CURVE_SECP160K1
PSA_ECC_CURVE_SECP160R1
PSA_ECC_CURVE_SECP160R2
PSA_ECC_CURVE_SECP192K1
PSA_ECC_CURVE_SECP192R1
PSA_ECC_CURVE_SECP224K1
PSA_ECC_CURVE_SECP224R1
PSA_ECC_CURVE_SECP256K1
PSA_ECC_CURVE_SECP256R1
PSA_ECC_CURVE_SECP384R1
PSA_ECC_CURVE_SECP521R1
PSA_ECC_CURVE_SECT163K1
PSA_ECC_CURVE_SECT163R1
PSA_ECC_CURVE_SECT163R2
PSA_ECC_CURVE_SECT193R1
PSA_ECC_CURVE_SECT193R2
PSA_ECC_CURVE_SECT233K1
PSA_ECC_CURVE_SECT233R1
PSA_ECC_CURVE_SECT239K1
PSA_ECC_CURVE_SECT283K1
PSA_ECC_CURVE_SECT283R1
PSA_ECC_CURVE_SECT409K1
PSA_ECC_CURVE_SECT409R1
PSA_ECC_CURVE_SECT571K1
PSA_ECC_CURVE_SECT571R1
PSA_KEY_TYPE_GET_CURVE
PSA_KEY_TYPE_GET_GROUP
The following macros have been added:
The following macros have new values:
The following macros with specification-defined values have new example implementations:
Add ECC family
PSA_ECC_FAMILY_FRP
for the FRP256v1 curve.Restructure
psa_algorithm_t
encoding, to increase consistency across algorithm categories.Algorithms that include a hash operation all use the same structure to encode the hash algorithm. The following
PSA_ALG_XXXX_GET_HASH()
macros have all been replaced by a single macroPSA_ALG_GET_HASH()
:PSA_ALG_HKDF_GET_HASH()
PSA_ALG_HMAC_GET_HASH()
PSA_ALG_RSA_OAEP_GET_HASH()
PSA_ALG_SIGN_GET_HASH()
PSA_ALG_TLS12_PRF_GET_HASH()
PSA_ALG_TLS12_PSK_TO_MS_GET_HASH()
Stream cipher algorithm macros have been removed; the key type indicates which cipher to use. Instead of
PSA_ALG_ARC4
andPSA_ALG_CHACHA20
, usePSA_ALG_STREAM_CIPHER
.
All of the other
PSA_ALG_XXX
macros have updated values or updated example implementations.The following macros have new values:
The following macros with specification-defined values have new example implementations:
Added ECB block cipher mode, with no padding, as
PSA_ALG_ECB_NO_PADDING
.Add functions to suspend and resume hash operations:
psa_hash_suspend()
halts the current operation and outputs a hash suspend state.psa_hash_resume()
continues a previously suspended hash operation.
The format of the hash suspend state is documented in Hash suspend state, and supporting macros are provided for using the Crypto API:
Complement
PSA_ERROR_STORAGE_FAILURE
with new error codesPSA_ERROR_DATA_CORRUPT
andPSA_ERROR_DATA_INVALID
. These permit an implementation to distinguish different causes of failure when reading from key storage.Added input step
PSA_KEY_DERIVATION_INPUT_CONTEXT
for key derivation, supporting obvious mapping from the step identifiers to common KDF constructions.
Clarifications¶
Clarified rules regarding modification of parameters in concurrent environments.
Guarantee that
psa_destroy_key
(
PSA_KEY_ID_NULL
)
always returnsPSA_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_ERROR
→PSA_ERROR_GENERIC_ERROR
PSA_ERROR_OCCUPIED_SLOT
→PSA_ERROR_ALREADY_EXISTS
PSA_ERROR_EMPTY_SLOT
→PSA_ERROR_DOES_NOT_EXIST
PSA_ERROR_INSUFFICIENT_CAPACITY
→PSA_ERROR_INSUFFICIENT_DATA
PSA_ERROR_TAMPERING_DETECTED
→PSA_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()
andpsa_copy_key()
now take an attribute structure, as a pointer topsa_key_attributes_t
, to specify key metadata. This replaces the previous method of passing arguments topsa_create_key()
or to the key material creation function or callingpsa_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 withpsa_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 alifetime
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:
psa_crypto_generator_t
→psa_key_derivation_operation_t
PSA_CRYPTO_GENERATOR_INIT
→PSA_KEY_DERIVATION_OPERATION_INIT
psa_crypto_generator_init()
→psa_key_derivation_operation_init()
PSA_GENERATOR_UNBRIDLED_CAPACITY
→PSA_KEY_DERIVATION_UNLIMITED_CAPACITY
psa_set_generator_capacity()
→psa_key_derivation_set_capacity()
psa_get_generator_capacity()
→psa_key_derivation_get_capacity()
psa_key_agreement()
→psa_key_derivation_key_agreement()
psa_generator_read()
→psa_key_derivation_output_bytes()
psa_generate_derived_key()
→psa_key_derivation_output_key()
psa_generator_abort()
→psa_key_derivation_abort()
psa_key_agreement_raw_shared_secret()
→psa_raw_key_agreement()
PSA_KDF_STEP_xxx
→PSA_KEY_DERIVATION_INPUT_xxx
PSA_xxx_KEYPAIR
→PSA_xxx_KEY_PAIR
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¶
Remove obsolete definition
PSA_ALG_IS_KEY_SELECTION
.PSA_AEAD_FINISH_OUTPUT_SIZE
: remove spurious parameterplaintext_length
.
Clarifications¶
psa_key_agreement()
: documentalg
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.