1 /* 2 * Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 /*! 8 @file 9 @brief This file contains all of the CryptoCell ChaCha APIs, their enums and definitions. 10 */ 11 12 /*! 13 @defgroup cc_chacha CryptoCell ChaCha APIs 14 @brief Contains all CryptoCell ChaCha APIs. See mbedtls_cc_chacha.h. 15 16 The ChaCha family of stream ciphers is a variant of the Salsa20 family of stream ciphers. 17 For more information, see <em>ChaCha, a variant of Salsa20</em>. 18 @{ 19 @ingroup cryptocell_api 20 @} 21 */ 22 23 #ifndef _MBEDTLS_CC_CHACHA_H 24 #define _MBEDTLS_CC_CHACHA_H 25 26 27 #include "cc_pal_types.h" 28 #include "cc_error.h" 29 30 31 #ifdef __cplusplus 32 extern "C" 33 { 34 #endif 35 36 /************************ Defines ******************************/ 37 38 /*! The size of the ChaCha user-context in words. */ 39 #define CC_CHACHA_USER_CTX_SIZE_IN_WORDS 17 40 41 /*! The size of the ChaCha block in words. */ 42 #define CC_CHACHA_BLOCK_SIZE_IN_WORDS 16 43 /*! The size of the ChaCha block in Bytes. */ 44 #define CC_CHACHA_BLOCK_SIZE_IN_BYTES (CC_CHACHA_BLOCK_SIZE_IN_WORDS * sizeof(uint32_t)) 45 46 /*! The maximal size of the nonce buffer in words. */ 47 #define CC_CHACHA_NONCE_MAX_SIZE_IN_WORDS 3 48 /*! The maximal size of the nonce buffer in Bytes. */ 49 #define CC_CHACHA_NONCE_MAX_SIZE_IN_BYTES (CC_CHACHA_NONCE_MAX_SIZE_IN_WORDS * sizeof(uint32_t)) 50 51 /*! The maximal size of the ChaCha key in words. */ 52 #define CC_CHACHA_KEY_MAX_SIZE_IN_WORDS 8 53 /*! The maximal size of the ChaCha key in Bytes. */ 54 #define CC_CHACHA_KEY_MAX_SIZE_IN_BYTES (CC_CHACHA_KEY_MAX_SIZE_IN_WORDS * sizeof(uint32_t)) 55 56 /************************ Enums ********************************/ 57 58 /*! The ChaCha operation:<ul><li>Encrypt</li><li>Decrypt</li></ul>. */ 59 typedef enum { 60 CC_CHACHA_Decrypt = 0, /*!< A ChaCha decrypt operation. */ 61 CC_CHACHA_Encrypt = 1, /*!< A ChaCha encrypt operation. */ 62 CC_CHACHA_EncryptNumOfOptions, /*!< The maximal number of encrypt or decrypt operations for the ChaCha engine. */ 63 CC_CHACHA_EncryptModeLast = 0x7FFFFFFF, /*!< Reserved. */ 64 65 }mbedtls_chacha_encrypt_mode_t; 66 67 /*! The allowed nonce-size values of the ChaCha engine in bits. */ 68 typedef enum { 69 CC_CHACHA_Nonce64BitSize = 0, /*!< A 64-bit nonce size. */ 70 CC_CHACHA_Nonce96BitSize = 1, /*!< A 96-bit nonce size. */ 71 CC_CHACHA_NonceSizeNumOfOptions, /*!< The maximal number of nonce sizes for the ChaCha engine. */ 72 CC_CHACHA_NonceSizeLast = 0x7FFFFFFF, /*!< Reserved. */ 73 }mbedtls_chacha_nonce_size_t; 74 75 /************************ Typedefs ****************************/ 76 77 /*! The definition of the 12-Byte array of the nonce buffer. */ 78 typedef uint8_t mbedtls_chacha_nonce[CC_CHACHA_NONCE_MAX_SIZE_IN_BYTES]; 79 80 /*! The definition of the key buffer of the ChaCha engine. */ 81 typedef uint8_t mbedtls_chacha_key[CC_CHACHA_KEY_MAX_SIZE_IN_BYTES]; 82 83 84 /************************ context Structs ******************************/ 85 86 /*! 87 @brief The context prototype of the user. 88 89 The argument type that is passed by the user to the ChaCha API. 90 91 The context saves the state of the operation. It must be saved by the user 92 until the end of the API flow, for example, until ::mbedtls_chacha_free is called. 93 */ 94 typedef struct mbedtls_chacha_user_context { 95 /* The allocated buffer must be double the size of the actual context 96 * + 1 word for offset management */ 97 uint32_t buff[CC_CHACHA_USER_CTX_SIZE_IN_WORDS]; /*!< The context buffer for internal use */ 98 }mbedtls_chacha_user_context; 99 100 /************************ Public Variables **********************/ 101 102 103 /************************ Public Functions **********************/ 104 105 /****************************************************************************************************/ 106 107 /*! 108 @brief This function initializes the context for ChaCha-engine operations. 109 110 @return \c CC_OK on success. 111 @return A non-zero value on failure as defined in mbedtls_cc_chacha_error.h. 112 */ 113 CIMPORT_C CCError_t mbedtls_chacha_init( 114 mbedtls_chacha_user_context *pContextID, /*!< [in] A pointer to the ChaCha context buffer that is allocated by the user and used for the ChaCha operation. */ 115 mbedtls_chacha_nonce pNonce, /*!< [in] A buffer containing a nonce. */ 116 mbedtls_chacha_nonce_size_t nonceSize, /*!< [in] An enumerator defining the nonce size. Valid values are: 64bits or 96bits. */ 117 mbedtls_chacha_key pKey, /*!< [in] A pointer to the key buffer of the user. */ 118 uint32_t initialCounter, /*!< [in] An initial counter. */ 119 mbedtls_chacha_encrypt_mode_t EncryptDecryptFlag /*!< [in] A flag specifying whether the ChaCha engine should perform an Encrypt operation or a Decrypt operation. */ 120 ); 121 122 123 /*! 124 @brief This function processes aligned blocks of the ChaCha engine. 125 126 The data-in size should be a multiple of the ChaCha block size. 127 128 @return \c CC_OK on success. 129 @return A non-zero value on failure as defined in mbedtls_cc_chacha_error.h. 130 */ 131 CIMPORT_C CCError_t mbedtls_chacha_block( 132 mbedtls_chacha_user_context *pContextID, /*!< [in] A pointer to the context buffer. */ 133 uint8_t *pDataIn, /*!< [in] A pointer to the buffer of the input data to the ChaCha engine. 134 The pointer does not need to be aligned. Must not be null. */ 135 size_t dataInSize, /*!< [in] The size of the input data. 136 Must be a multiple of ::CC_CHACHA_BLOCK_SIZE_IN_BYTES Bytes, and must not be zero. */ 137 uint8_t *pDataOut /*!< [out] A pointer to the buffer of the output data from the ChaCha engine. 138 The pointer does not need to be aligned. Must not be null. */ 139 ); 140 141 142 /*! 143 @brief This function processes the remaining ChaCha data. 144 145 The data-in size should be smaller than the ChaCha block size. 146 147 @return \c CC_OK on success. 148 @return A non-zero value on failure as defined in mbedtls_cc_chacha_error.h. 149 */ 150 CIMPORT_C CCError_t mbedtls_chacha_finish( 151 mbedtls_chacha_user_context *pContextID, /*!< [in] A pointer to the context buffer. */ 152 uint8_t *pDataIn, /*!< [in] A pointer to the buffer of the input data to the ChaCha engine. 153 The pointer does not need to be aligned. If dataInSize = 0, 154 an input buffer is not required. */ 155 size_t dataInSize, /*!< [in] The size of the input data. Valid values are:Zero or 156 values that are not multiples of ::CC_CHACHA_BLOCK_SIZE_IN_BYTES. */ 157 uint8_t *pDataOut /*!< [out] A pointer to the buffer of the output data from the ChaCha engine. 158 The pointer does not need to be aligned. If dataInSize = 0, 159 an output buffer is not required. */ 160 ); 161 162 163 /*! 164 @brief This function frees the context used for ChaCha operations. 165 166 @return \c CC_OK on success. 167 @return A non-zero value on failure as defined in mbedtls_cc_chacha_error.h. 168 */ 169 CIMPORT_C CCError_t mbedtls_chacha_free( 170 mbedtls_chacha_user_context *pContextID /*!< [in] A pointer to the context buffer. */ 171 ); 172 173 174 /*! 175 @brief This function performs the ChaCha operation in one integrated process. 176 177 @return \c CC_OK on success. 178 @return A non-zero value on failure as defined in mbedtls_cc_chacha_error.h. 179 */ 180 CIMPORT_C CCError_t mbedtls_chacha( 181 mbedtls_chacha_nonce pNonce, /*!< [in] A buffer containing a nonce. */ 182 mbedtls_chacha_nonce_size_t nonceSize, /*!< [in] An enumerator defining the size of the nonce. 183 Valid values are: 64bits or 96bits. */ 184 mbedtls_chacha_key pKey, /*!< [in] A pointer to the key buffer of the user. */ 185 uint32_t initialCounter, /*!< [in] An initial counter. */ 186 mbedtls_chacha_encrypt_mode_t encryptDecryptFlag, /*!< [in] A flag specifying which operation the ChaCha engine should 187 perform: encrypt or decrypt. */ 188 uint8_t *pDataIn, /*!< [in] A pointer to the buffer of the input-data to the ChaCha engine. 189 The pointer does not need to be aligned. Must not be null. */ 190 size_t dataInSize, /*!< [in] The size of the input data. Must not be zero. */ 191 uint8_t *pDataOut /*!< [out] A pointer to the buffer of the output data from the ChaCha. 192 The pointer does not need to be aligned. Must not be null. */ 193 ); 194 195 196 /***********************************************************************************/ 197 198 #ifdef __cplusplus 199 } 200 #endif 201 202 #endif /* #ifndef _MBEDTLS_CC_CHACHA_H */ 203
