1 /* 2 * Copyright (c) 2020, Cypress Semiconductor Corporation. All rights reserved. 3 * Copyright (c) 2020-2021, Arm Limited. All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 * 7 */ 8 9 #ifndef __TFM_HAL_ITS_ENCRYPTION_H__ 10 #define __TFM_HAL_ITS_ENCRYPTION_H__ 11 12 #include <stddef.h> 13 #include <stdint.h> 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 20 /** 21 * \brief Struct containing information required from the platform to perform 22 * encryption/decryption of ITS files. 23 */ 24 struct tfm_hal_its_auth_crypt_ctx { 25 uint8_t *deriv_label; /* The derivation label for AEAD */ 26 size_t deriv_label_size; /* Size of the deriv_label in bytes */ 27 uint8_t *aad; /* The additional authenticated data for AEAD */ 28 size_t add_size; /* Size of the add in bytes */ 29 uint8_t *nonce; /* The nonce for AEAD */ 30 size_t nonce_size; /* Size of the nonce in bytes */ 31 }; 32 33 /** 34 * \brief Generate an encryption nonce 35 * 36 * \details The nonce has to be unique for every encryption using the same key, 37 * even across resets. 38 * \param [out] nonce Pointer to the nonce 39 * \param [in] nonce_size Size of the nonce in bytes 40 * 41 * \retval TFM_HAL_SUCCESS The operation completed successfully 42 * \retval TFM_HAL_ERROR_INVALID_INPUT Invalid argument 43 * \retval TFM_HAL_ERROR_GENERIC Failed to fill the nonce seed because of 44 * an internal error 45 */ 46 enum tfm_hal_status_t tfm_hal_its_aead_generate_nonce(uint8_t *nonce, 47 const size_t nonce_size); 48 49 /** 50 * \brief Perform authenticated encryption. 51 * 52 * \details Perform the the AEAD encryption. 53 * It will start with deriving a key based long-term key-derivation 54 * key and the provided derivation label. 55 * This derived key will then be used to perform the AEAD operation. 56 * Therefore the following members of the ctx struct must be set: 57 * nonce 58 * nonce_size 59 * deriv_label 60 * deriv_label_size 61 * If additional data should be authenticated also 62 * aad 63 * aad_size 64 * must be set. 65 * 66 * \param [in] ctx AEAD context for ITS object 67 * \param [in] plaintext Pointer to the plaintext 68 * \param [in] plaintext_size Size of the plaintext in bytes 69 * \param [out] ciphertext Pointer to the ciphertext 70 * \param [in] ciphertext_size Size of the ciphertext in bytes 71 * \param [out] tag Authentication tag 72 * \param [in] tag_size Authentication tag size in bytes 73 * 74 * \retval TFM_HAL_SUCCESS The operation completed successfully 75 * \retval TFM_HAL_ERROR_INVALID_INPUT Invalid argument 76 * \retval TFM_HAL_ERROR_GENERIC Failed to encrypt 77 */ 78 enum tfm_hal_status_t tfm_hal_its_aead_encrypt( 79 struct tfm_hal_its_auth_crypt_ctx *ctx, 80 const uint8_t *plaintext, 81 const size_t plaintext_size, 82 uint8_t *ciphertext, 83 const size_t ciphertext_size, 84 uint8_t *tag, 85 const size_t tag_size); 86 87 /** 88 * \brief Perform authenticated decryption. 89 * 90 * \details To perform the the AEAD decryption, the following members of the 91 * ctx struct must be set: 92 * nonce 93 * nonce_size 94 * deriv_label 95 * deriv_label_size 96 * If additional data should be authenticated also 97 * aad 98 * aad_size 99 * must be set. 100 * 101 * 102 * \param [in] ctx AEAD context for ITS object 103 * \param [in] ciphertext Pointer to the ciphertext 104 * \param [in] ciphertext_size Size of the ciphertext in bytes 105 * \param [in] tag Authentication tag 106 * \param [in] tag_size Authentication tag size in bytes 107 * \param [out] plaintext Pointer to the plaintext 108 * \param [in] plaintext_size Size of the plaintext in bytes 109 * 110 * \retval TFM_HAL_SUCCESS The operation completed successfully 111 * \retval TFM_HAL_ERROR_INVALID_INPUT Invalid argument 112 * \retval TFM_HAL_ERROR_GENERIC Failed to decrypt 113 */ 114 enum tfm_hal_status_t tfm_hal_its_aead_decrypt( 115 struct tfm_hal_its_auth_crypt_ctx *ctx, 116 const uint8_t *ciphertext, 117 const size_t ciphertext_size, 118 uint8_t *tag, 119 const size_t tag_size, 120 uint8_t *plaintext, 121 const size_t plaintext_size); 122 123 124 #ifdef __cplusplus 125 } 126 #endif 127 128 #endif /* __TFM_HAL_ITS_ENCRYPTION_H__ */ 129
