Modules
	CryptoCell AES-CCM specific errors

Data Structures
struct	CRYS_AESCCM_UserContext_t

Macros
#define	CRYS_AESCCM_USER_CTX_SIZE_IN_WORDS (152/4)

#define	CRYS_AESCCM_KEY_SIZE_WORDS 8

#define	CRYS_AESCCM_NONCE_MIN_SIZE_BYTES 7

#define	CRYS_AESCCM_NONCE_MAX_SIZE_BYTES 13

#define	CRYS_AESCCM_MAC_MIN_SIZE_BYTES 4

#define	CRYS_AESCCM_MAC_MAX_SIZE_BYTES 16

#define	CRYS_AESCCM_STAR_NONCE_SIZE_BYTES 13

#define	CRYS_AESCCM_STAR_SOURCE_ADDRESS_SIZE_BYTES 8

#define	CRYS_AESCCM_MODE_CCM 0

#define	CRYS_AESCCM_MODE_STAR 1

#define	CRYS_AESCCM_Init (ContextID_ptr, EncrDecrMode, CCM_Key, KeySizeId, AdataSize, TextSizeQ, N_ptr, SizeOfN, SizeOfT) CC_AESCCM_Init (ContextID_ptr, EncrDecrMode, CCM_Key, KeySizeId, AdataSize, TextSizeQ, N_ptr, SizeOfN, SizeOfT, CRYS_AESCCM_MODE_CCM )

#define	CRYS_AESCCMStar_Init (ContextID_ptr, EncrDecrMode, CCM_Key, KeySizeId, AdataSize, TextSizeQ, N_ptr, SizeOfN, SizeOfT) CC_AESCCM_Init (ContextID_ptr, EncrDecrMode, CCM_Key, KeySizeId, AdataSize, TextSizeQ, N_ptr, SizeOfN, SizeOfT, CRYS_AESCCM_MODE_STAR )

#define	CRYS_AESCCM (EncrDecrMode, CCM_Key, KeySizeId, N_ptr, SizeOfN, ADataIn_ptr, ADataInSize, TextDataIn_ptr, TextDataInSize, TextDataOut_ptr, SizeOfT, Mac_Res) CC_AESCCM (EncrDecrMode, CCM_Key, KeySizeId, N_ptr, SizeOfN, ADataIn_ptr, ADataInSize, TextDataIn_ptr, TextDataInSize, TextDataOut_ptr, SizeOfT, Mac_Res, CRYS_AESCCM_MODE_CCM )

#define	CRYS_AESCCMStar (EncrDecrMode, CCM_Key, KeySizeId, N_ptr, SizeOfN, ADataIn_ptr, ADataInSize, TextDataIn_ptr, TextDataInSize, TextDataOut_ptr, SizeOfT, Mac_Res) CC_AESCCM (EncrDecrMode, CCM_Key, KeySizeId, N_ptr, SizeOfN, ADataIn_ptr, ADataInSize, TextDataIn_ptr, TextDataInSize, TextDataOut_ptr, SizeOfT, Mac_Res, CRYS_AESCCM_MODE_STAR )

Typedefs
typedef uint8_t	CRYS_AESCCM_Key_t [8 *sizeof(uint32_t)]

typedef uint8_t	CRYS_AESCCM_Mac_Res_t [(4 *sizeof(uint32_t))]

typedef uint8_t	CRYS_AESCCMStar_SourceAddress_t [8]

typedef uint8_t	CRYS_AESCCMStar_Nonce_t [13]

typedef struct CRYS_AESCCM_UserContext_t	CRYS_AESCCM_UserContext_t

Enumerations
enum	CRYS_AESCCM_KeySize_t { CRYS_AES_Key128BitSize = 0, CRYS_AES_Key192BitSize = 1, CRYS_AES_Key256BitSize = 2, CRYS_AES_Key512BitSize = 3, CRYS_AES_KeySizeNumOfOptions , CRYS_AES_KeySizeLast = 0x7FFFFFFF }

Functions
CRYSError_t	CC_AESCCM_Init ( CRYS_AESCCM_UserContext_t ContextID_ptr, SaSiAesEncryptMode_t EncrDecrMode, CRYS_AESCCM_Key_t CCM_Key, CRYS_AESCCM_KeySize_t KeySizeId, uint32_t AdataSize, uint32_t TextSizeQ, uint8_t N_ptr, uint8_t SizeOfN, uint8_t SizeOfT, uint32_t ccmMode)
	This function initializes the AES CCM context. More...

