From fdfe80728c9aff1a60198de7e08a07a7da714016 Mon Sep 17 00:00:00 2001 From: liyuxuan_hw <447978021@qq.com> Date: Mon, 23 Jun 2025 10:14:26 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0TEE=20kit?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: liyuxuan_hw <447978021@qq.com> --- zh-cn/native_sdk/TEEKit/tee/dstb_api.h | 119 ++ zh-cn/native_sdk/TEEKit/tee/pthread_attr.h | 102 ++ .../TEEKit/tee/rpmb_driver_rw_api.h | 366 +++++ zh-cn/native_sdk/TEEKit/tee/rpmb_fcntl.h | 297 +++++ zh-cn/native_sdk/TEEKit/tee/tee_agent.h | 108 ++ zh-cn/native_sdk/TEEKit/tee/tee_apm_api.h | 234 ++++ zh-cn/native_sdk/TEEKit/tee/tee_arith_api.h | 638 +++++++++ zh-cn/native_sdk/TEEKit/tee/tee_core_api.h | 128 ++ zh-cn/native_sdk/TEEKit/tee/tee_crypto_api.h | 1172 +++++++++++++++++ zh-cn/native_sdk/TEEKit/tee/tee_crypto_hal.h | 101 ++ zh-cn/native_sdk/TEEKit/tee/tee_defines.h | 968 ++++++++++++++ zh-cn/native_sdk/TEEKit/tee/tee_drv_client.h | 97 ++ zh-cn/native_sdk/TEEKit/tee/tee_dynamic_srv.h | 149 +++ zh-cn/native_sdk/TEEKit/tee/tee_ext_api.h | 216 +++ .../TEEKit/tee/tee_get_recoverymode.h | 86 ++ zh-cn/native_sdk/TEEKit/tee/tee_hw_ext_api.h | 149 +++ .../TEEKit/tee/tee_hw_ext_api_legacy.h | 141 ++ .../TEEKit/tee/tee_internal_se_api.h | 586 +++++++++ zh-cn/native_sdk/TEEKit/tee/tee_log.h | 382 ++++++ .../native_sdk/TEEKit/tee/tee_mem_mgmt_api.h | 278 ++++ .../TEEKit/tee/tee_notify_set_priority.h | 68 + zh-cn/native_sdk/TEEKit/tee/tee_object_api.h | 376 ++++++ .../native_sdk/TEEKit/tee/tee_property_api.h | 272 ++++ .../native_sdk/TEEKit/tee/tee_rtc_time_api.h | 117 ++ .../TEEKit/tee/tee_service_public.h | 194 +++ zh-cn/native_sdk/TEEKit/tee/tee_sharemem.h | 64 + .../native_sdk/TEEKit/tee/tee_sharemem_ops.h | 130 ++ zh-cn/native_sdk/TEEKit/tee/tee_time_api.h | 130 ++ .../TEEKit/tee/tee_trusted_storage_api.h | 416 ++++++ zh-cn/native_sdk/TEEKit/tee/tee_tui_gp_api.h | 479 +++++++ .../TEEKit/tee_client/tee_client_api.h | 246 ++++ .../TEEKit/tee_client/tee_client_constants.h | 230 ++++ .../TEEKit/tee_client/tee_client_type.h | 292 ++++ 33 files changed, 9331 insertions(+) create mode 100644 zh-cn/native_sdk/TEEKit/tee/dstb_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/pthread_attr.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/rpmb_driver_rw_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/rpmb_fcntl.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_agent.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_apm_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_arith_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_core_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_crypto_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_crypto_hal.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_defines.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_drv_client.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_dynamic_srv.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_ext_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_get_recoverymode.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_hw_ext_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_hw_ext_api_legacy.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_internal_se_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_log.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_mem_mgmt_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_notify_set_priority.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_object_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_property_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_rtc_time_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_service_public.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_sharemem.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_sharemem_ops.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_time_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_trusted_storage_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee/tee_tui_gp_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee_client/tee_client_api.h create mode 100644 zh-cn/native_sdk/TEEKit/tee_client/tee_client_constants.h create mode 100644 zh-cn/native_sdk/TEEKit/tee_client/tee_client_type.h diff --git a/zh-cn/native_sdk/TEEKit/tee/dstb_api.h b/zh-cn/native_sdk/TEEKit/tee/dstb_api.h new file mode 100644 index 00000000..e8484662 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/dstb_api.h @@ -0,0 +1,119 @@ +/* + * 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. + */ + +#ifndef DSTB_API_H +#define DSTB_API_H + +/** + * @addtogroup TeeTrusted + * @{ + * + * @brief TEE(Trusted Excution Environment) 可信执行环境 API. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file dstb_api.h + * + * @brief 提供分布式TEE服务相关的API。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 枚举设备ID类型。 + * @since 20 + */ +enum devid_type { + /** 网络ID。 */ + DEVID_NETID = 0, + /** 设备ID。 */ + DEVID_UDID = 1, +}; + +/** + * @brief 定义设备信息。 + * @since 20 + */ +struct device_info { + /** 设备ID类型枚举变量。 */ + enum devid_type devid_type; + /** 设备ID值。 */ + char *devid; +}; + +/** + * @brief 枚举协商条件类型。 + * @since 20 + */ +enum nego_condition { + /** 检查本地是否有对端记录，若无则发起协商。 */ + CHECK_LOCAL = 0, + /** 检查本地和对端是否互相有记录，若无则发起协商。 */ + CHECK_BOTH = 1, + /** 无条件发起协商。 */ + NO_CHECK = 2, +}; + +/** + * @brief 通过分布式TEE生成共享密钥。 + * + * @param devid_info [OUT] 对端设备ID，可以是网络ID或设备ID。 + * @param salt [IN] 随机盐值，如果调用者希望生成相同的共享密钥，需与对端一致。 + * @param salt_len [IN] 盐值缓冲区的长度。 + * @param info [IN] 生成共享密钥的附加信息，如果调用者希望生成相同的共享密钥，需与对端一致。 + * @param info_len [IN] 附加信息缓冲区的长度。 + * @param key [OUT] 生成的密钥结果。 + * @param key_len [IN] 密钥结果的长度。 + * @return 操作成功时返回TEE_SUCCESS，否则返回其他信息。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_dstb_gen_sharekey(struct device_info *devid_info, const uint8_t *salt, uint32_t salt_len, + const uint8_t *info, uint32_t info_len, uint8_t *key, uint32_t key_len); + +/** + * @brief 分布式TEE服务的预协商接口。 + * + * @param devid_info [OUT] 对端设备ID，可以是网络ID或设备ID。 + * @param cond [IN] 预协商条件。 + * @return 操作成功时返回 {@code TEE_SUCCESS}； + * 否则返回其他信息。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_dstb_pre_attestation(struct device_info *devid_info, enum nego_condition cond); + +#ifdef __cplusplus +} +#endif +/** @} */ +#endif \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/pthread_attr.h b/zh-cn/native_sdk/TEEKit/tee/pthread_attr.h new file mode 100644 index 00000000..40a1d3e1 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/pthread_attr.h @@ -0,0 +1,102 @@ +/* + * 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. + */ + +#ifndef PTHREAD_ATTR_H +#define PTHREAD_ATTR_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @addtogroup TeeTrusted + * @{ + * + * @brief TEE(Trusted Excution Environment) 可信执行环境 API. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file pthread_attr.h + * + * @brief 提供关于TA多线程的属性。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +/** + * @brief 定义CA的线程属性未显式设置（通配符/默认状态）。 + * + * @since 20 + */ +#define TEESMP_THREAD_ATTR_CA_WILDCARD 0 + +/** + * @brief 定义CA的线程属性继承自父线程。 + * + * @since 20 + */ +#define TEESMP_THREAD_ATTR_CA_INHERIT (-1U) + +/** + * @brief 定义任务ID属性继承自父任务/线程。 + * + * @since 20 + */ +#define TEESMP_THREAD_ATTR_TASK_ID_INHERIT (-1U) + +/** + * @brief 定义线程属性具有影子线程。 + * + * @since 20 + */ +#define TEESMP_THREAD_ATTR_HAS_SHADOW 0x1 + +/** + * @brief 定义线程属性不具有影子线程。 + * + * @since 20 + */ +#define TEESMP_THREAD_ATTR_NO_SHADOW 0x0 + +/** + * @brief 设置 CA、任务 ID 和影子线程的线程属性。 + * + * @param ca 指定 CA 属性值（例如 TEESMP_THREAD_ATTR_CA_INHERIT 表示继承）。 + * @param task_id 指定任务 ID 属性值（例如 TEESMP_THREAD_ATTR_TASK_ID_INHERIT 表示继承）。 + * @param shadow 指示是否启用影子线程设置（TEESMP_THREAD_ATTR_NO_SHADOW 为 0x0 表示无影子，TEESMP_THREAD_ATTR_HAS_SHADOW 为 0x1 表示有影子）。 + * + * @return 始终返回 0。 + * + * @since 20 + * @version 1.0 + */ +int pthread_attr_settee(pthread_attr_t *, int ca, int task_id, int shadow); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/rpmb_driver_rw_api.h b/zh-cn/native_sdk/TEEKit/tee/rpmb_driver_rw_api.h new file mode 100644 index 00000000..160d3226 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/rpmb_driver_rw_api.h @@ -0,0 +1,366 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file rpmb_driver_rw_api.h + * + * @brief 与RPMB驱动的读写相关的API。 + * 提供读取和写入RPMB驱动的功能。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef RPMB_DRIVER_RW_API_H +#define RPMB_DRIVER_RW_API_H + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 定义总块数。 + * + * @since 20 + * @version 1.0 + */ +#define TOTAL_BLK 4 + +/** + * @brief 定义块的大小。 + * + * @since 20 + * @version 1.0 + */ +#define BLK_SIZE 256 + +/** + * @brief 定义总块的大小。 + * + * @since 20 + * @version 1.0 + */ +#define TOTAL_BLK_SIZE (TOTAL_BLK * BLK_SIZE) + +/** + * @brief 定义安全写保护条目的数量。 + * + * @since 20 + * @version 1.0 + */ +#define SEC_WRITE_PROTECT_ENTRY_NUM 4 + +/** + * @brief 定义保留的安全写保护条目数量。 + * + * @since 20 + * @version 1.0 + */ +#define SEC_WRITE_PROTECT_ENTRY_RESERVED_NUM 3 + +/** + * @brief 定义安全写保护条目的保留大小。 + * + * @since 20 + * @version 1.0 + */ +#define SEC_WRITE_PROTECT_ENTRY_RESERVED_SIZE 16 + +/** + * @brief 定义安全写保护帧的保留数量。 + * + * @since 20 + * @version 1.0 + */ +#define SEC_WRITE_PROTECT_FRAME_RESERVED_NUM 14 + +/** + * @brief 定义安全写保护帧的保留结束数量。 + * + * @since 20 + * @version 1.0 + */ +#define SEC_WRITE_PROTECT_FRAME_RESERVED_END_NUM 176 + +/** + * @brief 定义安全写保护块的大小。 + * + * @since 20 + * @version 1.0 + */ +#define SEC_WRITE_PROTECT_BLK_SIZE 256 + +/** + * @brief 定义安全写保护LUN的最大数量。 + * + * @since 20 + * @version 1.0 + */ +#define SEC_WRITE_PROTECT_LUN_MAX 5 + +/** + * @brief WPF 设置为 1 表示逻辑单元应禁止修改在 LOGICAL BLOCK ADDRESS 字段和 NUMBER OF LOGICAL BLOCKS 字段 + * 指定范围内的 LBA 的介质。要求写入介质的命令应以 CHECK CONDITION 状态终止， + * 并将感知键设置为 DATA PROTECT，附加感知码设置为 WRITE PROTECTED。 + * + * @since 20 + * @version 1.0 + */ +typedef enum { + /** 禁用写保护 */ + SEC_WRITE_PROTECT_DISABLE = 0, + /** 启用写保护 */ + SEC_WRITE_PROTECT_ENABLE = 1, +} write_protect_flag; + +/** + * @brief 写保护类型指定如何修改 WPF 位。 + * + * @since 20 + * @version 1.0 + */ +typedef enum { + /** WPF 位在断电和硬件复位后是持久的。WPF 值只能通过写入安全写保护配置块来更改。 */ + NV_TYPE = 0, + /** WPF 位在断电或硬件复位后自动清除为 0b。 */ + P_TYPE = 1, + /** WPF 位在断电或硬件复位后自动设置为 1b。 */ + NV_AWP_TYPE = 2, +} write_protect_type; + +/** + * @brief 安全写保护条目。 + * +-----+---+---+---+---+---+---+---+----+ + * | | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | + * +-----+---+---+---+---+---+---+---+----+ + * | 0 | 保留位 | WFT | WPF| -> wp_data + * +-----+---+---+---+---+---+---+---+----+ + * | 1 | 保留位 | + * +-----+---+---+---+---+---+---+---+----+ + * | 2 | 保留位 | + * +-----+---+---+---+---+---+---+---+----+ + * | 3 | 保留位 | + * +-----+---+---+---+---+---+---+---+----+ + * | 4 | 逻辑块地址 | -> logical_blk_addr + * +-----+ + + * | ... | | + * +-----+ + + * | 11 | | + * +-----+ + + * | 12 | | + * +-----+---+---+---+---+---+---+---+----+ + * | ... | 逻辑块数量 | -> logical_blk_num + * +-----+---+---+---+---+---+---+---+----+ + * | 15 | | + * +-----+---+---+---+---+---+---+---+----+ + * + * @since 20 + * @version 1.0 + */ +struct rpmb_protect_cfg_blk_entry { + /** 该字段指定安全写保护区域的第一个逻辑块地址（LBA）。 */ //TODO: + uint8_t wp_data; + /** 保留字段 */ + uint8_t reserved[SEC_WRITE_PROTECT_ENTRY_RESERVED_NUM]; + /** 该字段指定安全写保护区域的第一个逻辑地址的 LBA。 */ + uint64_t logical_blk_addr; + /** 该字段指定属于安全写保护区域的连续逻辑块数量。 */ + uint32_t logical_blk_num; +} __attribute__((packed)); + + +/** + * @brief 安全写保护配置块仅由 RPMB 区域 0 支持。 + * 此配置块用于配置逻辑单元中的安全写保护区域。 + * 每个逻辑单元都有一个对应的安全写保护配置块。 + * 每个条目表示一个安全写保护区域。 + * 如果某个条目未使用，则相关字段的值应为零。 + * +-----+---+---+---+---+---+---+---+----+ + * | | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | + * +-----+---+---+---+---+---+---+---+----+ + * | 0 | LUN | + * +-----+---+---+---+---+---+---+---+----+ + * | 1 | 数据长度 | + * +-----+---+---+---+---+---+---+---+----+ + * | 2 | | + * +-----+ + + * | ... | 保留位 | + * +-----+ + + * | 15 | | + * +-----+---+---+---+---+---+---+---+----+ + * | 16 | | + * +-----+ + + * | ... | 安全写保护条目 0 | + * +-----+ + + * | 31 | | + * +-----+---+---+---+---+---+---+---+----+ + * | 32 | | + * +-----+ + + * | ... | 安全写保护条目 1 | + * +-----+ + + * | 47 | | + * +-----+---+---+---+---+---+---+---+----+ + * | 48 | | + * +-----+ + + * | ... | 安全写保护条目 2 | + * +-----+ + + * | 63 | | + * +-----+---+---+---+---+---+---+---+----+ + * | 64 | | + * +-----+ + + * | ... | 安全写保护条目 3 | + * +-----+ + + * | 79 | | + * +-----+---+---+---+---+---+---+---+----+ + * | 80 | | + * +-----+ + + * | ... | 保留位 | + * +-----+ + + * | 255 | | + * +-----+---+---+---+---+---+---+---+----+ + * + * @since 20 + * @version 1.0 + */ +struct rpmb_protect_cfg_block { + /** 逻辑单元号 (LUN) */ + uint8_t lun; + /** 数据长度 */ + uint8_t data_length; + /** 保留字段 */ + uint8_t reserved[SEC_WRITE_PROTECT_FRAME_RESERVED_NUM]; + /** 安全写保护条目数组 */ + struct rpmb_protect_cfg_blk_entry entries[SEC_WRITE_PROTECT_ENTRY_NUM]; + /** 保留字段 */ + uint8_t reserved_end[SEC_WRITE_PROTECT_FRAME_RESERVED_END_NUM]; +} __attribute__((packed)); + +/** + * @brief 通过 RPMB 驱动写入保护配置块。 + * + * @param lun 指定适用安全写保护的逻辑单元，且 0 <= lun <= {@code SEC_WRITE_PROTECT_LUN_MAX}。 + * @param entries 指定安全写保护条目数组，最大长度为 4。 + * @param len 指定安全写保护条目数组的实际长度，值小于 4。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数不正确。\n + * 返回 {@code TEE_ERROR_OUT_OF_MEMORY} 表示发送消息失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_rpmb_protect_cfg_blk_write(uint8_t lun, struct rpmb_protect_cfg_blk_entry *entries, uint32_t len); + +/** + * @brief 通过 RPMB 驱动读取保护配置块。 + * + * @param lun 指定适用安全读取保护的逻辑单元，且 0 <= lun <= SEC_WRITE_PROTECT_LUN_MAX。 + * @param entries 指定安全读取保护条目数组，最大长度为 4。 + * @param len 指定安全读取保护条目数组的实际长度，值小于 4。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数不正确。\n + * 返回 {@code TEE_ERROR_OUT_OF_MEMORY} 表示发送消息失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_rpmb_protect_cfg_blk_read(uint8_t lun, struct rpmb_protect_cfg_blk_entry *entries, uint32_t *len); + +/** + * @brief 向 RPMB 驱动写入明文缓冲区数据。 + * + * @param buf 指定写入数据的缓冲区。 + * @param size 指定缓冲区的长度，最大值为 1024。 + * @param block 指定起始块的位置索引，值范围为 [0, 3]。 + * @param offset 指定数据位置的偏移字节，偏移字节值小于 256。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数不正确。\n + * 返回 {@code TEE_ERROR_OUT_OF_MEMORY} 表示发送消息失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_rpmb_driver_write(const uint8_t *buf, size_t size, uint32_t block, uint32_t offset); + +/** + * @brief 从RPMB驱动读取明文缓冲区。 + * + * @param buf 表示用于读取数据的缓冲区。 + * @param size 表示缓冲区的长度，最大值为1024。 + * @param block 表示起始块的位置的块索引，值范围为[0, 3]。 + * @param offset 表示数据位置的偏移字节，偏移字节的值小于256。 + * + * @return 返回{@code TEE_SUCCESS}表示操作成功。\n + * 返回{@code TEE_ERROR_BAD_PARAMETERS}表示输入参数不正确。\n + * 返回{@code TEE_ERROR_OUT_OF_MEMORY}表示发送消息失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_rpmb_driver_read(uint8_t *buf, size_t size, uint32_t block, uint32_t offset); + +/** + * @brief 从RPMB驱动移除数据。 + * + * @param size 表示移除数据的长度，最大值为1024。 + * @param block 表示起始块的位置的块索引，值范围为[0, 3]。 + * @param offset 表示数据位置的偏移字节，偏移字节的值小于256。 + * + * @return 返回{@code TEE_SUCCESS}表示操作成功。\n + * 返回{@code TEE_ERROR_BAD_PARAMETERS}表示输入参数不正确。\n + * 返回{@code TEE_ERROR_OUT_OF_MEMORY}表示发送消息失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_rpmb_driver_remove(size_t size, uint32_t block, uint32_t offset); + +/** + * @brief RPMB 安全存储全格式化操作 + * + * @param NA + * + * @return TEE_SUCCESS 表示函数执行成功 + * TEE_ERROR_RPMB_GENERIC 表示 RPMB 控制器通用错误\n + * TEE_ERROR_RPMB_MAC_FAIL 表示 RPMB 控制器 MAC 校验失败\n + * TEE_ERROR_RPMB_RESP_UNEXPECT_MAC 表示 RPMB 响应数据 MAC 校验失败 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_rpmb_format(); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/rpmb_fcntl.h b/zh-cn/native_sdk/TEEKit/tee/rpmb_fcntl.h new file mode 100644 index 00000000..5e8a2a56 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/rpmb_fcntl.h @@ -0,0 +1,297 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file rpmb_fcntl.h + * + * @brief 提供与RPMB服务相关的API。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef RPMB_RPMB_FCNTL_H +#define RPMB_RPMB_FCNTL_H + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 分区初始化，执行RPMB密钥写入和格式化操作。 + * + * @attention 此函数只需执行一次。 + * + * @return 返回{@code TEE_SUCCESS}表示操作成功。\n + * 返回{@code TEE_ERROR_RPMB_GENERIC}表示RPMB控制器一般错误。\n + * 返回{@code TEE_ERROR_RPMB_MAC_FAIL}表示RPMB控制器MAC校验错误。\n + * 返回{@code TEE_ERROR_RPMB_RESP_UNEXPECT_MAC}表示RPMB响应数据MAC校验错误。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_RPMB_FS_Init(void); + +/** + * @brief RPMB安全存储完全格式化操作。 + * + * @return 返回{@code TEE_SUCCESS}表示操作成功。\n + * 返回{@code TEE_ERROR_RPMB_GENERIC}表示RPMB控制器一般错误。\n + * 返回{@code TEE_ERROR_RPMB_MAC_FAIL}表示RPMB控制器MAC校验错误。\n + * 返回{@code TEE_ERROR_RPMB_RESP_UNEXPECT_MAC}表示RPMB响应数据MAC校验错误。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_RPMB_FS_Format(void); + +/** + * @brief 写文件到RPMB。 + * + * @attention 如果要提高写文件的性能，需要在TA的manifest中定义堆大小，至少是文件大小的三倍加256KB。 + * 例如：要写入一个100KB大小的文件，定义的堆大小至少是556KB（3 * 100 + 256）。如果无法满足堆大小要求， + * 文件写入仍会成功，但性能会较差。 + * + * @param filename 表示要写入数据的文件名，最大长度为64字节。 + * @param buf 表示写入数据的缓冲区。 + * @param size 表示写入数据的大小，最大为160KB。 + * + * @return 返回{@code TEE_SUCCESS}表示操作成功。\n + * 返回{@code TEE_ERROR_BAD_PARAMETERS}表示输入参数不正确，或者文件名超过64字节。\n + * 返回{@code TEE_ERROR_RPMB_NOSPC}表示RPMB分区磁盘空间不足。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_RPMB_FS_Write(const char *filename, const uint8_t *buf, size_t size); + +/** + * @brief 通过 huk2 加密方式向 RPMB 写入文件。 + * + * @attention 如果希望提升文件写入性能，需要在 TA 的 manifest 文件中定义堆大小，至少为文件大小的 3 倍加上 256KB。 + * 例如：写入一个大小为 100KB 的文件时，定义的堆大小至少为 556KB（3 * 100 + 256）。如果堆大小不足，文件写入仍会成功， + * 但性能会较差。 + * + * @param filename 表示要写入数据的文件名，最大长度为 64 字节。 + * @param buf 表示用于写入数据的缓冲区。 + * @param size 表示写入数据的大小，最大为 160KB。 + * @param fmode 表示写入数据使用的加密方式，本接口指定使用 huk2 加密。 + * + * @return 操作成功返回 {@code TEE_SUCCESS}\n + * 如果输入参数错误，或文件名超过 64 字节，返回 {@code TEE_ERROR_BAD_PARAMETERS}\n + * 如果 RPMB 分区空间不足，返回 {@code TEE_ERROR_RPMB_NOSPC} + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_RPMB_FS_Write_Attr(const char *filename, const uint8_t *buf, size_t size, uint32_t fmode); + +/** + * @brief 从RPMB读取文件。 + * + * @attention 如果要提高读取文件的性能，需要在TA的manifest中定义堆大小，至少是文件大小的三倍加256KB。 + * 例如：要读取一个100KB大小的文件，定义的堆大小至少是556KB（3 * 100 + 256）。如果无法满足堆大小要求， + * 文件读取仍会成功，但性能会较差。 + * + * @param filename 表示要读取数据的文件名，最大长度为64字节。 + * @param buf 表示读取数据的缓冲区。 + * @param size 表示读取数据的大小。 + * @param count 表示实际读取的大小。 + * + * @return 返回{@code TEE_SUCCESS}表示操作成功。\n + * 返回{@code TEE_ERROR_BAD_PARAMETERS}表示输入参数不正确，或者文件名超过64字节。\n + * 返回{@code TEE_ERROR_RPMB_FILE_NOT_FOUND}表示文件不存在。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_RPMB_FS_Read(const char *filename, uint8_t *buf, size_t size, uint32_t *count); + +/** + * @brief 重命名RPMB中的文件。 + * + * @param old_name 表示旧文件名。 + * @param new_name 表示新文件名。 + * + * @return 返回{@code TEE_SUCCESS}表示操作成功。\n + * 返回{@code TEE_ERROR_BAD_PARAMETERS}表示输入参数不正确，或者文件名超过64字节。\n + * 返回{@code TEE_ERROR_RPMB_FILE_NOT_FOUND}表示文件不存在。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_RPMB_FS_Rename(const char *old_name, const char *new_name); + +/** + * @brief 删除RPMB中的文件。 + * + * @param filename 表示要删除的文件名。 + * + * @return 返回{@code TEE_SUCCESS}表示操作成功。\n + * 返回{@code TEE_ERROR_BAD_PARAMETERS}表示输入参数不正确，或者文件名超过64字节。\n + * 返回{@code TEE_ERROR_RPMB_FILE_NOT_FOUND}表示文件不存在。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_RPMB_FS_Rm(const char *filename); + +/** + * @brief 存储在RPMB分区中的文件状态，供{@code TEE_RPMB_FS_Stat}使用。 + * + * @since 20 + */ +struct rpmb_fs_stat { + /** 表示文件的大小，以字节为单位。 */ + uint32_t size; + /** 保留字段，当前未使用。 */ + uint32_t reserved; +}; + +/** + * @brief 获取RPMB中的文件状态。 + * + * @param filename 表示RPMB中的文件名。 + * @param stat 表示获取的文件状态信息。 + * + * @return 返回{@code TEE_SUCCESS}表示操作成功。\n + * 返回{@code TEE_ERROR_BAD_PARAMETERS}表示输入参数不正确，或者文件名超过64字节。\n + * 返回{@code TEE_ERROR_RPMB_FILE_NOT_FOUND}表示文件不存在。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_RPMB_FS_Stat(const char *filename, struct rpmb_fs_stat *stat); + +/** + * @brief 存储在RPMB分区中的磁盘状态，供{@code TEE_RPMB_FS_StatDisk}使用。 + * + * @since 20 + */ +struct rpmb_fs_statdisk { + /** 表示RPMB分区的总大小。 */ + uint32_t disk_size; + /** 表示TA已使用的大小。 */ + uint32_t ta_used_size; + /** 表示RPMB分区的剩余空间大小。 */ + uint32_t free_size; + /** 保留字段，当前未使用。 */ + uint32_t reserved; +}; + +/** + * @brief 获取磁盘状态。 + * + * @param stat 表示获取的磁盘状态信息。 + * + * @return 返回{@code TEE_SUCCESS}表示操作成功。\n + * 返回{@code TEE_ERROR_BAD_PARAMETERS}表示输入参数不正确。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_RPMB_FS_StatDisk(struct rpmb_fs_statdisk *stat); + +/** + * @brief 文件属性定义，表示该文件在出厂重置过程中不能被擦除。 + * + * @since 20 + */ +#define TEE_RPMB_FMODE_NON_ERASURE (1U << 0) + +/** + * @brief 文件属性定义，表示清除文件的属性值。 + * + * @since 20 + */ +#define TEE_RPMB_FMODE_CLEAR 0 + +/** + * @brief 设置RPMB中的文件属性。 + * + * @param filename 表示RPMB中的文件名。 + * @param fmode 表示文件属性，当前支持{@code TEE_RPMB_FMODE_NON_ERASURE}和{@code TEE_RPMB_FMODE_CLEAR}两种属性，其他值将返回{@code TEE_ERROR_BAD_PARAMETERS}。 + * + * @return 返回{@code TEE_SUCCESS}表示操作成功。\n + * 返回{@code TEE_ERROR_BAD_PARAMETERS}表示输入参数不正确，或者文件名超过64字节。\n + * 返回{@code TEE_ERROR_RPMB_FILE_NOT_FOUND}表示文件不存在。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_RPMB_FS_SetAttr(const char *filename, uint32_t fmode); + +/** + * @brief 格式化，删除文件属性为可擦除文件，保留文件属性为不可擦除文件。 + * + * @return 返回{@code TEE_SUCCESS}表示操作成功。\n + * 返回{@code TEE_ERROR_RPMB_GENERIC}表示RPMB控制器一般错误。\n + * 返回{@code TEE_ERROR_RPMB_MAC_FAIL}表示RPMB控制器MAC校验错误。\n + * 返回{@code TEE_ERROR_RPMB_RESP_UNEXPECT_MAC}表示RPMB响应数据MAC校验错误。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_RPMB_FS_Erase(void); + +/** + * @brief 枚举RPMB密钥状态的类型，供{@code TEE_RPMB_KEY_Status}使用。 + * + * @since 20 + */ +enum TEE_RPMB_KEY_STAT { + /** RPMB密钥状态无效。 */ + TEE_RPMB_KEY_INVALID = 0x0, + /** RPMB密钥已编程并且匹配正确。 */ + TEE_RPMB_KEY_SUCCESS, + /** RPMB密钥未编程。 */ + TEE_RPMB_KEY_NOT_PROGRAM, + /** RPMB密钥已编程，但未能匹配。 */ + TEE_RPMB_KEY_NOT_MATCH, +}; + +/** + * @brief 获取RPMB密钥状态。 + * + * @return 返回{@code TEE_RPMB_KEY_SUCCESS}表示RPMB密钥已编程并且匹配正确。\n + * 返回{@code TEE_RPMB_KEY_NOT_PROGRAM}表示RPMB密钥未编程。\n + * 返回{@code TEE_RPMB_KEY_NOT_MATCH}表示RPMB密钥已编程但未能匹配。\n + * 返回{@code TEE_RPMB_KEY_INVALID}表示RPMB密钥状态无效。 + * + * @since 20 + * @version 1.0 + */ +uint32_t TEE_RPMB_KEY_Status(void); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_agent.h b/zh-cn/native_sdk/TEEKit/tee/tee_agent.h new file mode 100644 index 00000000..6707bcc2 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_agent.h @@ -0,0 +1,108 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_agent.h + * + * @brief 提供TA代理相关的API。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_AGENT_H +#define TEE_AGENT_H + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief TA 发送消息给 gtask 以锁定代理。 + * + * @param agent_id 请求被锁定的代理 ID。 + * + * @return 操作成功时返回 {@code TEE_SUCCESS}； + * 否则返回其他信息。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_agent_lock(uint32_t agent_id); + +/** + * @brief 解锁代理。 + * + * @param agent_id 请求被解锁的代理 ID。 + * + * @return 操作成功时返回 {@code TEE_SUCCESS}； + * 否则返回其他信息。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_agent_unlock(uint32_t agent_id); + +/** + * @brief 发送代理命令给 gtask。 + * + * @param agent_id 代理 ID。 + * + * @return 操作成功时返回 {@code TEE_SUCCESS}； + * 否则返回其他信息。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_send_agent_cmd(uint32_t agent_id); + +/** + * @brief 在获取代理缓冲区接收消息。 + * + * @param agent_id 代理 ID。 + * @param buffer 代理缓冲区。 + * @param length 代理缓冲区的长度。 + * + * @return 操作成功时返回 {@code TEE_SUCCESS}； + * 否则返回其他信息。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_get_agent_buffer(uint32_t agent_id, void **buffer, uint32_t *length); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_apm_api.h b/zh-cn/native_sdk/TEEKit/tee/tee_apm_api.h new file mode 100644 index 00000000..eb8523b2 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_apm_api.h @@ -0,0 +1,234 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_apm_api.h + * + * @brief 提供关于TA APM的API。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_APM_API_H +#define TEE_APM_API_H + +#include "tee_defines.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 枚举TEE度量结果值。 + * + * @since 20 + */ +enum tee_measure_result_value { + /** 度量成功。 */ + TEE_MEASURE_SUCCESS = 0x00000000, + /** 通用错误。 */ + TEE_MEASURE_ERROR_GENERIC = 0x00000001, + /** TA哈希检查失败。 */ + TEE_MEASURE_ERROR_TA_HASH_CHECK_FAILED = 0x00000002, + /** TA基线不存在。 */ + TEE_MEASURE_ERROR_TA_BASELINE_NOT_EXIST = 0x00000003, + /** TA内存哈希不存在。 */ + TEE_MEASURE_ERROR_TA_MEMHASH_NOT_EXIST = 0x00000004, + /** 权限被拒绝。 */ + TEE_MEASURE_ERROR_PERMISSION_DENY = 0x00000005, + /** TA历史度量不存在。 */ + TEE_MEASURE_ERROR_TA_HISTORY_MEASURE_NOT_EXIST = 0x00000006, + /** MSPC报告查询失败。 */ + TEE_MEASURE_ERROR_MSPC_REPORT_QUERY_FAILED = 0x00000007, + /** MSPC不支持。 */ + TEE_MEASURE_ERROR_MSPC_NOT_SUPPORT = 0x00000008, + /** 报告不支持。 */ + TEE_MEASURE_ERROR_REPORT_NOT_SUPPORT = 0x00000009, + /** APM不支持。 */ + TEE_MEASURE_ERROR_APM_NOT_SUPPORT = 0x0000000a, +}; + +/** + * @brief 记录最近的度量错误。 + * + * @since 20 + * @version 1.0 + */ +#define MAX_HISTORY_MEASURE_RECORDS_NUM 10 + +/** + * @brief 定义记录最近度量错误的结构体。 + * + * @since 20 + */ +struct history_measure_result_t { + uint8_t error_num; + /** 度量错误类型 */ + uint32_t error_type[MAX_HISTORY_MEASURE_RECORDS_NUM]; + /** 度量错误发生时间 */ + uint64_t error_time[MAX_HISTORY_MEASURE_RECORDS_NUM]; +}; + +/** + * @brief 定义TA哈希的大小。 + * + * @since 20 + */ +#define TA_HASH_SIZE 32 + +/** + * @brief 定义TA度量报告的结构体。 + * + * @since 20 + */ +struct ta_measure_report_t { + /** TA的UUID */ + TEE_UUID uuid; + /** TA的度量结果 */ + uint32_t measure_result; + /** TA的度量哈希 */ + uint8_t ta_measured[TA_HASH_SIZE]; + /** TA的基线哈希 */ + uint8_t ta_baseline[TA_HASH_SIZE]; + /** 历史度量错误 */ + struct history_measure_result_t history_result; +}; + +/** + * @brief 查询TA度量报告。 + * + * @param uuid 指向TA的UUID。 + * @param report 指向存储度量报告结果的结构体。 + * + * @return 返回查询结果，成功时返回TEE_SUCCESS，失败时返回相应错误码。 + * + * @since 20 + */ +TEE_Result tee_query_ta_measure_report(const TEE_UUID *uuid, struct ta_measure_report_t *report); + +/** + * @brief 定义 MSPC 度量报告元素的结构体。 + * + * @since 20 + */ +struct mspc_metric_report_element_t { + /** 基线状态 */ + uint32_t baseline_status; + /** 最近一次错误 */ + uint32_t recent_error; + /** 错误类型 */ + uint32_t error_class; + /** 错误发生时间 */ + uint32_t error_time; +}; + +/** + * @brief 定义 MSPC 度量结果报告的子结构体。 + * + * @since 20 + */ +struct mspc_metric_result_report_sub { + /** 全局度量结果 */ + struct mspc_metric_report_element_t global_result; + /** BL2 度量结果 */ + struct mspc_metric_report_element_t bl2_result; + /** BL31 度量结果 */ + struct mspc_metric_report_element_t bl31_result; + /** TEE 度量结果 */ + struct mspc_metric_report_element_t tee_result; +}; + +/** + * @brief 定义 MSPC 度量结果报告中被动部分的结构体。 + * + * @since 20 + */ +struct mspc_metric_result_report_passive { + /** BL2 验证结果 */ + struct mspc_metric_report_element_t bl2_verify_result; + /** TEE 主动防护度量结果 */ + struct mspc_metric_report_element_t tee_active_protect; +}; + +/** + * @brief 定义 MSPC 度量结果报告中命令处理部分的结构体。 + * + * @since 20 + */ +struct mspc_metric_result_report_of_cmd_process { + /** 基线命令的度量结果 */ + struct mspc_metric_report_element_t cmd_baseline; + /** 主动命令的度量结果 */ + struct mspc_metric_report_element_t cmd_active_metric; + /** 被动命令的度量结果 */ + struct mspc_metric_report_element_t cmd_passive_metric; + /** 查询命令的度量结果 */ + struct mspc_metric_report_element_t cmd_query_result; +}; + +/** + * @brief 定义 MSPC 度量结果报告的结构体。 + * + * @since 20 + */ +struct mspc_metric_result_report_t { + /** 最终度量结果 */ + uint32_t final_result; + /** 基线度量报告 */ + struct mspc_metric_result_report_sub baseline_report; + /** 空闲状态的度量报告 */ + struct mspc_metric_result_report_sub idle_metric_report; + /** 主动状态的度量报告 */ + struct mspc_metric_result_report_sub active_metric_report; + /** 被动状态的度量报告 */ + struct mspc_metric_result_report_passive passive_metric_report; + /** 命令处理的度量报告 */ + struct mspc_metric_result_report_of_cmd_process cmd_process_report; +}; + +/** + * @brief 查询MSPC度量报告。 + * + * @param report 存储MSPC度量报告的结构体。 + * + * @return 如果操作成功，返回 {@code TEE_SUCCESS}。 + * 否则，返回其他错误信息。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_query_mspc_measure_report(struct mspc_metric_result_report_t *report); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_arith_api.h b/zh-cn/native_sdk/TEEKit/tee/tee_arith_api.h new file mode 100644 index 00000000..c0024749 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_arith_api.h @@ -0,0 +1,638 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_arith_api.h + * + * @brief 提供操作大整数的API。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_ARITH_API_H +#define TEE_ARITH_API_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 定义大整数类型。 + * + * @since 20 + */ +typedef uint32_t TEE_BigInt; + +/** + * @brief 定义大整数模乘类型。 + * + * @since 20 + */ +typedef uint32_t TEE_BigIntFMM; + +/** + * @brief 定义大整数模乘上下文类型。 + * + * @since 20 + */ +typedef uint32_t TEE_BigIntFMMContext; + +/** + * @brief 获取表示BigInt所需的uint32_t类型数组的大小。 + * + * @param n 表示TEE_BigInt类型。 + * + * @return 返回获得的BigInt大小。 + * + * @since 20 + * @version 1.0 + */ +#define TEE_BigIntSizeInU32(n) ((((n) + 31) / 32) + 2) + +/** + * @brief 获取uint32_t类型数组的大小。 + * + * @param modulusSizeInBits 表示模数大小，单位为比特。 + * + * @return 返回存储TEE_BigIntFMM所需的字节数，给定模数的长度为modSizeInBits。 + * + * @since 20 + * @version 1.0 + */ +size_t TEE_BigIntFMMSizeInU32(size_t modulusSizeInBits); + +/** + * @brief 获取表示快速模数上下文所需的uint32_t类型数组的大小。 + * + * @param modulusSizeInBits 表示模数大小，单位为比特。 + * + * @return 返回存储TEE_BigIntFMMContext所需的字节数，给定模数的长度为modSizeInBits。 + * + * @since 20 + * @version 1.0 + */ +size_t TEE_BigIntFMMContextSizeInU32(size_t modulusSizeInBits); + +/** + * @brief 初始化TEE_BigInt。 + * + * @param bigInt 表示要初始化的TEE_BigInt指针。 + * @param len 表示指向TEE_BigInt的内存大小，以uint32_t为单位。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntInit(TEE_BigInt *bigInt, size_t len); + +/** + * @brief 计算快速模数乘法所需的前置条件，并将其存储在上下文中。 + * + * @param context 表示要初始化的TEE_BigIntFMMContext指针。 + * @param len 表示指向的内存大小，以uint32_t为单位。 + * @param modulus 表示指向模数的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntInitFMMContext(TEE_BigIntFMMContext *context, size_t len, const TEE_BigInt *modulus); + +/** + * @brief 计算快速模数乘法所需的前置条件，并将其存储在上下文中。 + * + * @param context 表示要初始化的TEE_BigIntFMMContext指针。 + * @param len 表示指向的内存大小，以uint32_t为单位。 + * @param modulus 表示指向模数的指针。 + * + * @return 返回TEE_SUCCESS表示操作成功。\n + * 如果操作失败，则返回其他值。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_BigIntInitFMMContext1(TEE_BigIntFMMContext *context, size_t len, const TEE_BigInt *modulus); + +/** + * @brief 初始化TEE_BigIntFMM并将其表示的值设置为零。 + * + * @param bigIntFMM 表示要初始化的TEE_BigIntFMM指针。 + * @param len 表示指向bigIntFMM的内存大小，以uint32_t为单位。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntInitFMM(TEE_BigIntFMM *bigIntFMM, size_t len); + +/** + * @brief 将八位字符串缓冲区转换为TEE_BigInt格式。 + * + * @param dest 表示保存结果的TEE_BigInt指针。 + * @param buffer 表示保存整数的八位字符串表示形式的缓冲区指针。 + * @param bufferLen 表示缓冲区长度，以字节为单位。 + * @param sign 表示dest的符号，设置为sign的符号。 + * + * @return 返回TEE_SUCCESS表示操作成功。\n + * 返回TEE_ERROR_OVERFLOW表示为dest分配的内存过小。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_BigIntConvertFromOctetString(TEE_BigInt *dest, const uint8_t *buffer, size_t bufferLen, int32_t sign); + +/** + * @brief 将TEE_BigInt格式的整数的绝对值转换为八位字符串。 + * + * @param buffer 表示输出缓冲区的指针，保存转换后的八位字符串表示形式。 + * @param bufferLen 表示缓冲区长度，以字节为单位。 + * @param bigInt 表示要转换的整数的指针。 + * + * @return 返回TEE_SUCCESS表示操作成功。\n + * 返回TEE_ERROR_SHORT_BUFFER表示输出缓冲区太小，无法容纳八位字符串。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_BigIntConvertToOctetString(void *buffer, size_t *bufferLen, const TEE_BigInt *bigInt); + +/** + * @brief 将dest设置为shortVal的值。 + * + * @param dest 表示保存结果的TEE_BigInt指针。 + * @param shortVal 表示要设置的值。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntConvertFromS32(TEE_BigInt *dest, int32_t shortVal); + +/** + * @brief 将dest设置为src的值，包括src的符号。 + * + * @param dest 表示保存结果的int32_t指针。 + * @param src 表示要设置的值的指针。 + * + * @return 返回TEE_SUCCESS表示操作成功。\n + * 返回TEE_ERROR_OVERFLOW表示src无法适配到int32_t中。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_BigIntConvertToS32(int32_t *dest, const TEE_BigInt *src); + +/** + * @brief 检查op1 > op2、op1 == op2或op1 < op2。 + * + * @param op1 表示第一个操作数的指针。 + * @param op2 表示第二个操作数的指针。 + * + * @return 如果op1 == op2，返回0。 + * 如果op1 > op2，返回一个正数。 + * + * @since 20 + * @version 1.0 + */ +int32_t TEE_BigIntCmp(const TEE_BigInt *op1, const TEE_BigInt *op2); + +/** + * @brief 检查op > shortVal、op == shortVal或op < shortVal。 + * + * @param op 表示第一个操作数的指针。 + * @param shortVal 表示第二个操作数的值。 + * + * @return 如果op1 == shortVal，返回0。 + * 如果op1 > shortVal，返回一个正数。 + * + * @since 20 + * @version 1.0 + */ +int32_t TEE_BigIntCmpS32(const TEE_BigInt *op, int32_t shortVal); + +/** + * @brief 计算|dest| = |op| >> bits。 + * + * @param dest 表示保存移位结果的TEE_BigInt指针。 + * @param op 表示要移位的操作数的指针。 + * @param bits 表示移位的位数。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntShiftRight(TEE_BigInt *dest, const TEE_BigInt *op, size_t bits); + +/** + * @brief 获取|src|的自然二进制表示中第bitIndex位的值。 + * + * @param src 表示整数的指针。 + * @param bitIndex 表示要读取的位的偏移量，从最低有效位的偏移0开始。 + * + * @return 返回|src|中bitIndex位的布尔值。值true表示1，值false表示0。 + * + * @since 20 + * @version 1.0 + */ +bool TEE_BigIntGetBit(const TEE_BigInt *src, uint32_t bitIndex); + +/** + * @brief 获取|src|的自然二进制表示中的位数，即src的大小。 + * + * @param src 表示整数的指针。 + * + * @return 如果src为0，返回0。\n + * 返回src自然二进制表示中的位数。 + * + * @since 20 + * @version 1.0 + */ +uint32_t TEE_BigIntGetBitCount(const TEE_BigInt *src); + +#if defined(API_LEVEL) && (API_LEVEL >= API_LEVEL1_2) +/** + * @brief 将op的自然二进制表示中第bitIndex位设置为1或0。 + * + * @param op 表示整数的指针。 + * @param bitIndex 表示要设置的位的偏移量，从最低有效位的偏移0开始。 + * @param value 表示要设置的位值。值true表示1，值false表示0。 + * + * @return 返回TEE_SUCCESS表示操作成功。\n + * 返回TEE_ERROR_OVERFLOW表示bitIndex位大于op分配的位长度。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_BigIntSetBit(TEE_BigInt *op, uint32_t bitIndex, bool value); + +/** + * @brief 将src的值赋给dest。 + * + * @param dest 表示要赋值的TEE_BigInt指针。 + * @param src 表示源操作数的指针。 + * + * @return 返回TEE_SUCCESS表示操作成功。\n + * 返回TEE_ERROR_OVERFLOW表示dest操作数无法容纳src的值。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_BigIntAssign(TEE_BigInt *dest, const TEE_BigInt *src); + +/** + * @brief 将src的绝对值赋给dest。 + * + * @param dest 表示要赋值的TEE_BigInt指针。 + * @param src 表示源操作数的指针。 + * + * @return 返回TEE_SUCCESS表示操作成功。\n + * 返回TEE_ERROR_OVERFLOW表示dest操作数无法容纳src的值。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_BigIntAbs(TEE_BigInt *dest, const TEE_BigInt *src); +#endif /* API_LEVEL */ + +/** + * @brief 计算dest = op1 + op2。 + * + * @param dest 表示保存op1和op2之和的TEE_BigInt指针。 + * @param op1 表示第一个操作数的指针。 + * @param op2 表示第二个操作数的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntAdd(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2); + +/** + * @brief 计算dest = op1 - op2。 + * + * @param dest 表示保存op1和op2之差的TEE_BigInt指针。 + * @param op1 表示第一个操作数的指针。 + * @param op2 表示第二个操作数的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntSub(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2); + +/** + * @brief 对操作数取反：dest = -op。 + * + * @param dest 表示保存结果- op的TEE_BigInt指针。 + * @param op 表示要取反的操作数的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntNeg(TEE_BigInt *dest, const TEE_BigInt *op); + +/** + * @brief 计算dest = op1 * op2。 + * + * @param dest 表示保存op1和op2之积的TEE_BigInt指针。 + * @param op1 表示第一个操作数的指针。 + * @param op2 表示第二个操作数的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntMul(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2); + +/** + * @brief 计算dest = op * op。 + * + * @param dest 表示保存op * op结果的TEE_BigInt指针。 + * @param op 表示要平方的操作数的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntSquare(TEE_BigInt *dest, const TEE_BigInt *op); + +/** + * @brief 计算dest = op1 + op2。 + * + * @param dest 表示保存op1和op2之和的TEE_BigInt指针。 + * @param op1 表示第一个操作数的指针。 + * @param op2 表示第二个操作数的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntAdd(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2); + +/** + * @brief 计算dest = op1 - op2。 + * + * @param dest 表示保存op1和op2之差的TEE_BigInt指针。 + * @param op1 表示第一个操作数的指针。 + * @param op2 表示第二个操作数的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntSub(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2); + +/** + * @brief 对操作数取反：dest = -op。 + * + * @param dest 表示保存结果- op的TEE_BigInt指针。 + * @param op 表示要取反的操作数的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntNeg(TEE_BigInt *dest, const TEE_BigInt *op); + +/** + * @brief 计算dest = op1 * op2。 + * + * @param dest 表示保存op1和op2之积的TEE_BigInt指针。 + * @param op1 表示第一个操作数的指针。 + * @param op2 表示第二个操作数的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntMul(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2); + +/** + * @brief 计算dest = op * op。 + * + * @param dest 表示保存op * op结果的TEE_BigInt指针。 + * @param op 表示要平方的操作数的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntSquare(TEE_BigInt *dest, const TEE_BigInt *op); + +/** + * @brief 计算 dest_r 和 dest_q，使得 op1 = dest_q * op2 + dest_r。 + * + * @param dest_q 指向 TEE_BigInt 类型的指针，用于存储商。 + * @param dest_r 指向 TEE_BigInt 类型的指针，用于存储余数。 + * @param op1 指向第一个操作数的指针，即被除数。 + * @param op2 指向第二个操作数的指针，即除数。 + * + * @return 操作成功返回 TEE_SUCCESS\n + * 如果至少有一个参数为 null，返回 TEE_ERROR_BAD_PARAMETERS + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntDiv(TEE_BigInt *dest_q, TEE_BigInt *dest_r, const TEE_BigInt *op1, const TEE_BigInt *op2); + +/** + * @brief 计算 dest = op (mod n)，使得 0 <= dest < n。 + * + * @param dest 指向 TEE_BigInt 的指针，用于存储 op (mod n) 的结果。 + * @param op 指向需要进行模运算的操作数。 + * @param n [IN] 指向模数的指针，模数必须大于 1。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntMod(TEE_BigInt *dest, const TEE_BigInt *op, const TEE_BigInt *n); + +/** + * @brief 计算 dest = (op1 + op2) (mod n)。 + * + * @param dest 指向 TEE_BigInt 的指针，用于存储 (op1 + op2)(mod n) 的结果。 + * @param op1 指向第一个操作数。 + * @param op2 指向第二个操作数。 + * @param n 指向模数的指针，模数必须大于 1。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntAddMod(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2, const TEE_BigInt *n); + +/** + * @brief 计算 dest = (op1 - op2) (mod n)。 + * + * @param dest 指向 TEE_BigInt 的指针，用于存储 (op1 - op2)(mod n) 的结果。 + * @param op1 指向第一个操作数。 + * @param op2 指向第二个操作数。 + * @param n 指向模数的指针，模数必须大于 1。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntSubMod(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2, const TEE_BigInt *n); + +/** + * @brief 计算 dest = (op1 * op2) (mod n)。 + * + * @param dest 指向 TEE_BigInt 的指针，用于存储 (op1 * op2)(mod n) 的结果。 + * @param op1 指向第一个操作数。 + * @param op2 指向第二个操作数。 + * @param n 指向模数的指针，模数必须大于 1。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntMulMod(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2, const TEE_BigInt *n); + +/** + * @brief 计算 dest = (op * op) (mod n)。 + * + * @param dest 指向 TEE_BigInt 的指针，用于存储 (op * op)(mod n) 的结果。 + * @param op 指向操作数的指针。 + * @param n [IN] 指向模数的指针，模数必须大于 1。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntSquareMod(TEE_BigInt *dest, const TEE_BigInt *op, const TEE_BigInt *n); + +/** + * @brief 计算dest，使得dest * op = 1 (mod n)。 + * + * @param dest 表示保存结果(op^–1)(mod n)的TEE_BigInt指针。 + * @param op 表示操作数的指针。 + * @param n [IN] 表示模数的指针，必须大于1。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntInvMod(TEE_BigInt *dest, const TEE_BigInt *op, const TEE_BigInt *n); + +/** + * @brief 检查gcd(op1, op2)是否等于1。 + * + * @param op1 表示第一个操作数的指针。 + * @param op2 表示第二个操作数的指针。 + * + * @return 如果gcd(op1, op2) == 1，返回true。\n + * 如果gcd(op1, op2) != 1，返回false。 + * + * @since 20 + * @version 1.0 + */ +bool TEE_BigIntRelativePrime(const TEE_BigInt *op1, const TEE_BigInt *op2); + +/** + * @brief 计算op1和op2的最大公约数。 + * + * @param gcd 表示保存op1和op2最大公约数的TEE_BigInt指针。 + * @param u 表示保存第一个系数的TEE_BigInt指针。 + * @param v 表示保存第二个系数的TEE_BigInt指针。 + * @param op1 表示第一个操作数的指针。 + * @param op2 表示第二个操作数的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntComputeExtendedGcd(TEE_BigInt *gcd, TEE_BigInt *u, TEE_BigInt *v, const TEE_BigInt *op1, + const TEE_BigInt *op2); + +/** + * @brief 对op执行概率性素性测试。 + * + * @param op 表示待测试的候选数字的指针。 + * @param confidenceLevel 表示非定论测试的期望置信度。 + * + * @return 如果op是合数，返回0。\n + * 如果op是素数，返回1。\n + * 如果测试结果不确定但op是合数的概率小于2^(-confidenceLevel)，返回-1。 + * + * @since 20 + * @version 1.0 + */ +int32_t TEE_BigIntIsProbablePrime(const TEE_BigInt *op, uint32_t confidenceLevel); + +/** + * @brief 将src转换为适合进行快速模数乘法的表示形式。 + * + * @param dest 表示初始化后的TEE_BigIntFMM内存区域的指针。 + * @param src 表示要转换的TEE_BigInt指针。 + * @param n 表示模数的指针。 + * @param context 表示之前使用{@link TEE_BigIntInitFMMContext1}初始化的上下文的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntConvertToFMM(TEE_BigIntFMM *dest, const TEE_BigInt *src, const TEE_BigInt *n, + const TEE_BigIntFMMContext *context); + +/** + * @brief 将快速模数乘法表示中的src转换回TEE_BigInt表示形式。 + * + * @param dest 表示保存转换结果的初始化后的TEE_BigInt内存区域的指针。 + * @param src 表示保存快速模数乘法表示的TEE_BigIntFMM指针。 + * @param n 表示模数的指针。 + * @param context 表示之前使用{@link TEE_BigIntInitFMMContext1}初始化的上下文的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntConvertFromFMM(TEE_BigInt *dest, const TEE_BigIntFMM *src, const TEE_BigInt *n, + const TEE_BigIntFMMContext *context); + +/** + * @brief 在快速模数乘法表示中计算dest = op1 * op2。 + * + * @param dest 表示保存结果op1 * op2的TEE_BigIntFMM指针。 + * @param op1 表示第一个操作数的指针。 + * @param op2 表示第二个操作数的指针。 + * @param n 表示模数的指针。 + * @param context 表示之前使用{@link TEE_BigIntInitFMMContext1}初始化的上下文的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_BigIntComputeFMM(TEE_BigIntFMM *dest, const TEE_BigIntFMM *op1, const TEE_BigIntFMM *op2, const TEE_BigInt *n, + const TEE_BigIntFMMContext *context); + +/** + * @brief 计算dest = (op1 ^ op2)(mod n)。 + * + * @param des 表示保存结果(op1 ^ op2)(mod n)的TEE_BigInt指针。 + * @param op1 表示第一个操作数的指针。 + * @param op2 表示第二个操作数的指针。 + * @param n 表示模数的指针。 + * @param context 表示之前使用{@link TEE_BigIntInitFMMContext1}初始化的上下文的指针，或者初始化为null。 + * + * @return 返回TEE_SUCCESS表示操作成功。\n + * 返回TEE_ERROR_NOT_SUPPORTED表示n的值不被支持。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_BigIntExpMod(TEE_BigInt *des, TEE_BigInt *op1, const TEE_BigInt *op2, const TEE_BigInt *n, + TEE_BigIntFMMContext *context); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_core_api.h b/zh-cn/native_sdk/TEEKit/tee/tee_core_api.h new file mode 100644 index 00000000..0b614d77 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_core_api.h @@ -0,0 +1,128 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_core_api.h + * + * @brief 提供用于管理可信应用 (TA) 会话的 API。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef __TEE_CORE_API_H +#define __TEE_CORE_API_H + +#include "tee_defines.h" + +#ifdef __cplusplus +extern "C" { +#endif + +#ifndef _TEE_TA_SESSION_HANDLE +/** + * @brief 定义 TA 会话的句柄。 + * + * @since 20 + */ +#define _TEE_TA_SESSION_HANDLE + +/** + * @brief 定义 TA 会话句柄类型。 + * + * @since 20 + */ +typedef uint32_t TEE_TASessionHandle; +#endif + +/** + * @brief 在 TA 实例中触发 panic。 + * + * @param panicCode 指定由 TA 定义的 panic 代码。 + * + * @since 20 + * @version 1.0 + */ +void TEE_Panic(TEE_Result panicCode); + +/** + * @brief 打开与 TA 的新会话。 + * + * @param destination 指向 TEE_UUID 结构体的指针，其中包含目标 TA 的通用唯一标识符 (UUID)。 + * @param cancellationRequestTimeout 指定超时时间（以毫秒为单位），或特殊值表示无超时。 + * @param paramTypes 指定在操作中传递的所有参数的类型。 + * @param params 指向操作中传递的参数。 + * @param session 指向用于接收客户端会话句柄的变量的指针。 + * @param returnOrigin 指向保存返回来源的变量的指针。 + * + * @return 返回 TEE_SUCCESS 表示会话已成功打开。\n + * 返回 TEE_ERROR_ITEM_NOT_FOUND 表示在可信执行环境 (TEE) 中未找到 TA。\n + * 返回 TEE_ERROR_ACCESS_DENIED 表示对 TA 的访问请求被拒绝。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_OpenTASession(const TEE_UUID *destination, uint32_t cancellationRequestTimeout, uint32_t paramTypes, + TEE_Param params[TEE_PARAMS_NUM], TEE_TASessionHandle *session, uint32_t *returnOrigin); + +/** + * @brief 关闭客户端会话。 + * + * @param session 指定要关闭的会话句柄。 + * + * @since 20 + * @version 1.0 + */ +void TEE_CloseTASession(TEE_TASessionHandle session); + +/** + * @brief 在此客户端 TA 实例与目标 TA 实例之间打开的会话中调用命令。 + * + * @param session 指定已打开的会话句柄。 + * @param cancellationRequestTimeout 指定超时时间（以毫秒为单位），或特殊值表示无超时。 + * @param commandID 指定要调用的命令的标识符。 + * @param paramTypes 指定在操作中传递的所有参数的类型。 + * @param params 指向操作中传递的参数。 + * @param returnOrigin 指向保存返回来源的变量的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_ACCESS_DENIED 表示命令调用失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_InvokeTACommand(TEE_TASessionHandle session, uint32_t cancellationRequestTimeout, uint32_t commandID, + uint32_t paramTypes, TEE_Param params[TEE_PARAMS_NUM], uint32_t *returnOrigin); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_crypto_api.h b/zh-cn/native_sdk/TEEKit/tee/tee_crypto_api.h new file mode 100644 index 00000000..7bd82f17 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_crypto_api.h @@ -0,0 +1,1172 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_crypto_api.h + * + * @brief 提供加密操作的 API。 + * + * 您可以使用这些 API 实现加密和解密。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_CRYPTO_API_H +#define TEE_CRYPTO_API_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +#ifndef NULL +/** + * @brief 定义 NULL。 + * + * @since 20 + */ +#define NULL ((void *)0) +#endif +/** + * @brief 定义最大密钥长度（单位：比特）。 + * + * @since 20 + */ +#define TEE_MAX_KEY_SIZE_IN_BITS (1024 * 8) + +/** + * @brief 定义 SW_RSA 密钥的长度（单位：字节）。 + * + * @since 20 + */ +#define SW_RSA_KEYLEN 1024 + +/** + * @brief 定义其他 Diffie-Hellman (DH) 信息的最大长度（单位：字节）。 + * + * @since 20 + */ +#define TEE_DH_MAX_SIZE_OF_OTHER_INFO 64 + +/** + * @brief 定义最大参数数量。 + * + * @since 20 + */ +#define TEE_PARAM_COUNT_MAX 9 + +/** + * @brief 枚举加密操作句柄类型。 + * + * @since 20 + */ +enum __TEE_Operation_Constants { + /** 对称加密操作 */ + TEE_OPERATION_CIPHER = 0x1, + /** 消息认证码操作 */ + TEE_OPERATION_MAC = 3, + /** 认证加密操作 */ + TEE_OPERATION_AE = 4, + /** 摘要算法操作 */ + TEE_OPERATION_DIGEST = 5, + /** 非对称加密操作 */ + TEE_OPERATION_ASYMMETRIC_CIPHER = 6, + /** 非对称签名操作 */ + TEE_OPERATION_ASYMMETRIC_SIGNATURE = 7, + /** 密钥派生操作 */ + TEE_OPERATION_KEY_DERIVATION = 8, + /** KDF 密钥派生操作 */ + TEE_OPERATION_KDF_KEY_DERIVATION = 9, +}; + +/** + * @brief 枚举加密算法。 + * + * @since 20 + */ +enum __tee_crypto_algorithm_id { + /** 非法算法 */ + TEE_ALG_INVALID = 0x0, + /** AES_ECB_NOPAD 算法 */ + TEE_ALG_AES_ECB_NOPAD = 0x10000010, + /** AES_CBC_NOPAD 算法 */ + TEE_ALG_AES_CBC_NOPAD = 0x10000110, + /** AES_CTR 算法 */ + TEE_ALG_AES_CTR = 0x10000210, + /** AES_CTS 算法 */ + TEE_ALG_AES_CTS = 0x10000310, + /** AES_XTS 算法 */ + TEE_ALG_AES_XTS = 0x10000410, + /** AES_CBC_MAC_NOPAD 算法 */ + TEE_ALG_AES_CBC_MAC_NOPAD = 0x30000110, + /** AES_CBC_MAC_PKCS5 算法 */ + TEE_ALG_AES_CBC_MAC_PKCS5 = 0x30000510, + /** AES_CMAC 算法 */ + TEE_ALG_AES_CMAC = 0x30000610, + /** AES_GMAC 算法 */ + TEE_ALG_AES_GMAC = 0x30000810, + /** AES_CCM 算法 */ + TEE_ALG_AES_CCM = 0x40000710, + /** AES_GCM 算法 */ + TEE_ALG_AES_GCM = 0x40000810, + /** DES_ECB_NOPAD 算法 */ + TEE_ALG_DES_ECB_NOPAD = 0x10000011, + /** DES_CBC_NOPAD 算法 */ + TEE_ALG_DES_CBC_NOPAD = 0x10000111, + /** DES_CBC_MAC_NOPAD 算法 */ + TEE_ALG_DES_CBC_MAC_NOPAD = 0x30000111, + /** DES_CBC_MAC_PKCS5 算法 */ + TEE_ALG_DES_CBC_MAC_PKCS5 = 0x30000511, + /** DES3_ECB_NOPAD 算法 */ + TEE_ALG_DES3_ECB_NOPAD = 0x10000013, + /** DES3_CBC_NOPAD 算法 */ + TEE_ALG_DES3_CBC_NOPAD = 0x10000113, + /** DES3_CBC_MAC_NOPAD 算法 */ + TEE_ALG_DES3_CBC_MAC_NOPAD = 0x30000113, + /** DES3_CBC_MAC_PKCS5 算法 */ + TEE_ALG_DES3_CBC_MAC_PKCS5 = 0x30000513, + /** RSASSA_PKCS1_V1_5_MD5 签名算法 */ + TEE_ALG_RSASSA_PKCS1_V1_5_MD5 = 0x70001830, + /** RSASSA_PKCS1_V1_5_SHA1 签名算法 */ + TEE_ALG_RSASSA_PKCS1_V1_5_SHA1 = 0x70002830, + /** RSASSA_PKCS1_V1_5_SHA224 签名算法 */ + TEE_ALG_RSASSA_PKCS1_V1_5_SHA224 = 0x70003830, + /** RSASSA_PKCS1_V1_5_SHA256 签名算法 */ + TEE_ALG_RSASSA_PKCS1_V1_5_SHA256 = 0x70004830, + /** RSASSA_PKCS1_V1_5_SHA384 签名算法 */ + TEE_ALG_RSASSA_PKCS1_V1_5_SHA384 = 0x70005830, + /** RSASSA_PKCS1_V1_5_SHA512 签名算法 */ + TEE_ALG_RSASSA_PKCS1_V1_5_SHA512 = 0x70006830, + /** RSASSA_PKCS1_V1_5_SM3 签名算法 */ + TEE_ALG_RSASSA_PKCS1_V1_5_SM3 = 0xF0007830, + /** RSASSA_PKCS1_V1_5_MD5_SHA1 签名算法 */ + TEE_ALG_RSASSA_PKCS1_V1_5_MD5_SHA1 = 0xF0008830, + /** RSASSA_PKCS1_PSS_MGF1_MD5 签名算法 */ + TEE_ALG_RSASSA_PKCS1_PSS_MGF1_MD5 = 0x70111930, + /** RSASSA_PKCS1_PSS_MGF1_SHA1 签名算法 */ + TEE_ALG_RSASSA_PKCS1_PSS_MGF1_SHA1 = 0x70212930, + /** RSASSA_PKCS1_PSS_MGF1_SHA224 签名算法 */ + TEE_ALG_RSASSA_PKCS1_PSS_MGF1_SHA224 = 0x70313930, + /** RSASSA_PKCS1_PSS_MGF1_SHA256 签名算法 */ + TEE_ALG_RSASSA_PKCS1_PSS_MGF1_SHA256 = 0x70414930, + /** RSASSA_PKCS1_PSS_MGF1_SHA384 签名算法 */ + TEE_ALG_RSASSA_PKCS1_PSS_MGF1_SHA384 = 0x70515930, + /** RSASSA_PKCS1_PSS_MGF1_SHA512 签名算法 */ + TEE_ALG_RSASSA_PKCS1_PSS_MGF1_SHA512 = 0x70616930, + /** RSAES_PKCS1_V1_5 加密算法 */ + TEE_ALG_RSAES_PKCS1_V1_5 = 0x60000130, + /** RSAES_PKCS1_OAEP_MGF1_SHA1 加密算法 */ + TEE_ALG_RSAES_PKCS1_OAEP_MGF1_SHA1 = 0x60210230, + /** RSAES_PKCS1_OAEP_MGF1_SHA224 加密算法 */ + TEE_ALG_RSAES_PKCS1_OAEP_MGF1_SHA224 = 0x60211230, + /** RSAES_PKCS1_OAEP_MGF1_SHA256 加密算法 */ + TEE_ALG_RSAES_PKCS1_OAEP_MGF1_SHA256 = 0x60212230, + /** RSAES_PKCS1_OAEP_MGF1_SHA384 加密算法 */ + TEE_ALG_RSAES_PKCS1_OAEP_MGF1_SHA384 = 0x60213230, + /** RSAES_PKCS1_OAEP_MGF1_SHA512 加密算法 */ + TEE_ALG_RSAES_PKCS1_OAEP_MGF1_SHA512 = 0x60214230, + /** RSA_NOPAD 加密算法 */ + TEE_ALG_RSA_NOPAD = 0x60000030, + /** DSA_SHA1 签名算法 */ + TEE_ALG_DSA_SHA1 = 0x70002131, + /** DSA_SHA224 签名算法 */ + TEE_ALG_DSA_SHA224 = 0x70003131, + /** DSA_SHA256 签名算法 */ + TEE_ALG_DSA_SHA256 = 0x70004131, + /** DH 密钥协商算法 */ + TEE_ALG_DH_DERIVE_SHARED_SECRET = 0x80000032, + /** MD5 摘要算法 */ + TEE_ALG_MD5 = 0x50000001, + /** SHA1 摘要算法 */ + TEE_ALG_SHA1 = 0x50000002, + /** SHA224 摘要算法 */ + TEE_ALG_SHA224 = 0x50000003, + /** SHA256 摘要算法 */ + TEE_ALG_SHA256 = 0x50000004, + /** SHA384 摘要算法 */ + TEE_ALG_SHA384 = 0x50000005, + /** SHA512 摘要算法 */ + TEE_ALG_SHA512 = 0x50000006, + /** HMAC_MD5 消息认证算法 */ + TEE_ALG_HMAC_MD5 = 0x30000001, + /** HMAC_SHA1 消息认证算法 */ + TEE_ALG_HMAC_SHA1 = 0x30000002, + /** HMAC_SHA224 消息认证算法 */ + TEE_ALG_HMAC_SHA224 = 0x30000003, + /** HMAC_SHA256 消息认证算法 */ + TEE_ALG_HMAC_SHA256 = 0x30000004, + /** HMAC_SHA384 消息认证算法 */ + TEE_ALG_HMAC_SHA384 = 0x30000005, + /** HMAC_SHA512 消息认证算法 */ + TEE_ALG_HMAC_SHA512 = 0x30000006, + /** HMAC_SM3 消息认证算法 */ + TEE_ALG_HMAC_SM3 = 0x30000007, + /** AES_ECB_PKCS5 加密算法 */ + TEE_ALG_AES_ECB_PKCS5 = 0x10000020, + /** AES_CBC_PKCS5 加密算法 */ + TEE_ALG_AES_CBC_PKCS5 = 0x10000220, + /** AES_CBC_ISO_PADDING 加密算法 */ + TEE_ALG_AES_CBC_ISO_PADDING = 0x10000330, + /** ECDSA_SHA1 签名算法 */ + TEE_ALG_ECDSA_SHA1 = 0x70001042, + /** ECDSA_SHA224 签名算法 */ + TEE_ALG_ECDSA_SHA224 = 0x70002042, + /** ECDSA_SHA256 签名算法 */ + TEE_ALG_ECDSA_SHA256 = 0x70003042, + /** ECDSA_SHA384 签名算法 */ + TEE_ALG_ECDSA_SHA384 = 0x70004042, + /** ECDSA_SHA512 签名算法 */ + TEE_ALG_ECDSA_SHA512 = 0x70005042, + /** ED25519 签名算法 */ + TEE_ALG_ED25519 = 0x70005043, + /** ECDH 密钥协商算法 */ + TEE_ALG_ECDH_DERIVE_SHARED_SECRET = 0x80000042, + /** X25519 密钥协商算法 */ + TEE_ALG_X25519 = 0x80000044, + /** ECC 算法通用标识 */ + TEE_ALG_ECC = 0x80000001, + /** ECDSA_P192 签名算法 */ + TEE_ALG_ECDSA_P192 = 0x70001042, + /** ECDSA_P224 签名算法 */ + TEE_ALG_ECDSA_P224 = 0x70002042, + /** ECDSA_P256 签名算法 */ + TEE_ALG_ECDSA_P256 = 0x70003042, + /** ECDSA_P384 签名算法 */ + TEE_ALG_ECDSA_P384 = 0x70004042, + /** ECDSA_P521 签名算法 */ + TEE_ALG_ECDSA_P521 = 0x70005042, + /** ECDH_P192 密钥协商算法 */ + TEE_ALG_ECDH_P192 = 0x80001042, + /** ECDH_P224 密钥协商算法 */ + TEE_ALG_ECDH_P224 = 0x80002042, + /** ECDH_P256 密钥协商算法 */ + TEE_ALG_ECDH_P256 = 0x80003042, + /** ECDH_P384 密钥协商算法 */ + TEE_ALG_ECDH_P384 = 0x80004042, + /** ECDH_P521 密钥协商算法 */ + TEE_ALG_ECDH_P521 = 0x80005042, + /** SIP_HASH 哈希算法 */ + TEE_ALG_SIP_HASH = 0xF0000002, + /** SM2_DSA_SM3 国密签名算法 */ + TEE_ALG_SM2_DSA_SM3 = 0x70006045, + /** SM2_PKE 国密加密算法 */ + TEE_ALG_SM2_PKE = 0x80000045, + /** SM3 摘要算法 */ + TEE_ALG_SM3 = 0x50000007, + /** SM4_ECB_NOPAD 加密算法 */ + TEE_ALG_SM4_ECB_NOPAD = 0x10000014, + /** SM4_ECB_PKCS7 加密算法 */ + TEE_ALG_SM4_ECB_PKCS7 = 0x10000024, + /** SM4_CBC_NOPAD 加密算法 */ + TEE_ALG_SM4_CBC_NOPAD = 0x10000114, + /** SM4_CBC_PKCS7 加密算法 */ + TEE_ALG_SM4_CBC_PKCS7 = 0xF0000003, + /** SM4_CTR 加密算法 */ + TEE_ALG_SM4_CTR = 0x10000214, + /** SM4_CFB128 加密算法 */ + TEE_ALG_SM4_CFB128 = 0xF0000000, + /** SM4_XTS 加密算法 */ + TEE_ALG_SM4_XTS = 0x10000414, + /** SM4_OFB 加密算法 */ + TEE_ALG_SM4_OFB = 0x10000514, + /** AES_OFB 加密算法 */ + TEE_ALG_AES_OFB = 0x10000510, + /** AES_CFB128 加密算法 */ + TEE_ALG_AES_CFB128 = 0xF0000610, + /** SM4_GCM 加密算法 */ + TEE_ALG_SM4_GCM = 0xF0000005, + /** PBKDF2_HMAC_SHA1 密钥派生算法 */ + TEE_ALG_PBKDF2_HMAC_SHA1_DERIVE_KEY = 0x800020C2, + /** PBKDF2_HMAC_SHA256 密钥派生算法 */ + TEE_ALG_PBKDF2_HMAC_SHA256_DERIVE_KEY= 0x800040C2, + /** PBKDF2_HMAC_SHA384 密钥派生算法 */ + TEE_ALG_PBKDF2_HMAC_SHA384_DERIVE_KEY= 0x800050C2, + /** PBKDF2_HMAC_SHA512 密钥派生算法 */ + TEE_ALG_PBKDF2_HMAC_SHA512_DERIVE_KEY= 0x800060C2, + /** HKDF 密钥派生算法 */ + TEE_ALG_HKDF = 0x80000047, + /** PRF 伪随机函数算法 */ + TEE_ALG_PRF = 0xF0000006, +}; + +/** + * @brief 定义了加密算法标识符。 + * @see __tee_crypto_algorithm_id + * + * @since 20 + */ +typedef enum __tee_crypto_algorithm_id tee_crypto_algorithm_id; + +/** + * @brief 没有可用元素。 + * + * @since 20 + */ +#define TEE_OPTIONAL_ELEMENT_NONE 0x00000000 + +/** + * @brief 枚举支持的椭圆曲线密码学（ECC）曲线。 + * + * @since 20 + */ +typedef enum { + /** CURVE_NIST_P192 */ + TEE_ECC_CURVE_NIST_P192 = 0x00000001, + /** CURVE_NIST_P224 */ + TEE_ECC_CURVE_NIST_P224 = 0x00000002, + /** CURVE_NIST_P256 */ + TEE_ECC_CURVE_NIST_P256 = 0x00000003, + /** CURVE_NIST_P384 */ + TEE_ECC_CURVE_NIST_P384 = 0x00000004, + /** CURVE_NIST_P521 */ + TEE_ECC_CURVE_NIST_P521 = 0x00000005, + /** CURVE_SM2 256 位 */ + TEE_ECC_CURVE_SM2 = 0x00000300, + /** CURVE_25519 256 位 */ + TEE_ECC_CURVE_25519 = 0x00000200, +} TEE_ECC_CURVE; + +/** + * @brief 枚举掩码生成函数（MGF1）模式。 + * + * @since 20 + */ +typedef enum { + /** 使用SHA-1哈希算法 */ + TEE_DH_HASH_SHA1_mode = 0, + /** 使用SHA-224哈希算法 */ + TEE_DH_HASH_SHA224_mode = 1, + /** 使用SHA-256哈希算法 */ + TEE_DH_HASH_SHA256_mode = 2, + /** 使用SHA-384哈希算法 */ + TEE_DH_HASH_SHA384_mode = 3, + /** 使用SHA-512哈希算法 */ + TEE_DH_HASH_SHA512_mode = 4, + /** 哈希模式数量 */ + TEE_DH_HASH_NumOfModes, +} TEE_DH_HASH_Mode; + +/** + * @brief 枚举 Diffie-Hellman 操作模式。 + * + * @since 20 + */ +typedef enum { + /** PKCS3 模式 */ + TEE_DH_PKCS3_mode =0, + /** ANSI X9.42 算法模式 */ + TEE_DH_ANSI_X942_mode = 1, + /** 模式数量 */ + TEE_DH_NumOfModes, +} TEE_DH_OpMode_t; + +/** + * @brief 定义 TEE_DH_DerivFuncMode 的枚举类型。 + * + * @since 20 + */ +typedef enum { + /** ASN.1 派生模式 */ + TEE_DH_ASN1_DerivMode = 0, + /** 拼接派生模式 */ + TEE_DH_ConcatDerivMode = 1, + /** X9.63 派生模式（与拼接派生模式相同） */ + TEE_DH_X963_DerivMode =TEE_DH_ConcatDerivMode, + /** OMADRM 派生模式 */ + TEE_DH_OMADRM_DerivMode = 2, + /** ISO18033 KDF1 派生模式 */ + TEE_DH_ISO18033_KDF1_DerivMode = 3, + /** ISO18033 KDF2 派生模式 */ + TEE_DH_ISO18033_KDF2_DerivMode = 4, + /** 模式数量 */ + TEE_DH_DerivFunc_NumOfModes, +} TEE_DH_DerivFuncMode; + +/** + * @brief 枚举加密操作中使用的对象属性类型。 + * + * @since 20 + */ +enum __TEE_DK_ObjectAttribute { + /** 指向共享密钥值的指针。 */ + TEE_DK_SECRECT = 0, + /** 指向包含其他数据的结构体的指针。 */ + TEE_DK_OTHER, + /** 要使用的哈希函数的枚举 ID。 */ + TEE_DK_HASH_MODE, + /** 派生函数模式的枚举 ID。 */ + TEE_DK_DERIVATION_MODE +}; + +/** + * @brief 定义 __TEE_DK_ObjectAttribute 的类型别名结构体。 + * + * @see __TEE_DK_ObjectAttribute + * + * @since 20 + */ +typedef enum __TEE_DK_ObjectAttribute tee_dk_objectattribute; + +/** + * @brief 枚举加密操作模式。 + * + * @since 20 + */ +enum __TEE_OperationMode { + /** 加密 */ + TEE_MODE_ENCRYPT = 0x0, + /** 解密 */ + TEE_MODE_DECRYPT, + /** 签名 */ + TEE_MODE_SIGN, + /** 签名验证 */ + TEE_MODE_VERIFY, + /** 消息认证码 (MAC) */ + TEE_MODE_MAC, + /** 摘要 */ + TEE_MODE_DIGEST, + /** 密钥派生 */ + TEE_MODE_DERIVE +}; + +/** + * @brief 枚举加密操作状态。 + * + * @since 20 + */ +enum tee_operation_state { + /** 初始状态 */ + TEE_OPERATION_STATE_INITIAL = 0x00000000, + /** 激活状态 */ + TEE_OPERATION_STATE_ACTIVE = 0x00000001, +}; + +/** + * @brief 定义加密操作的模式类型。 + * + * @since 20 + */ +typedef uint32_t TEE_OperationMode; + +/** + * @brief 定义 TEE_DH_OtherInfo 的结构体。 + * + * @since 20 + */ +typedef struct { + /** 对象标识符（OID） */ + uint8_t algorithm_id[TEE_DH_MAX_SIZE_OF_OTHER_INFO]; + /** AlgorithmID 的长度 */ + uint32_t size_of_algorithm_id; + /** 发送方的公有信息 */ + uint8_t party_u_info[TEE_DH_MAX_SIZE_OF_OTHER_INFO]; + /** PartyUInfo 的长度 */ + uint32_t size_of_party_u_info; + /** 接收方的公有信息 */ + uint8_t party_v_info[TEE_DH_MAX_SIZE_OF_OTHER_INFO]; + /** PartyVInfo 的长度 */ + uint32_t size_of_party_v_info; + /** 共享的私有信息 */ + uint8_t supp_priv_info[TEE_DH_MAX_SIZE_OF_OTHER_INFO]; + /** SuppPrivInfo 的长度 */ + uint32_t size_of_supp_priv_info; + /** 共享的公有信息 */ + uint8_t supp_pub_info[TEE_DH_MAX_SIZE_OF_OTHER_INFO]; + /** SuppPubInfo 的长度 */ + uint32_t size_of_supp_pub_info; +} TEE_DH_OtherInfo; + +/** + * @brief 定义操作信息。 + * + * @since 20 + */ +struct __TEE_OperationInfo { + /** 算法ID */ + uint32_t algorithm; + /** 操作类型 */ + uint32_t operationClass; + /** 操作模式 */ + uint32_t mode; + /** 摘要长度 */ + uint32_t digestLength; + /** 最大密钥长度 */ + uint32_t maxKeySize; + /** 密钥长度 */ + uint32_t keySize; + /** 所需的密钥使用 */ + uint32_t requiredKeyUsage; + /** 句柄状态 */ + uint32_t handleState; + /** 密钥 */ + void *keyValue; +}; + +/** + * @brief 定义 __TEE_OperationInfo 结构体。 + * + * @see __TEE_OperationInfo + */ +typedef struct __TEE_OperationInfo TEE_OperationInfo; + +/** + * @brief 定义存储在 OperationInfo 中的密钥信息。 + * + * @since 20 + */ +typedef struct { + /** 密钥长度 */ + uint32_t keySize; + /** 所需的密钥使用 */ + uint32_t requiredKeyUsage; +} TEE_OperationInfoKey; + +/** + * @brief 定义关于操作的信息。 + * + * @since 20 + */ +typedef struct { + /** 算法ID */ + uint32_t algorithm; + /** 操作类型 */ + uint32_t operationClass; + /** 操作模式 */ + uint32_t mode; + /** 摘要长度 */ + uint32_t digestLength; + /** 最大密钥长度 */ + uint32_t maxKeySize; + /** 句柄状态 */ + uint32_t handleState; + /** 操作状态 */ + uint32_t operationState; + /** 密钥数量 */ + uint32_t numberOfKeys; + /** 密钥信息 */ + TEE_OperationInfoKey keyInformation[]; +} TEE_OperationInfoMultiple; + +/** + * @brief 定义加密操作句柄。 + * + * @since 20 + */ +struct __TEE_OperationHandle { + /** 算法ID */ + uint32_t algorithm; + /** 操作类型 */ + uint32_t operationClass; + /** 操作模式 */ + uint32_t mode; + /** 摘要长度 */ + uint32_t digestLength; + /** 最大密钥长度 */ + uint32_t maxKeySize; + /** 密钥长度 */ + uint32_t keySize; + /** 第二个密钥长度 */ + uint32_t keySize2; + /** 必要的密钥使用方式 */ + uint32_t requiredKeyUsage; + /** 句柄状态 */ + uint32_t handleState; + /** 密钥 */ + void *keyValue; + /** 第二个密钥 */ + void *keyValue2; + /** 加密上下文 */ + void *crypto_ctxt; + /** HMAC剩余上下文 */ + void *hmac_rest_ctext; + /** 初始化向量（IV） */ + void *IV; + /** 公钥 */ + void *publicKey; + /** 公钥长度 */ + uint32_t publicKeyLen; + /** 私钥 */ + void *privateKey; + /** 私钥长度 */ + uint32_t privateKeyLen; + /** 初始化向量（IV）长度 */ + uint32_t IVLen; + /** 操作锁 */ + pthread_mutex_t operation_lock; + /** HAL信息 */ + void *hal_info; +}; + +/** + * @brief 定义用于转换整数的数据。 + * + * @since 20 + */ +typedef struct { + /** 源数据 */ + uint32_t src; + /** 目标数据 */ + uint32_t dest; +} crypto_uint2uint; + +/** + * @brief 定义RSA公钥的最大长度。 + * + * @since 20 + */ +#define RSA_PUBKEY_MAXSIZE sizeof(CRYS_RSAUserPubKey_t) + +/** + * @brief 定义RSA私钥的最大长度。 + * + * @since 20 + */ +#define RSA_PRIVKEY_MAXSIZE sizeof(CRYS_RSAUserPrivKey_t) + +/** + * @brief 定义一个结构体来保存输入和输出数据。 + * + * @since 20 + */ +typedef struct { + /** 源数据 */ + void *src_data; + /** 源数据的长度 */ + size_t src_len; + /** 目标数据 */ + void *dest_data; + /** 目标数据的长度 */ + size_t *dest_len; +} operation_src_dest; + +/** + * @brief 定义AE初始化数据。 + * + * @since 20 + */ +typedef struct { + /** nonce */ + void *nonce; + /** nonce的长度 */ + size_t nonce_len; + /** 标签的长度 */ + uint32_t tag_len; + /** 附加认证数据（AAD）的长度 */ + size_t aad_len; + /** 有效负载的长度 */ + size_t payload_len; +} operation_ae_init; + +/** + * @brief 定义 __TEE_OperationHandle 结构体。 + * + * @see __TEE_OperationHandle + * + * @since 20 + */ +typedef struct __TEE_OperationHandle TEE_OperationHandleVar; + +/** + * @brief 定义 __TEE_ObjectHandle 结构体。 + * + * @since 20 + */ +typedef struct __TEE_ObjectHandle TEE_ObjectHandleVar; + +/** + * @brief 分配操作句柄。 + * + * @param operation 操作句柄的指针。 + * @param algorithm 密码算法。 + * @param mode 操作模式。 + * @param maxKeySize 密钥的最大长度。 + * + * @return 返回 TEE_SUCCESS 表示成功分配操作句柄。\n + * 返回 TEE_ERROR_OUT_OF_MEMORY 表示没有足够的内存来分配操作句柄。\n + * 返回 TEE_ERROR_NOT_SUPPORTED 表示指定的算法不被支持。\n + * 返回 TEE_ERROR_GENERIC 表示由于其他错误导致操作失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_AllocateOperation(TEE_OperationHandle *operation, uint32_t algorithm, uint32_t mode, + uint32_t maxKeySize); + +/** +* @brief 释放操作句柄。 +* +* @param operation 要释放的操作句柄。 +* +* @since 20 +* @version 1.0 +*/ +void TEE_FreeOperation(TEE_OperationHandle operation); + +/** +* @brief 获取操作信息。 +* +* @param operation 操作句柄。 +* @param operationInfo 指向操作信息的指针。 +* +* @since 20 +* @version 1.0 +*/ +void TEE_GetOperationInfo(const TEE_OperationHandle operation, TEE_OperationInfo *operationInfo); + +/** +* @brief 重置操作句柄。 +* +* @param operation 要重置的操作句柄。 +* +* @since 20 +* @version 1.0 +*/ +void TEE_ResetOperation(TEE_OperationHandle operation); + +/** + * @brief 设置操作的密钥。 + * + * @param operation 操作句柄。 + * @param key 密钥。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_BAD_PARAMETERS 表示由于无效参数导致操作失败。\n + * 返回 TEE_ERROR_OUT_OF_MEMORY 表示没有足够的内存来完成此操作。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SetOperationKey(TEE_OperationHandle operation, const TEE_ObjectHandle key); + +/** + * @brief 设置两个密钥供操作使用。 + * + * @param operation 操作句柄。 + * @param key1 密钥 1。 + * @param key2 密钥 2。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_BAD_PARAMETERS 表示由于无效参数导致操作失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SetOperationKey2(TEE_OperationHandle operation, const TEE_ObjectHandle key1, + const TEE_ObjectHandle key2); + +/** + * @brief 复制操作句柄。 + * + * @param dstOperation 目标操作句柄。 + * @param srcOperation 源操作句柄。 + * + * @since 20 + * @version 1.0 + */ +void TEE_CopyOperation(TEE_OperationHandle dstOperation, const TEE_OperationHandle srcOperation); + +/** + * @brief 初始化上下文以启动加密操作。 + * + * @param operation 操作句柄。 + * @param IV 指向存储操作IV的缓冲区的指针。表示此参数不使用，则设置为 NULL。 + * @param IVLen IV缓冲区的长度。 + * + * @since 20 + * @version 1.0 + */ +void TEE_CipherInit(TEE_OperationHandle operation, const void *IV, size_t IVLen); + +/** + * @brief 更新加密操作的数据。 + * + * @param operation 操作句柄。 + * @param srcData 指向源数据的指针。 + * @param srcLen 源数据的长度。 + * @param destData 指向目标数据的指针。 + * @param destLen 指向目标数据长度的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_BAD_PARAMETERS 表示由于无效参数导致操作失败。\n + * 返回 TEE_ERROR_GENERIC 表示由于其他错误导致操作失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_CipherUpdate(TEE_OperationHandle operation, const void *srcData, size_t srcLen, void *destData, + size_t *destLen); + +/** + * @brief 完成加密操作。 + * + * @param operation 操作句柄。 + * @param srcData 指向源数据的指针。 + * @param srcLen 源数据的长度。 + * @param destData 指向目标数据的指针。 + * @param destLen 指向目标数据长度的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_BAD_PARAMETERS 表示由于无效参数导致操作失败。\n + * 返回 TEE_ERROR_GENERIC 表示由于其他错误导致操作失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_CipherDoFinal(TEE_OperationHandle operation, const void *srcData, size_t srcLen, void *destData, + size_t *destLen); + +/** + * @brief 更新摘要。 + * + * @param operation 操作句柄。 + * @param chunk 指向要散列的数据块的指针。 + * @param chunkSize 数据块的长度。 + * + * @since 20 + * @version 1.0 + */ +void TEE_DigestUpdate(TEE_OperationHandle operation, const void *chunk, size_t chunkSize); + +/** + * @brief 完成消息摘要操作。 + * + * @param operation 操作句柄。 + * @param chunk 指向要散列的数据块的指针。 + * @param chunkLen 数据块的长度。 + * @param hash 指向存储消息哈希值的缓冲区的指针。 + * @param hashLen 指向哈希长度的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_GENERIC 表示操作失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_DigestDoFinal(TEE_OperationHandle operation, const void *chunk, size_t chunkLen, void *hash, + size_t *hashLen); + +/** + * @brief 初始化MAC操作。 + * + * @param operation 操作句柄。 + * @param IV 指向存储操作IV的缓冲区的指针。表示此参数不使用，则设置为 NULL。 + * @param IVLen IV缓冲区的长度。 + * + * @since 20 + * @version 1.0 + */ +void TEE_MACInit(TEE_OperationHandle operation, void *IV, size_t IVLen); + +/** + * @brief 更新MAC。 + * + * @param operation 操作句柄。 + * @param chunk 指向MAC数据块的指针。 + * @param chunkSize 数据块的大小。 + * + * @since 20 + * @version 1.0 + */ +void TEE_MACUpdate(TEE_OperationHandle operation, const void *chunk, size_t chunkSize); + +/** + * @brief MAC操作完成，处理最后一块消息并计算MAC。 + * + * @param operation 操作句柄。 + * @param message 指向包含最后一块消息数据的缓冲区的指针。 + * @param messageLen 消息缓冲区的长度。 + * @param mac 指向存储计算出的MAC的缓冲区的指针。 + * @param macLen 指向MAC缓冲区长度的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_GENERIC 表示操作失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_MACComputeFinal(TEE_OperationHandle operation, const void *message, size_t messageLen, void *mac, + size_t *macLen); + +/** + * @brief 完成MAC操作并与传入的MAC进行比较。 + * + * @param operation 操作句柄。 + * @param message 指向包含最后一块消息数据的缓冲区的指针。 + * @param messageLen 消息缓冲区的长度。 + * @param mac 指向存储计算出的MAC的缓冲区的指针。 + * @param macLen MAC缓冲区的长度。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_GENERIC 表示操作失败。\n + * 返回 TEE_ERROR_MAC_INVALID 表示计算的MAC与传入的MAC不匹配。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_MACCompareFinal(TEE_OperationHandle operation, const void *message, size_t messageLen, const void *mac, + const size_t macLen); + +/** + * @brief 推导一个密钥。 + * + * @param operation 操作句柄。 + * @param params 指向此操作的参数的指针。 + * @param paramCount 参数的数量。 + * @param derivedKey 推导出的密钥。 + * + * @since 20 + * @version 1.0 + */ +void TEE_DeriveKey(TEE_OperationHandle operation, const TEE_Attribute *params, uint32_t paramCount, +TEE_ObjectHandle derivedKey); + +/** + * @brief 生成随机数据。 + * + * @param randomBuffer 指向存储生成的随机数据的缓冲区的指针。 + * @param randomBufferLen 随机数据缓冲区的长度。 + * + * @since 20 + * @version 1.0 + */ +void TEE_GenerateRandom(void *randomBuffer, size_t randomBufferLen); + +/** + * @brief 初始化AE操作。 + * + * @param operation 操作句柄。 + * @param nonce 指向存储nonce的缓冲区的指针。 + * @param nonceLen nonce的长度。 + * @param tagLen tag的长度。 + * @param AADLen AAD的长度。 + * @param payloadLen payload的长度。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_GENERIC 表示操作由于其他错误失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_AEInit(TEE_OperationHandle operation, void *nonce, size_t nonceLen, uint32_t tagLen, size_t AADLen, + size_t payloadLen); + +/** + * @brief 更新AE操作中的AAD。 + * + * @param operation 操作句柄。 + * @param AADdata 指向新AAD的指针。 + * @param AADdataLen 新AAD的长度。 + * + * @since 20 + * @version 1.0 + */ +void TEE_AEUpdateAAD(TEE_OperationHandle operation, const void *AADdata, size_t AADdataLen); + +/** + * @brief 更新AE操作中的数据。 + * + * @param operation 操作句柄。 + * @param srcData 指向源数据的指针。 + * @param srcLen 源数据的长度。 + * @param destData 指向目标数据的指针。 + * @param destLen 指向目标数据长度的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_GENERIC 表示操作由于其他错误失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_AEUpdate(TEE_OperationHandle operation, void *srcData, size_t srcLen, void *destData, size_t *destLen); + +/** + * @brief 完成AE加密操作。 + * + * @param operation 操作句柄。 + * @param srcData 指向源数据的指针。 + * @param srcLen 源数据的长度。 + * @param destData 指向目标数据的指针。 + * @param destLen 指向目标数据长度的指针。 + * @param tag 指向存储计算出的tag的缓冲区的指针。 + * @param tagLen 指向tag缓冲区长度的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_GENERIC 表示操作由于其他错误失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_AEEncryptFinal(TEE_OperationHandle operation, void *srcData, size_t srcLen, void *destData, + size_t *destLen, void *tag, size_t *tagLen); + +/** + * @brief 完成AE解密操作。 + * + * @param operation 操作句柄。 + * @param srcData 指向源数据的指针。 + * @param srcLen 源数据的长度。 + * @param destData 指向目标数据的指针。 + * @param destLen 指向目标数据长度的指针。 + * @param tag 指向存储计算出的tag的缓冲区的指针。 + * @param tagLen tag缓冲区的长度。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_MAC_INVALID 表示计算出的tag与提供的tag不匹配。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_AEDecryptFinal(TEE_OperationHandle operation, void *srcData, size_t srcLen, void *destData, + size_t *destLen, void *tag, size_t tagLen); + +/** + * @brief 执行非对称加密。 + * + * @param operation 操作句柄。 + * @param params 指向此操作的参数的指针。 + * @param paramCount 参数的数量。 + * @param srcData 指向源数据的指针。 + * @param srcLen 源数据的长度。 + * @param destData 指向目标数据的指针。 + * @param destLen 指向目标数据长度的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_BAD_PARAMETERS 表示操作因无效参数失败。\n + * 返回 TEE_ERROR_GENERIC 表示操作因其他错误失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_AsymmetricEncrypt(TEE_OperationHandle operation, const TEE_Attribute *params, uint32_t paramCount, + void *srcData, size_t srcLen, void *destData, size_t *destLen); + +/** + * @brief 执行非对称解密。 + * + * @param operation 操作句柄。 + * @param params 指向此操作的参数的指针。 + * @param paramCount 参数的数量。 + * @param srcData 指向源数据的指针。 + * @param srcLen 源数据的长度。 + * @param destData 指向目标数据的指针。 + * @param destLen 指向目标数据长度的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_BAD_PARAMETERS 表示操作因无效参数失败。\n + * 返回 TEE_ERROR_GENERIC 表示操作因其他错误失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_AsymmetricDecrypt(TEE_OperationHandle operation, const TEE_Attribute *params, uint32_t paramCount, + void *srcData, size_t srcLen, void *destData, size_t *destLen); + +/** + * @brief 在非对称操作中对消息摘要进行签名。 + * + * @param operation 操作句柄。 + * @param params 指向此操作参数的指针。 + * @param paramCount 参数的数量。 + * @param digest 指向消息摘要的指针。 + * @param digestLen 消息摘要的长度。 + * @param signature 指向签名的指针。 + * @param signatureLen 指向签名长度的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_BAD_PARAMETERS 表示操作因无效参数失败。\n + * 返回 TEE_ERROR_GENERIC 表示操作因其他错误失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_AsymmetricSignDigest(TEE_OperationHandle operation, const TEE_Attribute *params, uint32_t paramCount, + void *digest, size_t digestLen, void *signature, size_t *signatureLen); + +/** + * @brief 在非对称操作中验证消息摘要签名。 + * + * @param operation 操作句柄。 + * @param params 指向此操作参数的指针。 + * @param paramCount 参数的数量。 + * @param digest 指向消息摘要的指针。 + * @param digestLen 消息摘要的长度。 + * @param signature 指向签名的指针。 + * @param signatureLen 签名的长度。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_BAD_PARAMETERS 表示操作因无效参数失败。\n + * 返回 TEE_ERROR_GENERIC 表示操作因其他错误失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_AsymmetricVerifyDigest(TEE_OperationHandle operation, const TEE_Attribute *params, uint32_t paramCount, + void *digest, size_t digestLen, void *signature, size_t signatureLen); + +/** + * @brief 获取涉及多个密钥的操作信息。 + * + * @param operation 操作句柄。 + * @param operationInfoMultiple 指向获取的操作信息的指针。 + * @param operationSize [IN/OUT] 指向操作信息大小的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_BAD_PARAMETERS 表示操作因无效参数失败。\n + * 返回 TEE_ERROR_SHORT_BUFFER 表示操作信息缓冲区不足以容纳获取到的信息。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_GetOperationInfoMultiple(TEE_OperationHandle operation, TEE_OperationInfoMultiple *operationInfoMultiple, + const size_t *operationSize); + +/** + * @brief 检查算法是否被支持。 + * + * @param algId 要检查的算法。 + * @param element 密码元素。 + * + * @return 返回 TEE_SUCCESS 表示算法被支持。\n + * 返回 TEE_ERROR_NOT_SUPPORTED 表示算法不被支持。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_IsAlgorithmSupported(uint32_t algId, uint32_t element); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_crypto_hal.h b/zh-cn/native_sdk/TEEKit/tee/tee_crypto_hal.h new file mode 100644 index 00000000..8f5391a5 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_crypto_hal.h @@ -0,0 +1,101 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_crypto_hal.h + * + * @brief 提供密码学操作的 API。 + * + * 您可以使用这些 API 来实现加密和解密。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_CRYPTO_HAL_H +#define TEE_CRYPTO_HAL_H + +#include "tee_crypto_api.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 枚举加密引擎的类型。 + * + * @since 20 + */ +enum CRYPTO_ENGINE { + /** 基于硬件的 DX 加密引擎。 */ + DX_CRYPTO = 0, + /** 基于硬件的 MSPE 加密引擎。 */ + EPS_CRYPTO = 1, + /** 基于软件的加密引擎，例如 OpenSSL。 */ + SOFT_CRYPTO = 2, + /** SEC 加密引擎，常用于车载平台。 */ + SEC_CRYPTO = 3, + /** 加密引擎的最大取值。 */ + CRYPTO_ENGINE_MAX = 1024, +}; + +/** + * @brief 设置加密和解密引擎到操作中。 + * + * @param operation [IN] 指定操作的句柄。 + * @param crypto [IN] 指定要设置的加密引擎。 + * + * @return 返回 TEE_SUCCESS 如果操作成功。\n + * 返回 TEE_ERROR_BAD_PARAMETERS 如果 operation 为 null 或 crypto 无效。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SetCryptoFlag(TEE_OperationHandle operation, uint32_t crypto); + +/** + * @brief 设置加密和解密引擎到对象中。 + * + * @param object [IN] 指定对象的句柄。 + * @param crypto [IN] 指定要设置的加密引擎。 + * + * @return 返回 TEE_SUCCESS 如果操作成功。\n + * 返回 TEE_ERROR_BAD_PARAMETERS 如果 object 为 null 或 crypto 无效。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SetObjectFlag(TEE_ObjectHandle object, uint32_t crypto); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_defines.h b/zh-cn/native_sdk/TEEKit/tee/tee_defines.h new file mode 100644 index 00000000..f4957098 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_defines.h @@ -0,0 +1,968 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_defines.h + * + * @brief 定义TEE的基本数据类型和数据结构。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef __TEE_DEFINES_H +#define __TEE_DEFINES_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +#ifndef TA_EXPORT +/** + * @brief 定义TA导出宏。 + * + * @since 20 + */ +#define TA_EXPORT +#endif + +/** + * @brief 定义tee互斥锁句柄类型。 + * + * @since 20 + */ +typedef int *tee_mutex_handle; + +/** + * @brief 定义API级别1.1.1。 + * + * @since 20 + */ +#define API_LEVEL1_1_1 2 + +/** + * @brief 定义API级别1.2。 + * + * @since 20 + */ +#define API_LEVEL1_2 3 + +/** + * @brief 定义TEE参数数量。 + * + * @since 20 + */ +#define TEE_PARAMS_NUM 4 + +#ifndef NULL +/** + * @brief 表示空指针常量。 + * + * @since 20 + */ +#define NULL ((void *)0) +#endif + +/** + * @brief 用于标记未使用的参数。 + * + * @since 20 + */ +#define PARAM_NOT_USED(val) ((void)(val)) + +/** + * @brief 枚举TEE参数。 + * + * @since 20 + */ +typedef union { + struct { + /** 指向内存缓冲区的指针。 */ + void *buffer; + /** 内存缓冲区的大小。 */ + size_t size; + } memref; + struct { + /** 第一个值。 */ + unsigned int a; + /** 第二个值。 */ + unsigned int b; + } value; + struct { + /** 指向共享内存缓冲区的指针。 */ + void *buffer; + /** 共享内存缓冲区的大小。 */ + size_t size; + } sharedmem; +} TEE_Param; + +/** + * @brief 定义TEE参数类型组合宏。 + * + * @since 20 + */ +#define TEE_PARAM_TYPES(param0Type, param1Type, param2Type, param3Type) \ + (((param3Type) << 12) | ((param2Type) << 8) | ((param1Type) << 4) | (param0Type)) + +/** + * @brief 从参数类型组合中获取指定索引的参数类型。 + * + * @since 20 + */ +#define TEE_PARAM_TYPE_GET(paramTypes, index) (((paramTypes) >> (4U * (index))) & 0x0F) + +/** + * @brief 检查参数类型。 + * + * @param param_to_check 表示要检查的参数值。 + * @param valid0 表示第一个参数类型要检查的值。 + * @param valid1 表示第二个参数类型要检查的值。 + * @param valid2 表示第三个参数类型要检查的值。 + * @param valid3 表示第四个参数类型要检查的值。 + * + * @return 如果参数类型正确，返回true。 + * 如果参数类型不正确，返回false。 + * + * @since 20 + */ +static inline bool check_param_type(uint32_t param_to_check, uint32_t valid0, uint32_t valid1, uint32_t valid2, + uint32_t valid3) +{ + return (TEE_PARAM_TYPES(valid0, valid1, valid2, valid3) == param_to_check); +} + +/** + * @brief 枚举TEE参数类型。 + * + * @since 20 + */ +enum TEE_ParamType { + /** 无参数类型。 */ + TEE_PARAM_TYPE_NONE = 0x0, + /** 输入参数类型 */ + TEE_PARAM_TYPE_VALUE_INPUT = 0x1, + /** 输出参数类型 */ + TEE_PARAM_TYPE_VALUE_OUTPUT = 0x2, + /** 输入输出参数类型 */ + TEE_PARAM_TYPE_VALUE_INOUT = 0x3, + /** 输入内存引用参数类型。 */ + TEE_PARAM_TYPE_MEMREF_INPUT = 0x5, + /** 输出内存引用参数类型。 */ + TEE_PARAM_TYPE_MEMREF_OUTPUT = 0x6, + /** 输入输出内存引用参数类型。 */ + TEE_PARAM_TYPE_MEMREF_INOUT = 0x7, + /** 输入ION参数类型。 */ + TEE_PARAM_TYPE_ION_INPUT = 0x8, + /** 输入ION单链表参数类型。 */ + TEE_PARAM_TYPE_ION_SGLIST_INPUT = 0x9, + /** 输入输出共享内存引用参数类型。 */ + TEE_PARAM_TYPE_MEMREF_SHARED_INOUT = 0xa, + /** 输入资源内存参数类型。 */ + TEE_PARAM_TYPE_RESMEM_INPUT = 0xc, + /** 输出资源内存参数类型。 */ + TEE_PARAM_TYPE_RESMEM_OUTPUT = 0xd, + /** 输入输出资源内存参数类型。 */ + TEE_PARAM_TYPE_RESMEM_INOUT = 0xe, +}; + +/** + * @brief 用于标记未使用的变量。 + * + * @since 20 + */ +#define S_VAR_NOT_USED(variable) \ + do { \ + (void)(variable); \ + } while (0) + +/** + * @brief 定义一个对象信息。 + * + * @since 20 + */ +typedef struct { + /** 对象类型。 */ + uint32_t objectType; + /** 对象大小。 */ + uint32_t objectSize; + /** 最大对象大小。 */ + uint32_t maxObjectSize; + /** 对象的使用方式。 */ + uint32_t objectUsage; + /** 数据大小。 */ + uint32_t dataSize; + /** 数据位置。 */ + uint32_t dataPosition; + /** 句柄标志。 */ + uint32_t handleFlags; +} TEE_ObjectInfo; + +/** + * @brief 定义一个对象属性。 + * + * @since 20 + */ +typedef struct { + /** 属性ID。 */ + uint32_t attributeID; + + /** 属性内容，包含引用和数值两种类型。 */ + union { + struct { + /** 指向数据缓冲区的指针。 */ + void *buffer; + /** 数据缓冲区的长度。 */ + size_t length; + } ref; + + struct { + /** 第一个值。 */ + uint32_t a; + /** 第二个值。 */ + uint32_t b; + } value; + } content; +} TEE_Attribute; + +/** + * @brief 枚举对象属性类型，用于加密操作。 + * + * @since 20 + */ +enum TEE_ObjectAttribute { + /** 密钥值属性。 */ + TEE_ATTR_SECRET_VALUE = 0xC0000000, + /** RSA 模数属性。 */ + TEE_ATTR_RSA_MODULUS = 0xD0000130, + /** RSA 公钥指数属性。 */ + TEE_ATTR_RSA_PUBLIC_EXPONENT = 0xD0000230, + /** RSA 私钥指数属性。 */ + TEE_ATTR_RSA_PRIVATE_EXPONENT = 0xC0000330, + /** RSA 素数 prime1 属性。 */ + TEE_ATTR_RSA_PRIME1 = 0xC0000430, + /** RSA 素数 prime2 属性。 */ + TEE_ATTR_RSA_PRIME2 = 0xC0000530, + /** RSA 指数 exponent1 属性。 */ + TEE_ATTR_RSA_EXPONENT1 = 0xC0000630, + /** RSA 指数 exponent2 属性。 */ + TEE_ATTR_RSA_EXPONENT2 = 0xC0000730, + /** RSA 系数属性。 */ + TEE_ATTR_RSA_COEFFICIENT = 0xC0000830, + /** RSA MGF1 哈希函数属性。 */ + TEE_ATTR_RSA_MGF1_HASH = 0xF0000830, + /** DSA 主素数属性。 */ + TEE_ATTR_DSA_PRIME = 0xD0001031, + /** DSA 子素数属性。 */ + TEE_ATTR_DSA_SUBPRIME = 0xD0001131, + /** DSA 基数属性。 */ + TEE_ATTR_DSA_BASE = 0xD0001231, + /** DSA 公钥值属性。 */ + TEE_ATTR_DSA_PUBLIC_VALUE = 0xD0000131, + /** DSA 私钥值属性。 */ + TEE_ATTR_DSA_PRIVATE_VALUE = 0xC0000231, + /** DH 主素数属性。 */ + TEE_ATTR_DH_PRIME = 0xD0001032, + /** DH 子素数属性。 */ + TEE_ATTR_DH_SUBPRIME = 0xD0001132, + /** DH 基数属性。 */ + TEE_ATTR_DH_BASE = 0xD0001232, + /** DH 私钥位长度属性。 */ + TEE_ATTR_DH_X_BITS = 0xF0001332, + /** DH 公钥值属性。 */ + TEE_ATTR_DH_PUBLIC_VALUE = 0xD0000132, + /** DH 私钥值属性。 */ + TEE_ATTR_DH_PRIVATE_VALUE = 0xC0000232, + /** RSA OAEP 标签属性。 */ + TEE_ATTR_RSA_OAEP_LABEL = 0xD0000930, + /** RSA PSS 盐长度属性。 */ + TEE_ATTR_RSA_PSS_SALT_LENGTH = 0xF0000A30, + /** ECC 公钥 X 坐标属性。 */ + TEE_ATTR_ECC_PUBLIC_VALUE_X = 0xD0000141, + /** ECC 公钥 Y 坐标属性。 */ + TEE_ATTR_ECC_PUBLIC_VALUE_Y = 0xD0000241, + /** ECC 私钥值属性。 */ + TEE_ATTR_ECC_PRIVATE_VALUE = 0xC0000341, + /** ECC 曲线属性。 */ + TEE_ATTR_ECC_CURVE = 0xF0000441, + /** ED25519 上下文属性。 */ + TEE_ATTR_ED25519_CTX = 0xD0000643, + /** ED25519 公钥值属性。 */ + TEE_ATTR_ED25519_PUBLIC_VALUE = 0xD0000743, + /** ED25519 私钥值属性。 */ + TEE_ATTR_ED25519_PRIVATE_VALUE = 0xC0000843, + /** ED25519 PH（预哈希）属性。 */ + TEE_ATTR_ED25519_PH = 0xF0000543, + /** X25519 公钥值属性。 */ + TEE_ATTR_X25519_PUBLIC_VALUE = 0xD0000944, + /** X25519 私钥值属性。 */ + TEE_ATTR_X25519_PRIVATE_VALUE = 0xC0000A44, + /** PBKDF2 HMAC 密码属性。 */ + TEE_ATTR_PBKDF2_HMAC_PASSWORD = 0xD0000133, + /** PBKDF2 HMAC 盐属性。 */ + TEE_ATTR_PBKDF2_HMAC_SALT = 0xD0000134, + /** PRF 标签属性。 */ + TEE_ATTR_PRF_LABEL = 0xD0000136, + /** PRF 种子属性。 */ + TEE_ATTR_PRF_SEED = 0xD0000137, + /** PRF 哈希算法属性。 */ + TEE_ATTR_PRF_HASH_ALGORITHM = 0xF0000138, + /** HKDF 盐属性。 */ + TEE_ATTR_HKDF_SALT = 0xD0000946, + /** HKDF 附加信息属性。 */ + TEE_ATTR_HKDF_INFO = 0xD0000A46, + /** PBKDF2 HMAC 摘要算法属性。 */ + TEE_ATTR_PBKDF2_HMAC_DIGEST = 0xF0000135, + /** HKDF 哈希算法属性。 */ + TEE_ATTR_HKDF_HASH_ALGORITHM = 0xF0000B46, + /** KDF 密钥长度属性。 */ + TEE_ATTR_KDF_KEY_SIZE = 0xF0000C46, +}; + +/** + * @brief 枚举对象的类型。 + * + * @since 20 + */ +enum TEE_ObjectType { + /** AES 对象类型。 */ + TEE_TYPE_AES = 0xA0000010, + /** DES 对象类型。 */ + TEE_TYPE_DES = 0xA0000011, + /** 3DES 对象类型。 */ + TEE_TYPE_DES3 = 0xA0000013, + /** HMAC MD5 对象类型。 */ + TEE_TYPE_HMAC_MD5 = 0xA0000001, + /** HMAC SHA1 对象类型。 */ + TEE_TYPE_HMAC_SHA1 = 0xA0000002, + /** HMAC SHA224 对象类型。 */ + TEE_TYPE_HMAC_SHA224 = 0xA0000003, + /** HMAC SHA256 对象类型。 */ + TEE_TYPE_HMAC_SHA256 = 0xA0000004, + /** HMAC SHA384 对象类型。 */ + TEE_TYPE_HMAC_SHA384 = 0xA0000005, + /** HMAC SHA512 对象类型。 */ + TEE_TYPE_HMAC_SHA512 = 0xA0000006, + /** RSA 公钥对象类型。 */ + TEE_TYPE_RSA_PUBLIC_KEY = 0xA0000030, + /** RSA 密钥对对象类型。 */ + TEE_TYPE_RSA_KEYPAIR = 0xA1000030, + /** DSA 公钥对象类型。 */ + TEE_TYPE_DSA_PUBLIC_KEY = 0xA0000031, + /** DSA 密钥对对象类型。 */ + TEE_TYPE_DSA_KEYPAIR = 0xA1000031, + /** DH 密钥对对象类型。 */ + TEE_TYPE_DH_KEYPAIR = 0xA1000032, + /** 通用密钥对象类型。 */ + TEE_TYPE_GENERIC_SECRET = 0xA0000000, + /** 数据对象类型。 */ + TEE_TYPE_DATA = 0xA1000033, + /** 数据对象类型（GP1.1） */ + TEE_TYPE_DATA_GP1_1 = 0xA00000BF, + /** ECDSA 公钥对象类型。 */ + TEE_TYPE_ECDSA_PUBLIC_KEY = 0xA0000041, + /** ECDSA 密钥对对象类型。 */ + TEE_TYPE_ECDSA_KEYPAIR = 0xA1000041, + /** ECDH 公钥对象类型。 */ + TEE_TYPE_ECDH_PUBLIC_KEY = 0xA0000042, + /** ECDH 密钥对对象类型。 */ + TEE_TYPE_ECDH_KEYPAIR = 0xA1000042, + /** ED25519 公钥对象类型。 */ + TEE_TYPE_ED25519_PUBLIC_KEY = 0xA0000043, + /** ED25519 密钥对对象类型。 */ + TEE_TYPE_ED25519_KEYPAIR = 0xA1000043, + /** X25519 公钥对象类型。 */ + TEE_TYPE_X25519_PUBLIC_KEY = 0xA0000044, + /** X25519 密钥对对象类型。 */ + TEE_TYPE_X25519_KEYPAIR = 0xA1000044, + /** SM2 DSA 公钥对象类型。 */ + TEE_TYPE_SM2_DSA_PUBLIC_KEY = 0xA0000045, + /** SM2 DSA 密钥对对象类型。 */ + TEE_TYPE_SM2_DSA_KEYPAIR = 0xA1000045, + /** SM2 KEP 公钥对象类型。 */ + TEE_TYPE_SM2_KEP_PUBLIC_KEY = 0xA0000046, + /** SM2 KEP 密钥对对象类型。 */ + TEE_TYPE_SM2_KEP_KEYPAIR = 0xA1000046, + /** SM2 PKE 公钥对象类型。 */ + TEE_TYPE_SM2_PKE_PUBLIC_KEY = 0xA0000047, + /** SM2 PKE 密钥对对象类型。 */ + TEE_TYPE_SM2_PKE_KEYPAIR = 0xA1000047, + /** HMAC SM3 对象类型。 */ + TEE_TYPE_HMAC_SM3 = 0xA0000007, + /** SM4 对象类型。 */ + TEE_TYPE_SM4 = 0xA0000014, + /** HKDF 对象类型。 */ + TEE_TYPE_HKDF = 0xA000004A, + /** SIP 哈希对象类型。 */ + TEE_TYPE_SIP_HASH = 0xF0000002, + /** PBKDF2 HMAC 对象类型。 */ + TEE_TYPE_PBKDF2_HMAC = 0xF0000004, + /** PRF 对象类型。 */ + TEE_TYPE_PRF = 0xF0000005, + /** 损坏的对象类型。 */ + TEE_TYPE_CORRUPTED_OBJECT = 0xA00000BE, +}; + +/** + * @brief 定义对象的最大名称长度。 + * + * @since 20 + */ +#define OBJECT_NAME_LEN_MAX 256 + +/** + * @brief 定义一个对象句柄。 + * + * @since 20 + */ +struct __TEE_ObjectHandle { + /** 指向对象数据的指针。 */ + void *dataPtr; + /** 对象数据的长度。 */ + uint32_t dataLen; + /** 对象数据的名称，最大长度为255。 */ + uint8_t dataName[OBJECT_NAME_LEN_MAX]; + /** 指向对象信息的指针。 */ + TEE_ObjectInfo *ObjectInfo; + /** 指向对象属性的指针。 */ + TEE_Attribute *Attribute; + /** 对象属性的长度。 */ + uint32_t attributesLen; + /** 对象的CRT模式。 */ + uint32_t CRTMode; + /** 信息属性文件描述符。 */ + void *infoattrfd; + /** 对象生成标志。 */ + uint32_t generate_flag; + /** 存储ID。 */ + uint32_t storage_id; +}; + +/** + * @brief 定义__TEE_ObjectHandle结构体。 + * + * @see __TEE_ObjectHandle + * + * @since 20 + */ +typedef struct __TEE_ObjectHandle *TEE_ObjectHandle; + +/** + * @brief 定义节点长度。 + * + * @since 20 + */ +#define NODE_LEN 8 + +/** + * @brief 定义TA的UUID。 + * + * @since 20 + */ +typedef struct tee_uuid { + /** 时间低位部分。 */ + uint32_t timeLow; + /** 时间中间部分。 */ + uint16_t timeMid; + /** 时间高位和版本部分。 */ + uint16_t timeHiAndVersion; + /** 时钟序列和节点部分。 */ + uint8_t clockSeqAndNode[NODE_LEN]; +} TEE_UUID; + +/** + * @brief 定义spawn UUID的类型。 + * + * @since 20 + */ +typedef struct spawn_uuid { + /** UUID是否有效标志。 */ + uint64_t uuid_valid; + /** UUID值。 */ + TEE_UUID uuid; +} spawn_uuid_t; + +/** + * @brief 枚举 TEEKit API 中使用的返回码。 + * + * @since 20 + */ +enum TEE_Result_Value { + /** 操作成功。 */ + TEE_SUCCESS = 0x00000000, + /** 命令无效。 */ + TEE_ERROR_INVALID_CMD = 0x00000001, + /** 服务不存在。 */ + TEE_ERROR_SERVICE_NOT_EXIST = 0x00000002, + /** 会话不存在。 */ + TEE_ERROR_SESSION_NOT_EXIST = 0x00000003, + /** 会话数超过限制。 */ + TEE_ERROR_SESSION_MAXIMUM = 0x00000004, + /** 服务已被注册。 */ + TEE_ERROR_REGISTER_EXIST_SERVICE = 0x00000005, + /** 发生内部错误。 */ + TEE_ERROR_TARGET_DEAD_FATAL = 0x00000006, + /** 数据读取失败。 */ + TEE_ERROR_READ_DATA = 0x00000007, + /** 数据写入失败。 */ + TEE_ERROR_WRITE_DATA = 0x00000008, + /** 截断对象失败。 */ + TEE_ERROR_TRUNCATE_OBJECT = 0x00000009, + /** 数据定位失败。 */ + TEE_ERROR_SEEK_DATA = 0x0000000A, + /** 数据同步失败。 */ + TEE_ERROR_SYNC_DATA = 0x0000000B, + /** 重命名文件失败。 */ + TEE_ERROR_RENAME_OBJECT = 0x0000000C, + /** 加载 TA 时发生错误。 */ + TEE_ERROR_TRUSTED_APP_LOAD_ERROR = 0x0000000D, + /** TA 类型与加载模式不匹配。 */ + TEE_ERROR_OTRP_LOAD_NOT_MATCHED = 0x80000100, + /** 未打开会话的 OTRP 服务数量超限。 */ + TEE_ERROR_OTRP_LOAD_EXCEED = 0x80000101, + /** 加载命令的 UUID 与 sec 文件不一致。 */ + TEE_ERROR_OTRP_ACCESS_DENIED = 0x80000102, + /** OTRP 服务已过期。 */ + TEE_ERROR_OTRP_SERVICE_AGED = 0x80000103, + /** 存储数据时发生 I/O 错误。 */ + TEE_ERROR_STORAGE_EIO = 0x80001001, + /** 存储区域不可用。 */ + TEE_ERROR_STORAGE_EAGAIN = 0x80001002, + /** 操作目标不是目录。 */ + TEE_ERROR_STORAGE_ENOTDIR = 0x80001003, + /** 不能对目录执行该操作。 */ + TEE_ERROR_STORAGE_EISDIR = 0x80001004, + /** 系统打开的文件数超限。 */ + TEE_ERROR_STORAGE_ENFILE = 0x80001005, + /** 进程打开的文件数超限。 */ + TEE_ERROR_STORAGE_EMFILE = 0x80001006, + /** 存储区域为只读。 */ + TEE_ERROR_STORAGE_EROFS = 0x80001007, + /** 文件对象已回滚。 */ + TEE_ERROR_STORAGE_EROLLBACK = 0x80001008, + /** 文件路径不正确。 */ + TEE_ERROR_STORAGE_PATH_WRONG = 0x8000100A, + /** 服务消息队列溢出。 */ + TEE_ERROR_MSG_QUEUE_OVERFLOW = 0x8000100B, + /** TA 创建的子线程无法访问服务。 */ + TEE_ERROR_SUBTHREAD_ACCESS = 0x8000100C, + /** 启用备份功能，原分区未激活。 */ + TEE_ERROR_ORIGIN_PARTITION_INACTIVE = 0x8000100D, + /** 启用备份功能，备份分区未激活。 */ + TEE_ERROR_BACKUP_PARTITION_INACTIVE = 0x8000100E, + /** 文件对象已损坏。 */ + TEE_ERROR_CORRUPT_OBJECT = 0xF0100001, + /** 存储区域不可用。 */ + TEE_ERROR_STORAGE_NOT_AVAILABLE = 0xF0100003, + /** 密文不正确。 */ + TEE_ERROR_CIPHERTEXT_INVALID = 0xF0100006, + /** 套接字连接协议错误。 */ + TEE_ISOCKET_ERROR_PROTOCOL = 0xF1007001, + /** 远端关闭了套接字。 */ + TEE_ISOCKET_ERROR_REMOTE_CLOSED = 0xF1007002, + /** 套接字连接超时。 */ + TEE_ISOCKET_ERROR_TIMEOUT = 0xF1007003, + /** 套接字连接资源不足。 */ + TEE_ISOCKET_ERROR_OUT_OF_RESOURCES = 0xF1007004, + /** 套接字缓冲区过大。 */ + TEE_ISOCKET_ERROR_LARGE_BUFFER = 0xF1007005, + /** 套接字连接产生警告。 */ + TEE_ISOCKET_WARNING_PROTOCOL = 0xF1007006, + /** 通用错误。 */ + TEE_ERROR_GENERIC = 0xFFFF0000, + /** 拒绝访问。 */ + TEE_ERROR_ACCESS_DENIED = 0xFFFF0001, + /** 操作被取消。 */ + TEE_ERROR_CANCEL = 0xFFFF0002, + /** 发生访问冲突。 */ + TEE_ERROR_ACCESS_CONFLICT = 0xFFFF0003, + /** 数据量超限。 */ + TEE_ERROR_EXCESS_DATA = 0xFFFF0004, + /** 数据格式错误。 */ + TEE_ERROR_BAD_FORMAT = 0xFFFF0005, + /** 参数错误。 */ + TEE_ERROR_BAD_PARAMETERS = 0xFFFF0006, + /** 当前状态不支持该操作。 */ + TEE_ERROR_BAD_STATE = 0xFFFF0007, + /** 未找到目标项。 */ + TEE_ERROR_ITEM_NOT_FOUND = 0xFFFF0008, + /** API 未实现。 */ + TEE_ERROR_NOT_IMPLEMENTED = 0xFFFF0009, + /** API 不支持。 */ + TEE_ERROR_NOT_SUPPORTED = 0xFFFF000A, + /** 无可用数据。 */ + TEE_ERROR_NO_DATA = 0xFFFF000B, + /** 内存不足。 */ + TEE_ERROR_OUT_OF_MEMORY = 0xFFFF000C, + /** 系统繁忙。 */ + TEE_ERROR_BUSY = 0xFFFF000D, + /** 与目标通信失败。 */ + TEE_ERROR_COMMUNICATION = 0xFFFF000E, + /** 安全错误。 */ + TEE_ERROR_SECURITY = 0xFFFF000F, + /** 缓冲区不足。 */ + TEE_ERROR_SHORT_BUFFER = 0xFFFF0010, + /** 外部操作已取消。 */ + TEE_ERROR_EXTERNAL_CANCEL = 0xFFFF0011, + /** 服务处于挂起状态（异步）。 */ + TEE_PENDING = 0xFFFF2000, + /** 服务处于挂起状态（备用）。 */ + TEE_PENDING2 = 0xFFFF2001, + /** 保留。 */ + TEE_PENDING3 = 0xFFFF2002, + /** 操作超时。 */ + TEE_ERROR_TIMEOUT = 0xFFFF3001, + /** 数据溢出。 */ + TEE_ERROR_OVERFLOW = 0xFFFF300f, + /** TA 崩溃。 */ + TEE_ERROR_TARGET_DEAD = 0xFFFF3024, + /** 空间不足。 */ + TEE_ERROR_STORAGE_NO_SPACE = 0xFFFF3041, + /** MAC 校验失败。 */ + TEE_ERROR_MAC_INVALID = 0xFFFF3071, + /** 签名验证失败。 */ + TEE_ERROR_SIGNATURE_INVALID = 0xFFFF3072, + /** 证书验证失败。 */ + TEE_ERROR_CERTIFICATE_INVALID = 0xFFFF3073, + /** 被 CFC 中断，检测到控制流异常。 */ + TEE_CLIENT_INTR = 0xFFFF4000, + /** 时间未设置。 */ + TEE_ERROR_TIME_NOT_SET = 0xFFFF5000, + /** 需要重设时间。 */ + TEE_ERROR_TIME_NEEDS_RESET = 0xFFFF5001, + /** 系统错误。 */ + TEE_FAIL = 0xFFFF5002, + /** 定时器错误码的基础值。 */ + TEE_ERROR_TIMER = 0xFFFF6000, + /** 创建定时器失败。 */ + TEE_ERROR_TIMER_CREATE_FAILED = 0xFFFF6001, + /** 销毁定时器失败。 */ + TEE_ERROR_TIMER_DESTROY_FAILED = 0xFFFF6002, + /** 未找到定时器。 */ + TEE_ERROR_TIMER_NOT_FOUND = 0xFFFF6003, + /** RPMB 错误码的基础值。 */ + TEE_ERROR_RPMB_BASE = 0xFFFF7000, + /** RPMB 操作通用错误。 */ + TEE_ERROR_RPMB_GENERIC = 0xFFFF7001, + /** RPMB 操作中 MAC 校验失败。 */ + TEE_ERROR_RPMB_MAC_FAIL = 0xFFFF7002, + /** RPMB 操作中计数器无效。 */ + TEE_ERROR_RPMB_COUNTER_FAIL = 0xFFFF7003, + /** RPMB 操作中地址检查失败。 */ + TEE_ERROR_RPMB_ADDR_FAIL = 0xFFFF7004, + /** RPMB 写入失败。 */ + TEE_ERROR_RPMB_WRITE_FAIL = 0xFFFF7005, + /** RPMB 读取失败。 */ + TEE_ERROR_RPMB_READ_FAIL = 0xFFFF7006, + /** RPMB 中未配置密钥。 */ + TEE_ERROR_RPMB_KEY_NOT_PROGRAM = 0xFFFF7007, + /** RPMB 响应中消息类型不正确。 */ + TEE_ERROR_RPMB_RESP_UNEXPECT_MSGTYPE = 0xFFFF7100, + /** RPMB 响应中数据块数量不正确。 */ + TEE_ERROR_RPMB_RESP_UNEXPECT_BLKCNT = 0xFFFF7101, + /** RPMB 响应中块索引不正确。 */ + TEE_ERROR_RPMB_RESP_UNEXPECT_BLKIDX = 0xFFFF7102, + /** RPMB 响应中写计数不正确。 */ + TEE_ERROR_RPMB_RESP_UNEXPECT_WRCNT = 0xFFFF7103, + /** RPMB 响应中随机数不正确。 */ + TEE_ERROR_RPMB_RESP_UNEXPECT_NONCE = 0xFFFF7104, + /** RPMB 响应中 MAC 不正确。 */ + TEE_ERROR_RPMB_RESP_UNEXPECT_MAC = 0xFFFF7105, + /** RPMB 中未找到文件。 */ + TEE_ERROR_RPMB_FILE_NOT_FOUND = 0xFFFF7106, + /** RPMB 空间不足。 */ + TEE_ERROR_RPMB_NOSPC = 0xFFFF7107, + /** TA 超过其可用的 RPMB 空间限制。 */ + TEE_ERROR_RPMB_SPC_CONFLICT = 0xFFFF7108, + /** RPMB 服务不可用。 */ + TEE_ERROR_RPMB_NOT_AVAILABLE = 0xFFFF7109, + /** RPMB 分区已损坏。 */ + TEE_ERROR_RPMB_DAMAGED = 0xFFFF710A, + /** TUI（可信用户界面）正在使用中。 */ + TEE_ERROR_TUI_IN_USE = 0xFFFF7110, + /** TUI 响应中切换通道消息不正确。 */ + TEE_ERROR_TUI_SWITCH_CHANNAL = 0xFFFF7111, + /** TUI 响应中配置驱动消息不正确。 */ + TEE_ERROR_TUI_CFG_DRIVER = 0xFFFF7112, + /** TUI 事件无效。 */ + TEE_ERROR_TUI_INVALID_EVENT = 0xFFFF7113, + /** TUI 响应中轮询事件消息不正确。 */ + TEE_ERROR_TUI_POLL_EVENT = 0xFFFF7114, + /** TUI 被取消。 */ + TEE_ERROR_TUI_CANCELED = 0xFFFF7115, + /** TUI 已退出。 */ + TEE_ERROR_TUI_EXIT = 0xFFFF7116, + /** TUI 不可用。 */ + TEE_ERROR_TUI_NOT_AVAILABLE = 0xFFFF7117, + /** 安全闪存不可用。 */ + TEE_ERROR_SEC_FLASH_NOT_AVAILABLE = 0xFFFF7118, + /** 安全元素（SE）服务崩溃或未启用。 */ + TEE_ERROR_SESRV_NOT_AVAILABLE = 0xFFFF7119, + /** 生物识别服务不可用。 */ + TEE_ERROR_BIOSRV_NOT_AVAILABLE = 0xFFFF711A, + /** 根信任服务不可用。 */ + TEE_ERROR_ROTSRV_NOT_AVAILABLE = 0xFFFF711B, + /** TA 防回滚服务不可用。 */ + TEE_ERROR_ARTSRV_NOT_AVAILABLE = 0xFFFF711C, + /** 硬件安全模块（HSM）服务不可用。 */ + TEE_ERROR_HSMSRV_NOT_AVAILABLE = 0xFFFF711D, + /** REE VRPMB 代理校验 magic 失败，可能为缓存失败。 */ + TEE_ERROR_VRPMB_AGENT_FAIL = 0xFFFF7200, + /** REE SSD 驱动读写失败。 */ + TEE_ERROR_VRPMB_RW_FAIL = 0xFFFF7201, + /** VRPMB 超级块 MAC 校验失败。 */ + TEE_ERROR_VRPMB_SUPER_MAC_FAILED = 0xFFFF7202, + /** 拒绝写入 VRPMB。 */ + TEE_ERROR_VRPMB_WRITE_REJECT = 0xFFFF7203, + /** AntiRoot 响应验证失败。 */ + TEE_ERROR_ANTIROOT_RSP_FAIL = 0xFFFF9110, + /** AntiRoot 调用命令错误。 */ + TEE_ERROR_ANTIROOT_INVOKE_ERROR = 0xFFFF9111, + /** 审计失败。 */ + TEE_ERROR_AUDIT_FAIL = 0xFFFF9112, + /** 未使用。 */ + TEE_FAIL2 = 0xFFFF9113, + /** IPC 通道溢出错误。 */ + TEE_ERROR_IPC_OVERFLOW = 0xFFFF9114, + /** APM 错误。 */ + TEE_ERROR_APM = 0xFFFF9115, + /** CA 授权文件不存在。 */ + TEE_ERROR_CA_AUTHFILE_NOT_EXIST = 0xFFFF9116, + /** CA 调用者访问被拒绝。 */ + TEE_ERROR_CA_CALLER_ACCESS_DENIED = 0xFFFF9117, + /** TA 格式无效。 */ + TEE_ERROR_INVALID_TA_FORMAT = 0xFFFF9118, + /** 本地 DSTB 服务签名报告错误。 */ + TEE_DSTB_LOCAL_SIGN_REPORT_ERROR = 0xFFFF9200, + /** 远程 DSTB 服务签名报告错误。 */ + TEE_DSTB_REMOTE_SIGN_REPORT_ERROR = 0xFFFF9201, + /** 本地 DSTB 报告证书链错误。 */ + TEE_DSTB_LOCAL_REPORT_CERT_CHAIN_ERROR = 0xFFFF9202, + /** 远程 DSTB 报告证书链错误。 */ + TEE_DSTB_REMOTE_REPORT_CERT_CHAIN_ERROR = 0xFFFF9203, + /** 本地 DSTB 报告验证错误。 */ + TEE_DSTB_LOCAL_REPORT_VERIFY_ERROR = 0xFFFF9204, + /** 远程 DSTB 报告验证错误。 */ + TEE_DSTB_REMOTE_REPORT_VERIFY_ERROR = 0xFFFF9205, + /** 本地 DSTB 验证证书链错误。 */ + TEE_DSTB_LOCAL_CERT_CHAIN_VERIFY_ERROR = 0xFFFF9206, + /** 远程 DSTB 验证证书链错误。 */ + TEE_DSTB_REMOTE_CERT_CHAIN_VERIFY_ERROR = 0xFFFF9207, + /** 本地 DSTB 密钥版本错误。 */ + TEE_DSTB_LOCAL_INVALID_KEY_VERSION_ERROR = 0xFFFF9208, + /** 远程 DSTB 密钥版本错误。 */ + TEE_DSTB_REMOTE_INVALID_KEY_VERSION_ERROR = 0xFFFF9209, + /** UDID 无效。 */ + TEE_DSTB_INVALID_UDID = 0xFFFF920A, + /** DSTB 派生密钥错误。 */ + TEE_DSTB_DERIVE_KEY_ERROR = 0xFFFF920B, + /** REE 的 DSTB 服务错误。 */ + TEE_DSTB_REE_SRV_ERROR = 0xFFFF920C, + /** Anti-Rollback 导致 TA 加载失败。 */ + TEE_ERROR_TA_ANTI_ROLLBACK = 0xFFFF920D, + /** 与 close_session 冲突导致 open_session 重试。 */ + TEE_ERROR_RETRY_OPEN_SESSION = 0xFFFF920E, + /** 加载 TA 控制文件失败。 */ + TEE_ERROR_TA_CTRL_FILE_LOAD_FAIL = 0xFFFF920F, + /** 验证 TA 控制文件失败。 */ + TEE_ERROR_TA_CTRL_FILE_VERIFY_FAIL = 0xFFFF9210, + /** TA 版本低于控制文件中的版本。 */ + TEE_ERROR_TA_VER_BELOW_CONTROL_VER = 0xFFFF9211, + /** 本地 DSTB 证书链有效性检查失败。 */ + TEE_DSTB_LOCAL_CERT_VALIDITY_ERROR = 0xFFFF9212, + /** 远程 DSTB 证书链有效性检查失败。 */ + TEE_DSTB_REMOTE_CERT_VALIDITY_ERROR = 0xFFFF9213, +}; + +/** + * @brief 登录类型定义 + * + * @since 20 + */ +enum TEE_LoginMethod { + /** 公共登录方式。 */ + TEE_LOGIN_PUBLIC = 0x0, + /** 用户登录方式。 */ + TEE_LOGIN_USER, + /** 用户组登录方式。 */ + TEE_LOGIN_GROUP, + /** 应用登录方式。 */ + TEE_LOGIN_APPLICATION = 0x4, + /** 用户-应用联合登录方式。 */ + TEE_LOGIN_USER_APPLICATION = 0x5, + /** 用户组-应用联合登录方式。 */ + TEE_LOGIN_GROUP_APPLICATION = 0x6, + /** 自定义登录方式。 */ + TEE_LOGIN_IDENTIFY = 0x7, + /** 源自 Linux 内核的登录方式。 */ + TEEK_LOGIN_IDENTIFY = 0x80000001, +}; + +/** + * @brief 定义TEE身份。 + * + * @since 20 + */ +typedef struct { + /** 登录类型。 */ + uint32_t login; + /** 身份的UUID。 */ + TEE_UUID uuid; +} TEE_Identity; + +/** + * @brief 定义返回值类型。 + * + * @since 20 + * @version 1.0 + */ +typedef uint32_t TEE_Result; + +/** + * @brief 定义返回值类型。 + * + * @since 20 + * @version 1.0 + */ +typedef TEE_Result TEEC_Result; + +/** + * @brief 定义TEE的来源标志。 + * + * @since 20 + */ +#define TEE_ORIGIN_TEE 0x00000003 + +/** + * @brief 定义受信应用程序的来源标志。 + * + * @since 20 + */ +#define TEE_ORIGIN_TRUSTED_APP 0x00000004 + +#ifndef _TEE_TA_SESSION_HANDLE +/** + * @brief 定义TA会话句柄。 + * + * @since 20 + */ +#define _TEE_TA_SESSION_HANDLE + +/** + * @brief 定义TA会话句柄。 + * + * @since 20 + */ +typedef uint32_t TEE_TASessionHandle; +#endif + +/** + * @brief 定义指向TEE_ObjectEnumHandle的指针。 + * + * @see __TEE_ObjectEnumHandle + * + * @since 20 + */ +typedef struct __TEE_ObjectEnumHandle *TEE_ObjectEnumHandle; + +/** + * @brief 定义指向__TEE_OperationHandle的指针。 + * + * @see __TEE_OperationHandle + * + * @since 20 + */ +typedef struct __TEE_OperationHandle *TEE_OperationHandle; + +/** + * @brief 定义无限超时时间。 + * + * @since 20 + */ +#define TEE_TIMEOUT_INFINITE (0xFFFFFFFF) + +/** + * @brief 定义TEE时间。 + * + * @since 20 + */ +typedef struct { + /** 秒数。 */ + uint32_t seconds; + /** 毫秒数。 */ + uint32_t millis; +} TEE_Time; + +/** + * @brief 定义TEE的日期时间。 + * + * @since 20 + */ +typedef struct { + /** 秒数。 */ + int32_t seconds; + /** 毫秒数。 */ + int32_t millis; + /** 分钟数。 */ + int32_t min; + /** 小时数。 */ + int32_t hour; + /** 日数。 */ + int32_t day; + /** 月份。 */ + int32_t month; + /** 年份。 */ + int32_t year; +} TEE_Date_Time; + +/** + * @brief 定义TEE的定时器属性。 + * + * @since 20 + */ +typedef struct { + /** 定时器类型。 */ + uint32_t type; + /** 定时器ID。 */ + uint32_t timer_id; + /** 定时器类别。 */ + uint32_t timer_class; + /** 保留字段。 */ + uint32_t reserved2; +} TEE_timer_property; + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_drv_client.h b/zh-cn/native_sdk/TEEKit/tee/tee_drv_client.h new file mode 100644 index 00000000..61e55261 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_drv_client.h @@ -0,0 +1,97 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_drv_client.h + * + * @brief 声明 TEE 驱动客户端 API。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_DRV_CLIENT_H +#define TEE_DRV_CLIENT_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 在 TEE 中打开指定的驱动程序。 + * + * @param drv_name [IN] 驱动程序名称。 + * @param param [IN] 参数信息。 + * @param param_len [IN] 参数的长度。 + * + * @return 返回大于 0 的值，表示对应驱动的文件描述符。 + * 返回小于或等于 0 的值，表示打开驱动失败。 + * + * @since 20 + * @version 1.0 + */ +int64_t tee_drv_open(const char *drv_name, const void *param, uint32_t param_len); + +/** + * @brief 取消操作。 + * + * @param fd [IN] 驱动的文件描述符。 + * @param cmd_id [IN] 命令 ID。 + * @param param [IN] 参数信息。 + * @param param_len [IN] 参数的长度。 + * + * @return 返回 0，表示操作成功。 + * 返回 -1，表示操作失败。 + * + * @since 20 + * @version 1.0 + */ +int64_t tee_drv_ioctl(int64_t fd, uint32_t cmd_id, const void *param, uint32_t param_len); + +/** + * @brief 关闭在 TEE 中打开的驱动程序。 + * + * @param fd [IN] 驱动的文件描述符。 + * + * @return 返回 0，表示操作成功。 + * 返回 -1，表示操作失败。 + * + * @since 20 + * @version 1.0 + */ +int64_t tee_drv_close(int64_t fd); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_dynamic_srv.h b/zh-cn/native_sdk/TEEKit/tee/tee_dynamic_srv.h new file mode 100644 index 00000000..3feefaf1 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_dynamic_srv.h @@ -0,0 +1,149 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_dynamic_srv.h + * + * @brief 提供与动态服务开发相关的 API。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef _TEE_DYNAMIC_SRV_H_ +#define _TEE_DYNAMIC_SRV_H_ + +#include +#include "tee_service_public.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 定义动态服务的线程初始化信息。 + * + * @since 20 + */ +struct srv_thread_init_info { + /** 指向线程启动函数的指针。 */ + void *(*func)(void *arg); + /** 最大并发线程数。 */ + uint32_t max_thread; + /** 线程的 shadow 属性。 */ + int32_t shadow; + /** 线程的堆栈大小。 */ + uint32_t stack_size; + /** 线程的超时时间（单位：秒）。 */ + uint32_t time_out_sec; +}; + +/** + * @brief 定义线程分发函数的类型。 + * + * @since 20 + */ +typedef void (*srv_dispatch_fn_t)(tee_service_ipc_msg *msg, + uint32_t sndr, tee_service_ipc_msg_rsp *rsp); + +/** + * @brief 定义服务分发结构体。 + * + * @since 20 + */ +struct srv_dispatch_t { + /** 命令标识符。 */ + uint32_t cmd; + /** 线程分发函数的指针。 */ + srv_dispatch_fn_t fn; +}; + +/** + * @brief 获取发送者的 UUID。 + * + * @param sender [IN] 指示发送者的任务 Id。 + * @param uuid [OUT] 指示全局唯一标识符。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数不正确，或文件名超过 64 字节。\n + * 返回 {@code TEE_ERROR_ITEM_NOT_FOUND} 表示未能根据发送者找到相应的 UUID。\n + * 返回 {@code TEE_ERROR_GENERIC} 表示获取 UUID 失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_srv_get_uuid_by_sender(uint32_t sender, TEE_UUID *uuid); + +/** + * @brief 释放指定地址区域的对象映射。 + * + * @param va_addr [IN] 指示要释放的内存区域的地址。 + * @param size [IN] 指示要释放的内存区域的大小。 + * + * @since 20 + * @version 1.0 + */ +void tee_srv_unmap_from_task(uint32_t va_addr, uint32_t size); + +/** + * @brief 在调用进程的虚拟地址空间中创建新的映射。 + * + * @param in_task_id [IN] 指示任务 Id。 + * @param va_addr [IN] 指示要映射的内存区域的地址。 + * @param size [IN] 指示要映射的内存区域的大小。 + * @param virt_addr [OUT] 指示新映射的虚拟地址。 + * + * @return 返回 0 表示操作成功。\n + * 返回 -1 表示操作失败。 + * + * @since 20 + * @version 1.0 + */ +int tee_srv_map_from_task(uint32_t in_task_id, uint32_t va_addr, uint32_t size, uint32_t *virt_addr); + +/** + * @brief 根据任务名称分派任务。 + * + * @param task_name [IN] 指示任务名称。 + * @param dispatch [IN] 指示分派信息。 + * @param n_dispatch [IN] 指示分派数量。 + * @param cur_thread [IN] 指示当前线程信息。 + * + * @since 20 + * @version 1.0 + */ +void tee_srv_cs_server_loop(const char *task_name, const struct srv_dispatch_t *dispatch, + uint32_t n_dispatch, struct srv_thread_init_info *cur_thread); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_ext_api.h b/zh-cn/native_sdk/TEEKit/tee/tee_ext_api.h new file mode 100644 index 00000000..a67be5a6 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_ext_api.h @@ -0,0 +1,216 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_ext_api.h + * + * @brief 提供扩展接口。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_EXT_API_H +#define TEE_EXT_API_H + +#include "tee_defines.h" +#include "tee_hw_ext_api.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 定义无效用户 ID 的值。 + * + * @since 20 + */ +#define INVALID_USERID 0xFFFFFFFFU + +/** + * @brief 定义来自用户模式的 SMC。 + * + * @since 20 + */ +#define TEE_SMC_FROM_USR 0 + +/** + * @brief 定义来自内核模式的 SMC。 + * + * @since 20 + */ +#define TEE_SMC_FROM_KERNEL 1 + +/** + * @brief 定义保留缓冲区的大小。 + * + * @since 20 + */ +#define RESERVED_BUF_SIZE 32 + +/** + * @brief 定义调用者信息。 + * + * @since 20 + */ +typedef struct ta_caller_info { + /** 会话类型。 */ + uint32_t session_type; + union { + struct { + /** 调用者的 UUID。 */ + TEE_UUID caller_uuid; + /** 调用者的组 ID。 */ + uint32_t group_id; + }; + /** 用于存储 CA 信息的缓冲区。 */ + uint8_t ca_info[RESERVED_BUF_SIZE]; + } caller_identity; + /** 表示是否从内核模式发送的 SMC。 */ + uint8_t smc_from_kernel_mode; + /** 保留的缓冲区。 */ + uint8_t reserved[RESERVED_BUF_SIZE - 1]; +} caller_info; + +/** + * @brief 获取当前会话的调用者信息，详细信息请参考 caller_info 结构体。 + * + * @param caller_info_data 返回的调用者信息。 + * @param length 输入参数，表示 caller_info_data 的长度。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回其他信息表示操作失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_get_caller_info(caller_info *caller_info_data, uint32_t length); + +/** + * @brief 获取当前 CA 的用户 ID。 + * + * @param user_id 返回的用户 ID。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回其他信息表示操作失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_get_caller_userid(uint32_t *user_id); + +/** + * @brief 添加一个能够调用此 TA 的调用者信息。 + * 该 API 适用于本地 CA 和 HAP 格式的客户端应用（CA）。 + * + * @param cainfo_hash 调用者信息的哈希值。 + * @param length 哈希值的长度。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回其他信息表示操作失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result AddCaller_CA(const uint8_t *cainfo_hash, uint32_t length); + +/** + * @brief TA 调用此 API 允许其他 TA 与其建立会话。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回其他信息表示操作失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result AddCaller_TA_all(void); + +/** + * @brief 定义来自 CA 的会话调用者。 + * + * @since 20 + */ +#define SESSION_FROM_CA 0 + +/** + * @brief 定义来自 TA 的会话调用者。 + * + * @since 20 + */ +#define SESSION_FROM_TA 1 + +/** + * @brief 定义找不到 TA 任务的情况，例如来自 TA 子线程的调用。 + * + * @since 20 + */ +#define SESSION_FROM_NOT_SUPPORTED 0xFE + +/** + * @brief 定义找不到 TA 调用者的情况。 + * + * @since 20 + */ +#define SESSION_FROM_UNKNOWN 0xFF + +/** + * @brief 获取会话类型。 + * + * @return 返回获取的会话类型。 + * + * @since 20 + * @version 1.0 + */ +uint32_t tee_get_session_type(void); + +/** + * @brief 从平台密钥派生新密钥。 + * + * @param object [IN/OUT] 输入数据通过 ObjectInfo->keytype 指定，输出密钥通过 Attributes 返回。 + * @param key_size [IN] 密钥位数，也用于决定 ECC 曲线类型。 + * @param params [IN] 未使用参数。 + * @param param_count [IN] 未使用参数数量。 + * @param exinfo [IN] 用户信息，用作派生的盐值。 + * @param exinfo_size [IN] 用户信息的长度，最大为 64 字节，且必须大于 0。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回其他值表示失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_derive_ta_platfrom_keys(TEE_ObjectHandle object, uint32_t key_size, const TEE_Attribute *params, + uint32_t param_count, const uint8_t *exinfo, uint32_t exinfo_size); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_get_recoverymode.h b/zh-cn/native_sdk/TEEKit/tee/tee_get_recoverymode.h new file mode 100644 index 00000000..5a44041f --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_get_recoverymode.h @@ -0,0 +1,86 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_get_recoverymode.h + * + * @brief 提供用于获取系统启动模式的相关接口函数。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_GET_RECOVERYMODE_H +#define TEE_GET_RECOVERYMODE_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 枚举系统支持的启动模式。 + * + * @since 20 + */ +typedef enum { + /** 系统处于关机或正在关机状态。 */ + BOOT_MODE_SHUTDOWN = 0, + /** 正常启动模式。 */ + BOOT_MODE_NORMAL, + /** Fastboot 启动模式。 */ + BOOT_MODE_FASTBOOT, + /** 恢复模式。 */ + BOOT_MODE_RECOVERY, + /** eRecovery 模式。 */ + BOOT_MODE_RECOVERY2, + /** 支持的启动模式数量上限。 */ + BOOT_MODE_CNT_MAX +} boot_modes; + +/** + * @brief 获取当前启动模式。 + * + * @param recoverymode [OUT] 表示当前启动模式。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数错误。 + * + * @since 20 + * @version 1.0 + */ +int32_t tee_ext_get_recoverymode(enum boot_modes *recoverymode); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_hw_ext_api.h b/zh-cn/native_sdk/TEEKit/tee/tee_hw_ext_api.h new file mode 100644 index 00000000..46e1fb64 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_hw_ext_api.h @@ -0,0 +1,149 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_hw_ext_api.h + * + * @brief 提供扩展接口。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_HW_EXT_API_H +#define TEE_HW_EXT_API_H + +#include "tee_defines.h" +#include "tee_crypto_api.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 从 TEE 获取唯一设备 ID。 + * + * @param device_unique_id 指向用于存储设备 ID 的缓冲区的指针。 + * @param length 指向缓冲区长度的指针。 + * + * @return 返回 TEE_SUCCESS，表示操作成功。 + * 返回其他信息，否则表示失败。 + * + * @since 20 + */ +TEE_Result tee_ext_get_device_unique_id(uint8_t *device_unique_id, uint32_t *length); + +/** + * @brief 定义内存信息结构体。 + * + * @since 20 + */ +struct meminfo_t { + /** 内存缓冲区地址。 */ + uint64_t buffer; + /** 内存大小。 */ + uint32_t size; +}; + +/** + * @brief 从设备根密钥和当前任务的 UUID 进行密钥派生迭代。 + * + * @param salt [IN] 指向盐值数据的指针。 + * @param key [OUT] 指向保存派生密钥的指针。 + * @param outer_iter_num [IN] huk 服务中的迭代次数。 + * @param inner_iter_num [IN] 平台驱动中的迭代次数。 + * + * @return 返回 {@code TEE_SUCCESS}，表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS}，表示输入参数不正确。\n + * 返回 {@code TEE_ERROR_GENERIC}，表示处理失败。 + * + * @since 20 + */ +TEE_Result tee_ext_derive_key_iter(const struct meminfo_t *salt, struct meminfo_t *key, + uint32_t outer_iter_num, uint32_t inner_iter_num); + +/** + * @brief 使用 HUK2 加密算法，通过设备根密钥和当前任务的 UUID 迭代派生密钥。 + * + * @param salt [IN] 表示用于加盐的数据。 + * @param key [OUT] 表示用于保存派生密钥的指针。 + * @param outer_iter_num [IN] 表示在 HUK 服务中进行的迭代次数。 + * @param inner_iter_num [IN] 表示在平台驱动中进行的迭代次数。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数非法。\n + * 返回 {@code TEE_ERROR_GENERIC} 表示处理失败。 + * + * @since 20 + */ +TEE_Result tee_ext_derive_key_iter_by_huk2(const struct meminfo_t *salt, struct meminfo_t *key, + uint32_t outer_iter_num, uint32_t inner_iter_num); + +/** + * @brief 通过 HUK2 从设备根密钥派生密钥。 + * @attention 如果设备不支持 HUK2，则使用 HUK 进行密钥派生。 + * + * @param salt [IN] 表示用于加盐的数据。 + * @param size [IN] 表示盐的长度。 + * @param key [OUT] 表示用于保存派生密钥的指针。 + * @param key_size [IN] 表示密钥长度，必须为 16 的整数倍。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数非法。\n + * 返回 {@code TEE_ERROR_GENERIC} 表示处理失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_derive_ta_root_key_by_huk2(const uint8_t *salt, uint32_t size, uint8_t *key, uint32_t key_size); + +/** + * @brief 使用增强型 HUK2，通过设备根密钥和当前任务 UUID 进行迭代派生密钥。 + * + * @param salt [IN] 用于加盐的数据。 + * @param key [OUT] 用于保存派生密钥的指针。 + * @param outer_iter_num [IN] 表示在 HUK 服务中进行的迭代次数。 + * @param inner_iter_num [IN] 表示在平台驱动中进行的迭代次数。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数非法。\n + * 返回 {@code TEE_ERROR_GENERIC} 表示处理失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_derive_key_iter_by_huk2_enhance(const struct meminfo_t *salt, struct meminfo_t *key, + uint32_t outer_iter_num, uint32_t inner_iter_num); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_hw_ext_api_legacy.h b/zh-cn/native_sdk/TEEKit/tee/tee_hw_ext_api_legacy.h new file mode 100644 index 00000000..a48c9411 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_hw_ext_api_legacy.h @@ -0,0 +1,141 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_hw_ext_api_legacy.h + * + * @brief 提供扩展接口。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef __TEE_HW_EXT_API_LEGACY_H__ +#define __TEE_HW_EXT_API_LEGACY_H__ + +#include "tee_defines.h" +#include "tee_crypto_api.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 从设备根密钥派生密钥。 + * + * @param salt [IN] 指向盐值数据的指针。 + * @param size [IN] 盐值的长度。 + * @param key [OUT] 指向保存派生密钥的指针。 + * @param key_size [IN] 密钥的大小，必须是 16 的整数倍。 + * + * @return 返回 {@code TEE_SUCCESS}，表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS}，表示输入参数不正确。\n + * 返回 {@code TEE_ERROR_GENERIC}，表示处理失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_EXT_DeriveTARootKey(const uint8_t *salt, uint32_t size, uint8_t *key, uint32_t key_size); + +/** + * @brief 通过 HUK2 从设备根密钥派生密钥。 + * @attention 如果设备不支持 HUK2，则使用 HUK 进行密钥派生。 + * + * @param secret [IN] 指向输入的密钥材料。 + * @param secret_len [IN] 输入密钥材料的长度。 + * @param key [OUT] 指向派生密钥的指针。 + * @param key_len [IN] 派生密钥的长度。 + * + * @return 返回 {@code TEE_SUCCESS}，表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS}，表示输入参数不正确。\n + * 返回 {@code TEE_ERROR_GENERIC}，表示处理失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_root_derive_key2_by_huk2(const uint8_t *secret, uint32_t secret_len, uint8_t *key, uint32_t key_len); + +/** + * @brief 通过 HUK2 从设备根密钥和当前任务的 UUID 派生密钥。 + * @attention 如果设备不支持 HUK2，则使用 HUK 进行密钥派生。 + * + * @param salt [IN] 指向盐值数据的指针。 + * @param size [IN] 盐值的长度。 + * @param key [OUT] 指向保存派生密钥的指针。 + * @param key_size [IN] 生成密钥的大小，固定为 32 字节。 + * + * @return 返回 {@code TEE_SUCCESS}，表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS}，表示输入参数不正确。\n + * 返回 {@code TEE_ERROR_GENERIC}，表示处理失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_root_uuid_derive_key_by_huk2(const uint8_t *salt, uint32_t size, uint8_t *key, uint32_t key_size); + +/** + * @brief 使用增强型 HUK2，通过根密钥为 Keymaster 派生密钥。 + * + * @param secret [IN] 输入的密钥原始数据。 + * @param secret_len [IN] 输入数据的长度。 + * @param key [OUT] 保存派生密钥的指针。 + * @param key_len [OUT] 派生密钥的长度。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数非法。\n + * 返回 {@code TEE_ERROR_GENERIC} 表示处理失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_root_derive_key2_by_huk2_enhance(const uint8_t *secret, uint32_t secret_len, uint8_t *key, uint32_t key_len); + +/** + * @brief 使用增强型 HUK2，通过设备根密钥和当前任务的 UUID 派生密钥。 + * + * @param salt [IN] 加盐数据。 + * @param size [IN] 盐的长度。 + * @param key_size [OUT] 派生密钥的长度，固定为 32 字节。 + * @param key [OUT] 保存派生密钥的指针。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数非法。\n + * 返回 {@code TEE_ERROR_GENERIC} 表示处理失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_root_uuid_derive_key_by_huk2_enhance(const uint8_t *salt, uint32_t size, uint8_t *key, uint32_t *key_size); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_internal_se_api.h b/zh-cn/native_sdk/TEEKit/tee/tee_internal_se_api.h new file mode 100644 index 00000000..012b9dc0 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_internal_se_api.h @@ -0,0 +1,586 @@ +您说： +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_internal_se_api.h + * + * @brief 提供与 TEE 可信元素相关的 API。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_INTERNAL_SE_API_H +#define TEE_INTERNAL_SE_API_H + +#include "tee_defines.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 定义 {@code TEE_SEServiceHandle} 的结构体。 + * + * @since 20 + */ +struct __TEE_SEServiceHandle; + +/** + * @brief 定义 {@code TEE_SEReaderHandle} 的结构体。 + * + * @since 20 + */ +struct __TEE_SEReaderHandle; + +/** + * @brief 定义 {@code TEE_SESessionHandle} 的结构体。 + * + * @since 20 + */ +struct __TEE_SESessionHandle; + +/** + * @brief 定义 {@code TEE_SEChannelHandle} 的结构体。 + * + * @since 20 + */ +struct __TEE_SEChannelHandle; + +/** + * @brief 定义 {@code TEE_SEServiceHandle} 的指针类型。 + * + * @since 20 + */ +typedef struct __TEE_SEServiceHandle *TEE_SEServiceHandle; + +/** + * @brief 定义 {@code TEE_SEReaderHandle} 的指针类型。 + * + * @since 20 + */ +typedef struct __TEE_SEReaderHandle *TEE_SEReaderHandle; + +/** + * @brief 定义 {@code TEE_SESessionHandle} 的指针类型。 + * + * @since 20 + */ +typedef struct __TEE_SESessionHandle *TEE_SESessionHandle; + +/** + * @brief 定义 {@code TEE_SEChannelHandle} 的指针类型。 + * + * @since 20 + */ +typedef struct __TEE_SEChannelHandle *TEE_SEChannelHandle; + +/** + * @brief 定义最大 ATR 长度。 + * + * @since 20 + */ +#define ATR_LEN_MAX 32U + +/** + * @brief 定义最小 AID 长度。 + * + * @since 20 + */ +#define AID_LEN_MIN 5U + +/** + * @brief 定义最大 AID 长度。 + * + * @since 20 + */ +#define AID_LEN_MAX 16U + +/** + * @brief 定义逻辑通道的最大值。 + * + * @since 20 + */ +#define SE_LOGIC_CHANNEL_MAX 8U + +/** + * @brief 定义 SCP03 类型。 + * + * @since 20 + */ +#define TEE_SC_TYPE_SCP03 0x01 + +/** + * @brief 定义字节长度。 + * + * @since 20 + */ +#define BYTE_LEN 8 + +/** + * @brief 表示 SE 读取器的属性。 + * + * @since 20 + */ +typedef struct __TEE_SEReaderProperties { + /** 如果读取器中存在 SE，则值为 true。 */ + bool sePresent; + /** 如果该读取器仅通过 TEE 访问，则值为 true。 */ + bool teeOnly; + /** 如果在 TEE 中可以获取对 SELECT 的响应，则值为 true。 */ + bool selectResponseEnable; +} TEE_SEReaderProperties; + +/** + * @brief 定义 SE AID。 + * + * @since 20 + */ +typedef struct __TEE_SEAID { + /** 应用程序的 AID 值。 */ + uint8_t *buffer; + /** 应用程序 AID 的长度。 */ + uint32_t bufferLen; +} TEE_SEAID; + +/** + * @brief 枚举密钥的类型。 + * + * @since 20 + */ +typedef enum { + /** 根据 SCP02 的基础密钥。 */ + TEE_SC_BASE_KEY = 0, + /** 根据 SCP02 和 SCP03 的密钥集（密钥-MAC，密钥-ENC）。 */ + TEE_SC_KEY_SET = 1 +} TEE_SC_KeyType; + +/** + * @brief 定义密钥集的引用。 + * + * @since 20 + */ +typedef struct __TEE_SC_KeySetRef { + /** 密钥-ENC（静态加密密钥）。 */ + TEE_ObjectHandle scKeyEncHandle; + /** 密钥-MAC（静态 MAC 密钥）。 */ + TEE_ObjectHandle scKeyMacHandle; +} TEE_SC_KeySetRef; + +/** + * @brief 枚举安全级别。 + * + * @since 20 + */ +typedef enum { + /** 不应用任何保护。 */ + TEE_SC_NO_SECURE_MESSAGING = 0x00, + /** 命令和响应 APDU 不加密。 */ + TEE_SC_AUTHENTICATE = 0x80, + /** 命令 APDU 应该进行 MAC 保护。 */ + TEE_SC_C_MAC = 0x01, + /** 响应 APDU 应该进行 MAC 保护。 */ + TEE_SC_R_MAC = 0x10, + /** 命令和响应 APDU 都应进行 MAC 保护。 */ + TEE_SC_CR_MAC = 0x11, + /** 命令 APDU 应该进行加密并进行 MAC 保护。 */ + TEE_SC_C_ENC_MAC = 0x03, + /** 响应 APDU 应该进行加密并进行 MAC 保护。 */ + TEE_SC_R_ENC_MAC = 0x30, + /** 命令和响应 APDU 都应进行加密并进行 MAC 保护。 */ + TEE_SC_CR_ENC_MAC = 0x33, + /** 命令 APDU 应该加密，且命令和响应 APDU 都应进行 MAC 保护。 */ + TEE_SC_C_ENC_CR_MAC = 0x13 +} TEE_SC_SecurityLevel; + +/** + * @brief 定义 TEE_SC_AUTHENTICATE 的别名。 + * + * @since 20 + */ +#define TEE_AUTHENTICATE TEE_SC_AUTHENTICATE + +/** + * @brief 表示 SC 卡密钥的引用。 + * + * @since 20 + */ +typedef struct __TEE_SC_CardKeyRef { + /** SC 卡密钥的密钥标识符。 */ + uint8_t scKeyID; + /** SC 卡密钥的密钥版本。 */ + uint8_t scKeyVersion; +} TEE_SC_CardKeyRef; + +/** + * @brief 表示 SC 设备密钥的引用。 + * + * @since 20 + */ +typedef struct __TEE_SC_DeviceKeyRef { + /** SC 密钥的类型。 */ + TEE_SC_KeyType scKeyType; + /** 包含 SC 密钥的具体信息. */ + union { + /** SC 基础密钥的句柄。 */ + TEE_ObjectHandle scBaseKeyHandle; + /** SC 密钥集的引用 */ + TEE_SC_KeySetRef scKeySetRef; + } __TEE_key; +} TEE_SC_DeviceKeyRef; + +/** + * @brief 定义 SC 的 OID。 + * + * @since 20 + */ +typedef struct __TEE_SC_OID { + /** OID 的值。 */ + uint8_t *buffer; + /** OID 的长度。 */ + uint32_t bufferLen; +} TEE_SC_OID; + +/** + * @brief 表示关于 SC 的参数。 + * + * @since 20 + */ +typedef struct __TEE_SC_Params { + /** SC 类型。 */ + uint8_t scType; + /** 由 OID 定义的 SC 类型。 */ + TEE_SC_OID scOID; + /** SC 的安全级别。 */ + TEE_SC_SecurityLevel scSecurityLevel; + /** SC 卡密钥的引用。 */ + TEE_SC_CardKeyRef scCardKeyRef; + /** SC 设备密钥的引用。 */ + TEE_SC_DeviceKeyRef scDeviceKeyRef; +} TEE_SC_Params; + +/** + * @brief 打开 SE 服务。 + * + * @param se_service_handle [IN] 指定 SE 服务的句柄。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。 + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数不正确。 + * 返回 {@code TEE_ERROR_ACCESS_CONFLICT} 表示由于冲突导致无法访问 SE 服务。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SEServiceOpen(TEE_SEServiceHandle *se_service_handle); + +/** + * @brief 关闭 SE 服务。 + * + * @param se_service_handle [IN] 指定 SE 服务的句柄。 + * + * @since 20 + * @version 1.0 + */ +void TEE_SEServiceClose(TEE_SEServiceHandle se_service_handle); + +/** + * @brief 获取 SE 服务的可用读取器句柄。 + * + * @param se_service_handle [IN] 指定 SE 服务的句柄。 + * @param se_reader_handle_list [OUT] 指定可用读取器的句柄列表。 + * @param se_reader_handle_list_len [OUT] 指定句柄列表的长度。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。 + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数不正确。 + * 返回 {@code TEE_ITEM_NOT_FOUND} 表示无法找到输入的 SE 服务句柄。 + * 返回 {@code TEE_ERROR_SHORT_BUFFER} 表示提供的缓冲区太小，无法存储读取器句柄。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SEServiceGetReaders(TEE_SEServiceHandle se_service_handle, TEE_SEReaderHandle *se_reader_handle_list, + uint32_t *se_reader_handle_list_len); + +/** + * @brief 获取 SE 服务的可用读取器的属性。 + * + * @param se_reader_handle [IN] 指定 SE 读取器的句柄。 + * @param reader_properties [OUT] 指定读取器的属性。 + * + * @since 20 + * @version 1.0 + */ +void TEE_SEReaderGetProperties(TEE_SEReaderHandle se_reader_handle, TEE_SEReaderProperties *reader_properties); + +/** + * @brief 获取 SE 读取器的名称。 + * + * @param se_reader_handle [IN] 指定 SE 读取器的句柄。 + * @param reader_name [OUT] 指定 SE 读取器的名称。 + * @param reader_name_len [OUT] 指定读取器名称的长度。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。 + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数不正确。 + * 返回 {@code TEE_ITEM_NOT_FOUND} 表示无法找到输入的 SE 读取器句柄。 + * 返回 {@code TEE_ERROR_BAD_FORMAT} 表示输入的 se_reader_handle 指向非法的读取器。 + * 返回 {@code TEE_ERROR_SHORT_BUFFER} 表示 reader_name_len 太小，无法存储读取器名称。 + * 返回 {@code TEE_ERROR_SECURITY} 表示检测到安全错误。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SEReaderGetName(TEE_SEReaderHandle se_reader_handle, char *reader_name, uint32_t *reader_name_len); + +/** + * @brief 在 SE 读取器和 SE 之间打开会话。 + * + * @param se_reader_handle 指定 SE 读取器的句柄。 + * @param se_session_handle 指定会话句柄。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。 + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数不正确。 + * 返回 {@code TEE_ITEM_NOT_FOUND} 表示无法找到输入的 SE 读取器句柄。 + * 返回 {@code TEE_ERROR_COMMUNICATION} 表示与 SE 通信失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SEReaderOpenSession(TEE_SEReaderHandle se_reader_handle, TEE_SESessionHandle *se_session_handle); + +/** + * @brief 关闭 SE 读取器和 SE 之间的会话。 + * + * @param se_reader_handle 指定 SE 读取器的句柄。 + * + * @since 20 + * @version 1.0 + */ +void TEE_SEReaderCloseSessions(TEE_SEReaderHandle se_reader_handle); + +/** + * @brief 获取 SE ATR。 + * + * @param se_session_handle 指定会话句柄。 + * @param atr 指定 SE ATR。 + * @param atrLen 指定 ATR 的长度。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。 + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数不正确。 + * 返回 {@code TEE_ERROR_SHORT_BUFFER} 表示提供的缓冲区太小，无法存储 ATR。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SESessionGetATR(TEE_SESessionHandle se_session_handle, void *atr, uint32_t *atrLen); + +/** + * @brief 检查会话是否已关闭。 + * + * @param se_session_handle 指定会话句柄。 + * + * @return 返回 {@code TEE_SUCCESS} 表示会话已关闭或输入的句柄无效。 + * 返回 {@code TEE_ERROR_COMMUNICATION} 表示会话状态无效。 + * 返回 {@code TEE_ERROR_BAD_STATE} 表示会话已打开。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SESessionIsClosed(TEE_SESessionHandle se_session_handle); + +/** + * @brief 关闭 SE 会话。 + * + * @param se_session_handle 指定会话句柄。 + * + * @since 20 + * @version 1.0 + */ +void TEE_SESessionClose(TEE_SESessionHandle se_session_handle); + +/** + * @brief 关闭所有由 SE 会话指向的通道。 + * + * @param se_session_handle 指定会话句柄。 + * + * @since 20 + * @version 1.0 + */ +void TEE_SESessionCloseChannels(TEE_SESessionHandle se_session_handle); + +/** + * @brief 打开 SE 会话指向的基本通道。 + * + * @param se_session_handle 指定会话句柄。 + * @param se_aid 指定 SE AID。 + * @param se_channel_handle 指定 SE 通道句柄。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。 + * 返回 {@code TEE_ERROR_BAD_STATE} 表示会话已关闭。 + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数不正确。 + * 返回 {@code TEE_ITEM_NOT_FOUND} 表示无法找到输入的 SE 读取器句柄。 + * 返回其他值表示 SE 响应异常状态字。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SESessionOpenBasicChannel(TEE_SESessionHandle se_session_handle, TEE_SEAID *se_aid, + TEE_SEChannelHandle *se_channel_handle); + +/** +* @brief 打开 SE 会话指向的逻辑通道。 +* +* @param se_session_handle 指定会话句柄。 +* @param se_aid 指定 SE AID。 +* @param se_channel_handle 指定 SE 通道句柄。 +* +* @return 返回 {@code TEE_SUCCESS} 表示操作成功。 +* 返回 {@code TEE_ERROR_BAD_STATE} 表示会话已关闭。 +* 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数不正确。 +* 返回 {@code TEE_ITEM_NOT_FOUND} 表示无法找到输入的 SE 读取器句柄。 +* 返回其他值表示 SE 响应异常状态字。 +* +* @since 20 +* @version 1.0 +*/ +TEE_Result TEE_SESessionOpenLogicalChannel(TEE_SESessionHandle se_session_handle, TEE_SEAID *se_aid, + TEE_SEChannelHandle *se_channel_handle); + +/** +* @brief 关闭由通道句柄指向的通道。 +* +* @param se_channel_handle 指定 SE 通道句柄。 +* +* @since 20 +* @version 1.0 +*/ +void TEE_SEChannelClose(TEE_SEChannelHandle se_channel_handle); + +/** + * @brief 选择由通道句柄指向的下一个 SE 服务。 + * + * @param se_channel_handle 指定 SE 通道句柄。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。 + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数无效或 SE 模式错误。 + * 返回其他值表示 SE 响应异常状态字。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SEChannelSelectNext(TEE_SEChannelHandle se_channel_handle); + +/** + * @brief 获取在打开通道句柄时 SE 的 SELECT 命令响应。 + * + * @param se_channel_handle 指定 SE 通道句柄。 + * @param response 指定 SE 的响应。 + * @param response_len 指定响应的长度。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。 + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数无效。 + * 返回 {@code TEE_ERROR_SHORT_BUFFER} 表示提供的缓冲区太小，无法存储响应。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SEChannelGetSelectResponse(TEE_SEChannelHandle se_channel_handle, void *response, + uint32_t *response_len); + +/** + * @brief 通过通道传输命令。 + * + * @param se_channel_handle 指定 SE 通道句柄。 + * @param command 指定传输的命令。 + * @param command_len 指定命令的长度。 + * @param response 指定 SE 的响应。 + * @param response_len 指定响应的长度。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。 + * 返回 {@code TEE_ERROR_COMMUNICATION} 表示命令长度小于 4。 + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数无效。 + * 返回 {@code TEE_ERROR_BAD_STATE} 表示通道已关闭。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SEChannelTransmit(TEE_SEChannelHandle se_channel_handle, void *command, uint32_t command_len, + void *response, uint32_t *response_len); + +/** + * @brief 打开基于输入通道句柄的 SE 安全通道。 + * 此后，当调用 {@code TEE_SEChannelTransmit} 时，基于该句柄传输的所有 APDU（加密/MAC 保护）会自动根据定义的安全通道参数选项进行保护。 + * 目前仅支持 SCP03。 + * + * @param se_channel_handle 指定 SE 通道句柄。 + * @param sc_params 指定安全通道协议的参数引用。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。 + * 返回 {@code TEE_ERROR_COMMUNICATION} 表示与 SE 通信失败。 + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数无效或 SE 模式错误。 + * 返回 {@code TEE_ERROR_NOT_SUPPORTED} 表示 sc_params 的参数不受支持。 + * 返回 {@code TEE_ERROR_MAC_INVALID} 表示验证失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SESecureChannelOpen(TEE_SEChannelHandle se_channel_handle, TEE_SC_Params *sc_params); + +/** + * @brief 关闭基于输入通道句柄的 SE 安全通道。 + * 由输入通道句柄指向的通道不会被关闭。 + * 它可以用于不安全的通信，但调用 {@code TEE_SEChannelTransmit} 时传输的 APDU 将不再是安全的。 + * + * @param se_channel_handle 指定 SE 通道句柄。 + * + * @since 20 + * @version 1.0 + */ +void TEE_SESecureChannelClose(TEE_SEChannelHandle se_channel_handle); + +/** + * @brief 获取由输入通道句柄指向的通道 ID。 + * + * @param se_channel_handle 指定 SE 通道句柄。 + * @param channel_id 指定 SE 通道 ID。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。 + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数无效。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SEChannelGetID(TEE_SEChannelHandle se_channel_handle, uint8_t *channel_id); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_log.h b/zh-cn/native_sdk/TEEKit/tee/tee_log.h new file mode 100644 index 00000000..7d0f3d6b --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_log.h @@ -0,0 +1,382 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_log.h + * + * @brief 提供 TEE 日志 API。 + * + * 包含 TEE 日志 API 及其内部定义的参考信息。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef __TEE_LOG_H +#define __TEE_LOG_H + +#include "tee_defines.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 定义 TA 日志的 ERROR 级别。 + * + * @since 20 + */ +#define TA_LOG_LEVEL_ERROR 0 + +/** + * @brief 定义 TA 日志的 WARNING 级别。 + * + * @since 20 + */ +#define TA_LOG_LEVEL_WARNING 1 + +/** + * @brief 定义 TA 日志的 INFO 级别。 + * + * @since 20 + */ +#define TA_LOG_LEVEL_INFO 2 + +/** + * @brief 定义 TA 日志的 DEBUG 级别。 + * + * @since 20 + */ +#define TA_LOG_LEVEL_DEBUG 3 + +/** + * @brief 定义 TA 日志的 VERBO（详细）级别。 + * + * @since 20 + */ +#define TA_LOG_LEVEL_VERBO 4 + +/** + * @brief 定义 TA 日志的默认级别。 + * + * @since 20 + */ +#define TA_LOG_LEVEL_DEFAULT TA_LOG_LEVEL_INFO + +/** + * @brief 定义 TA 日志的默认级别。 + * + * {@code TA_LOG_LEVEL} 可由 TA 开发人员重新定义。 + * + * @since 20 + */ +#ifndef TA_LOG_LEVEL +#define TA_LOG_LEVEL TA_LOG_LEVEL_DEFAULT +#endif + +/** + * @brief 定义 VERBO（详细）级别 TA 日志的标签。 + * + * @since 20 + */ +#define TAG_VERB "[verb]" + +/** + * @brief 定义 DEBUG 级别 TA 日志的标签。 + * + * @since 20 + */ +#define TAG_DEBUG "[debug]" + +/** + * @brief 定义 INFO 级别 TA 日志的标签。 + * + * @since 20 + */ +#define TAG_INFO "[info]" + +/** + * @brief 定义 WARNING 级别 TA 日志的标签。 + * + * @since 20 + */ +#define TAG_WARN "[warn]" + +/** + * @brief 定义 ERROR 级别 TA 日志的标签。 + * + * @since 20 + */ +#define TAG_ERROR "[error]" + +/** + * @brief 枚举日志的级别。 + * + * @since 20 + */ +typedef enum { + /** 错误级别日志。 */ + LOG_LEVEL_ERROR = 0, + /** 警告级别日志。 */ + LOG_LEVEL_WARN = 1, + /** 信息级别日志。 */ + LOG_LEVEL_INFO = 2, + /** 调试级别日志。 */ + LOG_LEVEL_DEBUG = 3, + /** 详细（VERBO）级别日志。 */ + LOG_LEVEL_VERBO = 4, + /** 开启日志记录。 */ + LOG_LEVEL_ON = 5, +} LOG_LEVEL; + +/** + * @brief 提供 UART 日志打印功能。 + * + * @param fmt [IN] 指向日志信息的指针。 + * + * @since 20 + */ +void uart_cprintf(const char *fmt, ...); + +/** + * @brief 提供 UART 日志打印功能。 + * + * @param fmt [IN] 指向日志信息的指针。 + * + * @since 20 + */ +void uart_printf_func(const char *fmt, ...); + +/** + * @brief 提供 TEE 日志打印功能。 + * + * @param log_level [IN] 日志级别。 + * @param fmt [IN] 指向日志信息的指针。 + * + * @since 20 + */ +void tee_print(LOG_LEVEL log_level, const char *fmt, ...); + +/** + * @brief 提供 TEE 驱动日志的打印功能。 + * + * @since 20 + */ +void tee_print_driver(LOG_LEVEL log_level, const char *log_tag, const char *fmt, ...); + +/** + * @brief 定义全局调试前缀字符串。 + * + * @since 20 + */ +extern const char *g_debug_prefix; + +#if (TA_LOG_LEVEL >= TA_LOG_LEVEL_VERBO) +#ifdef DRIVER_LOG_TAG +/** + * @brief 定义用于在 VERBO（详细）等级下输出 TEE 日志的宏接口（包含日志标签）。 + * + * @since 20 + */ +#define tlogv(fmt, args...) \ + tee_print_driver(LOG_LEVEL_VERBO, DRIVER_LOG_TAG, "%s %d:" fmt "", TAG_VERB, __LINE__, ##args) +#else +/** + * @brief 定义用于在 VERBO（详细）等级下输出 TEE 日志的宏接口（不含日志标签）。 + * + * @since 20 + */ +#define tlogv(fmt, args...) tee_print(LOG_LEVEL_VERBO, "%s %d:" fmt "", TAG_VERB, __LINE__, ##args) +#endif /* DRIVER_LOG_TAG */ +#else +/** + * @brief 定义空操作的 tlogv 宏，当日志等级低于 VERBO 时禁用详细日志。 + * + * @since 20 + */ +#define tlogv(fmt, args...) \ + do { \ + } while (0) +#endif /* TA_LOG_LEVEL >= TA_LOG_LEVEL_VERBO */ + +#if (TA_LOG_LEVEL >= TA_LOG_LEVEL_DEBUG) +#ifdef DRIVER_LOG_TAG +/** + * @brief 定义用于在 DEBUG 等级下输出 TEE 日志的宏接口（包含日志标签）。 + * + * @since 20 + */ +#define tlogd(fmt, args...) \ + tee_print_driver(LOG_LEVEL_DEBUG, DRIVER_LOG_TAG, "%s %d:" fmt "", TAG_DEBUG, __LINE__, ##args) +#else +/** + * @brief 定义用于在 DEBUG 等级下输出 TEE 日志的宏接口（不含日志标签）。 + * + * @since 20 + */ +#define tlogd(fmt, args...) tee_print(LOG_LEVEL_DEBUG, "%s %d:" fmt "", TAG_DEBUG, __LINE__, ##args) +#endif /* DRIVER_LOG_TAG */ +#else +/** + * @brief 定义空操作的 tlogd 宏，当日志等级低于 DEBUG 时禁用调试日志。 + * + * @since 20 + */ +#define tlogd(fmt, args...) \ + do { \ + } while (0) +#endif /* TA_LOG_LEVEL >= TA_LOG_LEVEL_DEBUG */ + +#if (TA_LOG_LEVEL >= TA_LOG_LEVEL_INFO) +#ifdef DRIVER_LOG_TAG +/** + * @brief 定义用于在 INFO 等级下输出 TEE 日志的宏接口（包含日志标签）。 + * + * @since 20 + */ +#define tlogi(fmt, args...) \ + tee_print_driver(LOG_LEVEL_INFO, DRIVER_LOG_TAG, "%s %d:" fmt "", TAG_INFO, __LINE__, ##args) +#else +/** + * @brief 定义用于在 INFO 等级下输出 TEE 日志的宏接口（不含日志标签）。 + * + * @since 20 + */ +#define tlogi(fmt, args...) tee_print(LOG_LEVEL_INFO, "%s %d:" fmt "", TAG_INFO, __LINE__, ##args) +#endif /* DRIVER_LOG_TAG */ +#else +/** + * @brief 定义空操作的 tlogi 宏，当日志等级低于 INFO 时禁用信息日志。 + * + * @since 20 + */ +#define tlogi(fmt, args...) \ + do { \ + } while (0) +#endif /* TA_LOG_LEVEL >= TA_LOG_LEVEL_INFO */ + +#if (TA_LOG_LEVEL >= TA_LOG_LEVEL_WARNING) +#ifdef DRIVER_LOG_TAG +/** + * @brief 定义用于在 WARNING 等级下输出 TEE 日志的宏接口（包含日志标签）。 + * + * @since 20 + */ +#define tlogw(fmt, args...) \ + tee_print_driver(LOG_LEVEL_WARN, DRIVER_LOG_TAG, "%s %d:" fmt "", TAG_WARN, __LINE__, ##args) +#else +/** + * @brief 定义用于在 WARNING 等级下输出 TEE 日志的宏接口（不含日志标签）。 + * + * @since 20 + */ +#define tlogw(fmt, args...) tee_print(LOG_LEVEL_WARN, "%s %d:" fmt "", TAG_WARN, __LINE__, ##args) +#endif /* DRIVER_LOG_TAG */ +#else +/** + * @brief 定义空操作的 tlogw 宏，当日志等级低于 WARNING 时禁用警告日志。 + * + * @since 20 + */ +#define tlogw(fmt, args...) \ + do { \ + } while (0) +#endif /* TA_LOG_LEVEL >= TA_LOG_LEVEL_WARNING */ + +#if (TA_LOG_LEVEL >= TA_LOG_LEVEL_ERROR) /* Always meet this condition. */ +#ifndef TLOGE_NO_TIMESTAMP +#ifdef DRIVER_LOG_TAG +/** + * @brief 定义用于在 ERROR 等级下输出 TEE 日志的宏接口（包含日志标签）。 + * + * @since 20 + */ +#define tloge(fmt, args...) \ + tee_print_driver(LOG_LEVEL_ERROR, DRIVER_LOG_TAG, "%s %d:" fmt " ", TAG_ERROR, __LINE__, ##args) +#else +/** + * @brief 定义用于在 ERROR 等级下输出 TEE 日志的宏接口（不含日志标签）。 + * + * @since 20 + */ +#define tloge(fmt, args...) tee_print(LOG_LEVEL_ERROR, "%s %d:" fmt " ", TAG_ERROR, __LINE__, ##args) +#endif /* DRIVER_LOG_TAG */ +#else +/** + * @brief 定义用于在 ERROR 等级下输出 TEE 日志的宏接口（不使用日志系统时间戳）。 + * + * @since 20 + */ +#define tloge(fmt, args...) printf("[%s] %s %d:" fmt " ", g_debug_prefix, TAG_ERROR, __LINE__, ##args) +#endif /* TLOGE_NO_TIMESTAMP */ +#else +/** + * @brief 定义空操作的 tloge 宏，当日志等级低于 ERROR 时禁用错误日志。 + * + * @since 20 + */ +#define tloge(fmt, args...) \ + do { \ + } while (0) +#endif /* TA_LOG_LEVEL >= TA_LOG_LEVEL_ERROR */ + +/** + * @brief 定义系统事件类型的枚举。 + * + * @since 20 + */ +typedef enum { + /** 故障事件。 */ + FAULT = 1, + /** 统计事件。 */ + STATISTIC = 2, + /** 安全事件。 */ + SECURITY = 3, + /** 行为事件。 */ + BEHAVIOR = 4, +} HISYSEVENT_TYPE; + +/** + * @brief 将 DFX 消息上报到 HiViewOcean 系统。 + * + * @param domain 表示消息的域名。 + * @param event 表示消息的事件名称。 + * @param event_type 表示消息的事件类型。 + * @param fmt 表示日志消息的格式字符串。 + * + * @since 20 + */ +void tee_report(const char *domain, const char *event, HISYSEVENT_TYPE event_type, const char *fmt, ...); + +#ifdef __cplusplus +} +#endif + +#endif /* __TEE_LOG_H */ +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_mem_mgmt_api.h b/zh-cn/native_sdk/TEEKit/tee/tee_mem_mgmt_api.h new file mode 100644 index 00000000..03c1055b --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_mem_mgmt_api.h @@ -0,0 +1,278 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_mem_mgmt_api.h + * + * @brief 提供内存管理相关的 API。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_MEM_MGMT_API_H +#define TEE_MEM_MGMT_API_H + +#include "tee_defines.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* + * The definitions below are defined by Global Platform or Platform SDK released previously + * for compatibility. + * Do not make any change to the content below. + */ +#ifndef ZERO_SIZE_PTR +/** + * @brief 表示零大小指针。 + * + * @since 20 + */ +#define ZERO_SIZE_PTR ((void *)16) +/** + * @brief 检查指针是否为零大小或 NULL。 + * + * @since 20 + */ +#define zero_or_null_ptr(x) ((unsigned long)(x) <= (unsigned long)ZERO_SIZE_PTR) +#endif + +/** + * @brief 定义内存分配的提示枚举值。 + * + * @since 20 + */ +enum MALLOC_HINT { + /** 未初始化的缓冲区。 */ + ZERO = 0, + /** 非零初始化的缓冲区。 */ + NOT_ZERO = 1, + /** 4 字节对齐的缓冲区。 */ + ALIGN_004 = 0x80000002, + /** 8 字节对齐的缓冲区。 */ + ALIGN_008 = 0x80000003, + /** 16 字节对齐的缓冲区。 */ + ALIGN_016 = 0x80000004, + /** 32 字节对齐的缓冲区。 */ + ALIGN_032 = 0x80000005, + /** 64 字节对齐的缓冲区。 */ + ALIGN_064 = 0x80000006, + /** 128 字节对齐的缓冲区。 */ + ALIGN_128 = 0x80000007, + /** 256 字节对齐的缓冲区。 */ + ALIGN_256 = 0x80000008, + /** 4 字节对齐并初始化为零的缓冲区。 */ + ALIGN_004_ZERO = 0x80000012, + /** 8 字节对齐并初始化为零的缓冲区。 */ + ALIGN_008_ZERO = 0x80000013, + /** 16 字节对齐并初始化为零的缓冲区。 */ + ALIGN_016_ZERO = 0x80000014, + /** 32 字节对齐并初始化为零的缓冲区。 */ + ALIGN_032_ZERO = 0x80000015, + /** 64 字节对齐并初始化为零的缓冲区。 */ + ALIGN_064_ZERO = 0x80000016, + /** 128 字节对齐并初始化为零的缓冲区。 */ + ALIGN_128_ZERO = 0x80000017, + /** 256 字节对齐并初始化为零的缓冲区。 */ + ALIGN_256_ZERO = 0x80000018, +}; + +/** + * @brief 分配的内存填充为零。 + * + * @since 20 + */ +#define TEE_MALLOC_FILL_ZERO 0x00000000 + +/** + * @brief 分配的内存不进行填充。 + * + * @since 20 + */ +#define TEE_MALLOC_NO_FILL 0x00000001 + +/** + * @brief 分配的内存不可共享。 + * + * @since 20 + */ +#define TEE_MALLOC_NO_SHARE 0x00000002 + +/** + * @brief 允许内存的读权限。 + * + * @since 20 + */ +#define TEE_MEMORY_ACCESS_READ 0x00000001 + +/** + * @brief 允许内存的写权限。 + * + * @since 20 + */ +#define TEE_MEMORY_ACCESS_WRITE 0x00000002 + +/** + * @brief 允许内存由任意所有者访问。 + * + * @since 20 + */ +#define TEE_MEMORY_ACCESS_ANY_OWNER 0x00000004 + +/** + * @brief 将指定值 x 填充到缓冲区的前 size 个字节中。 + * + * @param buffer 指向要填充的缓冲区的指针。 + * @param x 要填充的值。 + * @param size 要填充的字节数。 + * + * @since 20 + * @version 1.0 + */ +void TEE_MemFill(void *buffer, uint8_t x, size_t size); + +/** + * @brief 复制指定数量的字节。 + * + * @param dest 指向存储复制后字节的缓冲区的指针。 + * @param src 指向要复制的字节所在的缓冲区的指针。 + * @param size 要复制的字节数。 + * + * @since 20 + * @version 1.0 + */ +void TEE_MemMove(void *dest, const void *src, size_t size); + +/** + * @brief 为对象分配指定大小的内存空间。 + * + * @param size 要分配的内存大小。 + * @param hint 提供给分配器的提示。值为 0 表示返回的内存块已填充为 "\0"。 + * + * @return 成功时，返回指向新分配内存空间的指针。\n + * 失败时，返回 NULL 指针。 + * + * @since 20 + * @version 1.0 + */ +void *TEE_Malloc(size_t size, uint32_t hint); + +/** + * @brief 释放由 TEE_Malloc 分配的内存。 + * + * 如果缓冲区指针为 NULL，TEE_Free 不执行任何操作。\n + * 要释放的缓冲区必须由 TEE_Malloc 或 TEE_Realloc 分配，且不能重复释放， + * 否则可能导致意外结果。 + * + * @param buffer 指向要释放的内存的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_Free(void *buffer); + +/** + * @brief 重新分配内存。 + * + * 如果 new_size 大于原有大小，原内存的内容保持不变，超出部分包含未指定的内容。\n + * 如果新内存对象的大小需要移动对象，则会释放之前的内存空间。\n + * 如果无法分配空间，原内存对象仍保持分配状态，且该函数返回 NULL 指针。\n + * 如果缓冲区指针为 NULL，此函数等效于 TEE_Malloc。 + * + * @param buffer 指向要重新分配内存的指针。 + * @param new_size 指定所需的新内存大小。 + * + * @return 成功时，返回指向已分配内存的指针。\n + * 失败时，返回 NULL 指针。 + * + * @since 20 + * @version 1.0 + */ +void *TEE_Realloc(void *buffer, size_t new_size); + +/** + * @brief 从起始位置比较内存内容。 + * + * @param buffer1 指向第一个缓冲区的指针。 + * @param buffer2 指向第二个缓冲区的指针。 + * @param size 指定要比较的字节数。 + * + * @return 返回 -1 表示 buffer1 < buffer2。\n + * 返回 0 表示 buffer1 == buffer2。\n + * 返回 1 表示 buffer1 > buffer2。 + * + * @since 20 + * @version 1.0 + */ +int32_t TEE_MemCompare(const void *buffer1, const void *buffer2, size_t size); + +/** + * @brief 检查当前 TA 是否具有访问指定缓冲区的权限。 + * + * @param accessFlags 指定要检查的访问权限。 + * @param buffer 指向目标缓冲区的指针。 + * @param size 指定要检查的缓冲区大小。 + * + * @return 返回 TEE_SUCCESS 表示 TA 具有所请求的权限。\n + * 返回 TEE_ERROR_ACCESS_DENIED 表示无权限。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_CheckMemoryAccessRights(uint32_t accessFlags, const void *buffer, size_t size); + +/** + * @brief 设置 TA 实例数据指针。 + * + * @param instanceData 指向全局 TA 实例数据的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_SetInstanceData(void *instanceData); + +/** + * @brief 获取由 TA 使用 TEE_SetInstanceData 设置的实例数据指针。 + * + * @return 返回由 TEE_SetInstanceData 设置的实例数据指针。\n + * 如果未设置实例数据指针，则返回 NULL。 + * + * @since 20 + * @version 1.0 + */ +void *TEE_GetInstanceData(void); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_notify_set_priority.h b/zh-cn/native_sdk/TEEKit/tee/tee_notify_set_priority.h new file mode 100644 index 00000000..58a55442 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_notify_set_priority.h @@ -0,0 +1,68 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_notify_set_priority.h + * + * @brief 提供设置影子线程优先级的接口。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_NOTIFY_SET_PRIORITY_H +#define TEE_NOTIFY_SET_PRIORITY_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 支持设置影子线程的优先级。 + * + * @param priority_ree [IN] 影子线程的优先级。 + * + * @return 0 表示设置成功。 + * @return TEE_ERROR_ACCESS_DENIED 表示无访问权限（线程未设置影子线程标志）。 + * @return TEE_ERROR_BAD_PARAMETERS 表示传入的 priority_ree 参数无效。 + * @return -1 表示设置优先级失败。 + * + * @since 20 + * @version 1.0 + */ +int spi_notify_set_shadow_priority(uint32_t priority_ree); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_object_api.h b/zh-cn/native_sdk/TEEKit/tee/tee_object_api.h new file mode 100644 index 00000000..23578d22 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_object_api.h @@ -0,0 +1,376 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_object_api.h + * + * @brief 提供可信存储 API。 + * + * 这些 API 可用于实现可信存储功能。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef __TEE_OBJECT_API_H +#define __TEE_OBJECT_API_H + +#include "tee_defines.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 定义 HANDLE_NULL，用于表示句柄的缺失。 + * + * @since 20 + */ +#define TEE_HANDLE_NULL 0x00000000 + +/** + * @brief 枚举 TEE_ObjectHandle 的密钥用途。 + * + * @since 20 + */ +enum Usage_Constants { + /** 该对象的密钥是可提取的。 */ + TEE_USAGE_EXTRACTABLE = 0x00000001, + /** 用于加密。 */ + TEE_USAGE_ENCRYPT = 0x00000002, + /** 用于解密。 */ + TEE_USAGE_DECRYPT = 0x00000004, + /** 用于哈希计算。 */ + TEE_USAGE_MAC = 0x00000008, + /** 用于创建签名。 */ + TEE_USAGE_SIGN = 0x00000010, + /** 用于签名验证。 */ + TEE_USAGE_VERIFY = 0x00000020, + /** 用于密钥派生。 */ + TEE_USAGE_DERIVE = 0x00000040, + /** 用于对象初始化，默认分配所有权限。 */ + TEE_USAGE_DEFAULT = 0xFFFFFFFF, +}; + +/** + * @brief 定义 TEE_ObjectHandle 标志所指向对象的信息，例如对象是否为持久对象或已初始化。 + * + * @since 20 + */ +enum Handle_Flag_Constants { + /** 该对象是持久对象。 */ + TEE_HANDLE_FLAG_PERSISTENT = 0x00010000, + /** 该对象已初始化。 */ + TEE_HANDLE_FLAG_INITIALIZED = 0x00020000, + /** 保留字段 */ //TODO + TEE_HANDLE_FLAG_KEY_SET = 0x00040000, + /** 保留字段 */ //TODO + TEE_HANDLE_FLAG_EXPECT_TWO_KEYS = 0x00080000, +}; + +/** + * @brief 定义值属性标识符标志。 + * + * @since 20 + */ +#define TEE_ATTR_FLAG_VALUE 0x20000000 + +/** + * @brief 定义公有属性标识符标志。 + * + * @since 20 + */ +#define TEE_ATTR_FLAG_PUBLIC 0x10000000 + +/** + * @brief 检查属性是否为缓冲区类型。 + * + * @since 20 + */ +#define TEE_ATTR_IS_BUFFER(attribute_id) ((((attribute_id) << 2) >> 31) == 0) + +/** + * @brief 检查属性是否为值类型。 + * + * @since 20 + */ +#define TEE_ATTR_IS_VALUE(attribute_id) ((((attribute_id) << 2) >> 31) == 1) + +/** + * @brief 检查属性是否受保护。 + * + * @since 20 + */ +#define TEE_ATTR_IS_PROTECTED(attribute_id) ((((attribute_id) << 3) >> 31) == 0) + +/** + * @brief 检查属性是否为公有属性。 + * + * @since 20 + */ +#define TEE_ATTR_IS_PUBLIC(attribute_id) ((((attribute_id) << 3) >> 31) == 1) + +/** + * @brief 从指向对象的 TEE_ObjectHandle 结构体中的 TEE_Attribute 获取缓冲区属性。 + * + * TEE_Attribute 结构体中的成员必须是 ref 类型。如果 TEE_Attribute 是私有的， + * 则对象的 Usage_Constants 必须包含 TEE_USAGE_EXTRACTABLE。 + * + * @param object 指示对象的句柄。 + * @param attributeID 指示要获取的属性的 ID，例如 TEE_ObjectAttribute。 + * 属性 ID 也可以自定义。 + * @param buffer 指向存储获取的属性的缓冲区的指针。 + * @param size 指向存储内容长度的指针。 + * + * @return 如果操作成功，返回 TEE_SUCCESS。\n + * 如果无法在对象中找到 TEE_Attribute 或对象未初始化，返回 TEE_ERROR_ITEM_NOT_FOUND。\n + * 如果缓冲区太小，无法存储获取的内容，返回 TEE_ERROR_SHORT_BUFFER。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_GetObjectBufferAttribute(TEE_ObjectHandle object, uint32_t attributeID, void *buffer, size_t *size); + +/** + * @brief 从对象的 TEE_Attribute 获取值属性。 + * + * TEE_Attribute 结构体的成员必须是值类型。如果 TEE_Attribute 是私有的， + * 则对象的 Usage_Constants 必须包含 TEE_USAGE_EXTRACTABLE。 + * + * @param object 指示对象的句柄。 + * @param attributeID 指示要获取的属性的 ID，例如 TEE_ObjectAttribute。 + * 属性 ID 也可以自定义。 + * @param a 指向用属性字段 a 填充的占位符的指针。 + * @param b 指向用属性字段 b 填充的占位符的指针。 + * + * @return 如果操作成功，返回 TEE_SUCCESS。\n + * 如果无法在对象中找到 TEE_Attribute 或对象未初始化，返回 TEE_ERROR_ITEM_NOT_FOUND。\n + * 如果 TEE_Attribute 是私有的，但对象的 Usage_Constants 不包含 TEE_USAGE_EXTRACTABLE 标志，返回 TEE_ERROR_ACCESS_DENIED。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_GetObjectValueAttribute(TEE_ObjectHandle object, uint32_t attributeID, uint32_t *a, uint32_t *b); + +/** + * @brief 关闭 TEE_ObjectHandle 对象。 + * + * 该对象可以是持久对象或临时对象。 + * + * @param object 指示要关闭的 TEE_ObjectHandle 对象。 + * + * @since 20 + * @version 1.0 + */ +void TEE_CloseObject(TEE_ObjectHandle object); + +/** + * @brief 分配一个未初始化的对象来存储密钥。 + * + * 必须指定 objectType 和 maxObjectSize。 + * + * @param objectType 表示要创建的对象类型，值为 TEE_ObjectType。 + * @param maxObjectSize 表示对象的最大字节数。 + * @param object 表示指向新创建对象句柄的指针。 + * + * @return 如果操作成功，返回 TEE_SUCCESS。 + * 如果内存不足，返回 TEE_ERROR_OUT_OF_MEMORY。\n + * 如果不支持该对象类型，返回 TEE_ERROR_NOT_SUPPORTED。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_AllocateTransientObject(uint32_t objectType, uint32_t maxObjectSize, TEE_ObjectHandle *object); + +/** + * @brief 释放之前使用 TEE_AllocateTransientObject 分配的临时对象。 + * + * 调用此函数后，句柄变为无效，所有分配的资源被释放。 + * TEE_FreeTransientObject 和 TEE_AllocateTransientObject 是一对使用的函数。 + * + * @param object 表示要释放的 TEE_ObjectHandle。 + * + * @since 20 + * @version 1.0 + */ +void TEE_FreeTransientObject(TEE_ObjectHandle object); + +/** + * @brief 将一个未初始化的对象重置为其分配后的初始状态。 + * + * 可以使用一个已分配但尚未初始化或用来存储密钥的对象来存储密钥。 + * + * @param object 表示要重置的 TEE_ObjectHandle。 + * + * @since 20 + * @version 1.0 + */ +void TEE_ResetTransientObject(TEE_ObjectHandle object); + +/** + * @brief 用 TA 传递的 attrs 参数中的对象属性填充未初始化的对象。 + * + * 对象必须是未初始化的。\n + * attrs 参数由 TA 传递。 + * + * @param object 表示已创建但未初始化对象的句柄。 + * @param attrs 表示指向对象属性数组的指针，数组可以包含一个或多个 TEE_Attribute。 + * @param attrCount 表示属性数组中的成员数。 + * + * @return 如果操作成功，返回 TEE_SUCCESS。\n + * 如果检测到不正确或不一致的属性值，返回 TEE_ERROR_BAD_PARAMETERS。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_PopulateTransientObject(TEE_ObjectHandle object, TEE_Attribute *attrs, uint32_t attrCount); + +/** + * @brief 初始化缓冲区类型的 TEE_Attribute。 + * + * TEE_Attribute 结构中的成员必须是 ref 类型。 + * + * @param attr 表示指向已初始化的 TEE_Attribute 的指针。 + * @param attributeID 表示分配给 TEE_Attribute 的 ID。 + * @param buffer 表示指向用于存储待分配内容的缓冲区的指针。 + * @param length 表示分配值的长度，单位为字节。 + * + * @since 20 + * @version 1.0 + */ +void TEE_InitRefAttribute(TEE_Attribute *attr, uint32_t attributeID, void *buffer, size_t length); + +/** + * @brief 初始化一个 TEE_Attribute。 + * + * @param attr 表示指向已初始化的 TEE_Attribute 的指针。 + * @param attributeID 表示分配给 TEE_Attribute 的 ID。 + * @param a 表示要分配给 TEE_Attribute 成员 a 的值。 + * @param b 表示要分配给 TEE_Attribute 成员 b 的值。 + * + * @since 20 + * @version 1.0 + */ +void TEE_InitValueAttribute(TEE_Attribute *attr, uint32_t attributeID, uint32_t a, uint32_t b); + +/** + * @brief 生成一个随机密钥或密钥对，并将生成的密钥填充到临时密钥对象中。 + * + * @param object 表示用于保存生成密钥的临时对象。 + * @param keySize 表示密钥的字节数。 + * @param params 表示指向密钥生成参数的指针。 + * @param paramCount 表示密钥生成所需的参数数量。 + * + * @return 如果操作成功，返回 TEE_SUCCESS。\n + * 如果生成的密钥类型与临时对象能保存的密钥类型不匹配，返回 TEE_ERROR_BAD_PARAMETERS。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_GenerateKey(TEE_ObjectHandle object, uint32_t keySize, TEE_Attribute *params, uint32_t paramCount); + +/** + * @brief 获取对象数据部分的信息，包括数据部分的总长度和数据流的当前位置信息。 + * + * @param object 表示对象的句柄。 + * @param pos 表示数据流的位置。 + * @param len 表示数据流的长度。 + * + * @return 如果操作成功，返回 TEE_SUCCESS。\n + * 如果操作失败，返回其他错误码。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_InfoObjectData(TEE_ObjectHandle object, uint32_t *pos, uint32_t *len); + +/** + * @brief 获取 TEE_ObjectInfo。 + * + * 此函数获取 TEE_ObjectInfo 并将获取的信息复制到预分配的空间， + * 该空间由 objectInfo 指针指向。 + * + * @param object 表示对象的句柄。 + * @param objectInfo 表示指向获取的 TEE_ObjectInfo 的指针。 + * + * @return 如果操作成功，返回 TEE_SUCCESS。\n + * 如果对象已损坏，将关闭该对象句柄并返回 TEE_ERROR_CORRUPT_OBJECT。\n + * 如果对象存储在当前不可访问的存储区域，返回 TEE_ERROR_STORAGE_NOT_AVAILABLE。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_GetObjectInfo1(TEE_ObjectHandle object, TEE_ObjectInfo *objectInfo); + +/** + * @brief 将已初始化对象的 TEE_Attribute 分配给未初始化对象。 + * + * 此函数将一个未初始化对象填充为 TEE_Attribute。\n + * 即将 srcobject 的 TEE_Attribute 复制到 destobject。\n + * 两个对象的 TEE_Attribute 类型和 ID 必须匹配。 + * + * @param destObject 表示未初始化的对象。 + * @param srcObject 表示已初始化的对象。 + * + * @return 如果操作成功，返回 TEE_SUCCESS。\n + * 如果对象已损坏，将关闭该对象句柄并返回 TEE_ERROR_CORRUPT_OBJECT。\n + * 如果对象存储在当前不可访问的存储区域，返回 TEE_ERROR_STORAGE_NOT_AVAILABLE。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_CopyObjectAttributes1(TEE_ObjectHandle destObject, TEE_ObjectHandle srcObject); + +/** + * @brief 限制对象的 objectUse 位。 + * + * 该位决定对象中密钥的使用方式。值的范围是 Usage_Constant。\n + * objectUse 参数中的位可以如下设置：\n + * 如果设置为 1，对象中的相应使用标志保持不变。\n + * 如果设置为 0，则清除对象中的相应使用标志。\n + * 新创建的对象包含所有 Usage_Constant，并且只能清除使用标志。 + * + * @param object 表示目标对象的 TEE_ObjectHandle。 + * @param objectUsage 表示新的对象使用方式。 + * + * @return 如果操作成功，返回 TEE_SUCCESS。\n + * 如果对象已损坏，将关闭该对象句柄并返回 TEE_ERROR_CORRUPT_OBJECT。\n + * 如果对象存储在当前不可访问的存储区域，返回 TEE_ERROR_STORAGE_NOT_AVAILABLE。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_RestrictObjectUsage1(TEE_ObjectHandle object, uint32_t objectUsage); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_property_api.h b/zh-cn/native_sdk/TEEKit/tee/tee_property_api.h new file mode 100644 index 00000000..e2b0ae29 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_property_api.h @@ -0,0 +1,272 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_property_api.h + * + * @brief TEE 对象 API 定义的参考。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_PROPERTY_API_H +#define TEE_PROPERTY_API_H + +#include "tee_defines.h" + +#ifdef __cplusplus +extern "C" { +#endif +/** + * @brief 以下定义由 Global Platform 或先前发布的 Platform SDK 定义，以保持兼容性。 + * 请勿更改以下内容。 + */ + +/** + * @brief 枚举属性集的类型。 + * + * @since 20 + */ +typedef enum { + /** 未知的属性集类型。 */ + TEE_PROPSET_UNKNOW = 0, + /** TEE 实现的属性集类型。 */ + TEE_PROPSET_TEE_IMPLEMENTATION = 0xFFFFFFFD, + /** 当前客户端的属性集类型。 */ + TEE_PROPSET_CURRENT_CLIENT = 0xFFFFFFFE, + /** 当前可信应用 (TA) 的属性集类型。 */ + TEE_PROPSET_CURRENT_TA = 0xFFFFFFFF, +} Pseudo_PropSetHandle; + +/** + * @brief 定义属性集句柄类型。 + * + * @since 20 + */ +typedef uint32_t TEE_PropSetHandle; + +/** + * @brief 从属性集中获取属性并将其值转换为可打印字符串。 + * + * @param propsetOrEnumerator 指向一个 TEE_PROPSET_XXX 伪句柄或属性枚举器句柄。 + * @param name 指向包含要获取的属性名称的以零结尾的字符串的指针。 + * @param valueBuffer 指向用于存储获取到的属性值的缓冲区的指针。 + * @param valueBufferLen 指向缓冲区长度的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_ITEM_NOT_FOUND 表示无法获取目标属性。\n + * 返回 TEE_ERROR_SHORT_BUFFER 表示值缓冲区的空间不足以存储获取的属性值。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_GetPropertyAsString(TEE_PropSetHandle propsetOrEnumerator, const char *name, char *valueBuffer, + size_t *valueBufferLen); + +/** +* @brief 从属性集中获取属性并将其值转换为布尔值。 +* +* @param propsetOrEnumerator 指向一个 TEE_PROPSET_XXX 伪句柄或属性枚举器句柄。 +* @param name 指向包含要获取的属性名称的以零结尾的字符串的指针。 +* @param value 指向用于存储获取到的属性值的变量的指针。 +* +* @return 返回 TEE_SUCCESS 表示操作成功。\n +* 返回 TEE_ERROR_ITEM_NOT_FOUND 表示无法获取目标属性。 +* +* @since 20 +* @version 1.0 +*/ +TEE_Result TEE_GetPropertyAsBool(TEE_PropSetHandle propsetOrEnumerator, const char *name, bool *value); + +/** +* @brief 从属性集中获取属性并将其值转换为 32 位无符号整数。 +* +* @param propsetOrEnumerator 指向一个 TEE_PROPSET_XXX 伪句柄或属性枚举器句柄。 +* @param name 指向包含要获取的属性名称的以零结尾的字符串的指针。 +* @param value 指向用于存储获取到的属性值的变量的指针。 +* +* @return 返回 TEE_SUCCESS 表示操作成功。\n +* 返回 TEE_ERROR_ITEM_NOT_FOUND 表示无法获取目标属性。 +* +* @since 20 +* @version 1.0 +*/ +TEE_Result TEE_GetPropertyAsU32(TEE_PropSetHandle propsetOrEnumerator, const char *name, uint32_t *value); + +#if defined(API_LEVEL) && (API_LEVEL >= API_LEVEL1_2) +/** + * @brief 从属性集中获取属性并将其值转换为 64 位无符号整数。 + * + * @param propsetOrEnumerator 指向一个 TEE_PROPSET_XXX 伪句柄或属性枚举器句柄。 + * @param name 指向包含要获取的属性名称的以零结尾的字符串的指针。 + * @param value 指向用于存储获取到的属性值的变量的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_ITEM_NOT_FOUND 表示无法获取目标属性。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_GetPropertyAsU64(TEE_PropSetHandle propsetOrEnumerator, const char *name, uint64_t *value); +#endif // API_LEVEL + +/** + * @brief 从属性集中获取属性并将其值转换为二进制块。 + * + * @param propsetOrEnumerator 指向一个 TEE_PROPSET_XXX 伪句柄或属性枚举器句柄。 + * @param name 指向包含要获取的属性名称的以零结尾的字符串的指针。 + * @param valueBuffer 指向用于存储获取到的属性值的缓冲区的指针。 + * @param valueBufferLen 指向缓冲区长度的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_ITEM_NOT_FOUND 表示无法获取目标属性。\n + * 返回 TEE_ERROR_SHORT_BUFFER 表示值缓冲区空间不足，无法容纳完整的属性值。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_GetPropertyAsBinaryBlock(TEE_PropSetHandle propsetOrEnumerator, const char *name, void *valueBuffer, + size_t *valueBufferLen); + +/** +* @brief 从属性集中获取属性并将其值转换为 TEE_UUID 结构体。 +* +* @param propsetOrEnumerator 指向一个 TEE_PROPSET_XXX 伪句柄或属性枚举器句柄。 +* @param name 指向包含要获取的属性名称的以零结尾的字符串的指针。 +* @param value 指向用于存储获取到的属性值的变量的指针。 +* +* @return 返回 TEE_SUCCESS 表示操作成功。\n +* 返回 TEE_ERROR_ITEM_NOT_FOUND 表示无法获取目标属性。 +* +* @since 20 +* @version 1.0 +*/ +TEE_Result TEE_GetPropertyAsUUID(TEE_PropSetHandle propsetOrEnumerator, const char *name, TEE_UUID *value); + +/** +* @brief 从属性集中获取属性并将其值转换为 TEE_Identity 结构体。 +* +* @param propsetOrEnumerator 指向一个 TEE_PROPSET_XXX 伪句柄或属性枚举器句柄。 +* @param name 指向包含要获取的属性名称的以零结尾的字符串的指针。 +* @param value 指向用于存储获取到的属性值的变量的指针。 +* +* @return 返回 TEE_SUCCESS 表示操作成功。\n +* 返回 TEE_ERROR_ITEM_NOT_FOUND 表示无法获取目标属性。 +* +* @since 20 +* @version 1.0 +*/ +TEE_Result TEE_GetPropertyAsIdentity(TEE_PropSetHandle propsetOrEnumerator, const char *name, TEE_Identity *value); + +/** + * @brief 分配一个属性枚举器对象。 + * + * @param enumerator 指向用于存储分配的属性枚举器句柄的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_OUT_OF_MEMORY 表示资源不足，无法分配属性枚举器。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_AllocatePropertyEnumerator(TEE_PropSetHandle *enumerator); + +/** + * @brief 释放一个属性枚举器对象。 + * + * @param enumerator 指向要释放的属性枚举器的句柄。 + * + * @return 无返回值。 + * + * @since 20 + * @version 1.0 + */ +void TEE_FreePropertyEnumerator(TEE_PropSetHandle enumerator); + +/** + * @brief 开始枚举属性枚举器中的属性。 + * + * @param enumerator 指向属性枚举器的句柄。 + * @param propSet 指向要枚举的属性集的伪句柄。 + * + * @return 无返回值。 + * + * @since 20 + * @version 1.0 + */ +void TEE_StartPropertyEnumerator(TEE_PropSetHandle enumerator, TEE_PropSetHandle propSet); + +/** + * @brief 立即重置属性枚举器（通常在分配后执行）。 + * + * @param enumerator 指向要重置的属性枚举器的句柄。 + * + * @return 无返回值。 + * + * @since 20 + * @version 1.0 + */ +void TEE_ResetPropertyEnumerator(TEE_PropSetHandle enumerator); + +/** + * @brief 获取枚举器中当前属性的名称。 + * + * @param enumerator 指向属性枚举器的句柄。 + * @param nameBuffer 指向用于存储获取到的属性名称的缓冲区的指针。 + * @param nameBufferLen 指向缓冲区长度的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_ITEM_NOT_FOUND 表示未找到属性，可能是因为枚举器尚未启动或已到达属性集的末尾。\n + * 返回 TEE_ERROR_SHORT_BUFFER 表示缓冲区空间不足，无法存储属性名称。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_GetPropertyName(TEE_PropSetHandle enumerator, void *nameBuffer, size_t *nameBufferLen); + +/** + * @brief 获取枚举器中的下一个属性。 + * + * @param enumerator 指向属性枚举器的句柄。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_ITEM_NOT_FOUND 表示未找到属性，可能是因为枚举器尚未启动或已到达属性集的末尾。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_GetNextProperty(TEE_PropSetHandle enumerator); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_rtc_time_api.h b/zh-cn/native_sdk/TEEKit/tee/tee_rtc_time_api.h new file mode 100644 index 00000000..eea4010a --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_rtc_time_api.h @@ -0,0 +1,117 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_rtc_time_api.h + * + * @brief 提供关于 rtc 定时器的 API。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef __TEE_RTC_TIME_API_H +#define __TEE_RTC_TIME_API_H + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 创建一个安全定时器。 + * + * @param time_seconds 指定安全时长。 + * @param timer_property 指定定时器的属性，仅需指定定时器类型。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。 + * @return 返回其他值表示操作失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_create_timer(uint32_t time_seconds, TEE_timer_property *timer_property); + +/** + * @brief 销毁一个安全定时器。 + * + * @param timer_property 指定定时器的属性，仅需指定定时器类型。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。 + * @return 返回其他值表示操作失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_destory_timer(TEE_timer_property *timer_property); + +/** + * @brief 获取设定的定时时长。 + * + * @param timer_property 指定定时器的属性，仅需指定定时器类型。 + * @param time_seconds 指定定时时长。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。 + * @return 返回其他值表示操作失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_get_timer_expire(TEE_timer_property *timer_property, uint32_t *time_seconds); + +/** + * @brief 获取剩余的定时时长。 + * + * @param timer_property 指定定时器的属性，仅需指定定时器类型。 + * @param time_seconds 指定剩余定时时长。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。 + * @return 返回其他值表示操作失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result tee_ext_get_timer_remain(TEE_timer_property *timer_property, uint32_t *time_seconds); + +/** + * @brief 获取当前 RTC 时钟的时间。 + * @attention 获取的时间是秒数，无法转换为通用时间。 + * + * @return RTC 时钟计数（秒数）。 + * + * @since 20 + * @version 1.0 + */ +unsigned int tee_get_secure_rtc_time(void); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_service_public.h b/zh-cn/native_sdk/TEEKit/tee/tee_service_public.h new file mode 100644 index 00000000..5c758e42 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_service_public.h @@ -0,0 +1,194 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_service_public.h + * + * @brief 提供 TEE 服务的公共函数，供开发者使用。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef _TEE_SERVICE_PUBLIC_H_ +#define _TEE_SERVICE_PUBLIC_H_ + +#include "tee_defines.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 定义函数指针类型。 + * + * @since 20 + */ +typedef void (*func_ptr)(void); + +/** + * @brief 定义 TEE 服务的消息队列大小。 + * + * @since 20 + */ +#define TEE_SERVICE_MSG_QUEUE_SIZE 100 + +/** + * @brief 定义镜像哈希值的最大长度。 + * + * @since 20 + */ +#define MAX_IMAGE_HASH_SIZE 64 + +/** + * @brief 定义消息的参数。 + * + * @since 20 + */ +typedef struct { + /** 参数 0。 */ + uint64_t arg0; + /** 参数 1。 */ + uint64_t arg1; + /** 参数 2。 */ + uint64_t arg2; + /** 参数 3。 */ + uint64_t arg3; + /** 参数 4。 */ + uint64_t arg4; + /** 参数 5。 */ + uint64_t arg5; + /** 参数 6。 */ + uint64_t arg6; + /** 参数 7。 */ + uint64_t arg7; +} args_t; + +/** + * @brief 定义 TA 的注册信息。 + * + * @since 20 + */ +struct reg_ta_info { + /** TA 的任务 ID。 */ + uint32_t taskid; + /** TA 的 UUID（通用唯一标识符）。 */ + TEE_UUID uuid; + /** 用户 ID。 */ + uint32_t userid; + /** 仅用于 SSA，其他任务应忽略此字段。 */ + bool ssa_enum_enable; +}; + +/** + * @brief 定义 TEE 服务的 IPC（进程间通信）消息。 + * + * @since 20 + */ +typedef union { + /** 参数数据。 */ + args_t args_data; + /** TA 的注册信息。 */ + struct reg_ta_info reg_ta; +} tee_service_ipc_msg; + +/** + * @brief 定义 TEE 服务的 IPC 请求消息。 + * + * @since 20 + */ +struct tee_service_ipc_msg_req { + /** 请求的命令标识。 */ + uint32_t cmd; + /** 请求中携带的 IPC 消息。 */ + tee_service_ipc_msg msg; +}; + +/** + * @brief 定义 TEE 服务的 IPC 响应消息。 + * + * @since 20 + */ +typedef struct { + /** 请求的返回结果。 */ + TEE_Result ret; + /** 响应中携带的 IPC 消息。 */ + tee_service_ipc_msg msg; +} tee_service_ipc_msg_rsp; + +/** + * @brief 定义 TEE 服务的消息。 + * + * @since 20 + */ +typedef struct { + /** 消息 ID，标识消息的唯一标识符。 */ + uint32_t msg_id; + /** 发送该消息的发送者 ID。 */ + uint32_t sender; + /** 消息数据。 */ + tee_service_ipc_msg msg; +} tee_service_msg_t; + +/** + * @brief 定义 TEE 服务的消息队列。 + * + * @since 20 + */ +typedef struct { + /** 指向队列的输入位置。 */ + uint32_t in; + /** 指向队列的输出位置。 */ + uint32_t out; + /** 消息数组，存储队列中的消息。 */ + tee_service_msg_t msg[TEE_SERVICE_MSG_QUEUE_SIZE]; +} tee_service_msg_queue_t; + +/** + * @brief 向指定服务发送 IPC 同步消息并接收来自该服务的响应。 + * + * @param task_name 指向接收方任务名称的指针。 + * @param snd_cmd 要发送的消息的命令 ID。 + * @param snd_msg 指向发送消息的指针。 + * @param ack_cmd 要接收的应答命令 (ack cmd) 的 ID。 + * @param rsp_msg 指向服务响应消息的指针。 + * + * @since 20 + * @version 1.0 + */ +void tee_common_ipc_proc_cmd(const char *task_name, + uint32_t snd_cmd, const tee_service_ipc_msg *snd_msg, + uint32_t ack_cmd, tee_service_ipc_msg_rsp *rsp_msg); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_sharemem.h b/zh-cn/native_sdk/TEEKit/tee/tee_sharemem.h new file mode 100644 index 00000000..d6eee2ec --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_sharemem.h @@ -0,0 +1,64 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_sharemem.h + * + * @brief 提供共享内存相关的API。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_EXT_SHAREMEM_H +#define TEE_EXT_SHAREMEM_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 获取高级安全模式 + * + * @param advsecmode [OUT] 返回值为 0 表示非高级安全模式；非零值表示对应等级的安全模式。 + * + * @return 返回 {@code TEE_SUCCESS} 表示成功，其他值表示失败。 + * @since 20 + * @version 1.0 + */ +int32_t tee_ext_get_advsecmode(uint32_t *advsecmode); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_sharemem_ops.h b/zh-cn/native_sdk/TEEKit/tee/tee_sharemem_ops.h new file mode 100644 index 00000000..8d1417ef --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_sharemem_ops.h @@ -0,0 +1,130 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_sharemem_ops.h + * + * @brief 为开发者提供申请共享内存的 API。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_SHAREMEM_OPS_H +#define TEE_SHAREMEM_OPS_H + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 在 TEE 中分配共享内存。 + * + * @param uuid 指示 TA 的 UUID。 + * @param size 指示请求的共享内存大小。 + * + * @return 如果操作成功，返回指向新分配空间的指针。 + * 如果分配失败，返回 NULL 指针。 + * + * @since 20 + * @version 1.0 + */ +void *tee_alloc_sharemem_aux(const struct tee_uuid *uuid, uint32_t size); + +/** + * @brief 在 TEE 中分配连续共享内存。 + * + * @param uuid 指示 TA 的 UUID。 + * @param size 指示请求的共享内存大小。 + * + * @return 如果操作成功，返回指向新分配空间的指针。 + * 如果分配失败，返回 NULL 指针。 + * + * @since 20 + * @version 1.0 + */ +void *tee_alloc_coherent_sharemem_aux(const struct tee_uuid *uuid, uint32_t size); + +/** + * @brief 释放 TEE 中的共享内存。 + * + * @param addr 指示将被释放的共享内存地址。 + * @param size 指示共享内存的大小。 + * + * @return 如果操作成功，返回 0。 + * 如果操作失败，返回其他值。 + * + * @since 20 + * @version 1.0 + */ +uint32_t tee_free_sharemem(void *addr, uint32_t size); + +/** + * @brief 从源任务复制共享内存。 + * + * @param src_task 指示源任务的 pid。 + * @param src 指示源缓冲区的地址。 + * @param src_size 指示源缓冲区的大小。 + * @param dst 指示目标缓冲区的地址。 + * @param dst_size 指示目标缓冲区的大小。 + * + * @return 如果操作成功，返回 0。 + * 如果操作失败，返回 -1。 + * + * @since 20 + * @version 1.0 + */ +int32_t copy_from_sharemem(uint32_t src_task, uint64_t src, uint32_t src_size, uintptr_t dst, uint32_t dst_size); + +/** + * @brief 将共享内存复制到目标任务。 + * + * @param src 指示源缓冲区的地址。 + * @param src_size 指示源缓冲区的大小。 + * @param dst_task 指示目标任务的 pid。 + * @param dst 指示目标缓冲区的地址。 + * @param dst_size 指示目标缓冲区的大小。 + * + * @return 如果操作成功，返回 0。 + * 如果操作失败，返回 -1。 + * + * @since 20 + * @version 1.0 + */ +int32_t copy_to_sharemem(uintptr_t src, uint32_t src_size, uint32_t dst_task, uint64_t dst, uint32_t dst_size); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_time_api.h b/zh-cn/native_sdk/TEEKit/tee/tee_time_api.h new file mode 100644 index 00000000..6cd4dc18 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_time_api.h @@ -0,0 +1,130 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_time_api.h + * + * @brief 提供用于管理可信执行环境（TEE）时间的API。 + * + * 您可以使用这些API实现TEE中的时间相关功能。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef __TEE_TIME_API_H +#define __TEE_TIME_API_H + +#include "tee_defines.h" +#include "tee_rtc_time_api.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 获取当前 TEE 系统的 RTC 时间。 + * + * @param time [OUT] 当前 TEE 系统的 RTC 时间。 + * + * @since 20 + * @version 1.0 + */ +void get_sys_rtc_time(TEE_Time *time); + +/** + * @brief 获取当前的可信执行环境（TEE）系统时间。 + * + * @param time 指向获取到的当前系统时间的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_GetSystemTime(TEE_Time *time); + +/** + * @brief 等待指定的时间段，单位为毫秒。 + * + * @param timeout 指定的等待时间，单位为毫秒。 + * + * @return 如果操作成功，返回 TEE_SUCCESS。\n + 如果等待被取消，返回 TEE_ERROR_CANCEL。\n + 如果内存不足以完成操作，返回 TEE_ERROR_OUT_OF_MEMORY。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_Wait(uint32_t timeout); + +/** + * @brief 获取此可信应用程序（TA）的持久时间。 + * + * @param time 指向TA持久时间的指针。 + * + * @return 如果操作成功，返回 TEE_SUCCESS。\n + 如果持久时间未设置，返回 TEE_ERROR_TIME_NOT_SET。\n + 如果持久时间损坏且应用程序不再可信，返回 TEE_ERROR_TIME_NEEDS_RESET。\n + 如果TA持久时间中的秒数超出 uint32_t 的范围，返回 TEE_ERROR_OVERFLOW。\n + 如果内存不足以完成操作，返回 TEE_ERROR_OUT_OF_MEMORY。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_GetTAPersistentTime(TEE_Time *time); + +/** + * @brief 设置此TA的持久时间。 + * + * @param time 指向TA持久时间的指针。 + * + * @return 如果操作成功，返回 TEE_SUCCESS。\n + 如果内存不足以完成操作，返回 TEE_ERROR_OUT_OF_MEMORY。\n + 如果存储空间不足以完成操作，返回 TEE_ERROR_STORAGE_NO_SPACE。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SetTAPersistentTime(TEE_Time *time); + +/** + * @brief 获取当前丰富执行环境（REE）系统时间。 + * + * @param time 指向获取到的REE系统时间的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEE_GetREETime(TEE_Time *time); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_trusted_storage_api.h b/zh-cn/native_sdk/TEEKit/tee/tee_trusted_storage_api.h new file mode 100644 index 00000000..ebaee751 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_trusted_storage_api.h @@ -0,0 +1,416 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_trusted_storage_api.h + * + * @brief 提供可信存储 API。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef __TEE_TRUSTED_STORAGE_API_H +#define __TEE_TRUSTED_STORAGE_API_H + +#include "tee_defines.h" +#include "tee_object_api.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 定义与对象关联的数据流的起始位置。 + * 用于 TEE_SeekObjectData 函数。 + * + * @since 20 + */ +enum __TEE_Whence { + /** 将起始位置设置为数据流的开头。 */ + TEE_DATA_SEEK_SET = 0, + /** 将起始位置设置为当前数据流位置。 */ + TEE_DATA_SEEK_CUR, + /** 将起始位置设置为数据流的末尾。 */ + TEE_DATA_SEEK_END +}; + +/** + * @brief 定义对象枚举句柄。 + * + * @since 20 + */ +struct __TEE_ObjectEnumHandle; + +/** + * @brief 定义数据流位置的类型。//TODO + * + * @since 20 + */ +typedef uint32_t TEE_Whence; + +/** + * @brief 定义存储 ID，用于标识应用程序使用的存储空间。 + * + * @since 20 + */ +enum Object_Storage_Constants { + /** 为每个应用程序提供独立的私有存储空间。 */ + TEE_OBJECT_STORAGE_PRIVATE = 0x00000001, + /** 为应用程序提供独立的个性化存储空间。 */ + TEE_OBJECT_STORAGE_PERSO = 0x00000002, + /** 用于安全闪存的存储空间。 */ + TEE_OBJECT_SEC_FLASH = 0x80000000, + /** 用于 RPMB 存储的存储空间。 */ + TEE_OBJECT_STORAGE_RPMB = 0x80000001, + /** 用于凭据加密的存储空间。 */ + TEE_OBJECT_STORAGE_CE = 0x80000002, + /** 用于防回滚的存储空间。 */ + TEE_OBJECT_STORAGE_ANTIROLLBACK = 0x80000003, +}; + +/** + * @brief 定义系统资源约束，如数据流位置指示器的最大值。 + * + * @since 20 + */ +enum Miscellaneous_Constants { + /** 数据流位置指示器的最大长度。 */ + TEE_DATA_MAX_POSITION = 0xFFFFFFFF, + /** 对象 ID 的最大长度，最大可扩展至 128 字节。 */ + TEE_OBJECT_ID_MAX_LEN = 64, +}; + +/** + * @brief 定义数据流中可容纳的最大字节数。 + * + * @since 20 + */ +enum TEE_DATA_Size { + /** 数据流中可容纳的最大字节数。 */ + TEE_DATA_OBJECT_MAX_SIZE = 0xFFFFFFFF +}; + +/** + * @brief 定义 TEE_ObjectHandle 的 handleFlags。 + * 该标志用于决定与对象关联的数据流的访问权限。 + * + * @since 20 + */ +enum Data_Flag_Constants { + /** 数据流可读。 */ + TEE_DATA_FLAG_ACCESS_READ = 0x00000001, + /** 数据流可写或可截断。 */ + TEE_DATA_FLAG_ACCESS_WRITE = 0x00000002, + /** 可删除或重命名数据流。 */ + TEE_DATA_FLAG_ACCESS_WRITE_META = 0x00000004, + /** 可通过多个 TEE_ObjectHandle 并发读取。 */ + TEE_DATA_FLAG_SHARE_READ = 0x00000010, + /** 可通过多个 TEE_ObjectHandle 并发写入。 */ + TEE_DATA_FLAG_SHARE_WRITE = 0x00000020, + /** 保留字段。 */ + TEE_DATA_FLAG_CREATE = 0x00000200, + /** + * 保护已有同名文件。如果同名文件已存在则返回错误，否则创建新数据文件。 + */ + TEE_DATA_FLAG_EXCLUSIVE = 0x00000400, + /** + * 保护已有同名文件。如果同名文件已存在则返回错误，否则创建新数据文件。 + */ + TEE_DATA_FLAG_OVERWRITE = 0x00000400, + /** 第25位为1表示通过 GID 派生 TA 根密钥。 */ + TEE_DATA_FLAG_GID = 0x02000000, + /** 第26位为1表示通过 HUK2 派生 TA 根密钥。 */ + TEE_DATA_FLAG_HUK2 = 0x04000000, + /** + * 第27位为1表示一次性派生32字节的 TA 根密钥； + * 为0表示分段派生多个密钥后组合生成最终密钥。 + */ + TEE_DATA_FLAG_DERIVE_32BYTES_KEY_ONCE = 0x08000000, + /** 第28位为1使用 AES256，加密；为0使用 AES128。 */ + TEE_DATA_FLAG_AES256 = 0x10000000, + /** 第29位为1时优先打开旧版本数据。 */ + TEE_DATA_FLAG_OPEN_AESC = 0x20000000, + /** 第30位为1表示使用国密算法保护数据。 */ + TEE_DATA_FLAG_GM = 0x40000000, +}; + +/** + * @brief 创建持久对象。 + * + * 此函数会创建一个带有初始化的 TEE_Attribute 和数据流的持久对象。\n + * 可以使用返回的句柄访问对象的 TEE_Attribute 和数据流。 + * + * @param storageID 指定要使用的存储空间。该值由 Object_Storage_Constants 指定。 + * @param ojbectID 指向对象标识符（即要创建的对象的名称）的指针。 + * @param objectIDLen 指定对象标识符的长度（以字节为单位）。长度不能超过 128 字节。 + * @param flags 指定创建的对象的标志。该值可以是 + * 一个或多个 Data_Flag_Constants 或 Handle_Flag_Constants 的组合。 + * @param attributes 指向一个瞬态对象的 TEE_ObjectHandle，从中获取 TEE_Attribute。 + * 如果持久对象不包含属性，则该参数可以为 TEE_HANDLE_NULL。 + * @param initialData 指向用于初始化数据流的初始数据的指针。 + * @param initialDataLen 指定初始数据的长度（以字节为单位）。 + * @param object 指向在函数成功执行后返回的 TEE_ObjectHandle 的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_ITEM_NOT_FOUND 表示指定的存储空间不存在。\n + * 返回 TEE_ERROR_ACCESS_CONFLICT 表示发生访问冲突。\n + * 返回 TEE_ERROR_OUT_OF_MEMORY 表示内存不足，无法完成操作。\n + * 返回 TEE_ERROR_STORAGE_NO_SPACE 表示存储空间不足，无法创建对象。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_CreatePersistentObject(uint32_t storageID, const void *ojbectID, size_t objectIDLen, uint32_t flags, + TEE_ObjectHandle attributes, const void *initialData, size_t initialDataLen, + TEE_ObjectHandle *object); + +/** + * @brief 打开已存在的持久对象。 + * + * 返回的句柄可用于访问对象的 TEE_Attribute 和数据流。 + * + * @param storageID 指定要使用的存储空间。该值由 Object_Storage_Constants 指定。 + * @param ojbectID 指向对象标识符（即要打开的对象的名称）的指针。 + * @param objectIDLen 指定对象标识符的长度（以字节为单位）。长度不能超过 128 字节。 + * @param flags 指定打开对象的标志。该值可以是一个或多个 Data_Flag_Constants 或 + * Handle_Flag_Constants 的组合。 + * @param object 指向在函数成功执行后返回的 TEE_ObjectHandle 的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_ITEM_NOT_FOUND 表示指定的存储空间不存在或在该存储空间中找不到指定的对象标识符。\n + * 返回 TEE_ERROR_ACCESS_CONFLICT 表示发生访问冲突。\n + * 返回 TEE_ERROR_OUT_OF_MEMORY 表示内存不足，无法完成操作。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_OpenPersistentObject(uint32_t storageID, const void *ojbectID, size_t objectIDLen, uint32_t flags, + TEE_ObjectHandle *object); + +/** + * @brief 从与对象关联的数据流中读取数据到缓冲区。 + * + * 对象的 TEE_ObjectHandle 必须以 TEE_DATA_FLAG_ACCESS_READ 权限打开。 + * + * @param object 指向要读取的对象的 TEE_ObjectHandle。 + * @param buffer 指向用于存储读取数据的缓冲区的指针。 + * @param size 指定要读取的字节数。 + * @param count 指向存储实际读取字节数的变量的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_OUT_OF_MEMORY 表示内存不足，无法完成操作。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_ReadObjectData(TEE_ObjectHandle object, void *buffer, size_t size, uint32_t *count); + +/** + * @brief 将缓冲区中的字节写入与对象关联的数据流。 + * + * 对象的 TEE_ObjectHandle 必须以 TEE_DATA_FLAG_ACCESS_WRITE 权限打开。 + * + * @param object 指向要写入数据的对象的 TEE_ObjectHandle。 + * @param buffer 指向存储要写入数据的缓冲区的指针。 + * @param size 指定要写入的字节数，不能超过 4096 字节。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_OUT_OF_MEMORY 表示内存不足，无法完成操作。\n + * 返回 TEE_ERROR_STORAGE_NO_SPACE 表示存储空间不足，无法完成操作。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_WriteObjectData(TEE_ObjectHandle object, const void *buffer, size_t size); + +/** + * @brief 更改数据流的大小。 + * + * 如果指定的大小小于当前数据流大小，超出部分的字节将被删除。\n + * 如果指定的大小大于当前数据流大小，则在数据流末尾填充 0 来扩展数据流。\n + * 对象句柄必须以 TEE_DATA_FLAG_ACCESS_WRITE 权限打开。 + * + * @param object 指向要更改数据流大小的对象的 TEE_ObjectHandle。 + * @param size 指定数据流的新大小。不能超过 4096 字节。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_STORAGE_NO_SPACE 表示存储空间不足，无法完成操作。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_TruncateObjectData(TEE_ObjectHandle object, size_t size); + +/** + * @brief 设置 TEE_ObjectHandle 指向的数据流的位置。 + * + * 数据位置指示器由起始位置和偏移量共同决定。\n + * 参数 whence 用于确定起始位置，其值可参考 TEE_Whence 枚举值：\n + * TEE_DATA_SEEK_SET = 0：起始位置为数据流的开头。\n + * TEE_DATA_SEEK_CUR：起始位置为数据流的当前位置。\n + * TEE_DATA_SEEK_END：起始位置为数据流的末尾。\n + * 如果 offset 为正数，数据位置向前移动；\n + * 如果 offset 为负数，数据位置向后移动。 + * + * @param object 指向目标对象的 TEE_ObjectHandle。 + * @param offset 指定要移动数据位置的字节数，不能超过 4096 字节。 + * @param whence 指定数据流中计算新位置的起始位置。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_OVERFLOW 表示由于该操作导致的位置指示器超出 TEE_DATA_MAX_POSIT。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SeekObjectData(TEE_ObjectHandle object, int32_t offset, TEE_Whence whence); + +/** + * @brief 将已打开的 TEE_ObjectHandle 及其对应的安全属性文件同步到磁盘。 + * + * @param object 指向目标对象的 TEE_ObjectHandle。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_SyncPersistentObject(TEE_ObjectHandle object); + +/** + * @brief 更改对象标识符。 + * + * TEE_ObjectHandle 必须以 TEE_DATA_FLAG_ACCESS_WRITE_META 权限打开。 + * + * @param object 指向目标对象的句柄。 + * @param newObjectID 指向新的对象标识符的指针。 + * @param newObjectIDLen 指定新对象标识符的长度。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_RenamePersistentObject(TEE_ObjectHandle object, void *newObjectID, size_t newObjectIDLen); + +/** + * @brief 为未初始化的对象枚举器分配一个句柄。 + * + * @param obj_enumerator 指向新创建的对象枚举器句柄的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_OUT_OF_MEMORY 表示内存不足，无法完成操作。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_AllocatePersistentObjectEnumerator(TEE_ObjectEnumHandle *obj_enumerator); + +/** + * @brief 释放与对象枚举器句柄关联的所有资源。 + * + * 调用此函数后，对象句柄将不再有效，且与对象枚举器句柄关联的所有资源将被回收。\n + * TEE_FreePersistentObjectEnumerator 与 TEE_AllocatePersistentObjectEnumerator 成对使用。 + * + * @param obj_enumerator 要释放的 TEE_ObjectEnumHandle。 + * + * @since 20 + * @version 1.0 + */ +void TEE_FreePersistentObjectEnumerator(TEE_ObjectEnumHandle obj_enumerator); + +/** + * @brief 将对象枚举器句柄重置为其分配后的初始状态。 + * + * @param obj_enumerator 要重置的对象枚举器的 TEE_ObjectEnumHandle。 + * + * @since 20 + * @version 1.0 + */ +void TEE_ResetPersistentObjectEnumerator(TEE_ObjectEnumHandle obj_enumerator); + +/** + * @brief 开始枚举指定可信存储中的所有对象。 + * + * 可使用 TEE_GetNextPersistentObject 获取对象信息。 + * + * @param obj_enumerator 指向对象枚举器的 TEE_ObjectEnumHandle。 + * @param storage_id 指定要枚举对象的存储空间。该值由 Object_Storage_Constants 指定。\n + * 当前仅支持 TEE_STORAGE_PRIVATE。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ITEM_NOT_FOUND 表示 storage_id 不是 TEE_STORAGE_PRIVATE + * 或指定的存储空间中没有对象。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_StartPersistentObjectEnumerator(TEE_ObjectEnumHandle obj_enumerator, uint32_t storage_id); + +/** + * @brief 获取对象枚举器中的下一个对象。 + * + * 获取的信息包括 TEE_ObjectInfo、objectID 和 objectIDLen。 + * + * @param obj_enumerator 指向对象枚举器的 TEE_ObjectEnumHandle。 + * @param object_info 指向获取到的 TEE_ObjectInfo 的指针。 + * @param object_id 指向用于存储获取到的 objectID 的缓冲区的指针。 + * @param object_id_len 指向 objectIDLen 的指针。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ITEM_NOT_FOUND 表示对象枚举器中没有元素 + * 或枚举器尚未初始化。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_GetNextPersistentObject(TEE_ObjectEnumHandle obj_enumerator, + TEE_ObjectInfo *object_info, void *object_id, size_t *object_id_len); + +/** + * @brief 关闭 TEE_ObjectHandle 并删除对象。 + * + * 该对象必须是持久对象，且对象句柄必须以 TEE_DATA_FLAG_ACCESS_WRITE_META 权限打开。 + * + * @param object 指向要关闭的对象句柄。 + * + * @return 返回 TEE_SUCCESS 表示操作成功。\n + * 返回 TEE_ERROR_STORAGE_NOT_AVAILABLE 表示对象存储在当前无法访问的存储区域。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_CloseAndDeletePersistentObject1(TEE_ObjectHandle object); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee/tee_tui_gp_api.h b/zh-cn/native_sdk/TEEKit/tee/tee_tui_gp_api.h new file mode 100644 index 00000000..1100b6ef --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee/tee_tui_gp_api.h @@ -0,0 +1,479 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_tui_gp_api.h + * + * @brief 提供TUI（可信用户界面）相关操作的 API。 + * + * @library NA + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TASK_TUI_GP_API_H +#define TASK_TUI_GP_API_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 定义 TEE TUI 按钮类型的常量。 + * + * @since 20 + */ +#define TEE_TUI_NUMBER_BUTTON_TYPES 0x00000006 + +/** + * @brief 定义 TEE 存储的私有区域标识符。 + * + * @since 20 + */ +#define TEE_STORAGE_PRIVATE 0x00000001 + +/** + * @brief 定义默认的最大字段数。 + * + * @since 20 + */ +#define DEFAULT_MAX_ENTRY_FIELDS 3 + +/** + * @brief 定义退出操作的标识符。 + * + * @since 20 + */ +#define TUI_EXIT 8 + +/** + * @brief 枚举在输入字段内显示字符时支持的模式。 + * + * @since 20 + */ +typedef enum { + /** 永不显示，显示为 '*'。 */ + TEE_TUI_HIDDEN_MODE = 0, + /** 始终可见。 */ + TEE_TUI_CLEAR_MODE, + /** 显示后隐藏。 */ + TEE_TUI_TEMPORARY_CLEAR_MODE +} TEE_TUIEntryFieldMode; + +/** + * @brief 枚举 TUI 输入字段支持的输入类型。 + * + * @since 20 + */ +typedef enum { + /** 字段仅接受数字输入。 */ + TEE_TUI_NUMERICAL = 0, + /** 字段接受字符和数字输入。 */ + TEE_TUI_ALPHANUMERICAL, +} TEE_TUIEntryFieldType; + +/** + * @brief 枚举 TUI 屏幕的方向。 + * @attention 当前 {@code TEE_TUI_LANDSCAPE} 不支持。 + * + * @since 20 + */ +typedef enum { + /** 以纵向显示，即竖屏。 */ + TEE_TUI_PORTRAIT = 0, + /** 以横向显示，即横屏。 */ + TEE_TUI_LANDSCAPE, +} TEE_TUIScreenOrientation; + +/** + * @brief 枚举按钮的类型。 + * + * @since 20 + */ +typedef enum { + /** 用于删除前一个输入的数字。 */ + TEE_TUI_CORRECTION = 0, + /** 退出当前界面。 */ + TEE_TUI_OK, + /** 取消操作并退出界面。 */ + TEE_TUI_CANCEL, + /** 用于触发 PIN 验证并退出界面。 */ + TEE_TUI_VALIDATE, + /** 退出当前界面并请求 TA 显示上一个界面。 */ + TEE_TUI_PREVIOUS, + /** 退出当前界面并请求 TA 显示下一个界面。 */ + TEE_TUI_NEXT, +} TEE_TUIButtonType; + +/** + * @brief 枚举使用的图片来源。 + * + * @since 20 + */ +typedef enum { + /** 输入中未提供图片。 */ + TEE_TUI_NO_SOURCE = 0, + /** 图片通过内存指针提供。 */ + TEE_TUI_REF_SOURCE, + /** 图片通过受信存储中的对象提供。 */ + TEE_TUI_OBJECT_SOURCE, + /** 图片通过文件提供。 */ + TEE_TUI_FILE_SOURCE = 0x8001 +} TEE_TUIImageSource; + +/** + * @brief 表示 PNG 格式的图片。 + * + * @since 20 + */ +typedef struct { + /** 图片来源。 */ + TEE_TUIImageSource source; + /** 图片通过内存引用提供。 */ + struct { + /** 图片的内存指针。 */ + void *image; + /** 图片的长度。 */ + size_t imageLength; + } ref; + /** 图片通过可信存储中的对象提供。 */ + struct { + /** 存储区标识符。 */ + uint32_t storageID; + /** 对象标识符。 */ + void *objectID; + /** 对象标识符的长度。 */ + size_t objectIDLen; + } object; + /** 表示图片宽度的像素数。 */ + uint32_t width; + /** 表示图片高度的像素数。 */ + uint32_t height; +} TEE_TUIImage; + +/** + * @brief 枚举 GP 颜色索引。 + * + * @since 20 + */ +enum gp_color_idx { + /** 红色索引。 */ + RED_IDX = 0, + /** 绿色索引。 */ + GREEN_IDX = 1, + /** 蓝色索引。 */ + BLUE_IDX = 2, + /** RGB 颜色索引。 */ + RGB_COLOR_IDX = 3, +}; + +/** + * @brief 表示用于 TA 品牌标识/信息的标签，通常显示在屏幕顶部。 + * + * @since 20 + */ +typedef struct { + /** 显示在标签区域的字符串，可以为 NULL。 */ + char *text; + /** 文本信息左上角的 X 坐标。 */ + uint32_t textXOffset; + /** 文本信息左上角的 Y 坐标。 */ + uint32_t textYOffset; + /** 显示文本信息所使用的 RGB 颜色。 */ + uint8_t textColor[RGB_COLOR_IDX]; + /** 显示在标签区域的图像内容。 */ + TEE_TUIImage image; + /** 图像左上角的 X 坐标。 */ + uint32_t imageXOffset; + /** 图像左上角的 Y 坐标。 */ + uint32_t imageYOffset; +} TEE_TUIScreenLabel; + +/** + * @brief 表示按钮上显示的内容。 + * + * @since 20 + */ +typedef struct { + /** 与按钮关联的字符串，可以为 NULL。 */ + char *text; + /** 与按钮关联的图片。 */ + TEE_TUIImage image; +} TEE_TUIButton; + +/** + * @brief 表示 TUI 屏幕的配置。 + * + * @since 20 + */ +typedef struct { + /** 请求的屏幕方向。 */ + TEE_TUIScreenOrientation screenOrientation; + /** 屏幕的标签。 */ + TEE_TUIScreenLabel label; + /** 自定义的按钮，与默认按钮相比。 */ + TEE_TUIButton *buttons[TEE_TUI_NUMBER_BUTTON_TYPES]; + /** 指定要显示哪些按钮。 */ + bool requestedButtons[TEE_TUI_NUMBER_BUTTON_TYPES]; +} TEE_TUIScreenConfiguration; + +/** + * @brief 表示 TUI 屏幕按钮的相关信息。 + * @attention {@code buttonTextCustom} 和 {@code buttonImageCustom} 不能同时设置为 true。 + * + * @since 20 + */ +typedef struct { + /** 按钮文本的默认标签值。如果值为 NULL，则表示该参数不可用。 */ + const char *buttonText; + /** 按钮的像素宽度。 + * 如果按钮上的文本或图片不可自定义，则值为 0。 + */ + uint32_t buttonWidth; + /** 按钮的像素高度。 + * 如果按钮上的文本或图片不可自定义，则值为 0。 + */ + uint32_t buttonHeight; + /** 如果按钮上的文本不可自定义，则值为 true。 */ + bool buttonTextCustom; + /** 如果按钮上的图片不可自定义，则值为 true。 */ + bool buttonImageCustom; +} TEE_TUIScreenButtonInfo; + +/** + * @brief 表示 TUI 上显示的信息。 + * + * @since 20 + */ +typedef struct { + /** 可用的灰度位深。 */ + uint32_t grayscaleBitsDepth; + /** 可用的红色深度级别。 */ + uint32_t redBitsDepth; + /** 可用的绿色深度级别。 */ + uint32_t greenBitsDepth; + /** 可用的蓝色深度级别。 */ + uint32_t blueBitsDepth; + /** 表示水平方向上每英寸的像素数。 */ + uint32_t widthInch; + /** 表示垂直方向上每英寸的像素数。 */ + uint32_t heightInch; + /** 表示 TUI 上可以显示的最大条目数。 */ + uint32_t maxEntryFields; + /** 表示输入区域标签的像素宽度。 */ + uint32_t entryFieldLabelWidth; + /** 表示输入区域标签的像素高度。 */ + uint32_t entryFieldLabelHeight; + /** 表示输入区域最大可输入字符数。 */ + uint32_t maxEntryFieldLength; + /** 默认标签画布的 RGB 值。 */ + uint8_t labelColor[RGB_COLOR_IDX]; + /** 表示标签画布的像素宽度。 */ + uint32_t labelWidth; + /** 表示标签画布的像素高度。 */ + uint32_t labelHeight; + /** 表示界面上按钮的信息。 */ + TEE_TUIScreenButtonInfo buttonInfo[TEE_TUI_NUMBER_BUTTON_TYPES]; +} TEE_TUIScreenInfo; + +/** + * @brief 表示需要用户输入的输入字段中的信息。 + * + * @since 20 + */ +typedef struct { + /** 输入字段的标签。 */ + char *label; + /** 用于显示字符的模式。 */ + TEE_TUIEntryFieldMode mode; + /** 输入字段中可以输入的字符类型。 */ + TEE_TUIEntryFieldType type; + /** 最小输入字符数。 */ + uint32_t minExpectedLength; + /** 最大输入字符数。 */ + uint32_t maxExpectedLength; + /** 包含用户输入的内容。 */ + char *buffer; + /** 缓冲区的长度。 */ + size_t bufferLength; +} TEE_TUIEntryField; + +/** + * @brief 初始化 TUI 资源。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数不正确。\n + * 返回 {@code TEE_ERROR_NOT_SUPPORTED} 表示设备不支持 TUI。\n + * 返回 {@code TEE_ERROR_BUSY} 表示 TUI 资源无法分配。\n + * 返回 {@code TEE_ERROR_OUT_OF_MEMORY} 表示系统资源不足。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_TUIInitSession(void); + + +/** + * @brief 释放之前获得的 TUI 资源。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_STATE} 表示当前 TA 不在通过成功调用 {@code TEE_TUIInitSession} 初始启动的 TUI 会话中。\n + * 返回 {@code TEE_ERROR_BUSY} 表示 TUI 资源当前正在使用中。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_TUICloseSession(void); + +/** + * @brief 允许 TA 检查给定的文本是否可以由当前实现渲染，并获取渲染该文本所需的大小和宽度信息。 + * + * @param text 指定要检查的字符串。 + * @param width 指定渲染文本所需的宽度（以像素为单位）。 + * @param height 指定渲染文本所需的高度（以像素为单位）。 + * @param last_index 指定已检查的最后一个字符索引。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_NOT_SUPPORTED} 表示文本字符串中的至少一个字符无法渲染。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_TUICheckTextFormat(const char *text, uint32_t *width, uint32_t *height, uint32_t *last_index); + +/** + * @brief 根据屏幕方向和所需输入字段的数量，检索有关屏幕的信息。 + * + * @param screenOrientation 定义请求屏幕信息的方向。 + * @param nbEntryFields 指定请求的输入字段的数量。 + * @param screenInfo 指定给定方向下请求的屏幕信息。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_NOT_SUPPORTED} 表示不支持所请求的输入字段数量。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_TUIGetScreenInfo(TEE_TUIScreenOrientation screenOrientation, + uint32_t nbEntryFields, + TEE_TUIScreenInfo *screenInfo); + +/** + * @brief 显示 TUI 屏幕。 + * + * @param screenConfiguration 指定显示界面上的标签和可选按钮的配置。 + * @param closeTUISession 如果值为 true，则在退出函数时自动关闭 TUI 会话。 + * @param entryFields 指定输入字段的信息。 + * @param entryFieldCount 指定输入字段的数量。 + * @param selectedButton 指示用户选择的按钮，用于退出 TUI 屏幕。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_OUT_OF_MEMORY} 表示系统资源不足。\n + * 返回 {@code TEE_ERROR_ITEM_NOT_FOUND} 表示 TA 提供的至少一张图片引用了一个不存在的存储区的 storageID， + * 或者无法在存储区中找到相应的对象标识符。\n + * 返回 {@code TEE_ERROR_ACCESS_CONFLICT} 表示 TA 提供的至少一张图片引用了受信存储中的数据对象， + * 且在打开该对象时检测到访问权限冲突。\n + * 返回 {@code TEE_ERROR_BAD_FORMAT} 表示至少一张输入图片不符合 PNG 格式。\n + * 返回 {@code TEE_ERROR_BAD_STATE} 表示当前 TA 不在通过成功调用 {@code TEE_TUIInitSession} 初始化启动的 TUI 会话中。\n + * 返回 {@code TEE_ERROR_BUSY} 表示 TUI 资源当前正在使用，即 TUI 屏幕正在显示。\n + * 返回 {@code TEE_ERROR_CANCEL} 表示在当前显示 TUI 屏幕时操作已被取消。\n + * 返回 {@code TEE_ERROR_EXTERNAL_CANCEL} 表示在当前显示 TUI 屏幕时，由于 REE 中发生的外部事件导致操作被取消。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_TUIDisplayScreen(TEE_TUIScreenConfiguration *screenConfiguration, + bool closeTUISession, + TEE_TUIEntryField *entryFields, + uint32_t entryFieldCount, + TEE_TUIButtonType *selectedButton); + +/** + * @brief 指纹识别端口。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_NOT_SUPPORTED} 表示设备不支持 TUI。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_TUINotify_fp(void); + +/** + * @brief 设置中文字符编码。系统默认支持 UTF-8。 + * + * @param type 指定编码类型。值 1 表示 GBK。其他值不支持。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_NOT_SUPPORTED} 表示设备不支持此功能。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数不正确。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_TUISetInfo(int32_t type); + +/** + * @brief 向 TUI 发送消息。 + * + * @param type 指定发送给 TUI 的消息。只支持 {@code TUI_EXIT}。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_BAD_PARAMETERS} 表示输入参数不正确。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_TUISendEvent(int32_t type); + +/** + * @brief 设置 TUI 背景图片。 + * + * @param label 配置背景图片信息的标签变量。 + * 图片必须是 PNG 格式的数组形式。 + * @param len 指定标签的大小。 + * + * @return 返回 {@code TEE_SUCCESS} 表示操作成功。\n + * 返回 {@code TEE_ERROR_GENERIC} 表示输入参数不正确。\n + * 返回 {@code TEE_ERROR_ACCESS_DENIED} 表示权限验证失败。 + * + * @since 20 + * @version 1.0 + */ +TEE_Result TEE_TUISetLabel(TEE_TUIScreenLabel *label, uint32_t len); +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee_client/tee_client_api.h b/zh-cn/native_sdk/TEEKit/tee_client/tee_client_api.h new file mode 100644 index 00000000..1c58efa0 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee_client/tee_client_api.h @@ -0,0 +1,246 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_client_api.h + * + * @brief 定义了供可信应用（TA）访问的客户端应用（CA）API。 + * + *

