File crypto_compat.h

PSA cryptography module: Backward compatibility aliases.

This header declares alternative names for macro and functions. New application code should not use these names. These names may be removed in a future version of Mbed TLS.

Note

This file may not be included directly. Applications must include psa/crypto.h.

Defines

PSA_KEY_HANDLE_INIT
MBEDTLS_PSA_DEPRECATED
PSA_KEY_TYPE_GET_CURVE
PSA_KEY_TYPE_GET_GROUP
MBEDTLS_DEPRECATED_CONSTANT(type, value)
PSA_ERROR_UNKNOWN_ERROR
PSA_ERROR_OCCUPIED_SLOT
PSA_ERROR_EMPTY_SLOT
PSA_ERROR_INSUFFICIENT_CAPACITY
PSA_ERROR_TAMPERING_DETECTED
PSA_KEY_USAGE_SIGN
PSA_KEY_USAGE_VERIFY
PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE
PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg)
PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits)
PSA_BLOCK_CIPHER_BLOCK_SIZE(type)
PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE
PSA_HASH_SIZE(alg)
PSA_MAC_FINAL_SIZE(key_type, key_bits, alg)
PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN
PSA_ECC_CURVE_SECP160K1
PSA_ECC_CURVE_SECP192K1
PSA_ECC_CURVE_SECP224K1
PSA_ECC_CURVE_SECP256K1
PSA_ECC_CURVE_SECP160R1
PSA_ECC_CURVE_SECP192R1
PSA_ECC_CURVE_SECP224R1
PSA_ECC_CURVE_SECP256R1
PSA_ECC_CURVE_SECP384R1
PSA_ECC_CURVE_SECP521R1
PSA_ECC_CURVE_SECP160R2
PSA_ECC_CURVE_SECT163K1
PSA_ECC_CURVE_SECT233K1
PSA_ECC_CURVE_SECT239K1
PSA_ECC_CURVE_SECT283K1
PSA_ECC_CURVE_SECT409K1
PSA_ECC_CURVE_SECT571K1
PSA_ECC_CURVE_SECT163R1
PSA_ECC_CURVE_SECT193R1
PSA_ECC_CURVE_SECT233R1
PSA_ECC_CURVE_SECT283R1
PSA_ECC_CURVE_SECT409R1
PSA_ECC_CURVE_SECT571R1
PSA_ECC_CURVE_SECT163R2
PSA_ECC_CURVE_SECT193R2
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_SECP_K1
PSA_ECC_CURVE_SECP_R1
PSA_ECC_CURVE_SECP_R2
PSA_ECC_CURVE_SECT_K1
PSA_ECC_CURVE_SECT_R1
PSA_ECC_CURVE_SECT_R2
PSA_ECC_CURVE_BRAINPOOL_P_R1
PSA_ECC_CURVE_MONTGOMERY
PSA_DH_GROUP_FFDHE2048
PSA_DH_GROUP_FFDHE3072
PSA_DH_GROUP_FFDHE4096
PSA_DH_GROUP_FFDHE6144
PSA_DH_GROUP_FFDHE8192
PSA_DH_GROUP_RFC7919
PSA_DH_GROUP_CUSTOM
PSA_ALG_ARC4
PSA_ALG_CHACHA20
PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH(aead_alg)
PSA_ALG_AEAD_WITH_TAG_LENGTH(aead_alg, tag_length)
PSA_AEAD_TAG_LENGTH_1_ARG(alg)

The tag size for an AEAD algorithm, in bytes.

Parameters

  • alg – An AEAD algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).

Returns

The tag size for the specified algorithm. If the AEAD algorithm does not have an identified tag that can be distinguished from the rest of the ciphertext, return 0. If the AEAD algorithm is not recognized, return 0.

PSA_AEAD_ENCRYPT_OUTPUT_SIZE_2_ARG(alg, plaintext_length)

The maximum size of the output of psa_aead_encrypt(), in bytes.