CRYSError_t	CRYS_AESCCM_BlockAdata ( CRYS_AESCCM_UserContext_t ContextID_ptr, uint8_t DataIn_ptr, uint32_t DataInSize)
	This function receives a CCM context and a block of additional data, and adds it to the AES MAC calculation. This API can be called only once per operation context. It should not be called in case AdataSize was set to zero in CC_AESCCM_Init . More...

CRYSError_t	CRYS_AESCCM_BlockTextData ( CRYS_AESCCM_UserContext_t ContextID_ptr, uint8_t DataIn_ptr, uint32_t DataInSize, uint8_t *DataOut_ptr)
	This function can be invoked for any block of Text data whose size is a multiple of 16 bytes, excluding the last block that must be processed by CRYS_AESCCM_Finish . More...

CRYSError_t	CRYS_AESCCM_Finish ( CRYS_AESCCM_UserContext_t ContextID_ptr, uint8_t DataIn_ptr, uint32_t DataInSize, uint8_t DataOut_ptr, CRYS_AESCCM_Mac_Res_t MacRes, uint8_t SizeOfT)
	This function must be the last to be called on the text data. It can either be called on the entire text data (if transferred as one block), or on the last block of the text data, even if total size of text data is equal to 0. It performs the same operations as CRYS_AESCCM_BlockTextData , but additionally: More...

CRYSError_t	CC_AESCCM ( SaSiAesEncryptMode_t EncrDecrMode, CRYS_AESCCM_Key_t CCM_Key, CRYS_AESCCM_KeySize_t KeySizeId, uint8_t N_ptr, uint8_t SizeOfN, uint8_t ADataIn_ptr, uint32_t ADataInSize, uint8_t TextDataIn_ptr, uint32_t TextDataInSize, uint8_t TextDataOut_ptr, uint8_t SizeOfT, CRYS_AESCCM_Mac_Res_t Mac_Res, uint32_t ccmMode)
	AES CCM combines Counter mode encryption with CBC-MAC authentication. Input to CCM includes the following elements: More...

CRYSError_t	CRYS_AESCCMStar_NonceGenerate ( CRYS_AESCCMStar_SourceAddress_t srcAddr, uint32_t FrameCounter, uint8_t SizeOfT, CRYS_AESCCMStar_Nonce_t nonce)
	This function receives the MAC source address, the frame counter and the MAC size and returns the required nonce for AES-CCM* as defined in ieee-802.15.4. This API should be called before CRYS_AESCCMStar and CRYS_AESCCMStar_Init, and the generated nonce should be provided to these functions. More...

Detailed Description

Note

Regarding the AES-CCM*, the API supports only AES-CCM* as defined in ieee-802.15.4-2011; With the instantiations as defined in B.3.2 and the nonce as defined in 7.3.2. in case of AES-CCM* the flow should be as follows:

AES-CCM* integrated
- CRYS_AESCCMStar_NonceGenerate
- CRYS_AESCCMStar

AES-CCM* non-integrated
- CRYS_AESCCMStar_NonceGenerate
- CRYS_AESCCMStar_Init
- CRYS_AESCCM_BlockAdata
- CRYS_AESCCM_BlockTextData
- CRYS_AESCCM_Finish

Macro Definition Documentation

#define CRYS_AESCCM	(	EncrDecrMode,
		CCM_Key,
		KeySizeId,
		N_ptr,
		SizeOfN,
		ADataIn_ptr,
		ADataInSize,
		TextDataIn_ptr,
		TextDataInSize,
		TextDataOut_ptr,
		SizeOfT,
		Mac_Res
	)	CC_AESCCM (EncrDecrMode, CCM_Key, KeySizeId, N_ptr, SizeOfN, ADataIn_ptr, ADataInSize, TextDataIn_ptr, TextDataInSize, TextDataOut_ptr, SizeOfT, Mac_Res, CRYS_AESCCM_MODE_CCM )

Macro defintion for CRYS_AESCCM (AES CCM non-star implementation).

#define CRYS_AESCCM_Init	(	ContextID_ptr,
		EncrDecrMode,
		CCM_Key,
		KeySizeId,
		AdataSize,
		TextSizeQ,
		N_ptr,
		SizeOfN,
		SizeOfT
	)	CC_AESCCM_Init (ContextID_ptr, EncrDecrMode, CCM_Key, KeySizeId, AdataSize, TextSizeQ, N_ptr, SizeOfN, SizeOfT, CRYS_AESCCM_MODE_CCM )

Macro defintion for CRYS_AESCCM_Init (AES CCM non-star implementation).

