/* * Copyright (c) 2025 Huawei Device Co., Ltd. * Licensed under the Apache License, Version 2.0 (the "License"), * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * @addtogroup TeeTrusted * @{ * * @brief TEE(Trusted Excution Environment) API. * Provides security capability APIs such as trusted storage, encryption and decryption, * and trusted time for trusted application development. * * @since 20 */ /** * @file rpmb_driver_rw_api.h * * @brief APIs related to RPMB driver read and write. * Provides the function of reading and writing RPMB driver. * * @library NA * @kit TEEKit * @syscap SystemCapability.Tee.TeeClient * @since 20 */ #ifndef RPMB_DRIVER_RW_API_H #define RPMB_DRIVER_RW_API_H #include #include #ifdef __cplusplus extern "C" { #endif /** * @brief Defines the total block number. * * @since 20 */ #define TOTAL_BLK 4 /** * @brief Defines the size of block. * * @since 20 */ #define BLK_SIZE 256 /** * @brief Defines the size of the total block. * * @since 20 */ #define TOTAL_BLK_SIZE (TOTAL_BLK * BLK_SIZE) /** * @brief Defines the number of security write protection entries. * * @since 20 */ #define SEC_WRITE_PROTECT_ENTRY_NUM 4 /** * @brief Defines the number of reserved security write protection entries. * * @since 20 */ #define SEC_WRITE_PROTECT_ENTRY_RESERVED_NUM 3 /** * @brief Defines the reserved size of security write protection entries. * * @since 20 */ #define SEC_WRITE_PROTECT_ENTRY_RESERVED_SIZE 16 /** * @brief Defines the number of reserved security write protection frames. * * @since 20 */ #define SEC_WRITE_PROTECT_FRAME_RESERVED_NUM 14 /** * @brief Defines the number of reserved end security write protection frames. * * @since 20 */ #define SEC_WRITE_PROTECT_FRAME_RESERVED_END_NUM 176 /** * @brief Defines the size of the security write protection block. * * @since 20 */ #define SEC_WRITE_PROTECT_BLK_SIZE 256 /** * @brief Defines the maximum number of security write protection LUNs. * * @since 20 */ #define SEC_WRITE_PROTECT_LUN_MAX 5 /** * @brief A WPF set to one specifies that the logical unit shall inhibit alteration of the medium for LBA within * the range indicated by LOGICAL BLOCK ADDRESS field and NUMBER OF LOGICAL BLOCKS field. * Commands requiring writes to the medium shall be terminated with CHECK CONDITION status, * with the sense key set to DATA PROTECT, and the additional sense code set to WRITE PROTECTED. * * @since 20 */ typedef enum { /** Disables the write protection. */ SEC_WRITE_PROTECT_DISABLE = 0, /** Enables the write protection. */ SEC_WRITE_PROTECT_ENABLE = 1, } write_protect_flag; /** * @brief Write Protect Type specifies how WPF bit may be modified. * * @since 20 */ typedef enum { /** WPF bit is persistent through power cycle and hardware reset. * WPF value may only be changed writing to Secure Write Protect Configuration Block. */ NV_TYPE = 0, /** WPF bit is automatically cleared to 0b after power cycle or hardware reset. */ P_TYPE = 1, /** WPF bit is automatically set to 1b after power cycle or hardware reset. */ NV_AWP_TYPE = 2, } write_protect_type; /** * @brief Secure Write Protect Entry. * +-----+---+---+---+---+---+---+---+----+ * | | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | * +-----+---+---+---+---+---+---+---+----+ * | 0 | Reserved | WFT | WPF| -> wp_data * +-----+---+---+---+---+---+---+---+----+ * | 1 | Reserved | * +-----+---+---+---+---+---+---+---+----+ * | 2 | Reserved | * +-----+---+---+---+---+---+---+---+----+ * | 3 | Reserved | * +-----+---+---+---+---+---+---+---+----+ * | 4 | LOGICAL BLOCK ADDRESS | -> logical_blk_addr * +-----+ + * | ... | | * +-----+ + * | 11 | | * +-----+ + * | 20 | | * +-----+---+---+---+---+---+---+---+----+ * | ... | NUMBER OF LOGICAL BLOCKS | -> logical_blk_num * +-----+---+---+---+---+---+---+---+----+ * | 15 | | * +-----+---+---+---+---+---+---+---+----+ * * @since 20 */ struct rpmb_protect_cfg_blk_entry { /** This field specifies the write protect data. */ uint8_t wp_data; /** Reserved bytes for padding. */ uint8_t reserved[SEC_WRITE_PROTECT_ENTRY_RESERVED_NUM]; /** This field specifies the LBA of the first logical address of the Secure Write Protect ares. */ uint64_t logical_blk_addr; /** This field specifies the number of contiguous logical size that belong to the Secure Write Protect. */ uint32_t logical_blk_num; }__attribute__((packed)); /** * @brief Secure Write Protect Configuration Block is supported by RPMB region 0 only. * This block is used for configuring secure write protect areas in logical units. * Each Secure Write Protect Configuration Block for each logical unit. * Each entry represents one secure write protect area. * If an entry is not used, then the related fields shall contain a value of zero. * +-----+---+---+---+---+---+---+---+----+ * | | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | * +-----+---+---+---+---+---+---+---+----+ * | 0 | LUN | * +-----+---+---+---+---+---+---+---+----+ * | 1 | DATA LENGTH | * +-----+---+---+---+---+---+---+---+----+ * | 2 | | * +-----+ + * | ... | Reserved | * +-----+ + * | 15 | | * +-----+---+---+---+---+---+---+---+----+ * | 16 | | * +-----+ + * | ... | Secure Write Protect Entry 0 | * +-----+ + * | 31 | | * +-----+---+---+---+---+---+---+---+----+ * | 32 | | * +-----+ + * | ... | Secure Write Protect Entry 1 | * +-----+ + * | 47 | | * +-----+---+---+---+---+---+---+---+----+ * | 48 | | * +-----+ + * | ... | Secure Write Protect Entry 1 | * +-----+ + * | 63 | | * +-----+---+---+---+---+---+---+---+----+ * | 64 | | * +-----+ + * | ... | Secure Write Protect Entry 1 | * +-----+ + * | 79 | | * +-----+---+---+---+---+---+---+---+----+ * | 80 | | * +-----+ + * | ... | Reserved | * +-----+ + * | 255 | | * +-----+---+---+---+---+---+---+---+----+ * * @since 20 */ struct rpmb_protect_cfg_block { /** Logical Unit Number (LUN) */ uint8_t lun; /** Data length for the configuration block */ uint8_t data_length; /** Reserved bytes for padding */ uint8_t reserved[SEC_WRITE_PROTECT_FRAME_RESERVED_NUM]; /** Array of Secure Write Protect entries */ struct rpmb_protect_cfg_blk_entry entries[SEC_WRITE_PROTECT_ENTRY_NUM]; /** Reserved bytes for padding at the end of the block */ uint8_t reserved_end[SEC_WRITE_PROTECT_FRAME_RESERVED_END_NUM]; }__attribute__((packed)); /** * @brief Write protect config block by RPMB driver. * * @param lun Indicates the logical unit to which secure write protection shall apply, * and 0 <= lun <= {@code SEC_WRITE_PROTECT_LUN_MAX} * @param entries Indicates the Secure Write Protect Entry array, The maximum length is 4. * @param len Indicates the real length of the Secure Write Protect Entry array, which value is less than 4. * * @return Returns {@code TEE_SUCCESS} if the operation is successful. * Returns {@code TEE_ERROR_BAD_PARAMETERS} if the input parameter is incorrect. * Returns {@code TEE_ERROR_OUT_OF_MEMORY} if the send message fail. * * @since 20 */ TEE_Result tee_ext_rpmb_protect_cfg_blk_write(uint8_t lun, struct rpmb_protect_cfg_blk_entry *entries, uint32_t len); /** * @brief Read protect config block by RPMB driver. * * @param lun Indicates the logical unit to which secure read protection shall apply, * and 0 <= lun <= SEC_WRITE_PROTECT_LUN_MAX. * @param entries Indicates the Secure Read Protect Entry array, The maximum length is 4. * @param len Indicates the real length of the Secure Read Protect Entry array, which value is less than 4. * * @return Returns {@code TEE_SUCCESS} if the operation is successful. * Returns {@code TEE_ERROR_BAD_PARAMETERS} if the input parameter is incorrect. * Returns {@code TEE_ERROR_OUT_OF_MEMORY} if the send message fail. * * @since 20 */ TEE_Result tee_ext_rpmb_protect_cfg_blk_read(uint8_t lun, struct rpmb_protect_cfg_blk_entry *entries, uint32_t *len); /** * @brief Write plaintext buffer to RPMB driver. * * @param buf Indicates the buffer for writing data. * @param size Indicates the length of buffer, the maximum value is 1024. * @param block Indicates the block index of the position of start block, the value is [0, 3]. * @param offset Indicates the offset bytes of data position, and the value of offest bytes is less than 256. * * @return Returns {@code TEE_SUCCESS} if the operation is successful. * Returns {@code TEE_ERROR_BAD_PARAMETERS} if the input parameter is incorrect. * Returns {@code TEE_ERROR_OUT_OF_MEMORY} if the send message fail. * * @since 20 */ TEE_Result tee_ext_rpmb_driver_write(const uint8_t *buf, size_t size, uint32_t block, uint32_t offset); /** * @brief Read plaintext buffer from RPMB driver. * * @param buf Indicates the buffer for read data. * @param size Indicates the length of buffer, the maximum value is 1024. * @param block Indicates the block index of the position of start block, the value is [0, 3]. * @param offset Indicates the offset bytes of data position, and the value of offest bytes is less than 256. * * @return Returns {@code TEE_SUCCESS} if the operation is successful. * Returns {@code TEE_ERROR_BAD_PARAMETERS} if the input parameter is incorrect. * Returns {@code TEE_ERROR_OUT_OF_MEMORY} if the send message fail. * * @since 20 */ TEE_Result tee_ext_rpmb_driver_read(uint8_t *buf, size_t size, uint32_t block, uint32_t offset); /** * @brief Remove data from RPMB driver. * * @param size Indicates the length of remove data, the maximum value is 1024. * @param block Indicates the block index of the position of start block, the value is [0, 3]. * @param offset Indicates the offset bytes of data position, and the value of offest bytes is less than 256. * * @return Returns {@code TEE_SUCCESS} if the operation is successful. * Returns {@code TEE_ERROR_BAD_PARAMETERS} if the input parameter is incorrect. * Returns {@code TEE_ERROR_OUT_OF_MEMORY} if the send message fail. * * @since 20 */ TEE_Result tee_ext_rpmb_driver_remove(size_t size, uint32_t block, uint32_t offset); /** * @brief RPMB secure storage fully formatted operation * * @return TEE_SUCCESS Indicates that the function was executed successfully * TEE_ERROR_RPMB_GENERIC RPMB controller general error * TEE_ERROR_RPMB_MAC_FAIL RPMB controller MAC check error * TEE_ERROR_RPMB_RESP_UNEXPECT_MAC RPMB response data MAC check error * * @since 20 */ TEE_Result tee_ext_rpmb_format(); #ifdef __cplusplus } #endif #endif /** @} */