Mistake on this page?
Report an issue in GitHub or email us
crys_aesccm.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 #ifndef CRYS_AESCCM_H
38 #define CRYS_AESCCM_H
39 
40 #include "ssi_pal_types.h"
41 #include "crys_error.h"
42 
43 #include "ssi_aes.h"
44 
45 
46 #ifdef __cplusplus
47 extern "C"
48 {
49 #endif
50 
51 /*!
52 @file
53 @brief This file contains all of the enums and definitions that are used for the CRYS AESCCM APIs, as well as the APIs themselves.
54 The API supports AES-CCM and AES-CCM* as defined in ieee-802.15.4.
55 @defgroup crys_aesccm CryptoCell AES-CCM APIs
56 @{
57 @ingroup cryptocell_api
58 
59 
60 @note
61 Regarding the AES-CCM*, the API supports only AES-CCM* as defined in ieee-802.15.4-2011; With the instantiations as defined in B.3.2 and the nonce as defined in 7.3.2.
62 in case of AES-CCM* the flow should be as follows:
63 <ul><li>AES-CCM* integrated</li>
64  <ul><li>CRYS_AESCCMStar_NonceGenerate</li>
65  <li>CRYS_AESCCMStar</li></ul></ul>
66 <ul><li>AES-CCM* non-integrated</li>
67  <ul><li>CRYS_AESCCMStar_NonceGenerate</li>
68  <li>CRYS_AESCCMStar_Init</li>
69  <li>CRYS_AESCCM_BlockAdata</li>
70  <li>CRYS_AESCCM_BlockTextData</li>
71  <li>CRYS_AESCCM_Finish</li></ul></ul>
72 */
73 
74 /************************ Defines ******************************/
75 
76 /*! AES CCM context size in words.*/
77 #define CRYS_AESCCM_USER_CTX_SIZE_IN_WORDS (152/4)
78 
79 /*! AES CCM maximal key size in words. */
80 #define CRYS_AESCCM_KEY_SIZE_WORDS 8
81 
82 /* nonce and AESCCM-MAC sizes definitions */
83 /*! AES CCM NONCE minimal size in bytes. */
84 #define CRYS_AESCCM_NONCE_MIN_SIZE_BYTES 7
85 /*! AES CCM NONCE maximal size in bytes. */
86 #define CRYS_AESCCM_NONCE_MAX_SIZE_BYTES 13
87 /*! AES CCM MAC minimal size in bytes..*/
88 #define CRYS_AESCCM_MAC_MIN_SIZE_BYTES 4
89 /*! AES CCM MAC maximal size in bytes. */
90 #define CRYS_AESCCM_MAC_MAX_SIZE_BYTES 16
91 
92 /*! AES CCM star NONCE size in bytes. */
93 #define CRYS_AESCCM_STAR_NONCE_SIZE_BYTES 13
94 /*! AES CCM star source address size in bytes. */
95 #define CRYS_AESCCM_STAR_SOURCE_ADDRESS_SIZE_BYTES 8
96 
97 /*! AES CCM mode - CCM. */
98 #define CRYS_AESCCM_MODE_CCM 0
99 /*! AES CCM mode - CCM STAR. */
100 #define CRYS_AESCCM_MODE_STAR 1
101 
102 
103 /************************ Typedefs ****************************/
104 /*! AES CCM key sizes. */
105 typedef enum {
106  /*! Key size 128 bits. */
108  /*! Key size 192 bits. */
110  /*! Key size 256 bits. */
112  /*! Key size 512 bits. */
114  /*! Number of optional key sizes. */
116  /*! Reserved. */
117  CRYS_AES_KeySizeLast = 0x7FFFFFFF,
118 
120 
121 /*! AES_CCM key buffer definition.*/
122 typedef uint8_t CRYS_AESCCM_Key_t[CRYS_AESCCM_KEY_SIZE_WORDS * sizeof(uint32_t)];
123 /*! AES_CCM MAC buffer definition.*/
125 
126 /*! AES_CCM_STAR source address buffer defintion. */
128 /*! AES_CCM_STAR Nonce buffer defintion. */
130 
131 /******************* Context Structure ***********************/
132 /*! The user's context structure - the argument type that is passed by the user to the AES CCM APIs */
134 {
135  /*! AES CCM context buffer for internal usage. */
138 
139 
140 /************************ Public Functions **********************/
141 
142 /*!
143 @brief This function initializes the AES CCM context.
144 
145 It formats of the input data, calculates AES-MAC value for the formatted B0 block containing control information and
146 CCM unique value (Nonce), and initializes the AES context structure including the initial CTR0 value.
147 
148 @return CRYS_OK on success.
149 @return A non-zero value on failure as defined crys_aesccm_error.h.
150 */
152  CRYS_AESCCM_UserContext_t *ContextID_ptr, /*!< [in] Pointer to the AES context buffer that is allocated by the user and is used for
153  the AES operation. */
154  SaSiAesEncryptMode_t EncrDecrMode, /*!< [in] Flag specifying whether Encrypt (::SASI_AES_ENCRYPT) or Decrypt
155  (::SASI_AES_DECRYPT) operation should be performed. */
156  CRYS_AESCCM_Key_t CCM_Key, /*!< [in] Pointer to the AES-CCM key. */
157  CRYS_AESCCM_KeySize_t KeySizeId, /*!< [in] Enumerator defining the key size (only 128 bit is valid). */
158  uint32_t AdataSize, /*!< [in] Full byte length of additional (associated) data. If set to zero,
159  calling ::CRYS_AESCCM_BlockAdata on the same context would return an error. */
160  uint32_t TextSizeQ, /*!< [in] Full length of plain text data. */
161  uint8_t *N_ptr, /*!< [in] Pointer to the Nonce. */
162  uint8_t SizeOfN, /*!< [in] Nonce byte size. The valid values depend on the ccm mode:
163  <ul><li>CCM: valid values = [7 .. 13].</li>
164  <li>CCM*: valid values = [13].</li></ul> */
165  uint8_t SizeOfT, /*!< [in] AES-CCM MAC (tag) byte size. The valid values depend on the ccm mode:
166  <ul><li>CCM: valid values = [4, 6, 8, 10, 12, 14, 16].</li>
167  <li>CCM*: valid values = [0, 4, 8, 16].</li></ul>*/
168  uint32_t ccmMode /*!< [in] Flag specifying whether AES-CCM or AES-CCM* should be performed. */
169 );
170 
171 /*! Macro defintion for CRYS_AESCCM_Init (AES CCM non-star implementation). */
172 #define CRYS_AESCCM_Init(ContextID_ptr, EncrDecrMode, CCM_Key, KeySizeId, AdataSize, TextSizeQ, N_ptr, SizeOfN, SizeOfT) \
173  CC_AESCCM_Init(ContextID_ptr, EncrDecrMode, CCM_Key, KeySizeId, AdataSize, TextSizeQ, N_ptr, SizeOfN, SizeOfT, CRYS_AESCCM_MODE_CCM)
174 
175 /*! Macro defintion CRYS_AESCCMStar_Init (AES CCM star implementation). */
176 #define CRYS_AESCCMStar_Init(ContextID_ptr, EncrDecrMode, CCM_Key, KeySizeId, AdataSize, TextSizeQ, N_ptr, SizeOfN, SizeOfT) \
177  CC_AESCCM_Init(ContextID_ptr, EncrDecrMode, CCM_Key, KeySizeId, AdataSize, TextSizeQ, N_ptr, SizeOfN, SizeOfT, CRYS_AESCCM_MODE_STAR)
178 
179 /*!
180 @brief This function receives a CCM context and a block of additional data, and adds it to the AES MAC
181 calculation.
182 This API can be called only once per operation context. It should not be called in case AdataSize was set to
183 zero in ::CC_AESCCM_Init.
184 
185 @return CRYS_OK on success.
186 @return A non-zero value on failure as defined crys_aesccm_error.h.
187 */
189  CRYS_AESCCM_UserContext_t *ContextID_ptr, /*!< [in] Pointer to the context buffer. */
190  uint8_t *DataIn_ptr, /*!< [in] Pointer to the additional input data. The buffer must be contiguous. */
191  uint32_t DataInSize /*!< [in] Byte size of the additional data. Must match AdataSize parameter provided to
192  ::CRYS_AESCCM_Init. */
193 );
194 
195 /*!
196 @brief This function can be invoked for any block of Text data whose size is a multiple of 16 bytes,
197 excluding the last block that must be processed by ::CRYS_AESCCM_Finish.
198 <ul><li> If encrypting:
199  Continues calculation of the intermediate AES_MAC value of the text data, while simultaneously encrypting the text data using AES_CTR,
200  starting from CTR value = CTR0+1.</li>
201 <li>If decrypting:
202  Continues decryption of the text data, while calculating the intermediate AES_MAC value of decrypted data.</li></ul>
203 
204 @return CRYS_OK on success.
205 @return A non-zero value on failure as defined crys_aesccm_error.h.
206 */
208  CRYS_AESCCM_UserContext_t *ContextID_ptr, /*!< [in] Pointer to the context buffer. */
209  uint8_t *DataIn_ptr, /*!< [in] Pointer to the additional input data. The buffer must be contiguous. */
210  uint32_t DataInSize, /*!< [in] Byte size of the text data block. Must be a multiple of 16 bytes. */
211  uint8_t *DataOut_ptr /*!< [out] Pointer to the output data. The size of the output buffer must be at least DataInSize.
212  The buffer must be contiguous. */
213 );
214 
215 /*!
216 @brief This function must be the last to be called on the text data.
217 It can either be called on the entire text data (if transferred as one block), or on the last block of the text data,
218 even if total size of text data is equal to 0.
219 It performs the same operations as ::CRYS_AESCCM_BlockTextData, but additionally:
220 <ul><li> If encrypting: </li>
221  <ul><li>If the size of text data is not in multiples of 16 bytes, it pads the remaining bytes with zeros to a full 16-bytes block and
222  processes the data using AES_MAC and AES_CTR algorithms.</li>
223  <li> Encrypts the AES_MAC result with AES_CTR using the CTR0 value saved in the context and places the SizeOfT bytes of MAC (tag)
224  at the end.</li></ul></ul>
225 <ul><li> If decrypting: </li>
226  <ul><li>Processes the text data, except for the last SizeOfT bytes (tag), using AES_CTR and then AES_MAC algorithms.</li>
227  <li>Encrypts the calculated MAC using AES_CTR based on the saved CTR0 value, and compares it with SizeOfT last bytes of input data (i.e.
228  tag value).</li>
229  <li>The function saves the validation result (Valid/Invalid) in the context.</li>
230  <li>Returns (as the error code) the final CCM-MAC verification result.</li></ul></ul>
231 
232 @return CRYS_OK on success.
233 @return A non-zero value on failure as defined crys_aesccm_error.h.
234 */
236  CRYS_AESCCM_UserContext_t *ContextID_ptr, /*!< [in] Pointer to the context buffer. */
237  uint8_t *DataIn_ptr, /*!< [in] Pointer to the last input data. The buffer must be contiguous. */
238  uint32_t DataInSize, /*!< [in] Byte size of the last text data block. Can be zero. */
239  uint8_t *DataOut_ptr, /*!< [in] Pointer to the output (cipher or plain text data) data. The buffer must
240  be contiguous. If DataInSize = 0, output buffer is not required. */
241  CRYS_AESCCM_Mac_Res_t MacRes, /*!< [in] MAC result buffer pointer. */
242  uint8_t *SizeOfT /*!< [out] AES-CCM MAC byte size as defined in CRYS_AESCCM_Init. */
243 );
244 
245 /****************************************************************************************************/
246 /******** AESCCM FUNCTION ******/
247 /****************************************************************************************************/
248 /*!
249 @brief AES CCM combines Counter mode encryption with CBC-MAC authentication.
250 Input to CCM includes the following elements:
251 <ul><li> Payload - text data that is both authenticated and encrypted.</li>
252 <li> Associated data (Adata) - data that is authenticated but not encrypted, e.g., a header.</li>
253 <li> Nonce - A unique value that is assigned to the payload and the associated data.</li></ul>
254 
255 @return CRYS_OK on success.
256 @return A non-zero value on failure as defined crys_aesccm_error.h.
257 */
258 CIMPORT_C CRYSError_t CC_AESCCM(
259  SaSiAesEncryptMode_t EncrDecrMode, /*!< [in] A flag specifying whether an AES Encrypt (::SASI_AES_ENCRYPT) or Decrypt
260  (::SASI_AES_DECRYPT) operation should be performed. */
261  CRYS_AESCCM_Key_t CCM_Key, /*!< [in] Pointer to AES-CCM key. */
262  CRYS_AESCCM_KeySize_t KeySizeId, /*!< [in] Enumerator defining the key size (only 128 bit is valid). */
263  uint8_t *N_ptr, /*!< [in] Pointer to the Nonce. */
264  uint8_t SizeOfN, /*!< [in] Nonce byte size. The valid values depend on the ccm mode:
265  <ul><li>CCM: valid values = [7 .. 13].</li>
266  <li>CCM*: valid values = [13].</li></ul> */
267  uint8_t *ADataIn_ptr, /*!< [in] Pointer to the additional input data. The buffer must be contiguous. */
268  uint32_t ADataInSize, /*!< [in] Byte size of the additional data. */
269  uint8_t *TextDataIn_ptr, /*!< [in] Pointer to the plain-text data for encryption or cipher-text data for decryption.
270  The buffer must be contiguous. */
271  uint32_t TextDataInSize, /*!< [in] Byte size of the full text data. */
272  uint8_t *TextDataOut_ptr, /*!< [out] Pointer to the output (cipher or plain text data according to encrypt-decrypt mode)
273  data. The buffer must be contiguous. */
274  uint8_t SizeOfT, /*!< [in] AES-CCM MAC (tag) byte size. The valid values depend on the ccm mode:
275  <ul><li>CCM: valid values = [4, 6, 8, 10, 12, 14, 16].</li>
276  <li>CCM*: valid values = [0, 4, 8, 16].</li></ul>*/
277  CRYS_AESCCM_Mac_Res_t Mac_Res, /*!< [in/out] Pointer to the MAC result buffer. */
278  uint32_t ccmMode /*!< [in] Flag specifying whether AES-CCM or AES-CCM* should be performed. */
279 );
280 
281 /*! Macro defintion for CRYS_AESCCM (AES CCM non-star implementation). */
282 #define CRYS_AESCCM(EncrDecrMode, CCM_Key, KeySizeId, N_ptr, SizeOfN, ADataIn_ptr, ADataInSize, TextDataIn_ptr, TextDataInSize, TextDataOut_ptr, SizeOfT, Mac_Res) \
283  CC_AESCCM(EncrDecrMode, CCM_Key, KeySizeId, N_ptr, SizeOfN, ADataIn_ptr, ADataInSize, TextDataIn_ptr, TextDataInSize, TextDataOut_ptr, SizeOfT, Mac_Res, CRYS_AESCCM_MODE_CCM)
284 
285 /*! Macro defintion for CRYS_AESCCMStar (AES CCM star implementation). */
286 #define CRYS_AESCCMStar(EncrDecrMode, CCM_Key, KeySizeId, N_ptr, SizeOfN, ADataIn_ptr, ADataInSize, TextDataIn_ptr, TextDataInSize, TextDataOut_ptr, SizeOfT, Mac_Res) \
287  CC_AESCCM(EncrDecrMode, CCM_Key, KeySizeId, N_ptr, SizeOfN, ADataIn_ptr, ADataInSize, TextDataIn_ptr, TextDataInSize, TextDataOut_ptr, SizeOfT, Mac_Res, CRYS_AESCCM_MODE_STAR)
288 
289 
290 /*!
291 @brief This function receives the MAC source address, the frame counter and the MAC size
292 and returns the required nonce for AES-CCM* as defined in ieee-802.15.4.
293 This API should be called before CRYS_AESCCMStar and CRYS_AESCCMStar_Init,
294 and the generated nonce should be provided to these functions.
295 
296 @return CRYS_OK on success.
297 @return A non-zero value on failure as defined crys_aesccm_error.h.
298 */
300  CRYS_AESCCMStar_SourceAddress_t srcAddr, /*!< [in] The MAC address in EUI-64 format. */
301  uint32_t FrameCounter, /*!< [in] The MAC frame counter. */
302  uint8_t SizeOfT, /*!< [in] AES-CCM* MAC (tag) byte size. Valid values = [0,4,8,16]. */
303  CRYS_AESCCMStar_Nonce_t nonce /*!< [out] The required nonce for AES-CCM*. */
304 );
305 
306 #ifdef __cplusplus
307 }
308 #endif
309 
310 /**
311 @}
312  */
313 
314 #endif /*#ifndef CRYS_AESCCM_H*/
315 
uint8_t CRYS_AESCCMStar_Nonce_t[13]
Definition: crys_aesccm.h:129
CRYSError_t CC_AESCCM_Init(CRYS_AESCCM_UserContext_t *ContextID_ptr, SaSiAesEncryptMode_t EncrDecrMode, CRYS_AESCCM_Key_t CCM_Key, CRYS_AESCCM_KeySize_t KeySizeId, uint32_t AdataSize, uint32_t TextSizeQ, uint8_t *N_ptr, uint8_t SizeOfN, uint8_t SizeOfT, uint32_t ccmMode)
This function initializes the AES CCM context.
#define SASI_AES_BLOCK_SIZE_IN_BYTES
Definition: ssi_aes_defs.h:64
#define CRYS_AESCCM_STAR_SOURCE_ADDRESS_SIZE_BYTES
Definition: crys_aesccm.h:95
CRYSError_t CRYS_AESCCM_Finish(CRYS_AESCCM_UserContext_t *ContextID_ptr, uint8_t *DataIn_ptr, uint32_t DataInSize, uint8_t *DataOut_ptr, CRYS_AESCCM_Mac_Res_t MacRes, uint8_t *SizeOfT)
This function must be the last to be called on the text data. It can either be called on the entire t...
uint8_t CRYS_AESCCMStar_SourceAddress_t[8]
Definition: crys_aesccm.h:127
uint8_t CRYS_AESCCM_Key_t[8 *sizeof(uint32_t)]
Definition: crys_aesccm.h:122
CRYSError_t CRYS_AESCCM_BlockAdata(CRYS_AESCCM_UserContext_t *ContextID_ptr, uint8_t *DataIn_ptr, uint32_t DataInSize)
This function receives a CCM context and a block of additional data, and adds it to the AES MAC calcu...
struct CRYS_AESCCM_UserContext_t CRYS_AESCCM_UserContext_t
CRYSError_t CRYS_AESCCMStar_NonceGenerate(CRYS_AESCCMStar_SourceAddress_t srcAddr, uint32_t FrameCounter, uint8_t SizeOfT, CRYS_AESCCMStar_Nonce_t nonce)
This function receives the MAC source address, the frame counter and the MAC size and returns the req...
CRYSError_t CRYS_AESCCM_BlockTextData(CRYS_AESCCM_UserContext_t *ContextID_ptr, uint8_t *DataIn_ptr, uint32_t DataInSize, uint8_t *DataOut_ptr)
This function can be invoked for any block of Text data whose size is a multiple of 16 bytes...
#define CRYS_AESCCM_USER_CTX_SIZE_IN_WORDS
Definition: crys_aesccm.h:77
uint32_t buff[(152/4)]
Definition: crys_aesccm.h:136
#define CRYS_AESCCM_KEY_SIZE_WORDS
Definition: crys_aesccm.h:80
SaSiAesEncryptMode_t
Definition: ssi_aes.h:65
#define CRYS_AESCCM_STAR_NONCE_SIZE_BYTES
Definition: crys_aesccm.h:93
CRYSError_t CC_AESCCM(SaSiAesEncryptMode_t EncrDecrMode, CRYS_AESCCM_Key_t CCM_Key, CRYS_AESCCM_KeySize_t KeySizeId, uint8_t *N_ptr, uint8_t SizeOfN, uint8_t *ADataIn_ptr, uint32_t ADataInSize, uint8_t *TextDataIn_ptr, uint32_t TextDataInSize, uint8_t *TextDataOut_ptr, uint8_t SizeOfT, CRYS_AESCCM_Mac_Res_t Mac_Res, uint32_t ccmMode)
AES CCM combines Counter mode encryption with CBC-MAC authentication. Input to CCM includes the follo...
uint8_t CRYS_AESCCM_Mac_Res_t[(4 *sizeof(uint32_t))]
Definition: crys_aesccm.h:124
This file contains all of the enums and definitions that are used for the CryptoCell AES APIs...
uint32_t CRYSError_t
Definition: crys_error.h:253
This file contains the platform dependent definitions and types.
CRYS_AESCCM_KeySize_t
Definition: crys_aesccm.h:105
This module defines the error return code types and the numbering spaces of the error codes for each ...
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.