1 /* 2 * Copyright (C) 2022 Huawei Technologies Co., Ltd. 3 * Licensed under the Mulan PSL v2. 4 * You can use this software according to the terms and conditions of the Mulan PSL v2. 5 * You may obtain a copy of Mulan PSL v2 at: 6 * http://license.coscl.org.cn/MulanPSL2 7 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR 8 * IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY OR FIT FOR A PARTICULAR 9 * PURPOSE. 10 * See the Mulan PSL v2 for more details. 11 */ 12 13 #ifndef TEE_HW_EXT_API_H 14 #define TEE_HW_EXT_API_H 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 12 25 */ 26 27 /** 28 * @file tee_hw_ext_api.h 29 * 30 * @brief Provides extended interfaces. 31 * 32 * @library NA 33 * @kit TEE Kit 34 * @syscap SystemCapability.Tee.TeeClient 35 * @since 12 36 * @version 1.0 37 */ 38 39 #include "tee_defines.h" 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @brief Obtains the unique device ID from the TEE. 47 * 48 * @param device_unique_id Indicates the pointer to the buffer for storing the device ID. 49 * @param length Indicates the pointer to the buffer length. 50 * 51 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 52 * @return Returns other information otherwise. 53 * 54 * @since 20 55 */ 56 TEE_Result tee_ext_get_device_unique_id(uint8_t *device_unique_id, uint32_t *length); 57 58 /** 59 * @brief Defines the memory information. 60 * 61 * @since 20 62 */ 63 struct meminfo_t { 64 /** Pointer to the memory buffer. */ 65 uint64_t buffer; 66 /** The size of the memory. */ 67 uint32_t size; 68 }; 69 70 /** 71 * @brief Derive key from device rootkey and UUID of the current task for iteration. 72 * 73 * @param salt [IN] Indicates the data for salt. 74 * @param key [OUT] Indicates the pointer where key is saved. 75 * @param outer_iter_num [IN] Indicates the iteration times in huk service. 76 * @param inner_iter_num [IN] Indicates the iteration times in platform driver. 77 * 78 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 79 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect. 80 * Returns {@code TEE_ERROR_GENERIC} if the processing failed. 81 * 82 * @since 20 83 */ 84 TEE_Result tee_ext_derive_key_iter(const struct meminfo_t *salt, struct meminfo_t *key, 85 uint32_t outer_iter_num, uint32_t inner_iter_num); 86 87 /** 88 * @brief Derive key from device rootkey and UUID of the current task for iteration by huk2 encryption. 89 * 90 * @param salt [IN] Indicates the data for salt. 91 * @param key [OUT] Indicates the pointer where key is saved. 92 * @param outer_iter_num [IN] Indicates the iteration times in huk service. 93 * @param inner_iter_num [IN] Indicates the iteration times in platform driver. 94 * 95 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 96 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect. 97 * Returns {@code TEE_ERROR_GENERIC} if the processing failed. 98 * 99 * @since 20 100 */ 101 TEE_Result tee_ext_derive_key_iter_by_huk2(const struct meminfo_t *salt, struct meminfo_t *key, 102 uint32_t outer_iter_num, uint32_t inner_iter_num); 103 104 /** 105 * @brief Derive key from device root key by HUK2. 106 * @attention If the device does not support HUK2, the key is derived by HUK. 107 * 108 * @param salt [IN] Indicates the data for salt. 109 * @param size [IN] Indicates the length of salt. 110 * @param key [OUT] Indicates the pointer where key is saved. 111 * @param key_size [IN] Indicates the size of the key, which must be integer times of 16. 112 * 113 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 114 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect. 115 * Returns {@code TEE_ERROR_GENERIC} if the processing failed. 116 * 117 * @since 20 118 * @version 1.0 119 */ 120 TEE_Result tee_ext_derive_ta_root_key_by_huk2(const uint8_t *salt, uint32_t size, uint8_t *key, uint32_t key_size); 121 122 /** 123 * @brief derive key from device rootkey and UUID of the current task for iteration using huk2 enhance 124 * 125 * @param salt [IN] data for salt 126 * @param key [OUT] pointer where key is saved 127 * @param outer_iter_num [IN] iteration times in huk service 128 * @param inner_iter_num [IN] iteration times in platdrv 129 * 130 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 131 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is illegal. 132 * Returns {@code TEE_ERROR_GENERIC} if the processing failed. 133 * 134 * @since 20 135 * @version 1.0 136 */ 137 TEE_Result tee_ext_derive_key_iter_by_huk2_enhance(const struct meminfo_t *salt, struct meminfo_t *key, 138 uint32_t outer_iter_num, uint32_t inner_iter_num); 139 140 #ifdef __cplusplus 141 } 142 #endif 143 /** @} */ 144 #endif