1 /* 2 * This file is part of the openHiTLS project. 3 * 4 * openHiTLS is licensed under the Mulan PSL v2. 5 * You can use this software according to the terms and conditions of the Mulan PSL v2. 6 * You may obtain a copy of Mulan PSL v2 at: 7 * 8 * http://license.coscl.org.cn/MulanPSL2 9 * 10 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, 11 * EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, 12 * MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. 13 * See the Mulan PSL v2 for more details. 14 */ 15 16 /** 17 * @defgroup crypt_eal_mac 18 * @ingroup crypt 19 * @brief mac of crypto module 20 */ 21 22 #ifndef CRYPT_EAL_MAC_H 23 #define CRYPT_EAL_MAC_H 24 25 #include <stdbool.h> 26 #include <stdint.h> 27 #include "crypt_algid.h" 28 #include "crypt_types.h" 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 typedef struct EAL_MacCtx CRYPT_EAL_MacCtx; 35 36 /** 37 * @ingroup crypt_eal_mac 38 * @brief Check whether the id is Valid MAC algorithm ID. 39 * 40 * @param id [IN] MAC algorithm ID 41 * 42 * @retval true, if valid. 43 * false, if invalid. 44 */ 45 bool CRYPT_EAL_MacIsValidAlgId(CRYPT_MAC_AlgId id); 46 47 /** 48 * @ingroup crypt_eal_mac 49 * @brief Apply for a MAC context. 50 * 51 * @param id [IN] MAC algorithm ID 52 * 53 * @retval CRYPT_EAL_MacCtx Pointer. 54 * NULL, if the operation fails. 55 */ 56 CRYPT_EAL_MacCtx *CRYPT_EAL_MacNewCtx(CRYPT_MAC_AlgId id); 57 58 /** 59 * @ingroup crypt_eal_mac 60 * @brief Create an MAC context in the providers. 61 * 62 * @param libCtx [IN] Library context 63 * @param algId [IN] mac algorithm ID. 64 * @param attrName [IN] Specify expected attribute values 65 * 66 * @retval CRYPT_EAL_MacCtx pointer. 67 * NULL, if the operation fails. 68 */ 69 CRYPT_EAL_MacCtx *CRYPT_EAL_ProviderMacNewCtx(CRYPT_EAL_LibCtx *libCtx, int32_t algId, const char *attrName); 70 71 /** 72 * @ingroup crypt_eal_mac 73 * @brief Release the MAC context memory. 74 * 75 * @param ctx [IN] MAC context, ctx set NULL by caller. 76 */ 77 void CRYPT_EAL_MacFreeCtx(CRYPT_EAL_MacCtx *ctx); 78 79 /** 80 * @ingroup crypt_eal_mac 81 * 82 * MAC algorithm initialize the context, which is used after the CRYPT_EAL_MacNewCtx interface is called. 83 * The initialization interface can be used at any time during the calculation, note that the last calculation data 84 * is cleared after the initialization interface is called. 85 * 86 * @param ctx [IN] MAC context 87 * @param key [IN] Key, The length specifications are as follows: 88 * HMAC:Any integer greater than or equal to 0 89 * The length of HMAC-SHA1, HMAC-SHA224, and HMAC-SHA256 must be less than 2^64 bits, 90 * the length of HMAC-SHA384 and HMAC-SHA512 must be less than 2^128 bits. 91 * HMAC-SHA3 series has no limit on length 92 * CMAC: The length of CMAC-AES128 must be 128 bits, and the length of CMAC-AES192 must be 192 bits. 93 * The length of CMAC-AES256 must be 256 bits. 94 * @param len [IN] Key length 95 * 96 * @retval #CRYPT_SUCCESS, initialization succeeded. 97 * @retval #CRYPT_NULL_INPUT, pointer ctx parameter or key parameter is NULL. 98 * @retval #CRYPT_AES_ERR_KEYLEN, the key length of the AES & CMAC algorithm is incorrect. 99 * Other error codes see the crypt_errno.h. 100 */ 101 int32_t CRYPT_EAL_MacInit(CRYPT_EAL_MacCtx *ctx, const uint8_t *key, uint32_t len); 102 103 /** 104 * @ingroup crypt_eal_mac 105 * @brief Continuously input the MAC data. 106 * 107 * This command is used only after the CRYPT_EAL_MacInit interface is successfully called. 108 * 109 * @param ctx [IN] MAC context 110 * @param in [IN] Input data, when the variable is null, the len parameter must be 0. 111 * Otherwise, an error is reported. 112 * @param len [IN] Input data length, the value can be 0. 113 * 114 * @retval #CRYPT_SUCCESS, succeeded in updating the internal status of the digest. 115 * @retval #CRYPT_NULL_INPUT, the input parameter is NULL. 116 * @retval #CRYPT_EAL_ERR_STATE, status error. 117 * @retval #CRYPT_SHA1_INPUT_OVERFLOW, the length of the HMAC-SHA1 input data exceeds the maximum value. 118 * @retval #CRYPT_SHA2_INPUT_OVERFLOW, the length of the HMAC-SHA224, HMAC-SHA256, HMAC-SHA384, or HMAC-SHA512 119 * input data exceeds the maximum value, Other error codes see the crypt_errno.h. 120 */ 121 int32_t CRYPT_EAL_MacUpdate(CRYPT_EAL_MacCtx *ctx, const uint8_t *in, uint32_t len); 122 123 /** 124 * @ingroup crypt_eal_mac 125 * @brief Output the MAC result. 126 * 127 * This API must be used after the CRYPT_EAL_MacInit API is successfully executed, during the process, you 128 * do not need to call the CRYPT_EAL_MacUpdate API. 129 * MAC output length. HMAC-SHA1 corresponds to 20 bytes, HMAC-SHA224 corresponds to 28 bytes, and HMAC-SHA256 130 * corresponds to 32 bytes. HMAC-SHA384 corresponds to 48 bytes, HMAC-SHA512 corresponds to 64 bytes, and CMAC-AES 131 * corresponds to 16 bytes. HMAC-SHA3-224 corresponds to 28 bytes, HMAC-SHA3-256 corresponds to 32 bytes, 132 * HMAC-SHA3-384 corresponds to 48 bytes, and HMAC-SHA3-512 corresponds to 64 bytes. 133 * 134 * @param ctx [IN] MAC context 135 * @param out [OUT] Output data. Sufficient memory must be allocated to store MAC results and cannot be null. 136 * @param len [IN/OUT] Output data length. The input parameter must specify the out length, 137 * which must be greater than or equal to the length generated by the MAC. 138 * The output parameter is the output length of the MAC. 139 * 140 * @retval #CRYPT_SUCCESS, calculation succeeded. 141 * @retval #CRYPT_NULL_INPUT, the input parameter is NULL. 142 * @retval #CRYPT_EAL_ERR_STATE, status incorrect. 143 * @retval #CRYPT_HMAC_OUT_BUFF_LEN_NOT_ENOUGH, the length of the output buffer in the HMAC algorithm is insufficient. 144 * @retval #CRYPT_CMAC_OUT_BUFF_LEN_NOT_ENOUGH, the length of the output buffer in the CMAC algorithm is insufficient. 145 * @retval #CRYPT_SHA1_INPUT_OVERFLOW, the length of the HMAC-SHA1 input data exceeds the maximum. 146 * @retval #CRYPT_SHA2_INPUT_OVERFLOW, the length of the input data in HMAC-SHA224, HMAC-SHA256, HMAC-SHA384, or 147 * HMAC-SHA512 exceeds the maximum value. 148 * Other error codes see the crypt_errno.h 149 */ 150 int32_t CRYPT_EAL_MacFinal(CRYPT_EAL_MacCtx *ctx, uint8_t *out, uint32_t *len); 151 152 /** 153 * @ingroup crypt_eal_mac 154 * @brief Deinitialization function. 155 * 156 * If calculation is required after this function is called, it needs to be initialized again. 157 * 158 * @param ctx [IN] MAC context 159 */ 160 void CRYPT_EAL_MacDeinit(CRYPT_EAL_MacCtx *ctx); 161 162 /** 163 * @ingroup crypt_eal_mac 164 * @brief Re-initialize with the information retained in ctx. 165 * 166 * @attention Doesn't need call the init interface again for initialization, it is equivalent to the combination 167 * of the deinit and init interfaces. 168 * @param ctx [IN] MAC context 169 * @retval #CRYPT_SUCCESS, reinit succeeded. 170 * @retval #CRYPT_NULL_INPUT, the input parameter is NULL. 171 */ 172 int32_t CRYPT_EAL_MacReinit(CRYPT_EAL_MacCtx *ctx); 173 174 /** 175 * @ingroup crypt_eal_mac 176 * @brief Through the context, obtain the output MAC length of the corresponding algorithm. 177 * 178 * @param ctx [IN] MAC context 179 * @retval The MAC length corresponding to the context. 180 */ 181 uint32_t CRYPT_EAL_GetMacLen(const CRYPT_EAL_MacCtx *ctx); 182 183 /** 184 * @ingroup crypt_eal_mac 185 * @brief Set algorithm parameters. This API must be called after the CRYPT_EAL_MacInit API is called. 186 * This API supports only the GMAC algorithm. 187 * 188 * Parameter Data Type len stands for length, and in represents the number of bytes 189 * CRYPT_CTRL_SET_IV uint8_t array Length of IV 190 * CRYPT_CTRL_SET_TAGLEN uint32_t 4 bytes, sizeof(uint32_t) 191 * CRYPT_CTRL_GET_MACLEN 192 * 193 * @param ctx [IN] MAC context 194 * @param type [IN] Set parameter type. 195 * @param in [IN] Input data 196 * @param len [IN] Input data length 197 * @retval #CRYPT_SUCCESS, parameters are set successfully. 198 * @retval #CRYPT_EAL_ERR_STATE, status incorrect. 199 * @retval #CRYPT_EAL_MAC_CTRL_TYPE_ERROR, the parameter type is set incorrect. 200 * @retval #CRYPT_EAL_ERR_ALGID, algorithm ID exclude GMAC. 201 * Other error codes see crypt_errno.h 202 */ 203 int32_t CRYPT_EAL_MacCtrl(CRYPT_EAL_MacCtx *ctx, int32_t type, void *in, uint32_t len); 204 205 #ifdef __cplusplus 206 } // end extern "C" 207 #endif 208 209 #endif // CRYPT_EAL_MAC_H 210