Kenji Arai / mbed-os_TYBLE16

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

Embed: (wiki syntax)

« Back to documentation index

CryptoCell AES APIs
Data Structures | Modules | Typedefs | Enumerations | Functions

CryptoCell AES APIs

Data Structures

struct  SaSiAesUserContext_t
struct  SaSiAesUserKeyData_t
struct  SaSiAesHwKeyData_t

Modules

 CryptoCell AES definitions
 CryptoCell AES specific errors

Typedefs

typedef uint8_t SaSiAesIv_t [SASI_AES_IV_SIZE_IN_BYTES]
typedef uint8_t SaSiAesKeyBuffer_t [SASI_AES_KEY_MAX_SIZE_IN_BYTES]
typedef struct SaSiAesUserContext_t SaSiAesUserContext_t
typedef struct SaSiAesUserKeyData_t SaSiAesUserKeyData_t
typedef struct SaSiAesHwKeyData_t SaSiAesHwKeyData_t

Enumerations

enum  SaSiAesEncryptMode_t { SASI_AES_ENCRYPT = 0, SASI_AES_DECRYPT = 1, SASI_AES_NUM_OF_ENCRYPT_MODES, SASI_AES_ENCRYPT_MODE_LAST = 0x7FFFFFFF }
enum  SaSiAesOperationMode_t {
  SASI_AES_MODE_ECB = 0, SASI_AES_MODE_CBC = 1, SASI_AES_MODE_CBC_MAC = 2, SASI_AES_MODE_CTR = 3,
  SASI_AES_MODE_XCBC_MAC = 4, SASI_AES_MODE_CMAC = 5, SASI_AES_MODE_XTS = 6, SASI_AES_MODE_CBC_CTS = 7,
  SASI_AES_MODE_OFB = 8, SASI_AES_NUM_OF_OPERATION_MODES, SASI_AES_OPERATION_MODE_LAST = 0x7FFFFFFF
}
enum  SaSiAesPaddingType_t { SASI_AES_PADDING_NONE = 0, SASI_AES_PADDING_PKCS7 = 1, SASI_AES_NUM_OF_PADDING_TYPES, SASI_AES_PADDING_TYPE_LAST = 0x7FFFFFFF }
enum  SaSiAesKeyType_t {
  SASI_AES_USER_KEY = 0, SASI_AES_PLATFORM_KEY = 1, SASI_AES_CUSTOMER_KEY = 2, SASI_AES_NUM_OF_KEY_TYPES,
  SASI_AES_KEY_TYPE_LAST = 0x7FFFFFFF
}

Functions

CIMPORT_C SaSiError_t SaSi_AesInit (SaSiAesUserContext_t *pContext, SaSiAesEncryptMode_t encryptDecryptFlag, SaSiAesOperationMode_t operationMode, SaSiAesPaddingType_t paddingType)
 This function is used to initialize an AES operation context. To operate the AES machine, this must be the first API called.
CIMPORT_C SaSiError_t SaSi_AesSetKey (SaSiAesUserContext_t *pContext, SaSiAesKeyType_t keyType, void *pKeyData, size_t keyDataSize)
 This function sets the key information for the AES operation, in the context that was initialized by SaSi_AesInit.
CIMPORT_C SaSiError_t SaSi_AesSetIv (SaSiAesUserContext_t *pContext, SaSiAesIv_t pIV)
 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.
CIMPORT_C SaSiError_t SaSi_AesGetIv (SaSiAesUserContext_t *pContext, SaSiAesIv_t pIV)
 This function retrieves the current IV, counter or tweak from the AES context.
CIMPORT_C SaSiError_t SaSi_AesBlock (SaSiAesUserContext_t *pContext, uint8_t *pDataIn, size_t dataInSize, uint8_t *pDataOut)
 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.
CIMPORT_C SaSiError_t SaSi_AesFinish (SaSiAesUserContext_t *pContext, size_t dataSize, uint8_t *pDataIn, size_t dataInBuffSize, uint8_t *pDataOut, size_t *dataOutBuffSize)
 This function is used to finish AES operation.
CIMPORT_C SaSiError_t SaSi_AesFree (SaSiAesUserContext_t *pContext)
 This function releases and crears resources after AES operations.

Typedef Documentation

