crys_hash.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 HASH APIs, as well as the APIs themselves.
00040 @defgroup crys_hash CryptoCell HASH APIs
00041 @{
00042 @ingroup cryptocell_api
00043 
00044 
00045 This product supports the following HASH algorithms (or modes, according to product):
00046 <ul><li> CRYS_HASH_MD5 (producing 16 byte output).</li>
00047 <li> CRYS_HASH_SHA1 (producing 20 byte output).</li>
00048 <li> CRYS_HASH_SHA224 (producing 28 byte output).</li>
00049 <li> CRYS_HASH_SHA256 (producing 32 byte output).</li>
00050 <li> CRYS_HASH_SHA384 (producing 48 byte output).</li>
00051 <li> CRYS_HASH_SHA512 (producing 64 byte output).</li></ul>
00052 
00053 HASH calculation can be performed in either of the following two modes of operation:
00054 <ul><li> Integrated operation - Processes all data in a single function call. This flow is applicable when all data is available prior to the
00055      cryptographic operation.</li>
00056 <li> Block operation - Processes a subset of the data buffers, and is called multiple times in a sequence. This flow is applicable when the
00057      next data buffer becomes available only during/after processing of the current data buffer.</li></ul>
00058 
00059 The following is a typical HASH Block operation flow:
00060 <ol><li> ::CRYS_HASH_Init - this function initializes the HASH machine on the CRYS level by setting the context pointer that is used on the entire
00061      HASH operation.</li>
00062 <li> ::CRYS_HASH_Update - this function runs a HASH operation on a block of data allocated by the user. This function may be called as many times
00063      as required.</li>
00064 <li> ::CRYS_HASH_Finish - this function ends the HASH operation. It returns the digest result and clears the context.</li></ol>
00065 */
00066 
00067 #ifndef CRYS_HASH_H
00068 #define CRYS_HASH_H
00069 
00070 
00071 #include "ssi_pal_types.h"
00072 #include "crys_error.h"
00073 #include "crys_hash_defs.h"
00074 
00075 
00076 #ifdef __cplusplus
00077 extern "C"
00078 {
00079 #endif
00080 
00081 
00082 /************************ Defines ******************************/
00083 /* The hash result in words
00084 #define CRYS_HASH_RESULT_SIZE_IN_WORDS 5*/
00085 /*! The maximal hash result is 512 bits for SHA512. */
00086 #define CRYS_HASH_RESULT_SIZE_IN_WORDS  16
00087 
00088 /*! MD5 digest result size in bytes. */
00089 #define CRYS_HASH_MD5_DIGEST_SIZE_IN_BYTES 16
00090 
00091 /*! MD5 digest result size in words. */
00092 #define CRYS_HASH_MD5_DIGEST_SIZE_IN_WORDS 4
00093 
00094 /*! SHA-1 digest result size in bytes. */
00095 #define CRYS_HASH_SHA1_DIGEST_SIZE_IN_BYTES 20
00096 
00097 /*! SHA-1 digest result size in words. */
00098 #define CRYS_HASH_SHA1_DIGEST_SIZE_IN_WORDS 5
00099 
00100 /*! SHA-256 digest result size in words. */
00101 #define CRYS_HASH_SHA224_DIGEST_SIZE_IN_WORDS 7
00102 
00103 /*! SHA-256 digest result size in words. */
00104 #define CRYS_HASH_SHA256_DIGEST_SIZE_IN_WORDS 8
00105 
00106 /*! SHA-384 digest result size in words. */
00107 #define CRYS_HASH_SHA384_DIGEST_SIZE_IN_WORDS 12
00108 
00109 /*! SHA-512 digest result size in words. */
00110 #define CRYS_HASH_SHA512_DIGEST_SIZE_IN_WORDS 16
00111 
00112 /*! SHA-256 digest result size in bytes */
00113 #define CRYS_HASH_SHA224_DIGEST_SIZE_IN_BYTES 28
00114 
00115 /*! SHA-256 digest result size in bytes */
00116 #define CRYS_HASH_SHA256_DIGEST_SIZE_IN_BYTES 32
00117 
00118 /*! SHA-384 digest result size in bytes */
00119 #define CRYS_HASH_SHA384_DIGEST_SIZE_IN_BYTES 48
00120 
00121 /*! SHA-512 digest result size in bytes */
00122 #define CRYS_HASH_SHA512_DIGEST_SIZE_IN_BYTES 64
00123 
00124 /*! SHA1 hash block size in words */
00125 #define CRYS_HASH_BLOCK_SIZE_IN_WORDS 16
00126 
00127 /*! SHA1 hash block size in bytes */
00128 #define CRYS_HASH_BLOCK_SIZE_IN_BYTES 64
00129 
00130 /*! SHA2 hash block size in words */
00131 #define CRYS_HASH_SHA512_BLOCK_SIZE_IN_WORDS    32
00132 
00133 /*! SHA2 hash block size in bytes */
00134 #define CRYS_HASH_SHA512_BLOCK_SIZE_IN_BYTES    128
00135 
00136 /*! Maximal data size for update operation. */
00137 #define CRYS_HASH_UPDATE_DATA_MAX_SIZE_IN_BYTES (1 << 29)
00138 
00139 
00140 /************************ Enums ********************************/
00141 
00142 /*!
00143 HASH operation mode
00144 */
00145 typedef enum {
00146     CRYS_HASH_SHA1_mode           = 0,    /*!< SHA1. */
00147     CRYS_HASH_SHA224_mode         = 1,    /*!< SHA224. */
00148     CRYS_HASH_SHA256_mode         = 2,    /*!< SHA256. */
00149     CRYS_HASH_SHA384_mode         = 3,    /*!< SHA384. */
00150     CRYS_HASH_SHA512_mode         = 4,    /*!< SHA512. */
00151     CRYS_HASH_MD5_mode            = 5,    /*!< MD5. */
00152     /*! Number of hash modes. */
00153     CRYS_HASH_NumOfModes ,
00154     /*! Reserved. */
00155     CRYS_HASH_OperationModeLast = 0x7FFFFFFF,
00156 
00157 }CRYS_HASH_OperationMode_t ;
00158 
00159 /************************ Typedefs  *****************************/
00160 
00161 /*! HASH result buffer. */
00162 typedef uint32_t CRYS_HASH_Result_t [CRYS_HASH_RESULT_SIZE_IN_WORDS];
00163 
00164 /************************ Structs  ******************************/
00165 /*! The user's context prototype - the argument type that is passed by the user
00166    to the HASH APIs. The context saves the state of the operation and must be saved by the user
00167    till the end of the APIs flow. */
00168 typedef struct CRYS_HASHUserContext_t  {
00169     /*! Internal buffer */
00170     uint32_t buff [CRYS_HASH_USER_CTX_SIZE_IN_WORDS];
00171 }CRYS_HASHUserContext_t ;
00172 
00173 /************************ Public Variables **********************/
00174 
00175 /************************ Public Functions **********************/
00176 
00177 
00178 /************************************************************************************************/
00179 /*!
00180 @brief This function initializes the HASH machine and the HASH Context.
00181 
00182 It receives as input a pointer to store the context handle to the HASH Context,
00183 and initializes the HASH Context with the cryptographic attributes that are needed for the HASH block operation (initializes H's value for the HASH algorithm).
00184 
00185 @return CRYS_OK on success.
00186 @return A non-zero value from crys_hash_error.h on failure.
00187 */
00188 CIMPORT_C CRYSError_t  CRYS_HASH_Init(
00189                         CRYS_HASHUserContext_t      *ContextID_ptr,         /*!< [in]  Pointer to the HASH context buffer allocated by the user that is used
00190                                         for the HASH machine operation. */
00191                         CRYS_HASH_OperationMode_t   OperationMode           /*!< [in]  One of the supported HASH modes, as defined in CRYS_HASH_OperationMode_t. */
00192 );
00193 
00194 /************************************************************************************************/
00195 /*!
00196 @brief This function processes a block of data to be HASHed.
00197 
00198 It updates a HASH Context that was previously initialized by CRYS_HASH_Init or updated by a previous call to CRYS_HASH_Update.
00199 
00200 @return CRYS_OK on success.
00201 @return A non-zero value from crys_hash_error.h on failure.
00202 */
00203 
00204 CIMPORT_C CRYSError_t  CRYS_HASH_Update(
00205                         CRYS_HASHUserContext_t   *ContextID_ptr,         /*!< [in]  Pointer to the HASH context buffer allocated by the user, which is used for the
00206                                            HASH machine operation. */
00207                         uint8_t                 *DataIn_ptr,            /*!< [in]  Pointer to the input data to be HASHed.
00208                                                                                    it is a one contiguous memory block. */
00209                         size_t                 DataInSize             /*!< [in]  Byte size of the input data. Must be > 0.
00210                                                                                     If not a multiple of the HASH block size (64 for MD5, SHA-1 and SHA-224/256,
00211                                             128 for SHA-384/512), no further calls
00212                                                                                     to CRYS_HASH_Update are allowed in this context, and only CRYS_HASH_Finish
00213                                             can be called to complete the computation. */
00214 );
00215 
00216 /************************************************************************************************/
00217 /*!
00218 @brief This function finalizes the hashing process of data block.
00219 
00220 It receives a handle to the HASH Context, which was previously initialized by CRYS_HASH_Init or by CRYS_HASH_Update.
00221 It "adds" a header to the data block according to the relevant HASH standard, and computes the final message digest.
00222 
00223 @return CRYS_OK on success.
00224 @return A non-zero value from crys_hash_error.h on failure.
00225 */
00226 
00227 CIMPORT_C CRYSError_t  CRYS_HASH_Finish(
00228                         CRYS_HASHUserContext_t   *ContextID_ptr,         /*!< [in]  Pointer to the HASH context buffer allocated by the user that is used for
00229                                            the HASH machine operation. */
00230                         CRYS_HASH_Result_t       HashResultBuff         /*!< [in]  Pointer to the word-aligned 64 byte buffer. The actual size of the HASH
00231                                            result depends on CRYS_HASH_OperationMode_t. */
00232 );
00233 
00234 
00235 /************************************************************************************************/
00236 /*!
00237 @brief This function is a utility function that frees the context if the operation has failed.
00238 
00239 The function executes the following major steps:
00240 <ol><li> Checks the validity of all of the inputs of the function. </li>
00241 <li> Clears the user's context.</li>
00242 <li> Exits the handler with the OK code.</li></ol>
00243 
00244 @return CRYS_OK on success.
00245 @return A non-zero value from crys_hash_error.h on failure.
00246 */
00247 
00248 CIMPORT_C CRYSError_t   CRYS_HASH_Free(
00249                         CRYS_HASHUserContext_t   *ContextID_ptr         /*!< [in]  Pointer to the HASH context buffer allocated by the user that is used for
00250                                          the HASH machine operation. */
00251 );
00252 
00253 
00254 /************************************************************************************************/
00255 /*!
00256 @brief This function processes a single buffer of data.
00257 
00258 The function allocates an internal HASH Context, and initializes it with the cryptographic attributes
00259 that are needed for the HASH block operation (initialize H's value for the HASH algorithm).
00260 Then it processes the data block, calculating the HASH. Finally, it returns the data buffer's message digest.
00261 
00262 @return CRYS_OK on success.
00263 @return A non-zero value from crys_hash_error.h on failure.
00264  */
00265 
00266 CIMPORT_C CRYSError_t  CRYS_HASH  (
00267                         CRYS_HASH_OperationMode_t   OperationMode,       /*!< [in]  One of the supported HASH modes, as defined in CRYS_HASH_OperationMode_t. */
00268                         uint8_t                   *DataIn_ptr,          /*!< [in]  Pointer to the input data to be HASHed.
00269                                                                                    The size of the scatter/gather list representing the data buffer is limited
00270                                            to 128 entries, and the size of each entry is limited to 64KB
00271                                            (fragments larger than 64KB are broken into fragments <= 64KB). */
00272                         size_t                   DataSize,            /*!< [in]  The size of the data to be hashed in bytes. */
00273                         CRYS_HASH_Result_t         HashResultBuff       /*!< [out] Pointer to a word-aligned 64 byte buffer. The actual size of the HASH
00274                                            result depends on CRYS_HASH_OperationMode_t. */
00275 );
00276 
00277 
00278 
00279 #ifdef __cplusplus
00280 }
00281 #endif
00282 /**
00283 @}
00284  */
00285 #endif