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