If the size of the ciphertext buffer is at least this large, it is guaranteed that psa_aead_encrypt() will not fail due to an insufficient buffer size. Depending on the algorithm, the actual size of the ciphertext may be smaller.

Warning

This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects.

Parameters

  • alg – An AEAD algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).

  • plaintext_length – Size of the plaintext in bytes.

Returns

The AEAD ciphertext size for the specified algorithm. If the AEAD algorithm is not recognized, return 0.

PSA_AEAD_DECRYPT_OUTPUT_SIZE_2_ARG(alg, ciphertext_length)

The maximum size of the output of psa_aead_decrypt(), in bytes.

If the size of the plaintext buffer is at least this large, it is guaranteed that psa_aead_decrypt() will not fail due to an insufficient buffer size. Depending on the algorithm, the actual size of the plaintext may be smaller.

Warning

This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects.

Parameters

  • alg – An AEAD algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).

  • ciphertext_length – Size of the plaintext in bytes.

Returns

The AEAD ciphertext size for the specified algorithm. If the AEAD algorithm is not recognized, return 0.

PSA_AEAD_UPDATE_OUTPUT_SIZE_2_ARG(alg, input_length)

A sufficient output buffer size for psa_aead_update().

If the size of the output buffer is at least this large, it is guaranteed that psa_aead_update() will not fail due to an insufficient buffer size. The actual size of the output may be smaller in any given call.

Warning

This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects.

Parameters

  • alg – An AEAD algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).

  • input_length – Size of the input in bytes.

Returns

A sufficient output buffer size for the specified algorithm. If the AEAD algorithm is not recognized, return 0.

PSA_AEAD_FINISH_OUTPUT_SIZE_1_ARG(alg)

A sufficient ciphertext buffer size for psa_aead_finish().

If the size of the ciphertext buffer is at least this large, it is guaranteed that psa_aead_finish() will not fail due to an insufficient ciphertext buffer size. The actual size of the output may be smaller in any given call.

Parameters

  • alg – An AEAD algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).

Returns

A sufficient ciphertext buffer size for the specified algorithm. If the AEAD algorithm is not recognized, return 0.

PSA_AEAD_VERIFY_OUTPUT_SIZE_1_ARG(alg)

A sufficient plaintext buffer size for psa_aead_verify().

If the size of the plaintext buffer is at least this large, it is guaranteed that psa_aead_verify() will not fail due to an insufficient plaintext buffer size. The actual size of the output may be smaller in any given call.

Parameters

  • alg – An AEAD algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).

Returns

A sufficient plaintext buffer size for the specified algorithm. If the AEAD algorithm is not recognized, return 0.

Typedefs

typedef mbedtls_svc_key_id_t psa_key_handle_t
MBEDTLS_PSA_DEPRECATED size_t mbedtls_deprecated_size_t
MBEDTLS_PSA_DEPRECATED psa_status_t mbedtls_deprecated_psa_status_t
MBEDTLS_PSA_DEPRECATED psa_key_usage_t mbedtls_deprecated_psa_key_usage_t
MBEDTLS_PSA_DEPRECATED psa_ecc_family_t mbedtls_deprecated_psa_ecc_family_t
MBEDTLS_PSA_DEPRECATED psa_dh_family_t mbedtls_deprecated_psa_dh_family_t
MBEDTLS_PSA_DEPRECATED psa_ecc_family_t psa_ecc_curve_t
MBEDTLS_PSA_DEPRECATED psa_dh_family_t psa_dh_group_t
MBEDTLS_PSA_DEPRECATED psa_algorithm_t mbedtls_deprecated_psa_algorithm_t

Functions

static inline int psa_key_handle_is_null(psa_key_handle_t handle)

Check whether a handle is null.

Parameters

handle – Handle

Returns

Non-zero if the handle is null, zero otherwise.