示例： + *

1. 初始化 TEE：调用 TEEC_InitializeContext 来初始化 TEE。 + *

2. 打开会话：调用 TEEC_OpenSession 并传入可信应用 (TA) 的通用唯一标识符 (UUID)。 + *

3. 发送命令：调用 TEEC_InvokeCommand 向 TA 发送命令。 + *

4. 关闭会话：调用 TEEC_CloseSession 关闭会话。 + *

5. 关闭 TEE：调用 TEEC_FinalizeContext 关闭 TEE。 + * + * @library libteec.so + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_CLIENT_API_H +#define TEE_CLIENT_API_H + +#include +#include "tee_client_type.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 定义了在 REE（普通执行环境）与 TEE（可信执行环境）之间传输的参数值。 + * + * @since 20 + * @version 1.0 + */ +#define TEEC_PARAM_TYPES(param0Type, param1Type, param2Type, param3Type) \ + ((param3Type) << 12 | (param2Type) << 8 | (param1Type) << 4 | (param0Type)) + +/** + * @brief 定义由 paramTypes 和 index 指定的参数值。 + * + * @since 20 + * @version 1.0 + */ +#define TEEC_PARAM_TYPE_GET(paramTypes, index) \ + (((paramTypes) >> (4*(index))) & 0x0F) + +/** + * @brief 初始化 TEE（可信执行环境）。 + * + * 必须在打开会话或发送命令之前初始化 TEE。 + * 初始化完成后，客户端应用（CA）与 TEE 之间将建立连接。 + * + * @param name [IN] 指向 TEE 路径的指针。 + * @param context [IN/OUT] 指向上下文的指针，该指针是 TEE 的句柄。 + * + * @return 返回 {@code TEEC_SUCCESS} 表示 TEE 成功初始化。\n + * 返回 {@code TEEC_ERROR_BAD_PARAMETERS} 表示 name 不正确或 context 为 null。\n + * 返回 {@code TEEC_ERROR_GENERIC} 表示系统资源不足。 + * + * @since 20 + * @version 1.0 + */ +TEEC_Result TEEC_InitializeContext(const char *name, TEEC_Context *context); + +/** + * @brief 关闭 TEE。 + * + * TEE 关闭后，客户端应用（CA）将与 TEE 断开连接。 + * + * @param context [IN/OUT] 指向已成功初始化的 TEE 的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEEC_FinalizeContext(TEEC_Context *context); + +/** + * @brief 打开一个会话。 + * + * 此函数用于在指定 TEE 上下文中，为客户端应用（CA）与指定 UUID 的可信应用（TA）建立连接。 + * 传输的数据包含在 operation 中。 + * 如果会话成功打开，则返回的 session 提供连接的描述。 + * 如果会话打开失败，则返回 returnOrigin 表示失败的原因。 + * + * @param context [IN/OUT] 指向已成功初始化的 TEE 的指针。 + * @param session [OUT] 指向会话的指针。该值不能为空。 + * @param destination [IN] 指向目标 TA 的 UUID 的指针。每个 TA 都有唯一的 UUID。 + * @param connectionMethod [IN] 指示连接方法。详情请参见 {@link TEEC_LoginMethod}。 + * @param connectionData [IN] 指向连接数据的指针，该值根据连接模式而变化。 + * 如果连接模式为 {@code TEEC_LOGIN_PUBLIC}、{@code TEEC_LOGIN_USER}、 + * {@code TEEC_LOGIN_USER_APPLICATION} 或 {@code TEEC_LOGIN_GROUP_APPLICATION}，则连接数据必须为 null。 + * 如果连接模式为 {@code TEEC_LOGIN_GROUP} 或 {@code TEEC_LOGIN_GROUP_APPLICATION}， + * 则连接数据必须指向一个 uint32_t 类型的数据，表示 CA 需连接的目标用户组。 + * @param operation [IN/OUT] 指向 CA 与 TA 之间传输数据的指针。 + * @param returnOrigin [IN/OUT] 指向错误来源的指针。 + * 详情请参见 {@code TEEC_ReturnCodeOrigin}。 + * + * @return 返回 {@code TEEC_SUCCESS} 表示会话成功打开。\n + * 返回 {@code TEEC_ERROR_BAD_PARAMETERS} 表示 context、session 或 destination 为空。\n + * 返回 {@code TEEC_ERROR_ACCESS_DENIED} 表示访问请求被拒绝。\n + * 返回 {@code TEEC_ERROR_OUT_OF_MEMORY} 表示系统资源不足。\n + * 返回 {@code TEEC_ERROR_TRUSTED_APP_LOAD_ERROR} 表示 TA 加载失败。\n + * 有关其他返回值的详细信息，请参见 {@code TEEC_ReturnCode}。 + * + * @since 20 + * @version 1.0 + */ +TEEC_Result TEEC_OpenSession(TEEC_Context *context, TEEC_Session *session, const TEEC_UUID *destination, + uint32_t connectionMethod, const void *connectionData, TEEC_Operation *operation, uint32_t *returnOrigin); + +/** + * @brief 关闭会话。 + * + * 会话关闭后，客户端应用（CA）将与可信应用（TA）断开连接。 + * + * @param session [IN/OUT] 指向要关闭的会话的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEEC_CloseSession(TEEC_Session *session); + +/** + * @brief 向 TA 发送命令。 + * + * 客户端应用（CA）通过指定的会话向 TA 发送命令 ID。 + * + * @param session [IN/OUT] 指向已打开的会话的指针。 + * @param commandID [IN] 指定 TA 支持的命令 ID，由 TA 定义。 + * @param operation [IN/OUT] 指向从 CA 向 TA 发送的数据的指针。 + * @param returnOrigin [IN/OUT] 指向错误来源的指针。 + * 详情请参见 {@code TEEC_ReturnCodeOrigin}。 + * + * @return 返回 {@code TEEC_SUCCESS} 表示命令发送成功。\n + * 返回 {@code TEEC_ERROR_BAD_PARAMETERS} 表示 session 为空或 operation 格式错误。\n + * 返回 {@code TEEC_ERROR_ACCESS_DENIED} 表示访问请求被拒绝。\n + * 返回 {@code TEEC_ERROR_OUT_OF_MEMORY} 表示系统资源不足。\n + * 有关其他返回值的详细信息，请参见 {@code TEEC_ReturnCode}。 + * + * @since 20 + * @version 1.0 + */ +TEEC_Result TEEC_InvokeCommand(TEEC_Session *session, uint32_t commandID, + TEEC_Operation *operation, uint32_t *returnOrigin); + +/** + * @brief 在指定 TEE 上下文中注册共享内存。 + * + * 注册的共享内存可以实现零拷贝。 + * 然而，零拷贝功能还需要操作系统的支持。 + * 目前，无法以此方式实现零拷贝。 + * + * @param context [IN/OUT] 指向已成功初始化的 TEE 的指针。 + * @param sharedMem [IN/OUT] 指向共享内存的指针。 + * 该指针指向的共享内存不能为空，且其大小不能为 0。 + * + * @return 返回 {@code TEEC_SUCCESS} 表示操作成功。\n + * 返回 {@code TEEC_ERROR_BAD_PARAMETERS} 表示 context、sharedMem 为空或指向的内存为空。 + * + * @since 20 + * @version 1.0 + */ +TEEC_Result TEEC_RegisterSharedMemory(TEEC_Context *context, TEEC_SharedMemory *sharedMem); + +/** + * @brief 在指定的 TEE 上下文中请求共享内存。 + * + * 共享内存可用于在普通执行环境（REE）与可信执行环境（TEE）之间的数据传输中实现零拷贝。 + * 然而，零拷贝功能还需要操作系统的支持。 + * 目前，无法以此方式实现零拷贝。 + * + * @attention 如果输入参数 sharedMem 的 size 字段设置为 0，虽然函数会返回 TEEC_SUCCESS， + * 但该共享内存将无法使用，因为该内存既没有地址也没有大小。 + * + * @param context [IN/OUT] 指向已成功初始化的 TEE 的指针。 + * @param sharedMem [IN/OUT] 指向共享内存的指针。共享内存的大小不能为 0。 + * + * @return 返回 {@code TEEC_SUCCESS} 表示操作成功。\n + * 返回 {@code TEEC_ERROR_BAD_PARAMETERS} 表示 context 或 sharedMem 为空。\n + * 返回 {@code TEEC_ERROR_OUT_OF_MEMORY} 表示系统资源不足。 + * + * @since 20 + * @version 1.0 + */ +TEEC_Result TEEC_AllocateSharedMemory(TEEC_Context *context, TEEC_SharedMemory *sharedMem); + +/** + * @brief 释放已注册或已获取的共享内存。 + * + * @attention 如果共享内存是通过 {@code TEEC_AllocateSharedMemory} 获取的， + * 则释放后该内存会被系统回收；如果共享内存是通过 {@code TEEC_RegisterSharedMemory} 获取的， + * 则释放后本地内存不会被回收。 + * + * @param sharedMem [IN/OUT] 指向要释放的共享内存的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEEC_ReleaseSharedMemory(TEEC_SharedMemory *sharedMem); + +/** + * @brief 取消一个操作。 + * + * @attention 此操作仅用于发送取消消息。是否执行取消操作由 TEE 或 TA 决定。 + * 当前，取消操作不生效。 + * + * @param operation [IN/OUT] 指向从 CA 到 TA 发送数据的指针。 + * + * @since 20 + * @version 1.0 + */ +void TEEC_RequestCancellation(TEEC_Operation *operation); + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee_client/tee_client_constants.h b/zh-cn/native_sdk/TEEKit/tee_client/tee_client_constants.h new file mode 100644 index 00000000..eaebbb31 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee_client/tee_client_constants.h @@ -0,0 +1,230 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_client_constants.h + * + * @brief 定义了公共数据和常量。 + * + * @library libteec.so + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_CLIENT_CONSTANTS_H +#define TEE_CLIENT_CONSTANTS_H + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 定义 TEEC_Operation 中的 TEEC_Parameter 数量。 + * + * @since 20 + * @version 1.0 + */ +#define TEEC_PARAM_NUM 4 + +/** + * @brief 定义返回错误码。 + * + * @since 20 + * @version 1.0 + */ +enum TEEC_ReturnCode { + /** 操作成功。 */ + TEEC_SUCCESS = 0x0, + /** 无效命令。该命令不受 TA 支持。 */ + TEEC_ERROR_INVALID_CMD, + /** TA 不存在。 */ + TEEC_ERROR_SERVICE_NOT_EXIST, + /** CA 与 TA 之间的会话不存在。 */ + TEEC_ERROR_SESSION_NOT_EXIST, + /** 连接到 TA 的数量已达到上限。 */ + TEEC_ERROR_SESSION_MAXIMUM, + /** 要注册的 TA 已存在。 */ + TEEC_ERROR_REGISTER_EXIST_SERVICE, + /** 安全 OS 框架错误。 */ + TEEC_ERROR_TAGET_DEAD_FATAL, + /** 读取文件失败。 */ + TEEC_ERROR_READ_DATA, + /** 写入文件失败。 */ + TEEC_ERROR_WRITE_DATA, + /** 截断文件失败。 */ + TEEC_ERROR_TRUNCATE_OBJECT, + /** 数据查找失败。 */ + TEEC_ERROR_SEEK_DATA, + /** 文件同步错误。 */ + TEEC_ERROR_FSYNC_DATA, + /** 文件重命名失败。 */ + TEEC_ERROR_RENAME_OBJECT, + /** 打开会话时加载 TA 失败。 */ + TEEC_ERROR_TRUSTED_APP_LOAD_ERROR, + /** 初始化 TA 失败。 */ + TEEC_ERROR_GENERIC = 0xFFFF0000, + /** 权限验证失败。此错误码在 TEE 或会话打开之前或在发送命令之前发生权限验证失败时返回。 */ + TEEC_ERROR_ACCESS_DENIED = 0xFFFF0001, + /** 操作被取消。当使用带有取消标志的参数操作时返回此错误码。 */ + TEEC_ERROR_CANCEL = 0xFFFF0002, + /** 并发访问引发权限冲突。可信存储服务中的文件的并发访问可能会导致此错误。 */ + TEEC_ERROR_ACCESS_CONFLICT = 0xFFFF0003, + /** 在请求的操作中传入的数据过多，导致 TA 无法解析。 */ + TEEC_ERROR_EXCESS_DATA = 0xFFFF0004, + /** 数据格式不正确。TA 无法解析 CA 发送的参数。 */ + TEEC_ERROR_BAD_FORMAT = 0xFFFF0005, + /** 无效参数。输入参数为空或无效。 */ + TEEC_ERROR_BAD_PARAMETERS = 0xFFFF0006, + /** 当前状态下的操作无效。如果请求了可信存储服务操作时，可信存储服务未初始化，则返回此错误码。 */ + TEEC_ERROR_BAD_STATE = 0xFFFF0007, + /** 未找到请求的数据。 */ + TEEC_ERROR_ITEM_NOT_FOUND = 0xFFFF0008, + /** 请求的操作尚未实现。当调用 TEEC_RequestCancellation 时返回此错误码。 */ + TEEC_ERROR_NOT_IMPLEMENTED = 0xFFFF0009, + /** 请求的操作有效，但在此实现中不受支持。当请求安全加密和解密服务的某些算法（如 DSA）时返回此错误码。 */ + TEEC_ERROR_NOT_SUPPORTED = 0xFFFF000A, + /** 请求的操作所需的数据未找到。 */ + TEEC_ERROR_NO_DATA = 0xFFFF000B, + /** 系统资源不足。 */ + TEEC_ERROR_OUT_OF_MEMORY = 0xFFFF000C, + /** 系统繁忙。某些资源已被系统独占使用。 */ + TEEC_ERROR_BUSY = 0xFFFF000D, + /** REE 中的应用程序与 TA 之间的通信失败。 */ + TEEC_ERROR_COMMUNICATION = 0xFFFF000E, + /** 在 TEE 中检测到安全故障。 */ + TEEC_ERROR_SECURITY = 0xFFFF000F, + /** 提供的缓冲区对于生成的输出数据来说过短。 + 此错误可能在使用 {@code TEEC_MEMREF_TEMP_OUTPUT} 时发生。 */ + TEEC_ERROR_SHORT_BUFFER = 0xFFFF0010, + /** MAC 值校验错误。 */ + TEEC_ERROR_MAC_INVALID = 0xFFFF3071, + /** TA 崩溃。 */ + TEEC_ERROR_TARGET_DEAD = 0xFFFF3024, + /** 常见错误。 */ + TEEC_FAIL = 0xFFFF5002 +}; + +/** + * @brief 定义返回错误码来源。 + * + * @since 20 + * @version 1.0 + */ +enum TEEC_ReturnCodeOrigin { + /** 错误码表示来自客户端 API 的错误。 */ + TEEC_ORIGIN_API = 0x1, + /** 错误码表示来自 REE（普通执行环境）与 TEE（可信执行环境）之间通信的错误。 */ + TEEC_ORIGIN_COMMS = 0x2, + /** 错误码表示来自 TEE 代码内部的错误。 */ + TEEC_ORIGIN_TEE = 0x3, + /** 错误码表示来自 TA（可信应用）代码内部的错误。 */ + TEEC_ORIGIN_TRUSTED_APP = 0x4, +}; + +/** + * @brief 定义共享内存标识符。 + * + * @since 20 + * @version 1.0 + */ +enum TEEC_SharedMemCtl { + /** 共享内存可用于从 CA（客户端应用）向 TA（可信应用）传输数据。 */ + TEEC_MEM_INPUT = 0x1, + /** 共享内存可用于从 TA（可信应用）向 CA（客户端应用）传输数据。 */ + TEEC_MEM_OUTPUT = 0x2, + /** 共享内存可用于在 CA（客户端应用）与 TA（可信应用）之间的双向数据传输。 */ + TEEC_MEM_INOUT = 0x3, +}; + +/** + * @brief 定义参数类型。 + * + * @since 20 + * @version 1.0 + */ +enum TEEC_ParamType { + /** 该参数未使用。 */ + TEEC_NONE = 0x0, + /** 该参数为标记为输入的 {@code TEEC_Value}。数据从 CA（客户端应用）流向 TA（可信应用）。 */ + TEEC_VALUE_INPUT = 0x01, + /** 该参数为标记为输出的 {@code TEEC_Value}。数据从 TA（可信应用）流向 CA（客户端应用）。 */ + TEEC_VALUE_OUTPUT = 0x02, + /** 该参数为标记为输入和输出的 {@code TEEC_Value}。 */ + TEEC_VALUE_INOUT = 0x03, + /** 该参数为标记为输入的 {@code TEEC_TempMemoryReference}。数据从 CA（客户端应用）流向 TA（可信应用）。 */ + TEEC_MEMREF_TEMP_INPUT = 0x05, + /** 该参数为标记为输出的 {@code TEEC_TempMemoryReference}。数据从 TA（可信应用）流向 CA（客户端应用）。 */ + TEEC_MEMREF_TEMP_OUTPUT = 0x06, + /** 该参数为标记为输入和输出的 {@code TEEC_TempMemoryReference}。 + 数据在 TA（可信应用）和 CA（客户端应用）之间传输。 */ + TEEC_MEMREF_TEMP_INOUT = 0x07, + /** 该参数为标记为输入的 {@code TEEC_IonReference}。数据从 CA（客户端应用）流向 TA（可信应用）。 */ + TEEC_ION_INPUT = 0x08, + /** 该参数为标记为输入的 {@code TEEC_IonSglistReference}。数据从 CA（客户端应用）流向 TA（可信应用）。 */ + TEEC_ION_SGLIST_INPUT = 0x09, + /** 该参数为 {@code TEEC_RegisteredMemoryReference}，用于指向完整的内存块。 + 数据流向与 {@code TEEC_SharedMemCtl} 相同。 */ + TEEC_MEMREF_WHOLE = 0xc, + /** 该参数为标记为输入的 {@code TEEC_RegisteredMemoryReference}。数据从 CA（客户端应用）流向 TA（可信应用）。 */ + TEEC_MEMREF_PARTIAL_INPUT = 0xd, + /** 该参数为标记为输出的 {@code TEEC_RegisteredMemoryReference}。数据从 TA（可信应用）流向 CA（客户端应用）。 */ + TEEC_MEMREF_PARTIAL_OUTPUT = 0xe, + /** 该参数为标记为输入和输出的 {@code TEEC_RegisteredMemoryReference}。 + 数据在 TA（可信应用）和 CA（客户端应用）之间传输。 */ + TEEC_MEMREF_PARTIAL_INOUT = 0xf +}; + +/** + * @brief 定义了登录方法。 + * + * @since 20 + * @version 1.0 + */ +enum TEEC_LoginMethod { + /** 未提供任何登录数据。 */ + TEEC_LOGIN_PUBLIC = 0x0, + /** 提供了关于运行 CA（客户端应用）进程的用户的登录数据。 */ + TEEC_LOGIN_USER, + /** 提供了关于运行 CA（客户端应用）进程的用户组的登录数据。 */ + TEEC_LOGIN_GROUP, + /** 提供了关于正在运行的 CA（客户端应用）的登录数据。 */ + TEEC_LOGIN_APPLICATION = 0x4, + /** 提供了关于运行 CA（客户端应用）进程的用户及 CA 的登录数据。 */ + TEEC_LOGIN_USER_APPLICATION = 0x5, + /** 提供了关于运行 CA（客户端应用）进程的用户组及 CA 的登录数据。 */ + TEEC_LOGIN_GROUP_APPLICATION = 0x6, + /** TEEOS 预留的登录方法。 */ + TEEC_LOGIN_IDENTIFY = 0x7, +}; + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file diff --git a/zh-cn/native_sdk/TEEKit/tee_client/tee_client_type.h b/zh-cn/native_sdk/TEEKit/tee_client/tee_client_type.h new file mode 100644 index 00000000..0d073584 --- /dev/null +++ b/zh-cn/native_sdk/TEEKit/tee_client/tee_client_type.h @@ -0,0 +1,292 @@ +/* + * 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. + * + * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。 + * + * @since 20 + */ + +/** + * @file tee_client_type.h + * + * @brief 定义基本数据类型和数据结构。 + * + * @library libteec.so + * @kit TEEKit + * @syscap SystemCapability.Tee.TeeClient + * @since 20 + * @version 1.0 + */ + +#ifndef TEE_CLIENT_TYPE_H +#define TEE_CLIENT_TYPE_H + +#include +#include +#include +#include +#include +#include "tee_client_constants.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 定义链表节点类型。 + * + * @since 20 + * @version 1.0 + */ +struct ListNode { + /** 指向链表中下一个节点的指针。 */ + struct ListNode *next; + /** 指向链表中上一个节点的指针。 */ + struct ListNode *prev; +}; + +/** + * @brief 定义返回值类型。 + * + * @since 20 + * @version 1.0 + */ +typedef enum TEEC_ReturnCode TEEC_Result; + +/** + * @brief 定义通用唯一标识符 (UUID)，符合 RFC4122 [2] 标准。UUID 用于标识可信应用 (TA)。 + * + * @since 20 + * @version 1.0 + */ +typedef struct { + /** UUID 的低 32 位时间字段。 */ + uint32_t timeLow; + /** UUID 的中 16 位时间字段。 */ + uint16_t timeMid; + /** UUID 的高 16 位时间字段和版本号。 */ + uint16_t timeHiAndVersion; + /** 时钟序列和节点值，长度为 8 字节。 */ + uint8_t clockSeqAndNode[8]; +} TEEC_UUID; + +/** + * @brief 定义上下文 (Context)，表示 CA（客户端应用）与 TEE（可信执行环境）之间的逻辑连接。 + * + * @since 20 + * @version 1.0 + */ +typedef struct { + /** 文件描述符。 */ + int32_t fd; + /** 指向可信应用 (TA) 路径的指针。 */ + uint8_t *ta_path; + /** 链接到当前上下文中的会话链表。 */ + struct ListNode session_list; + /** 链接到当前上下文中的共享内存链表。 */ + struct ListNode shrd_mem_list; + /** 共享缓冲区或实现特定数据的联合体。 */ + union { + struct { + /** 指向共享缓冲区的指针。 */ + void *buffer; + /** 共享缓冲区的信号量，用于同步访问。 */ + sem_t buffer_barrier; + } share_buffer; + /** 实现特定的 64 位数据。 */ + uint64_t imp; + }; +} TEEC_Context; + +/** + * @brief 定义 CA（客户端应用）与 TA（可信应用）之间的会话。 + * + * @since 20 + * @version 1.0 + */ +typedef struct { + /** 会话 ID，唯一标识 CA 和 TA 之间的会话。 */ + uint32_t session_id; + /** 目标 TA 的 UUID（通用唯一标识符）。 */ + TEEC_UUID service_id; + /** 操作计数器，跟踪该会话内的操作次数。 */ + uint32_t ops_cnt; + /** 记录会话链表头节点或实现特定数据的联合体。 */ + union { + /** 链表头节点，指向当前会话节点。 */ + struct ListNode head; + /** 实现特定的 64 位数据。 */ + uint64_t imp; + }; + /** 指向当前会话所属的上下文 (Context)。 */ + TEEC_Context *context; +} TEEC_Session; + +/** + * @brief 定义共享内存块，可通过注册或分配方式获取。 + * + * @since 20 + * @version 1.0 + */ +typedef struct { + /** 指向共享内存缓冲区的指针。 */ + void *buffer; + /** 共享内存的大小。 */ + uint32_t size; + /** 共享内存的标志位，标识内存的使用方式。 */ + uint32_t flags; + /** 操作计数器，跟踪在该共享内存上执行的操作次数。 */ + uint32_t ops_cnt; + /** 指示共享内存是否通过 TEEC_AllocateSharedMemory 分配。 */ //TODO + bool is_allocated; + /** 记录共享内存链表头节点或实现特定数据的联合体。 */ + union { + /** 链表头节点，指向当前共享内存节点。 */ + struct ListNode head; + /** 实现特定的指针数据。 */ + void* imp; + }; + /** 指向当前共享内存所属的上下文 。 */ + TEEC_Context *context; +} TEEC_SharedMemory; + +/** + * @brief 定义指向临时缓冲区的指针。 + * + * @since 20 + * @version 1.0 + */ +typedef struct { + /** 指向临时缓冲区的指针。 */ + void *buffer; + /** 临时缓冲区的大小（以字节为单位）。 */ + uint32_t size; +} TEEC_TempMemoryReference; + +/** + * @brief 定义指向已注册或已分配共享内存的指针。 + * + * @since 20 + * @version 1.0 + */ +typedef struct { + /** 指向已注册或已分配共享内存的指针。 */ + TEEC_SharedMemory *parent; + /** 共享内存大小。 */ + uint32_t size; + /** 共享内存偏移量。 */ + uint32_t offset; +} TEEC_RegisteredMemoryReference; + +/** + * @brief 描述一个以值传递的小型原始数据参数。 + * + * @since 20 + * @version 1.0 + */ +typedef struct { + /** 参数值 a。 */ + uint32_t a; + /** 参数值 b。 */ + uint32_t b; +} TEEC_Value; + +/** + * @brief 描述 ION 内存的大小和句柄。 + * + * @since 20 + * @version 1.0 + */ +typedef struct { + /** ION 内存的共享文件描述符。 */ + int ionShareFd; + /** ION 内存的大小。 */ + uint32_t ionSize; +} TEEC_IonReference; + +/** + * @brief 定义 {@code TEEC_Operation} 的参数。 + * + * @since 20 + * @version 1.0 + */ +typedef union { + /** 临时内存引用。 */ + TEEC_TempMemoryReference tmpref; + /** 已注册的内存引用。 */ + TEEC_RegisteredMemoryReference memref; + /** 以值传递的小型原始数据。 */ + TEEC_Value value; + /** ION 内存引用。 */ + TEEC_IonReference ionref; +} TEEC_Parameter; + +/** + * @brief 定义可信用户界面（TUI）的参数。 + * + * @since 20 + */ +typedef struct { + /** TUI 事件类型。 */ + uint32_t event_type; + /** 返回值，如果事件为 getKeycode，则表示按键码。 */ + uint32_t value; + /** 屏幕刘海区域的大小。 */ + uint32_t notch; + /** 折叠屏的宽度。 */ + uint32_t width; + /** 折叠屏的高度。 */ + uint32_t height; + /** 折叠屏的状态。 */ + uint32_t fold_state; + /** 折叠屏的某种显示状态。 */ + uint32_t display_state; + /** 移动设备的物理宽度。 */ + uint32_t phy_width; + /** 移动设备的物理高度。 */ + uint32_t phy_height; +} TEEC_TUI_Parameter; + +/** + * @brief 定义用于打开会话或发送命令的参数。 + * + * @since 20 + * @version 1.0 + */ +typedef struct { + /** 值为 0 表示取消命令，其他值表示执行命令。 */ + uint32_t started; + /** 使用 {@code TEEC_PARAM_TYPES} 创建的参数类型。 */ + uint32_t paramTypes; + /** 参数数组，包含最多 TEEC_PARAM_NUM 个参数。 */ + TEEC_Parameter params[TEEC_PARAM_NUM]; + /** 指向当前操作所属的会话。 */ + TEEC_Session *session; + /** 取消标志，指示是否取消该操作。 */ + bool cancel_flag; +} TEEC_Operation; + +#ifdef __cplusplus +} +#endif + +#endif +/** @} */ \ No newline at end of file -- Gitee