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