1 /* 2 * Copyright (c) 2021-2023 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 /** 17 * @file hks_api.h 18 * 19 * @brief Declares huks operation inner interface. 20 * 21 * @since 8 22 */ 23 24 #ifndef HKS_API_H 25 #define HKS_API_H 26 27 #include "hks_type.h" 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 /** 34 * @brief Get HUKS sdk version 35 * @param sdkVersion sdk version 36 * @return error code, see hks_type.h 37 */ 38 HKS_API_EXPORT int32_t HksGetSdkVersion(struct HksBlob *sdkVersion); 39 40 /** 41 * @brief HUKS initialize 42 * @return error code, see hks_type.h 43 */ 44 HKS_API_EXPORT int32_t HksInitialize(void); 45 46 /** 47 * @brief HUKS initialize fresh key info 48 * @return error code, see hks_type.h 49 */ 50 HKS_API_EXPORT int32_t HksRefreshKeyInfo(void); 51 52 /** 53 * @brief Generate key 54 * @param keyAlias key alias 55 * @param paramSetIn required parameter set 56 * @param paramSetOut output parameter set 57 * @return error code, see hks_type.h 58 */ 59 HKS_API_EXPORT int32_t HksGenerateKey(const struct HksBlob *keyAlias, 60 const struct HksParamSet *paramSetIn, struct HksParamSet *paramSetOut); 61 62 /** 63 * @brief Import key 64 * @param keyAlias key alias 65 * @param paramSet required parameter set 66 * @param key the key needs to be imported 67 * @return error code, see hks_type.h 68 */ 69 HKS_API_EXPORT int32_t HksImportKey(const struct HksBlob *keyAlias, 70 const struct HksParamSet *paramSet, const struct HksBlob *key); 71 72 /** 73 * @brief Import wrapped key 74 * @param keyAlias key alias 75 * @param wrappingKeyAlias alias used to decrypt the key data after the wrap 76 * @param paramSet required parameter set 77 * @param wrappedKeyData wrapped key data out 78 * @return error code, see hks_type.h 79 */ 80 HKS_API_EXPORT int32_t HksImportWrappedKey(const struct HksBlob *keyAlias, const struct HksBlob *wrappingKeyAlias, 81 const struct HksParamSet *paramSet, const struct HksBlob *wrappedKeyData); 82 83 /** 84 * @brief Export public key 85 * @param keyAlias key alias 86 * @param paramSet required parameter set 87 * @param key exported key 88 * @return error code, see hks_type.h 89 */ 90 HKS_API_EXPORT int32_t HksExportPublicKey(const struct HksBlob *keyAlias, 91 const struct HksParamSet *paramSet, struct HksBlob *key); 92 93 /** 94 * @brief Delete key 95 * @param keyAlias key alias 96 * @param paramSet required parameter set 97 * @return error code, see hks_type.h 98 */ 99 HKS_API_EXPORT int32_t HksDeleteKey(const struct HksBlob *keyAlias, const struct HksParamSet *paramSet); 100 101 /** 102 * @brief Get key parameter set 103 * @param keyAlias key alias 104 * @param paramSetIn required parameter set 105 * @param paramSetOut output parameter set 106 * @return error code, see hks_type.h 107 */ 108 HKS_API_EXPORT int32_t HksGetKeyParamSet(const struct HksBlob *keyAlias, 109 const struct HksParamSet *paramSetIn, struct HksParamSet *paramSetOut); 110 111 /** 112 * @brief Check whether the key exists 113 * @param keyAlias key alias 114 * @param paramSetIn required parameter set 115 * @param paramSetOut output parameter set 116 * @return error code, see hks_type.h 117 */ 118 HKS_API_EXPORT int32_t HksKeyExist(const struct HksBlob *keyAlias, const struct HksParamSet *paramSet); 119 120 /** 121 * @brief Generate random 122 * @param paramSet required parameter set 123 * @param random output random 124 * @return error code, see hks_type.h 125 */ 126 HKS_API_EXPORT int32_t HksGenerateRandom(const struct HksParamSet *paramSet, struct HksBlob *random); 127 128 /** 129 * @brief Sign operation 130 * @param key required key to sign data 131 * @param paramSet required parameter set 132 * @param srcData the data needs to sign 133 * @param signature signatured data 134 * @return error code, see hks_type.h 135 */ 136 HKS_API_EXPORT int32_t HksSign(const struct HksBlob *key, const struct HksParamSet *paramSet, 137 const struct HksBlob *srcData, struct HksBlob *signature); 138 139 /** 140 * @brief Verify operation 141 * @param key required key to verify data 142 * @param paramSet required parameter set 143 * @param srcData the data needs to verify 144 * @param signature verified data 145 * @return error code, see hks_type.h 146 */ 147 HKS_API_EXPORT int32_t HksVerify(const struct HksBlob *key, const struct HksParamSet *paramSet, 148 const struct HksBlob *srcData, const struct HksBlob *signature); 149 150 /** 151 * @brief Encrypt operation 152 * @param key required key to encrypt data 153 * @param paramSet required parameter set 154 * @param plainText the data needs to encrypt 155 * @param cipherText encrypted data 156 * @return error code, see hks_type.h 157 */ 158 HKS_API_EXPORT int32_t HksEncrypt(const struct HksBlob *key, const struct HksParamSet *paramSet, 159 const struct HksBlob *plainText, struct HksBlob *cipherText); 160 161 /** 162 * @brief Decrypt operation 163 * @param key required key to decrypt data 164 * @param paramSet required parameter set 165 * @param cipherText the data needs to decrypt 166 * @param plainText decrypted data 167 * @return error code, see hks_type.h 168 */ 169 HKS_API_EXPORT int32_t HksDecrypt(const struct HksBlob *key, const struct HksParamSet *paramSet, 170 const struct HksBlob *cipherText, struct HksBlob *plainText); 171 172 /** 173 * @brief Agree key 174 * @param paramSet required parameter set 175 * @param privateKey self private key 176 * @param peerPublicKey peer public key 177 * @param agreedKey agreed key 178 * @return error code, see hks_type.h 179 */ 180 HKS_API_EXPORT int32_t HksAgreeKey(const struct HksParamSet *paramSet, const struct HksBlob *privateKey, 181 const struct HksBlob *peerPublicKey, struct HksBlob *agreedKey); 182 183 /** 184 * @brief Derive key 185 * @param paramSet required parameter set 186 * @param mainKey main key to derive key 187 * @param derivedKey derived key 188 * @return error code, see hks_type.h 189 */ 190 HKS_API_EXPORT int32_t HksDeriveKey(const struct HksParamSet *paramSet, const struct HksBlob *mainKey, 191 struct HksBlob *derivedKey); 192 193 /** 194 * @brief Mac operation 195 * @param key main key to derive key 196 * @param paramSet required parameter set 197 * @param srcData data needs to mac 198 * @param mac mac value 199 * @return error code, see hks_type.h 200 */ 201 HKS_API_EXPORT int32_t HksMac(const struct HksBlob *key, const struct HksParamSet *paramSet, 202 const struct HksBlob *srcData, struct HksBlob *mac); 203 204 /** 205 * @brief Hash operation 206 * @param paramSet required parameter set 207 * @param srcData data needs to hash 208 * @param mac hash value 209 * @return error code, see hks_type.h 210 */ 211 HKS_API_EXPORT int32_t HksHash(const struct HksParamSet *paramSet, 212 const struct HksBlob *srcData, struct HksBlob *hash); 213 214 /** 215 * @brief Get key info list 216 * @param paramSet required parameter set 217 * @param keyInfoList key info list 218 * @param listCount list count 219 * @return error code, see hks_type.h 220 */ 221 HKS_API_EXPORT int32_t HksGetKeyInfoList(const struct HksParamSet *paramSet, 222 struct HksKeyInfo *keyInfoList, uint32_t *listCount); 223 224 /** 225 * @brief Attest key 226 * @param keyAlias key alias 227 * @param paramSet required parameter set 228 * @param certChain cert chain 229 * @return error code, see hks_type.h 230 */ 231 HKS_API_EXPORT int32_t HksAttestKey(const struct HksBlob *keyAlias, 232 const struct HksParamSet *paramSet, struct HksCertChain *certChain); 233 234 /** 235 * @brief Get certificate chain 236 * @param keyAlias key alias 237 * @param paramSet required parameter set 238 * @param certChain cert chain 239 * @return error code, see hks_type.h 240 */ 241 HKS_API_EXPORT int32_t HksGetCertificateChain(const struct HksBlob *keyAlias, 242 const struct HksParamSet *paramSet, struct HksCertChain *certChain); 243 244 /** 245 * @brief Wrap key operation 246 * @param keyAlias key alias 247 * @param targetKeyAlias target key alias 248 * @param paramSet required parameter set 249 * @param wrappedData wrapped data 250 * @return error code, see hks_type.h 251 */ 252 HKS_API_EXPORT int32_t HksWrapKey(const struct HksBlob *keyAlias, const struct HksBlob *targetKeyAlias, 253 const struct HksParamSet *paramSet, struct HksBlob *wrappedData); 254 255 /** 256 * @brief Unwrap key operation 257 * @param keyAlias key alias 258 * @param targetKeyAlias target key alias 259 * @param wrappedData wrapped data 260 * @param paramSet required parameter set 261 * @return error code, see hks_type.h 262 */ 263 HKS_API_EXPORT int32_t HksUnwrapKey(const struct HksBlob *keyAlias, const struct HksBlob *targetKeyAlias, 264 const struct HksBlob *wrappedData, const struct HksParamSet *paramSet); 265 266 /** 267 * @brief Big-numble exponent mod x = a^e mod n 268 * @param x result 269 * @param a base 270 * @param e exponent 271 * @param n modulus 272 * @return error code, see hks_type.h 273 */ 274 HKS_API_EXPORT int32_t HksBnExpMod(struct HksBlob *x, const struct HksBlob *a, 275 const struct HksBlob *e, const struct HksBlob *n); 276 277 /** 278 * @brief Check whether the device key exists 279 * @param paramSet required parameter set 280 * @return error code, see hks_type.h 281 */ 282 HKS_API_EXPORT int32_t HcmIsDeviceKeyExist(const struct HksParamSet *paramSet); 283 284 /** 285 * @brief Validate certificate chain 286 * @param certChain certificate chain needs to validate 287 * @param paramSetOut parameter set out 288 * @return error code, see hks_type.h 289 */ 290 HKS_API_EXPORT int32_t HksValidateCertChain(const struct HksCertChain *certChain, struct HksParamSet *paramSetOut); 291 292 /** 293 * @brief Init operation 294 * @param keyAlias key alias 295 * @param paramSet required parameter set 296 * @param handle operation handle 297 * @param token token 298 * @return error code, see hks_type.h 299 */ 300 HKS_API_EXPORT int32_t HksInit(const struct HksBlob *keyAlias, const struct HksParamSet *paramSet, 301 struct HksBlob *handle, struct HksBlob *token); 302 303 /** 304 * @brief Update operation 305 * @param handle operation handle 306 * @param paramSet required parameter set 307 * @param inData the data to update 308 * @param outData output data 309 * @return error code, see hks_type.h 310 */ 311 HKS_API_EXPORT int32_t HksUpdate(const struct HksBlob *handle, const struct HksParamSet *paramSet, 312 const struct HksBlob *inData, struct HksBlob *outData); 313 314 /** 315 * @brief Finish operation 316 * @param handle operation handle 317 * @param paramSet required parameter set 318 * @param inData the data to update 319 * @param outData output data 320 * @return error code, see hks_type.h 321 */ 322 HKS_API_EXPORT int32_t HksFinish(const struct HksBlob *handle, const struct HksParamSet *paramSet, 323 const struct HksBlob *inData, struct HksBlob *outData); 324 325 /** 326 * @brief Abort operation 327 * @param handle operation handle 328 * @param paramSet required parameter set 329 * @return error code, see hks_type.h 330 */ 331 HKS_API_EXPORT int32_t HksAbort(const struct HksBlob *handle, const struct HksParamSet *paramSet); 332 333 /** 334 * @brief Export chipset platform publicKey 335 * @param salt salt value 336 * @param scene scene 337 * @param publicKey public key 338 * @return error code, see hks_type.h 339 */ 340 HKS_API_EXPORT int32_t HksExportChipsetPlatformPublicKey(const struct HksBlob *salt, 341 enum HksChipsetPlatformDecryptScene scene, struct HksBlob *publicKey); 342 343 #ifdef __cplusplus 344 } 345 #endif 346 347 #endif /* HKS_API_H */ 348