mirror of https://github.com/ARMmbed/mbed-os.git
326 lines
16 KiB
C
326 lines
16 KiB
C
/**************************************************************************************
|
|
* 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 */
|
|
|