crys_hmac.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
00039 that are used for the CRYS HMAC APIs, as well as the APIs themselves.
00040 @defgroup crys_hmac CryptoCell HMAC APIs
00041 @{
00042 @ingroup cryptocell_api
00043 
00044 
00045 HMAC is a wrapping algorithm that uses a HASH function (one of the supported HASH algorithms, as specified in the HASH chapter) and a key,
00046 to generate a unique authentication code over the input data.
00047 HMAC calculation can be performed in either of the following two modes of operation:
00048 <ul><li> Integrated operation - Processes all data in a single function call. This flow is applicable when all data is available prior to
00049 the cryptographic operation.</li>
00050 <li> Block operation - Processes a subset of the data buffers, and is called multiple times in a sequence. This flow is applicable when
00051 the next data buffer becomes available only during/after processing of the current data buffer.</li></ul>
00052 
00053 The following is a typical HMAC Block operation flow:
00054 <ol><li> ::CRYS_HMAC_Init: This function initializes the HMAC machine on the CRYS level by setting the context pointer that is
00055     used on the entire HMAC operation.</li>
00056 <li> ::CRYS_HMAC_Update: This function runs an HMAC operation on a block of data allocated by the user. This function may be called as
00057      many times as required.</li>
00058 <li> ::CRYS_HMAC_Finish: This function ends the HMAC operation. It returns the digest result and clears the context.</li></ol>
00059 */
00060 
00061 #ifndef CRYS_HMAC_H
00062 #define CRYS_HMAC_H
00063 
00064 
00065 #include "ssi_pal_types.h"
00066 #include "crys_error.h"
00067 
00068 #include "crys_hash.h"
00069 #include "crys_hmac_defs.h"
00070 
00071 #ifdef __cplusplus
00072 extern "C"
00073 {
00074 #endif
00075 
00076 
00077 /************************ Defines ******************************/
00078 
00079 /*! HMAC key size after padding for MD5, SHA1, SHA256. */
00080 #define CRYS_HMAC_KEY_SIZE_IN_BYTES 64
00081 
00082 /*! HMAC key size after padding for SHA384, SHA512 */
00083 #define CRYS_HMAC_SHA2_1024BIT_KEY_SIZE_IN_BYTES 128
00084 
00085 /************************ Enums ********************************/
00086 
00087 /************************ Typedefs  ****************************/
00088 
00089 /*********************** Structures ****************************/
00090 
00091 
00092 /*! User's context prototype - the argument type that is passed by the user
00093    to the HMAC APIs. The context saves the state of the operation and must be saved by the user
00094    till the end of the APIs flow */
00095 typedef struct CRYS_HMACUserContext_t  {
00096     /*! Context buffer for internal use */
00097     uint32_t buff [CRYS_HMAC_USER_CTX_SIZE_IN_WORDS];
00098 
00099 }CRYS_HMACUserContext_t ;
00100 
00101 /************************ Structs  ******************************/
00102 
00103 
00104 /************************ Public Variables **********************/
00105 
00106 
00107 /************************ Public Functions **********************/
00108 
00109 /*!
00110 @brief This function initializes the HMAC machine.
00111 
00112 It allocates and initializes the HMAC Context. It initiates a HASH session and processes a HASH update on the Key XOR ipad,
00113 then stores it in the context
00114 
00115 @return CRYS_OK on success.
00116 @return A non-zero value from crys_hmac_error.h or crys_hash_error.h on failure.
00117 */
00118 CIMPORT_C CRYSError_t  CRYS_HMAC_Init(
00119                         CRYS_HMACUserContext_t      *ContextID_ptr,         /*!< [in]  Pointer to the HMAC context buffer allocated by the user, which is used
00120                                               for the HMAC machine operation. */
00121                         CRYS_HASH_OperationMode_t   OperationMode,          /*!< [in]  One of the supported HASH modes, as defined in CRYS_HASH_OperationMode_t. */
00122                         uint8_t                    *key_ptr,               /*!< [in]  The pointer to the user's key buffer. */
00123                         uint16_t                    keySize                /*!< [in]  The key size in bytes. If the key size is bigger than the HASH block, the key will be hashed.
00124                                          The limitations on the key size are the same as the limitations on MAX hash size. */
00125 );
00126 
00127 
00128 /*!
00129 @brief This function processes a block of data to be HASHed.
00130 
00131 It receives a handle to the HMAC Context, and updates the HASH value with the new data.
00132 
00133 @return CRYS_OK on success.
00134 @return A non-zero value from crys_hmac_error.h or crys_hash_error.h on failure.
00135 */
00136 
00137 CIMPORT_C CRYSError_t  CRYS_HMAC_Update(
00138                         CRYS_HMACUserContext_t   *ContextID_ptr,         /*!< [in]  Pointer to the HMAC context buffer allocated by the user
00139                                            that is used for the HMAC machine operation. */
00140                         uint8_t                 *DataIn_ptr,            /*!< [in]  Pointer to the input data to be HASHed.
00141                                                                                    The size of the scatter/gather list representing the data buffer is limited to
00142                                            128 entries, and the size of each entry is limited to 64KB
00143                                            (fragments larger than 64KB are broken into fragments <= 64KB). */
00144                         size_t                 DataInSize             /*!< [in]  Byte size of the input data. Must be > 0.
00145                                                                                    If not a multiple of the HASH block size (64 for SHA-1 and SHA-224/256,
00146                                            128 for SHA-384/512), no further calls to ::CRYS_HMAC_Update are allowed in
00147                                            this context, and only ::CRYS_HMAC_Finish can be called to complete the
00148                                            computation. */
00149 );
00150 
00151 
00152 /*!
00153 @brief This function finalizes the HMAC processing of a data block.
00154 
00155 It receives a handle to the HMAC context that was previously initialized by ::CRYS_HMAC_Init, or by ::CRYS_HMAC_Update.
00156 It completes the HASH calculation on the ipad and text, and then executes a new HASH operation with the key XOR opad and the previous
00157 HASH operation result.
00158 
00159 @return CRYS_OK on success.
00160 @return A non-zero value from crys_hmac_error.h or crys_hash_error.h on failure.
00161 */
00162 
00163 CIMPORT_C CRYSError_t  CRYS_HMAC_Finish(
00164                         CRYS_HMACUserContext_t   *ContextID_ptr,         /*!< [in]  Pointer to the HMAC context buffer allocated by the user, which is used
00165                                            for the HMAC machine operation. */
00166                         CRYS_HASH_Result_t        HmacResultBuff         /*!< [out] Pointer to the word-aligned 64 byte buffer. The actual size of the
00167                                            HASH result depends on CRYS_HASH_OperationMode_t. */
00168 );
00169 
00170 
00171 /*!
00172 @brief This function is a service function that frees the context if the operation has failed.
00173 
00174 The function executes the following major steps:
00175 <ol><li> Checks the validity of all of the inputs of the function. </li>
00176 <li> Clears the user's context.</li>
00177 <li> Exits the handler with the OK code.</li></ol>
00178 
00179 @return CRYS_OK on success.
00180 @return a non-zero value from crys_hmac_error.h on failure.
00181 */
00182 
00183 CIMPORT_C CRYSError_t   CRYS_HMAC_Free(
00184                         CRYS_HMACUserContext_t   *ContextID_ptr         /*!< [in]  Pointer to the HMAC context buffer allocated by the user, which is used for
00185                                           the HMAC machine operation. */
00186 );
00187 
00188 
00189 /*!
00190 @brief This function processes a single buffer of data, and returns the data buffer's message digest.
00191 
00192 @return CRYS_OK on success.
00193 @return A non-zero value from crys_hmac_error.h or crys_hash_error.h on failure.
00194 */
00195 CIMPORT_C CRYSError_t  CRYS_HMAC  (
00196                         CRYS_HASH_OperationMode_t   OperationMode,       /*!< [in]  One of the supported HASH modes, as defined in CRYS_HASH_OperationMode_t. */
00197                         uint8_t                    *key_ptr,            /*!< [in]  The pointer to the user's key buffer. */
00198                         uint16_t                    keySize,            /*!< [in]  The key size in bytes. If the key size is bigger than the HASH block, the key will be hashed.
00199                                          The limitations on the key size are the same as the limitations on MAX hash size.*/
00200                         uint8_t                    *DataIn_ptr,         /*!< [in]  Pointer to the input data to be HASHed.
00201                                                                                    The size of the scatter/gather list representing the data buffer is limited to 128
00202                                            entries, and the size of each entry is limited to 64KB (fragments larger than
00203                                            64KB are broken into fragments <= 64KB). */
00204                         size_t                    DataSize,           /*!< [in]  The size of the data to be hashed (in bytes). */
00205                         CRYS_HASH_Result_t           HmacResultBuff      /*!< [out] Pointer to the word-aligned 64 byte buffer. The actual size of the
00206                                            HMAC result depends on CRYS_HASH_OperationMode_t. */
00207 );
00208 #ifdef __cplusplus
00209 }
00210 #endif
00211 /**
00212 @}
00213  */
00214 #endif