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_md 18 * @ingroup crypt 19 * @brief md algorithms of crypto module 20 */ 21 22 #ifndef CRYPT_EAL_MD_H 23 #define CRYPT_EAL_MD_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 // __cplusplus 33 34 typedef struct EAL_MdCtx CRYPT_EAL_MdCTX; 35 36 /** 37 * @ingroup crypt_eal_md 38 * @brief Create the MD context. 39 * 40 * After the calculation is complete, call the CRYPT_EAL_MdFreeCtx interface to release the memory. 41 * 42 * @param id [IN] Algorithm ID 43 * @retval CRYPT_EAL_MdCTX, MD context pointer. 44 * NULL, if the operation fails. 45 */ 46 CRYPT_EAL_MdCTX *CRYPT_EAL_MdNewCtx(CRYPT_MD_AlgId id); 47 48 /** 49 * @ingroup crypt_eal_md 50 * @brief Create a md context in the providers. 51 * 52 * @param libCtx [IN] Library context, if NULL, use the default provider 53 * @param algId [IN] md algorithm ID. 54 * @param attrName [IN] Specify expected attribute values 55 * 56 * @retval CRYPT_EAL_PkeyCtx pointer. 57 * NULL, if the operation fails. 58 */ 59 CRYPT_EAL_MdCTX *CRYPT_EAL_ProviderMdNewCtx(CRYPT_EAL_LibCtx *libCtx, int32_t algId, const char *attrName); 60 61 /** 62 * @ingroup crypt_eal_md 63 * @brief Check whether the id is valid MD algorithm ID. Not supported in provider 64 * 65 * @param id [IN] MD algorithm ID. 66 * @retval true, If the value is valid. 67 * false, If the value is invalid. 68 */ 69 bool CRYPT_EAL_MdIsValidAlgId(CRYPT_MD_AlgId id); 70 71 /** 72 * @ingroup crypt_eal_md 73 * @brief Return the MD algorithm ID. 74 * 75 * @param pkey [IN] MD context 76 * @retval ID, MD algorithm ID. 77 * CRYPT_MD_MAX, which indicates invalid ID or the input parameter is null. 78 */ 79 int32_t CRYPT_EAL_MdGetId(CRYPT_EAL_MdCTX *ctx); 80 81 /** 82 * @ingroup crypt_eal_md 83 * @brief Copy the MD context. 84 * 85 * @param to [IN/OUT] Target MD context 86 * @param from [IN] Source MD context 87 * @retval #CRYPT_SUCCESS. 88 * For other error codes, see crypt_errno.h. 89 */ 90 int32_t CRYPT_EAL_MdCopyCtx(CRYPT_EAL_MdCTX *to, const CRYPT_EAL_MdCTX *from); 91 92 /** 93 * @ingroup crypt_eal_md 94 * @brief Copy the MD context. 95 * 96 * Note that need to call the CRYPT_EAL_MdFreeCtx interface to release the memory after the duplication is complete. 97 * 98 * @param ctx [IN] Source MD context 99 * @retval CRYPT_EAL_MdCTX, MD context pointer. 100 * NULL, if the operation fails. 101 */ 102 CRYPT_EAL_MdCTX *CRYPT_EAL_MdDupCtx(const CRYPT_EAL_MdCTX *ctx); 103 104 /** 105 * @ingroup crypt_eal_md 106 * @brief Release the MD context. 107 * 108 * @param ctx [IN] MD context. which is created by using the CRYPT_EAL_MdNewCtx interface and need to be set 109 * NULL by caller. 110 * @retval Void, no return value. 111 */ 112 void CRYPT_EAL_MdFreeCtx(CRYPT_EAL_MdCTX *ctx); 113 114 /** 115 * @ingroup crypt_eal_md 116 * @brief Initialize the MD context. 117 * 118 * @param ctx [IN/OUT] MD context, which is created by using the CRYPT_EAL_MdNewCtx interface. 119 * @retval #CRYPT_SUCCESS. 120 * For other error codes, see crypt_errno.h. 121 */ 122 int32_t CRYPT_EAL_MdInit(CRYPT_EAL_MdCTX *ctx); 123 124 /** 125 * @ingroup crypt_eal_md 126 * @brief Continuously input the data to be digested. 127 * 128 * @param ctx [IN/OUT] MD context, which is created by using the CRYPT_EAL_MdNewCtx interface. 129 * @param data [IN] Data to be digested. 130 * @param len [IN] Data length. 131 * The maximum length of sha384 and sha512 is [0, 2^128 bits). 132 * The maximum total length of sha1, sha224, sha256, sm3, and md5 is [0, 2^64 bits). 133 * The maximum length at a time is [0, 0xffffffff]. 134 * @retval #CRYPT_SUCCESS. 135 * For other error codes, see crypt_errno.h. 136 */ 137 int32_t CRYPT_EAL_MdUpdate(CRYPT_EAL_MdCTX *ctx, const uint8_t *data, uint32_t len); 138 139 /** 140 * @ingroup crypt_eal_md 141 * @brief Generate output from the sponge construction's squeezing phase. 142 * 143 * This interface implements the squeeze capability of sponge-based hash functions (e.g. SHAKE). 144 * Can be called multiple times to generate additional output. Must be called after finalization. 145 * 146 * @param ctx [IN/OUT] MD context (must be in squeezed state) 147 * @param out [OUT] Buffer to store squeezed output 148 * @param len [IN] Input: requested output length (must be <= buffer size) 149 * @retval #CRYPT_SUCCESS 150 * #CRYPT_E_SHORT_BUFFER if output buffer is too small 151 * For other error codes, see crypt_errno.h 152 */ 153 int32_t CRYPT_EAL_MdSqueeze(CRYPT_EAL_MdCTX *ctx, uint8_t *out, uint32_t len); 154 155 /** 156 * @ingroup crypt_eal_md 157 * @brief Complete the digest and output the final digest result. 158 * 159 * @param ctx [IN/OUT] MD context, which is created by using the CRYPT_EAL_MdNewCtx interface. 160 * @param out [OUT] Digest result cache, which needs to be created and managed by users. 161 * @param len [IN/OUT] The input parameter indicates the length of the buffer marked as "out", and the output 162 * parameter indicates the valid length of the obtained "out". The length must be greater than or equal to 163 * the hash length of the corresponding algorithm, the hash length can be obtained through the 164 * CRYPT_EAL_MdGetDigestSize interface. 165 * Requires user creation management. 166 * @retval #CRYPT_SUCCESS. 167 * For other error codes, see crypt_errno.h. 168 */ 169 int32_t CRYPT_EAL_MdFinal(CRYPT_EAL_MdCTX *ctx, uint8_t *out, uint32_t *len); 170 171 /** 172 * @ingroup crypt_eal_md 173 * @brief Obtain the digest length of the algorithm output. Not supported in provider 174 * 175 * @param id [IN] Algorithm ID 176 * @retval Digest length, if successful. 177 * 0, if failed(in this case, the ID is invalid). 178 */ 179 uint32_t CRYPT_EAL_MdGetDigestSize(CRYPT_MD_AlgId id); 180 181 /** 182 * @ingroup crypt_eal_md 183 * @brief Calculate the data digest. Not supported in provider 184 * 185 * @param id [IN] Algorithm ID 186 * @param in [IN] Data to be digested 187 * @param len [IN] Data length 188 * @param out [OUT] Digest result 189 * @param len [IN/OUT] The input parameter indicates the length of the buffer marked as "out", and the output 190 * parameter indicates the valid length of the obtained "out". 191 * @retval #CRYPT_SUCCESS. 192 * For other error codes, see crypt_errno.h. 193 */ 194 int32_t CRYPT_EAL_Md(CRYPT_MD_AlgId id, const uint8_t *in, uint32_t inLen, uint8_t *out, uint32_t *outLen); 195 196 /** 197 * @ingroup crypt_eal_md 198 * @brief Deinitialize the function. 199 * 200 * If need to be calculated after the CRYPT_EAL_MdDeinit is called, it needs to be initialized again. 201 * 202 * @param ctx [IN] Md Context 203 */ 204 int32_t CRYPT_EAL_MdDeinit(CRYPT_EAL_MdCTX *ctx); 205 206 #ifdef __cplusplus 207 } 208 #endif // __cplusplus 209 210 #endif // CRYPT_EAL_MD_H 211