| /************************************************************************************** |
| * 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. * |
| **************************************************************************************/ |
| |
| |
| /*! |
| @file |
| @brief This file contains all of the enums and definitions |
| that are used for the CRYS HASH APIs, as well as the APIs themselves. |
| @defgroup crys_hash CryptoCell HASH APIs |
| @{ |
| @ingroup cryptocell_api |
| |
| |
| This product supports the following HASH algorithms (or modes, according to product): |
| <ul><li> CRYS_HASH_MD5 (producing 16 byte output).</li> |
| <li> CRYS_HASH_SHA1 (producing 20 byte output).</li> |
| <li> CRYS_HASH_SHA224 (producing 28 byte output).</li> |
| <li> CRYS_HASH_SHA256 (producing 32 byte output).</li> |
| <li> CRYS_HASH_SHA384 (producing 48 byte output).</li> |
| <li> CRYS_HASH_SHA512 (producing 64 byte output).</li></ul> |
| |
| HASH calculation can be performed in either of the following two modes of operation: |
| <ul><li> Integrated operation - Processes all data in a single function call. This flow is applicable when all data is available prior to the |
| cryptographic operation.</li> |
| <li> Block operation - Processes a subset of the data buffers, and is called multiple times in a sequence. This flow is applicable when the |
| next data buffer becomes available only during/after processing of the current data buffer.</li></ul> |
| |
| The following is a typical HASH Block operation flow: |
| <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 |
| HASH operation.</li> |
| <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 |
| as required.</li> |
| <li> ::CRYS_HASH_Finish - this function ends the HASH operation. It returns the digest result and clears the context.</li></ol> |
| */ |
| |
| #ifndef CRYS_HASH_H |
| #define CRYS_HASH_H |
| |
| |
| #include "ssi_pal_types.h" |
| #include "crys_error.h" |
| #include "crys_hash_defs.h" |
| |
| |
| #ifdef __cplusplus |
| extern "C" |
| { |
| #endif |
| |
| |
| /************************ Defines ******************************/ |
| /* The hash result in words |
| #define CRYS_HASH_RESULT_SIZE_IN_WORDS 5*/ |
| /*! The maximal hash result is 512 bits for SHA512. */ |
| #define CRYS_HASH_RESULT_SIZE_IN_WORDS 16 |
| |
| /*! MD5 digest result size in bytes. */ |
| #define CRYS_HASH_MD5_DIGEST_SIZE_IN_BYTES 16 |
| |
| /*! MD5 digest result size in words. */ |
| #define CRYS_HASH_MD5_DIGEST_SIZE_IN_WORDS 4 |
| |
| /*! SHA-1 digest result size in bytes. */ |
| #define CRYS_HASH_SHA1_DIGEST_SIZE_IN_BYTES 20 |
| |
| /*! SHA-1 digest result size in words. */ |
| #define CRYS_HASH_SHA1_DIGEST_SIZE_IN_WORDS 5 |
| |
| /*! SHA-256 digest result size in words. */ |
| #define CRYS_HASH_SHA224_DIGEST_SIZE_IN_WORDS 7 |
| |
| /*! SHA-256 digest result size in words. */ |
| #define CRYS_HASH_SHA256_DIGEST_SIZE_IN_WORDS 8 |
| |
| /*! SHA-384 digest result size in words. */ |
| #define CRYS_HASH_SHA384_DIGEST_SIZE_IN_WORDS 12 |
| |
| /*! SHA-512 digest result size in words. */ |
| #define CRYS_HASH_SHA512_DIGEST_SIZE_IN_WORDS 16 |
| |
| /*! SHA-256 digest result size in bytes */ |
| #define CRYS_HASH_SHA224_DIGEST_SIZE_IN_BYTES 28 |
| |
| /*! SHA-256 digest result size in bytes */ |
| #define CRYS_HASH_SHA256_DIGEST_SIZE_IN_BYTES 32 |
| |
| /*! SHA-384 digest result size in bytes */ |
| #define CRYS_HASH_SHA384_DIGEST_SIZE_IN_BYTES 48 |
| |
| /*! SHA-512 digest result size in bytes */ |
| #define CRYS_HASH_SHA512_DIGEST_SIZE_IN_BYTES 64 |
| |
| /*! SHA1 hash block size in words */ |
| #define CRYS_HASH_BLOCK_SIZE_IN_WORDS 16 |
| |
| /*! SHA1 hash block size in bytes */ |
| #define CRYS_HASH_BLOCK_SIZE_IN_BYTES 64 |
| |
| /*! SHA2 hash block size in words */ |
| #define CRYS_HASH_SHA512_BLOCK_SIZE_IN_WORDS 32 |
| |
| /*! SHA2 hash block size in bytes */ |
| #define CRYS_HASH_SHA512_BLOCK_SIZE_IN_BYTES 128 |
| |
| /*! Maximal data size for update operation. */ |
| #define CRYS_HASH_UPDATE_DATA_MAX_SIZE_IN_BYTES (1 << 29) |
| |
| |
| /************************ Enums ********************************/ |
| |
| /*! |
| HASH operation mode |
| */ |
| typedef enum { |
| CRYS_HASH_SHA1_mode = 0, /*!< SHA1. */ |
| CRYS_HASH_SHA224_mode = 1, /*!< SHA224. */ |
| CRYS_HASH_SHA256_mode = 2, /*!< SHA256. */ |
| CRYS_HASH_SHA384_mode = 3, /*!< SHA384. */ |
| CRYS_HASH_SHA512_mode = 4, /*!< SHA512. */ |
| CRYS_HASH_MD5_mode = 5, /*!< MD5. */ |
| /*! Number of hash modes. */ |
| CRYS_HASH_NumOfModes, |
| /*! Reserved. */ |
| CRYS_HASH_OperationModeLast= 0x7FFFFFFF, |
| |
| }CRYS_HASH_OperationMode_t; |
| |
| /************************ Typedefs *****************************/ |
| |
| /*! HASH result buffer. */ |
| typedef uint32_t CRYS_HASH_Result_t[CRYS_HASH_RESULT_SIZE_IN_WORDS]; |
| |
| /************************ Structs ******************************/ |
| /*! The user's context prototype - the argument type that is passed by the user |
| to the HASH APIs. The context saves the state of the operation and must be saved by the user |
| till the end of the APIs flow. */ |
| typedef struct CRYS_HASHUserContext_t { |
| /*! Internal buffer */ |
| uint32_t buff[CRYS_HASH_USER_CTX_SIZE_IN_WORDS]; |
| }CRYS_HASHUserContext_t; |
| |
| /************************ Public Variables **********************/ |
| |
| /************************ Public Functions **********************/ |
| |
| |
| /************************************************************************************************/ |
| /*! |
| @brief This function initializes the HASH machine and the HASH Context. |
| |
| It receives as input a pointer to store the context handle to the HASH Context, |
| 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). |
| |
| @return CRYS_OK on success. |
| @return A non-zero value from crys_hash_error.h on failure. |
| */ |
| CIMPORT_C CRYSError_t CRYS_HASH_Init( |
| CRYS_HASHUserContext_t *ContextID_ptr, /*!< [in] Pointer to the HASH context buffer allocated by the user that is used |
| for the HASH machine operation. */ |
| CRYS_HASH_OperationMode_t OperationMode /*!< [in] One of the supported HASH modes, as defined in CRYS_HASH_OperationMode_t. */ |
| ); |
| |
| /************************************************************************************************/ |
| /*! |
| @brief This function processes a block of data to be HASHed. |
| |
| It updates a HASH Context that was previously initialized by CRYS_HASH_Init or updated by a previous call to CRYS_HASH_Update. |
| |
| @return CRYS_OK on success. |
| @return A non-zero value from crys_hash_error.h on failure. |
| */ |
| |
| CIMPORT_C CRYSError_t CRYS_HASH_Update( |
| CRYS_HASHUserContext_t *ContextID_ptr, /*!< [in] Pointer to the HASH context buffer allocated by the user, which is used for the |
| HASH machine operation. */ |
| uint8_t *DataIn_ptr, /*!< [in] Pointer to the input data to be HASHed. |
| it is a one contiguous memory block. */ |
| size_t DataInSize /*!< [in] Byte size of the input data. Must be > 0. |
| If not a multiple of the HASH block size (64 for MD5, SHA-1 and SHA-224/256, |
| 128 for SHA-384/512), no further calls |
| to CRYS_HASH_Update are allowed in this context, and only CRYS_HASH_Finish |
| can be called to complete the computation. */ |
| ); |
| |
| /************************************************************************************************/ |
| /*! |
| @brief This function finalizes the hashing process of data block. |
| |
| It receives a handle to the HASH Context, which was previously initialized by CRYS_HASH_Init or by CRYS_HASH_Update. |
| It "adds" a header to the data block according to the relevant HASH standard, and computes the final message digest. |
| |
| @return CRYS_OK on success. |
| @return A non-zero value from crys_hash_error.h on failure. |
| */ |
| |
| CIMPORT_C CRYSError_t CRYS_HASH_Finish( |
| CRYS_HASHUserContext_t *ContextID_ptr, /*!< [in] Pointer to the HASH context buffer allocated by the user that is used for |
| the HASH machine operation. */ |
| CRYS_HASH_Result_t HashResultBuff /*!< [in] Pointer to the word-aligned 64 byte buffer. The actual size of the HASH |
| result depends on CRYS_HASH_OperationMode_t. */ |
| ); |
| |
| |
| /************************************************************************************************/ |
| /*! |
| @brief This function is a utility function that frees the context if the operation has failed. |
| |
| The function executes the following major steps: |
| <ol><li> Checks the validity of all of the inputs of the function. </li> |
| <li> Clears the user's context.</li> |
| <li> Exits the handler with the OK code.</li></ol> |
| |
| @return CRYS_OK on success. |
| @return A non-zero value from crys_hash_error.h on failure. |
| */ |
| |
| CIMPORT_C CRYSError_t CRYS_HASH_Free( |
| CRYS_HASHUserContext_t *ContextID_ptr /*!< [in] Pointer to the HASH context buffer allocated by the user that is used for |
| the HASH machine operation. */ |
| ); |
| |
| |
| /************************************************************************************************/ |
| /*! |
| @brief This function processes a single buffer of data. |
| |
| The function allocates an internal HASH Context, and initializes it with the cryptographic attributes |
| that are needed for the HASH block operation (initialize H's value for the HASH algorithm). |
| Then it processes the data block, calculating the HASH. Finally, it returns the data buffer's message digest. |
| |
| @return CRYS_OK on success. |
| @return A non-zero value from crys_hash_error.h on failure. |
| */ |
| |
| CIMPORT_C CRYSError_t CRYS_HASH ( |
| CRYS_HASH_OperationMode_t OperationMode, /*!< [in] One of the supported HASH modes, as defined in CRYS_HASH_OperationMode_t. */ |
| uint8_t *DataIn_ptr, /*!< [in] Pointer to the input data to be HASHed. |
| The size of the scatter/gather list representing the data buffer is limited |
| to 128 entries, and the size of each entry is limited to 64KB |
| (fragments larger than 64KB are broken into fragments <= 64KB). */ |
| size_t DataSize, /*!< [in] The size of the data to be hashed in bytes. */ |
| CRYS_HASH_Result_t HashResultBuff /*!< [out] Pointer to a word-aligned 64 byte buffer. The actual size of the HASH |
| result depends on CRYS_HASH_OperationMode_t. */ |
| ); |
| |
| |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| /** |
| @} |
| */ |
| #endif |