Mistake on this page?
Report an issue in GitHub or email us
crys_hash.h
Go to the documentation of this file.
1 /**************************************************************************************
2 * Copyright (c) 2016-2017, ARM Limited or its affiliates. All rights reserved *
3 * *
4 * This file and the related binary are licensed under the following license: *
5 * *
6 * ARM Object Code and Header Files License, v1.0 Redistribution. *
7 * *
8 * Redistribution and use of object code, header files, and documentation, without *
9 * modification, are permitted provided that the following conditions are met: *
10 * *
11 * 1) Redistributions must reproduce the above copyright notice and the *
12 * following disclaimer in the documentation and/or other materials *
13 * provided with the distribution. *
14 * *
15 * 2) Unless to the extent explicitly permitted by law, no reverse *
16 * engineering, decompilation, or disassembly of is permitted. *
17 * *
18 * 3) Redistribution and use is permitted solely for the purpose of *
19 * developing or executing applications that are targeted for use *
20 * on an ARM-based product. *
21 * *
22 * DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND *
23 * CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT *
24 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, *
25 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE *
26 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, *
27 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED *
28 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR *
29 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF *
30 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING *
31 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS *
32 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. *
33 **************************************************************************************/
34 
35 
36 /*!
37 @file
38 @brief This file contains all of the enums and definitions
39 that are used for the CRYS HASH APIs, as well as the APIs themselves.
40 @defgroup crys_hash CryptoCell HASH APIs
41 @{
42 @ingroup cryptocell_api
43 
44 
45 This product supports the following HASH algorithms (or modes, according to product):
46 <ul><li> CRYS_HASH_MD5 (producing 16 byte output).</li>
47 <li> CRYS_HASH_SHA1 (producing 20 byte output).</li>
48 <li> CRYS_HASH_SHA224 (producing 28 byte output).</li>
49 <li> CRYS_HASH_SHA256 (producing 32 byte output).</li>
50 <li> CRYS_HASH_SHA384 (producing 48 byte output).</li>
51 <li> CRYS_HASH_SHA512 (producing 64 byte output).</li></ul>
52 
53 HASH calculation can be performed in either of the following two modes of operation:
54 <ul><li> Integrated operation - Processes all data in a single function call. This flow is applicable when all data is available prior to the
55  cryptographic operation.</li>
56 <li> Block operation - Processes a subset of the data buffers, and is called multiple times in a sequence. This flow is applicable when the
57  next data buffer becomes available only during/after processing of the current data buffer.</li></ul>
58 
59 The following is a typical HASH Block operation flow:
60 <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
61  HASH operation.</li>
62 <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
63  as required.</li>
64 <li> ::CRYS_HASH_Finish - this function ends the HASH operation. It returns the digest result and clears the context.</li></ol>
65 */
66 
67 #ifndef CRYS_HASH_H
68 #define CRYS_HASH_H
69 
70 
71 #include "ssi_pal_types.h"
72 #include "crys_error.h"
73 #include "crys_hash_defs.h"
74 
75 
76 #ifdef __cplusplus
77 extern "C"
78 {
79 #endif
80 
81 
82 /************************ Defines ******************************/
83 /* The hash result in words
84 #define CRYS_HASH_RESULT_SIZE_IN_WORDS 5*/
85 /*! The maximal hash result is 512 bits for SHA512. */
86 #define CRYS_HASH_RESULT_SIZE_IN_WORDS 16
87 
88 /*! MD5 digest result size in bytes. */
89 #define CRYS_HASH_MD5_DIGEST_SIZE_IN_BYTES 16
90 
91 /*! MD5 digest result size in words. */
92 #define CRYS_HASH_MD5_DIGEST_SIZE_IN_WORDS 4
93 
94 /*! SHA-1 digest result size in bytes. */
95 #define CRYS_HASH_SHA1_DIGEST_SIZE_IN_BYTES 20
96 
97 /*! SHA-1 digest result size in words. */
98 #define CRYS_HASH_SHA1_DIGEST_SIZE_IN_WORDS 5
99 
100 /*! SHA-256 digest result size in words. */
101 #define CRYS_HASH_SHA224_DIGEST_SIZE_IN_WORDS 7
102 
103 /*! SHA-256 digest result size in words. */
104 #define CRYS_HASH_SHA256_DIGEST_SIZE_IN_WORDS 8
105 
106 /*! SHA-384 digest result size in words. */
107 #define CRYS_HASH_SHA384_DIGEST_SIZE_IN_WORDS 12
108 
109 /*! SHA-512 digest result size in words. */
110 #define CRYS_HASH_SHA512_DIGEST_SIZE_IN_WORDS 16
111 
112 /*! SHA-256 digest result size in bytes */
113 #define CRYS_HASH_SHA224_DIGEST_SIZE_IN_BYTES 28
114 
115 /*! SHA-256 digest result size in bytes */
116 #define CRYS_HASH_SHA256_DIGEST_SIZE_IN_BYTES 32
117 
118 /*! SHA-384 digest result size in bytes */
119 #define CRYS_HASH_SHA384_DIGEST_SIZE_IN_BYTES 48
120 
121 /*! SHA-512 digest result size in bytes */
122 #define CRYS_HASH_SHA512_DIGEST_SIZE_IN_BYTES 64
123 
124 /*! SHA1 hash block size in words */
125 #define CRYS_HASH_BLOCK_SIZE_IN_WORDS 16
126 
127 /*! SHA1 hash block size in bytes */
128 #define CRYS_HASH_BLOCK_SIZE_IN_BYTES 64
129 
130 /*! SHA2 hash block size in words */
131 #define CRYS_HASH_SHA512_BLOCK_SIZE_IN_WORDS 32
132 
133 /*! SHA2 hash block size in bytes */
134 #define CRYS_HASH_SHA512_BLOCK_SIZE_IN_BYTES 128
135 
136 /*! Maximal data size for update operation. */
137 #define CRYS_HASH_UPDATE_DATA_MAX_SIZE_IN_BYTES (1 << 29)
138 
139 
140 /************************ Enums ********************************/
141 
142 /*!
143 HASH operation mode
144 */
145 typedef enum {
146  CRYS_HASH_SHA1_mode = 0, /*!< SHA1. */
147  CRYS_HASH_SHA224_mode = 1, /*!< SHA224. */
148  CRYS_HASH_SHA256_mode = 2, /*!< SHA256. */
149  CRYS_HASH_SHA384_mode = 3, /*!< SHA384. */
150  CRYS_HASH_SHA512_mode = 4, /*!< SHA512. */
151  CRYS_HASH_MD5_mode = 5, /*!< MD5. */
152  /*! Number of hash modes. */
154  /*! Reserved. */
156 
158 
159 /************************ Typedefs *****************************/
160 
161 /*! HASH result buffer. */
163 
164 /************************ Structs ******************************/
165 /*! The user's context prototype - the argument type that is passed by the user
166  to the HASH APIs. The context saves the state of the operation and must be saved by the user
167  till the end of the APIs flow. */
168 typedef struct CRYS_HASHUserContext_t {
169  /*! Internal buffer */
172 
173 /************************ Public Variables **********************/
174 
175 /************************ Public Functions **********************/
176 
177 
178 /************************************************************************************************/
179 /*!
180 @brief This function initializes the HASH machine and the HASH Context.
181 
182 It receives as input a pointer to store the context handle to the HASH Context,
183 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).
184 
185 @return CRYS_OK on success.
186 @return A non-zero value from crys_hash_error.h on failure.
187 */
188 CIMPORT_C CRYSError_t CRYS_HASH_Init(
189  CRYS_HASHUserContext_t *ContextID_ptr, /*!< [in] Pointer to the HASH context buffer allocated by the user that is used
190  for the HASH machine operation. */
191  CRYS_HASH_OperationMode_t OperationMode /*!< [in] One of the supported HASH modes, as defined in CRYS_HASH_OperationMode_t. */
192 );
193 
194 /************************************************************************************************/
195 /*!
196 @brief This function processes a block of data to be HASHed.
197 
198 It updates a HASH Context that was previously initialized by CRYS_HASH_Init or updated by a previous call to CRYS_HASH_Update.
199 
200 @return CRYS_OK on success.
201 @return A non-zero value from crys_hash_error.h on failure.
202 */
203 
204 CIMPORT_C CRYSError_t CRYS_HASH_Update(
205  CRYS_HASHUserContext_t *ContextID_ptr, /*!< [in] Pointer to the HASH context buffer allocated by the user, which is used for the
206  HASH machine operation. */
207  uint8_t *DataIn_ptr, /*!< [in] Pointer to the input data to be HASHed.
208  it is a one contiguous memory block. */
209  size_t DataInSize /*!< [in] Byte size of the input data. Must be > 0.
210  If not a multiple of the HASH block size (64 for MD5, SHA-1 and SHA-224/256,
211  128 for SHA-384/512), no further calls
212  to CRYS_HASH_Update are allowed in this context, and only CRYS_HASH_Finish
213  can be called to complete the computation. */
214 );
215 
216 /************************************************************************************************/
217 /*!
218 @brief This function finalizes the hashing process of data block.
219 
220 It receives a handle to the HASH Context, which was previously initialized by CRYS_HASH_Init or by CRYS_HASH_Update.
221 It "adds" a header to the data block according to the relevant HASH standard, and computes the final message digest.
222 
223 @return CRYS_OK on success.
224 @return A non-zero value from crys_hash_error.h on failure.
225 */
226 
227 CIMPORT_C CRYSError_t CRYS_HASH_Finish(
228  CRYS_HASHUserContext_t *ContextID_ptr, /*!< [in] Pointer to the HASH context buffer allocated by the user that is used for
229  the HASH machine operation. */
230  CRYS_HASH_Result_t HashResultBuff /*!< [in] Pointer to the word-aligned 64 byte buffer. The actual size of the HASH
231  result depends on CRYS_HASH_OperationMode_t. */
232 );
233 
234 
235 /************************************************************************************************/
236 /*!
237 @brief This function is a utility function that frees the context if the operation has failed.
238 
239 The function executes the following major steps:
240 <ol><li> Checks the validity of all of the inputs of the function. </li>
241 <li> Clears the user's context.</li>
242 <li> Exits the handler with the OK code.</li></ol>
243 
244 @return CRYS_OK on success.
245 @return A non-zero value from crys_hash_error.h on failure.
246 */
247 
248 CIMPORT_C CRYSError_t CRYS_HASH_Free(
249  CRYS_HASHUserContext_t *ContextID_ptr /*!< [in] Pointer to the HASH context buffer allocated by the user that is used for
250  the HASH machine operation. */
251 );
252 
253 
254 /************************************************************************************************/
255 /*!
256 @brief This function processes a single buffer of data.
257 
258 The function allocates an internal HASH Context, and initializes it with the cryptographic attributes
259 that are needed for the HASH block operation (initialize H's value for the HASH algorithm).
260 Then it processes the data block, calculating the HASH. Finally, it returns the data buffer's message digest.
261 
262 @return CRYS_OK on success.
263 @return A non-zero value from crys_hash_error.h on failure.
264  */
265 
266 CIMPORT_C CRYSError_t CRYS_HASH (
267  CRYS_HASH_OperationMode_t OperationMode, /*!< [in] One of the supported HASH modes, as defined in CRYS_HASH_OperationMode_t. */
268  uint8_t *DataIn_ptr, /*!< [in] Pointer to the input data to be HASHed.
269  The size of the scatter/gather list representing the data buffer is limited
270  to 128 entries, and the size of each entry is limited to 64KB
271  (fragments larger than 64KB are broken into fragments <= 64KB). */
272  size_t DataSize, /*!< [in] The size of the data to be hashed in bytes. */
273  CRYS_HASH_Result_t HashResultBuff /*!< [out] Pointer to a word-aligned 64 byte buffer. The actual size of the HASH
274  result depends on CRYS_HASH_OperationMode_t. */
275 );
276 
277 
278 
279 #ifdef __cplusplus
280 }
281 #endif
282 /**
283 @}
284  */
285 #endif
#define CRYS_HASH_USER_CTX_SIZE_IN_WORDS
CRYSError_t CRYS_HASH_Free(CRYS_HASHUserContext_t *ContextID_ptr)
This function is a utility function that frees the context if the operation has failed.
CRYS_HASH_OperationMode_t
Definition: crys_hash.h:145
CRYSError_t CRYS_HASH_Update(CRYS_HASHUserContext_t *ContextID_ptr, uint8_t *DataIn_ptr, size_t DataInSize)
This function processes a block of data to be HASHed.
struct CRYS_HASHUserContext_t CRYS_HASHUserContext_t
CRYSError_t CRYS_HASH_Init(CRYS_HASHUserContext_t *ContextID_ptr, CRYS_HASH_OperationMode_t OperationMode)
This function initializes the HASH machine and the HASH Context.
uint32_t CRYS_HASH_Result_t[16]
Definition: crys_hash.h:162
uint32_t buff[60]
Definition: crys_hash.h:170
This file contains HASH definitions.
uint32_t CRYSError_t
Definition: crys_error.h:253
#define CRYS_HASH_RESULT_SIZE_IN_WORDS
Definition: crys_hash.h:86
This file contains the platform dependent definitions and types.
CRYSError_t CRYS_HASH_Finish(CRYS_HASHUserContext_t *ContextID_ptr, CRYS_HASH_Result_t HashResultBuff)
This function finalizes the hashing process of data block.
CRYSError_t CRYS_HASH(CRYS_HASH_OperationMode_t OperationMode, uint8_t *DataIn_ptr, size_t DataSize, CRYS_HASH_Result_t HashResultBuff)
This function processes a single buffer of data.
This module defines the error return code types and the numbering spaces of the error codes for each ...
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.