1 /** 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 * 15 * Description: Provides hash driver header file\n 16 * 17 * History: \n 18 * 2022-08-09, Create file. \n 19 */ 20 #ifndef HASH_H 21 #define HASH_H 22 23 #include <stdint.h> 24 #include "errcode.h" 25 26 #ifdef __cplusplus 27 #if __cplusplus 28 extern "C" { 29 #endif 30 #endif 31 32 /** 33 * @defgroup drivers_driver_hash Hash 34 * @ingroup drivers_driver 35 * @{ 36 */ 37 38 #define SHA256_HASH_SIZE 32 39 #if SHA512_SUPPORT == YES 40 #define SHA512_HASH_SIZE 64 41 #endif 42 43 /** 44 * @if Eng 45 * @brief Hash algorithm type 46 * @note SHA1 is not secure, and we advise not to use it. 47 * @else 48 * @brief hash算法类型 49 * @note SHA1不安全，不建议使用 50 * @endif 51 */ 52 typedef enum { 53 DRV_CIPHER_HASH_TYPE_SHA1 = 0x00, 54 DRV_CIPHER_HASH_TYPE_SHA224, 55 DRV_CIPHER_HASH_TYPE_SHA256, 56 DRV_CIPHER_HASH_TYPE_SHA384, 57 DRV_CIPHER_HASH_TYPE_SHA512, 58 DRV_CIPHER_HASH_TYPE_SM3 = 0x10, 59 DRV_CIPHER_HASH_TYPE_HMAC_SHA1 = 0x20, 60 DRV_CIPHER_HASH_TYPE_HMAC_SHA224, 61 DRV_CIPHER_HASH_TYPE_HMAC_SHA256, 62 DRV_CIPHER_HASH_TYPE_HMAC_SHA384, 63 DRV_CIPHER_HASH_TYPE_HMAC_SHA512, 64 DRV_CIPHER_HASH_TYPE_HMAC_SM3 = 0x30, 65 DRV_CIPHER_HASH_TYPE_MAX, 66 DRV_CIPHER_HASH_TYPE_INVALID = 0xffffffff, 67 } drv_cipher_hash_type_t; 68 69 /** 70 * @if Eng 71 * @brief Defines the security type of the buffer. 72 * @else 73 * @brief 定义缓冲区的安全类型 74 * @endif 75 */ 76 typedef enum { 77 DRV_CIPHER_BUF_NONSECURE = 0x00, 78 DRV_CIPHER_BUF_SECURE, 79 DRV_CIPHER_BUF_UNDEFINED, 80 DRV_CIPHER_BUF_INVALID = 0xffffffff, 81 } drv_cipher_buffer_secure_t; 82 83 /** 84 * @if Eng 85 * @brief Attributes of the buffer that stores encrypted and decrypted data. 86 * @else 87 * @brief 存储加解密数据的缓冲区属性 88 * @endif 89 */ 90 typedef struct { 91 uint8_t *address; /*!< @if Eng Buffer address, which should be 4-byte aligned 92 @else 缓冲区地址，应该4字节对齐 @endif */ 93 drv_cipher_buffer_secure_t buf_sec; /*!< @if Eng Buffer security attribute. 94 @else 缓冲区安全属性。 @endif */ 95 } drv_cipher_buf_attr_t; 96 97 /** 98 * @if Eng 99 * @brief Definition of hash handle attribute 100 * @else 101 * @brief hash 句柄属性 102 * @endif 103 */ 104 typedef struct { 105 drv_cipher_hash_type_t hash_type; /*!< @if Eng Hash algorithm type 106 @else hash 算法类型 @endif */ 107 uint32_t keyslot; /*!< @if Eng This attribute is verified during the keylot handle 108 HMAC calculation. 109 @else keyslot句柄,hmac计算时会验证该属性 @endif */ 110 } drv_cipher_hash_attr_t; 111 112 /** 113 * @if Eng 114 * @brief Creates a hash handle and binds the keyslot channel. 115 * @param [out] hhash Handle for operating the hash algorithm. 116 * @param [in] hash_attr Configures the basic attributes of the hash handle, including the hash type and the 117 bound keylot channel. 118 * @param [in] check_word The XOR result of the preceding parameter. 119 * @retval ERRCODE_SUCC Success. 120 * @retval Other Failure. For details, see @ref errcode_t 121 * @else 122 * @brief 创建hash句柄，并绑定keyslot通道 123 * @param [out] hhash hash操作句柄 124 * @param [in] hash_attr 配置hash句柄基本属性，包括hash类型和绑定的keyslot通道. 125 * @param [in] check_word 前面参数的异或结果. 126 * @retval ERRCODE_SUCC 成功 127 * @retval Other 失败，参考 @ref errcode_t 128 * @endif 129 */ 130 errcode_t uapi_drv_cipher_hash_init(uintptr_t *hhash, const drv_cipher_hash_attr_t *hash_attr, 131 const uintptr_t check_word); 132 133 /** 134 * @if Eng 135 * @brief Hash calculation. 136 * @note The hash handle must have been created before this interface is invoked. If the uapi_drv_cipher_hash_final 137 interface has been invoked to obtain the digest information, the calculation cannot be performed again. 138 This interface supports retry. That is, if a process calculation fails, this interface can be invoked to 139 recalculate the process until the calculation succeeds without restarting the calculation process. 140 * @param [out] hhash Handle for operating the hash algorithm. 141 * @param [in] src_buf Source buffer attributes, including the buffer address and buffer security type. 142 * @param [in] len Buffer size. 143 * @param [in] timeout_ms Timeout in milliseconds. 144 * @param [in] check_word The XOR result of the preceding parameter. 145 * @retval ERRCODE_SUCC Success. 146 * @retval Other Failure. For details, see @ref errcode_t 147 * @else 148 * @brief HASH计算 149 * @note 调用该接口前必须已经创建了hash句柄,如已经调用了uapi_drv_cipher_hash_final接口获取摘要信息，则不能再次进行该计算 150 该接口支持重试，即若某次过程计算失败，仍可调用该接口重新计算直至成功，而不需要重新开始计算流程 151 * @param [out] hhash hash操作句柄 152 * @param [in] src_buf 源缓冲区属性，包括缓冲区地址与缓冲区安全类型. 153 * @param [in] len 缓冲区大小。 154 * @param [in] timeout_ms 毫秒记时的超时时间。 155 * @param [in] check_word 前面参数的异或结果。 156 * @retval ERRCODE_SUCC 成功 157 * @retval Other 失败，参考 @ref errcode_t 158 * @endif 159 */ 160 errcode_t uapi_drv_cipher_hash_update(uintptr_t hhash, const drv_cipher_buf_attr_t *src_buf, const uint32_t len, 161 const uint32_t timeout_ms, const uintptr_t check_word); 162 163 /** 164 * @if Eng 165 * @brief The hash calculation obtains the digest information and destroys the hash handle when the calculation 166 succeeds. 167 * @note The hash handle must have been created. 168 This interface supports retry. That is, if a process calculation fails, this interface can be invoked to 169 recalculate, the process until the calculation succeeds without restarting the calculation process. 170 * @param [out] hhash Handle for operating the hash algorithm. 171 * @param [out] out Pointer to the address of the buffer for storing summary information. 172 * @param [out] out_len Pointer to the size of the buffer for storing summary information. 173 * @param [in] check_word The XOR result of the preceding parameter. 174 * @retval ERRCODE_SUCC Success. 175 * @retval Other Failure. For details, see @ref errcode_t 176 * @else 177 * @brief HASH计算获取摘要信息，并在计算成功的时候销毁hash句柄。 178 * @note 必须已经创建了hash句柄。该接口支持重试，即若某次过程计算失败，仍可调用该接口重新计算直至成功，而不需要重新开始计算流程 179 * @param [out] hhash hash句柄. 180 * @param [out] out 存储摘要信息的缓冲区地址指针。 181 * @param [out] out_len 存储摘要信息的缓冲区大小指针。 182 * @param [in] check_word 前面参数的异或结果。 183 * @retval ERRCODE_SUCC 成功 184 * @retval Other 失败，参考 @ref errcode_t 185 * @endif 186 */ 187 errcode_t uapi_drv_cipher_hash_final(uintptr_t hhash, uint8_t *out, uint32_t *out_len, const uintptr_t check_word); 188 189 /** 190 * @} 191 */ 192 193 #ifdef __cplusplus 194 #if __cplusplus 195 } 196 #endif 197 #endif 198 199 #endif 200