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 cipher driver header \n 16 * 17 * History: \n 18 * 2023-03-14, Create file. \n 19 */ 20 #ifndef CIPHER_H 21 #define CIPHER_H 22 23 #include <stdint.h> 24 #include <stdbool.h> 25 #include "errcode.h" 26 27 #ifdef __cplusplus 28 #if __cplusplus 29 extern "C" { 30 #endif 31 #endif 32 33 /** 34 * @defgroup security_unified_cipher Cipher 35 * @ingroup drivers_driver_security_unified 36 * @{ 37 */ 38 39 /** 40 * @if Eng 41 * @brief Symmetric encryption channel type 42 * @else 43 * @brief 对称加密通道类型 44 * @endif 45 */ 46 typedef enum { 47 UAPI_DRV_CIPHER_SYMC_TYPE_NORMAL = 0x0, 48 UAPI_DRV_CIPHER_SYMC_TYPE_REG, 49 UAPI_DRV_CIPHER_SYMC_TYPE_MAX, 50 UAPI_DRV_CIPHER_SYMC_TYPE_INVALID = 0xffffffff, 51 } uapi_drv_cipher_symc_type_t; 52 53 /** 54 * @if Eng 55 * @brief Symmetrical encryption algorithm type 56 * @note TDES is not secure, and we advise not to use it. 57 * @else 58 * @brief 对称加密算法类型 59 * @note TDES不安全，不建议使用 60 * @endif 61 */ 62 typedef enum { 63 UAPI_DRV_CIPHER_SYMC_ALG_TDES = 0x0, 64 UAPI_DRV_CIPHER_SYMC_ALG_AES = 0x1, 65 UAPI_DRV_CIPHER_SYMC_ALG_SM4 = 0x2, 66 UAPI_DRV_CIPHER_SYMC_ALG_LEA = 0x3, 67 UAPI_DRV_CIPHER_SYMC_ALG_DMA = 0x4, 68 UAPI_DRV_CIPHER_SYMC_ALG_MAX, 69 UAPI_DRV_CIPHER_SYMC_ALG_INVALID = 0xffffffff, 70 } uapi_drv_cipher_symc_alg_t; 71 72 /** 73 * @if Eng 74 * @brief Symmetric encryption algorithm worke mode 75 * @note ECB is not secure, and we advise not to use it. 76 * @else 77 * @brief 对称加密算法工作模式 78 * @note ECB模式不安全，不建议使用 79 * @endif 80 */ 81 typedef enum { 82 UAPI_DRV_CIPHER_SYMC_WORK_MODE_ECB = 0x0, 83 UAPI_DRV_CIPHER_SYMC_WORK_MODE_CBC, 84 UAPI_DRV_CIPHER_SYMC_WORK_MODE_CTR, 85 UAPI_DRV_CIPHER_SYMC_WORK_MODE_OFB, 86 UAPI_DRV_CIPHER_SYMC_WORK_MODE_CFB, 87 UAPI_DRV_CIPHER_SYMC_WORK_MODE_CCM, 88 UAPI_DRV_CIPHER_SYMC_WORK_MODE_GCM, 89 UAPI_DRV_CIPHER_SYMC_WORK_MODE_CBC_MAC, 90 UAPI_DRV_CIPHER_SYMC_WORK_MODE_CMAC, 91 UAPI_DRV_CIPHER_SYMC_WORK_MODE_MAX, 92 UAPI_DRV_CIPHER_SYMC_WORK_MODE_INVALID = 0xffffffff, 93 } uapi_drv_cipher_symc_work_mode_t; 94 95 /** 96 * @if Eng 97 * @brief Symmetric encryption key length 98 * @else 99 * @brief 对称加密密钥长度 100 * @endif 101 */ 102 typedef enum { 103 UAPI_DRV_CIPHER_SYMC_KEY_64BIT = 0x0, 104 UAPI_DRV_CIPHER_SYMC_KEY_128BIT = 0x1, 105 UAPI_DRV_CIPHER_SYMC_KEY_192BIT = 0x2, 106 UAPI_DRV_CIPHER_SYMC_KEY_256BIT = 0x3, 107 UAPI_DRV_CIPHER_SYMC_KEY_LENGTH_MAX, 108 UAPI_DRV_CIPHER_SYMC_KEY_LENGTH_INVALID = 0xffffffff, 109 } uapi_drv_cipher_symc_key_length_t; 110 111 /** 112 * @if Eng 113 * @brief Symmetric encryption key parity 114 * @else 115 * @brief 对称算法密钥奇偶性 116 * @endif 117 */ 118 typedef enum { 119 UAPI_DRV_CIPHER_SYMC_KEY_EVEN = 0x0, 120 UAPI_DRV_CIPHER_SYMC_KEY_ODD = 0x1, 121 UAPI_DRV_CIPHER_SYMC_KEY_PARITY_MAX, 122 UAPI_DRV_CIPHER_SYMC_KEY_PARITY_INVALID = 0xffffffff, 123 } uapi_drv_cipher_symc_key_parity_t; 124 125 /** 126 * @if Eng 127 * @brief Symmetric encryption key bit width 128 * @else 129 * @brief 对称算法密钥位宽 130 * @endif 131 */ 132 typedef enum { 133 UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_1BIT = 0x0, 134 UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_8BIT = 0x1, 135 UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_64BIT = 0x2, 136 UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_128BIT = 0x3, 137 UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_MAX, 138 UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_INVALID = 0xffffffff, 139 } uapi_drv_cipher_symc_bit_width_t; 140 141 /** 142 * @if Eng 143 * @brief Symmetric encryption iv change flag 144 * @else 145 * @brief 对称算法初始值标志 146 * @endif 147 */ 148 typedef enum { 149 UAPI_DRV_CIPHER_SYMC_IV_DO_NOT_CHANGE = 0, 150 UAPI_DRV_CIPHER_SYMC_IV_CHANGE_ONE_PKG, 151 UAPI_DRV_CIPHER_SYMC_IV_CHANGE_ALL_PKG, 152 /* GCM. */ 153 UAPI_DRV_CIPHER_SYMC_GCM_IV_DO_NOT_CHANGE, 154 UAPI_DRV_CIPHER_SYMC_GCM_IV_CHANGE_START, 155 UAPI_DRV_CIPHER_SYMC_GCM_IV_CHANGE_UPDATE, 156 UAPI_DRV_CIPHER_SYMC_GCM_IV_CHANGE_FINISH, 157 /* CCM. */ 158 UAPI_DRV_CIPHER_SYMC_CCM_IV_DO_NOT_CHANGE, 159 UAPI_DRV_CIPHER_SYMC_CCM_IV_CHANGE_START, 160 UAPI_DRV_CIPHER_SYMC_CCM_IV_CHANGE_UPDATE, 161 UAPI_DRV_CIPHER_SYMC_CCM_IV_CHANGE_FINISH, 162 UAPI_DRV_CIPHER_SYMC_IV_CHANGE_MAX, 163 UAPI_DRV_CIPHER_SYMC_IV_CHANGE_INVALID = 0xffffffff, 164 } uapi_drv_cipher_symc_iv_change_type_t; 165 166 /** 167 * @if Eng 168 * @brief Security attribute selection for the buffer 169 * @else 170 * @brief 缓冲区的安全属性选择 171 * @endif 172 */ 173 typedef enum uapi_drv_cipher_buffer_secure { 174 UAPI_DRV_CIPHER_BUF_NONSECURE, 175 UAPI_DRV_CIPHER_BUF_SECURE, 176 } uapi_drv_cipher_buffer_secure_t; 177 178 /** 179 * @if Eng 180 * @brief Hash algorithm type 181 * @note SHA1 and SHA224 are not secure, and we advise not to use them. 182 * @else 183 * @brief hash算法类型 184 * @note SHA1和SHA224不安全，不建议使用 185 * @endif 186 */ 187 typedef enum uapi_drv_hash_type { 188 UAPI_DRV_CIPHER_HASH_TYPE_SHA1 = 0xf690a0, 189 UAPI_DRV_CIPHER_HASH_TYPE_SHA224 = 0x10690e0, 190 UAPI_DRV_CIPHER_HASH_TYPE_SHA256 = 0x1169100, 191 UAPI_DRV_CIPHER_HASH_TYPE_SHA384 = 0x127a180, 192 UAPI_DRV_CIPHER_HASH_TYPE_SHA512 = 0x137a200, 193 UAPI_DRV_CIPHER_HASH_TYPE_SM3 = 0x2169100, 194 195 UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SHA1 = 0x10f690a0, 196 UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SHA224 = 0x110690e0, 197 UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SHA256 = 0x11169100, 198 UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SHA384 = 0x1127a180, 199 UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SHA512 = 0x1137a200, 200 UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SM3 = 0x12169100, 201 202 UAPI_DRV_CIPHER_HASH_TYPE_INVALID = 0xffffffff, 203 } uapi_drv_cipher_hash_type_t; 204 205 /** 206 * @if Eng 207 * @brief Attribute structure of the buffer 208 * @else 209 * @brief 缓冲区的属性结构体 210 * @endif 211 */ 212 typedef struct uapi_drv_cipher_buf_attr { 213 uint64_t uapi_mem_handle; /*!< @if Eng This parameter is not used. 214 @else 该参数未使用。 @endif */ 215 uint64_t addr_offset; /*!< @if Eng This parameter is not used. 216 @else 该参数未使用。 @endif */ 217 void *kapi_mem_handle; /*!< @if Eng This parameter is not used. 218 @else 该参数未使用。 @endif */ 219 uintptr_t phys_addr; /*!< @if Eng Physical address of the buffer. 220 @else 缓冲区的物理地址。 @endif */ 221 void *virt_addr; /*!< @if Eng Indicates the CPU address of the buffer. 222 @else 缓冲区的cpu地址。 @endif */ 223 uapi_drv_cipher_buffer_secure_t buf_sec; /*!< @if Eng Buffer security attribute. 224 @else 缓冲区安全属性。 @endif */ 225 } uapi_drv_cipher_buf_attr_t; 226 227 /** 228 * @if Eng 229 * @brief Symmetric encryption parameter attribute structure 230 * @else 231 * @brief 对称加密参数属性结构体 232 * @endif 233 */ 234 typedef struct { 235 uapi_drv_cipher_symc_alg_t symc_alg; /*!< @if Eng Symmetric encryption algorithm. 236 @else 对称加密算法。 @endif */ 237 uapi_drv_cipher_symc_work_mode_t work_mode; /*!< @if Eng Symmetric encryption word mode. 238 @else 对称加密算法工作模式。 @endif */ 239 uapi_drv_cipher_symc_type_t symc_type; /*!< @if Eng Symmetric encryption channel type. 240 @else 对称加密通道类型。 @endif */ 241 bool is_long_term; /*!< @if Eng Long or short term channel occupancy flag. 242 @else 长短期通道占用标志。 @endif */ 243 } uapi_drv_cipher_symc_attr_t; 244 245 /** 246 * @if Eng 247 * @brief Parameter structure of CCM and GCM 248 * @else 249 * @brief CCM和GCM工作模式的参数结构体 250 * @endif 251 */ 252 typedef struct { 253 uapi_drv_cipher_buf_attr_t aad_buf; /*!< @if Attribute structure of the buffer. 254 @else 缓冲区的属性结构体。 @endif */ 255 uint32_t aad_len; /*!< @if Addition data length in bytes. 256 @else 附加信息的字节长度。 @endif */ 257 uint32_t data_len; /*!< @if Crypto data length in bytes. 258 @else 加密数据的字节长度。 @endif */ 259 uint32_t tag_len; /*!< @if Tag length in bytes. 260 @else 标签的字节长度。 @endif */ 261 } uapi_drv_cipher_symc_config_aes_ccm_gcm_t; 262 263 #define UAPI_DRV_CIPHER_IV_LEN_IN_BYTES 16 264 265 /** 266 * @if Eng 267 * @brief Parameters of symmetric encryption algorithm 268 * @else 269 * @brief 对称加密算法的参数 270 * @endif 271 */ 272 typedef struct { 273 uapi_drv_cipher_symc_alg_t symc_alg; /*!< @if Eng Symmetric encryption algorithm. 274 @else 对称加密算法。 @endif */ 275 uapi_drv_cipher_symc_work_mode_t work_mode; /*!< @if Eng Symmetric encryption word mode. 276 @else 对称加密算法工作模式。 @endif */ 277 uapi_drv_cipher_symc_key_length_t symc_key_length; /*!< @if Eng Symmetric encryption key length. 278 @else 对称加密密钥长度。 @endif */ 279 uapi_drv_cipher_symc_key_parity_t key_parity; /*!< @if Eng Symmetric encryption key parity. 280 @else 对称算法密钥奇偶性。 @endif */ 281 uapi_drv_cipher_symc_bit_width_t symc_bit_width; /*!< @if Eng Symmetric encryption key bit width. 282 @else 对称算法密钥位宽。 @endif */ 283 uapi_drv_cipher_symc_iv_change_type_t iv_change_flag; /*!< @if Eng Symmetric encryption iv change flag. 284 @else 对称算法密钥位宽。 @endif */ 285 uint8_t iv[UAPI_DRV_CIPHER_IV_LEN_IN_BYTES]; /*!< @if Eng Symmetric encryption iv. 286 @else 对称加密算法初始值。 @endif */ 287 uint32_t iv_length; /*!< @if Eng Symmetric encryption iv length. 288 @else 对称加密算法初始值长度。 @endif */ 289 void *param; /*!< @if Eng Symmetric encryption ccm and gam parameter. 290 @else 对称加密CCM和GCM工作模式的参数。 @endif */ 291 } uapi_drv_cipher_symc_ctrl_t; 292 293 /** 294 * @if Eng 295 * @brief Control parameters of symmetric encryption algorithm 296 * @else 297 * @brief Attribute structure of cbc_mac and cmac 298 * @endif 299 */ 300 typedef struct { 301 bool is_long_term; /*!< @if Eng Long or short term channel occupancy flag. 302 @else 长短期通道占用标志。 @endif */ 303 uapi_drv_cipher_symc_alg_t symc_alg; /*!< @if Eng Symmetric encryption algorithm. 304 @else 对称加密算法。 @endif */ 305 uapi_drv_cipher_symc_work_mode_t work_mode; /*!< @if Eng Symmetric encryption word mode. 306 @else 对称加密算法工作模式。 @endif */ 307 uapi_drv_cipher_symc_key_length_t symc_key_length; /*!< @if Eng Symmetric encryption key length. 308 @else 对称加密密钥长度。 @endif */ 309 uint32_t keyslot_chn; /*!< @if Eng Keyslot channel id. 310 @else Key槽ID。 @endif */ 311 } uapi_drv_cipher_symc_mac_attr_t; 312 313 /** 314 * @if Eng 315 * @brief Hash channel and algorithm parameter structure 316 * @else 317 * @brief hash通道及算法参数结构体 318 * @endif 319 */ 320 typedef struct uapi_drv_hash_attr { 321 uint8_t *key; /*!< @if Eng Pointer to the key used by the HMAC algorithm, 322 This parameter is valid only when the HMAC algorithm 323 is used and is_keyslot is set to false. 324 @else 指向hmac算法使用密钥的指针， 325 当使用hmac算法且is_keyslot为false时该参数生效 @endif */ 326 uint32_t key_len; /*!< @if Eng Key length, in bytes. 327 When the algorithm is HMAC-SHA1, SHA224, SHA256, or SM3, 328 the value cannot exceed 64 bytes. 329 When the algorithm is HMAC-SHA384 or SHA512, the value cannot exceed 128 bytes. 330 @else 密钥长度，单位为字节。当算法为HMAC-SHA1/SHA224/SHA256/SM3时，不超过64字节； 331 当算法为HMAC-SHA384/SHA512时，不超过128字节。 @endif */ 332 uint32_t keyslot_handle; /*!< @if Eng Keyslot channel handle used by the HMAC algorithm. 333 This parameter is valid only when is_keyslot is set to true. 334 @else hmac算法使用的keyslot通道句柄，当is_keyslot为true时该参数生效。 @endif */ 335 uapi_drv_cipher_hash_type_t hash_type; /*!< @if Eng Indicates the hash algorithm type. 336 For details, see @ref uapi_drv_cipher_hash_type_t 337 @else hash算法类型。参考 @ref uapi_drv_cipher_hash_type_t @endif */ 338 bool is_keyslot; /*!< @if Eng Indicates whether the HMAC algorithm uses keyslot. 339 @else 指示hmac算法是否使用keyslot 。 @endif */ 340 bool is_long_term; /*!< @if Eng Indicates whether the created channel is a long-term or short-term channel. 341 A maximum of two long-term channels and eight short-term channels can be created. 342 @else 指示创建的通道为长期通道还是短期通道。最大支持创建2个长期通道和8个短期通道。 @endif */ 343 } uapi_drv_cipher_hash_attr_t; 344 345 #define UAPI_DRV_CIPHER_HASH_RESULT_SIZE_MAX_IN_WORD 16 // for SHA-512 346 #define UAPI_DRV_CIPHER_HASH_BLOCK_SIZE_MAX 128 // for SHA-512 347 348 /** 349 * @if Eng 350 * @brief Structure of the intermediate hash calculation result 351 * @note This structure does not need to be constructed by users. 352 It is obtained by calling the uapi_drv_cipher_hash_get interface and 353 set by calling the uapi_drv_cipher_hash_set interface. 354 * @else 355 * @brief hash计算中间结果结构体 356 * @note 该结构体的内容无需用户构造，通过uapi_drv_cipher_hash_get接口获取，并通过uapi_drv_cipher_hash_set接口设置。 357 * @endif 358 */ 359 typedef struct uapi_drv_cipher_hash_clone_ctx { 360 uint32_t length[2]; /*!< @if Eng Indicates the length of the currently processed data, in bits. 361 @else 保存当前已处理的数据长度，单位是位。 @endif */ 362 uint32_t state[UAPI_DRV_CIPHER_HASH_RESULT_SIZE_MAX_IN_WORD]; /*!< @if Eng Saving calculation intermediate results. 363 @else 保存计算中间结果。 @endif */ 364 uint32_t tail_len; /*!< @if Eng Length of the remaining unaligned tail data since the last calculation. 365 @else 上次计算后剩余未对齐的尾部数据长度。 @endif */ 366 uapi_drv_cipher_hash_type_t hash_type; /*!< @if Eng Algorithm used for hash calculation. 367 @else hash计算使用的算法。 @endif */ 368 uint8_t o_key_pad[UAPI_DRV_CIPHER_HASH_BLOCK_SIZE_MAX]; /*!< @if Eng Save o_key_pad, 369 which is used by the HMAC algorithm. 370 @else 保存o_key_pad，hmac 算法使用。 @endif */ 371 uint8_t i_key_pad[UAPI_DRV_CIPHER_HASH_BLOCK_SIZE_MAX]; /*!< @if Eng Save i_key_pad, 372 which is used by the HMAC algorithm. 373 @else 保存i_key_pad，hmac 算法使用。 @endif */ 374 uint8_t tail[UAPI_DRV_CIPHER_HASH_BLOCK_SIZE_MAX]; /*!< @if Eng Unaligned tail data remaining 375 since last calculation. 376 @else 上次计算后剩余未对齐的尾部数据。 @endif */ 377 } uapi_drv_cipher_hash_clone_ctx_t; 378 379 /** 380 * @if Eng 381 * @brief Parameter structure of PBKDF2 382 * @else 383 * @brief PBKDF2算法的参数结构体 384 * @endif 385 */ 386 typedef struct { 387 uapi_drv_cipher_hash_type_t hash_type; /*!< @if The type of hash algorithm used by PBKDF2. 388 @else PBKDF2使用的hash算法类型。 @endif */ 389 uint8_t *password; /*!< @if Password for PBKDF2. 390 @else PBKDF2的输入口令。 @endif */ 391 uint32_t plen; /*!< @if Password length of PBKDF2. 392 @else PBKDF2的输入口令长度。 @endif */ 393 uint8_t *salt; /*!< @if Salt of PBKDF2. 394 @else PBKDF2的盐值。 @endif */ 395 uint32_t slen; /*!< @if Salt of PBKDF2. 396 @else PBKDF2的盐值长度。 @endif */ 397 uint16_t count; /*!< @if Iterations of PBKDF2. 398 @else PBKDF2的迭代次数。 @endif */ 399 } uapi_drv_cipher_kdf_pbkdf2_param_t; 400 401 /** 402 * @if Eng 403 * @brief Parameter structure of key extract 404 * @else 405 * @brief 密钥提取的参数结构体 406 * @endif 407 */ 408 typedef struct { 409 uapi_drv_cipher_hash_type_t hmac_type; /*!< @if Type of the HMAC algorithm for extracting keys. 410 @else 提取密钥的HMAC算法类型。 @endif */ 411 uint8_t *salt; /*!< @if Extract the salt value of the key. 412 @else 提取密钥的盐值。 @endif */ 413 uint32_t salt_length; /*!< @if Extract the salt length of the key. 414 @else 提取密钥的盐值长度。 @endif */ 415 uint8_t *ikm; /*!< @if Extract the input key material of the key. 416 @else 提取密钥的原始密钥材料。 @endif */ 417 uint32_t ikm_length; /*!< @if Length of the input key material of the extracted key. 418 @else 提取密钥的原始密钥材料长度。 @endif */ 419 } uapi_drv_cipher_hkdf_extract_t; 420 421 /** 422 * @if Eng 423 * @brief Parameter structure of key extend 424 * @else 425 * @brief 密钥拓展的参数结构体 426 * @endif 427 */ 428 typedef struct { 429 uapi_drv_cipher_hash_type_t hmac_type; /*!< @if HMAC algorithm type of the extended key. 430 @else 拓展密钥的HMAC算法类型。 @endif */ 431 uint8_t *prk; /*!< @if Pseudo-random key of the extended key. 432 @else 拓展密钥的伪随机密钥。 @endif */ 433 uint32_t prk_length; /*!< @if Pseudo-random key length of the extended key. 434 @else 拓展密钥的伪随机密钥长度。 @endif */ 435 uint8_t *info; /*!< @if Information about the extended key. 436 @else 拓展密钥的信息。 @endif */ 437 uint32_t info_length; /*!< @if Length of extended key information. 438 @else 拓展密钥的信息长度。 @endif */ 439 } uapi_drv_cipher_hkdf_expand_t; 440 441 /** 442 * @if Eng 443 * @brief Parameter structure of HKDF 444 * @else 445 * @brief HKDF参数结构体 446 * @endif 447 */ 448 typedef struct { 449 uapi_drv_cipher_hash_type_t hmac_type; /*!< @if HMAC algorithm type of the extended key. 450 @else 提起、拓展密钥的HMAC算法类型。 @endif */ 451 uint8_t *salt; /*!< @if Extract the salt value of the key. 452 @else 提取密钥的盐值。 @endif */ 453 uint32_t salt_length; /*!< @if Extract the salt length of the key. 454 @else 提取密钥的盐值长度。 @endif */ 455 uint8_t *ikm; /*!< @if Extract the input key material of the key. 456 @else 提取密钥的原始密钥材料。 @endif */ 457 uint32_t ikm_length; /*!< @if Length of the input key material of the extracted key. 458 @else 提取密钥的原始密钥材料长度。 @endif */ 459 uint8_t *info; /*!< @if Information about the extended key. 460 @else 拓展密钥的信息。 @endif */ 461 uint32_t info_length; /*!< @if Length of extended key information. 462 @else 拓展密钥的信息长度。 @endif */ 463 } uapi_drv_cipher_hkdf_t; 464 465 /** 466 * @if Eng 467 * @brief Symmetric encryption initialization. 468 * @retval ERRCODE_SUCC Success. 469 * @retval Other Failure. For details, see @ref errcode_t 470 * @else 471 * @brief 对称加密初始化。 472 * @retval ERRCODE_SUCC 成功。 473 * @retval Other 失败，参考 @ref errcode_t 。 474 * @endif 475 */ 476 errcode_t uapi_drv_cipher_symc_init(void); 477 478 /** 479 * @if Eng 480 * @brief Symmetric encryption deinitialization. 481 * @retval ERRCODE_SUCC Success. 482 * @retval Other Failure. For details, see @ref errcode_t 483 * @else 484 * @brief 对称加密去初始化。 485 * @retval ERRCODE_SUCC 成功。 486 * @retval Other 失败，参考 @ref errcode_t 。 487 * @endif 488 */ 489 errcode_t uapi_drv_cipher_symc_deinit(void); 490 491 /** 492 * @if Eng 493 * @brief Create a symc channel and set the symc channel parameters. 494 * @param [out] symc_handle Randnum pointer to the created symc channel handle. 495 * @param [in] symc_attr Symc attr pointer to symc channel structure. 496 For details, see @ref uapi_drv_cipher_symc_attr_t 497 * @retval ERRCODE_SUCC Success. 498 * @retval Other Failure. For details, see @ref errcode_t 499 * @else 500 * @brief 创建symc通道，并设置symc通道属性参数。 501 * @param [out] symc_handle symc_handle 指向创建的symc通道句柄的指针。 502 * @param [in] symc_attr 指向symc通道属性结构体的指针，参考 @ref uapi_drv_cipher_symc_attr_t 。 503 * @retval ERRCODE_SUCC 成功。 504 * @retval Other 失败，参考 @ref errcode_t 。 505 * @endif 506 */ 507 errcode_t uapi_drv_cipher_symc_create(uint32_t *symc_handle, const uapi_drv_cipher_symc_attr_t *symc_attr); 508 509 /** 510 * @if Eng 511 * @brief Destroy a symc channel. 512 * @param [in] symc_handle The number of the channel to be destroyed. 513 * @retval ERRCODE_SUCC Success. 514 * @retval Other Failure. For details, see @ref errcode_t 515 * @else 516 * @brief 销毁symc通道。 517 * @param [in] symc_handle 要销毁的通道号。 518 * @retval ERRCODE_SUCC 成功。 519 * @retval Other 失败，参考 @ref errcode_t 。 520 * @endif 521 */ 522 errcode_t uapi_drv_cipher_symc_destroy(uint32_t symc_handle); 523 524 /** 525 * @if Eng 526 * @brief Set algorithm parameters. 527 * @param [in] symc_handle The number of the channel to be set. 528 * @param [in] symc_ctrl Parameters of symmetric encryption algorithm. 529 For details, see @ref uapi_drv_cipher_symc_ctrl_t 530 * @retval ERRCODE_SUCC Success. 531 * @retval Other Failure. For details, see @ref errcode_t 532 * @else 533 * @brief 设置算法参数。 534 * @param [in] symc_handle 要设置的通道号。 535 * @param [in] symc_ctrl 对称加密算法的参数，参考 @ref uapi_drv_cipher_symc_attr_t 。 536 * @retval ERRCODE_SUCC 成功。 537 * @retval Other 失败，参考 @ref errcode_t 。 538 * @endif 539 */ 540 errcode_t uapi_drv_cipher_symc_set_config(uint32_t symc_handle, const uapi_drv_cipher_symc_ctrl_t *symc_ctrl); 541 542 /** 543 * @if Eng 544 * @brief Get algorithm parameters. 545 * @param [in] symc_handle The channel number of the algorithm parameter to be obtained. 546 * @param [in] symc_ctrl Parameters of symmetric encryption algorithm. 547 For details, see @ref uapi_drv_cipher_symc_ctrl_t 548 * @retval ERRCODE_SUCC Success. 549 * @retval Other Failure. For details, see @ref errcode_t 550 * @else 551 * @brief 获取算法参数。 552 * @param [in] symc_handle 要获取算法参数的通道号。 553 * @param [in] symc_ctrl 对称加密算法的参数，参考 @ref uapi_drv_cipher_symc_attr_t 。 554 * @retval ERRCODE_SUCC 成功。 555 * @retval Other 失败，参考 @ref errcode_t 。 556 * @endif 557 */ 558 errcode_t uapi_drv_cipher_symc_get_config(uint32_t symc_handle, const uapi_drv_cipher_symc_ctrl_t *symc_ctrl); 559 560 /** 561 * @if Eng 562 * @brief Attach keyslot handle to the encryption handle. 563 * @param [in] symc_handle Encryption handle. 564 * @param [in] keyslot_handle Keyslot handle. 565 * @retval ERRCODE_SUCC Success. 566 * @retval Other Failure. For details, see @ref errcode_t 567 * @else 568 * @brief 将key的句柄关联到加解密句柄。 569 * @param [in] symc_handle 加解密句柄。 570 * @param [in] keyslot_handle key的句柄。 571 * @retval ERRCODE_SUCC 成功。 572 * @retval Other 失败，参考 @ref errcode_t 。 573 * @endif 574 */ 575 errcode_t uapi_drv_cipher_symc_attach(uint32_t symc_handle, uint32_t keyslot_handle); 576 577 /** 578 * @if Eng 579 * @brief Detach keyslot handle from the encryption handle. 580 * @param [in] symc_handle Encryption handle. 581 * @param [in] keyslot_handle Keyslot handle. 582 * @retval ERRCODE_SUCC Success. 583 * @retval Other Failure. For details, see @ref errcode_t 584 * @else 585 * @brief 将key的句柄和加解密句柄解关联。 586 * @param [in] symc_handle 加解密句柄。 587 * @param [in] keyslot_handle key的句柄。 588 * @retval ERRCODE_SUCC 成功。 589 * @retval Other 失败，参考 @ref errcode_t 。 590 * @endif 591 */ 592 errcode_t uapi_drv_cipher_symc_detach(uint32_t symc_handle, uint32_t keyslot_handle); 593 594 /** 595 * @if Eng 596 * @brief Encrypts data from the source address and sends the encrypted data to the destination address. 597 * @param [in] symc_handle Encryption handle. 598 * @param [in] src_buf Source buffer. 599 * @param [out] dst_buf Destination buffer. 600 * @param [in] length Length of the encrypted data. 601 * @retval ERRCODE_SUCC Success. 602 * @retval Other Failure. For details, see @ref errcode_t 603 * @else 604 * @brief 将源地址数据加密，输出到目的地址。 605 * @param [in] symc_handle 加密句柄。 606 * @param [in] src_buf 源地址。 607 * @param [out] dst_buf 目的地址。 608 * @param [in] length 加密数据长度。 609 * @retval ERRCODE_SUCC 成功。 610 * @retval Other 失败，参考 @ref errcode_t 。 611 * @endif 612 */ 613 errcode_t uapi_drv_cipher_symc_encrypt(uint32_t symc_handle, const uapi_drv_cipher_buf_attr_t *src_buf, 614 const uapi_drv_cipher_buf_attr_t *dst_buf, uint32_t length); 615 616 /** 617 * @if Eng 618 * @brief Decrypts data from the source address and sends the decrypted data to the destination address. 619 * @param [in] symc_handle Encryption handle. 620 * @param [in] src_buf Source buffer. 621 * @param [out] dst_buf Destination buffer. 622 * @param [in] length Length of the encrypted data. 623 * @retval ERRCODE_SUCC Success. 624 * @retval Other Failure. For details, see @ref errcode_t 625 * @else 626 * @brief 将源地址数据解密，输出到目的地址。 627 * @param [in] symc_handle 解密句柄。 628 * @param [in] src_buf 源地址。 629 * @param [out] dst_buf 目的地址。 630 * @param [in] length 解密数据长度。 631 * @retval ERRCODE_SUCC 成功。 632 * @retval Other 失败，参考 @ref errcode_t 。 633 * @endif 634 */ 635 errcode_t uapi_drv_cipher_symc_decrypt(uint32_t symc_handle, const uapi_drv_cipher_buf_attr_t *src_buf, 636 const uapi_drv_cipher_buf_attr_t *dst_buf, uint32_t length); 637 638 /** 639 * @if Eng 640 * @brief Gets the label value in CCM or GCM mode. 641 * @param [in] symc_handle Encryption handle. 642 * @param [out] tag Lable buffer. 643 * @param [in] tag_length Length of the lable buffer. 644 * @retval ERRCODE_SUCC Success. 645 * @retval Other Failure. For details, see @ref errcode_t 646 * @else 647 * @brief 获取CCM或者GCM模式的标签值。 648 * @param [in] symc_handle 加解密句柄。 649 * @param [out] tag 标签值缓冲区。 650 * @param [in] tag_length 标签值缓冲区长度。 651 * @retval ERRCODE_SUCC 成功。 652 * @retval Other 失败，参考 @ref errcode_t 。 653 * @endif 654 */ 655 errcode_t uapi_drv_cipher_symc_get_tag(uint32_t symc_handle, uint8_t *tag, uint32_t tag_length); 656 657 /** 658 * @if Eng 659 * @brief Create a symc channel and set the symc channel and algorithm parameters. 660 * @param [out] symc_handle randnum Pointer to the created symc channel handle. 661 * @param [in] mac_attr symc Pointer to the symc algorithm parameter structure. 662 For details, see @ref uapi_drv_cipher_symc_mac_attr_t 663 * @retval ERRCODE_SUCC Success. 664 * @retval Other Failure. For details, see @ref errcode_t 665 * @else 666 * @brief 创建symc通道，并设置symc通道及算法参数。 667 * @param [out] symc_handle 指向创建的symc通道句柄的指针。 668 * @param [in] mac_attr 指向symc算法参数结构体的指针，参考 @ref uapi_drv_cipher_symc_mac_attr_t 。 669 * @retval ERRCODE_SUCC 成功。 670 * @retval Other 失败，参考 @ref errcode_t 。 671 * @endif 672 */ 673 errcode_t uapi_drv_cipher_mac_start(uint32_t *symc_handle, const uapi_drv_cipher_symc_mac_attr_t *mac_attr); 674 675 /** 676 * @if Eng 677 * @brief MAC calculation. 678 * @param [in] symc_handle The channel handle for calculating the MAC. 679 * @param [in] src_buf Buffer for input data. 680 * @param [in] length Length of the buffer for input data. 681 * @retval ERRCODE_SUCC Success. 682 * @retval Other Failure. For details, see @ref errcode_t 683 * @else 684 * @brief 计算mac值 685 * @param [in] symc_handle 计算mac值的通道句柄。 686 * @param [in] src_buf 输入数据的缓冲区。 687 * @param [in] length 输入数据的缓冲区长度。 688 * @retval ERRCODE_SUCC 成功。 689 * @retval Other 失败，参考 @ref errcode_t 。 690 * @endif 691 */ 692 errcode_t uapi_drv_cipher_mac_update(uint32_t symc_handle, const uapi_drv_cipher_buf_attr_t *src_buf, uint32_t length); 693 694 /** 695 * @if Eng 696 * @brief Get the calculation result and destroy the channel.. 697 * @param [in] symc_handle The channel handle for calculating the MAC. 698 * @param [in] mac Buffer for input data. 699 * @param [in] mac_length Length of the buffer for input data. 700 * @retval ERRCODE_SUCC Success. 701 * @retval Other Failure. For details, see @ref errcode_t 702 * @else 703 * @brief 计算mac值 704 * @param [in] symc_handle 计算mac值的通道句柄。 705 * @param [in] mac 输出结果的缓冲区。 706 * @param [in] mac_length 输出结果的缓冲区长度。 707 * @retval ERRCODE_SUCC 成功。 708 * @retval Other 失败，参考 @ref errcode_t 。 709 * @endif 710 */ 711 errcode_t uapi_drv_cipher_mac_finish(uint32_t symc_handle, uint8_t *mac, uint32_t *mac_length); 712 713 /** 714 * @if Eng 715 * @brief Hash caculation initialization. 716 * @retval ERRCODE_SUCC Success. 717 * @retval Other Failure. For details, see @ref errcode_t 718 * @else 719 * @brief Hash计算初始化。 720 * @retval ERRCODE_SUCC 成功。 721 * @retval Other 失败，参考 @ref errcode_t 。 722 * @endif 723 */ 724 errcode_t uapi_drv_cipher_hash_init(void); 725 726 /** 727 * @if Eng 728 * @brief Hash caculation deinitialization. 729 * @retval ERRCODE_SUCC Success. 730 * @retval Other Failure. For details, see @ref errcode_t 731 * @else 732 * @brief Hash计算去初始化。 733 * @retval ERRCODE_SUCC 成功。 734 * @retval Other 失败，参考 @ref errcode_t 。 735 * @endif 736 */ 737 errcode_t uapi_drv_cipher_hash_deinit(void); 738 739 /** 740 * @if Eng 741 * @brief Create a hash channel and set the hash channel and algorithm parameters. 742 * @param [out] hash_handle randnum Pointer to the created hash channel handle. 743 * @param [in] hash_attr Pointer to the hash algorithm parameter structure. 744 For details, see @ref uapi_drv_cipher_hash_attr_t 745 * @retval ERRCODE_SUCC Success. 746 * @retval Other Failure. For details, see @ref errcode_t 747 * @else 748 * @brief 创建hash通道，并设置hash通道及算法参数。 749 * @param [out] hash_handle 指向创建的hash通道句柄的指针。 750 * @param [in] hash_attr 指向hash算法参数结构体的指针，参考 @ref uapi_drv_cipher_hash_attr_t 。 751 * @retval ERRCODE_SUCC 成功。 752 * @retval Other 失败，参考 @ref errcode_t 。 753 * @endif 754 */ 755 errcode_t uapi_drv_cipher_hash_start(uint32_t *hash_handle, const uapi_drv_cipher_hash_attr_t *hash_attr); 756 757 /** 758 * @if Eng 759 * @brief Hash calculation 760 * @note A hash handle must have been created before this API is called. 761 If the uapi_drv_cipher_hash_finish API has been called to obtain the digest information, 762 the calculation cannot be performed again. When calculating the abstract of a piece of data, 763 you can invoke this interface at a time. 764 You can also split data into multiple parts and invoke this interface for multiple times. 765 The results obtained by the two methods are the same. 766 * @param [in] hash_handle Handle of the created hash channel. 767 * @param [in] src_buf Source buffer properties, including buffer address and buffer security type. 768 For details, see @ref uapi_drv_cipher_buf_attr_t 769 * @param [in] len Buffer Size. 770 * @retval ERRCODE_SUCC Success. 771 * @retval Other Failure. For details, see @ref errcode_t 772 * @else 773 * @brief hash计算 774 * @note 调用该接口前必须已经创建了hash句柄，如已经调用了uapi_drv_cipher_hash_finish接口获取摘要信息，则不能再次进行该计算。 775 计算一段数据的摘要时，可以单次调用该接口；也可以将数据拆成多段，多次调用该接口。两种方式得到的结果相同。 776 * @param [in] hash_handle 已创建的hash通道句柄。 777 * @param [in] src_buf 源缓冲区属性，包括缓冲区地址与缓冲区安全类型。参考 @ref uapi_drv_cipher_buf_attr_t 。 778 * @param [in] len 缓冲区大小。 779 * @retval ERRCODE_SUCC 成功。 780 * @retval Other 失败，参考 @ref errcode_t 。 781 * @endif 782 */ 783 errcode_t uapi_drv_cipher_hash_update(uint32_t hash_handle, const uapi_drv_cipher_buf_attr_t *src_buf, 784 const uint32_t len); 785 786 /** 787 * @if Eng 788 * @brief Hash calculation obtains digest information and destroys the hash handle when the calculation is successful. 789 * @note The hash handle must have been created. 790 * @param [in] hash_handle Handle of the created hash channel. 791 * @param [out] out Pointer to the buffer address for storing the summary information. 792 * @param [inout] out_len Pointer to the size of the buffer for storing the summary information. 793 The input is the buffer length, and the output is the actual digest length. 794 * @retval ERRCODE_SUCC Success. 795 * @retval Other Failure. For details, see @ref errcode_t 796 * @else 797 * @brief HASH计算获取摘要信息，并在计算成功的时候销毁hash句柄。 798 * @note 必须已经创建了hash句柄。 799 * @param [in] hash_handle 已创建的hash通道句柄 800 * @param [out] out 存储摘要信息的缓冲区地址指针。 801 * @param [inout] out_len 存储摘要信息的缓冲区大小指针。输入为缓冲区长度，输出为实际摘要长度。 802 * @retval ERRCODE_SUCC 成功。 803 * @retval Other 失败，参考 @ref errcode_t 。 804 * @endif 805 */ 806 errcode_t uapi_drv_cipher_hash_finish(uint32_t hash_handle, uint8_t *out, uint32_t *out_len); 807 808 /** 809 * @if Eng 810 * @brief Obtains the intermediate result of hash calculation. 811 * @note The hash handle must have been created. 812 * @param [in] hash_handle Handle of the created hash channel. 813 * @param [out] hash_clone_ctx Pointer to the intermediate result structure of hash calculation. 814 For details, see @ref uapi_drv_cipher_hash_clone_ctx_t 815 * @retval ERRCODE_SUCC Success. 816 * @retval Other Failure. For details, see @ref errcode_t 817 * @else 818 * @brief 获取HASH计算中间结果。 819 * @note 必须已经创建了hash句柄。 820 * @param [in] hash_handle 已创建的hash通道句柄。 821 * @param [out] hash_clone_ctx 指向Hash计算中间结果结构体的指针。参考 @ref uapi_drv_cipher_hash_clone_ctx_t 。 822 * @retval ERRCODE_SUCC 成功。 823 * @retval Other 失败，参考 @ref errcode_t 。 824 * @endif 825 */ 826 errcode_t uapi_drv_cipher_hash_get(uint32_t hash_handle, uapi_drv_cipher_hash_clone_ctx_t *hash_clone_ctx); 827 828 /** 829 * @if Eng 830 * @brief Sets the intermediate result of hash calculation. 831 * @note The hash handle must have been created. 832 * @param [in] hash_handle Handle of the created hash channel. 833 * @param [in] hash_clone_ctx Pointer to the intermediate result structure of hash calculation. 834 For details, see @ref uapi_drv_cipher_hash_clone_ctx_t 835 * @retval ERRCODE_SUCC Success. 836 * @retval Other Failure. For details, see @ref errcode_t 837 * @else 838 * @brief 设置HASH计算中间结果。 839 * @note 必须已经创建了hash句柄。 840 * @param [in] hash_handle 已创建的hash通道句柄。 841 * @param [in] hash_clone_ctx 指向Hash计算中间结果结构体的指针。参考 @ref uapi_drv_cipher_hash_clone_ctx_t 。 842 * @retval ERRCODE_SUCC 成功。 843 * @retval Other 失败，参考 @ref errcode_t 。 844 * @endif 845 */ 846 errcode_t uapi_drv_cipher_hash_set(uint32_t hash_handle, const uapi_drv_cipher_hash_clone_ctx_t *hash_clone_ctx); 847 848 /** 849 * @if Eng 850 * @brief Destroying a hash channel. 851 * @note This interface destroys only the hash channel and does not start calculation or obtain digest results. 852 * @param [in] hash_handle Handle of the created hash channel. 853 * @retval ERRCODE_SUCC Success. 854 * @retval Other Failure. For details, see @ref errcode_t 855 * @else 856 * @brief 销毁hash通道。 857 * @note 该接口只销毁hash通道，不启动计算和获取摘要结果。 858 * @param [in] hash_handle 已创建的hash通道句柄。 859 * @retval ERRCODE_SUCC 成功。 860 * @retval Other 失败，参考 @ref errcode_t 。 861 * @endif 862 */ 863 errcode_t uapi_drv_cipher_hash_destroy(uint32_t hash_handle); 864 865 /** 866 * @if Eng 867 * @brief Use the PBKDF2 algorithm to derive keys. 868 * @param [in] param Parameter structure of PBKDF2. 869 * @param [in] out Output key buffer. 870 * @param [in] out_len Length of the output key buffer. 871 * @retval ERRCODE_SUCC Success. 872 * @retval Other Failure. For details, see @ref errcode_t 873 * @else 874 * @brief PBKDF2算法派生秘钥。 875 * @param [in] param PBKDF2算法的参数结构体。 876 * @param [in] out 输出秘钥缓冲区。 877 * @param [in] out_len 输出秘钥缓冲区长度。 878 * @retval ERRCODE_SUCC 成功。 879 * @retval Other 失败，参考 @ref errcode_t 。 880 * @endif 881 */ 882 errcode_t uapi_drv_cipher_pbkdf2(const uapi_drv_cipher_kdf_pbkdf2_param_t *param, uint8_t *out, const uint32_t out_len); 883 884 /** 885 * @if Eng 886 * @brief Extracting the key. 887 * @param [in] extract_param Key extraction parameter structure. 888 * @param [in] prk Pseudo-random key with extended key. 889 * @param [in] prk_length Extended pseudo-random key length. 890 * @retval ERRCODE_SUCC Success. 891 * @retval Other Failure. For details, see @ref errcode_t 892 * @else 893 * @brief 提取密钥。 894 * @param [in] extract_param 密钥提取的参数结构体。 895 * @param [out] prk 拓展密钥的伪随机密钥。 896 * @param [out] prk_length 拓展密钥的伪随机密钥长度。 897 * @retval ERRCODE_SUCC 成功。 898 * @retval Other 失败，参考 @ref errcode_t 。 899 * @endif 900 */ 901 errcode_t uapi_drv_cipher_hkdf_extract(uapi_drv_cipher_hkdf_extract_t *extract_param, 902 uint8_t *prk, uint32_t *prk_length); 903 904 /** 905 * @if Eng 906 * @brief Extended Key. 907 * @param [in] expand_param Key extension parameter structure. 908 * @param [in] okm Output key material. 909 * @param [in] okm_length Length of the output key material. 910 * @retval ERRCODE_SUCC Success. 911 * @retval Other Failure. For details, see @ref errcode_t 912 * @else 913 * @brief 拓展密钥。 914 * @param [in] expand_param 密钥拓展的参数结构体。 915 * @param [out] okm 输出密钥材料。 916 * @param [out] okm_length 输出密钥材料长度。 917 * @retval ERRCODE_SUCC 成功。 918 * @retval Other 失败，参考 @ref errcode_t 。 919 * @endif 920 */ 921 errcode_t uapi_drv_cipher_hkdf_expand(const uapi_drv_cipher_hkdf_expand_t *expand_param, 922 uint8_t *okm, uint32_t okm_length); 923 924 /** 925 * @if Eng 926 * @brief HKDF, including key extraction and key extension. 927 * @param [in] hkdf_param HKDF parameter structure. 928 * @param [in] okm Output key material. 929 * @param [in] okm_length Length of the output key material. 930 * @retval ERRCODE_SUCC Success. 931 * @retval Other Failure. For details, see @ref errcode_t 932 * @else 933 * @brief HKDF，包括提取密钥和拓展密钥两步。 934 * @param [in] hkdf_param HKDF的参数结构体。 935 * @param [out] okm 输出密钥材料。 936 * @param [out] okm_length 输出密钥材料长度。 937 * @retval ERRCODE_SUCC 成功。 938 * @retval Other 失败，参考 @ref errcode_t 。 939 * @endif 940 */ 941 errcode_t uapi_drv_cipher_hkdf(uapi_drv_cipher_hkdf_t *hkdf_param, uint8_t *okm, uint32_t okm_length); 942 943 /** 944 * @} 945 */ 946 947 #ifdef __cplusplus 948 #if __cplusplus 949 } 950 #endif 951 #endif 952 953 #endif 954