crys_chacha.h

00001 /**************************************************************************************
00002 * Copyright (c) 2016-2017, ARM Limited or its affiliates. All rights reserved         *
00003 *                                                                                     *
00004 * This file and the related binary are licensed under the following license:          *
00005 *                                                                                     *
00006 * ARM Object Code and Header Files License, v1.0 Redistribution.                      *
00007 *                                                                                     *
00008 * Redistribution and use of object code, header files, and documentation, without     *
00009 * modification, are permitted provided that the following conditions are met:         *
00010 *                                                                                     *
00011 * 1) Redistributions must reproduce the above copyright notice and the                *
00012 *    following disclaimer in the documentation and/or other materials                 *
00013 *    provided with the distribution.                                                  *
00014 *                                                                                     *
00015 * 2) Unless to the extent explicitly permitted by law, no reverse                     *
00016 *    engineering, decompilation, or disassembly of is permitted.                      *
00017 *                                                                                     *
00018 * 3) Redistribution and use is permitted solely for the purpose of                    *
00019 *    developing or executing applications that are targeted for use                   *
00020 *    on an ARM-based product.                                                         *
00021 *                                                                                     *
00022 * DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND                  *
00023 * CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT             *
00024 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT,        *
00025 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE          *
00026 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,   *
00027 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED            *
00028 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR              *
00029 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF              *
00030 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING                *
00031 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS                  *
00032 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                        *
00033 **************************************************************************************/
00034 
00035 
00036 /*!
00037 @file
00038 @brief This file contains all of the enums and definitions that are used for the
00039          CRYS CHACHA APIs, as well as the APIs themselves.
00040 @defgroup crys_chacha CryptoCell CHACHA APIs
00041 @{
00042 @ingroup cryptocell_api
00043 */
00044 #ifndef CRYS_CHACHA_H
00045 #define CRYS_CHACHA_H
00046 
00047 
00048 #include "ssi_pal_types.h"
00049 #include "crys_error.h"
00050 
00051 
00052 #ifdef __cplusplus
00053 extern "C"
00054 {
00055 #endif
00056 
00057 /************************ Defines ******************************/
00058 /*! CHACHA user's context size in words. */
00059 #define CRYS_CHACHA_USER_CTX_SIZE_IN_WORDS 17
00060 
00061 /*! CHACHA block size in words. */
00062 #define CRYS_CHACHA_BLOCK_SIZE_IN_WORDS 16
00063 /*! CHACHA block size in bytes. */
00064 #define CRYS_CHACHA_BLOCK_SIZE_IN_BYTES  (CRYS_CHACHA_BLOCK_SIZE_IN_WORDS * sizeof(uint32_t))
00065 
00066 /*! Nonce buffer max size in words. */
00067 #define CRYS_CHACHA_NONCE_MAX_SIZE_IN_WORDS   3
00068 /*! Nonce buffer max size in bytes. */
00069 #define CRYS_CHACHA_NONCE_MAX_SIZE_IN_BYTES  (CRYS_CHACHA_NONCE_MAX_SIZE_IN_WORDS * sizeof(uint32_t))
00070 
00071 /*! CHACHA KEY maximal size in words. */
00072 #define CRYS_CHACHA_KEY_MAX_SIZE_IN_WORDS 8
00073 /*! CHACHA KEY maximal size in bytes. */
00074 #define CRYS_CHACHA_KEY_MAX_SIZE_IN_BYTES (CRYS_CHACHA_KEY_MAX_SIZE_IN_WORDS * sizeof(uint32_t))
00075 
00076 /************************ Enums ********************************/
00077 
00078 /*! Enum defining the CHACHA Encrypt or Decrypt operation mode. */
00079 typedef enum {
00080     /*! CHACHA encrypt mode. */
00081     CRYS_CHACHA_Encrypt  = 0,
00082     /*! CHACHA decrypt mode. */
00083     CRYS_CHACHA_Decrypt  = 1,
00084     /*! CHACHA maximal number of operations (encrypt/decrypt). */
00085     CRYS_CHACHA_EncryptNumOfOptions ,
00086 
00087     /*! Reserved. */
00088     CRYS_CHACHA_EncryptModeLast  = 0x7FFFFFFF,
00089 
00090 }CRYS_CHACHA_EncryptMode_t ;
00091 
00092 /*! Enum defining the CHACHA Nonce size in bits. */
00093 typedef enum {
00094     /*! 64 bit Nonce size. */
00095         CRYS_CHACHA_Nonce64BitSize  = 0,
00096     /*! 96 bit Nonce size. */
00097         CRYS_CHACHA_Nonce96BitSize  = 1,
00098     /*! CHACHA maximal number of nonce sizes. */
00099         CRYS_CHACHA_NonceSizeNumOfOptions ,
00100     /*! Reserved. */
00101         CRYS_CHACHA_NonceSizeLast  = 0x7FFFFFFF,
00102 
00103 }CRYS_CHACHA_NonceSize_t ;
00104 
00105 /************************ Typedefs  ****************************/
00106 
00107 /*! Defines the Nonce buffer 12 bytes array. */
00108 typedef uint8_t CRYS_CHACHA_Nonce_t [CRYS_CHACHA_NONCE_MAX_SIZE_IN_BYTES];
00109 
00110 /*! Defines the CHACHA key buffer. */
00111 typedef uint8_t CRYS_CHACHA_Key_t [CRYS_CHACHA_KEY_MAX_SIZE_IN_BYTES];
00112 
00113 
00114 /************************ context Structs  ******************************/
00115 
00116 /*! The user's context prototype - the argument type that is passed by the user
00117    to the CHACHA API. The context saves the state of the operation and must be saved by the user
00118    till the end of the APIs flow (for example till ::CRYS_CHACHA_Free is called). */
00119 typedef struct CRYS_CHACHAUserContext_t  {
00120     /* Allocated buffer must be double the size of actual context
00121      * + 1 word for offset management */
00122     /*! Context buffer for internal use */
00123     uint32_t buff [CRYS_CHACHA_USER_CTX_SIZE_IN_WORDS];
00124 }CRYS_CHACHAUserContext_t ;
00125 
00126 /************************ Public Variables **********************/
00127 
00128 
00129 /************************ Public Functions **********************/
00130 
00131 /****************************************************************************************************/
00132 
00133 /*!
00134 @brief This function is used to initialize the context for CHACHA operations.
00135 
00136 @return CRYS_OK on success.
00137 @return A non-zero value on failure as defined crys_chacha_error.h.
00138 */
00139 CIMPORT_C CRYSError_t   CRYS_CHACHA_Init(
00140                         CRYS_CHACHAUserContext_t     *pContextID,        /*!< [in]  Pointer to the CHACHA context buffer that is allocated by the user
00141                                                                                    and is used for the CHACHA operation. */
00142                         CRYS_CHACHA_Nonce_t          pNonce,            /*!< [in]  A buffer containing an nonce. */
00143                         CRYS_CHACHA_NonceSize_t       nonceSize,         /*!< [in]  Enumerator defining the nonce size (only 64 and 96 bit are valid). */
00144                         CRYS_CHACHA_Key_t            pKey,               /*!< [in]  A pointer to the user's key buffer. */
00145                         uint32_t                     initialCounter,     /*!< [in]  An initial counter. */
00146                         CRYS_CHACHA_EncryptMode_t     EncryptDecryptFlag  /*!< [in]  A flag specifying whether the CHACHA should perform an Encrypt operation
00147                                                                                    or a Decrypt operation. */
00148 );
00149 
00150 
00151 /*!
00152 @brief This function is used to process aligned blocks of CHACHA.
00153 The data in size should be a multiple of chacha block size.
00154 
00155 @return CRYS_OK on success.
00156 @return A non-zero value on failure as defined crys_chacha_error.h.
00157 */
00158 CIMPORT_C CRYSError_t   CRYS_CHACHA_Block(
00159                         CRYS_CHACHAUserContext_t     *pContextID,        /*!< [in] Pointer to the context buffer. */
00160                         uint8_t                     *pDataIn,           /*!< [in]  A pointer to the buffer of the input data to the CHACHA.
00161                                                                                    The pointer does not need to be aligned. must not be null. */
00162                         uint32_t                    dataInSize,         /*!< [in]  The size of the input data.
00163                                                                                    Must be a multiple of ::CRYS_CHACHA_BLOCK_SIZE_IN_BYTES bytes and must not be 0. */
00164                         uint8_t                     *pDataOut           /*!< [out] A pointer to the buffer of the output data from the CHACHA.
00165                                                                                    The pointer does not need to be aligned. must not be null. */
00166 );
00167 
00168 
00169 /*!
00170 @brief This function is used to process the remaining data of CHACHA.
00171 The data in size should be smaller than chacha block size.
00172 
00173 @return CRYS_OK on success.
00174 @return A non-zero value on failure as defined crys_chacha_error.h.
00175 */
00176 CIMPORT_C CRYSError_t   CRYS_CHACHA_Finish(
00177                         CRYS_CHACHAUserContext_t     *pContextID,        /*!< [in]  Pointer to the context buffer. */
00178                         uint8_t                     *pDataIn,           /*!< [in]  A pointer to the buffer of the input data to the CHACHA.
00179                                                                                    The pointer does not need to be aligned. If dataInSize = 0, input buffer is not required. */
00180                         uint32_t                    dataInSize,         /*!< [in]  The size of the input data.
00181                                                                                    zero and non multiple of ::CRYS_CHACHA_BLOCK_SIZE_IN_BYTES are valid. */
00182                         uint8_t                     *pDataOut           /*!< [out] A pointer to the buffer of the output data from the CHACHA.
00183                                                                                    The pointer does not need to be aligned. If dataInSize = 0, output buffer is not required. */
00184 );
00185 
00186 
00187 /*!
00188 @brief This function is used to free the context of CHACHA operations.
00189 
00190 @return CRYS_OK on success.
00191 @return A non-zero value on failure as defined crys_chacha_error.h.
00192 */
00193 CIMPORT_C CRYSError_t   CRYS_CHACHA_Free(
00194                         CRYS_CHACHAUserContext_t  *pContextID    /*!< [in] Pointer to the context buffer. */
00195 );
00196 
00197 
00198 /*!
00199 @brief This function is used to perform the CHACHA operation in one integrated process.
00200 
00201 @return CRYS_OK on success.
00202 @return A non-zero value on failure as defined crys_chacha_error.h.
00203 */
00204 CIMPORT_C CRYSError_t   CRYS_CHACHA(
00205                             CRYS_CHACHA_Nonce_t           pNonce,           /*!< [in]  A buffer containing an nonce. */
00206                             CRYS_CHACHA_NonceSize_t        nonceSize,               /*!< [in]  Enumerator defining the nonce size (only 64 and 96 bit are valid). */
00207                             CRYS_CHACHA_Key_t             pKey,                 /*!< [in]  A pointer to the user's key buffer. */
00208                             uint32_t                      initialCounter,       /*!< [in]  An initial counter. */
00209                             CRYS_CHACHA_EncryptMode_t      encryptDecryptFlag,   /*!< [in]  A flag specifying whether the CHACHA should perform an Encrypt operation
00210                                                                                                 or a Decrypt operation. */
00211                             uint8_t                      *pDataIn,              /*!< [in]  A pointer to the buffer of the input data to the CHACHA.
00212                                                                                            The pointer does not need to be aligned. must not be null. */
00213                             uint32_t                      dataInSize,           /*!< [in]  The size of the input data. must not be 0. */
00214                             uint8_t                      *pDataOut              /*!< [out] A pointer to the buffer of the output data from the CHACHA.
00215                                                                                            The pointer does not need to be aligned. must not be null. */
00216 );
00217 
00218 
00219 /***********************************************************************************/
00220 
00221 #ifdef __cplusplus
00222 }
00223 #endif
00224 
00225 /**
00226 @}
00227  */
00228 
00229 #endif /* #ifndef CRYS_CHACHA_H */
00230 
00231 
00232 
00233 
00234