#define CRYS_AESCCM_KEY_SIZE_WORDS 8

AES CCM maximal key size in words.

#define CRYS_AESCCM_MAC_MAX_SIZE_BYTES 16

AES CCM MAC maximal size in bytes.

#define CRYS_AESCCM_MAC_MIN_SIZE_BYTES 4

AES CCM MAC minimal size in bytes..

#define CRYS_AESCCM_MODE_CCM 0

AES CCM mode - CCM.

#define CRYS_AESCCM_MODE_STAR 1

AES CCM mode - CCM STAR.

#define CRYS_AESCCM_NONCE_MAX_SIZE_BYTES 13

AES CCM NONCE maximal size in bytes.

#define CRYS_AESCCM_NONCE_MIN_SIZE_BYTES 7

AES CCM NONCE minimal size in bytes.

#define CRYS_AESCCM_STAR_NONCE_SIZE_BYTES 13

AES CCM star NONCE size in bytes.

#define CRYS_AESCCM_STAR_SOURCE_ADDRESS_SIZE_BYTES 8

AES CCM star source address size in bytes.

#define CRYS_AESCCM_USER_CTX_SIZE_IN_WORDS (152/4)

AES CCM context size in words.

#define CRYS_AESCCMStar	(	EncrDecrMode,
		CCM_Key,
		KeySizeId,
		N_ptr,
		SizeOfN,
		ADataIn_ptr,
		ADataInSize,
		TextDataIn_ptr,
		TextDataInSize,
		TextDataOut_ptr,
		SizeOfT,
		Mac_Res
	)	CC_AESCCM (EncrDecrMode, CCM_Key, KeySizeId, N_ptr, SizeOfN, ADataIn_ptr, ADataInSize, TextDataIn_ptr, TextDataInSize, TextDataOut_ptr, SizeOfT, Mac_Res, CRYS_AESCCM_MODE_STAR )

Macro defintion for CRYS_AESCCMStar (AES CCM star implementation).

#define CRYS_AESCCMStar_Init	(	ContextID_ptr,
		EncrDecrMode,
		CCM_Key,
		KeySizeId,
		AdataSize,
		TextSizeQ,
		N_ptr,
		SizeOfN,
		SizeOfT
	)	CC_AESCCM_Init (ContextID_ptr, EncrDecrMode, CCM_Key, KeySizeId, AdataSize, TextSizeQ, N_ptr, SizeOfN, SizeOfT, CRYS_AESCCM_MODE_STAR )

Macro defintion CRYS_AESCCMStar_Init (AES CCM star implementation).

Typedef Documentation

typedef uint8_t CRYS_AESCCM_Key_t[8 *sizeof(uint32_t)]

AES_CCM key buffer definition.

typedef uint8_t CRYS_AESCCM_Mac_Res_t[(4 *sizeof(uint32_t))]

AES_CCM MAC buffer definition.

typedef struct CRYS_AESCCM_UserContext_t CRYS_AESCCM_UserContext_t

The user's context structure - the argument type that is passed by the user to the AES CCM APIs

typedef uint8_t CRYS_AESCCMStar_Nonce_t[13]

AES_CCM_STAR Nonce buffer defintion.

typedef uint8_t CRYS_AESCCMStar_SourceAddress_t[8]

AES_CCM_STAR source address buffer defintion.

Enumeration Type Documentation

enum CRYS_AESCCM_KeySize_t

AES CCM key sizes.

Enumerator
CRYS_AES_Key128BitSize	Key size 128 bits.
CRYS_AES_Key192BitSize	Key size 192 bits.
CRYS_AES_Key256BitSize	Key size 256 bits.
CRYS_AES_Key512BitSize	Key size 512 bits.
CRYS_AES_KeySizeNumOfOptions	Number of optional key sizes.
CRYS_AES_KeySizeLast	Reserved.

Function Documentation

CRYSError_t CC_AESCCM	(	SaSiAesEncryptMode_t	EncrDecrMode ,
		CRYS_AESCCM_Key_t	CCM_Key ,
		CRYS_AESCCM_KeySize_t	KeySizeId ,
		uint8_t *	N_ptr ,
		uint8_t	SizeOfN ,
		uint8_t *	ADataIn_ptr ,
		uint32_t	ADataInSize ,
		uint8_t *	TextDataIn_ptr ,
		uint32_t	TextDataInSize ,
		uint8_t *	TextDataOut_ptr ,
		uint8_t	SizeOfT ,
		CRYS_AESCCM_Mac_Res_t	Mac_Res ,
		uint32_t	ccmMode
	)

