secure_fw/services/crypto/crypto_engine.h

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

#ifndef __CRYPTO_ENGINE_H__
#define __CRYPTO_ENGINE_H__

#ifdef __cplusplus
extern "C" {
#endif

#include <limits.h>
#include "psa_crypto.h"

#if defined(TFM_CRYPTO_ENGINE_MBEDTLS)
/* Pre include Mbed TLS headers */
#define LIB_PREFIX_NAME __tfm_crypto__
#include "mbedtls_global_symbols.h"

/* Include the Mbed TLS configuration file, the way Mbed TLS does it
 * in each of its header files. */
#if !defined(MBEDTLS_CONFIG_FILE)
#include "platform/ext/common/tfm_mbedtls_config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif

/**
 * \brief List of engine specific includes for Mbed TLS
 *
 */
#include "mbedtls/memory_buffer_alloc.h"
#include "mbedtls/md.h"
#include "mbedtls/cipher.h"
#include "mbedtls/cmac.h"

#endif /* TFM_CRYPTO_ENGINE_MBEDTLS */

/**
 * \brief Generic engine cipher context type
 *
 */
union engine_cipher_context {
    uint32_t dummy; /* Needed to keep the union always not empty */
#if defined(TFM_CRYPTO_ENGINE_MBEDTLS)
    mbedtls_cipher_context_t ctx;
#endif
};

/**
 * \brief Generic engine hash context type
 *
 */
union engine_hash_context {
    uint32_t dummy; /* Needed to keep the union always not empty */
#if defined (TFM_CRYPTO_ENGINE_MBEDTLS)
    mbedtls_md_context_t ctx;
#endif
};

/**
 * \brief Generic engine cmac context type
 *
 */
union engine_cmac_context {
    uint32_t dummy; /* Needed to keep the union always not empty */
#if defined (TFM_CRYPTO_ENGINE_MBEDTLS)
    mbedtls_cmac_context_t ctx;
#endif
};



/**
 * \brief For a cipher operation, define the possible modes of configuration.
 */
enum engine_cipher_mode_t {
    ENGINE_CIPHER_MODE_NONE = 0, /*!< Cipher mode not selected */
    ENGINE_CIPHER_MODE_DECRYPT,  /*!< Cipher mode set to decryption */
    ENGINE_CIPHER_MODE_ENCRYPT,  /*!< Cipher mode set to encryption */
    /* Used to force enum size */
    ENGINE_CIPHER_MODE_FORCE_INT_SIZE = INT_MAX
};

/**
 * \brief Structure used to keep engine information during the engine setup
 *        step for a hash operation.
 */
struct hash_engine_info {
    uint32_t type;           /*!< Engine specific identifier which describes
                              *   the operation which has to be configured on
                              *   the crypto engine
                              */
};

/**
 * \brief Structure used to keep engine information during the engine setup
 *        step for a cipher operation
 */
struct cipher_engine_info {
    uint32_t type;           /*!< Engine specific identifier which describes
                              *   the operation which has to be configured on
                              *   the crypto engine
                              */
    enum engine_cipher_mode_t cipher_mode; /*!< Describes if the cipher on
                                            *   the engine is configured for
                                            *   encryption or decryption
                                            */
    uint32_t padding_mode; /*!< Engine specific identifier which describes
                            *   the padding mode which has been configured
                            *   on the cipher, if any
                            */
};

/**
 * \brief This function performs all the generic operations required to
 *        initialise the crypto engine
 *
 * \return Return values as specified by \ref psa_status_t
 */
psa_status_t tfm_crypto_engine_init(void);

/**
 * \brief This function performs the setup of a multipart hash operation on the
 *        crypto engine
 *
 * \param[in]  alg         Algorithm to be setup
 * \param[out] engine_info Pointer to the engine_info structure containing
 *                         engine parameters determined during the setup
 *
 * \return Return values as specified by \ref psa_status_t
 */
psa_status_t tfm_crypto_engine_hash_setup(const psa_algorithm_t alg,
                                          struct hash_engine_info *engine_info);
/**
 * \brief This function starts a multipart hash operation on the crypto engine
 *
 * \param[in/out] hp          Pointer to the hash engine context to be used
 * \param[in]     engine_info Pointer to the engine_info structure as determined
 *                            during the setup step
 *
 * \return Return values as specified by \ref psa_status_t
 */
psa_status_t tfm_crypto_engine_hash_start(union engine_hash_context *hp,
                                    const struct hash_engine_info *engine_info);
/**
 * \brief This function updates a multipart hash operation with one chunk of
 *        input data
 *
 * \param[in/out] hp           Pointer to the hash engine context to be used
 * \param[in]     input        Pointer to the buffer containing the input data
 * \param[in]     input_length Size in bytes of the input data
 *
 * \return Return values as specified by \ref psa_status_t
 */
psa_status_t tfm_crypto_engine_hash_update(union engine_hash_context *hp,
                                           const uint8_t *input,
                                           const uint32_t input_length);
/**
 * \brief This function finalises a multipart hash operation producing one hash
 *        value in output as described by the operation context
 *
 * \param[in/out] hp   Pointer to the hash engine context to be used
 * \param[out]    hash Pointer to the buffer containing the output hash value
 *
 * \return Return values as specified by \ref psa_status_t
 */
psa_status_t tfm_crypto_engine_hash_finish(union engine_hash_context *hp,
                                           uint8_t *hash);
/**
 * \brief This function releases the crypto engine resources associated to a
 *        multipart hash operation context
 *
 * \param[in/out] hp Pointer to the hash engine context to be used
 *
 * \return Return values as specified by \ref psa_status_t
 */
psa_status_t tfm_crypto_engine_hash_release(union engine_hash_context *hp);

/**
 * \brief This function performs the setup of a multipart cipher operation on
 *        the crypto engine
 *
 * \param[in] alg                Algorithm to be configured
 * \param[in] key_type           Key type of the key that will be used
 * \param[in] key_size           Size in bits of the key that will be used
 * \param[in] engine_cipher_mode Parameter specifying if the cipher must be set
 *                               in encrypt or decrypt mode
 * \param[out] engine_info       Pointer to the engine configuration structure
 *                               containing engine parameters determined during
 *                               setup
 *
 * \return Return values as specified by \ref psa_status_t
 */
psa_status_t tfm_crypto_engine_cipher_setup(const psa_algorithm_t alg,
                             const psa_key_type_t key_type,
                             const uint32_t key_size,
                             const enum engine_cipher_mode_t engine_cipher_mode,
                             struct cipher_engine_info *engine_info);
/**
 * \brief This function sets the padding mode on the crypto engine based on the
 *        information gathered during the setup phase
 *
 * \param[in/out] cp          Pointer to the cipher engine context to be used
 * \param[in]     engine_info Pointer to the engine configuration structure
 *                            containing engine parameters determined during
 *                            setup
 *
 * \return Return values as specified by \ref psa_status_t
 */
psa_status_t tfm_crypto_engine_cipher_set_padding_mode(
                                  union engine_cipher_context *cp,
                                  const struct cipher_engine_info *engine_info);
/**
 * \brief This function starts a multipart cipher operation
 *
 * \param[in/out] cp          Pointer to the cipher engine context to be used
 * \param[in]     engine_info Pointer to the engine configuration structure
 *                            containing engine parameters determined during
 *                            setup
 *
 * \return Return values as specified by \ref psa_status_t
 */
psa_status_t tfm_crypto_engine_cipher_start(
                                  union engine_cipher_context *cp,
                                  const struct cipher_engine_info *engine_info);
/**
 * \brief This function sets the key data on the crypto engine for a multipart
 *        cipher operation. It reads also from the engine_info configuration
 *        item to determine if the key needs to be set in encryption or
 *        decryption mode on the engine.
 *
 * \param[in/out] cp          Pointer to the cipher engine context to be used
 * \param[in]     key_data    Pointer to the buffer containing key material
 * \param[in]     key_size    Size in bytes of the key pointed by key_data
 * \param[in]     engine_info Pointer to the engine configuration structure
 *                            containing engine parameters determined during
 *                            setup
 *
 * \return Return values as specified by \ref psa_status_t
 */
psa_status_t tfm_crypto_engine_cipher_set_key(
                                  union engine_cipher_context *cp,
                                  const uint8_t *key_data,
                                  const uint32_t key_size,
                                  const struct cipher_engine_info *engine_info);
/**
 * \brief This function sets the initialisation vector on the crypto engine for
 *        a multipart cipher operation
 *
 * \param[in/out] cp        Pointer to the cipher engine context to be used
 * \param[in]     iv        Pointer to the buffer containing the IV
 * \param[in]     iv_length Size in bytes of the initialisation vector
 *
 * \return Return values as specified by \ref psa_status_t
 */
psa_status_t tfm_crypto_engine_cipher_set_iv(union engine_cipher_context *cp,
                                             const uint8_t *iv,
                                             const uint32_t iv_length);
/**
 * \brief This function updates a multipart cipher operation on the crypto
 *        engine with a new chunk of input data. It may produce output data.
 *
 * \param[in/out] cp            Pointer to the cipher engine context to be used
 * \param[in]     input         Pointer to the buffer containing the input data
 *                              chunk
 * \param[in]     input_length  Size in bytes of the input data chunk
 * \param[out]    output        Pointer to the buffer containing the output data
 * \param[out]    output_length Pointer to the size in bytes of the data produced
 *                              as output
 *
 * \return Return values as specified by \ref psa_status_t
 */
psa_status_t tfm_crypto_engine_cipher_update(union engine_cipher_context *cp,
                                             const uint8_t *input,
                                             const uint32_t input_length,
                                             uint8_t *output,
                                             uint32_t *output_length);
/**
 * \brief This function finalises a multipart cipher operation on the crypto
 *        engine. It may produce output data.
 *
 * \param[in/out] cp            Pointer to the cipher engine context to be used
 * \param[out]    output        Pointer to the buffer containing the output data
 * \param[out]    output_length Pointer to the size in bytes of the data produced
 *                              as output
 *
 * \return Return values as specified by \ref psa_status_t
 */
psa_status_t tfm_crypto_engine_cipher_finish(union engine_cipher_context *cp,
                                             uint8_t *output,
                                             uint32_t *output_length);
/**
 * \brief This function releases the crypto engine resources associated to a
 *        multipart cipher operation context
 *
 * \param[in/out] cp Pointer to the cipher engine context to be used
 *
 * \return Return values as specified by \ref psa_status_t
 */
psa_status_t tfm_crypto_engine_cipher_release(union engine_cipher_context *cp);

/**
 * \brief This function performs an AEAD encryption on the provided data
 *
 * \param[in]  key_type               Key type of the key that will be used
 * \param[in]  alg                    Algorithm to be used
 * \param[in]  key_data               Pointer to the buffer containing key
 *                                    material
 * \param[in]  key_size               Size in bytes of the key pointed to by
 *                                    key_data
 * \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 specified by \ref psa_status_t
 */
psa_status_t tfm_crypto_engine_aead_encrypt(psa_key_type_t key_type,
                                            psa_algorithm_t alg,
                                            const uint8_t *key_data,
                                            uint32_t key_size,
                                            const uint8_t *nonce,
                                            uint32_t nonce_length,
                                            const uint8_t *additional_data,
                                            uint32_t additional_data_length,
                                            const uint8_t *plaintext,
                                            uint32_t plaintext_length,
                                            uint8_t *ciphertext,
                                            uint32_t ciphertext_size,
                                            uint32_t *ciphertext_length);
/**
 * \brief This function performs an AEAD decryption on the provided data
 *
 * \param[in]  key_type               Key type of the key that will be used
 * \param[in]  alg                    Algorithm to be used
 * \param[in]  key_data               Pointer to the buffer containing key
 *                                    material
 * \param[in]  key_size               Size in bytes of the key pointed to by
 *                                    key_data
 * \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 specified by \ref psa_status_t
 */
psa_status_t tfm_crypto_engine_aead_decrypt(psa_key_type_t key_type,
                                            psa_algorithm_t alg,
                                            const uint8_t *key_data,
                                            uint32_t key_size,
                                            const uint8_t *nonce,
                                            uint32_t nonce_length,
                                            const uint8_t *additional_data,
                                            uint32_t additional_data_length,
                                            const uint8_t *ciphertext,
                                            uint32_t ciphertext_length,
                                            uint8_t *plaintext,
                                            uint32_t plaintext_size,
                                            uint32_t *plaintext_length);
#ifdef __cplusplus
}
#endif

#endif /* __CRYPTO_ENGINE_H__ */