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_driver_rw_api.h 29 * 30 * @brief APIs related to RPMB driver read and write. 31 * Provides the function of reading and writing RPMB driver. 32 * 33 * @library NA 34 * @kit TEEKit 35 * @syscap SystemCapability.Tee.TeeClient 36 * @since 20 37 */ 38 39 #ifndef RPMB_DRIVER_RW_API_H 40 #define RPMB_DRIVER_RW_API_H 41 42 #include <stdint.h> 43 #include <tee_defines.h> 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @brief Defines the total block number. 51 * 52 * @since 20 53 */ 54 #define TOTAL_BLK 4 55 56 /** 57 * @brief Defines the size of block. 58 * 59 * @since 20 60 */ 61 #define BLK_SIZE 256 62 63 /** 64 * @brief Defines the size of the total block. 65 * 66 * @since 20 67 */ 68 #define TOTAL_BLK_SIZE (TOTAL_BLK * BLK_SIZE) 69 70 /** 71 * @brief Defines the number of security write protection entries. 72 * 73 * @since 20 74 */ 75 #define SEC_WRITE_PROTECT_ENTRY_NUM 4 76 77 /** 78 * @brief Defines the number of reserved security write protection entries. 79 * 80 * @since 20 81 */ 82 #define SEC_WRITE_PROTECT_ENTRY_RESERVED_NUM 3 83 84 /** 85 * @brief Defines the reserved size of security write protection entries. 86 * 87 * @since 20 88 */ 89 #define SEC_WRITE_PROTECT_ENTRY_RESERVED_SIZE 16 90 91 /** 92 * @brief Defines the number of reserved security write protection frames. 93 * 94 * @since 20 95 */ 96 #define SEC_WRITE_PROTECT_FRAME_RESERVED_NUM 14 97 98 /** 99 * @brief Defines the number of reserved end security write protection frames. 100 * 101 * @since 20 102 */ 103 #define SEC_WRITE_PROTECT_FRAME_RESERVED_END_NUM 176 104 105 /** 106 * @brief Defines the size of the security write protection block. 107 * 108 * @since 20 109 */ 110 #define SEC_WRITE_PROTECT_BLK_SIZE 256 111 112 /** 113 * @brief Defines the maximum number of security write protection LUNs. 114 * 115 * @since 20 116 */ 117 #define SEC_WRITE_PROTECT_LUN_MAX 5 118 119 /** 120 * @brief A WPF set to one specifies that the logical unit shall inhibit alteration of the medium for LBA within 121 * the range indicated by LOGICAL BLOCK ADDRESS field and NUMBER OF LOGICAL BLOCKS field. 122 * Commands requiring writes to the medium shall be terminated with CHECK CONDITION status, 123 * with the sense key set to DATA PROTECT, and the additional sense code set to WRITE PROTECTED. 124 * 125 * @since 20 126 */ 127 typedef enum { 128 /** Disables the write protection. */ 129 SEC_WRITE_PROTECT_DISABLE = 0, 130 /** Enables the write protection. */ 131 SEC_WRITE_PROTECT_ENABLE = 1, 132 } write_protect_flag; 133 134 /** 135 * @brief Write Protect Type specifies how WPF bit may be modified. 136 * 137 * @since 20 138 */ 139 typedef enum { 140 /** WPF bit is persistent through power cycle and hardware reset. 141 * WPF value may only be changed writing to Secure Write Protect Configuration Block. 142 */ 143 NV_TYPE = 0, 144 /** WPF bit is automatically cleared to 0b after power cycle or hardware reset. */ 145 P_TYPE = 1, 146 /** WPF bit is automatically set to 1b after power cycle or hardware reset. */ 147 NV_AWP_TYPE = 2, 148 } write_protect_type; 149 150 /** 151 * @brief Secure Write Protect Entry. 152 * +-----+---+---+---+---+---+---+---+----+ 153 * | | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 154 * +-----+---+---+---+---+---+---+---+----+ 155 * | 0 | Reserved | WFT | WPF| -> wp_data 156 * +-----+---+---+---+---+---+---+---+----+ 157 * | 1 | Reserved | 158 * +-----+---+---+---+---+---+---+---+----+ 159 * | 2 | Reserved | 160 * +-----+---+---+---+---+---+---+---+----+ 161 * | 3 | Reserved | 162 * +-----+---+---+---+---+---+---+---+----+ 163 * | 4 | LOGICAL BLOCK ADDRESS | -> logical_blk_addr 164 * +-----+ + 165 * | ... | | 166 * +-----+ + 167 * | 11 | | 168 * +-----+ + 169 * | 20 | | 170 * +-----+---+---+---+---+---+---+---+----+ 171 * | ... | NUMBER OF LOGICAL BLOCKS | -> logical_blk_num 172 * +-----+---+---+---+---+---+---+---+----+ 173 * | 15 | | 174 * +-----+---+---+---+---+---+---+---+----+ 175 * 176 * @since 20 177 */ 178 struct rpmb_protect_cfg_blk_entry { 179 /** This field specifies the write protect data. */ 180 uint8_t wp_data; 181 /** Reserved bytes for padding. */ 182 uint8_t reserved[SEC_WRITE_PROTECT_ENTRY_RESERVED_NUM]; 183 /** This field specifies the LBA of the first logical address of the Secure Write Protect ares. */ 184 uint64_t logical_blk_addr; 185 /** This field specifies the number of contiguous logical size that belong to the Secure Write Protect. */ 186 uint32_t logical_blk_num; 187 }__attribute__((packed)); 188 189 190 /** 191 * @brief Secure Write Protect Configuration Block is supported by RPMB region 0 only. 192 * This block is used for configuring secure write protect areas in logical units. 193 * Each Secure Write Protect Configuration Block for each logical unit. 194 * Each entry represents one secure write protect area. 195 * If an entry is not used, then the related fields shall contain a value of zero. 196 * +-----+---+---+---+---+---+---+---+----+ 197 * | | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 198 * +-----+---+---+---+---+---+---+---+----+ 199 * | 0 | LUN | 200 * +-----+---+---+---+---+---+---+---+----+ 201 * | 1 | DATA LENGTH | 202 * +-----+---+---+---+---+---+---+---+----+ 203 * | 2 | | 204 * +-----+ + 205 * | ... | Reserved | 206 * +-----+ + 207 * | 15 | | 208 * +-----+---+---+---+---+---+---+---+----+ 209 * | 16 | | 210 * +-----+ + 211 * | ... | Secure Write Protect Entry 0 | 212 * +-----+ + 213 * | 31 | | 214 * +-----+---+---+---+---+---+---+---+----+ 215 * | 32 | | 216 * +-----+ + 217 * | ... | Secure Write Protect Entry 1 | 218 * +-----+ + 219 * | 47 | | 220 * +-----+---+---+---+---+---+---+---+----+ 221 * | 48 | | 222 * +-----+ + 223 * | ... | Secure Write Protect Entry 1 | 224 * +-----+ + 225 * | 63 | | 226 * +-----+---+---+---+---+---+---+---+----+ 227 * | 64 | | 228 * +-----+ + 229 * | ... | Secure Write Protect Entry 1 | 230 * +-----+ + 231 * | 79 | | 232 * +-----+---+---+---+---+---+---+---+----+ 233 * | 80 | | 234 * +-----+ + 235 * | ... | Reserved | 236 * +-----+ + 237 * | 255 | | 238 * +-----+---+---+---+---+---+---+---+----+ 239 * 240 * @since 20 241 */ 242 struct rpmb_protect_cfg_block { 243 /** Logical Unit Number (LUN) */ 244 uint8_t lun; 245 /** Data length for the configuration block */ 246 uint8_t data_length; 247 /** Reserved bytes for padding */ 248 uint8_t reserved[SEC_WRITE_PROTECT_FRAME_RESERVED_NUM]; 249 /** Array of Secure Write Protect entries */ 250 struct rpmb_protect_cfg_blk_entry entries[SEC_WRITE_PROTECT_ENTRY_NUM]; 251 /** Reserved bytes for padding at the end of the block */ 252 uint8_t reserved_end[SEC_WRITE_PROTECT_FRAME_RESERVED_END_NUM]; 253 }__attribute__((packed)); 254 255 /** 256 * @brief Write protect config block by RPMB driver. 257 * 258 * @param lun Indicates the logical unit to which secure write protection shall apply, 259 * and <b>0</b> <= lun <= {@code SEC_WRITE_PROTECT_LUN_MAX} 260 * @param entries Indicates the Secure Write Protect Entry array, The maximum length is 4. 261 * @param len Indicates the real length of the Secure Write Protect Entry array, which value is less than 4. 262 * 263 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 264 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if the input parameter is incorrect. 265 * Returns {@code TEE_ERROR_OUT_OF_MEMORY} if the send message fail. 266 * 267 * @since 20 268 */ 269 TEE_Result tee_ext_rpmb_protect_cfg_blk_write(uint8_t lun, struct rpmb_protect_cfg_blk_entry *entries, uint32_t len); 270 271 /** 272 * @brief Read protect config block by RPMB driver. 273 * 274 * @param lun Indicates the logical unit to which secure read protection shall apply, 275 * and 0 <= lun <= <b>SEC_WRITE_PROTECT_LUN_MAX</b>. 276 * @param entries Indicates the Secure Read Protect Entry array, The maximum length is 4. 277 * @param len Indicates the real length of the Secure Read Protect Entry array, which value is less than 4. 278 * 279 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 280 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if the input parameter is incorrect. 281 * Returns {@code TEE_ERROR_OUT_OF_MEMORY} if the send message fail. 282 * 283 * @since 20 284 */ 285 TEE_Result tee_ext_rpmb_protect_cfg_blk_read(uint8_t lun, struct rpmb_protect_cfg_blk_entry *entries, uint32_t *len); 286 287 /** 288 * @brief Write plaintext buffer to RPMB driver. 289 * 290 * @param buf Indicates the buffer for writing data. 291 * @param size Indicates the length of buffer, the maximum value is 1024. 292 * @param block Indicates the block index of the position of start block, the value is [0, 3]. 293 * @param offset Indicates the offset bytes of data position, and the value of offest bytes is less than 256. 294 * 295 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 296 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if the input parameter is incorrect. 297 * Returns {@code TEE_ERROR_OUT_OF_MEMORY} if the send message fail. 298 * 299 * @since 20 300 */ 301 TEE_Result tee_ext_rpmb_driver_write(const uint8_t *buf, size_t size, uint32_t block, uint32_t offset); 302 303 /** 304 * @brief Read plaintext buffer from RPMB driver. 305 * 306 * @param buf Indicates the buffer for read data. 307 * @param size Indicates the length of buffer, the maximum value is 1024. 308 * @param block Indicates the block index of the position of start block, the value is [0, 3]. 309 * @param offset Indicates the offset bytes of data position, and the value of offest bytes is less than 256. 310 * 311 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 312 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if the input parameter is incorrect. 313 * Returns {@code TEE_ERROR_OUT_OF_MEMORY} if the send message fail. 314 * 315 * @since 20 316 */ 317 TEE_Result tee_ext_rpmb_driver_read(uint8_t *buf, size_t size, uint32_t block, uint32_t offset); 318 319 /** 320 * @brief Remove data from RPMB driver. 321 * 322 * @param size Indicates the length of remove data, the maximum value is 1024. 323 * @param block Indicates the block index of the position of start block, the value is [0, 3]. 324 * @param offset Indicates the offset bytes of data position, and the value of offest bytes is less than 256. 325 * 326 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 327 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if the input parameter is incorrect. 328 * Returns {@code TEE_ERROR_OUT_OF_MEMORY} if the send message fail. 329 * 330 * @since 20 331 */ 332 TEE_Result tee_ext_rpmb_driver_remove(size_t size, uint32_t block, uint32_t offset); 333 334 /** 335 * @brief RPMB secure storage fully formatted operation 336 * 337 * @return TEE_SUCCESS Indicates that the function was executed successfully 338 * TEE_ERROR_RPMB_GENERIC RPMB controller general error 339 * TEE_ERROR_RPMB_MAC_FAIL RPMB controller MAC check error 340 * TEE_ERROR_RPMB_RESP_UNEXPECT_MAC RPMB response data MAC check error 341 * 342 * @since 20 343 */ 344 TEE_Result tee_ext_rpmb_format(); 345 346 #ifdef __cplusplus 347 } 348 #endif 349 350 #endif 351 /** @} */