1 /*
2  * Copyright (c) 2021-2024 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 Anonymous Attest key
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 HksAnonAttestKey(const struct HksBlob *keyAlias,
242     const struct HksParamSet *paramSet, struct HksCertChain *certChain);
243 
244 /**
245  * @brief Get certificate chain
246  * @param keyAlias key alias
247  * @param paramSet required parameter set
248  * @param certChain cert chain
249  * @return error code, see hks_type.h
250  */
251 HKS_API_EXPORT int32_t HksGetCertificateChain(const struct HksBlob *keyAlias,
252     const struct HksParamSet *paramSet, struct HksCertChain *certChain);
253 
254 /**
255  * @brief Wrap key operation
256  * @param keyAlias key alias
257  * @param targetKeyAlias target key alias
258  * @param paramSet required parameter set
259  * @param wrappedData wrapped data
260  * @return error code, see hks_type.h
261  */
262 HKS_API_EXPORT int32_t HksWrapKey(const struct HksBlob *keyAlias, const struct HksBlob *targetKeyAlias,
263     const struct HksParamSet *paramSet, struct HksBlob *wrappedData);
264 
265 /**
266  * @brief Unwrap key operation
267  * @param keyAlias key alias
268  * @param targetKeyAlias target key alias
269  * @param wrappedData wrapped data
270  * @param paramSet required parameter set
271  * @return error code, see hks_type.h
272  */
273 HKS_API_EXPORT int32_t HksUnwrapKey(const struct HksBlob *keyAlias, const struct HksBlob *targetKeyAlias,
274     const struct HksBlob *wrappedData, const struct HksParamSet *paramSet);
275 
276 /**
277  * @brief Big-numble exponent mod x = a^e mod n
278  * @param x result
279  * @param a base
280  * @param e exponent
281  * @param n modulus
282  * @return error code, see hks_type.h
283  */
284 HKS_API_EXPORT int32_t HksBnExpMod(struct HksBlob *x, const struct HksBlob *a,
285     const struct HksBlob *e, const struct HksBlob *n);
286 
287 /**
288  * @brief Check whether the device key exists
289  * @param paramSet required parameter set
290  * @return error code, see hks_type.h
291  */
292 HKS_API_EXPORT int32_t HcmIsDeviceKeyExist(const struct HksParamSet *paramSet);
293 
294 /**
295  * @brief Validate certificate chain
296  * @param certChain certificate chain needs to validate
297  * @param paramSetOut parameter set out
298  * @return error code, see hks_type.h
299  */
300 HKS_API_EXPORT int32_t HksValidateCertChain(const struct HksCertChain *certChain, struct HksParamSet *paramSetOut);
301 
302 /**
303  * @brief Init operation
304  * @param keyAlias key alias
305  * @param paramSet required parameter set
306  * @param handle operation handle
307  * @param token token
308  * @return error code, see hks_type.h
309  */
310 HKS_API_EXPORT int32_t HksInit(const struct HksBlob *keyAlias, const struct HksParamSet *paramSet,
311     struct HksBlob *handle, struct HksBlob *token);
312 
313 /**
314  * @brief Update operation
315  * @param handle operation handle
316  * @param paramSet required parameter set
317  * @param inData the data to update
318  * @param outData output data
319  * @return error code, see hks_type.h
320  */
321 HKS_API_EXPORT int32_t HksUpdate(const struct HksBlob *handle, const struct HksParamSet *paramSet,
322     const struct HksBlob *inData, struct HksBlob *outData);
323 
324 /**
325  * @brief Finish operation
326  * @param handle operation handle
327  * @param paramSet required parameter set
328  * @param inData the data to update
329  * @param outData output data
330  * @return error code, see hks_type.h
331  */
332 HKS_API_EXPORT int32_t HksFinish(const struct HksBlob *handle, const struct HksParamSet *paramSet,
333     const struct HksBlob *inData, struct HksBlob *outData);
334 
335 /**
336  * @brief Abort operation
337  * @param handle operation handle
338  * @param paramSet required parameter set
339  * @return error code, see hks_type.h
340  */
341 HKS_API_EXPORT int32_t HksAbort(const struct HksBlob *handle, const struct HksParamSet *paramSet);
342 
343 /**
344  * @brief Export chipset platform publicKey
345  * @param salt salt value
346  * @param scene scene
347  * @param publicKey public key
348  * @return error code, see hks_type.h
349  */
350 HKS_API_EXPORT int32_t HksExportChipsetPlatformPublicKey(const struct HksBlob *salt,
351     enum HksChipsetPlatformDecryptScene scene, struct HksBlob *publicKey);
352 
353 /**
354  * @brief Get key alias list
355  * @param paramSet required parameter set
356  * @param outData key alias list
357  * @return error code, see hks_type.h
358  */
359 HKS_API_EXPORT int32_t HksListAliases(const struct HksParamSet *paramSet, struct HksKeyAliasSet **outData);
360 
361 /**
362  * @brief Rename key alias
363  * @param oldKeyAlias the old key alias
364  * @param paramSet required parameter set
365  * @param newKeyAlias the new key alias
366  * @return error code, see hks_type.h
367  */
368 HKS_API_EXPORT int32_t HksRenameKeyAlias(const struct HksBlob *oldKeyAlias, const struct HksParamSet *paramSet,
369     const struct HksBlob *newKeyAlias);
370 
371 /**
372  * @brief Change key storage level
373  * @param keyAlias key alias
374  * @param srcParamSet required source parameter set
375  * @param destParamSet required destination parameter set
376  * @return error code, see hks_type.h
377  */
378 HKS_API_EXPORT int32_t HksChangeStorageLevel(const struct HksBlob *keyAlias, const struct HksParamSet *srcParamSet,
379     const struct HksParamSet *destParamSet);
380 
381 #ifdef __cplusplus
382 }
383 #endif
384 
385 #endif /* HKS_API_H */
386