1 /* 2 * Copyright (c) 2025 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 * @addtogroup TeeTrusted 18 * @{ 19 * 20 * @brief TEE(Trusted Excution Environment) API. 21 * Provides security capability APIs such as trusted storage, encryption and decryption, 22 * and trusted time for trusted application development. 23 * 24 * @since 20 25 */ 26 27 /** 28 * @file tee_hw_ext_api.h 29 * 30 * @brief Provides extended interfaces. 31 * 32 * @library NA 33 * @kit TEEKit 34 * @syscap SystemCapability.Tee.TeeClient 35 * @since 20 36 */ 37 38 #ifndef TEE_HW_EXT_API_H 39 #define TEE_HW_EXT_API_H 40 41 #include "tee_defines.h" 42 #include "tee_crypto_api.h" 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * @brief Obtains the unique device ID from the TEE. 50 * 51 * @param device_unique_id Indicates the pointer to the buffer for storing the device ID. 52 * @param length Indicates the pointer to the buffer length. 53 * 54 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 55 * @return Returns other information otherwise. 56 * 57 * @since 20 58 */ 59 TEE_Result tee_ext_get_device_unique_id(uint8_t *device_unique_id, uint32_t *length); 60 61 /** 62 * @brief Defines the memory information. 63 * 64 * @since 20 65 */ 66 struct meminfo_t { 67 /** Pointer to the memory buffer. */ 68 uint64_t buffer; 69 /** The size of the memory. */ 70 uint32_t size; 71 }; 72 73 /** 74 * @brief Derive key from device rootkey and UUID of the current task for iteration. 75 * 76 * @param salt [IN] Indicates the data for salt. 77 * @param key [OUT] Indicates the pointer where key is saved. 78 * @param outer_iter_num [IN] Indicates the iteration times in huk service. 79 * @param inner_iter_num [IN] Indicates the iteration times in platform driver. 80 * 81 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 82 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect. 83 * Returns {@code TEE_ERROR_GENERIC} if the processing failed. 84 * 85 * @since 20 86 */ 87 TEE_Result tee_ext_derive_key_iter(const struct meminfo_t *salt, struct meminfo_t *key, 88 uint32_t outer_iter_num, uint32_t inner_iter_num); 89 90 /** 91 * @brief Derive key from device rootkey and UUID of the current task for iteration by huk2 encryption. 92 * 93 * @param salt [IN] Indicates the data for salt. 94 * @param key [OUT] Indicates the pointer where key is saved. 95 * @param outer_iter_num [IN] Indicates the iteration times in huk service. 96 * @param inner_iter_num [IN] Indicates the iteration times in platform driver. 97 * 98 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 99 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect. 100 * Returns {@code TEE_ERROR_GENERIC} if the processing failed. 101 * 102 * @since 20 103 */ 104 TEE_Result tee_ext_derive_key_iter_by_huk2(const struct meminfo_t *salt, struct meminfo_t *key, 105 uint32_t outer_iter_num, uint32_t inner_iter_num); 106 107 /** 108 * @brief Derive key from device root key by HUK2. 109 * @attention If the device does not support HUK2, the key is derived by HUK. 110 * 111 * @param salt [IN] Indicates the data for salt. 112 * @param size [IN] Indicates the length of salt. 113 * @param key [OUT] Indicates the pointer where key is saved. 114 * @param key_size [IN] Indicates the size of the key, which must be integer times of 16. 115 * 116 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 117 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect. 118 * Returns {@code TEE_ERROR_GENERIC} if the processing failed. 119 * 120 * @since 20 121 */ 122 TEE_Result tee_ext_derive_ta_root_key_by_huk2(const uint8_t *salt, uint32_t size, uint8_t *key, uint32_t key_size); 123 124 /** 125 * @brief derive key from device rootkey and UUID of the current task for iteration using huk2 enhance 126 * 127 * @param salt [IN] data for salt 128 * @param key [OUT] pointer where key is saved 129 * @param outer_iter_num [IN] iteration times in huk service 130 * @param inner_iter_num [IN] iteration times in platdrv 131 * 132 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 133 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is illegal. 134 * Returns {@code TEE_ERROR_GENERIC} if the processing failed. 135 * 136 * @since 20 137 */ 138 TEE_Result tee_ext_derive_key_iter_by_huk2_enhance(const struct meminfo_t *salt, struct meminfo_t *key, 139 uint32_t outer_iter_num, uint32_t inner_iter_num); 140 141 #ifdef __cplusplus 142 } 143 #endif 144 145 #endif 146 /** @} */