1 /* 2 * Copyright (c) 2020 Huawei Device Co., Ltd. 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 16 #ifndef HKS_CLIENT_H 17 #define HKS_CLIENT_H 18 19 #include "hks_types.h" 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 /* 26 * hks_get_sdk_version 27 * get sdk version 28 * return value: none 29 */ 30 HKS_DLL_API_PUBLIC void hks_get_sdk_version(struct hks_blob *sdk_version); 31 32 /* 33 * hks init 34 * load file hks_keystore to buffer 35 * parameter: none 36 * return value: none 37 */ 38 HKS_DLL_API_PUBLIC int32_t hks_init(void); 39 40 /* 41 * destroy 42 * parameter: none 43 * return value: none 44 */ 45 HKS_DLL_API_PUBLIC void hks_destroy(void); 46 47 /* 48 * refresh key info and root key info 49 * Reproduce the hks_keystore file header and clear the old key 50 * Reproduce root key info 51 * parameter: none 52 * return value: none 53 */ 54 HKS_DLL_API_PUBLIC int32_t hks_refresh_key_info(void); 55 56 /* 57 * generate key 58 * Only ED25519 algorithm key pair generation is supported 59 * The number of local storage keys (including 60 * generated ED25519 public-private key pairs 61 * imported ED25519 public keys) is limited to 16 62 * key_alias: key alias, constraint condition: 63 * key_alias->size <= 64 64 * key_param: The parameter of the key which need to generate 65 * constraint condition: 66 * key_param cannot be NULL 67 * key_param->key_type must be HKS_KEY_TYPE_EDDSA_KEYPAIR_ED25519 68 * return 0 OK, other error 69 */ 70 HKS_DLL_API_PUBLIC int32_t hks_generate_key(const struct hks_blob *key_alias, 71 const struct hks_key_param *key_param); 72 73 /* 74 * generate asymmetric key 75 * Only X25519 algorithm key pair generation is supported 76 * key_param: The parameter of the key which need to generate 77 * constraint condition: 78 * key_param.key_type must be 79 * HKS_KEY_TYPE_ECC_KEYPAIR_CURVE25519 80 * key_param.usage must be 81 * hks_alg_ecdh(HKS_ALG_SELECT_RAW) 82 * return 0 OK, other error 83 */ 84 HKS_DLL_API_PUBLIC int32_t hks_generate_asymmetric_key( 85 const struct hks_key_param *key_param, struct hks_blob *pri_key, 86 struct hks_blob *pub_key); 87 88 /* 89 * import public key 90 * Only ED25519 public key import is supported 91 * The number of local storage keys (including 92 * generated ED25519 public-private key pairs 93 * imported ED25519 public keys) is limited to no more than 16 94 * key_param: The parameter of the key which need to generate 95 * constraint condition: 96 * key_param.key_type must be 97 * HKS_KEY_TYPE_EDDSA_PUBLIC_KEY_ED25519 98 * return 0 OK, other error 99 */ 100 HKS_DLL_API_PUBLIC int32_t hks_import_public_key( 101 const struct hks_blob *key_alias, 102 const struct hks_key_param *key_param, const struct hks_blob *key); 103 104 /* 105 * export public key 106 * Only ED25519 public key export is supported 107 * key_alias: constraint condition: key_alias->size <= 64 108 * return 0 OK, other error 109 */ 110 HKS_DLL_API_PUBLIC int32_t hks_export_public_key( 111 const struct hks_blob *key_alias, struct hks_blob *key); 112 113 /* 114 * delete public key 115 * Only ED25519 public key delete is supported 116 * key_alias: constraint condition: key_alias->size <= 64 117 * return 0 OK, other error 118 */ 119 HKS_DLL_API_PUBLIC int32_t hks_delete_key(const struct hks_blob *key_alias); 120 121 /* 122 * get key param 123 * key_alias: constraint condition: key_alias->size <= 64 124 * return 0 OK, other error 125 */ 126 HKS_DLL_API_PUBLIC int32_t hks_get_key_param(const struct hks_blob *key_alias, 127 struct hks_key_param *key_param); 128 129 /* 130 * is key exist 131 * key_alias: constraint condition: key_alias->size <= 64 132 * return: 0 - exist; other - Non-existent 133 */ 134 HKS_DLL_API_PUBLIC int32_t hks_is_key_exist(const struct hks_blob *key_alias); 135 136 /* 137 * generate random 138 * random: random->size must be specified by the caller 139 * constraint condition: random->size <= 1024 140 * return 0 OK, other error 141 */ 142 HKS_DLL_API_PUBLIC int32_t hks_generate_random(struct hks_blob *random); 143 144 /* 145 * sign 146 * Only ED25519 local storage private key signature is supported 147 * key_alias: constraint condition: key_alias->size <= 64 148 * key_param: constraint condition: 149 * key_param.key_type must be 150 * HKS_KEY_TYPE_EDDSA_KEYPAIR_ED25519 151 * signature: constraint condition: 152 * signature->size >= 64 153 * return 0 OK, other error 154 */ 155 HKS_DLL_API_PUBLIC int32_t hks_asymmetric_sign( 156 const struct hks_blob *key_alias, 157 const struct hks_key_param *key_param, const struct hks_blob *hash, 158 struct hks_blob *signature); 159 160 /* 161 * verify 162 * Only ED25519 public key verify is supported 163 * key: key alias or the key value itself, 164 * differentiate by key.type: 165 * if it is the key alias, key.type must be HKS_BLOB_TYPE_ALIAS 166 * it is the key value itself, key.type must be HKS_BLOB_TYPE_KEY 167 * signature: constraint condition: 168 * signature->size >= 64 169 * return 0 OK, other error 170 */ 171 HKS_DLL_API_PUBLIC int32_t hks_asymmetric_verify(const struct hks_blob *key, 172 const struct hks_key_param *key_param, const struct hks_blob *hash, 173 const struct hks_blob *signature); 174 175 /* 176 * encrypt 177 * only support AES-128-GCM encrypt 178 * key: used to ecrypt plain_text 179 * key_param: constraint condition: 180 * key_param.key_type is HKS_KEY_TYPE_AES; 181 * key_param.key_len is 128 or 192 or 256; 182 * key_param.key_usage is HKS_KEY_USAGE_ENCRYPT; 183 * key_param.key_mode is HKS_ALG_GCM; 184 * key_param.key_pad is HKS_PADDING_NONE; 185 * crypt_param: 186 * crypt_param.nonce.size suggest to be 16 187 * crypt_param.aad.size suggest to be 16 188 * return 0 OK, other error 189 */ 190 HKS_DLL_API_PUBLIC int32_t hks_aead_encrypt(const struct hks_blob *key, 191 const struct hks_key_param *key_param, 192 const struct hks_crypt_param *crypt_param, 193 const struct hks_blob *plain_text, 194 struct hks_blob *cipher_text_with_tag); 195 196 /* 197 * decrypt 198 * only support AES-128-GCM decrypt 199 * key: used to decrypt cipher_text_with_tag 200 * key_param: constraint condition: 201 * key_param.key_type is HKS_KEY_TYPE_AES; 202 * key_param.key_len is 128 or 192 or 256; 203 * key_param.key_usage is HKS_KEY_USAGE_DECRYPT; 204 * key_param.key_mode is HKS_ALG_GCM; 205 * key_param.key_pad is HKS_PADDING_NONE; 206 * crypt_param: 207 * crypt_param.nonce.size suggest to be 16 208 * crypt_param.aad.size suggest to be 16 209 * return 0 OK, other error 210 */ 211 HKS_DLL_API_PUBLIC int32_t hks_aead_decrypt(const struct hks_blob *key, 212 const struct hks_key_param *key_param, 213 const struct hks_crypt_param *crypt_param, 214 struct hks_blob *plain_text, 215 const struct hks_blob *cipher_text_with_tag); 216 217 /* 218 * key agreement 219 * private_key_param: constraint condition: 220 * private_key_param.key_type is HKS_KEY_TYPE_ECC_KEYPAIR_CURVE25519 221 * private_key_param.key_usage is HKS_KEY_USAGE_DERIVE 222 * private_key_param.key_mode is the same as agreement_alg 223 * private_key: constraint condition: 224 * private_key.size must be 32 225 * peer_public_key: constraint condition: 226 * peer_public_key.size must be 32 227 * agreement_alg: constraint condition: 228 * agreement_alg must be 229 * hks_alg_ecdh(HKS_ALG_SELECT_RAW) 230 * return 0 OK, other error 231 */ 232 HKS_DLL_API_PUBLIC int32_t hks_key_agreement(struct hks_blob *agreed_key, 233 const struct hks_key_param *private_key_param, 234 const uint32_t agreement_alg, const struct hks_blob *private_key, 235 const struct hks_blob *peer_public_key); 236 237 /* 238 * key derivation 239 * derived_key and data cannot be null, and size >= 16 240 * key_param: constraint condition: 241 * key_param.key_type is HKS_KEY_TYPE_DERIVE 242 * key_param.key_usage is HKS_KEY_USAGE_DERIVE 243 * key_param.key_mode is hks_alg_hkdf(HKS_ALG_HASH_SHA_256) or 244 * hks_alg_hkdf(HKS_ALG_HASH_SHA_512) 245 * key_param.key_len is 128 or 256 246 * salt: constraint condition: 247 * salt.size must be greater than or equal to 16 248 * label: constraint condition: 249 * lable.size must be greater than or equal to 16 250 * return 0 OK, other error 251 */ 252 HKS_DLL_API_PUBLIC int32_t hks_key_derivation(struct hks_blob *derived_key, 253 const struct hks_key_param *key_param, const struct hks_blob *kdf_key, 254 const struct hks_blob *salt, const struct hks_blob *label); 255 256 /* 257 * hks_hmac 258 * key: data cannot be null,and size > 0 259 * src_data: data cannot be null,and size > 0 260 * alg: hks_alg_hmac(HKS_ALG_HASH_SHA_256) or 261 * hks_alg_hmac(HKS_ALG_HASH_SHA_512) 262 * output: output and output->data cannot be null 263 * constraint condition: 264 * when alg is hks_alg_hmac(HKS_ALG_HASH_SHA_256), output->size must be 265 * greater than or equal to 32 266 * when alg is hks_alg_hmac(HKS_ALG_HASH_SHA_512), output->size must be 267 * greater than or equal to 64 268 * return 0 OK, other error 269 */ 270 HKS_DLL_API_PUBLIC int32_t hks_hmac(const struct hks_blob *key, 271 const uint32_t alg, const struct hks_blob *src_data, 272 struct hks_blob *output); 273 274 /* 275 * hks_hash 276 * alg: Hash algorithm, Only spuuort SHA256/SHA512 277 * src_data: data cannot be null, and size > 0 278 * hash: hash and hash->data cannot be null 279 * constraint condition: 280 * when alg is HKS_ALG_HASH_SHA_256, hash->size must be 281 * greater than or equal to 32 282 * when alg is HKS_ALG_HASH_SHA_512, hash->size must be 283 * greater than or equal to 64 284 * return 0 OK, other error 285 */ 286 HKS_DLL_API_PUBLIC int32_t hks_hash(const uint32_t alg, 287 const struct hks_blob *src_data, struct hks_blob *hash); 288 289 /* 290 * hks_bn_exp_mod 291 * x: output, x and x->data cannot be null, x->size >= n.size 292 * a, e, n: input, data cannot be null, size > 0 293 * return 0 OK, other error 294 */ 295 HKS_DLL_API_PUBLIC int32_t hks_bn_exp_mod(struct hks_blob *x, 296 const struct hks_blob *a, const struct hks_blob *e, 297 const struct hks_blob *n); 298 299 /* 300 * register log Interface 301 * log: designated by the caller, invoked by hks 302 * return 0 OK, other error 303 */ 304 HKS_DLL_API_PUBLIC int32_t hks_register_log_interface( 305 const struct hks_log_f_group *log); 306 307 /* 308 * get public key alias list Interface 309 * key_alias_list: struct hks_blob array, alloc and free memory by the caller 310 * list_count: public key alias number, alloc and free memory by the caller 311 * return 0 OK, other error 312 */ 313 HKS_DLL_API_PUBLIC int32_t hks_get_pub_key_alias_list( 314 struct hks_blob *key_alias_list, uint32_t *list_count); 315 316 #ifdef __cplusplus 317 } 318 #endif 319 320 #endif /* HKS_CLIENT_H */ 321