1 /** 2 * @file hks_client.h 3 * 4 * Copyright (c) 2020 Huawei Device Co., Ltd. 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 /** 19 * Description: Contains key generation, signature verify, 20 * encryption and decryption, key derivation, key agreement, etc. \n 21 * Author: Huawei \n 22 * Create: 2019-06-19 23 */ 24 /** 25 * @defgroup iot_hks 26 * @ingroup hks 27 */ 28 29 #ifndef HKS_CLIENT_H 30 #define HKS_CLIENT_H 31 32 #include "hks_types.h" 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /** 39 * @ingroup iot_hks 40 * @brief Hks get sdk version.CNcomment:获取HKS sdk版本号。CNend 41 * 42 * @par 描述: 43 * Hks get sdk version.CNcomment:获取HKS sdk版本号。CNend 44 * 45 * @attention None 46 * @param sdk_version [OUT] type #struct hks_blob *，get sdk version.CNcomment:HKS sdk版本号。CNend 47 * 48 * @retval None 49 * @par 依赖: 50 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 51 * @see hks_get_sdk_version 52 */ 53 HKS_DLL_API_PUBLIC void hks_get_sdk_version(struct hks_blob *sdk_version); 54 55 /** 56 * @ingroup iot_hks 57 * @brief Hks init.CNcomment:hks 初始化。CNend 58 * 59 * @par 描述: 60 * Hks init.CNcomment:hks 初始化。CNend 61 * 62 * @attention None 63 * @param None 64 * 65 * @retval #0 Success. 66 * @retval #Other Failure. 67 * @par 依赖: 68 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 69 * @see hks_init 70 */ 71 HKS_DLL_API_PUBLIC int32_t hks_init(void); 72 73 /** 74 * @ingroup iot_hks 75 * @brief Hks destroy.CNcomment:销毁 hks。CNend 76 * 77 * @par 描述: 78 * Hks destroy.CNcomment:销毁 hks。CNend 79 * 80 * @attention None 81 * @param None 82 * 83 * @retval None 84 * @par 依赖: 85 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 86 * @see hks_destroy 87 */ 88 HKS_DLL_API_PUBLIC void hks_destroy(void); 89 90 /** 91 * @ingroup iot_hks 92 * @brief Refresh key info and root key info.CNcomment:刷新密钥信息和根密钥信息。CNend 93 * 94 * @par 描述: 95 * Refresh key info and root key info.CNcomment:刷新密钥信息和根密钥信息。CNend 96 * 97 * @attention None 98 * @param None 99 * 100 * @retval #0 Success. 101 * @retval #Other Failure. 102 * @par 依赖: 103 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 104 * @see hks_refresh_key_info 105 */ 106 HKS_DLL_API_PUBLIC int32_t hks_refresh_key_info(void); 107 108 /** 109 * @ingroup iot_hks 110 * @brief Generate key Only ED25519 algorithm key pair generation is supported The number of local storage keys. 111 CNcomment:生成密钥仅支持ED25519算法密钥对生成本地存储密钥。CNend 112 * 113 * @par 描述: 114 * Generate key Only ED25519 algorithm key pair generation is supported The number of local storage keys 115 (including generated ED25519 public-private key pairs imported ED25519 public keys) is limited to 16. 116 CNcomment:生成密钥仅支持ED25519算法密钥对生成本地存储密钥 117 （包括导入的ED25519公共密钥和私有ED25519生成的ED25519公共密钥对）的数量限制为16个。CNend 118 * 119 * @attention None 120 * @param key_alias [IN] type #const struct hks_blob *，key alias, constraint condition:key_alias->size <= 64. 121 CNcomment:密钥别名，约束条件：key_alias-> size <= 64。CNend 122 * @param key_param [IN] type #const struct hks_key_param *，The parameter of the key which need to generate 123 constraint condition: key_param cannot be NULL & key_param->key_type must be HKS_KEY_TYPE_EDDSA_KEYPAIR_ED25519. 124 CNcomment:需要生成的密钥参数 约束条件： 125 key_param不能为NULL ＆ key_param-> key_type必须为HKS_KEY_TYPE_EDDSA_KEYPAIR_ED25519。CNend 126 * @retval #0 Success. 127 * @retval #Other Failure. 128 * @par 依赖: 129 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 130 * @see hks_generate_key 131 */ 132 HKS_DLL_API_PUBLIC int32_t hks_generate_key(const struct hks_blob *key_alias, 133 const struct hks_key_param *key_param); 134 135 /** 136 * @ingroup iot_hks 137 * @brief Generate the X25519 algorithm key pair and return it to the caller. The generated key pair is not saved in HKS. 138 CNcomment:生成X25519算法秘钥对并返回给调用者，生成的秘钥对不在hks保存。CNend 139 * 140 * @par 描述: 141 * Generate the X25519 algorithm key pair and return it to the caller. 142 The generated key pair is not saved in HKS. 143 CNcomment:生成X25519算法秘钥对并返回给调用者，生成的秘钥对不在hks保存。CNend 144 * 145 * @attention None 146 * @param key_param [IN] type #const struct hks_key_param *，Used to specify related parameters that affect 147 key generation, constraint condition: key_param.key_type must be HKS_KEY_TYPE_ECC_KEYPAIR_CURVE25519 148 key_param.usage must be hks_alg_ecdh(HKS_ALG_SELECT_RAW). 149 CNcomment:用于指定影响秘钥生成的相关参数, 约束条件：key_param.key_type必须为HKS_KEY_TYPE_ECC_KEYPAIR_CURVE25519 150 key_param.usage必须为hks_alg_ecdh（HKS_ALG_SELECT_RAW）。CNend 151 * @param pri_key [OUT] type #struct hks_blob *，Used to save the generated private key 152 CNcomment:用于保存生成的私钥。CNend 153 * @param pub_key [OUT] type #struct hks_blob *，Used to save the generated public key. 154 CNcomment:用于保存生成的公钥。CNend 155 * @param 156 * @retval #0 Success. 157 * @retval #Other Failure. 158 * @par 依赖: 159 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 160 * @see hks_generate_asymmetric_key 161 */ 162 HKS_DLL_API_PUBLIC int32_t hks_generate_asymmetric_key( 163 const struct hks_key_param *key_param, struct hks_blob *pri_key, 164 struct hks_blob *pub_key); 165 166 /** 167 * @ingroup iot_hks 168 * @brief Associate the ED25519 algorithm public key and the parameters of the public key with the alias and 169 import it into HKS to save. CNcomment:将ED25519算法公钥以及公钥的参数与别名关联并导入到hks中保存。CNend 170 * 171 * @par 描述: 172 * Associate the ED25519 algorithm public key and the parameters of the public key with the alias and 173 import it into HKS to save. CNcomment:将ED25519算法公钥以及公钥的参数与别名关联并导入到hks中保存。CNend 174 * 175 * @attention None 176 * @param key_alias [IN] type #const struct hks_blob *，Alias to specify to save the ED25519 public key. 177 CNcomment:用于指定保存ED25519公钥的别名。CNend 178 * @param key_param [IN] type #const struct hks_key_param *，The key parameters associated with 179 the public key are saved to the HKS together with the public key, constraint condition: key_param.key_type must be 180 HKS_KEY_TYPE_EDDSA_PUBLIC_KEY_ED25519 181 CNcomment:和公钥关联的秘钥参数，与公钥一起保存到hks中, 约束条件：key_param.key_type必须为 182 HKS_KEY_TYPE_EDDSA_PUBLIC_KEY_ED25519。CNend 183 * @param key [IN] type #const struct hks_blob *，Public key to be imported into hks. 184 CNcomment:需要导入到hks中的公钥。CNend 185 * @retval #0 Success. 186 * @retval #Other Failure. 187 * @par 依赖: 188 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 189 * @see hks_import_public_key 190 */ 191 HKS_DLL_API_PUBLIC int32_t hks_import_public_key( 192 const struct hks_blob *key_alias, 193 const struct hks_key_param *key_param, const struct hks_blob *key); 194 195 /** 196 * @ingroup iot_hks 197 * @brief Export the public key associated with the file name saved in the HKS system. 198 CNcomment:导出保存在hks系统中与文件名关联的公钥。CNend 199 * 200 * @par 描述: 201 * Export the public key associated with the file name saved in the HKS system. 202 CNcomment:导出保存在hks系统中与文件名关联的公钥。CNend 203 * 204 * @attention None 205 * @param key_alias [IN] type #const struct hks_blob * Alias used to associate with the exported public key, 206 constraint condition: key_alias->size <= 64. 207 CNcomment:用于与导出公钥关联的别名, 约束条件：key_alias-> size <= 64。CNend 208 * @param key [OUT] type #struct hks_blob * Cache of hks public key.CNcomment:存放 hks公钥的缓存。CNend 209 * @retval #0 Success. 210 * @retval #Other Failure. 211 * @par 依赖: 212 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 213 * @see hks_export_public_key 214 */ 215 HKS_DLL_API_PUBLIC int32_t hks_export_public_key( 216 const struct hks_blob *key_alias, struct hks_blob *key); 217 218 /** 219 * @ingroup iot_hks 220 * @brief Delete the public key associated with the alias saved in the HKS system. 221 CNcomment:删除保存在hks系统中与别名关联的公钥。CNend 222 * 223 * @par 描述: 224 * Delete the public key associated with the alias saved in the HKS system. 225 CNcomment:删除保存在hks系统中与别名关联的公钥。CNend 226 * 227 * @attention None 228 * @param key_alias [IN] type #const struct hks_blob * The alias associated with the delete key, 229 constraint condition: key_alias->size <= 64. 230 CNcomment:与删除秘钥关联的别名, 约束条件：key_alias-> size <= 64。CNend 231 * @retval #0 Success. 232 * @retval #Other Failure. 233 * @par 依赖: 234 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 235 * @see hks_delete_key 236 */ 237 HKS_DLL_API_PUBLIC int32_t hks_delete_key(const struct hks_blob *key_alias); 238 239 /** 240 * @ingroup iot_hks 241 * @brief Export key attributes associated with aliases stored in the HKS system. 242 CNcomment:导出保存在hks系统中与别名关联的秘钥属性。CNend 243 * 244 * @par 描述: 245 * Export key attributes associated with aliases stored in the HKS system. 246 CNcomment:导出保存在hks系统中与别名关联的秘钥属性。CNend 247 * 248 * @attention None 249 * @param key_alias [IN] type #const struct hks_blob * Alias used to associate with the exported public key, 250 constraint condition: key_alias->size <= 64. 251 CNcomment:用于与导出公钥关联的别名, 约束条件：key_alias-> size <= 64。CNend 252 * @param key_param [OUT] type #struct hks_key_param * Pointer to key attribute. CNcomment:存放秘钥属性的指针。CNend 253 * @retval #0 Success. 254 * @retval #Other Failure. 255 * @par 依赖: 256 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 257 * @see hks_get_key_param 258 */ 259 HKS_DLL_API_PUBLIC int32_t hks_get_key_param(const struct hks_blob *key_alias, 260 struct hks_key_param *key_param); 261 262 /** 263 * @ingroup iot_hks 264 * @brief Determine if there is a public or secret key pair associated with the alias in hks. 265 CNcomment:判断hks中是否存在与别名关联的公钥或秘钥对。CNend 266 * 267 * @par 描述: 268 * Determine if there is a public or secret key pair associated with the alias in hks. 269 CNcomment:判断hks中是否存在与别名关联的公钥或秘钥对。CNend 270 * 271 * @attention None 272 * @param key_alias [IN] type #const struct hks_blob * The alias associated with the delete key, 273 constraint condition: key_alias->size <= 64. 274 CNcomment:与删除秘钥关联的别名, 约束条件：key_alias-> size <= 64。CNend 275 * @retval #0 Success. 276 * @retval #Other Failure. 277 * @par 依赖: 278 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 279 * @see hks_is_key_exist 280 */ 281 HKS_DLL_API_PUBLIC int32_t hks_is_key_exist(const struct hks_blob *key_alias); 282 283 /** 284 * @ingroup iot_hks 285 * @brief Generate a secure random number, no longer than 1024 bytes. CNcomment:生成安全随机数,长度不超过1024字节。CNend 286 * 287 * @par 描述: 288 * Generate a secure random number, no longer than 1024 bytes. 289 CNcomment:生成安全随机数,长度不超过1024字节。CNend 290 * 291 * @attention None 292 * @param random [OUT] type #struct hks_blob * Used to save generated random numbers, 293 random->size must be specified by the caller ,constraint condition: random->size <= 1024. 294 CNcomment:用于保存生成的随机数, random-> size必须由调用方指定，约束条件：random-> size <= 1024。CNend 295 * @retval #0 Success. 296 * @retval #Other Failure. 297 * @par 依赖: 298 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 299 * @see hks_generate_random 300 */ 301 HKS_DLL_API_PUBLIC int32_t hks_generate_random(struct hks_blob *random); 302 303 /** 304 * @ingroup iot_hks 305 * @brief Generate a data signature using the ED25519 private key associated with the alias in hks. 306 CNcomment:使用hks中与别名关联的ED25519私钥生成数据签名。CNend 307 * 308 * @par 描述: 309 * Generate a data signature using the ED25519 private key associated with the alias in hks. 310 CNcomment:使用hks中与别名关联的ED25519私钥生成数据签名。CNend 311 * 312 * @attention None 313 * @param key_alias [IN] type #const struct hks_blob * Sign using alias of secret key, 314 constraint condition: key_alias->size <= 64. 315 CNcomment:签名使用秘钥的别名, 约束条件：key_alias-> size <= 64。CNend 316 * @param key_param [IN] type #const struct hks_key_param *，Attributes of the key associated with key_alias. 317 CNcomment:与key_alias关联的秘钥的属性。CNend 318 * @param hash [IN] type #const struct hks_blob *，Data to be signed. CNcomment:待签名的数据。CNend 319 * @param signature [OUT] type #struct hks_blob *，Output data signature, constraint condition: 320 signature->size bigger & equal 64。 321 CNcomment:输出的数据签名,约束条件：签名大小> = 64。CNend 322 * @retval #0 Success. 323 * @retval #Other Failure. 324 * @par 依赖: 325 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 326 * @see hks_asymmetric_sign 327 */ 328 HKS_DLL_API_PUBLIC int32_t hks_asymmetric_sign( 329 const struct hks_blob *key_alias, 330 const struct hks_key_param *key_param, const struct hks_blob *hash, 331 struct hks_blob *signature); 332 333 /** 334 * @ingroup iot_hks 335 * @brief Verify data signature using ED25519 public key. CNcomment:使用ED25519公钥验证数据签名。CNend 336 * 337 * @par 描述: 338 * Verify data signature using ED25519 public key. CNcomment:使用ED25519公钥验证数据签名。CNend 339 * 340 * @attention None 341 * @param key [IN] type #const struct hks_blob * The alias or ED25519 public key associated with the ED25519 key. 342 CNcomment:与ED25519秘钥关联的别名或ED25519公钥。CNend 343 * @param key_param [IN] type #const struct hks_key_param *，The attributes of the key associated with the key. 344 CNcomment:与key关联的秘钥的属性。CNend 345 * @param hash [IN] type #const struct hks_blob *，Signed data. CNcomment:签名的数据。CNend 346 * @param signature [IN] type #const struct hks_blob *，Data signature,constraint condition: 347 signature->size bigger & equal 64。 348 CNcomment:数据签名, 约束条件：签名大小> = 64。CNend 349 * @retval #0 Success. 350 * @retval #Other Failure. 351 * @par 依赖: 352 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 353 * @see hks_asymmetric_verify 354 */ 355 HKS_DLL_API_PUBLIC int32_t hks_asymmetric_verify(const struct hks_blob *key, 356 const struct hks_key_param *key_param, const struct hks_blob *hash, 357 const struct hks_blob *signature); 358 359 /** 360 * @ingroup iot_hks 361 * @brief Data encryption using AES-128-GCM algorithm. CNcomment:使用AES-128-GCM算法对数据加密。CNend 362 * 363 * @par 描述: 364 * Data encryption using AES-128-GCM algorithm. CNcomment:使用AES-128-GCM算法对数据加密。CNend 365 * 366 * @attention None 367 * @param key [IN] type #const struct hks_blob *，The key used to encrypt the plaintext. 368 CNcomment:用于加密明文的秘钥。CNend 369 * @param key_param [IN] type #const struct hks_key_param *，The attributes of the key associated with the key. 370 constraint condition: key_param.key_type is HKS_KEY_TYPE_AES, key_param.key_len is 128 or 192 or 256; 371 key_param.key_usage is HKS_KEY_USAGE_ENCRYPT, key_param.key_mode is HKS_ALG_GCM; 372 key_param.key_pad is HKS_PADDING_NONE 373 CNcomment:与key关联的秘钥的属性,约束条件：key_param.key_type为HKS_KEY_TYPE_AES，key_param.key_len为128或192或256； 374 key_param.key_usage是HKS_KEY_USAGE_ENCRYPT，key_param.key_mode是HKS_ALG_GCM； 375 key_param.key_pad为HKS_PADDING_NONE。CNend 376 * @param crypt_param [IN] type #const struct hks_crypt_param *，Vectors and additional data used for encryption. 377 CNcomment:加密使用的向量和附加数据。CNend 378 * @param plain_text [IN] type #const struct hks_blob *，Data plaintext。CNcomment:数据明文。CNend 379 * @param cipher_text_with_tag [OUT] type #struct hks_blob *，Data ciphertext CNcomment:数据密文。CNend 380 * @retval #0 Success. 381 * @retval #Other Failure. 382 * @par 依赖: 383 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 384 * @see hks_aead_encrypt 385 */ 386 HKS_DLL_API_PUBLIC int32_t hks_aead_encrypt(const struct hks_blob *key, 387 const struct hks_key_param *key_param, 388 const struct hks_crypt_param *crypt_param, 389 const struct hks_blob *plain_text, 390 struct hks_blob *cipher_text_with_tag); 391 392 /** 393 * @ingroup iot_hks 394 * @brief Decrypt ciphertext using AES-128-GCM algorithm. CNcomment:使用AES-128-GCM算法对密文解密。CNend 395 * 396 * @par 描述: 397 * Decrypt ciphertext using AES-128-GCM algorithm. CNcomment:使用AES-128-GCM算法对密文解密。CNend 398 * 399 * @attention None 400 * @param key [IN] type #const struct hks_blob *，Secret key for decryption. CNcomment:用于解密的秘钥。CNend 401 * @param key_param [IN] type #const struct hks_key_param *，The attributes of the key associated with the key. 402 constraint condition: key_param.key_type is HKS_KEY_TYPE_AES, key_param.key_len is 128 or 192 or 256; 403 key_param.key_usage is HKS_KEY_USAGE_DECRYPT, key_param.key_mode is HKS_ALG_GCM; 404 key_param.key_pad is HKS_PADDING_NONE; 405 CNcomment:与key关联的秘钥的属性,约束条件：key_param.key_type为HKS_KEY_TYPE_AES，key_param.key_len为128或192或256； 406 key_param.key_usage是HKS_KEY_USAGE_DECRYPT，key_param.key_mode是HKS_ALG_GCM； 407 key_param.key_pad为HKS_PADDING_NONE。CNend 408 * @param crypt_param [IN] type #const struct hks_crypt_param *，Vector and additional data used for decryption. 409 CNcomment:解密使用的向量和附加数据。CNend 410 * @param plain_text [OUT] type #struct hks_blob *，Data plaintext。CNcomment:数据明文。CNend 411 * @param cipher_text_with_tag [IN] type #const struct hks_blob *，Data ciphertext CNcomment:数据密文。CNend 412 * @retval #0 Success. 413 * @retval #Other Failure. 414 * @par 依赖: 415 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 416 * @see hks_aead_decrypt 417 */ 418 HKS_DLL_API_PUBLIC int32_t hks_aead_decrypt(const struct hks_blob *key, 419 const struct hks_key_param *key_param, 420 const struct hks_crypt_param *crypt_param, 421 struct hks_blob *plain_text, 422 const struct hks_blob *cipher_text_with_tag); 423 424 /** 425 * @ingroup iot_hks 426 * @brief Key negotiation using X25519 algorithm. CNcomment:使用X25519算法进行秘钥协商。CNend 427 * 428 * @par 描述: 429 * Key negotiation using X25519 algorithm. CNcomment:使用X25519算法进行秘钥协商。CNend 430 * 431 * @attention None 432 * @param agreed_key [OUT] type #struct hks_blob *，Negotiation key calculated through X25519. 433 CNcomment:通过X25519计算出来的协商秘钥。CNend 434 * @param private_key_param [IN] type #const struct hks_key_param *，Local private key private_key attributes. 435 constraint condition:private_key_param.key_type is HKS_KEY_TYPE_ECC_KEYPAIR_CURVE25519 436 private_key_param.key_usage is HKS_KEY_USAGE_DERIVE 437 private_key_param.key_mode is the same as agreement_alg 438 CNcomment:本端私钥private_key的属性,约束条件：private_key_param.key_type为HKS_KEY_TYPE_ECC_KEYPAIR_CURVE25519 439 private_key_param.key_usage是HKS_KEY_USAGE_DERIVE 440 private_key_param.key_mode与Agreement_alg相同。CNend 441 * @param agreement_alg [IN] type #const uint32_t， 442 Algorithm for further deriving secret key based on negotiation secret key. 443 CNcomment:基于协商秘钥进一步派生秘钥的算法。CNend 444 * @param private_key [IN] type #const struct hks_blob *，Local X25519 private key。 445 CNcomment:本端X25519私钥。CNend 446 * @param peer_public_key [IN] type #const struct hks_blob *，Peer X25519 public key 447 CNcomment:对端X25519公钥。CNend 448 * @retval #0 Success. 449 * @retval #Other Failure. 450 * @par 依赖: 451 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 452 * @see hks_key_agreement 453 */ 454 HKS_DLL_API_PUBLIC int32_t hks_key_agreement(struct hks_blob *agreed_key, 455 const struct hks_key_param *private_key_param, 456 const uint32_t agreement_alg, const struct hks_blob *private_key, 457 const struct hks_blob *peer_public_key); 458 459 /** 460 * @ingroup iot_hks 461 * @brief Key derivation. CNcomment:秘钥派生。CNend 462 * 463 * @par 描述: 464 * Derive the key using HKD512 algorithm based on SHA512. 465 The currently derived key is only used for AES encryption and decryption. 466 CNcomment:使用基于SHA512的HKDF算法派生秘钥，当前派生的秘钥仅用于AES加解密。CNend 467 * 468 * @attention None 469 * @param derived_key [OUT] type #struct hks_blob *，Derived key calculated through HKDF ， 470 derived_key and data cannot be null, and size >= 16. 471 CNcomment:通过HKDF计算出来的派生秘钥 named_key和data不能为null，且大小> = 16。CNend 472 * @param key_param [IN] type #const struct hks_key_param *，Properties for derived keys constraint condition: 473 key_param.key_type is HKS_KEY_TYPE_DERIVE，key_param.key_usage is HKS_KEY_USAGE_DERIVE 474 key_param.key_mode is hks_alg_hkdf(HKS_ALG_HASH_SHA_256) or hks_alg_hkdf(HKS_ALG_HASH_SHA_512) 475 key_param.key_len is 128 or 256. 476 CNcomment:派生秘钥对应的属性，约束条件： 477 key_param.key_type为HKS_KEY_TYPE_DERIVE，key_param.key_usage为HKS_KEY_USAGE_DERIVE 478 key_param.key_mode为hks_alg_hkdf（HKS_ALG_HASH_SHA_256）或hks_alg_hkdf（HKS_ALG_HASH_SHA_512） 479 key_param.key_len是128或256。。CNend 480 * @param kdf_key [IN] type #const struct hks_blob *，The base key used to derive the key. 481 CNcomment:用于派生秘钥的基础秘钥。CNend 482 * @param salt [IN] type #const struct hks_blob *， 483 Derived salt value,salt.size must be greater than or equal to 16。 484 CNcomment:派生使用的盐值,salt.size必须大于或等于16。CNend 485 * @param label [IN] type #const struct hks_blob *，Derived label，constraint condition: 486 lable.size must be greater than or equal to 16 487 CNcomment:派生使用的label，约束条件：lable.size必须大于或等于16。CNend 488 * @retval #0 Success. 489 * @retval #Other Failure. 490 * @par 依赖: 491 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 492 * @see hks_key_derivation 493 */ 494 HKS_DLL_API_PUBLIC int32_t hks_key_derivation(struct hks_blob *derived_key, 495 const struct hks_key_param *key_param, const struct hks_blob *kdf_key, 496 const struct hks_blob *salt, const struct hks_blob *label); 497 498 /** 499 * @ingroup iot_hks 500 * @brief Generate message authentication code (MAC) based on SHA256 or SHA512. 501 CNcomment:基于SHA256或SHA512生成消息验证码(MAC)。CNend 502 * 503 * @par 描述: 504 * Generate message authentication code (MAC) based on SHA256 or SHA512. 505 CNcomment:基于SHA256或SHA512生成消息验证码(MAC)。CNend 506 * 507 * @attention None 508 * @param key [IN] type #const struct hks_blob *，Keys involved in calculating HMAC, 509 data cannot be null,and size > 0. 510 CNcomment:参与计算HMAC的秘钥,数据不能为null，大小> 0。CNend 511 * @param alg [IN] type #const uint32_t，HMAC algorithm hks_alg_hmac(HKS_ALG_HASH_SHA_256) or 512 (HKS_ALG_HASH_SHA_512). 513 CNcomment:HMAC算法, hks_alg_hmac（HKS_ALG_HASH_SHA_256）或 （HKS_ALG_HASH_SHA_512）。CNend 514 * @param src_data [IN] type #const struct hks_blob *，src data data cannot be null, and size > 0. 515 CNcomment:源数据，数据不能为null，大小> 0。CNend 516 * @param output [OUT] type #struct hks_blob *，Generated message verification code, 517 output and output->data cannot be null constraint condition: 518 when alg is hks_alg_hmac(HKS_ALG_HASH_SHA_256), output->size must be greater than or 519 equal to 32 when alg is hks_alg_hmac(HKS_ALG_HASH_SHA_512), output->size must be greater than or equal to 64 520 CNcomment:生成的消息验证码,输出和输出->数据不能为空约束条件： 521 当alg为hks_alg_hmac（HKS_ALG_HASH_SHA_256）时，output-> size必须大于或 522 当alg为hks_alg_hmac（HKS_ALG_HASH_SHA_512）时等于32，则output-> size必须大于或等于64。CNend 523 * @retval #0 Success. 524 * @retval #Other Failure. 525 * @par 依赖: 526 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 527 * @see hks_hmac 528 */ 529 HKS_DLL_API_PUBLIC int32_t hks_hmac(const struct hks_blob *key, 530 const uint32_t alg, const struct hks_blob *src_data, 531 struct hks_blob *output); 532 533 /** 534 * @ingroup iot_hks 535 * @brief Calculate the hash value of the data based on SHA256 or SHA512. 536 CNcomment:基于SHA256或SHA512计算数据的散列值。CNend 537 * 538 * @par 描述: 539 * Calculate the hash value of the data based on SHA256 or SHA512. 540 CNcomment:基于SHA256或SHA512计算数据的散列值。CNend 541 * 542 * @attention None 543 * @param alg [IN] type #const uint32_t，Hash algorithm, Only spuuort SHA256/SHA512. 544 CNcomment:哈希算法，仅支持SHA256 / SHA512。CNend 545 * @param src_data [IN] type #const struct hks_blob *，src data data cannot be null, and size > 0. 546 CNcomment:源数据，数据不能为null，大小> 0。CNend 547 * @param hash [OUT] type #struct hks_blob *，Generated message verification code , 548 hash and hash->data cannot be null constraint condition: 549 when alg is HKS_ALG_HASH_SHA_256, hash->size must be greater than or equal to 32 when alg is HKS_ALG_HASH_SHA_512, 550 hash->size must be greater than or equal to 64. 551 CNcomment:生成的消息验证码,hash和hash-> data不能为null约束条件：当alg为HKS_ALG_HASH_SHA_256时， 552 当alg为HKS_ALG_HASH_SHA_512时，hash-> size必须大于或等于32，hash-> size必须大于或等于64。CNend 553 * @retval #0 Success. 554 * @retval #Other Failure. 555 * @par 依赖: 556 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 557 * @see hks_hash 558 */ 559 HKS_DLL_API_PUBLIC int32_t hks_hash(const uint32_t alg, 560 const struct hks_blob *src_data, struct hks_blob *hash); 561 562 /** 563 * @ingroup iot_hks 564 * @brief Unsigned large integer modulo operation. CNcomment:无符号大整数模运算。CNend 565 * 566 * @par 描述: 567 * Unsigned large integer modulo operation. CNcomment:无符号大整数模运算。CNend 568 * 569 * @attention None 570 * @param x [OUT] type #struct hks_blob *，Modular result,x and x->data cannot be null, x->size >= n.size. 571 CNcomment:模运算结果,x和x-> data不能为null，x-> size> = n.size。CNend 572 * @param a [IN] type #const struct hks_blob *，Base data data cannot be null, size > 0. 573 CNcomment:底数, 数据不能为null，大小> 0。CNend 574 * @param e [IN] type #const struct hks_blob *，data cannot be null, size > 0. 575 CNcomment:幂, 数据不能为null，大小> 0。CNend 576 * @param n [IN] type #const struct hks_blob *，Modulus, data cannot be null, size > 0. 577 CNcomment:模数, 数据不能为null，大小> 0。CNend 578 * @retval #0 Success. 579 * @retval #Other Failure. 580 * @par 依赖: 581 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 582 * @see hks_bn_exp_mod 583 */ 584 HKS_DLL_API_PUBLIC int32_t hks_bn_exp_mod(struct hks_blob *x, 585 const struct hks_blob *a, const struct hks_blob *e, 586 const struct hks_blob *n); 587 588 /** 589 * @ingroup iot_hks 590 * @brief Get public key alias list Interface. CNcomment:获取公钥别名列表接口。CNend 591 * 592 * @par 描述: 593 * Get public key alias list Interface. CNcomment:获取公钥别名列表接口。CNend 594 * 595 * @attention None 596 * @param key_alias_list [OUT] type #struct hks_blob *，struct hks_blob array, alloc and free memory by the caller. 597 CNcomment:用于存放别名,struct hks_blob数组，调用者分配和释放内存。CNend 598 * @param list_count [IN] type #uint32_t *，Indicates the number of available hks_blob_t caches, 599 public key alias number, alloc and free memory by the caller. 600 CNcomment:表示可用的hks_blob_t缓存数量,调用方的公钥别名号，分配和可用内存。CNend 601 * @retval #0 Success. 602 * @retval #Other Failure. 603 * @par 依赖: 604 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 605 * @see hks_get_pub_key_alias_list 606 */ 607 HKS_DLL_API_PUBLIC int32_t hks_get_pub_key_alias_list( 608 struct hks_blob *key_alias_list, uint32_t *list_count); 609 610 /** 611 * @ingroup iot_hks 612 * @brief generate symmetric key. CNcomment:生成对称密钥。CNend 613 * 614 * @par 描述: 615 * generate symmetric key，Only AES-128/AES-192/AES-256 key generation is supported. 616 CNcomment:生成对称密钥，仅支持AES-128 / AES-192 / AES-256密钥生成。CNend 617 * 618 * @attention None 619 * @param output_key [OUT] type #struct hks_blob *，Key obtained.CNcomment:获取的key。CNend 620 * @param key_param [IN] type #const struct hks_key_param *，Need to generate key parameters. 621 CNcomment:需要生成key的参数。CNend 622 * @retval #0 Success. 623 * @retval #Other Failure. 624 * @par 依赖: 625 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 626 * @see hks_generate_symmetric_key 627 */ 628 HKS_DLL_API_PUBLIC int32_t hks_generate_symmetric_key(struct hks_blob *output_key, 629 const struct hks_key_param *key_param); 630 631 /** 632 * @ingroup iot_hks 633 * @brief AES encryption, requires the use of the AES symmetric key generated above as an input parameter, 634 supports GCM CCM CBC mode, key length 128/192/256. 635 CNcomment:AES加密，要求使用上述生成AES对称的密钥作为入参，支持GCM CCM CBC模式，key长度128/192/256。CNend 636 * 637 * @par 描述: 638 * AES encryption, requires the use of the AES symmetric key generated above as an input parameter, 639 supports GCM CCM CBC mode, key length 128/192/256. 640 CNcomment:AES加密，要求使用上述生成AES对称的密钥作为入参，支持GCM CCM CBC模式，key长度128/192/256。CNend 641 * 642 * @attention None 643 * @param key [IN] type #const struct hks_blob *，The key required for encryption, 644 the key to generate the AES symmetric key output as an input parameter. 645 CNcomment:加密所需密钥，需要为生成AES对称密钥输出的key作为入参。CNend 646 * @param key_param [IN] type #const struct hks_key_param *，Encryption key parameters. 647 CNcomment:加密密钥参数。CNend 648 * @param crypt_param [IN] type #const struct hks_crypt_param *，Encrypted information. CNcomment:加密信息。CNend 649 * @param plain_text [IN] type #const struct hks_blob *，plain_text.CNcomment:明文。CNend 650 * @param cipher_text_with_tag [OUT] type #struct hks_blob *，Encrypted ciphertext.CNcomment:加密后密文。CNend 651 * @retval #0 Success. 652 * @retval #Other Failure. 653 * @par 依赖: 654 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 655 * @see hks_symmetric_encrypt 656 */ 657 HKS_DLL_API_PUBLIC int32_t hks_symmetric_encrypt(const struct hks_blob *key, 658 const struct hks_key_param *key_param, const struct hks_crypt_param *crypt_param, 659 const struct hks_blob *plain_text, struct hks_blob *cipher_text_with_tag); 660 661 /** 662 * @ingroup iot_hks 663 * @brief AES decryption, requires the use of the above generated AES symmetric key as an input parameter, 664 supports GCM CCM CBC mode, key length 128/192/256. 665 CNcomment:AES解密，要求使用上述生成AES对称的密钥作为入参，支持GCM CCM CBC模式，key长度128/192/256。CNend 666 * 667 * @par 描述: 668 * AES decryption, requires the use of the above generated AES symmetric key as an input parameter, 669 supports GCM CCM CBC mode, key length 128/192/256. 670 CNcomment:AES解密，要求使用上述生成AES对称的密钥作为入参，支持GCM CCM CBC模式，key长度128/192/256。CNend 671 * 672 * @attention None 673 * @param key [IN] type #const struct hks_blob *，The key required for decryption needs to be the 674 input key for generating the AES symmetric key output. 675 CNcomment:解密所需密钥，需要为生成AES对称密钥输出的key作为入参。CNend 676 * @param key_param [IN] type #const struct hks_key_param *，decrypt key parameters. 677 CNcomment:解密密钥参数。CNend 678 * @param crypt_param [IN] type #const struct hks_crypt_param *，Decrypt information. CNcomment:解密信息。CNend 679 * @param plain_text [OUT] type #const struct hks_blob *，Plaintext after decryption.CNcomment:解密后明文。CNend 680 * @param cipher_text_with_tag [IN] type #struct hks_blob *，Ciphertext.CNcomment:密文。CNend 681 * @retval #0 Success. 682 * @retval #Other Failure. 683 * @par 依赖: 684 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 685 * @see hks_symmetric_encrypt 686 */ 687 HKS_DLL_API_PUBLIC int32_t hks_symmetric_decrypt(const struct hks_blob *key, 688 const struct hks_key_param *key_param, const struct hks_crypt_param *crypt_param, 689 struct hks_blob *plain_text, const struct hks_blob *cipher_text_with_tag); 690 691 /** 692 * @ingroup iot_hks 693 * @brief get security capabilites. CNcomment:获得安全功能。CNend 694 * 695 * @par 描述: 696 * Get device security attributes, output as a json string, you can get information such as the 697 algorithm type supported by the device certificate. 698 CNcomment:获取设备安全属性，输出为json串，可以获取设备证书支持的算法类型等信息。CNend 699 * 700 * @attention None 701 * @param flag [IN] type #uint32_t，Reserved field, no assignment is required. 702 CNcomment:预留字段，当前不需要赋值。CNend 703 * @param capabilities [OUT] type #struct hks_blob *，Information obtained.CNcomment:获取到的信息。CNend 704 * @retval #0 Success. 705 * @retval #Other Failure. 706 * @par 依赖: 707 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 708 * @see hks_get_security_capabilites 709 */ 710 HKS_DLL_API_PUBLIC int32_t hks_get_security_capabilites(uint32_t flag, struct hks_blob *capabilities); 711 712 /** 713 * @ingroup iot_hks 714 * @brief export device certs. CNcomment:导出设备证书。CNend 715 * 716 * @par 描述: 717 * export device certs. CNcomment:导出设备证书。CNend 718 * 719 * @attention None 720 * @param key_id [IN] type #uint8_t，Array index of device_identity field obtained with 721 hks_get_security_capabilites. 722 CNcomment:使用hks_get_security_capabilites获取的device_identity字段的数组下标。CNend 723 * @param cert_chain [OUT] type #hks_cert_chain *，Export certificate information. 724 CNcomment:导出证书信息。CNend 725 * @retval #0 Success. 726 * @retval #Other Failure. 727 * @par 依赖: 728 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 729 * @see hks_export_device_certs 730 */ 731 HKS_DLL_API_PUBLIC int32_t hks_export_device_certs(uint8_t key_id, struct hks_cert_chain *cert_chain); 732 733 /** 734 * @ingroup iot_hks 735 * @brief sign with device key. CNcomment:用设备私钥签名。CNend 736 * 737 * @par 描述: 738 * sign with device key. CNcomment:用设备私钥签名。CNend 739 * 740 * @attention None 741 * @param key_id [IN] type #uint8_t，Array index of device_identity field obtained with 742 hks_get_security_capabilites. 743 CNcomment:使用hks_get_security_capabilites获取的device_identity字段的数组下标。CNend 744 * @param usage [IN] type #const struct hks_usage_spec *，Signing required parameters. 745 CNcomment:签名所需参数。CNend 746 * @param challenge [IN] type #const struct hks_blob *，Data to be signed. 747 CNcomment:待签名的数据。CNend 748 * @param signature [OUT] type #struct hks_blob *，Output data signature. 749 CNcomment:输出的数据签名。CNend 750 * @retval #0 Success. 751 * @retval #Other Failure. 752 * @par 依赖: 753 * @li hks_types.h：describes hks_types SDK interfaces.CNcomment:描述hks_types SDK的接口。CNend 754 * @see hks_sign_with_device_key 755 */ 756 HKS_DLL_API_PUBLIC int32_t hks_sign_with_device_key(uint8_t key_id, 757 const struct hks_usage_spec *usage, const struct hks_blob *challenge, struct hks_blob *signature); 758 759 760 #ifdef __cplusplus 761 } 762 #endif 763 764 #endif /* HKS_CLIENT_H */ 765