secure_fw/partitions/crypto/tfm_crypto_api.h

/*
 * Copyright (c) 2018-2022, 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_client_struct.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_DERIVATION_OPERATION = 4,
    TFM_CRYPTO_AEAD_OPERATION = 5,

    /* Used to force the enum size */
    TFM_CRYPTO_OPERATION_TYPE_MAX = INT_MAX
};

/**
 * \brief Type associated to a function for the TF-M Crypto service
 *        API. It describes if an API is multipart related or not, i.e. and
 *        which multipart operation it requires (i.e. setup or lookup)
 */
enum tfm_crypto_function_type {
    TFM_CRYPTO_FUNCTION_TYPE_NON_MULTIPART = 0x0,
    TFM_CRYPTO_FUNCTION_TYPE_SETUP,
    TFM_CRYPTO_FUNCTION_TYPE_LOOKUP
};

/**
 * \brief Type associated to the group of a function encoding. There can be
 *        nine groups (Random, Key management, Hash, MAC, Cipher, AEAD,
 *        Asym sign, Asym encrypt, Key derivation).
 */
enum tfm_crypto_group_id {
    TFM_CRYPTO_GROUP_ID_RANDOM = 0x0,
    TFM_CRYPTO_GROUP_ID_KEY_MANAGEMENT,
    TFM_CRYPTO_GROUP_ID_HASH,
    TFM_CRYPTO_GROUP_ID_MAC,
    TFM_CRYPTO_GROUP_ID_CIPHER,
    TFM_CRYPTO_GROUP_ID_AEAD,
    TFM_CRYPTO_GROUP_ID_ASYM_SIGN,
    TFM_CRYPTO_GROUP_ID_ASYM_ENCRYPT,
    TFM_CRYPTO_GROUP_ID_KEY_DERIVATION,
};

/**
 * \brief Accessor to the API descriptor table that returns function_type of the API
 *
 * \param[in] func Function ID for the API to retrieve the associated group
 *
 * \return Return values as described in \ref enum tfm_crypto_function_type
 */
enum tfm_crypto_function_type
    get_function_type_from_descriptor(enum tfm_crypto_function_id func);

/**
 * \brief Accessor to the API descriptor table that returns function_type of the API
 *
 * \param[in] id Pointer to hold the ID of the caller
 *
 * \return Return values as described in \ref enum tfm_crypto_group_id
 */
enum tfm_crypto_group_id
    get_group_id_from_descriptor(enum tfm_crypto_function_id func);

/**
 * \brief Macro to determine the group_id corresponding to a function_id by
 *        accessing the tfm_crypto_api_descriptor table
 */
#define TFM_CRYPTO_IS_GROUP_ID(_function_id, _group_id) \
    (get_group_id_from_descriptor((_function_id)) == (_group_id))

/**
 * \brief Macro to get the function_type associated to a function_id by
 *        accessing the tfm_crypto_api_descriptor table
 */
#define TFM_CRYPTO_GET_FUNCTION_TYPE(_function_id) \
    (get_function_type_from_descriptor((_function_id)))