static inline MBEDTLS_PSA_DEPRECATED psa_status_t psa_asymmetric_sign (psa_key_handle_t key, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, uint8_t *signature, size_t signature_size, size_t *signature_length)
static inline MBEDTLS_PSA_DEPRECATED psa_status_t psa_asymmetric_verify (psa_key_handle_t key, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, const uint8_t *signature, size_t signature_length)
psa_status_t psa_open_key(mbedtls_svc_key_id_t key, psa_key_handle_t *handle)

Open a handle to an existing persistent key.

Open a handle to a persistent key. A key is persistent if it was created with a lifetime other than PSA_KEY_LIFETIME_VOLATILE. A persistent key always has a nonzero key identifier, set with psa_set_key_id() when creating the key. Implementations may provide additional pre-provisioned keys that can be opened with psa_open_key(). Such keys have an application key identifier in the vendor range, as documented in the description of psa_key_id_t.

The application must eventually close the handle with psa_close_key() or psa_destroy_key() to release associated resources. If the application dies without calling one of these functions, the implementation should perform the equivalent of a call to psa_close_key().

Some implementations permit an application to open the same key multiple times. If this is successful, each call to psa_open_key() will return a different key handle.

Note

This API is not part of the PSA Cryptography API Release 1.0.0 specification. It was defined in the 1.0 Beta 3 version of the specification but was removed in the 1.0.0 released version. This API is kept for the time being to not break applications relying on it. It is not deprecated yet but will be in the near future.

Note

Applications that rely on opening a key multiple times will not be portable to implementations that only permit a single key handle to be opened. See also :ref:`key-handles`.

Parameters

  • key – The persistent identifier of the key.

  • handle – [out] On success, a handle to the key.

Return values

  • PSA_SUCCESS – Success. The application can now use the value of *handle to access the key.

  • PSA_ERROR_INSUFFICIENT_MEMORY – The implementation does not have sufficient resources to open the key. This can be due to reaching an implementation limit on the number of open keys, the number of open key handles, or available memory.

  • PSA_ERROR_DOES_NOT_EXIST – There is no persistent key with key identifier key.

  • PSA_ERROR_INVALID_ARGUMENT – key is not a valid persistent key identifier.

  • PSA_ERROR_NOT_PERMITTED – The specified key exists, but the application does not have the permission to access it. Note that this specification does not define any way to create such a key, but it may be possible through implementation-specific means.

  • PSA_ERROR_COMMUNICATION_FAILURE –

  • PSA_ERROR_CORRUPTION_DETECTED –

  • PSA_ERROR_STORAGE_FAILURE –

  • PSA_ERROR_DATA_INVALID –

  • PSA_ERROR_DATA_CORRUPT –

  • PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_close_key(psa_key_handle_t handle)

Close a key handle.

If the handle designates a volatile key, this will destroy the key material and free all associated resources, just like psa_destroy_key().

If this is the last open handle to a persistent key, then closing the handle will free all resources associated with the key in volatile memory. The key data in persistent storage is not affected and can be opened again later with a call to psa_open_key().

Closing the key handle makes the handle invalid, and the key handle must not be used again by the application.

Note

This API is not part of the PSA Cryptography API Release 1.0.0 specification. It was defined in the 1.0 Beta 3 version of the specification but was removed in the 1.0.0 released version. This API is kept for the time being to not break applications relying on it. It is not deprecated yet but will be in the near future.

Note

If the key handle was used to set up an active :ref:`multipart operation <multipart-operations>`, then closing the key handle can cause the multipart operation to fail. Applications should maintain the key handle until after the multipart operation has finished.

Parameters

handle – The key handle to close. If this is 0, do nothing and return PSA_SUCCESS.

Return values

  • PSA_SUCCESS – handle was a valid handle or 0. It is now closed.

  • PSA_ERROR_INVALID_HANDLE – handle is not a valid handle nor 0.

  • PSA_ERROR_COMMUNICATION_FAILURE –

  • PSA_ERROR_CORRUPTION_DETECTED –

  • PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.