interface/include/tfm_crypto_veneers.h

/*
 * Copyright (c) 2018-2019, Arm Limited. All rights reserved.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 *
 */

#ifndef __TFM_CRYPTO_VENEERS_H__
#define __TFM_CRYPTO_VENEERS_H__

#ifdef __cplusplus
extern "C" {
#endif

#include "tfm_crypto_defs.h"

#include "psa_crypto.h"

#include "crypto_psa_wrappers.h"

/**
 * \brief Import the key data in the provided key slot (veneer function)
 *
 * \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_veneer_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 (veneer function)
 *
 * \param[in] key         Key slot
 *
 * \return Return values as described in \ref tfm_crypto_err_t
 */
enum tfm_crypto_err_t tfm_crypto_veneer_destroy_key(psa_key_slot_t key);

/**
 * \brief Retrieve key information for the provided key slot (veneer function)
 *
 * \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_veneer_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 (veneer function)
 *
 * \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_veneer_export_key(psa_key_slot_t key,
                                                   uint8_t *data,
                                                   size_t data_size,
                                                   size_t *data_length);

/**
 * \brief Initialise the key policy to a default that forbids any use of the
 *        key (veneer function)
 *
 * \param[out] policy  Key policy to initialise
 *
 * \return Return values as described in \ref tfm_crypto_err_t
 */
enum tfm_crypto_err_t tfm_crypto_veneer_key_policy_init(
                                                      psa_key_policy_t *policy);

/**
 * \brief Set the permitted usage and algorithm for the provided key policy
 *        (veneer function)
 *
 * \param[out] policy  Key policy to modify
 * \param[in]  usage   Permitted usage
 * \param[in]  alg     Permitted algorithm
 *
 * \return Return values as described in \ref tfm_crypto_err_t
 */
enum tfm_crypto_err_t tfm_crypto_veneer_key_policy_set_usage(
                                                       psa_key_policy_t *policy,
                                                       psa_key_usage_t usage,
                                                       psa_algorithm_t alg);

/**
 * \brief Get the permitted usage for the provided key policy (veneer function)
 *
 * \param[in]  policy  Key policy
 * \param[out] usage   Permitted usage for this key policy
 *
 * \return Return values as described in \ref tfm_crypto_err_t
 */
enum tfm_crypto_err_t tfm_crypto_veneer_key_policy_get_usage(
                                                 const psa_key_policy_t *policy,
                                                 psa_key_usage_t *usage);

/**
 * \brief Get the permitted algorithm for the provided key policy
 *        (veneer function)
 *
 * \param[in]  policy  Key policy
 * \param[out] alg     Permitted algorithm for this key policy
 *
 * \return Return values as described in \ref tfm_crypto_err_t
 */
enum tfm_crypto_err_t tfm_crypto_veneer_key_policy_get_algorithm(
                                                 const psa_key_policy_t *policy,
                                                 psa_algorithm_t *alg);

/**
 * \brief Set the key policy for the provided key slot (veneer function)
 *
 * \param[in] key     Key slot
 * \param[in] policy  Key policy
 *
 * \return Return values as described in \ref tfm_crypto_err_t
 */
enum tfm_crypto_err_t tfm_crypto_veneer_set_key_policy(
                                                psa_key_slot_t key,
                                                const psa_key_policy_t *policy);

/**
 * \brief Get the key policy for the provided key slot (veneer function)
 *
 * \param[in]  key     Key slot
 * \param[out] policy  Key policy
 *
 * \return Return values as described in \ref tfm_crypto_err_t
 */
enum tfm_crypto_err_t tfm_crypto_veneer_get_key_policy(
                                                      psa_key_slot_t key,
                                                      psa_key_policy_t *policy);

/**
 * \brief Set the lifetime for the provided key slot (veneer function)
 *
 * \param[in] key       Key slot
 * \param[in] lifetime  Lifetime value
 *
 * \return Return values as described in \ref tfm_crypto_err_t
 */
enum tfm_crypto_err_t tfm_crypto_veneer_set_key_lifetime(
                                                   psa_key_slot_t key,
                                                   psa_key_lifetime_t lifetime);

/**
 * \brief Get the lifetime for the provided key slot (veneer function)
 *
 * \param[in]  key       Key slot
 * \param[out] lifetime  Lifetime value
 *
 * \return Return values as described in \ref tfm_crypto_err_t
 */
enum tfm_crypto_err_t tfm_crypto_veneer_get_key_lifetime(
                                                  psa_key_slot_t key,
                                                  psa_key_lifetime_t *lifetime);

/**
 * \brief Set the initialisation vector on the provided cipher operation (veneer
 *        function)
 *
 * \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_veneer_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 (veneer function)
 *
 * \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_veneer_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 (veneer function)
 *
 * \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_veneer_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) (veneer function)
 *
 * \param[in]  operation Cipher operation context
 * \param[in]  input_s   Pointer to the struct containing input parameters
 * \param[out] output_s  Pointer to the struct containing output parameters
 *
 * \return Return values as described in \ref tfm_crypto_err_t
 */
enum tfm_crypto_err_t tfm_crypto_veneer_cipher_update(
                                     psa_cipher_operation_t *operation,
                                     struct psa_cipher_update_input *input_s,
                                     struct psa_cipher_update_output *output_s);
/**
 * \brief Finalise a cipher context flushing out any remaining block of
 *        output data (veneer function)
 *
 * \note A successful call to this function releases 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_veneer_cipher_finish(
                                              psa_cipher_operation_t *operation,
                                              uint8_t *output,
                                              size_t output_size,
                                              size_t *output_length);
/**
 * \brief Abort a cipher operation, clear the operation context provided
 *        (veneer function)
 *
 * \note A successful call to this function releases 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_veneer_cipher_abort(
                                             psa_cipher_operation_t *operation);
/**
 * \brief Setup a hash operation with the provided algorithm (veneer function)
 *
 * \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_veneer_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 (veneer function)
 *
 * \param[in,out] 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_veneer_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
 *        (veneer function)
 *
 * \note A successful call to this function releases 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_veneer_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 (veneer function)
 *
 * \note A successful call to this function releases the hash operation
 *       context provided as parameter. The hash operation is released
 *       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_veneer_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
 *        (veneer function)
 *
 * \note A successful call to this function releases 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_veneer_hash_abort(
                                               psa_hash_operation_t *operation);
/**
 * \brief Start a MAC operation with the provided algorithm (for signing)
 *        (veneer function)
 *
 * \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_veneer_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)
 *        (veneer function)
 *
 * \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_veneer_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 (veneer function)
 *
 * \param[in,out] 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_veneer_mac_update(
                                                 psa_mac_operation_t *operation,
                                                 const uint8_t *input,
                                                 size_t input_length);

/**
 * \brief Finalises a MAC context operation producing the final MAC value
 *        (veneer function)
 *
 * \note A successful call to this function releases the MAC operation
 *       context provided as parameter
 *
 * \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_veneer_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 (veneer function)
 *
 * \note A successful call to this function releases the MAC operation
 *       context provided as parameter. The MAC operation is released
 *       also in case TFM_CRYPTO_ERR_PSA_ERROR_INVALID_SIGNATURE is returned
 *
 * \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_veneer_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
 *        (veneer function)
 *
 * \note A successful call to this function releases the MAC operation
 *       context provided as parameter
 *
 * \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_veneer_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 (veneer function)
 *
 * \param[in]  input_s   Pointer to the struct containing input parameters
 * \param[out] output_s  Pointer to the struct containing output parameters
 *
 * \return Return values as described in \ref tfm_crypto_err_t
 */
enum tfm_crypto_err_t tfm_crypto_veneer_aead_encrypt(
                                     struct psa_aead_encrypt_input *input_s,
                                     struct psa_aead_encrypt_output *output_s);
/**
 * \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 (veneer
 *        function)
 *
 * \param[in]  input_s   Pointer to the struct containing input parameters
 * \param[out] output_s  Pointer to the struct containing output parameters
 *
 * \return Return values as described in \ref tfm_crypto_err_t
 */
enum tfm_crypto_err_t tfm_crypto_veneer_aead_decrypt(
                                     struct psa_aead_decrypt_input *input_s,
                                     struct psa_aead_decrypt_output *output_s);

#ifdef __cplusplus
}
#endif

#endif /* __TFM_CRYPTO_VENEERS_H__ */