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