Mbed OS Reference | ssi_aes.h Source File

Go to the documentation of this file.
 /**************************************************************************************
 * 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:
                       <ul><li> For XTS mode - 32 or 64 byte, indicating the full size of the double key (2x128 or 2x256 bit).</li>
                       <li>For XCBC-MAC mode - 16 byte (limited by the standard).</li>
                       <li>For all other modes - 16, 24 or 32 byte.</li></ul> */
 }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:
                                 <ul><li> NONE  - supported for all operation modes.</li>
                                 <li> PKCS7 - supported for ECB, CBC, CBC-MAC operation modes.</li></ul> */
 );
 
 
 /*!
 @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.
                             <ul><li> For CBC, CBC-CTS, OFB and CBC-MAC modes - the IV value.</li>
                             <li> For CTR mode - the counter.</li>
                             <li> For XTS mode - the tweak value.</li>
                             <li> For all other modes - N/A. </li></ul>*/
 );
 
 
 /*!
 @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.
                             <ul><li> For CBC, CBC-CTS, OFB and CBC-MAC modes - the IV value.</li>
                             <li> For CTR mode - the counter.</li>
                             <li> For XTS mode - the tweak value.</li>
                             <li> For all other modes - N/A. </li></ul> */
 );
 
 
 /*!
 @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.
                             <ul><li> For all modes except XTS, must be multiple of 16 bytes.</li>
                             <li> For XTS mode, only the following data sizes are supported: 64, 512, 520, 521, 1024 and 4096 bytes.
                                  The data passed in a single SaSi_AesBlock call is considered to be a single XTS unit.
                                  All subsequent calls to this API with the same context must use the same data size. </li></ul>*/
     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.
                                <ul><li> For CBC-CTS mode, must be > 16. Can be <=16 only if this is the only data (no previous calls were
                                         made to SaSi_AesBlock with the same context).</li>
                                <li> For XTS mode, the data size must conform to the dataInSize rules as listed for XTS under the
                                 SaSi_AesBlock API, and match the data size passed in the previous calls to SaSi_AesBlock with the
                                 same context.</li>
                                <li> For all other modes, zero is a valid size.</li>
                                <li> For ECB, CBC, CBC-MAC modes: </li>
                                  <ul><li> Must be >= 0, if direction is SASI_AES_ENCRYPT and padding type is SASI_AES_PADDING_PKCS7.</li>
                                  <li> Must be >= 16 and a multiple of 16 bytes, if direction is SASI_AES_DECRYPT and padding type
                                    is SASI_AES_PADDING_PKCS7.</li>
                                  <li> Must be a multiple of 16 bytes, otherwise. </li></ul></ul>*/
     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.
                                <ul><li> Must be >= dataSize. </li>
                                <li> According to padding type, must be >= dataSize + padding. For PKCS7, padding size is
                                 maximum SASI_AES_BLOCK_SIZE_IN_BYTES. </li></ul>*/
     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:
                                <ul><li> For CBC-MAC, XCBC-MAC, CMAC modes - 16 bytes (for MAC result).</li>
                                <li> For non-MAC modes - dataInBuffSize.</li></ul>
                               Out - The size in bytes of the actual output data:
                                <ul><li> If direction is SASI_AES_ENCRYPT and padding type is SASI_AES_PADDING_PKCS7, it is the actual size
                                  with the padding.</li>
                                <li> If direction is SASI_AES_DECRYPT and padding type is SASI_AES_PADDING_PKCS7, it is the size without
                                  the padding. </li>
                                <li> For CBC-MAC, XCBC-MAC, CMAC modes - always 16 bytes. </li></ul>*/
 );
 
 
 /*!
 @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 */
 
Important Information for this Arm website
