teec_protocol/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright (C) 2025-2026 KylinSoft Co., Ltd. <https://www.kylinos.cn/>
3// See LICENSES for license details.
4
5//! TEE Client-Application 通信协议定义
6//!
7//! 提供 CA（Client Application）与 TA（Trusted Application）之间通信的协议类型。
8//! 这些类型用于序列化/反序列化请求和响应数据，通过机密通信通道（TLS + VSOCK）传输。
9
10#![allow(dead_code)]
11#![allow(non_camel_case_types)]
12
13use bytemuck::{Pod, Zeroable};
14use serde::{Deserialize, Serialize};
15
16/// 数据包分块大小：32KiB
17pub const CHUNK_SIZE: u64 = 32 * 1024;
18
19/// 最大消息大小限制（10MB），防止 OOM 攻击
20pub const MAX_MESSAGE_SIZE: usize = 10 * 1024 * 1024;
21
22/// 数据包类型枚举，定义协议支持的不同操作类型
23#[derive(Debug, PartialEq, Eq, Default)]
24pub enum PacketType {
25    #[default]
26    Unknown = 0,
27    OpenSession = 1,
28    CloseSession = 2,
29    InvokeCommand = 3,
30    RequestCancellation = 4,
31}
32
33impl From<u64> for PacketType {
34    fn from(value: u64) -> Self {
35        match value {
36            0 => PacketType::Unknown,
37            1 => PacketType::OpenSession,
38            2 => PacketType::CloseSession,
39            3 => PacketType::InvokeCommand,
40            4 => PacketType::RequestCancellation,
41            _ => PacketType::Unknown,
42        }
43    }
44}
45
46impl From<PacketType> for u64 {
47    fn from(value: PacketType) -> Self {
48        match value {
49            PacketType::Unknown => 0,
50            PacketType::OpenSession => 1,
51            PacketType::CloseSession => 2,
52            PacketType::InvokeCommand => 3,
53            PacketType::RequestCancellation => 4,
54        }
55    }
56}
57
58/// 协议头结构，使用 #[repr(C)] 确保内存布局与 C 兼容
59/// 满足 bytemuck::Pod 要求：所有字段必须为基本类型
60#[repr(C)]
61#[derive(Debug, Copy, Clone, Pod, Zeroable)]
62pub struct PacketHeader {
63    /// 数据包类型标识，对应 PacketType 枚举的数值表示
64    pub data_type: u64,
65    /// 数据包负载大小
66    pub data_size: u64,
67}
68
69impl PacketHeader {
70    /// 协议头结构体的大小
71    pub const SIZE: usize = size_of::<PacketHeader>();
72
73    /// 将协议头序列化为字节切片
74    pub fn as_bytes(&self) -> &[u8] {
75        bytemuck::bytes_of(self)
76    }
77
78    /// 从字节切片反序列化协议头
79    pub fn from_bytes(buf: &[u8]) -> Self {
80        *bytemuck::from_bytes(buf)
81    }
82}
83
84/// TA 注册请求
85#[derive(Serialize, Deserialize, Debug)]
86pub enum TARequest {
87    Register { uuid: String },
88}
89
90/// TEE 请求枚举，定义 CA 发送给 TA 的所有请求类型
91///
92/// 这些请求会被序列化并通过机密通信通道（TLS + VSOCK）发送给 TA。
93#[derive(Serialize, Deserialize)]
94pub enum TEE_Request {
95    OpenSession {
96        uuid: String,
97        connection_method: u32,
98        params: TEE_Parameters,
99        #[serde(default)]
100        ca_auth_info: Option<CaAuthInfo>,
101    },
102    CloseSession {
103        session_id: u32,
104    },
105    InvokeCommand {
106        session_id: u32,
107        cmd_id: u32,
108        params: TEE_Parameters,
109    },
110    RequestCancellation {
111        session_id: u32,
112    },
113}
114
115/// CA 认证信息（用于 TA 的 ACL 访问控制）
116#[derive(Serialize, Deserialize, Debug, Clone)]
117pub struct CaAuthInfo {
118    /// CA 的唯一标识（UUID v5，基于调用者路径生成）
119    pub ca_uuid: String,
120    /// 验签是否通过（包含签名验证和证书链验证）
121    pub verified: bool,
122}
123
124/// TEE 响应枚举，定义 TA 返回给 CA 的所有响应类型
125///
126/// 这些响应会被序列化并通过机密通信通道（TLS + VSOCK）发送给 CA。
127#[derive(Serialize, Deserialize)]
128pub enum TEE_Response {
129    OpenSession { session_id: u32, result: u32 },
130    CloseSession { result: u32 },
131    InvokeCommand { params: TEE_Parameters, result: u32 },
132    RequestCancellation { result: u32 },
133}
134
135/// TEE 参数容器，包含最多 4 个参数
136///
137/// 这些参数会被序列化到请求/响应数据包中，通过网络传输。
138#[derive(Serialize, Deserialize, Default)]
139pub struct TEE_Parameters(
140    pub TEE_Parameter,
141    pub TEE_Parameter,
142    pub TEE_Parameter,
143    pub TEE_Parameter,
144);
145
146#[derive(Serialize, Deserialize, Default)]
147pub struct TEE_Parameter {
148    pub param: TEE_Param,
149    pub param_type: TEE_ParamType,
150}
151
152#[derive(Serialize, Deserialize, Default)]
153pub struct TEE_Param {
154    pub data: Vec<u8>,
155    pub values: TEE_Value,
156}
157
158#[derive(Serialize, Deserialize, Clone, Copy, Default)]
159pub struct TEE_Value {
160    pub a: u32,
161    pub b: u32,
162}
163
164#[derive(Serialize, Deserialize, Default, Debug, PartialEq, Eq, Clone, Copy)]
165pub enum TEE_ParamType {
166    #[default]
167    None = 0,
168    ValueInput = 1,
169    ValueOutput = 2,
170    ValueInout = 3,
171    MemrefInput = 5,
172    MemrefOutput = 6,
173    MemrefInout = 7,
174}
175
176impl From<u32> for TEE_ParamType {
177    fn from(value: u32) -> Self {
178        match value {
179            0 => TEE_ParamType::None,
180            1 => TEE_ParamType::ValueInput,
181            2 => TEE_ParamType::ValueOutput,
182            3 => TEE_ParamType::ValueInout,
183            5 => TEE_ParamType::MemrefInput,
184            6 => TEE_ParamType::MemrefOutput,
185            7 => TEE_ParamType::MemrefInout,
186            _ => TEE_ParamType::None,
187        }
188    }
189}
190
191impl From<TEE_ParamType> for u32 {
192    fn from(value: TEE_ParamType) -> Self {
193        match value {
194            TEE_ParamType::None => 0,
195            TEE_ParamType::ValueInput => 1,
196            TEE_ParamType::ValueOutput => 2,
197            TEE_ParamType::ValueInout => 3,
198            TEE_ParamType::MemrefInput => 5,
199            TEE_ParamType::MemrefOutput => 6,
200            TEE_ParamType::MemrefInout => 7,
201        }
202    }
203}
204
205/// 将路径转换为 UUID v5（用于生成 CA 唯一标识符）
206///
207/// 使用 NIL UUID 作为命名空间，路径字符串作为名称，
208/// 生成的 UUID 可用于 TEE_Request::OpenSession 的 ca_auth_info.ca_uuid 字段。
209pub fn path_to_uuid(path: &str) -> String {
210    use uuid::Uuid;
211    let namespace = Uuid::nil();
212    Uuid::new_v5(&namespace, path.as_bytes()).to_string()
213}
214
215pub use TEE_ParamType as ParamType;
216pub use TEE_Parameter as Parameter;
217pub use TEE_Parameters as Parameters;
218pub use TEE_Value as Value;
219
220#[cfg(test)]
221mod protocol_tests {
222    use super::*;
223
224    #[test]
225    fn test_tee_param_type_from_u32() {
226        // 测试 TEE_ParamType 的 From<u32> 实现 - 覆盖所有分支
227        assert_eq!(TEE_ParamType::from(0), TEE_ParamType::None);
228        assert_eq!(TEE_ParamType::from(1), TEE_ParamType::ValueInput);
229        assert_eq!(TEE_ParamType::from(2), TEE_ParamType::ValueOutput);
230        assert_eq!(TEE_ParamType::from(3), TEE_ParamType::ValueInout);
231        assert_eq!(TEE_ParamType::from(4), TEE_ParamType::None); // 未知值 -> None
232        assert_eq!(TEE_ParamType::from(5), TEE_ParamType::MemrefInput);
233        assert_eq!(TEE_ParamType::from(6), TEE_ParamType::MemrefOutput);
234        assert_eq!(TEE_ParamType::from(7), TEE_ParamType::MemrefInout);
235        assert_eq!(TEE_ParamType::from(8), TEE_ParamType::None); // 未知值 -> None
236        assert_eq!(TEE_ParamType::from(99), TEE_ParamType::None); // 未知值 -> None
237        assert_eq!(TEE_ParamType::from(255), TEE_ParamType::None); // 边界值
238    }
239
240    #[test]
241    fn test_tee_param_type_into_u32() {
242        // 测试 TEE_ParamType 的 Into<u32> 实现 - 覆盖所有变体
243        assert_eq!(u32::from(TEE_ParamType::None), 0);
244        assert_eq!(u32::from(TEE_ParamType::ValueInput), 1);
245        assert_eq!(u32::from(TEE_ParamType::ValueOutput), 2);
246        assert_eq!(u32::from(TEE_ParamType::ValueInout), 3);
247        assert_eq!(u32::from(TEE_ParamType::MemrefInput), 5);
248        assert_eq!(u32::from(TEE_ParamType::MemrefOutput), 6);
249        assert_eq!(u32::from(TEE_ParamType::MemrefInout), 7);
250    }
251
252    #[test]
253    fn test_tee_param_type_roundtrip() {
254        // 测试双向转换的往返一致性
255        let values = vec![0, 1, 2, 3, 5, 6, 7];
256        for value in values {
257            let param_type = TEE_ParamType::from(value);
258            let back_to_u32: u32 = param_type.into();
259            assert_eq!(value, back_to_u32);
260        }
261    }
262
263    #[test]
264    fn test_tee_value_default() {
265        // 测试 TEE_Value 的 Default trait
266        let default_val = TEE_Value::default();
267        assert_eq!(default_val.a, 0);
268        assert_eq!(default_val.b, 0);
269    }
270
271    #[test]
272    fn test_tee_parameter_default() {
273        // 测试 TEE_Parameter 的 Default trait
274        let default_param = TEE_Parameter::default();
275        assert_eq!(default_param.param_type, TEE_ParamType::None);
276        assert_eq!(default_param.param.value.a, 0);
277        assert_eq!(default_param.param.value.b, 0);
278        assert!(default_param.param.data.is_empty());
279    }
280
281    #[test]
282    fn test_packet_header_serialization_roundtrip() {
283        // 测试 PacketHeader 序列化/反序列化的往返一致性
284        let original = PacketHeader {
285            data_type: 0x1234_5678_9ABC_DEF0,
286            data_size: 0xFEDC_BA98_7654_3210,
287        };
288
289        let bytes = original.as_bytes();
290        let restored = PacketHeader::from_bytes(bytes);
291
292        assert_eq!(original.data_type, restored.data_type);
293        assert_eq!(original.data_size, restored.data_size);
294    }
295
296    #[test]
297    fn test_packet_type_conversion() {
298        // 测试协议类型转换 - 覆盖所有分支
299        assert_eq!(PacketType::from(0), PacketType::Unknown);
300        assert_eq!(PacketType::from(1), PacketType::OpenSession);
301        assert_eq!(PacketType::from(2), PacketType::CloseSession);
302        assert_eq!(PacketType::from(3), PacketType::InvokeCommand);
303        assert_eq!(PacketType::from(4), PacketType::RequestCancellation);
304        assert_eq!(PacketType::from(5), PacketType::Unknown); // 未知值 -> Unknown
305        assert_eq!(PacketType::from(0xFFFFFFFF), PacketType::Unknown); // 边界值
306
307        assert_eq!(u64::from(PacketType::Unknown), 0);
308        assert_eq!(u64::from(PacketType::OpenSession), 1);
309        assert_eq!(u64::from(PacketType::CloseSession), 2);
310        assert_eq!(u64::from(PacketType::InvokeCommand), 3);
311        assert_eq!(u64::from(PacketType::RequestCancellation), 4);
312    }
313
314    #[test]
315    fn test_packet_header_size() {
316        use core::mem;
317
318        // 测试协议头数据大小
319        let packet0 = PacketHeader {
320            data_type: u64::from(PacketType::OpenSession),
321            data_size: CHUNK_SIZE,
322        };
323
324        let packet1 = PacketHeader {
325            data_type: u64::from(PacketType::CloseSession),
326            data_size: 44,
327        };
328
329        assert_eq!(mem::size_of_val(&packet0), PacketHeader::SIZE);
330        assert_eq!(mem::size_of_val(&packet1), PacketHeader::SIZE);
331        assert_eq!(PacketHeader::SIZE, mem::size_of::<PacketHeader>());
332    }
333
334    #[test]
335    fn test_path_to_uuid_consistency() {
336        // 相同路径应该生成相同的 UUID
337        let uuid1 = path_to_uuid("/usr/bin/test");
338        let uuid2 = path_to_uuid("/usr/bin/test");
339        assert_eq!(uuid1, uuid2);
340    }
341
342    #[test]
343    fn test_path_to_uuid_uniqueness() {
344        // 不同路径应该生成不同的 UUID
345        let uuid1 = path_to_uuid("/usr/bin/test1");
346        let uuid2 = path_to_uuid("/usr/bin/test2");
347        assert_ne!(uuid1, uuid2);
348    }
349
350    #[test]
351    fn test_path_to_uuid_deterministic() {
352        // 测试 UUID v5 的确定性：相同路径总是生成相同的 UUID
353        // 这是 UUID v5 的核心特性，用于 CA 身份标识的稳定性
354
355        // 已知路径的已知 UUID（回归测试，确保算法稳定）
356        assert_eq!(
357            path_to_uuid("/usr/bin/test"),
358            "f2d62525-c975-5075-8bfd-ea1a7c98adc3"
359        );
360
361        // 不同路径生成不同 UUID
362        assert_ne!(path_to_uuid("/usr/bin/test"), path_to_uuid("/usr/bin/ls"));
363    }
364}
teec_protocol/lib.rs

teec_protocol/
lib.rs
