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
43extern "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 */
87typedef 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 */
98typedef 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 */
138struct 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 */
201struct 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 */
224TEE_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 */
241TEE_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 */
258TEE_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 */
275TEE_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 */
291TEE_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