/**
 * \brief Initialise the service
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_init(void);

/**
 * \brief Initialise the Alloc module
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_init_alloc(void);

/**
 * \brief Returns the ID of the caller
 *
 * \param[out] id Pointer to hold the ID of the caller
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_get_caller_id(int32_t *id);

/**
 * \brief Gets key attributes from client key attributes.
 *
 * \param[in]  client_key_attr  Client key attributes
 * \param[in]  client_id        Partition ID of the calling client
 * \param[out] key_attributes   Key attributes
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_key_attributes_from_client(
                    const struct psa_client_key_attributes_s *client_key_attr,
                    int32_t client_id,
                    psa_key_attributes_t *key_attributes);

/**
 * \brief Converts key attributes to client key attributes.
 *
 * \param[in]  key_attributes   Key attributes
 * \param[out] client_key_attr  Client key attributes
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_key_attributes_to_client(
                        const psa_key_attributes_t *key_attributes,
                        struct psa_client_key_attributes_s *client_key_attr);

/**
 * \brief Allocate an operation context in the backend
 *
 * \param[in]  type   Type of the operation context to allocate
 * \param[out] handle Pointer to hold the allocated handle
 * \param[out  ctx    Double pointer to the corresponding context
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_operation_alloc(enum tfm_crypto_operation_type type,
                                        uint32_t *handle,
                                        void **ctx);
/**
 * \brief Release an operation context in the backend
 *
 * \param[in] handle Pointer to the handle of the context to release
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_operation_release(uint32_t *handle);
/**
 * \brief Look up an operation context in the backend for the corresponding
 *        frontend operation
 *
 * \param[in]  type   Type of the operation context to look up
 * \param[in]  handle Handle of the context to lookup
 * \param[out] ctx    Double pointer to the corresponding context
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_operation_lookup(enum tfm_crypto_operation_type type,
                                         uint32_t handle,
                                         void **ctx);
/**
 * \brief This function handles the operations to allocate or retrieve a
 *        multipart context. It receives a operation and function type as
 *        inputs and then returns the looked or allocated context using
 *        the provided handle. If a context is allocated in a setup call
 *        the returned handle is then updated with the allocated value
 *
 * \param[in]      type          Type of the operation context to look up
 * \param[in]      function_type Type of the function
 * \param[in, out] handle        Pointer to the handle
 * \param[out]     ctx           Double pointer to the context
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_operation_handling(enum tfm_crypto_operation_type type,
                                    enum tfm_crypto_function_type function_type,
                                    uint32_t *handle,
                                    void **ctx);
/**
 * \brief This function acts as interface from the framework dispatching
 *        calls to the set of functions that implement the PSA Crypto APIs.
 *        It is based on the Uniform Signatures prototype.
 *
 * \param[in]  in_vec   Array of invec parameters
 * \param[in]  in_len   Length of the valid entries in in_vec
 * \param[out] out_vec  Array of outvec parameters
 * \param[in]  out_len  Length of the valid entries in out_vec
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_api_dispatcher(psa_invec in_vec[],
                                       size_t in_len,
                                       psa_outvec out_vec[],
                                       size_t out_len);
/**
 * \brief This function acts as interface for the Key management module
 *
 * \param[in]  in_vec   Array of invec parameters
 * \param[out] out_vec  Array of outvec parameters
 * \param[in]  encoded_key Key encoded with partition_id and key_id
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_key_management_interface(psa_invec in_vec[],
                                            psa_outvec out_vec[],
                                            mbedtls_svc_key_id_t *encoded_key);
/**
 * \brief This function acts as interface for the MAC module
 *
 * \param[in]  in_vec   Array of invec parameters
 * \param[out] out_vec  Array of outvec parameters
 * \param[in]  encoded_key Key encoded with partition_id and key_id
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_mac_interface(psa_invec in_vec[],
                                      psa_outvec out_vec[],
                                      mbedtls_svc_key_id_t *encoded_key);
/**
 * \brief This function acts as interface for the Cipher module
 *
 * \param[in]  in_vec   Array of invec parameters
 * \param[out] out_vec  Array of outvec parameters
 * \param[in]  encoded_key Key encoded with partition_id and key_id
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_cipher_interface(psa_invec in_vec[],
                                         psa_outvec out_vec[],
                                         mbedtls_svc_key_id_t *encoded_key);
/**
 * \brief This function acts as interface for the AEAD module
 *
 * \param[in]  in_vec   Array of invec parameters
 * \param[out] out_vec  Array of outvec parameters
 * \param[in]  encoded_key Key encoded with partition_id and key_id
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_aead_interface(psa_invec in_vec[],
                                       psa_outvec out_vec[],
                                       mbedtls_svc_key_id_t *encoded_key);
/**
 * \brief This function acts as interface for the Asymmetric module
 *
 * \param[in]  in_vec   Array of invec parameters
 * \param[out] out_vec  Array of outvec parameters
 * \param[in]  encoded_key Key encoded with partition_id and key_id
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_asymmetric_interface(psa_invec in_vec[],
                                             psa_outvec out_vec[],
                                             mbedtls_svc_key_id_t *encoded_key);
/**
 * \brief This function acts as interface for the Key derivation module
 *
 * \param[in]  in_vec   Array of invec parameters
 * \param[out] out_vec  Array of outvec parameters
 * \param[in]  encoded_key Key encoded with partition_id and key_id
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_key_derivation_interface(psa_invec in_vec[],
                                            psa_outvec out_vec[],
                                            mbedtls_svc_key_id_t *encoded_key);
/**
 * \brief This function acts as interface for the Random module
 *
 * \param[in]  in_vec   Array of invec parameters
 * \param[out] out_vec  Array of outvec parameters
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_random_interface(psa_invec in_vec[],
                                         psa_outvec out_vec[]);
/**
 * \brief This function acts as interface for the Hash module
 *
 * \param[in]  in_vec   Array of invec parameters
 * \param[out] out_vec  Array of outvec parameters
 *
 * \return Return values as described in \ref psa_status_t
 */
psa_status_t tfm_crypto_hash_interface(psa_invec in_vec[],
                                       psa_outvec out_vec[]);

#ifdef __cplusplus
}
#endif

#endif /* __TFM_CRYPTO_API_H__ */