owner-nrf52sdk/nRF5_SDK_15.2.0/external/nrf_cc310_bl/include/crys_aesccm.h

/**************************************************************************************
* 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*/