Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
crys_chacha.h
Go to the documentation of this file.
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 
36 /*!
37 @file
38 @brief This file contains all of the enums and definitions that are used for the
39  CRYS CHACHA APIs, as well as the APIs themselves.
40 @defgroup crys_chacha CryptoCell CHACHA APIs
41 @{
42 @ingroup cryptocell_api
43 */
44 #ifndef CRYS_CHACHA_H
45 #define CRYS_CHACHA_H
46 
47 
48 #include "ssi_pal_types.h"
49 #include "crys_error.h"
50 
51 
52 #ifdef __cplusplus
53 extern "C"
54 {
55 #endif
56 
57 /************************ Defines ******************************/
58 /*! CHACHA user's context size in words. */
59 #define CRYS_CHACHA_USER_CTX_SIZE_IN_WORDS 17
60 
61 /*! CHACHA block size in words. */
62 #define CRYS_CHACHA_BLOCK_SIZE_IN_WORDS 16
63 /*! CHACHA block size in bytes. */
64 #define CRYS_CHACHA_BLOCK_SIZE_IN_BYTES (CRYS_CHACHA_BLOCK_SIZE_IN_WORDS * sizeof(uint32_t))
65 
66 /*! Nonce buffer max size in words. */
67 #define CRYS_CHACHA_NONCE_MAX_SIZE_IN_WORDS 3
68 /*! Nonce buffer max size in bytes. */
69 #define CRYS_CHACHA_NONCE_MAX_SIZE_IN_BYTES (CRYS_CHACHA_NONCE_MAX_SIZE_IN_WORDS * sizeof(uint32_t))
70 
71 /*! CHACHA KEY maximal size in words. */
72 #define CRYS_CHACHA_KEY_MAX_SIZE_IN_WORDS 8
73 /*! CHACHA KEY maximal size in bytes. */
74 #define CRYS_CHACHA_KEY_MAX_SIZE_IN_BYTES (CRYS_CHACHA_KEY_MAX_SIZE_IN_WORDS * sizeof(uint32_t))
75 
76 /************************ Enums ********************************/
77 
78 /*! Enum defining the CHACHA Encrypt or Decrypt operation mode. */
79 typedef enum {
80  /*! CHACHA encrypt mode. */
81  CRYS_CHACHA_Encrypt = 0,
82  /*! CHACHA decrypt mode. */
83  CRYS_CHACHA_Decrypt = 1,
84  /*! CHACHA maximal number of operations (encrypt/decrypt). */
85  CRYS_CHACHA_EncryptNumOfOptions,
86 
87  /*! Reserved. */
88  CRYS_CHACHA_EncryptModeLast = 0x7FFFFFFF,
89 
90 }CRYS_CHACHA_EncryptMode_t;
91 
92 /*! Enum defining the CHACHA Nonce size in bits. */
93 typedef enum {
94  /*! 64 bit Nonce size. */
95  CRYS_CHACHA_Nonce64BitSize = 0,
96  /*! 96 bit Nonce size. */
97  CRYS_CHACHA_Nonce96BitSize = 1,
98  /*! CHACHA maximal number of nonce sizes. */
99  CRYS_CHACHA_NonceSizeNumOfOptions,
100  /*! Reserved. */
101  CRYS_CHACHA_NonceSizeLast = 0x7FFFFFFF,
102 
103 }CRYS_CHACHA_NonceSize_t;
104 
105 /************************ Typedefs ****************************/
106 
107 /*! Defines the Nonce buffer 12 bytes array. */
108 typedef uint8_t CRYS_CHACHA_Nonce_t[CRYS_CHACHA_NONCE_MAX_SIZE_IN_BYTES];
109 
110 /*! Defines the CHACHA key buffer. */
111 typedef uint8_t CRYS_CHACHA_Key_t[CRYS_CHACHA_KEY_MAX_SIZE_IN_BYTES];
112 
113 
114 /************************ context Structs ******************************/
115 
116 /*! The user's context prototype - the argument type that is passed by the user
117  to the CHACHA API. The context saves the state of the operation and must be saved by the user
118  till the end of the APIs flow (for example till ::CRYS_CHACHA_Free is called). */
119 typedef struct CRYS_CHACHAUserContext_t {
120  /* Allocated buffer must be double the size of actual context
121  * + 1 word for offset management */
122  /*! Context buffer for internal use */
123  uint32_t buff[CRYS_CHACHA_USER_CTX_SIZE_IN_WORDS];
124 }CRYS_CHACHAUserContext_t;
125 
126 /************************ Public Variables **********************/
127 
128 
129 /************************ Public Functions **********************/
130 
131 /****************************************************************************************************/
132 
133 /*!
134 @brief This function is used to initialize the context for CHACHA operations.
135 
136 @return CRYS_OK on success.
137 @return A non-zero value on failure as defined crys_chacha_error.h.
138 */
139 CIMPORT_C CRYSError_t CRYS_CHACHA_Init(
140  CRYS_CHACHAUserContext_t *pContextID, /*!< [in] Pointer to the CHACHA context buffer that is allocated by the user
141  and is used for the CHACHA operation. */
142  CRYS_CHACHA_Nonce_t pNonce, /*!< [in] A buffer containing an nonce. */
143  CRYS_CHACHA_NonceSize_t nonceSize, /*!< [in] Enumerator defining the nonce size (only 64 and 96 bit are valid). */
144  CRYS_CHACHA_Key_t pKey, /*!< [in] A pointer to the user's key buffer. */
145  uint32_t initialCounter, /*!< [in] An initial counter. */
146  CRYS_CHACHA_EncryptMode_t EncryptDecryptFlag /*!< [in] A flag specifying whether the CHACHA should perform an Encrypt operation
147  or a Decrypt operation. */
148 );
149 
150 
151 /*!
152 @brief This function is used to process aligned blocks of CHACHA.
153 The data in size should be a multiple of chacha block size.
154 
155 @return CRYS_OK on success.
156 @return A non-zero value on failure as defined crys_chacha_error.h.
157 */
158 CIMPORT_C CRYSError_t CRYS_CHACHA_Block(
159  CRYS_CHACHAUserContext_t *pContextID, /*!< [in] Pointer to the context buffer. */
160  uint8_t *pDataIn, /*!< [in] A pointer to the buffer of the input data to the CHACHA.
161  The pointer does not need to be aligned. must not be null. */
162  uint32_t dataInSize, /*!< [in] The size of the input data.
163  Must be a multiple of ::CRYS_CHACHA_BLOCK_SIZE_IN_BYTES bytes and must not be 0. */
164  uint8_t *pDataOut /*!< [out] A pointer to the buffer of the output data from the CHACHA.
165  The pointer does not need to be aligned. must not be null. */
166 );
167 
168 
169 /*!
170 @brief This function is used to process the remaining data of CHACHA.
171 The data in size should be smaller than chacha block size.
172 
173 @return CRYS_OK on success.
174 @return A non-zero value on failure as defined crys_chacha_error.h.
175 */
176 CIMPORT_C CRYSError_t CRYS_CHACHA_Finish(
177  CRYS_CHACHAUserContext_t *pContextID, /*!< [in] Pointer to the context buffer. */
178  uint8_t *pDataIn, /*!< [in] A pointer to the buffer of the input data to the CHACHA.
179  The pointer does not need to be aligned. If dataInSize = 0, input buffer is not required. */
180  uint32_t dataInSize, /*!< [in] The size of the input data.
181  zero and non multiple of ::CRYS_CHACHA_BLOCK_SIZE_IN_BYTES are valid. */
182  uint8_t *pDataOut /*!< [out] A pointer to the buffer of the output data from the CHACHA.
183  The pointer does not need to be aligned. If dataInSize = 0, output buffer is not required. */
184 );
185 
186 
187 /*!
188 @brief This function is used to free the context of CHACHA operations.
189 
190 @return CRYS_OK on success.
191 @return A non-zero value on failure as defined crys_chacha_error.h.
192 */
193 CIMPORT_C CRYSError_t CRYS_CHACHA_Free(
194  CRYS_CHACHAUserContext_t *pContextID /*!< [in] Pointer to the context buffer. */
195 );
196 
197 
198 /*!
199 @brief This function is used to perform the CHACHA operation in one integrated process.
200 
201 @return CRYS_OK on success.
202 @return A non-zero value on failure as defined crys_chacha_error.h.
203 */
204 CIMPORT_C CRYSError_t CRYS_CHACHA(
205  CRYS_CHACHA_Nonce_t pNonce, /*!< [in] A buffer containing an nonce. */
206  CRYS_CHACHA_NonceSize_t nonceSize, /*!< [in] Enumerator defining the nonce size (only 64 and 96 bit are valid). */
207  CRYS_CHACHA_Key_t pKey, /*!< [in] A pointer to the user's key buffer. */
208  uint32_t initialCounter, /*!< [in] An initial counter. */
209  CRYS_CHACHA_EncryptMode_t encryptDecryptFlag, /*!< [in] A flag specifying whether the CHACHA should perform an Encrypt operation
210  or a Decrypt operation. */
211  uint8_t *pDataIn, /*!< [in] A pointer to the buffer of the input data to the CHACHA.
212  The pointer does not need to be aligned. must not be null. */
213  uint32_t dataInSize, /*!< [in] The size of the input data. must not be 0. */
214  uint8_t *pDataOut /*!< [out] A pointer to the buffer of the output data from the CHACHA.
215  The pointer does not need to be aligned. must not be null. */
216 );
217 
218 
219 /***********************************************************************************/
220 
221 #ifdef __cplusplus
222 }
223 #endif
224 
225 /**
226 @}
227  */
228 
229 #endif /* #ifndef CRYS_CHACHA_H */
230 
231 
232 
233 
234 
CRYS_CHACHA_NONCE_MAX_SIZE_IN_BYTES
#define CRYS_CHACHA_NONCE_MAX_SIZE_IN_BYTES
Definition: crys_chacha.h:69
CRYS_CHACHA_Finish
CRYSError_t CRYS_CHACHA_Finish(CRYS_CHACHAUserContext_t *pContextID, uint8_t *pDataIn, uint32_t dataInSize, uint8_t *pDataOut)
This function is used to process the remaining data of CHACHA. The data in size should be smaller tha...
CRYS_CHACHA_Init
CRYSError_t CRYS_CHACHA_Init(CRYS_CHACHAUserContext_t *pContextID, CRYS_CHACHA_Nonce_t pNonce, CRYS_CHACHA_NonceSize_t nonceSize, CRYS_CHACHA_Key_t pKey, uint32_t initialCounter, CRYS_CHACHA_EncryptMode_t EncryptDecryptFlag)
This function is used to initialize the context for CHACHA operations.
CRYS_CHACHA_Nonce64BitSize
Definition: crys_chacha.h:95
CRYS_CHACHA_KEY_MAX_SIZE_IN_BYTES
#define CRYS_CHACHA_KEY_MAX_SIZE_IN_BYTES
Definition: crys_chacha.h:74
CRYS_CHACHA_Nonce96BitSize
Definition: crys_chacha.h:97
CRYS_CHACHA_NonceSizeNumOfOptions
Definition: crys_chacha.h:99
CRYS_CHACHAUserContext_t
Definition: crys_chacha.h:119
CRYS_CHACHA_Nonce_t
uint8_t CRYS_CHACHA_Nonce_t[(3 *sizeof(uint32_t))]
Definition: crys_chacha.h:108
CRYS_CHACHA
CRYSError_t CRYS_CHACHA(CRYS_CHACHA_Nonce_t pNonce, CRYS_CHACHA_NonceSize_t nonceSize, CRYS_CHACHA_Key_t pKey, uint32_t initialCounter, CRYS_CHACHA_EncryptMode_t encryptDecryptFlag, uint8_t *pDataIn, uint32_t dataInSize, uint8_t *pDataOut)
This function is used to perform the CHACHA operation in one integrated process.
CRYS_CHACHA_Decrypt
Definition: crys_chacha.h:83
CRYS_CHACHAUserContext_t
struct CRYS_CHACHAUserContext_t CRYS_CHACHAUserContext_t
CRYS_CHACHA_EncryptMode_t
CRYS_CHACHA_EncryptMode_t
Definition: crys_chacha.h:79
CRYS_CHACHAUserContext_t::buff
uint32_t buff[17]
Definition: crys_chacha.h:123
CRYS_CHACHA_Encrypt
Definition: crys_chacha.h:81
CRYS_CHACHA_Block
CRYSError_t CRYS_CHACHA_Block(CRYS_CHACHAUserContext_t *pContextID, uint8_t *pDataIn, uint32_t dataInSize, uint8_t *pDataOut)
This function is used to process aligned blocks of CHACHA. The data in size should be a multiple of c...
CRYS_CHACHA_EncryptModeLast
Definition: crys_chacha.h:88
CRYSError_t
uint32_t CRYSError_t
Definition: crys_error.h:253
CRYS_CHACHA_NonceSizeLast
Definition: crys_chacha.h:101
CRYS_CHACHA_USER_CTX_SIZE_IN_WORDS
#define CRYS_CHACHA_USER_CTX_SIZE_IN_WORDS
Definition: crys_chacha.h:59
ssi_pal_types.h
This file contains the platform dependent definitions and types.
CRYS_CHACHA_Key_t
uint8_t CRYS_CHACHA_Key_t[(8 *sizeof(uint32_t))]
Definition: crys_chacha.h:111
CRYS_CHACHA_Free
CRYSError_t CRYS_CHACHA_Free(CRYS_CHACHAUserContext_t *pContextID)
This function is used to free the context of CHACHA operations.
CRYS_CHACHA_EncryptNumOfOptions
Definition: crys_chacha.h:85
crys_error.h
This module defines the error return code types and the numbering spaces of the error codes for each ...
CRYS_CHACHA_NonceSize_t
CRYS_CHACHA_NonceSize_t
Definition: crys_chacha.h:93
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.