typedef struct SaSiAesHwKeyData_t SaSiAesHwKeyData_t

AES HW Key Data - this structure is likely to be changed when we'll start using it.

typedef uint8_t SaSiAesIv_t[SASI_AES_IV_SIZE_IN_BYTES]

Defines the IV buffer - 16 bytes array.

Definition at line 126 of file ssi_aes.h.

typedef uint8_t SaSiAesKeyBuffer_t[SASI_AES_KEY_MAX_SIZE_IN_BYTES]

Defines the AES key data buffer.

Definition at line 129 of file ssi_aes.h.

typedef struct SaSiAesUserContext_t SaSiAesUserContext_t

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 SaSiAesUserKeyData_t SaSiAesUserKeyData_t

AES User Key Data.

Enumeration Type Documentation

enum SaSiAesEncryptMode_t

Encrypt or Decrypt operation mode.

Enumerator:
SASI_AES_ENCRYPT 

Encrypt operation.

SASI_AES_DECRYPT 

Decrypt operation.

SASI_AES_NUM_OF_ENCRYPT_MODES 

Maximal number of operations.

SASI_AES_ENCRYPT_MODE_LAST 

Reserved.

Definition at line 65 of file ssi_aes.h.

enum SaSiAesKeyType_t

AES key type.

Enumerator:
SASI_AES_USER_KEY 

user key.

SASI_AES_PLATFORM_KEY 

Kplt hardware key.

SASI_AES_CUSTOMER_KEY 

Kcst hardware key.

SASI_AES_NUM_OF_KEY_TYPES 

Maximal number of AES key types

SASI_AES_KEY_TYPE_LAST 

Reserved.

Definition at line 112 of file ssi_aes.h.

enum SaSiAesOperationMode_t

AES operation mode.

Enumerator:
SASI_AES_MODE_ECB 

ECB mode.

SASI_AES_MODE_CBC 

CBC mode.

SASI_AES_MODE_CBC_MAC 

CBC-MAC mode.

SASI_AES_MODE_CTR 

CTR mode.

SASI_AES_MODE_XCBC_MAC 

XCBC-MAC mode.

SASI_AES_MODE_CMAC 

CMAC mode.

SASI_AES_MODE_XTS 

XTS mode.

SASI_AES_MODE_CBC_CTS 

CBC-CTS mode.

SASI_AES_MODE_OFB 

OFB mode.

SASI_AES_NUM_OF_OPERATION_MODES 

Maximal number of AES modes

SASI_AES_OPERATION_MODE_LAST 

Reserved.

Definition at line 79 of file ssi_aes.h.

enum SaSiAesPaddingType_t

AES padding type.

Enumerator:
SASI_AES_PADDING_NONE 

No padding.

SASI_AES_PADDING_PKCS7 

PKCS7 padding.

SASI_AES_NUM_OF_PADDING_TYPES 

Maximal number of AES padding modes

SASI_AES_PADDING_TYPE_LAST 

Reserved.

Definition at line 99 of file ssi_aes.h.

Function Documentation

CIMPORT_C SaSiError_t SaSi_AesBlock ( SaSiAesUserContext_t *  pContext,
uint8_t *  pDataIn,
size_t  dataInSize,
uint8_t *  pDataOut 
)

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.

Returns:
SASI_OK on success,
A non-zero value from ssi_aes_error.h on failure.
Parameters:
[in]pContextPointer to the AES context.
[in]pDataInPointer 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.
[in]dataInSizeSize of the input data in bytes.

  • For all modes except XTS, must be multiple of 16 bytes.
  • 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.
[out]pDataOutPointer 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.
CIMPORT_C SaSiError_t SaSi_AesFinish ( SaSiAesUserContext_t *  pContext,
size_t  dataSize,
uint8_t *  pDataIn,
size_t  dataInBuffSize,
uint8_t *  pDataOut,
size_t *  dataOutBuffSize 
)

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.
Returns:
SASI_OK on success,
A non-zero value from ssi_aes_error.h on failure.
Parameters:
[in]pContextPointer to the AES context.
[in]dataSizeThe size of the input data in bytes.

  • 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).
  • 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.
  • For all other modes, zero is a valid size.
  • For ECB, CBC, CBC-MAC modes:
    • Must be >= 0, if direction is SASI_AES_ENCRYPT and padding type is SASI_AES_PADDING_PKCS7.
    • Must be >= 16 and a multiple of 16 bytes, if direction is SASI_AES_DECRYPT and padding type is SASI_AES_PADDING_PKCS7.
    • Must be a multiple of 16 bytes, otherwise.
