1/* 2 * Copyright (c) 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#ifndef RPMB_RPMB_FCNTL_H 17#define RPMB_RPMB_FCNTL_H 18/** 19 * @addtogroup TeeTrusted 20 * @{ 21 * 22 * @brief TEE(Trusted Excution Environment) API. 23 * Provides security capability APIs such as trusted storage, encryption and decryption, 24 * and trusted time for trusted application development. 25 * 26 * @since 12 27 */ 28 29/** 30 * @file rpmb_fcntl.h 31 * 32 * @brief Provides the APIs related to RPMB service. 33 * 34 * @library NA 35 * @kit TEEKit 36 * @syscap SystemCapability.Tee.TeeClient 37 * @since 12 38 * @version 1.0 39 */ 40 41#ifdef __cplusplus 42extern "C" { 43#endif 44 45/** 46 * @brief Partition initialization, perform RPMB Key writing and formatting operations. 47 * 48 * @attention This function only needs to be executed once. 49 * 50 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 51 * Returns {@code TEE_ERROR_RPMB_GENERIC} if the RPMB controller general error. 52 * Returns {@code TEE_ERROR_RPMB_MAC_FAIL} if the RPMB controller MAC check error. 53 * Returns {@code TEE_ERROR_RPMB_RESP_UNEXPECT_MAC} if the RPMB response data MAC check error. 54 * 55 * @since 12 56 * @version 1.0 57 */ 58TEE_Result TEE_RPMB_FS_Init(void); 59 60/** 61 * @brief RPMB secure storage fully formatted operation. 62 * 63 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 64 * Returns {@code TEE_ERROR_RPMB_GENERIC} if the RPMB controller general error. 65 * Returns {@code TEE_ERROR_RPMB_MAC_FAIL} if the RPMB controller MAC check error. 66 * Returns {@code TEE_ERROR_RPMB_RESP_UNEXPECT_MAC} if the RPMB response data MAC check error. 67 * 68 * @since 12 69 * @version 1.0 70 */ 71TEE_Result TEE_RPMB_FS_Format(void); 72 73/** 74 * @brief Write files to RPMB. 75 * 76 * @attention If you want to improve the performance of writing files, you need to define the heap size in TA's 77 * manifest to be at leaset 3 times the file size plus 256KB. 78 * For example: To write a file with a size of 100KB, the defined heap size is at least 79 * 556KB (3 * 100 + 256). If the heap size cannot be satisfied, the file writing will still succeed, 80 * but the performance will be poor. 81 * 82 * @param filename Indicates the file name of the data to be written, the maximum length is 64 bytes. 83 * @param buf Indicates the buffer for writting data. 84 * @param size Indicates the size of the written data, the maximum size is 160KB. 85 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 86 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect, or the file name is longer than 64 87 * bytes. 88 * Returns {@code TEE_ERROR_RPMB_NOSPC} if the RPMB partition has insufficient disk space. 89 * 90 * @since 12 91 * @version 1.0 92 */ 93TEE_Result TEE_RPMB_FS_Write(const char *filename, const uint8_t *buf, size_t size); 94 95/** 96 * @brief Read files from RPMB. 97 * 98 * @attention If you want to improve the performance of reading files, you need to define the heap size in TA's 99 * manifest to be at leaset 3 times the file size plus 256KB. 100 * For example: To read a file with a size of 100KB, the defined heap size is at least 101 * 556KB (3 * 100 + 256). If the heap size cannot be satisfied, the file reading will still succeed, 102 * but the performance will be poor. 103 * 104 * @param filename Indicates the file name of the data to be read, the maximum length is 64 bytes. 105 * @param buf Indicates the buffer for reading data. 106 * @param size Indicates the read data size. 107 * @param count Indicates the size of the actual read. 108 * 109 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 110 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect, or the file name is longer than 64 111 * bytes. 112 * Returns {@code TEE_ERROR_RPMB_FILE_NOT_FOUND} if the file dose not exist. 113 * 114 * @since 12 115 * @version 1.0 116 */ 117TEE_Result TEE_RPMB_FS_Read(const char *filename, uint8_t *buf, size_t size, uint32_t *count); 118 119/** 120 * @brief Rename file name in RPMB. 121 * 122 * @param old_name Indicates the old file name. 123 * @param new_name Indicates the new file name. 124 * 125 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 126 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect, or the file name is longer than 64 127 * bytes. 128 * Returns {@code TEE_ERROR_RPMB_FILE_NOT_FOUND} if the file dose not exist. 129 * 130 * @since 12 131 * @version 1.0 132 */ 133TEE_Result TEE_RPMB_FS_Rename(const char *old_name, const char *new_name); 134 135/** 136 * @brief Delete files in RPMB. 137 * 138 * @param filename Indicates the file name to be deleted. 139 * 140 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 141 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect, or the file name is longer than 64 142 * bytes. 143 * Returns {@code TEE_ERROR_RPMB_FILE_NOT_FOUND} if the file dose not exist. 144 * 145 * @since 12 146 * @version 1.0 147 */ 148TEE_Result TEE_RPMB_FS_Rm(const char *filename); 149 150/** 151 * @brief File status stored in RPMB partition, used in {@code TEE_RPMB_FS_Stat}. 152 * 153 * @since 12 154 */ 155struct rpmb_fs_stat { 156 /** Indicates the file size. */ 157 uint32_t size; 158 uint32_t reserved; 159}; 160 161/** 162 * @brief Get file status in RPMB. 163 * 164 * @param filename Indicates the file name in RPMB. 165 * @param stat Indicates the file status information obtained. 166 * 167 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 168 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect, or the file name is longer than 64 169 * bytes. 170 * Returns {@code TEE_ERROR_RPMB_FILE_NOT_FOUND} if the file dose not exist. 171 * 172 * @since 12 173 * @version 1.0 174 */ 175TEE_Result TEE_RPMB_FS_Stat(const char *filename, struct rpmb_fs_stat *stat); 176 177/** 178 * @brief Disk status stored in RPMB partition, used in {@code TEE_RPMB_FS_StatDisk}. 179 * 180 * @since 12 181 */ 182struct rpmb_fs_statdisk { 183 /** Indicates the total size of RPMB partition. */ 184 uint32_t disk_size; 185 /** Indicates the TA used size. */ 186 uint32_t ta_used_size; 187 /** Indicates the free size of the RPMB partition. */ 188 uint32_t free_size; 189 uint32_t reserved; 190}; 191 192/** 193 * @brief Get the disk status. 194 * 195 * @param stat Indicates the disk status information obtained. 196 * 197 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 198 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect. 199 * 200 * @since 12 201 * @version 1.0 202 */ 203TEE_Result TEE_RPMB_FS_StatDisk(struct rpmb_fs_statdisk *stat); 204 205/** 206 * @brief File attribute definition, which means that the file cannot be erased during the factory reset. 207 * 208 * @since 12 209*/ 210#define TEE_RPMB_FMODE_NON_ERASURE (1U << 0) 211 212/** 213 * @brief File attribute definition, which means the attribute value of the cleard file. 214 * 215 * @since 12 216*/ 217#define TEE_RPMB_FMODE_CLEAR 0 218 219 220/** 221 * @brief Set the file attribute in RPMB. 222 * 223 * @param filename Indicates the file name in RPMB. 224 * @param fmode Indicates the file attribute, currently supports {@code TEE_RPMB_FMODE_NON_ERASURE} and 225 * {@code TEE_RPMB_FMODE_CLEAR} two attributes, other values will return {@code TEE_ERROR_BAD_PARAMETERS}. 226 * 227 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 228 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect, 229 * or the file name is longer than 64 bytes. 230 * Returns {@code TEE_ERROR_RPMB_FILE_NOT_FOUND} if the file dose not exist. 231 * 232 * @since 12 233 * @version 1.0 234 */ 235TEE_Result TEE_RPMB_FS_SetAttr(const char *filename, uint32_t fmode); 236 237/** 238 * @brief Format, delete file attribute is erasable file, keep the file attribute is an inerasable file. 239 * 240 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 241 * Returns {@code TEE_ERROR_RPMB_GENERIC} if the RPMB controller general error. 242 * Returns {@code TEE_ERROR_RPMB_MAC_FAIL} if the RPMB controller MAC check error. 243 * Returns {@code TEE_ERROR_RPMB_RESP_UNEXPECT_MAC} if the RPMB response data MAC check error. 244 * 245 * @since 12 246 * @version 1.0 247 */ 248TEE_Result TEE_RPMB_FS_Erase(void); 249 250/** 251 * @brief Enumerates the types of RPMB key status, used in {@code TEE_RPMB_KEY_Status}. 252 * 253 * @since 12 254*/ 255enum TEE_RPMB_KEY_STAT { 256 /** RPMB Key status is invalid. */ 257 TEE_RPMB_KEY_INVALID = 0x0, 258 /** RPMB Key has been programmed and matched correctly. */ 259 TEE_RPMB_KEY_SUCCESS, 260 /** RPMB Key is not programmed. */ 261 TEE_RPMB_KEY_NOT_PROGRAM, 262 /** RPMB Key has been programmed but failed to match. */ 263 TEE_RPMB_KEY_NOT_MATCH, 264}; 265 266/** 267 * @brief Obtain RPMB Key status. 268 * 269 * @return Returns {@code TEE_RPMB_KEY_SUCCESS} if the RPMB Key has been programmed and matched correctly. 270 * Returns {@code TEE_RPMB_KEY_NOT_PROGRAM} if the RPMB Key is not programmed. 271 * Returns {@code TEE_RPMB_KEY_NOT_MATCH} if RPMB Key has been programmed but failed to match. 272 * Returns {@code TEE_RPMB_KEY_INVALID} if the RPMB Key status is invalid. 273 * 274 * @since 12 275 * @version 1.0 276 */ 277uint32_t TEE_RPMB_KEY_Status(void); 278 279/** 280 * @brief Process the current TA version information. 281 * 282 * @param ta_version Indicates the TA version. 283 * 284 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 285 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect. 286 * Returns {@code TEE_ERROR_GENERIC} if the processing failed. 287 * 288 * @since 12 289 * @version 1.0 290 */ 291TEE_Result TEE_RPMB_TAVERSION_Process(uint32_t ta_version); 292#ifdef __cplusplus 293} 294#endif 295 296/** @} */ 297#endif 298