Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
crys_hmac.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 HMAC APIs, as well as the APIs themselves.
40 @defgroup crys_hmac CryptoCell HMAC APIs
41 @{
42 @ingroup cryptocell_api
43 
44 
45 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,
46 to generate a unique authentication code over the input data.
47 HMAC calculation can be performed in either of the following two modes of operation:
48 <ul><li> Integrated operation - Processes all data in a single function call. This flow is applicable when all data is available prior to
49 the cryptographic operation.</li>
50 <li> Block operation - Processes a subset of the data buffers, and is called multiple times in a sequence. This flow is applicable when
51 the next data buffer becomes available only during/after processing of the current data buffer.</li></ul>
52 
53 The following is a typical HMAC Block operation flow:
54 <ol><li> ::CRYS_HMAC_Init: This function initializes the HMAC machine on the CRYS level by setting the context pointer that is
55  used on the entire HMAC operation.</li>
56 <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
57  many times as required.</li>
58 <li> ::CRYS_HMAC_Finish: This function ends the HMAC operation. It returns the digest result and clears the context.</li></ol>
59 */
60 
61 #ifndef CRYS_HMAC_H
62 #define CRYS_HMAC_H
63 
64 
65 #include "ssi_pal_types.h"
66 #include "crys_error.h"
67 
68 #include "crys_hash.h"
69 #include "crys_hmac_defs.h"
70 
71 #ifdef __cplusplus
72 extern "C"
73 {
74 #endif
75 
76 
77 /************************ Defines ******************************/
78 
79 /*! HMAC key size after padding for MD5, SHA1, SHA256. */
80 #define CRYS_HMAC_KEY_SIZE_IN_BYTES 64
81 
82 /*! HMAC key size after padding for SHA384, SHA512 */
83 #define CRYS_HMAC_SHA2_1024BIT_KEY_SIZE_IN_BYTES 128
84 
85 /************************ Enums ********************************/
86 
87 /************************ Typedefs ****************************/
88 
89 /*********************** Structures ****************************/
90 
91 
92 /*! User's context prototype - the argument type that is passed by the user
93  to the HMAC APIs. The context saves the state of the operation and must be saved by the user
94  till the end of the APIs flow */
95 typedef struct CRYS_HMACUserContext_t {
96  /*! Context buffer for internal use */
97  uint32_t buff[CRYS_HMAC_USER_CTX_SIZE_IN_WORDS];
98 
99 }CRYS_HMACUserContext_t;
100 
101 /************************ Structs ******************************/
102 
103 
104 /************************ Public Variables **********************/
105 
106 
107 /************************ Public Functions **********************/
108 
109 /*!
110 @brief This function initializes the HMAC machine.
111 
112 It allocates and initializes the HMAC Context. It initiates a HASH session and processes a HASH update on the Key XOR ipad,
113 then stores it in the context
114 
115 @return CRYS_OK on success.
116 @return A non-zero value from crys_hmac_error.h or crys_hash_error.h on failure.
117 */
118 CIMPORT_C CRYSError_t CRYS_HMAC_Init(
119  CRYS_HMACUserContext_t *ContextID_ptr, /*!< [in] Pointer to the HMAC context buffer allocated by the user, which is used
120  for the HMAC machine operation. */
121  CRYS_HASH_OperationMode_t OperationMode, /*!< [in] One of the supported HASH modes, as defined in CRYS_HASH_OperationMode_t. */
122  uint8_t *key_ptr, /*!< [in] The pointer to the user's key buffer. */
123  uint16_t keySize /*!< [in] The key size in bytes. If the key size is bigger than the HASH block, the key will be hashed.
124  The limitations on the key size are the same as the limitations on MAX hash size. */
125 );
126 
127 
128 /*!
129 @brief This function processes a block of data to be HASHed.
130 
131 It receives a handle to the HMAC Context, and updates the HASH value with the new data.
132 
133 @return CRYS_OK on success.
134 @return A non-zero value from crys_hmac_error.h or crys_hash_error.h on failure.
135 */
136 
137 CIMPORT_C CRYSError_t CRYS_HMAC_Update(
138  CRYS_HMACUserContext_t *ContextID_ptr, /*!< [in] Pointer to the HMAC context buffer allocated by the user
139  that is used for the HMAC machine operation. */
140  uint8_t *DataIn_ptr, /*!< [in] Pointer to the input data to be HASHed.
141  The size of the scatter/gather list representing the data buffer is limited to
142  128 entries, and the size of each entry is limited to 64KB
143  (fragments larger than 64KB are broken into fragments <= 64KB). */
144  size_t DataInSize /*!< [in] Byte size of the input data. Must be > 0.
145  If not a multiple of the HASH block size (64 for SHA-1 and SHA-224/256,
146  128 for SHA-384/512), no further calls to ::CRYS_HMAC_Update are allowed in
147  this context, and only ::CRYS_HMAC_Finish can be called to complete the
148  computation. */
149 );
150 
151 
152 /*!
153 @brief This function finalizes the HMAC processing of a data block.
154 
155 It receives a handle to the HMAC context that was previously initialized by ::CRYS_HMAC_Init, or by ::CRYS_HMAC_Update.
156 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
157 HASH operation result.
158 
159 @return CRYS_OK on success.
160 @return A non-zero value from crys_hmac_error.h or crys_hash_error.h on failure.
161 */
162 
163 CIMPORT_C CRYSError_t CRYS_HMAC_Finish(
164  CRYS_HMACUserContext_t *ContextID_ptr, /*!< [in] Pointer to the HMAC context buffer allocated by the user, which is used
165  for the HMAC machine operation. */
166  CRYS_HASH_Result_t HmacResultBuff /*!< [out] Pointer to the word-aligned 64 byte buffer. The actual size of the
167  HASH result depends on CRYS_HASH_OperationMode_t. */
168 );
169 
170 
171 /*!
172 @brief This function is a service function that frees the context if the operation has failed.
173 
174 The function executes the following major steps:
175 <ol><li> Checks the validity of all of the inputs of the function. </li>
176 <li> Clears the user's context.</li>
177 <li> Exits the handler with the OK code.</li></ol>
178 
179 @return CRYS_OK on success.
180 @return a non-zero value from crys_hmac_error.h on failure.
181 */
182 
183 CIMPORT_C CRYSError_t CRYS_HMAC_Free(
184  CRYS_HMACUserContext_t *ContextID_ptr /*!< [in] Pointer to the HMAC context buffer allocated by the user, which is used for
185  the HMAC machine operation. */
186 );
187 
188 
189 /*!
190 @brief This function processes a single buffer of data, and returns the data buffer's message digest.
191 
192 @return CRYS_OK on success.
193 @return A non-zero value from crys_hmac_error.h or crys_hash_error.h on failure.
194 */
195 CIMPORT_C CRYSError_t CRYS_HMAC (
196  CRYS_HASH_OperationMode_t OperationMode, /*!< [in] One of the supported HASH modes, as defined in CRYS_HASH_OperationMode_t. */
197  uint8_t *key_ptr, /*!< [in] The pointer to the user's key buffer. */
198  uint16_t keySize, /*!< [in] The key size in bytes. If the key size is bigger than the HASH block, the key will be hashed.
199  The limitations on the key size are the same as the limitations on MAX hash size.*/
200  uint8_t *DataIn_ptr, /*!< [in] Pointer to the input data to be HASHed.
201  The size of the scatter/gather list representing the data buffer is limited to 128
202  entries, and the size of each entry is limited to 64KB (fragments larger than
203  64KB are broken into fragments <= 64KB). */
204  size_t DataSize, /*!< [in] The size of the data to be hashed (in bytes). */
205  CRYS_HASH_Result_t HmacResultBuff /*!< [out] Pointer to the word-aligned 64 byte buffer. The actual size of the
206  HMAC result depends on CRYS_HASH_OperationMode_t. */
207 );
208 #ifdef __cplusplus
209 }
210 #endif
211 /**
212 @}
213  */
214 #endif
CRYS_HMAC_Free
CRYSError_t CRYS_HMAC_Free(CRYS_HMACUserContext_t *ContextID_ptr)
This function is a service function that frees the context if the operation has failed.
CRYS_HMACUserContext_t
Definition: crys_hmac.h:95
CRYS_HMAC_USER_CTX_SIZE_IN_WORDS
#define CRYS_HMAC_USER_CTX_SIZE_IN_WORDS
Definition: crys_hmac_defs.h:55
CRYS_HMACUserContext_t::buff
uint32_t buff[94]
Definition: crys_hmac.h:97
CRYS_HASH_OperationMode_t
CRYS_HASH_OperationMode_t
Definition: crys_hash.h:145
CRYS_HMACUserContext_t
struct CRYS_HMACUserContext_t CRYS_HMACUserContext_t
CRYS_HMAC_Init
CRYSError_t CRYS_HMAC_Init(CRYS_HMACUserContext_t *ContextID_ptr, CRYS_HASH_OperationMode_t OperationMode, uint8_t *key_ptr, uint16_t keySize)
This function initializes the HMAC machine.
CRYS_HMAC_Finish
CRYSError_t CRYS_HMAC_Finish(CRYS_HMACUserContext_t *ContextID_ptr, CRYS_HASH_Result_t HmacResultBuff)
This function finalizes the HMAC processing of a data block.
CRYS_HASH_Result_t
uint32_t CRYS_HASH_Result_t[16]
Definition: crys_hash.h:162
crys_hash.h
This file contains all of the enums and definitions that are used for the CRYS HASH APIs...
crys_hmac_defs.h
This file contains HMAC definitions.
CRYS_HMAC
CRYSError_t CRYS_HMAC(CRYS_HASH_OperationMode_t OperationMode, uint8_t *key_ptr, uint16_t keySize, uint8_t *DataIn_ptr, size_t DataSize, CRYS_HASH_Result_t HmacResultBuff)
This function processes a single buffer of data, and returns the data buffer&#39;s message digest...
CRYSError_t
uint32_t CRYSError_t
Definition: crys_error.h:253
ssi_pal_types.h
This file contains the platform dependent definitions and types.
CRYS_HMAC_Update
CRYSError_t CRYS_HMAC_Update(CRYS_HMACUserContext_t *ContextID_ptr, uint8_t *DataIn_ptr, size_t DataInSize)
This function processes a block of data to be HASHed.
crys_error.h
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.