diff options
Diffstat (limited to 'thirdparty/nRF5_SDK_15.0.0_a53641a/external/nrf_cc310_bl/include/ssi_aes.h')
| -rw-r--r-- | thirdparty/nRF5_SDK_15.0.0_a53641a/external/nrf_cc310_bl/include/ssi_aes.h | 325 |
1 files changed, 325 insertions, 0 deletions
diff --git a/thirdparty/nRF5_SDK_15.0.0_a53641a/external/nrf_cc310_bl/include/ssi_aes.h b/thirdparty/nRF5_SDK_15.0.0_a53641a/external/nrf_cc310_bl/include/ssi_aes.h new file mode 100644 index 0000000..a42b65f --- /dev/null +++ b/thirdparty/nRF5_SDK_15.0.0_a53641a/external/nrf_cc310_bl/include/ssi_aes.h @@ -0,0 +1,325 @@ +/************************************************************************************** +* 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 */ + |