AES CCM combines Counter mode encryption with CBC-MAC authentication. Input to CCM includes the following elements:

Payload - text data that is both authenticated and encrypted.
Associated data (Adata) - data that is authenticated but not encrypted, e.g., a header.
Nonce - A unique value that is assigned to the payload and the associated data.

Returns: CRYS_OK on success.; A non-zero value on failure as defined crys_aesccm_error.h.

Parameters

[in]	EncrDecrMode	A flag specifying whether an AES Encrypt ( SASI_AES_ENCRYPT ) or Decrypt ( SASI_AES_DECRYPT ) operation should be performed.
[in]	CCM_Key	Pointer to AES-CCM key.
[in]	KeySizeId	Enumerator defining the key size (only 128 bit is valid).
[in]	N_ptr	Pointer to the Nonce.
[in]	SizeOfN	Nonce byte size. The valid values depend on the ccm mode: CCM: valid values = [7 .. 13]. CCM*: valid values = [13].
[in]	ADataIn_ptr	Pointer to the additional input data. The buffer must be contiguous.
[in]	ADataInSize	Byte size of the additional data.
[in]	TextDataIn_ptr	Pointer to the plain-text data for encryption or cipher-text data for decryption. The buffer must be contiguous.
[in]	TextDataInSize	Byte size of the full text data.
[out]	TextDataOut_ptr	Pointer to the output (cipher or plain text data according to encrypt-decrypt mode) data. The buffer must be contiguous.
[in]	SizeOfT	AES-CCM MAC (tag) byte size. The valid values depend on the ccm mode: CCM: valid values = [4, 6, 8, 10, 12, 14, 16]. CCM*: valid values = [0, 4, 8, 16].
[in,out]	Mac_Res	Pointer to the MAC result buffer.
[in]	ccmMode	Flag specifying whether AES-CCM or AES-CCM* should be performed.

CRYSError_t CC_AESCCM_Init	(	CRYS_AESCCM_UserContext_t *	ContextID_ptr ,
		SaSiAesEncryptMode_t	EncrDecrMode ,
		CRYS_AESCCM_Key_t	CCM_Key ,
		CRYS_AESCCM_KeySize_t	KeySizeId ,
		uint32_t	AdataSize ,
		uint32_t	TextSizeQ ,
		uint8_t *	N_ptr ,
		uint8_t	SizeOfN ,
		uint8_t	SizeOfT ,
		uint32_t	ccmMode
	)

This function initializes the AES CCM context.

It formats of the input data, calculates AES-MAC value for the formatted B0 block containing control information and CCM unique value (Nonce), and initializes the AES context structure including the initial CTR0 value.

Returns: CRYS_OK on success.; A non-zero value on failure as defined crys_aesccm_error.h.

Parameters

[in]	ContextID_ptr	Pointer to the AES context buffer that is allocated by the user and is used for the AES operation.
[in]	EncrDecrMode	Flag specifying whether Encrypt ( SASI_AES_ENCRYPT ) or Decrypt ( SASI_AES_DECRYPT ) operation should be performed.
[in]	CCM_Key	Pointer to the AES-CCM key.
[in]	KeySizeId	Enumerator defining the key size (only 128 bit is valid).
[in]	AdataSize	Full byte length of additional (associated) data. If set to zero, calling CRYS_AESCCM_BlockAdata on the same context would return an error.
[in]	TextSizeQ	Full length of plain text data.
[in]	N_ptr	Pointer to the Nonce.
[in]	SizeOfN	Nonce byte size. The valid values depend on the ccm mode: CCM: valid values = [7 .. 13]. CCM*: valid values = [13].
[in]	SizeOfT	AES-CCM MAC (tag) byte size. The valid values depend on the ccm mode: CCM: valid values = [4, 6, 8, 10, 12, 14, 16]. CCM*: valid values = [0, 4, 8, 16].
[in]	ccmMode	Flag specifying whether AES-CCM or AES-CCM* should be performed.

CRYSError_t CRYS_AESCCM_BlockAdata	(	CRYS_AESCCM_UserContext_t *	ContextID_ptr ,
		uint8_t *	DataIn_ptr ,
		uint32_t	DataInSize
	)

This function receives a CCM context and a block of additional data, and adds it to the AES MAC calculation. This API can be called only once per operation context. It should not be called in case AdataSize was set to zero in CC_AESCCM_Init .

Returns: CRYS_OK on success.; A non-zero value on failure as defined crys_aesccm_error.h.

