| /* |
| * Copyright (c) 2018-2019, Arm Limited. All rights reserved. |
| * |
| * SPDX-License-Identifier: BSD-3-Clause |
| * |
| */ |
| |
| #ifndef __TFM_CRYPTO_API_H__ |
| #define __TFM_CRYPTO_API_H__ |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| #include <stdint.h> |
| #include "tfm_crypto_defs.h" |
| #include "psa_crypto.h" |
| |
| /** |
| * \brief List of possible operation types supported by the TFM based |
| * implementation. This type is needed by the operation allocation, |
| * lookup and release functions. |
| * |
| */ |
| enum tfm_crypto_operation_type { |
| TFM_CRYPTO_OPERATION_NONE = 0, |
| TFM_CRYPTO_CIPHER_OPERATION = 1, |
| TFM_CRYPTO_MAC_OPERATION = 2, |
| TFM_CRYPTO_HASH_OPERATION = 3, |
| TFM_CRYPTO_KEY_POLICY = 4, |
| |
| /* Used to force the enum size */ |
| TFM_CRYPTO_OPERATION_TYPE_MAX = INT_MAX |
| }; |
| |
| /** |
| * \brief Initialise the service |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_init(void); |
| |
| /** |
| * \brief Initialise the Key module |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_init_key(void); |
| |
| /** |
| * \brief Initialise the Alloc module |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_init_alloc(void); |
| |
| /** |
| * \brief Allocate an operation object |
| * |
| * \param[in] type Type of the operation object to allocate |
| * \param[out] handle Pointer to the corresponding handle assigned |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_operation_alloc( |
| enum tfm_crypto_operation_type type, |
| uint32_t *handle); |
| /** |
| * \brief Release an operation object |
| * |
| * \param[in] handle Pointer to the handle for the release of the |
| * corresponding object |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_operation_release(uint32_t *handle); |
| |
| /** |
| * \brief Look up an operation object pointer from the corresponding handle |
| * |
| * \param[in] type Type of the operation object to look up |
| * \param[in] handle Handle to the operation object to look up |
| * \param[out] oper Double pointer to the corresponding object |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_operation_lookup( |
| enum tfm_crypto_operation_type type, |
| uint32_t handle, |
| void **oper); |
| /** |
| * \brief Import the key data in the provided key slot |
| * |
| * \param[in] key Key slot |
| * \param[in] type Key type |
| * \param[in] data Key data to import |
| * \param[in] data_length Length in bytes of the data field |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_import_key(psa_key_slot_t key, |
| psa_key_type_t type, |
| const uint8_t *data, |
| size_t data_length); |
| /** |
| * \brief Destroy the key in the provided key slot |
| * |
| * \param[in] key Key slot |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_destroy_key(psa_key_slot_t key); |
| |
| /** |
| * \brief Retrieve key information for the provided key slot |
| * |
| * \param[in] key Key slot |
| * \param[out] type Key type associated to the key slot requested |
| * \param[out] bits Length in bits of the key in the requested slot |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_get_key_information(psa_key_slot_t key, |
| psa_key_type_t *type, |
| size_t *bits); |
| /** |
| * \brief Export the key contained in the provided key slot |
| * |
| * \param[in] key Key slot |
| * \param[out] data Buffer to hold the exported key |
| * \param[in] data_size Length of the buffer pointed to by data |
| * \param[out] data_length Length of the exported key |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_export_key(psa_key_slot_t key, |
| uint8_t *data, |
| size_t data_size, |
| size_t *data_length); |
| /** |
| * \brief Export the public key contained in the provided key slot |
| * for an asymmetric key pair |
| * |
| * \param[in] key Key slot |
| * \param[out] data Buffer to hold the exported key |
| * \param[in] data_size Length of the buffer pointed to by data |
| * \param[out] data_length Length of the exported key |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_export_public_key(psa_key_slot_t key, |
| uint8_t *data, |
| size_t data_size, |
| size_t *data_length); |
| /** |
| * \brief Set the initialisation vector on the provided cipher operation |
| * |
| * \param[in] operation Cipher operation context |
| * \param[in] iv Buffer that contains the IV |
| * \param[in] iv_length Length of the provided IV |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_cipher_set_iv( |
| psa_cipher_operation_t *operation, |
| const unsigned char *iv, |
| size_t iv_length); |
| /** |
| * \brief Set the cipher operation using the provided algorithm and key slot, |
| * for encryption context |
| * |
| * \note A successful call to this function initialises a cipher operation |
| * context which will be referred using the operation parameter |
| * |
| * \param[out] operation Cipher operation context |
| * \param[in] key Key slot to bind to the cipher context |
| * \param[in] alg Algorithm to use for the cipher operation |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_cipher_encrypt_setup( |
| psa_cipher_operation_t *operation, |
| psa_key_slot_t key, |
| psa_algorithm_t alg); |
| /** |
| * \brief Set the cipher operation using the provided algorithm and key slot, |
| * for decryption context |
| * |
| * \note A successful call to this function initialises a cipher operation |
| * context which will be referred using the operation parameter |
| * |
| * \param[out] operation Cipher operation context |
| * \param[in] key Key slot to bind to the cipher context |
| * \param[in] alg Algorithm to use for the cipher operation |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_cipher_decrypt_setup( |
| psa_cipher_operation_t *operation, |
| psa_key_slot_t key, |
| psa_algorithm_t alg); |
| /** |
| * \brief Update the cipher context with a chunk of input data to create a |
| * chunk of encrypted output data (for encryption contexts), or to |
| * decrypt a chunk of encrypted input data to obtain decrypted data |
| * (for decryption contexts) |
| * |
| * \param[in/out] operation Cipher operation context |
| * \param[in] input Buffer containing input data |
| * \param[in] input_length Input length |
| * \param[out] output Buffer containing output data |
| * \param[in] output_size Size of the output buffer |
| * \param[out] output_length Size of the produced output |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_cipher_update( |
| psa_cipher_operation_t *operation, |
| const uint8_t *input, |
| size_t input_length, |
| unsigned char *output, |
| size_t output_size, |
| size_t *output_length); |
| /** |
| * \brief Finalise a cipher context flushing out any remaining block of |
| * output data |
| * |
| * \note A successful call to this function de-initialises the cipher operation |
| * context provided as parameter |
| * |
| * \param[in/out] operation Cipher operation context |
| * \param[out] output Buffer containing output data |
| * \param[in] output_size Size of the output buffer |
| * \param[out] output_length Size of the produced output |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_cipher_finish( |
| psa_cipher_operation_t *operation, |
| uint8_t *output, |
| size_t output_size, |
| size_t *output_length); |
| /** |
| * \brief Abort a cipher operation, clears the operation context provided |
| * |
| * \note A successful call to this function de-initialises the cipher operation |
| * context provided as parameter |
| * |
| * \param[in/out] operation Cipher operation context |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_cipher_abort( |
| psa_cipher_operation_t *operation); |
| /** |
| * \brief Start a hash operation with the provided algorithm |
| * |
| * \note A successful call to this function initialises a hash operation |
| * context which will be referred using the operation parameter |
| * |
| * \param[out] operation Hash operation context |
| * \param[in] alg Algorithm chosen as hash |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_hash_setup(psa_hash_operation_t *operation, |
| psa_algorithm_t alg); |
| /** |
| * \brief Add a new input chunk to the data for which the final hash value |
| * will be computed |
| * |
| * \param[in] operation Hash operation context |
| * \param[in] input Buffer containing the input data |
| * \param[in] input_length Size of the provided input data |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_hash_update(psa_hash_operation_t *operation, |
| const uint8_t *input, |
| size_t input_length); |
| /** |
| * \brief Finalise a hash context operation producing the final hash value |
| * |
| * \note A successful call to this function de-initialises the hash operation |
| * context provided as parameter |
| * |
| * \param[in/out] operation Hash operation context |
| * \param[out] hash Buffer containing hash data |
| * \param[in] hash_size Size of the hash buffer |
| * \param[out] hash_length Size of the produced hash |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_hash_finish(psa_hash_operation_t *operation, |
| uint8_t *hash, |
| size_t hash_size, |
| size_t *hash_length); |
| /** |
| * \brief Finalise a hash context operation, verifying that the final hash |
| * value matches the one provided as input |
| * |
| * \note A successful call to this function de-initialises the hash operation |
| * context provided as parameter. The hash operation is de-initialised |
| * also in case TFM_CRYPTO_ERR_PSA_ERROR_INVALID_SIGNATURE is returned |
| * |
| * \param[in/out] operation Hash operation context |
| * \param[in] hash Buffer containing the provided hash value |
| * \param[in] hash_length Size of the provided hash value |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_hash_verify(psa_hash_operation_t *operation, |
| const uint8_t *hash, |
| size_t hash_length); |
| /** |
| * \brief Abort a hash operation, clears the operation context provided |
| * |
| * \note A successful call to this function de-initialises the hash operation |
| * context provided as parameter |
| * |
| * \param[in/out] operation Hash operation context |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_hash_abort(psa_hash_operation_t *operation); |
| |
| /** |
| * \brief Start a MAC operation with the provided algorithm (for signing) |
| * |
| * \note A successful call to this function initialises a MAC operation |
| * context which will be referred using the operation parameter |
| * |
| * \param[out] operation MAC operation context |
| * \param[in] key Key slot to bind to the MAC context |
| * \param[in] alg Algorithm chosen as MAC |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_mac_sign_setup(psa_mac_operation_t *operation, |
| psa_key_slot_t key, |
| psa_algorithm_t alg); |
| /** |
| * \brief Start a MAC operation with the provided algorithm (for verifying) |
| * |
| * \note A successful call to this function initialises a MAC operation |
| * context which will be referred using the operation parameter |
| * |
| * \param[out] operation MAC operation context |
| * \param[in] key Key slot to bind to the MAC context |
| * \param[in] alg Algorithm chosen as MAC |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_mac_verify_setup( |
| psa_mac_operation_t *operation, |
| psa_key_slot_t key, |
| psa_algorithm_t alg); |
| /** |
| * \brief Adds a new input chunk to the data for which the final MAC value |
| * will be computed |
| * |
| * \param[in] operation MAC operation context |
| * \param[in] input Buffer containing the input data |
| * \param[in] input_length Size of the provided input data |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_mac_update(psa_mac_operation_t *operation, |
| const uint8_t *input, |
| size_t input_length); |
| /** |
| * \brief Finalise a MAC context operation producing the final MAC value |
| * |
| * \param[in/out] operation Mac operation context |
| * \param[out] mac Buffer containing MAC data |
| * \param[in] mac_size Size of the mac buffer |
| * \param[out] mac_length Size of the produced mac |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_mac_sign_finish(psa_mac_operation_t *operation, |
| uint8_t *mac, |
| size_t mac_size, |
| size_t *mac_length); |
| /** |
| * \brief Finalise a MAC context operation, verifying that the final MAC value |
| * matches the one provided as input |
| * |
| * \param[in/out] operation MAC operation context |
| * \param[in] mac Buffer containing the provided MAC value |
| * \param[in] mac_length Size of the provided MAC value |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_mac_verify_finish( |
| psa_mac_operation_t *operation, |
| const uint8_t *mac, |
| size_t mac_length); |
| /** |
| * \brief Abort a MAC operation, clear the operation context provided |
| * |
| * \param[in/out] operation MAC operation context |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_mac_abort(psa_mac_operation_t *operation); |
| |
| /** |
| * \brief Perform an AEAD encryption operation on input data with additional |
| * data to be authenticated, producing ciphertext in output with an |
| * appended authentication tag |
| * |
| * \param[in] key Key slot for the key |
| * \param[in] alg Algorithm to be used |
| * \param[in] nonce Pointer to a buffer holding a nonce or IV |
| * to use |
| * \param[in] nonce_length Size in bytes of the nonce or IV data |
| * \param[in] additional_data Additional information to be authenticated |
| * \param[in] additional_data_length Size in bytes of the additional data |
| * \param[in] plaintext Buffer pointing to data to be encrypted |
| * \param[in] plaintext_length Size in bytes of the plain text buffer |
| * \param[out] ciphertext Output encrypted data, with the |
| * authentication tag appended |
| * \param[in] ciphertext_size Size in bytes of the buffer to hold the |
| * cipher text plus authentication tag |
| * \param[out] ciphertext_length Size of the ciphertext plus tag produced |
| * as output |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_aead_encrypt(psa_key_slot_t key, |
| psa_algorithm_t alg, |
| const uint8_t *nonce, |
| size_t nonce_length, |
| const uint8_t *additional_data, |
| size_t additional_data_length, |
| const uint8_t *plaintext, |
| size_t plaintext_length, |
| uint8_t *ciphertext, |
| size_t ciphertext_size, |
| size_t *ciphertext_length); |
| /** |
| * \brief Perform an AEAD decryption operation on input data with additional |
| * data to be verified, producing back the original plain text in case |
| * the verification of the authentication tag is successful |
| * |
| * \param[in] key Key slot for the key |
| * \param[in] alg Algorithm to be used |
| * \param[in] nonce Pointer to a buffer holding a nonce or IV |
| * to use |
| * \param[in] nonce_length Size in bytes of the nonce or IV data |
| * \param[in] additional_data Additional information which was |
| * authenticated but not encrypted |
| * \param[in] additional_data_length Size in bytes of the additional data |
| * \param[in] ciphertext Buffer pointing to data be decrypted |
| * \param[in] ciphertext_length Size in bytes of the cipher text buffer |
| * \param[out] plaintext Buffer for decrypted output data |
| * \param[in] plaintext_size Size in bytes of the buffer to hold the |
| * plain text |
| * \param[out] plaintext_length Size of the plain text actually produced |
| * |
| * \return Return values as described in \ref tfm_crypto_err_t |
| */ |
| enum tfm_crypto_err_t tfm_crypto_aead_decrypt(psa_key_slot_t key, |
| psa_algorithm_t alg, |
| const uint8_t *nonce, |
| size_t nonce_length, |
| const uint8_t *additional_data, |
| size_t additional_data_length, |
| const uint8_t *ciphertext, |
| size_t ciphertext_length, |
| uint8_t *plaintext, |
| size_t plaintext_size, |
| size_t *plaintext_length); |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* __TFM_CRYPTO_API_H__ */ |