crys_chacha.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234
  1. /**************************************************************************************
  2. * Copyright (c) 2016-2017, ARM Limited or its affiliates. All rights reserved *
  3. * *
  4. * This file and the related binary are licensed under the following license: *
  5. * *
  6. * ARM Object Code and Header Files License, v1.0 Redistribution. *
  7. * *
  8. * Redistribution and use of object code, header files, and documentation, without *
  9. * modification, are permitted provided that the following conditions are met: *
  10. * *
  11. * 1) Redistributions must reproduce the above copyright notice and the *
  12. * following disclaimer in the documentation and/or other materials *
  13. * provided with the distribution. *
  14. * *
  15. * 2) Unless to the extent explicitly permitted by law, no reverse *
  16. * engineering, decompilation, or disassembly of is permitted. *
  17. * *
  18. * 3) Redistribution and use is permitted solely for the purpose of *
  19. * developing or executing applications that are targeted for use *
  20. * on an ARM-based product. *
  21. * *
  22. * DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND *
  23. * CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT *
  24. * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, *
  25. * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE *
  26. * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, *
  27. * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED *
  28. * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR *
  29. * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF *
  30. * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING *
  31. * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS *
  32. * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. *
  33. **************************************************************************************/
  34. /*!
  35. @file
  36. @brief This file contains all of the enums and definitions that are used for the
  37. CRYS CHACHA APIs, as well as the APIs themselves.
  38. @defgroup crys_chacha CryptoCell CHACHA APIs
  39. @{
  40. @ingroup cryptocell_api
  41. */
  42. #ifndef CRYS_CHACHA_H
  43. #define CRYS_CHACHA_H
  44. #include "ssi_pal_types.h"
  45. #include "crys_error.h"
  46. #ifdef __cplusplus
  47. extern "C"
  48. {
  49. #endif
  50. /************************ Defines ******************************/
  51. /*! CHACHA user's context size in words. */
  52. #define CRYS_CHACHA_USER_CTX_SIZE_IN_WORDS 17
  53. /*! CHACHA block size in words. */
  54. #define CRYS_CHACHA_BLOCK_SIZE_IN_WORDS 16
  55. /*! CHACHA block size in bytes. */
  56. #define CRYS_CHACHA_BLOCK_SIZE_IN_BYTES (CRYS_CHACHA_BLOCK_SIZE_IN_WORDS * sizeof(uint32_t))
  57. /*! Nonce buffer max size in words. */
  58. #define CRYS_CHACHA_NONCE_MAX_SIZE_IN_WORDS 3
  59. /*! Nonce buffer max size in bytes. */
  60. #define CRYS_CHACHA_NONCE_MAX_SIZE_IN_BYTES (CRYS_CHACHA_NONCE_MAX_SIZE_IN_WORDS * sizeof(uint32_t))
  61. /*! CHACHA KEY maximal size in words. */
  62. #define CRYS_CHACHA_KEY_MAX_SIZE_IN_WORDS 8
  63. /*! CHACHA KEY maximal size in bytes. */
  64. #define CRYS_CHACHA_KEY_MAX_SIZE_IN_BYTES (CRYS_CHACHA_KEY_MAX_SIZE_IN_WORDS * sizeof(uint32_t))
  65. /************************ Enums ********************************/
  66. /*! Enum defining the CHACHA Encrypt or Decrypt operation mode. */
  67. typedef enum {
  68. /*! CHACHA encrypt mode. */
  69. CRYS_CHACHA_Encrypt = 0,
  70. /*! CHACHA decrypt mode. */
  71. CRYS_CHACHA_Decrypt = 1,
  72. /*! CHACHA maximal number of operations (encrypt/decrypt). */
  73. CRYS_CHACHA_EncryptNumOfOptions,
  74. /*! Reserved. */
  75. CRYS_CHACHA_EncryptModeLast = 0x7FFFFFFF,
  76. }CRYS_CHACHA_EncryptMode_t;
  77. /*! Enum defining the CHACHA Nonce size in bits. */
  78. typedef enum {
  79. /*! 64 bit Nonce size. */
  80. CRYS_CHACHA_Nonce64BitSize = 0,
  81. /*! 96 bit Nonce size. */
  82. CRYS_CHACHA_Nonce96BitSize = 1,
  83. /*! CHACHA maximal number of nonce sizes. */
  84. CRYS_CHACHA_NonceSizeNumOfOptions,
  85. /*! Reserved. */
  86. CRYS_CHACHA_NonceSizeLast = 0x7FFFFFFF,
  87. }CRYS_CHACHA_NonceSize_t;
  88. /************************ Typedefs ****************************/
  89. /*! Defines the Nonce buffer 12 bytes array. */
  90. typedef uint8_t CRYS_CHACHA_Nonce_t[CRYS_CHACHA_NONCE_MAX_SIZE_IN_BYTES];
  91. /*! Defines the CHACHA key buffer. */
  92. typedef uint8_t CRYS_CHACHA_Key_t[CRYS_CHACHA_KEY_MAX_SIZE_IN_BYTES];
  93. /************************ context Structs ******************************/
  94. /*! The user's context prototype - the argument type that is passed by the user
  95. to the CHACHA API. The context saves the state of the operation and must be saved by the user
  96. till the end of the APIs flow (for example till ::CRYS_CHACHA_Free is called). */
  97. typedef struct CRYS_CHACHAUserContext_t {
  98. /* Allocated buffer must be double the size of actual context
  99. * + 1 word for offset management */
  100. /*! Context buffer for internal use */
  101. uint32_t buff[CRYS_CHACHA_USER_CTX_SIZE_IN_WORDS];
  102. }CRYS_CHACHAUserContext_t;
  103. /************************ Public Variables **********************/
  104. /************************ Public Functions **********************/
  105. /****************************************************************************************************/
  106. /*!
  107. @brief This function is used to initialize the context for CHACHA operations.
  108. @return CRYS_OK on success.
  109. @return A non-zero value on failure as defined crys_chacha_error.h.
  110. */
  111. CIMPORT_C CRYSError_t CRYS_CHACHA_Init(
  112. CRYS_CHACHAUserContext_t *pContextID, /*!< [in] Pointer to the CHACHA context buffer that is allocated by the user
  113. and is used for the CHACHA operation. */
  114. CRYS_CHACHA_Nonce_t pNonce, /*!< [in] A buffer containing an nonce. */
  115. CRYS_CHACHA_NonceSize_t nonceSize, /*!< [in] Enumerator defining the nonce size (only 64 and 96 bit are valid). */
  116. CRYS_CHACHA_Key_t pKey, /*!< [in] A pointer to the user's key buffer. */
  117. uint32_t initialCounter, /*!< [in] An initial counter. */
  118. CRYS_CHACHA_EncryptMode_t EncryptDecryptFlag /*!< [in] A flag specifying whether the CHACHA should perform an Encrypt operation
  119. or a Decrypt operation. */
  120. );
  121. /*!
  122. @brief This function is used to process aligned blocks of CHACHA.
  123. The data in size should be a multiple of chacha block size.
  124. @return CRYS_OK on success.
  125. @return A non-zero value on failure as defined crys_chacha_error.h.
  126. */
  127. CIMPORT_C CRYSError_t CRYS_CHACHA_Block(
  128. CRYS_CHACHAUserContext_t *pContextID, /*!< [in] Pointer to the context buffer. */
  129. uint8_t *pDataIn, /*!< [in] A pointer to the buffer of the input data to the CHACHA.
  130. The pointer does not need to be aligned. must not be null. */
  131. uint32_t dataInSize, /*!< [in] The size of the input data.
  132. Must be a multiple of ::CRYS_CHACHA_BLOCK_SIZE_IN_BYTES bytes and must not be 0. */
  133. uint8_t *pDataOut /*!< [out] A pointer to the buffer of the output data from the CHACHA.
  134. The pointer does not need to be aligned. must not be null. */
  135. );
  136. /*!
  137. @brief This function is used to process the remaining data of CHACHA.
  138. The data in size should be smaller than chacha block size.
  139. @return CRYS_OK on success.
  140. @return A non-zero value on failure as defined crys_chacha_error.h.
  141. */
  142. CIMPORT_C CRYSError_t CRYS_CHACHA_Finish(
  143. CRYS_CHACHAUserContext_t *pContextID, /*!< [in] Pointer to the context buffer. */
  144. uint8_t *pDataIn, /*!< [in] A pointer to the buffer of the input data to the CHACHA.
  145. The pointer does not need to be aligned. If dataInSize = 0, input buffer is not required. */
  146. uint32_t dataInSize, /*!< [in] The size of the input data.
  147. zero and non multiple of ::CRYS_CHACHA_BLOCK_SIZE_IN_BYTES are valid. */
  148. uint8_t *pDataOut /*!< [out] A pointer to the buffer of the output data from the CHACHA.
  149. The pointer does not need to be aligned. If dataInSize = 0, output buffer is not required. */
  150. );
  151. /*!
  152. @brief This function is used to free the context of CHACHA operations.
  153. @return CRYS_OK on success.
  154. @return A non-zero value on failure as defined crys_chacha_error.h.
  155. */
  156. CIMPORT_C CRYSError_t CRYS_CHACHA_Free(
  157. CRYS_CHACHAUserContext_t *pContextID /*!< [in] Pointer to the context buffer. */
  158. );
  159. /*!
  160. @brief This function is used to perform the CHACHA operation in one integrated process.
  161. @return CRYS_OK on success.
  162. @return A non-zero value on failure as defined crys_chacha_error.h.
  163. */
  164. CIMPORT_C CRYSError_t CRYS_CHACHA(
  165. CRYS_CHACHA_Nonce_t pNonce, /*!< [in] A buffer containing an nonce. */
  166. CRYS_CHACHA_NonceSize_t nonceSize, /*!< [in] Enumerator defining the nonce size (only 64 and 96 bit are valid). */
  167. CRYS_CHACHA_Key_t pKey, /*!< [in] A pointer to the user's key buffer. */
  168. uint32_t initialCounter, /*!< [in] An initial counter. */
  169. CRYS_CHACHA_EncryptMode_t encryptDecryptFlag, /*!< [in] A flag specifying whether the CHACHA should perform an Encrypt operation
  170. or a Decrypt operation. */
  171. uint8_t *pDataIn, /*!< [in] A pointer to the buffer of the input data to the CHACHA.
  172. The pointer does not need to be aligned. must not be null. */
  173. uint32_t dataInSize, /*!< [in] The size of the input data. must not be 0. */
  174. uint8_t *pDataOut /*!< [out] A pointer to the buffer of the output data from the CHACHA.
  175. The pointer does not need to be aligned. must not be null. */
  176. );
  177. /***********************************************************************************/
  178. #ifdef __cplusplus
  179. }
  180. #endif
  181. /**
  182. @}
  183. */
  184. #endif /* #ifndef CRYS_CHACHA_H */