/************************************************************************************** * Copyright (c) 2016-2017, ARM Limited or its affiliates. All rights reserved * * * * This file and the related binary are licensed under the following license: * * * * ARM Object Code and Header Files License, v1.0 Redistribution. * * * * Redistribution and use of object code, header files, and documentation, without * * modification, are permitted provided that the following conditions are met: * * * * 1) Redistributions must reproduce the above copyright notice and the * * following disclaimer in the documentation and/or other materials * * provided with the distribution. * * * * 2) Unless to the extent explicitly permitted by law, no reverse * * engineering, decompilation, or disassembly of is permitted. * * * * 3) Redistribution and use is permitted solely for the purpose of * * developing or executing applications that are targeted for use * * on an ARM-based product. * * * * DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND * * CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT * * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, * * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE * * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED * * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR * * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF * * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING * * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS * * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * **************************************************************************************/ /*! @file @brief This file contains all of the enums and definitions that are used for the CryptoCell AES APIs, as well as the APIs themselves. @defgroup ssi_aes CryptoCell AES APIs @{ @ingroup cryptocell_api */ #ifndef SSI_AES_H #define SSI_AES_H #include "ssi_pal_types.h" #include "ssi_aes_error.h" #include "ssi_aes_defs.h" #ifdef __cplusplus extern "C" { #endif /************************ Defines ******************************/ /************************ Enums ********************************/ /*! Encrypt or Decrypt operation mode. */ typedef enum { /*! Encrypt operation. */ SASI_AES_ENCRYPT = 0, /*! Decrypt operation. */ SASI_AES_DECRYPT = 1, /*! Maximal number of operations. */ SASI_AES_NUM_OF_ENCRYPT_MODES, /*! Reserved. */ SASI_AES_ENCRYPT_MODE_LAST = 0x7FFFFFFF }SaSiAesEncryptMode_t; /*! AES operation mode. */ typedef enum { SASI_AES_MODE_ECB = 0, /*!< ECB mode. */ SASI_AES_MODE_CBC = 1, /*!< CBC mode. */ SASI_AES_MODE_CBC_MAC = 2, /*!< CBC-MAC mode. */ SASI_AES_MODE_CTR = 3, /*!< CTR mode. */ SASI_AES_MODE_XCBC_MAC = 4, /*!< XCBC-MAC mode. */ SASI_AES_MODE_CMAC = 5, /*!< CMAC mode. */ SASI_AES_MODE_XTS = 6, /*!< XTS mode. */ SASI_AES_MODE_CBC_CTS = 7, /*!< CBC-CTS mode. */ SASI_AES_MODE_OFB = 8, /*!< OFB mode. */ /*! Maximal number of AES modes */ SASI_AES_NUM_OF_OPERATION_MODES, /*! Reserved. */ SASI_AES_OPERATION_MODE_LAST = 0x7FFFFFFF }SaSiAesOperationMode_t; /*! AES padding type. */ typedef enum { SASI_AES_PADDING_NONE = 0, /*!< No padding. */ SASI_AES_PADDING_PKCS7 = 1, /*!< PKCS7 padding. */ /*! Maximal number of AES padding modes */ SASI_AES_NUM_OF_PADDING_TYPES, /*! Reserved. */ SASI_AES_PADDING_TYPE_LAST = 0x7FFFFFFF }SaSiAesPaddingType_t; /*! AES key type. */ typedef enum { SASI_AES_USER_KEY = 0, /*!< user key. */ SASI_AES_PLATFORM_KEY = 1, /*!< Kplt hardware key. */ SASI_AES_CUSTOMER_KEY = 2, /*!< Kcst hardware key. */ /*! Maximal number of AES key types */ SASI_AES_NUM_OF_KEY_TYPES, /*! Reserved. */ SASI_AES_KEY_TYPE_LAST = 0x7FFFFFFF }SaSiAesKeyType_t; /************************ Typedefs ****************************/ /*! Defines the IV buffer - 16 bytes array. */ typedef uint8_t SaSiAesIv_t[SASI_AES_IV_SIZE_IN_BYTES]; /*! Defines the AES key data buffer. */ typedef uint8_t SaSiAesKeyBuffer_t[SASI_AES_KEY_MAX_SIZE_IN_BYTES]; /************************ Structs ******************************/ /*! The user's context prototype - the argument type that is passed by the user to the AES APIs. The context saves the state of the operation and must be saved by the user till the end of the APIs flow*/ typedef struct SaSiAesUserContext_t { /*! Context buffer for internal usage. */ uint32_t buff[SASI_AES_USER_CTX_SIZE_IN_WORDS]; }SaSiAesUserContext_t; /*! AES User Key Data. */ typedef struct SaSiAesUserKeyData_t { uint8_t * pKey; /*!< Pointer to the key. */ size_t keySize; /*!< The key size in bytes. Valid values: */ }SaSiAesUserKeyData_t; /*! AES HW Key Data - this structure is likely to be changed when we'll start using it. */ typedef struct SaSiAesHwKeyData_t { size_t slotNumber; /*!< Slot number. */ }SaSiAesHwKeyData_t; /************************ Functions *****************************/ /*! @brief This function is used to initialize an AES operation context. To operate the AES machine, this must be the first API called. @return SASI_OK on success, @return A non-zero value from ssi_aes_error.h on failure. */ CIMPORT_C SaSiError_t SaSi_AesInit( SaSiAesUserContext_t * pContext, /*!< [in] Pointer to the AES context buffer that is allocated by the caller and initialized by this API. Should be used in all subsequent calls that are part of the same operation. */ SaSiAesEncryptMode_t encryptDecryptFlag, /*!< [in] A flag specifying whether an AES Encrypt (SASI_AES_Encrypt) or Decrypt (SASI_AES_Decrypt) operation should be performed. Must be set to CRYS_AES_Encrypt in CBC-MAC, XCBC-MAC and CMAC modes. */ SaSiAesOperationMode_t operationMode, /*!< [in] The operation cipher/mode. */ SaSiAesPaddingType_t paddingType /*!< [in] The padding type for AES operation: */ ); /*! @brief This function sets the key information for the AES operation, in the context that was initialized by SaSi_AesInit. \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 different than 128/256 msb bits, according to the key size). @return SASI_OK on success, @return A non-zero value from ssi_aes_error.h on failure. */ CIMPORT_C SaSiError_t SaSi_AesSetKey( SaSiAesUserContext_t * pContext, /*!< [in] Pointer to the AES context, after it was initialized by SaSi_AesInit. */ SaSiAesKeyType_t keyType, /*!< [in] The type of key to be used for the AES operation. Currently only SASI_AES_USER_KEY is supported - the key is plaintext and provided in the pKeyData parameter. */ void * pKeyData, /*!< [in] Pointer to the key data structure (to be casted to the relevant struct type). */ size_t keyDataSize /*!< [in] The size of data passed in pKeyData in bytes. */ ); /*! @brief This function sets the IV, counter or tweak data for the following AES operation on the same context. The context must be first initialized by SaSi_AesInit. It must be called at least once prior to the first SaSi_AesBlock operation on the same context - for those ciphers that require it. If needed, it can also be called to override the IV in the middle of a sequence of SaSi_AesBlock operations. @return SASI_OK on success, @return A non-zero value from ssi_aes_error.h on failure. */ CIMPORT_C SaSiError_t SaSi_AesSetIv( SaSiAesUserContext_t * pContext, /*!< [in] Pointer to the AES context. */ SaSiAesIv_t pIV /*!< [in] Pointer to the buffer of the IV, counter or tweak. */ ); /*! @brief This function retrieves the current IV, counter or tweak from the AES context. @return SASI_OK on success, @return A non-zero value from ssi_aes_error.h on failure. */ CIMPORT_C SaSiError_t SaSi_AesGetIv( SaSiAesUserContext_t * pContext, /*!< [in] Pointer to the AES context. */ SaSiAesIv_t pIV /*!< [out] Pointer to the buffer of the IV, counter or tweak. */ ); /*! @brief This function performs an AES operation on an input data buffer, according to the configuration defined in the context parameter. It can be called as many times as needed, until all the input data is processed. SaSi_AesInit, SaSi_AesSetKey, and for some ciphers SaSi_AesSetIv, must be called before the first call to this API with the same context. @return SASI_OK on success, @return A non-zero value from ssi_aes_error.h on failure. */ CIMPORT_C SaSiError_t SaSi_AesBlock( SaSiAesUserContext_t * pContext, /*!< [in] Pointer to the AES context. */ uint8_t * pDataIn, /*!< [in] Pointer to the buffer of the input data to the AES. The pointer does not need to be aligned. For TZ, the size of the scatter/gather list representing the data buffer is limited to 128 entries, and the size of each entry is limited to 64KB (fragments larger than 64KB are broken into fragments <= 64KB). For ARM CryptoCell 3xx, The buffer must be contiguous and limited to 64KB. */ size_t dataInSize, /*!< [in] Size of the input data in bytes. */ uint8_t * pDataOut /*!< [out] Pointer to the output buffer. The pointer does not need to be aligned. For CBC-MAC, XCBC-MAC, CMAC modes it may be NULL. For TZ, the size of the scatter/gather list representing the data buffer is limited to 128 entries, and the size of each entry is limited to 64KB (fragments larger than 64KB are broken into fragments <= 64KB). For ARM CryptoCell 3xx, The buffer must be contiguous and limited to 64KB. */ ); /*! @brief This function is used to finish AES operation. It processes the last data block if needed, finalizes the AES operation (cipher-specific), and produces operation results (for MAC operations). \note In case AES padding is used (PKCS#7) Din and Dout user's buffers must include extra space for the padding scheme. @return SASI_OK on success, @return A non-zero value from ssi_aes_error.h on failure. */ CIMPORT_C SaSiError_t SaSi_AesFinish( SaSiAesUserContext_t * pContext, /*!< [in] Pointer to the AES context. */ size_t dataSize, /*!< [in] The size of the input data in bytes. */ uint8_t * pDataIn, /*!< [in] Pointer of the input data buffer. For TZ, the size of the scatter/gather list representing the data buffer is limited to 128 entries, and the size of each entry is limited to 64KB (fragments larger than 64KB are broken into fragments <= 64KB). For ARM CryptoCell 3xx, The buffer must be contiguous and limited to 64KB. */ size_t dataInBuffSize, /*!< [in] Size of pDataIn buffer in bytes. */ uint8_t * pDataOut, /*!< [out] Pointer to the output buffer. For TZ, the size of the scatter/gather list representing the data buffer is limited to 128 entries, and the size of each entry is limited to 64KB (fragments larger than 64KB are broken into fragments <= 64KB). For ARM CryptoCell 3xx, The buffer must be contiguous and limited to 64KB. */ size_t * dataOutBuffSize /*!< [in,out] In - Size of pDataOut buffer in bytes. The output buffer size must be no less than: Out - The size in bytes of the actual output data: */ ); /*! @brief This function releases and crears resources after AES operations. @return SASI_OK on success, @return A non-zero value from ssi_aes_error.h on failure. */ CIMPORT_C SaSiError_t SaSi_AesFree( SaSiAesUserContext_t * pContext /*!< [in] Pointer to the AES context. */ ); #ifdef __cplusplus } #endif /** @} */ #endif /* #ifndef SSI_AES_H */