crys_aesccm.h

00001 /**************************************************************************************
00002 * Copyright (c) 2016-2017, ARM Limited or its affiliates. All rights reserved         *
00003 *                                                                                     *
00004 * This file and the related binary are licensed under the following license:          *
00005 *                                                                                     *
00006 * ARM Object Code and Header Files License, v1.0 Redistribution.                      *
00007 *                                                                                     *
00008 * Redistribution and use of object code, header files, and documentation, without     *
00009 * modification, are permitted provided that the following conditions are met:         *
00010 *                                                                                     *
00011 * 1) Redistributions must reproduce the above copyright notice and the                *
00012 *    following disclaimer in the documentation and/or other materials                 *
00013 *    provided with the distribution.                                                  *
00014 *                                                                                     *
00015 * 2) Unless to the extent explicitly permitted by law, no reverse                     *
00016 *    engineering, decompilation, or disassembly of is permitted.                      *
00017 *                                                                                     *
00018 * 3) Redistribution and use is permitted solely for the purpose of                    *
00019 *    developing or executing applications that are targeted for use                   *
00020 *    on an ARM-based product.                                                         *
00021 *                                                                                     *
00022 * DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND                  *
00023 * CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT             *
00024 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT,        *
00025 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE          *
00026 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,   *
00027 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED            *
00028 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR              *
00029 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF              *
00030 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING                *
00031 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS                  *
00032 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                        *
00033 **************************************************************************************/
00034 
00035 
00036 
00037 #ifndef CRYS_AESCCM_H
00038 #define CRYS_AESCCM_H
00039 
00040 #include "ssi_pal_types.h"
00041 #include "crys_error.h"
00042 
00043 #include "ssi_aes.h"
00044 
00045 
00046 #ifdef __cplusplus
00047 extern "C"
00048 {
00049 #endif
00050 
00051 /*!
00052 @file
00053 @brief This file contains all of the enums and definitions that are used for the CRYS AESCCM APIs, as well as the APIs themselves.
00054 The API supports AES-CCM and AES-CCM* as defined in ieee-802.15.4.
00055 @defgroup crys_aesccm CryptoCell AES-CCM APIs
00056 @{
00057 @ingroup cryptocell_api
00058 
00059 
00060 @note
00061 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.
00062 in case of AES-CCM* the flow should be as follows:
00063 <ul><li>AES-CCM* integrated</li>
00064         <ul><li>CRYS_AESCCMStar_NonceGenerate</li>
00065         <li>CRYS_AESCCMStar</li></ul></ul>
00066 <ul><li>AES-CCM* non-integrated</li>
00067         <ul><li>CRYS_AESCCMStar_NonceGenerate</li>
00068         <li>CRYS_AESCCMStar_Init</li>
00069         <li>CRYS_AESCCM_BlockAdata</li>
00070         <li>CRYS_AESCCM_BlockTextData</li>
00071         <li>CRYS_AESCCM_Finish</li></ul></ul>
00072 */
00073 
00074 /************************ Defines ******************************/
00075 
00076 /*! AES CCM context size in words.*/
00077 #define CRYS_AESCCM_USER_CTX_SIZE_IN_WORDS (152/4)
00078 
00079 /*! AES CCM maximal key size in words. */
00080 #define CRYS_AESCCM_KEY_SIZE_WORDS           8
00081 
00082 /* nonce and AESCCM-MAC sizes definitions */
00083 /*! AES CCM NONCE minimal size in bytes. */
00084 #define CRYS_AESCCM_NONCE_MIN_SIZE_BYTES     7
00085 /*! AES CCM NONCE maximal size in bytes. */
00086 #define CRYS_AESCCM_NONCE_MAX_SIZE_BYTES    13
00087 /*! AES CCM MAC minimal size in bytes..*/
00088 #define CRYS_AESCCM_MAC_MIN_SIZE_BYTES       4
00089 /*! AES CCM MAC maximal size in bytes. */
00090 #define CRYS_AESCCM_MAC_MAX_SIZE_BYTES      16
00091 
00092 /*! AES CCM star NONCE size in bytes. */
00093 #define CRYS_AESCCM_STAR_NONCE_SIZE_BYTES               13
00094 /*! AES CCM star source address size in bytes. */
00095 #define CRYS_AESCCM_STAR_SOURCE_ADDRESS_SIZE_BYTES      8
00096 
00097 /*! AES CCM mode - CCM. */
00098 #define CRYS_AESCCM_MODE_CCM      0
00099 /*! AES CCM mode - CCM STAR. */
00100 #define CRYS_AESCCM_MODE_STAR     1
00101 
00102 
00103 /************************ Typedefs  ****************************/
00104 /*! AES CCM key sizes. */
00105 typedef enum {
00106     /*! Key size 128 bits. */
00107     CRYS_AES_Key128BitSize    = 0,
00108     /*! Key size 192 bits. */
00109     CRYS_AES_Key192BitSize    = 1,
00110     /*! Key size 256 bits. */
00111     CRYS_AES_Key256BitSize    = 2,
00112     /*! Key size 512 bits. */
00113     CRYS_AES_Key512BitSize    = 3,
00114     /*! Number of optional key sizes. */
00115     CRYS_AES_KeySizeNumOfOptions ,
00116     /*! Reserved. */
00117     CRYS_AES_KeySizeLast     = 0x7FFFFFFF,
00118 
00119 }CRYS_AESCCM_KeySize_t ;
00120 
00121 /*! AES_CCM key buffer definition.*/
00122 typedef uint8_t CRYS_AESCCM_Key_t [CRYS_AESCCM_KEY_SIZE_WORDS * sizeof(uint32_t)];
00123 /*! AES_CCM MAC buffer definition.*/
00124 typedef uint8_t CRYS_AESCCM_Mac_Res_t [SASI_AES_BLOCK_SIZE_IN_BYTES];
00125 
00126 /*! AES_CCM_STAR source address buffer defintion. */
00127 typedef uint8_t CRYS_AESCCMStar_SourceAddress_t [CRYS_AESCCM_STAR_SOURCE_ADDRESS_SIZE_BYTES];
00128 /*! AES_CCM_STAR Nonce buffer defintion. */
00129 typedef uint8_t CRYS_AESCCMStar_Nonce_t [CRYS_AESCCM_STAR_NONCE_SIZE_BYTES];
00130 
00131 /******************* Context Structure  ***********************/
00132 /*! The user's context structure - the argument type that is passed by the user to the AES CCM APIs */
00133 typedef struct CRYS_AESCCM_UserContext_t 
00134 {
00135     /*! AES CCM context buffer for internal usage. */
00136     uint32_t  buff [CRYS_AESCCM_USER_CTX_SIZE_IN_WORDS];
00137 }CRYS_AESCCM_UserContext_t ;
00138 
00139 
00140 /************************ Public Functions **********************/
00141 
00142 /*!
00143 @brief This function initializes the AES CCM context.
00144 
00145 It formats of the input data, calculates AES-MAC value for the formatted B0 block containing control information and
00146 CCM unique value (Nonce), and initializes the AES context structure including the initial CTR0 value.
00147 
00148 @return CRYS_OK on success.
00149 @return A non-zero value on failure as defined crys_aesccm_error.h.
00150 */
00151 CRYSError_t  CC_AESCCM_Init(
00152         CRYS_AESCCM_UserContext_t  *ContextID_ptr,   /*!< [in] Pointer to the AES context buffer that is allocated by the user and is used for
00153                                       the AES operation. */
00154         SaSiAesEncryptMode_t  EncrDecrMode,          /*!< [in] Flag specifying whether Encrypt (::SASI_AES_ENCRYPT) or Decrypt
00155                                       (::SASI_AES_DECRYPT) operation should be performed. */
00156         CRYS_AESCCM_Key_t  CCM_Key,                  /*!< [in] Pointer to the AES-CCM key. */
00157         CRYS_AESCCM_KeySize_t  KeySizeId,            /*!< [in] Enumerator defining the key size (only 128 bit is valid). */
00158         uint32_t AdataSize,                         /*!< [in] Full byte length of additional (associated) data. If set to zero,
00159                                       calling ::CRYS_AESCCM_BlockAdata on the same context would return an error. */
00160         uint32_t TextSizeQ,                         /*!< [in] Full length of plain text data. */
00161         uint8_t *N_ptr,                             /*!< [in] Pointer to the Nonce. */
00162         uint8_t SizeOfN,                            /*!< [in] Nonce byte size. The valid values depend on the ccm mode:
00163                                                                         <ul><li>CCM:  valid values = [7 .. 13].</li>
00164                                                                         <li>CCM*: valid values = [13].</li></ul> */
00165         uint8_t SizeOfT,                            /*!< [in] AES-CCM MAC (tag) byte size. The valid values depend on the ccm mode:
00166                                                                         <ul><li>CCM:  valid values = [4, 6, 8, 10, 12, 14, 16].</li>
00167                                                                         <li>CCM*: valid values = [0, 4, 8, 16].</li></ul>*/
00168                 uint32_t ccmMode                            /*!< [in] Flag specifying whether AES-CCM or AES-CCM* should be performed. */
00169 );
00170 
00171 /*! Macro defintion for CRYS_AESCCM_Init (AES CCM non-star implementation). */
00172 #define CRYS_AESCCM_Init(ContextID_ptr, EncrDecrMode, CCM_Key, KeySizeId, AdataSize, TextSizeQ, N_ptr, SizeOfN, SizeOfT) \
00173         CC_AESCCM_Init(ContextID_ptr, EncrDecrMode, CCM_Key, KeySizeId, AdataSize, TextSizeQ, N_ptr, SizeOfN, SizeOfT, CRYS_AESCCM_MODE_CCM)
00174 
00175 /*! Macro defintion CRYS_AESCCMStar_Init (AES CCM star implementation). */
00176 #define CRYS_AESCCMStar_Init(ContextID_ptr, EncrDecrMode, CCM_Key, KeySizeId, AdataSize, TextSizeQ, N_ptr, SizeOfN, SizeOfT) \
00177         CC_AESCCM_Init(ContextID_ptr, EncrDecrMode, CCM_Key, KeySizeId, AdataSize, TextSizeQ, N_ptr, SizeOfN, SizeOfT, CRYS_AESCCM_MODE_STAR)
00178 
00179 /*!
00180 @brief This function receives a CCM context and a block of additional data, and adds it to the AES MAC
00181 calculation.
00182 This API can be called only once per operation context. It should not be called in case AdataSize was set to
00183 zero in ::CC_AESCCM_Init.
00184 
00185 @return CRYS_OK on success.
00186 @return A non-zero value on failure as defined crys_aesccm_error.h.
00187 */
00188 CRYSError_t  CRYS_AESCCM_BlockAdata(
00189         CRYS_AESCCM_UserContext_t  *ContextID_ptr,   /*!< [in] Pointer to the context buffer. */
00190                 uint8_t *DataIn_ptr,                        /*!< [in] Pointer to the additional input data. The buffer must be contiguous. */
00191                 uint32_t DataInSize                         /*!< [in] Byte size of the additional data. Must match AdataSize parameter provided to
00192                                       ::CRYS_AESCCM_Init. */
00193 );
00194 
00195 /*!
00196 @brief This function can be invoked for any block of Text data whose size is a multiple of 16 bytes,
00197 excluding the last block that must be processed by ::CRYS_AESCCM_Finish.
00198 <ul><li> If encrypting:
00199     Continues calculation of the intermediate AES_MAC value of the text data, while simultaneously encrypting the text data using AES_CTR,
00200     starting from CTR value = CTR0+1.</li>
00201 <li>If decrypting:
00202     Continues decryption of the text data, while calculating the intermediate AES_MAC value of decrypted data.</li></ul>
00203 
00204 @return CRYS_OK on success.
00205 @return A non-zero value on failure as defined crys_aesccm_error.h.
00206 */
00207 CRYSError_t  CRYS_AESCCM_BlockTextData(
00208                 CRYS_AESCCM_UserContext_t  *ContextID_ptr,   /*!< [in] Pointer to the context buffer. */
00209                 uint8_t *DataIn_ptr,                        /*!< [in] Pointer to the additional input data. The buffer must be contiguous. */
00210                 uint32_t DataInSize,                        /*!< [in] Byte size of the text data block. Must be a multiple of 16 bytes. */
00211                 uint8_t *DataOut_ptr                        /*!< [out] Pointer to the output data. The size of the output buffer must be at least DataInSize.
00212                                                                        The buffer must be contiguous. */
00213 );
00214 
00215 /*!
00216 @brief This function must be the last to be called on the text data.
00217 It can either be called on the entire text data (if transferred as one block), or on the last block of the text data,
00218 even if total size of text data is equal to 0.
00219 It performs the same operations as ::CRYS_AESCCM_BlockTextData, but additionally:
00220 <ul><li> If encrypting: </li>
00221      <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
00222      processes the data using AES_MAC and AES_CTR algorithms.</li>
00223     <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)
00224     at the end.</li></ul></ul>
00225 <ul><li> If decrypting: </li>
00226     <ul><li>Processes the text data, except for the last SizeOfT bytes (tag), using AES_CTR and then AES_MAC algorithms.</li>
00227     <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.
00228         tag value).</li>
00229     <li>The function saves the validation result (Valid/Invalid) in the context.</li>
00230     <li>Returns (as the error code) the final CCM-MAC verification result.</li></ul></ul>
00231 
00232 @return CRYS_OK on success.
00233 @return A non-zero value on failure as defined crys_aesccm_error.h.
00234 */
00235 CEXPORT_C CRYSError_t  CRYS_AESCCM_Finish(
00236                 CRYS_AESCCM_UserContext_t  *ContextID_ptr,   /*!< [in] Pointer to the context buffer. */
00237                 uint8_t *DataIn_ptr,                        /*!< [in] Pointer to the last input data. The buffer must be contiguous. */
00238                 uint32_t DataInSize,                        /*!< [in] Byte size of the last text data block. Can be zero. */
00239                 uint8_t *DataOut_ptr,                       /*!< [in] Pointer to the output (cipher or plain text data) data. The buffer must
00240                                               be contiguous. If DataInSize = 0, output buffer is not required. */
00241                 CRYS_AESCCM_Mac_Res_t MacRes,               /*!< [in]  MAC result buffer pointer. */
00242                 uint8_t *SizeOfT                            /*!< [out] AES-CCM MAC byte size as defined in CRYS_AESCCM_Init. */
00243 );
00244 
00245 /****************************************************************************************************/
00246 /********                       AESCCM  FUNCTION                                              ******/
00247 /****************************************************************************************************/
00248 /*!
00249 @brief AES CCM combines Counter mode encryption with CBC-MAC authentication.
00250 Input to CCM includes the following elements:
00251 <ul><li> Payload - text data that is both authenticated and encrypted.</li>
00252 <li> Associated data (Adata) - data that is authenticated but not encrypted, e.g., a header.</li>
00253 <li> Nonce - A unique value that is assigned to the payload and the associated data.</li></ul>
00254 
00255 @return CRYS_OK on success.
00256 @return A non-zero value on failure as defined crys_aesccm_error.h.
00257 */
00258 CIMPORT_C CRYSError_t   CC_AESCCM(
00259                SaSiAesEncryptMode_t        EncrDecrMode,     /*!< [in] A flag specifying whether an AES Encrypt (::SASI_AES_ENCRYPT) or Decrypt
00260                                           (::SASI_AES_DECRYPT) operation should be performed. */
00261                CRYS_AESCCM_Key_t           CCM_Key,          /*!< [in] Pointer to AES-CCM key. */
00262                CRYS_AESCCM_KeySize_t       KeySizeId,        /*!< [in] Enumerator defining the key size (only 128 bit is valid). */
00263                uint8_t                   *N_ptr,            /*!< [in] Pointer to the Nonce. */
00264                uint8_t                    SizeOfN,          /*!< [in] Nonce byte size. The valid values depend on the ccm mode:
00265                                                                                         <ul><li>CCM:  valid values = [7 .. 13].</li>
00266                                                                                         <li>CCM*: valid values = [13].</li></ul> */
00267                uint8_t                   *ADataIn_ptr,      /*!< [in] Pointer to the additional input data. The buffer must be contiguous. */
00268                uint32_t                   ADataInSize,      /*!< [in] Byte size of the additional data. */
00269                uint8_t                   *TextDataIn_ptr,   /*!< [in] Pointer to the plain-text data for encryption or cipher-text data for decryption.
00270                                           The buffer must be contiguous. */
00271                uint32_t                   TextDataInSize,   /*!< [in] Byte size of the full text data. */
00272                uint8_t                   *TextDataOut_ptr,  /*!< [out] Pointer to the output (cipher or plain text data according to encrypt-decrypt mode)
00273                                            data. The buffer must be contiguous. */
00274                uint8_t                    SizeOfT,          /*!< [in] AES-CCM MAC (tag) byte size. The valid values depend on the ccm mode:
00275                                                                                         <ul><li>CCM:  valid values = [4, 6, 8, 10, 12, 14, 16].</li>
00276                                                                                         <li>CCM*: valid values = [0, 4, 8, 16].</li></ul>*/
00277                CRYS_AESCCM_Mac_Res_t      Mac_Res,          /*!< [in/out] Pointer to the MAC result buffer. */
00278                            uint32_t ccmMode                             /*!< [in] Flag specifying whether AES-CCM or AES-CCM* should be performed. */
00279 );
00280 
00281 /*! Macro defintion for CRYS_AESCCM (AES CCM non-star implementation). */
00282 #define CRYS_AESCCM(EncrDecrMode, CCM_Key, KeySizeId, N_ptr, SizeOfN, ADataIn_ptr, ADataInSize, TextDataIn_ptr, TextDataInSize, TextDataOut_ptr, SizeOfT, Mac_Res) \
00283         CC_AESCCM(EncrDecrMode, CCM_Key, KeySizeId, N_ptr, SizeOfN, ADataIn_ptr, ADataInSize, TextDataIn_ptr, TextDataInSize, TextDataOut_ptr, SizeOfT, Mac_Res, CRYS_AESCCM_MODE_CCM)
00284 
00285 /*! Macro defintion for CRYS_AESCCMStar (AES CCM star implementation). */
00286 #define CRYS_AESCCMStar(EncrDecrMode, CCM_Key, KeySizeId, N_ptr, SizeOfN, ADataIn_ptr, ADataInSize, TextDataIn_ptr, TextDataInSize, TextDataOut_ptr, SizeOfT, Mac_Res) \
00287         CC_AESCCM(EncrDecrMode, CCM_Key, KeySizeId, N_ptr, SizeOfN, ADataIn_ptr, ADataInSize, TextDataIn_ptr, TextDataInSize, TextDataOut_ptr, SizeOfT, Mac_Res, CRYS_AESCCM_MODE_STAR)
00288 
00289 
00290 /*!
00291 @brief This function receives the MAC source address, the frame counter and the MAC size
00292 and returns the required nonce for AES-CCM* as defined in ieee-802.15.4.
00293 This API should be called before CRYS_AESCCMStar and CRYS_AESCCMStar_Init,
00294 and the generated nonce should be provided to these functions.
00295 
00296 @return CRYS_OK on success.
00297 @return A non-zero value on failure as defined crys_aesccm_error.h.
00298 */
00299 CRYSError_t  CRYS_AESCCMStar_NonceGenerate(
00300         CRYS_AESCCMStar_SourceAddress_t srcAddr,        /*!< [in]  The MAC address in EUI-64 format. */
00301         uint32_t FrameCounter,                          /*!< [in]  The MAC frame counter. */
00302         uint8_t SizeOfT,                                /*!< [in]  AES-CCM* MAC (tag) byte size. Valid values = [0,4,8,16]. */
00303         CRYS_AESCCMStar_Nonce_t nonce                   /*!< [out] The required nonce for AES-CCM*. */
00304 );
00305 
00306 #ifdef __cplusplus
00307 }
00308 #endif
00309 
00310 /**
00311 @}
00312  */
00313 
00314 #endif /*#ifndef CRYS_AESCCM_H*/
00315