ccmLIB.h

00001 /*
00002  * Copyright (c) 2014-2018, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 #ifndef CCMLIB_H_
00018 #define CCMLIB_H_
00019 
00020 #include "ns_types.h"
00021 #include "platform/arm_hal_aes.h"
00022 
00023 /**
00024  *
00025  * \file ccmLIB.h
00026  * \brief CCM Library API.
00027  *
00028  *  \section ccm-api CCM Library API:
00029  *  - ccm_sec_init(), A function to init CCM context.
00030  *  - ccm_process_run(), A function to run configured CCM process.
00031  *
00032  *  \section ccm-instruction CCM process sequence:
00033  *  1. Init CCM context by, ccm key, ccm_sec_init()
00034  *      - security level
00035  *      - 128-bit CCM key
00036  *      - mode: AES_CCM_ENCRYPT or AES_CCM_DECRYPT
00037  *      - CCM L parameter: 2 or 3 depending on the nonce length (802.15.4 use 2 and TLS security use 3)
00038  *  2. Define ADATA pointer and length, if returned global structure mic_len field is > 0
00039  *  3. Set data pointer and length
00040  *  4. Do configured CCM process ccm_process_run()
00041  *  5. Check return value:
00042  *      -If 0 Process ok
00043  *      -< 0 MIC fail or parameter fail
00044  *
00045  */
00046 #ifdef __cplusplus
00047 extern "C" {
00048 #endif
00049 #define AES_NO_SECURITY                 0x00    /**< No security */
00050 #define AES_SECURITY_LEVEL_MIC32        0x01    /**< MIC32 */
00051 #define AES_SECURITY_LEVEL_MIC64        0x02    /**< MIC64 */
00052 #define AES_SECURITY_LEVEL_MIC128       0x03    /**< MIC128 */
00053 #define AES_SECURITY_LEVEL_ENC          0x04    /**< ENC */
00054 #define AES_SECURITY_LEVEL_ENC_MIC32    0x05    /**< ENC_MIC32 */
00055 #define AES_SECURITY_LEVEL_ENC_MIC64    0x06    /**< ENC_MIC64 */
00056 #define AES_SECURITY_LEVEL_ENC_MIC128   0x07    /**< ENC_MIC128 */
00057 
00058 #define AES_CCM_ENCRYPT                 0x00    /**< Encryption mode */
00059 #define AES_CCM_DECRYPT                 0x01    /**< Decryption mode */
00060 
00061 
00062 /*!
00063  * \struct ccm_globals_t
00064  * \brief CCM global structure.
00065  * The structure is used for configuring NONCE, adata and data before calling ccm_process_run().
00066  */
00067 typedef struct {
00068     uint8_t exp_nonce[15];      /**< CCM NONCE buffer Nonce. */
00069     uint8_t *data_ptr;          /**< Pointer to data IN. */
00070     uint16_t data_len;          /**< Length of data IN. */
00071     const uint8_t *adata_ptr;   /**< Pointer to authentication data. */
00072     uint16_t adata_len;         /**< Length of authentication data. */
00073     unsigned ccm_encode_mode: 1; /**< Encryption modeAES_CCM_ENCRYPT or AES_CCM_DECRYPT. */
00074     unsigned ccm_sec_level: 3;  /**< Encryption operation security level 0-7. */
00075     unsigned ccm_l_param: 4;    /**< Can be 2 or 3. 2 when NONCE length is 13 and 3 when 12*/
00076     uint8_t mic_len;            /**< ccm_sec_init() sets here the length of MIC. */
00077     uint8_t *mic;               /**< Encrypt process writes MIC. Decrypt reads it and compares it with the MIC obtained from data. */
00078     const uint8_t *key_ptr;     /**< Encyption key pointer to 128-bit key. */
00079     arm_aes_context_t *aes_context; /**< Allocated AES context. */
00080 } ccm_globals_t;
00081 
00082 
00083 /**
00084  * \brief A function to initialize the CCM context.
00085  * \param ccm_context pointer to initialized XXM context
00086  * \param sec_level Used CCM security level (0-7).
00087  * \param ccm_key Pointer to 128-key.
00088  * \param mode AES_CCM_ENCRYPT or AES_CCM_DECRYPT.
00089  * \param ccm_l Can be 2 or 3. 2 when NONCE length is 13 and 3 when 12. (NONCE length = (15-ccm_l))
00090  *
00091  * \return true when AES context allocation is OK and given parameters.
00092  * \return false CCM parameters or AES context allocation fail.
00093  */
00094 extern bool ccm_sec_init(ccm_globals_t *ccm_context, uint8_t sec_level, const uint8_t *ccm_key, uint8_t mode, uint8_t ccm_l);
00095 
00096 /**
00097  * \brief A function to run the configured CCM process.
00098  * When AES_CCM_ENCRYPT mode is selected and MIC is needed, the library saves MIC right after the encrypted data.
00099  * \param ccm_params CCM parameters
00100  *
00101  * \return 0 CCM process OK and when AES_CCM_DECRYPT mode was selected also MIC was correct.
00102  * \return -1 Init not called or data or adata pointers or lengths are zero.
00103  * \return -2 Null pointer given to function.
00104  */
00105 extern int8_t ccm_process_run(ccm_globals_t *ccm_params);
00106 
00107 /**
00108  * \brief A function to free aes context. Call only if ccm_process_run() is not called
00109  * \param ccm_params CCM parameters
00110  *
00111  */
00112 extern void ccm_free(ccm_globals_t *ccm_params);
00113 
00114 #ifdef __cplusplus
00115 }
00116 #endif
00117 
00118 #endif /* CCMLIB_H_ */