[in]pDataInPointer 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.
[in]dataInBuffSizeSize of pDataIn buffer in bytes.

  • Must be >= dataSize.
  • According to padding type, must be >= dataSize + padding. For PKCS7, padding size is maximum SASI_AES_BLOCK_SIZE_IN_BYTES.
[out]pDataOutPointer 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.
[in,out]dataOutBuffSizeIn - Size of pDataOut buffer in bytes. The output buffer size must be no less than:

  • For CBC-MAC, XCBC-MAC, CMAC modes - 16 bytes (for MAC result).
  • For non-MAC modes - dataInBuffSize.

Out - The size in bytes of the actual output data:

  • If direction is SASI_AES_ENCRYPT and padding type is SASI_AES_PADDING_PKCS7, it is the actual size with the padding.
  • If direction is SASI_AES_DECRYPT and padding type is SASI_AES_PADDING_PKCS7, it is the size without the padding.
  • For CBC-MAC, XCBC-MAC, CMAC modes - always 16 bytes.
CIMPORT_C SaSiError_t SaSi_AesFree ( SaSiAesUserContext_t *  pContext )

This function releases and crears resources after AES operations.

Returns:
SASI_OK on success,
A non-zero value from ssi_aes_error.h on failure.
Parameters:
[in]pContextPointer to the AES context.
CIMPORT_C SaSiError_t SaSi_AesGetIv ( SaSiAesUserContext_t *  pContext,
SaSiAesIv_t  pIV 
)

This function retrieves the current IV, counter or tweak from the AES context.

Returns:
SASI_OK on success,
A non-zero value from ssi_aes_error.h on failure.
Parameters:
[in]pContextPointer to the AES context.
[out]pIVPointer to the buffer of the IV, counter or tweak.

  • For CBC, CBC-CTS, OFB and CBC-MAC modes - the IV value.
  • For CTR mode - the counter.
  • For XTS mode - the tweak value.
  • For all other modes - N/A.
CIMPORT_C SaSiError_t SaSi_AesInit ( SaSiAesUserContext_t *  pContext,
SaSiAesEncryptMode_t  encryptDecryptFlag,
SaSiAesOperationMode_t  operationMode,
SaSiAesPaddingType_t  paddingType 
)

This function is used to initialize an AES operation context. To operate the AES machine, this must be the first API called.

Returns:
SASI_OK on success,
A non-zero value from ssi_aes_error.h on failure.
Parameters:
[in]pContextPointer 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.
[in]encryptDecryptFlagA 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.
[in]operationModeThe operation cipher/mode.
[in]paddingTypeThe padding type for AES operation:

  • NONE - supported for all operation modes.
  • PKCS7 - supported for ECB, CBC, CBC-MAC operation modes.
CIMPORT_C SaSiError_t SaSi_AesSetIv ( SaSiAesUserContext_t *  pContext,
SaSiAesIv_t  pIV 
)

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.

Returns:
SASI_OK on success,
A non-zero value from ssi_aes_error.h on failure.
Parameters:
[in]pContextPointer to the AES context.
[in]pIVPointer to the buffer of the IV, counter or tweak.

  • For CBC, CBC-CTS, OFB and CBC-MAC modes - the IV value.
  • For CTR mode - the counter.
  • For XTS mode - the tweak value.
  • For all other modes - N/A.
CIMPORT_C SaSiError_t SaSi_AesSetKey ( SaSiAesUserContext_t *  pContext,
SaSiAesKeyType_t  keyType,
void *  pKeyData,
size_t  keyDataSize 
)

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).
Returns:
SASI_OK on success,
A non-zero value from ssi_aes_error.h on failure.
Parameters:
[in]pContextPointer to the AES context, after it was initialized by SaSi_AesInit.
[in]keyTypeThe 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.
[in]pKeyDataPointer to the key data structure (to be casted to the relevant struct type).
[in]keyDataSizeThe size of data passed in pKeyData in bytes.
Generated on Tue Jul 12 2022 13:55:22 by  doxygen 1.7.2