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