mirror of https://github.com/ARMmbed/mbed-os.git
286 lines
13 KiB
C
286 lines
13 KiB
C
/**************************************************************************************
|
|
* 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
|