ssi_aes.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 /*! @file
00037 @brief This file contains all of the enums and definitions that are used for the
00038 CryptoCell AES APIs, as well as the APIs themselves.
00039 @defgroup ssi_aes CryptoCell AES APIs
00040 @{
00041 @ingroup cryptocell_api
00042 */
00043 
00044 #ifndef SSI_AES_H
00045 #define SSI_AES_H
00046 
00047 #include "ssi_pal_types.h"
00048 #include "ssi_aes_error.h"
00049 #include "ssi_aes_defs.h"
00050 
00051 
00052 #ifdef __cplusplus
00053 extern "C"
00054 {
00055 #endif
00056 
00057 /************************ Defines ******************************/
00058 
00059 
00060 /************************ Enums ********************************/
00061 
00062 /*!
00063 Encrypt or Decrypt operation mode.
00064 */
00065 typedef enum {
00066     /*! Encrypt operation. */
00067     SASI_AES_ENCRYPT  = 0,
00068     /*! Decrypt operation. */
00069     SASI_AES_DECRYPT  = 1,
00070     /*! Maximal number of operations. */
00071     SASI_AES_NUM_OF_ENCRYPT_MODES ,
00072     /*! Reserved. */
00073     SASI_AES_ENCRYPT_MODE_LAST  = 0x7FFFFFFF
00074 }SaSiAesEncryptMode_t ;
00075 
00076 /*!
00077 AES operation mode.
00078 */
00079 typedef enum {
00080     SASI_AES_MODE_ECB           = 0,     /*!< ECB mode. */
00081     SASI_AES_MODE_CBC           = 1,     /*!< CBC mode. */
00082     SASI_AES_MODE_CBC_MAC       = 2,     /*!< CBC-MAC mode. */
00083     SASI_AES_MODE_CTR           = 3,     /*!< CTR mode. */
00084     SASI_AES_MODE_XCBC_MAC      = 4,     /*!< XCBC-MAC mode. */
00085     SASI_AES_MODE_CMAC          = 5,     /*!< CMAC mode. */
00086     SASI_AES_MODE_XTS           = 6,     /*!< XTS mode. */
00087     SASI_AES_MODE_CBC_CTS       = 7,     /*!< CBC-CTS mode. */
00088     SASI_AES_MODE_OFB           = 8,     /*!< OFB mode. */
00089 
00090     /*! Maximal number of AES modes */
00091     SASI_AES_NUM_OF_OPERATION_MODES ,
00092     /*! Reserved. */
00093     SASI_AES_OPERATION_MODE_LAST  = 0x7FFFFFFF
00094 }SaSiAesOperationMode_t ;
00095 
00096 /*!
00097 AES padding type.
00098 */
00099 typedef enum {
00100        SASI_AES_PADDING_NONE   = 0,      /*!< No padding. */
00101        SASI_AES_PADDING_PKCS7  = 1,      /*!< PKCS7 padding. */
00102 
00103     /*! Maximal number of AES padding modes */
00104        SASI_AES_NUM_OF_PADDING_TYPES ,
00105     /*! Reserved. */
00106        SASI_AES_PADDING_TYPE_LAST  = 0x7FFFFFFF
00107 }SaSiAesPaddingType_t ;
00108 
00109 /*!
00110 AES key type.
00111 */
00112 typedef enum {
00113     SASI_AES_USER_KEY           = 0,     /*!< user key. */
00114     SASI_AES_PLATFORM_KEY       = 1,     /*!< Kplt hardware key. */
00115     SASI_AES_CUSTOMER_KEY       = 2,     /*!< Kcst hardware key. */
00116 
00117     /*! Maximal number of AES key types */
00118     SASI_AES_NUM_OF_KEY_TYPES ,
00119     /*! Reserved. */
00120     SASI_AES_KEY_TYPE_LAST  = 0x7FFFFFFF
00121 }SaSiAesKeyType_t ;
00122 
00123 /************************ Typedefs  ****************************/
00124 
00125 /*! Defines the IV buffer  - 16 bytes array. */
00126 typedef uint8_t SaSiAesIv_t [SASI_AES_IV_SIZE_IN_BYTES];
00127 
00128 /*! Defines the AES key data buffer. */
00129 typedef uint8_t SaSiAesKeyBuffer_t [SASI_AES_KEY_MAX_SIZE_IN_BYTES];
00130 
00131 /************************ Structs  ******************************/
00132 
00133 /*! The user's context prototype - the argument type that is passed by the user
00134    to the AES APIs. The context saves the state of the operation and must be saved by the user
00135    till the end of the APIs flow*/
00136 typedef struct SaSiAesUserContext_t  {
00137     /*! Context buffer for internal usage. */
00138     uint32_t buff [SASI_AES_USER_CTX_SIZE_IN_WORDS];
00139 }SaSiAesUserContext_t ;
00140 
00141 
00142 /*! AES User Key Data. */
00143 typedef struct SaSiAesUserKeyData_t  {
00144     uint8_t * pKey ;     /*!< Pointer to the key. */
00145     size_t    keySize ;  /*!< The key size in bytes. Valid values:
00146                       <ul><li> For XTS mode - 32 or 64 byte, indicating the full size of the double key (2x128 or 2x256 bit).</li>
00147                       <li>For XCBC-MAC mode - 16 byte (limited by the standard).</li>
00148                       <li>For all other modes - 16, 24 or 32 byte.</li></ul> */
00149 }SaSiAesUserKeyData_t ;
00150 
00151 /*! AES HW Key Data - this structure is likely to be changed when we'll start using it. */
00152 typedef struct SaSiAesHwKeyData_t  {
00153     size_t slotNumber ;      /*!< Slot number. */
00154 }SaSiAesHwKeyData_t ;
00155 
00156 
00157 /************************ Functions *****************************/
00158 
00159 /*!
00160 @brief This function is used to initialize an AES operation context.
00161        To operate the AES machine, this must be the first API called.
00162 
00163 @return SASI_OK on success,
00164 @return A non-zero value from ssi_aes_error.h on failure.
00165 */
00166 CIMPORT_C SaSiError_t  SaSi_AesInit(
00167     SaSiAesUserContext_t  * pContext,            /*!< [in]  Pointer to the AES context buffer that is allocated by the caller and initialized by this API.
00168                                    Should be used in all subsequent calls that are part of the same operation. */
00169     SaSiAesEncryptMode_t    encryptDecryptFlag,  /*!< [in]  A flag specifying whether an AES Encrypt (SASI_AES_Encrypt) or Decrypt (SASI_AES_Decrypt) operation should be performed.
00170                                    Must be set to CRYS_AES_Encrypt in CBC-MAC, XCBC-MAC and CMAC modes. */
00171     SaSiAesOperationMode_t  operationMode,       /*!< [in]  The operation cipher/mode. */
00172     SaSiAesPaddingType_t    paddingType          /*!< [in]  The padding type for AES operation:
00173                                 <ul><li> NONE  - supported for all operation modes.</li>
00174                                 <li> PKCS7 - supported for ECB, CBC, CBC-MAC operation modes.</li></ul> */
00175 );
00176 
00177 
00178 /*!
00179 @brief This function sets the key information for the AES operation, in the context that was initialized by SaSi_AesInit.
00180 \note When FIPS certification mode is set to ON, and the mode is AES-XTS, weak keys are not allowed (128/256 lsb bits must be
00181 different than 128/256 msb bits, according to the key size).
00182 @return SASI_OK on success,
00183 @return A non-zero value from ssi_aes_error.h on failure.
00184 */
00185 CIMPORT_C SaSiError_t  SaSi_AesSetKey(
00186     SaSiAesUserContext_t  * pContext,        /*!< [in]  Pointer to the AES context, after it was initialized by SaSi_AesInit. */
00187     SaSiAesKeyType_t        keyType,         /*!< [in]  The type of key to be used for the AES operation.
00188                                Currently only SASI_AES_USER_KEY is supported - the key is plaintext and provided in the pKeyData parameter. */
00189     void *                 pKeyData,        /*!< [in]  Pointer to the key data structure (to be casted to the relevant struct type). */
00190     size_t                 keyDataSize      /*!< [in]  The size of data passed in pKeyData in bytes. */
00191 );
00192 
00193 
00194 /*!
00195 @brief This function sets the IV, counter or tweak data for the following AES operation on the same context.
00196        The context must be first initialized by SaSi_AesInit.
00197        It must be called at least once prior to the first SaSi_AesBlock operation on the same context - for those ciphers that require it.
00198        If needed, it can also be called to override the IV in the middle of a sequence of SaSi_AesBlock operations.
00199 
00200 @return SASI_OK on success,
00201 @return A non-zero value from ssi_aes_error.h on failure.
00202 */
00203 CIMPORT_C SaSiError_t SaSi_AesSetIv(
00204     SaSiAesUserContext_t  * pContext,    /*!< [in]  Pointer to the AES context. */
00205     SaSiAesIv_t            pIV          /*!< [in]  Pointer to the buffer of the IV, counter or tweak.
00206                             <ul><li> For CBC, CBC-CTS, OFB and CBC-MAC modes - the IV value.</li>
00207                             <li> For CTR mode - the counter.</li>
00208                             <li> For XTS mode - the tweak value.</li>
00209                             <li> For all other modes - N/A. </li></ul>*/
00210 );
00211 
00212 
00213 /*!
00214 @brief This function retrieves the current IV, counter or tweak from the AES context.
00215 
00216 @return SASI_OK on success,
00217 @return A non-zero value from ssi_aes_error.h on failure.
00218 */
00219 CIMPORT_C SaSiError_t SaSi_AesGetIv(
00220     SaSiAesUserContext_t  * pContext,    /*!< [in]  Pointer to the AES context. */
00221     SaSiAesIv_t            pIV          /*!< [out] Pointer to the buffer of the IV, counter or tweak.
00222                             <ul><li> For CBC, CBC-CTS, OFB and CBC-MAC modes - the IV value.</li>
00223                             <li> For CTR mode - the counter.</li>
00224                             <li> For XTS mode - the tweak value.</li>
00225                             <li> For all other modes - N/A. </li></ul> */
00226 );
00227 
00228 
00229 /*!
00230 @brief This function performs an AES operation on an input data buffer, according to the configuration defined in the context parameter.
00231        It can be called as many times as needed, until all the input data is processed.
00232        SaSi_AesInit, SaSi_AesSetKey, and for some ciphers SaSi_AesSetIv, must be called before
00233        the first call to this API with the same context.
00234 
00235 @return SASI_OK on success,
00236 @return A non-zero value from ssi_aes_error.h on failure.
00237 */
00238 CIMPORT_C SaSiError_t  SaSi_AesBlock(
00239     SaSiAesUserContext_t  * pContext,    /*!< [in]  Pointer to the AES context. */
00240     uint8_t *              pDataIn,     /*!< [in]  Pointer to the buffer of the input data to the AES. The pointer does not need to be aligned.
00241                                For TZ, the size of the scatter/gather list representing the data buffer is limited to 128 entries,
00242                                and the size of each entry is limited to 64KB (fragments larger than 64KB are broken into fragments <= 64KB).
00243                                For ARM CryptoCell 3xx, The buffer must be contiguous and limited to 64KB. */
00244     size_t                 dataInSize,  /*!< [in]  Size of the input data in bytes.
00245                             <ul><li> For all modes except XTS, must be multiple of 16 bytes.</li>
00246                             <li> For XTS mode, only the following data sizes are supported: 64, 512, 520, 521, 1024 and 4096 bytes.
00247                                  The data passed in a single SaSi_AesBlock call is considered to be a single XTS unit.
00248                                  All subsequent calls to this API with the same context must use the same data size. </li></ul>*/
00249     uint8_t *              pDataOut     /*!< [out] Pointer to the output buffer. The pointer does not need to be aligned.
00250                                For CBC-MAC, XCBC-MAC, CMAC modes it may be NULL.
00251                                For TZ, the size of the scatter/gather list representing the data buffer is limited to 128 entries,
00252                                and the size of each entry is limited to 64KB (fragments larger than 64KB are broken into fragments <= 64KB).
00253                                For ARM CryptoCell 3xx, The buffer must be contiguous and limited to 64KB. */
00254 );
00255 
00256 
00257 /*!
00258 @brief This function is used to finish AES operation.
00259 
00260        It processes the last data block if needed, finalizes the AES operation (cipher-specific),
00261        and produces operation results (for MAC operations).
00262        \note In case AES padding is used (PKCS#7) Din and Dout user's buffers must include extra space for
00263        the padding scheme.
00264 
00265 @return SASI_OK on success,
00266 @return A non-zero value from ssi_aes_error.h on failure.
00267 */
00268 CIMPORT_C SaSiError_t  SaSi_AesFinish(
00269     SaSiAesUserContext_t  * pContext,       /*!< [in]  Pointer to the AES context. */
00270     size_t                 dataSize,       /*!< [in]  The size of the input data in bytes.
00271                                <ul><li> For CBC-CTS mode, must be > 16. Can be <=16 only if this is the only data (no previous calls were
00272                                         made to SaSi_AesBlock with the same context).</li>
00273                                <li> For XTS mode, the data size must conform to the dataInSize rules as listed for XTS under the
00274                                 SaSi_AesBlock API, and match the data size passed in the previous calls to SaSi_AesBlock with the
00275                                 same context.</li>
00276                                <li> For all other modes, zero is a valid size.</li>
00277                                <li> For ECB, CBC, CBC-MAC modes: </li>
00278                                  <ul><li> Must be >= 0, if direction is SASI_AES_ENCRYPT and padding type is SASI_AES_PADDING_PKCS7.</li>
00279                                  <li> Must be >= 16 and a multiple of 16 bytes, if direction is SASI_AES_DECRYPT and padding type
00280                                    is SASI_AES_PADDING_PKCS7.</li>
00281                                  <li> Must be a multiple of 16 bytes, otherwise. </li></ul></ul>*/
00282     uint8_t *              pDataIn,        /*!< [in]  Pointer of the input data buffer.
00283                               For TZ, the size of the scatter/gather list representing the data buffer is limited to 128 entries,
00284                               and the size of each entry is limited to 64KB (fragments larger than 64KB are broken into fragments <= 64KB).
00285                               For ARM CryptoCell 3xx, The buffer must be contiguous and limited to 64KB. */
00286     size_t                 dataInBuffSize, /*!< [in]  Size of pDataIn buffer in bytes.
00287                                <ul><li> Must be >= dataSize. </li>
00288                                <li> According to padding type, must be >= dataSize + padding. For PKCS7, padding size is
00289                                 maximum SASI_AES_BLOCK_SIZE_IN_BYTES. </li></ul>*/
00290     uint8_t *              pDataOut,       /*!< [out] Pointer to the output buffer.
00291                               For TZ, the size of the scatter/gather list representing the data buffer is limited to 128 entries,
00292                               and the size of each entry is limited to 64KB (fragments larger than 64KB are broken into fragments <= 64KB).
00293                               For ARM CryptoCell 3xx, The buffer must be contiguous and limited to 64KB. */
00294     size_t *               dataOutBuffSize /*!< [in,out]  In - Size of pDataOut buffer in bytes.
00295                               The output buffer size must be no less than:
00296                                <ul><li> For CBC-MAC, XCBC-MAC, CMAC modes - 16 bytes (for MAC result).</li>
00297                                <li> For non-MAC modes - dataInBuffSize.</li></ul>
00298                               Out - The size in bytes of the actual output data:
00299                                <ul><li> If direction is SASI_AES_ENCRYPT and padding type is SASI_AES_PADDING_PKCS7, it is the actual size
00300                                  with the padding.</li>
00301                                <li> If direction is SASI_AES_DECRYPT and padding type is SASI_AES_PADDING_PKCS7, it is the size without
00302                                  the padding. </li>
00303                                <li> For CBC-MAC, XCBC-MAC, CMAC modes - always 16 bytes. </li></ul>*/
00304 );
00305 
00306 
00307 /*!
00308 @brief This function releases and crears resources after AES operations.
00309 
00310 @return SASI_OK on success,
00311 @return A non-zero value from ssi_aes_error.h on failure.
00312 */
00313 CIMPORT_C SaSiError_t  SaSi_AesFree(
00314     SaSiAesUserContext_t  * pContext     /*!< [in] Pointer to the AES context. */
00315 );
00316 
00317 
00318 #ifdef __cplusplus
00319 }
00320 #endif
00321 /**
00322 @}
00323  */
00324 #endif /* #ifndef SSI_AES_H */
00325