mirror of https://github.com/ARMmbed/mbed-os.git
316 lines
18 KiB
C
316 lines
18 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. *
|
|
**************************************************************************************/
|
|
|
|
|
|
|
|
#ifndef CRYS_AESCCM_H
|
|
#define CRYS_AESCCM_H
|
|
|
|
#include "ssi_pal_types.h"
|
|
#include "crys_error.h"
|
|
|
|
#include "ssi_aes.h"
|
|
|
|
|
|
#ifdef __cplusplus
|
|
extern "C"
|
|
{
|
|
#endif
|
|
|
|
/*!
|
|
@file
|
|
@brief This file contains all of the enums and definitions that are used for the CRYS AESCCM APIs, as well as the APIs themselves.
|
|
The API supports AES-CCM and AES-CCM* as defined in ieee-802.15.4.
|
|
@defgroup crys_aesccm CryptoCell AES-CCM APIs
|
|
@{
|
|
@ingroup cryptocell_api
|
|
|
|
|
|
@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:
|
|
<ul><li>AES-CCM* integrated</li>
|
|
<ul><li>CRYS_AESCCMStar_NonceGenerate</li>
|
|
<li>CRYS_AESCCMStar</li></ul></ul>
|
|
<ul><li>AES-CCM* non-integrated</li>
|
|
<ul><li>CRYS_AESCCMStar_NonceGenerate</li>
|
|
<li>CRYS_AESCCMStar_Init</li>
|
|
<li>CRYS_AESCCM_BlockAdata</li>
|
|
<li>CRYS_AESCCM_BlockTextData</li>
|
|
<li>CRYS_AESCCM_Finish</li></ul></ul>
|
|
*/
|
|
|
|
/************************ Defines ******************************/
|
|
|
|
/*! AES CCM context size in words.*/
|
|
#define CRYS_AESCCM_USER_CTX_SIZE_IN_WORDS (152/4)
|
|
|
|
/*! AES CCM maximal key size in words. */
|
|
#define CRYS_AESCCM_KEY_SIZE_WORDS 8
|
|
|
|
/* nonce and AESCCM-MAC sizes definitions */
|
|
/*! AES CCM NONCE minimal size in bytes. */
|
|
#define CRYS_AESCCM_NONCE_MIN_SIZE_BYTES 7
|
|
/*! AES CCM NONCE maximal size in bytes. */
|
|
#define CRYS_AESCCM_NONCE_MAX_SIZE_BYTES 13
|
|
/*! AES CCM MAC minimal size in bytes..*/
|
|
#define CRYS_AESCCM_MAC_MIN_SIZE_BYTES 4
|
|
/*! AES CCM MAC maximal size in bytes. */
|
|
#define CRYS_AESCCM_MAC_MAX_SIZE_BYTES 16
|
|
|
|
/*! AES CCM star NONCE size in bytes. */
|
|
#define CRYS_AESCCM_STAR_NONCE_SIZE_BYTES 13
|
|
/*! AES CCM star source address size in bytes. */
|
|
#define CRYS_AESCCM_STAR_SOURCE_ADDRESS_SIZE_BYTES 8
|
|
|
|
/*! AES CCM mode - CCM. */
|
|
#define CRYS_AESCCM_MODE_CCM 0
|
|
/*! AES CCM mode - CCM STAR. */
|
|
#define CRYS_AESCCM_MODE_STAR 1
|
|
|
|
|
|
/************************ Typedefs ****************************/
|
|
/*! AES CCM key sizes. */
|
|
typedef enum {
|
|
/*! Key size 128 bits. */
|
|
CRYS_AES_Key128BitSize = 0,
|
|
/*! Key size 192 bits. */
|
|
CRYS_AES_Key192BitSize = 1,
|
|
/*! Key size 256 bits. */
|
|
CRYS_AES_Key256BitSize = 2,
|
|
/*! Key size 512 bits. */
|
|
CRYS_AES_Key512BitSize = 3,
|
|
/*! Number of optional key sizes. */
|
|
CRYS_AES_KeySizeNumOfOptions,
|
|
/*! Reserved. */
|
|
CRYS_AES_KeySizeLast = 0x7FFFFFFF,
|
|
|
|
}CRYS_AESCCM_KeySize_t;
|
|
|
|
/*! AES_CCM key buffer definition.*/
|
|
typedef uint8_t CRYS_AESCCM_Key_t[CRYS_AESCCM_KEY_SIZE_WORDS * sizeof(uint32_t)];
|
|
/*! AES_CCM MAC buffer definition.*/
|
|
typedef uint8_t CRYS_AESCCM_Mac_Res_t[SASI_AES_BLOCK_SIZE_IN_BYTES];
|
|
|
|
/*! AES_CCM_STAR source address buffer defintion. */
|
|
typedef uint8_t CRYS_AESCCMStar_SourceAddress_t[CRYS_AESCCM_STAR_SOURCE_ADDRESS_SIZE_BYTES];
|
|
/*! AES_CCM_STAR Nonce buffer defintion. */
|
|
typedef uint8_t CRYS_AESCCMStar_Nonce_t[CRYS_AESCCM_STAR_NONCE_SIZE_BYTES];
|
|
|
|
/******************* Context Structure ***********************/
|
|
/*! The user's context structure - the argument type that is passed by the user to the AES CCM APIs */
|
|
typedef struct CRYS_AESCCM_UserContext_t
|
|
{
|
|
/*! AES CCM context buffer for internal usage. */
|
|
uint32_t buff[CRYS_AESCCM_USER_CTX_SIZE_IN_WORDS];
|
|
}CRYS_AESCCM_UserContext_t;
|
|
|
|
|
|
/************************ Public Functions **********************/
|
|
|
|
/*!
|
|
@brief 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.
|
|
|
|
@return CRYS_OK on success.
|
|
@return A non-zero value on failure as defined crys_aesccm_error.h.
|
|
*/
|
|
CRYSError_t CC_AESCCM_Init(
|
|
CRYS_AESCCM_UserContext_t *ContextID_ptr, /*!< [in] Pointer to the AES context buffer that is allocated by the user and is used for
|
|
the AES operation. */
|
|
SaSiAesEncryptMode_t EncrDecrMode, /*!< [in] Flag specifying whether Encrypt (::SASI_AES_ENCRYPT) or Decrypt
|
|
(::SASI_AES_DECRYPT) operation should be performed. */
|
|
CRYS_AESCCM_Key_t CCM_Key, /*!< [in] Pointer to the AES-CCM key. */
|
|
CRYS_AESCCM_KeySize_t KeySizeId, /*!< [in] Enumerator defining the key size (only 128 bit is valid). */
|
|
uint32_t AdataSize, /*!< [in] Full byte length of additional (associated) data. If set to zero,
|
|
calling ::CRYS_AESCCM_BlockAdata on the same context would return an error. */
|
|
uint32_t TextSizeQ, /*!< [in] Full length of plain text data. */
|
|
uint8_t *N_ptr, /*!< [in] Pointer to the Nonce. */
|
|
uint8_t SizeOfN, /*!< [in] Nonce byte size. The valid values depend on the ccm mode:
|
|
<ul><li>CCM: valid values = [7 .. 13].</li>
|
|
<li>CCM*: valid values = [13].</li></ul> */
|
|
uint8_t SizeOfT, /*!< [in] AES-CCM MAC (tag) byte size. The valid values depend on the ccm mode:
|
|
<ul><li>CCM: valid values = [4, 6, 8, 10, 12, 14, 16].</li>
|
|
<li>CCM*: valid values = [0, 4, 8, 16].</li></ul>*/
|
|
uint32_t ccmMode /*!< [in] Flag specifying whether AES-CCM or AES-CCM* should be performed. */
|
|
);
|
|
|
|
/*! Macro defintion for CRYS_AESCCM_Init (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 CRYS_AESCCMStar_Init (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)
|
|
|
|
/*!
|
|
@brief 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.
|
|
|
|
@return CRYS_OK on success.
|
|
@return A non-zero value on failure as defined crys_aesccm_error.h.
|
|
*/
|
|
CRYSError_t CRYS_AESCCM_BlockAdata(
|
|
CRYS_AESCCM_UserContext_t *ContextID_ptr, /*!< [in] Pointer to the context buffer. */
|
|
uint8_t *DataIn_ptr, /*!< [in] Pointer to the additional input data. The buffer must be contiguous. */
|
|
uint32_t DataInSize /*!< [in] Byte size of the additional data. Must match AdataSize parameter provided to
|
|
::CRYS_AESCCM_Init. */
|
|
);
|
|
|
|
/*!
|
|
@brief 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.
|
|
<ul><li> 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.</li>
|
|
<li>If decrypting:
|
|
Continues decryption of the text data, while calculating the intermediate AES_MAC value of decrypted data.</li></ul>
|
|
|
|
@return CRYS_OK on success.
|
|
@return A non-zero value on failure as defined crys_aesccm_error.h.
|
|
*/
|
|
CRYSError_t CRYS_AESCCM_BlockTextData(
|
|
CRYS_AESCCM_UserContext_t *ContextID_ptr, /*!< [in] Pointer to the context buffer. */
|
|
uint8_t *DataIn_ptr, /*!< [in] Pointer to the additional input data. The buffer must be contiguous. */
|
|
uint32_t DataInSize, /*!< [in] Byte size of the text data block. Must be a multiple of 16 bytes. */
|
|
uint8_t *DataOut_ptr /*!< [out] Pointer to the output data. The size of the output buffer must be at least DataInSize.
|
|
The buffer must be contiguous. */
|
|
);
|
|
|
|
/*!
|
|
@brief 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:
|
|
<ul><li> If encrypting: </li>
|
|
<ul><li>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.</li>
|
|
<li> 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.</li></ul></ul>
|
|
<ul><li> If decrypting: </li>
|
|
<ul><li>Processes the text data, except for the last SizeOfT bytes (tag), using AES_CTR and then AES_MAC algorithms.</li>
|
|
<li>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).</li>
|
|
<li>The function saves the validation result (Valid/Invalid) in the context.</li>
|
|
<li>Returns (as the error code) the final CCM-MAC verification result.</li></ul></ul>
|
|
|
|
@return CRYS_OK on success.
|
|
@return A non-zero value on failure as defined crys_aesccm_error.h.
|
|
*/
|
|
CEXPORT_C CRYSError_t CRYS_AESCCM_Finish(
|
|
CRYS_AESCCM_UserContext_t *ContextID_ptr, /*!< [in] Pointer to the context buffer. */
|
|
uint8_t *DataIn_ptr, /*!< [in] Pointer to the last input data. The buffer must be contiguous. */
|
|
uint32_t DataInSize, /*!< [in] Byte size of the last text data block. Can be zero. */
|
|
uint8_t *DataOut_ptr, /*!< [in] Pointer to the output (cipher or plain text data) data. The buffer must
|
|
be contiguous. If DataInSize = 0, output buffer is not required. */
|
|
CRYS_AESCCM_Mac_Res_t MacRes, /*!< [in] MAC result buffer pointer. */
|
|
uint8_t *SizeOfT /*!< [out] AES-CCM MAC byte size as defined in CRYS_AESCCM_Init. */
|
|
);
|
|
|
|
/****************************************************************************************************/
|
|
/******** AESCCM FUNCTION ******/
|
|
/****************************************************************************************************/
|
|
/*!
|
|
@brief AES CCM combines Counter mode encryption with CBC-MAC authentication.
|
|
Input to CCM includes the following elements:
|
|
<ul><li> Payload - text data that is both authenticated and encrypted.</li>
|
|
<li> Associated data (Adata) - data that is authenticated but not encrypted, e.g., a header.</li>
|
|
<li> Nonce - A unique value that is assigned to the payload and the associated data.</li></ul>
|
|
|
|
@return CRYS_OK on success.
|
|
@return A non-zero value on failure as defined crys_aesccm_error.h.
|
|
*/
|
|
CIMPORT_C CRYSError_t CC_AESCCM(
|
|
SaSiAesEncryptMode_t EncrDecrMode, /*!< [in] A flag specifying whether an AES Encrypt (::SASI_AES_ENCRYPT) or Decrypt
|
|
(::SASI_AES_DECRYPT) operation should be performed. */
|
|
CRYS_AESCCM_Key_t CCM_Key, /*!< [in] Pointer to AES-CCM key. */
|
|
CRYS_AESCCM_KeySize_t KeySizeId, /*!< [in] Enumerator defining the key size (only 128 bit is valid). */
|
|
uint8_t *N_ptr, /*!< [in] Pointer to the Nonce. */
|
|
uint8_t SizeOfN, /*!< [in] Nonce byte size. The valid values depend on the ccm mode:
|
|
<ul><li>CCM: valid values = [7 .. 13].</li>
|
|
<li>CCM*: valid values = [13].</li></ul> */
|
|
uint8_t *ADataIn_ptr, /*!< [in] Pointer to the additional input data. The buffer must be contiguous. */
|
|
uint32_t ADataInSize, /*!< [in] Byte size of the additional data. */
|
|
uint8_t *TextDataIn_ptr, /*!< [in] Pointer to the plain-text data for encryption or cipher-text data for decryption.
|
|
The buffer must be contiguous. */
|
|
uint32_t TextDataInSize, /*!< [in] Byte size of the full text data. */
|
|
uint8_t *TextDataOut_ptr, /*!< [out] Pointer to the output (cipher or plain text data according to encrypt-decrypt mode)
|
|
data. The buffer must be contiguous. */
|
|
uint8_t SizeOfT, /*!< [in] AES-CCM MAC (tag) byte size. The valid values depend on the ccm mode:
|
|
<ul><li>CCM: valid values = [4, 6, 8, 10, 12, 14, 16].</li>
|
|
<li>CCM*: valid values = [0, 4, 8, 16].</li></ul>*/
|
|
CRYS_AESCCM_Mac_Res_t Mac_Res, /*!< [in/out] Pointer to the MAC result buffer. */
|
|
uint32_t ccmMode /*!< [in] Flag specifying whether AES-CCM or AES-CCM* should be performed. */
|
|
);
|
|
|
|
/*! Macro defintion for CRYS_AESCCM (AES CCM non-star implementation). */
|
|
#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_AESCCMStar (AES CCM star implementation). */
|
|
#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)
|
|
|
|
|
|
/*!
|
|
@brief 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.
|
|
|
|
@return CRYS_OK on success.
|
|
@return A non-zero value on failure as defined crys_aesccm_error.h.
|
|
*/
|
|
CRYSError_t CRYS_AESCCMStar_NonceGenerate(
|
|
CRYS_AESCCMStar_SourceAddress_t srcAddr, /*!< [in] The MAC address in EUI-64 format. */
|
|
uint32_t FrameCounter, /*!< [in] The MAC frame counter. */
|
|
uint8_t SizeOfT, /*!< [in] AES-CCM* MAC (tag) byte size. Valid values = [0,4,8,16]. */
|
|
CRYS_AESCCMStar_Nonce_t nonce /*!< [out] The required nonce for AES-CCM*. */
|
|
);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
/**
|
|
@}
|
|
*/
|
|
|
|
#endif /*#ifndef CRYS_AESCCM_H*/
|
|
|