Parameters

[in]	ContextID_ptr	Pointer to the context buffer.
[in]	DataIn_ptr	Pointer to the additional input data. The buffer must be contiguous.
[in]	DataInSize	Byte size of the additional data. Must match AdataSize parameter provided to CRYS_AESCCM_Init .

CRYSError_t CRYS_AESCCM_BlockTextData	(	CRYS_AESCCM_UserContext_t *	ContextID_ptr ,
		uint8_t *	DataIn_ptr ,
		uint32_t	DataInSize ,
		uint8_t *	DataOut_ptr
	)

This function can be invoked for any block of Text data whose size is a multiple of 16 bytes, excluding the last block that must be processed by CRYS_AESCCM_Finish .

If encrypting: Continues calculation of the intermediate AES_MAC value of the text data, while simultaneously encrypting the text data using AES_CTR, starting from CTR value = CTR0+1.
If decrypting: Continues decryption of the text data, while calculating the intermediate AES_MAC value of decrypted data.

Returns: CRYS_OK on success.; A non-zero value on failure as defined crys_aesccm_error.h.

Parameters

[in]	ContextID_ptr	Pointer to the context buffer.
[in]	DataIn_ptr	Pointer to the additional input data. The buffer must be contiguous.
[in]	DataInSize	Byte size of the text data block. Must be a multiple of 16 bytes.
[out]	DataOut_ptr	Pointer to the output data. The size of the output buffer must be at least DataInSize. The buffer must be contiguous.

CRYSError_t CRYS_AESCCM_Finish	(	CRYS_AESCCM_UserContext_t *	ContextID_ptr ,
		uint8_t *	DataIn_ptr ,
		uint32_t	DataInSize ,
		uint8_t *	DataOut_ptr ,
		CRYS_AESCCM_Mac_Res_t	MacRes ,
		uint8_t *	SizeOfT
	)

This function must be the last to be called on the text data. It can either be called on the entire text data (if transferred as one block), or on the last block of the text data, even if total size of text data is equal to 0. It performs the same operations as CRYS_AESCCM_BlockTextData , but additionally:

If encrypting:
- If the size of text data is not in multiples of 16 bytes, it pads the remaining bytes with zeros to a full 16-bytes block and processes the data using AES_MAC and AES_CTR algorithms.
- Encrypts the AES_MAC result with AES_CTR using the CTR0 value saved in the context and places the SizeOfT bytes of MAC (tag) at the end.

If decrypting:
- Processes the text data, except for the last SizeOfT bytes (tag), using AES_CTR and then AES_MAC algorithms.
- Encrypts the calculated MAC using AES_CTR based on the saved CTR0 value, and compares it with SizeOfT last bytes of input data (i.e. tag value).
- The function saves the validation result (Valid/Invalid) in the context.
- Returns (as the error code) the final CCM-MAC verification result.

Returns: CRYS_OK on success.; A non-zero value on failure as defined crys_aesccm_error.h.

Parameters

[in]	ContextID_ptr	Pointer to the context buffer.
[in]	DataIn_ptr	Pointer to the last input data. The buffer must be contiguous.
[in]	DataInSize	Byte size of the last text data block. Can be zero.
[in]	DataOut_ptr	Pointer to the output (cipher or plain text data) data. The buffer must be contiguous. If DataInSize = 0, output buffer is not required.
[in]	MacRes	MAC result buffer pointer.
[out]	SizeOfT	AES-CCM MAC byte size as defined in CRYS_AESCCM_Init.

CRYSError_t CRYS_AESCCMStar_NonceGenerate	(	CRYS_AESCCMStar_SourceAddress_t	srcAddr ,
		uint32_t	FrameCounter ,
		uint8_t	SizeOfT ,
		CRYS_AESCCMStar_Nonce_t	nonce
	)

This function receives the MAC source address, the frame counter and the MAC size and returns the required nonce for AES-CCM* as defined in ieee-802.15.4. This API should be called before CRYS_AESCCMStar and CRYS_AESCCMStar_Init, and the generated nonce should be provided to these functions.

Returns: CRYS_OK on success.; A non-zero value on failure as defined crys_aesccm_error.h.

Parameters

[in]	srcAddr	The MAC address in EUI-64 format.
[in]	FrameCounter	The MAC frame counter.
[in]	SizeOfT	AES-CCM* MAC (tag) byte size. Valid values = [0,4,8,16].
[out]	nonce	The required nonce for AES-CCM*.

CryptoCell AES-CCM APIs

nRF5 SDK v17.1.0

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation